# Use with AI agents

> Connect Claude Code, Cursor, VS Code, Codex or Gemini CLI to the design system through its MCP server, llms.txt, the registry and an AGENTS.md snippet.

AI agents can read the whole design system in open formats, so any agent, Claude or not, builds UI with the same tokens, components and patterns as the docs.

## What agents can read

| Source | Use it for |
| --- | --- |
| Page URL + `.md`, such as [/components/button.md](https://design.sosialoka.tech/components/button.md) | One page as Markdown. Every page also has **Copy as Markdown** and **Download .md** buttons. |
| [/llms.txt](https://design.sosialoka.tech/llms.txt) and [/id/llms.txt](https://design.sosialoka.tech/id/llms.txt) | The index of every page with a one-sentence summary ([llmstxt.org](https://llmstxt.org)). |
| [/llms-full.txt](https://design.sosialoka.tech/llms-full.txt) and [/id/llms-full.txt](https://design.sosialoka.tech/id/llms-full.txt) | Every page in one file. |
| [/tokens.json](https://design.sosialoka.tech/tokens.json) and `/tokens/<theme>.json` | Every token in the DTCG format, and the resolved values of one theme. |
| [/r/react/registry.json](https://design.sosialoka.tech/r/react/registry.json) and [/r/vue/registry.json](https://design.sosialoka.tech/r/vue/registry.json) | The shadcn registries of the React and Vue components. |
| [/sosialoka-design-system-docs.zip](https://design.sosialoka.tech/sosialoka-design-system-docs.zip) | All of the above in one download. |
| `https://design.sosialoka.tech/mcp` | The MCP server: search, pages, components, patterns and tokens as tools. |

## Connect the MCP server

The server speaks MCP over Streamable HTTP at `https://design.sosialoka.tech/mcp`. It needs no login: everything it serves is public. Name it `sosialoka-design` so the AGENTS.md snippet below finds it.

### Claude Code

```bash
claude mcp add --transport http sosialoka-design https://design.sosialoka.tech/mcp
```

Add `--scope project` to write it to the repository's `.mcp.json`, so the whole team gets it.

### Cursor

In `.cursor/mcp.json` of the project, or `~/.cursor/mcp.json` for every project:

```json
{
  "mcpServers": {
    "sosialoka-design": { "url": "https://design.sosialoka.tech/mcp" }
  }
}
```

### VS Code

In `.vscode/mcp.json`:

```json
{
  "servers": {
    "sosialoka-design": { "type": "http", "url": "https://design.sosialoka.tech/mcp" }
  }
}
```

### Codex

In `~/.codex/config.toml`:

```toml
[mcp_servers.sosialoka-design]
url = "https://design.sosialoka.tech/mcp"
```

### Gemini CLI

In `~/.gemini/settings.json`, or `.gemini/settings.json` of the project:

```json
{
  "mcpServers": {
    "sosialoka-design": { "httpUrl": "https://design.sosialoka.tech/mcp" }
  }
}
```

## Tools

Every tool returns Markdown. Tools that take `locale` accept `en` (the default) or `id`.

| Tool | Arguments | Returns |
| --- | --- | --- |
| `search_docs` | `query`, `locale`, `limit` | The matching pages, with the path to pass to `get_page`. |
| `get_page` | `path`, `locale` | One page. The path can be `foundations/color`, `/id/content/` or a full page URL. |
| `list_components` | none | Every component with its frameworks, and every page pattern. |
| `get_component` | `name`, `platform`, `locale` | A component guide with its install commands and code. `platform` (`react`, `vue` or `flutter`) keeps one platform's code. |
| `get_tokens` | `theme` | The resolved values of one theme. Without `theme`, the theme list and the link to the full DTCG file. |
| `list_themes` | none | The themes and how to switch them. |
| `get_pattern` | `name`, `locale` | A page pattern, such as `login`, `dashboard`, `list` or `form`, with its code. |

## Install components through the shadcn MCP

The React registry also works with the official shadcn MCP server, so an agent can search the Sosialoka components and install them by name. Add the registry to `components.json`:

```json
{
  "registries": {
    "@sosialoka": "https://design.sosialoka.tech/r/react/{name}.json"
  }
}
```

Then set up the shadcn MCP server for your agent (`claude`, `cursor` or `vscode`):

```bash
npx shadcn@latest mcp init --client claude
```

`mcp init` cannot write the Codex config, so for Codex add this to `~/.codex/config.toml`:

```toml
[mcp_servers.shadcn]
command = "npx"
args = ["shadcn@latest", "mcp"]
```

Ask for an item by its registry name, such as "add @sosialoka/button". The shadcn MCP serves the React registry; in a Vue project, the agent takes the `shadcn-vue` install command from `get_component` or from the component page.

## Add the rules to your repo

Paste this into the `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` or `.cursor/rules` file of a product repository. It is also at [/AGENTS.md](https://design.sosialoka.tech/AGENTS.md).

````markdown
## Sosialoka Design System

This product uses the Sosialoka Design System (https://design.sosialoka.tech). Follow it for every UI change.

- **Read before you build.** Index: https://design.sosialoka.tech/llms.txt (Indonesian: https://design.sosialoka.tech/id/llms.txt). Every page is Markdown at its URL + `.md`.
- **Use the MCP server when it is connected** (`sosialoka-design`, https://design.sosialoka.tech/mcp): `search_docs`, `get_component` with `platform`, `get_pattern`, `get_tokens` with a theme.
- **Install components from the registry; don't rewrite them.**
  - React: `npx shadcn@latest add https://design.sosialoka.tech/r/react/<name>.json`
  - Vue: `npx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/<name>.json`
  - Install your product's theme first: https://design.sosialoka.tech/web.md
  - Flutter: the `sosialoka_ui` package (https://design.sosialoka.tech/flutter.md).
- **Use tokens, never raw values:** `bg-primary`, `text-muted-foreground`, `border-input`, `rounded-md`. No hex colors, no pixel radius.
- **Set the theme on the root element:** `data-brand` = your product (`lokamusik`, `coverclearance`, `lokasign`, `mylokalink`), or `neutral` when the screen belongs to no product; `data-theme` = `light` or `dark`.
- **Icons:** Lucide. **UI font:** Plus Jakarta Sans.
- **Labels sit above inputs.** One primary action per screen.
- **Copy** (https://design.sosialoka.tech/content.md): Indonesian uses "kamu", never "Anda". Short, active sentences. Error messages come from the backend; the client only disables the button.
````

## Download everything

[sosialoka-design-system-docs.zip](https://design.sosialoka.tech/sosialoka-design-system-docs.zip) holds every page as Markdown in English and Indonesian, the `llms.txt` and `llms-full.txt` files, `tokens.json`, one `tokens/<theme>.json` file per theme and `AGENTS.md`. It is rebuilt with every release of the site.
