# For agents

> Kwark is written for two readers, people and the agents that build with them. Start here to connect Claude Code, Cursor, Codex or Gemini to the system in three steps.

Source: https://kwark.space/designSystem/agents

## Why two readers

Most of the interface code written today passes through an agent. An agent that has never seen your system fills the gaps with the most common answer it knows: a blue button, a grey card, a modal that says "Are you sure?". That is how products drift into looking like every other product.

So every page here is written once and published twice:

- **For people**: the page you are reading, with live components, Light and Dark, do and don't pairs.
- **For agents**: the same source as plain markdown, plus files an agent can load whole: `AGENTS.md` for the rules, `tokens.json` for values, `components.json` for parts, `llms.txt` as the map.

The rules are written so an agent can follow them without interpretation. They start with **Must**, **Never** or **Always**, they name tokens and components exactly, and each page ends with a readiness test you can use to check that an agent has understood it.

## The Person and Agent switch

At the top of every page, **Person** and **Agent** switch the view. Agent shows the page exactly as an agent reads it: the markdown twin, with **Copy markdown** to paste into a chat and **Open .md** for the file. Nothing is hidden from either reader: the agent view is not a summary, it is the same page.

You can also add `.md` to any URL:

```text
https://kwark.space/designSystem/components/breadcrumb      for people
https://kwark.space/designSystem/components/breadcrumb.md   for agents
```

## Quick start

Three steps, whichever tool you use.

### Claude Code

1. Add the rules to the project. In `CLAUDE.md`, add one line: `Follow https://kwark.space/designSystem/AGENTS.md for all UI. Load component pages from https://kwark.space/designSystem/components/<slug>.md before using a part.`
2. Install the MCP server so Claude can search the docs, read tokens and audit its own code: `claude mcp add kwark-design -- node /absolute/path/to/kwark-design-mcp.mjs`. See [MCP server](https://kwark.space/designSystem/agents/mcp.md).
3. Install the skills into `~/.claude/skills/` or the project's `.claude/skills/`. See [Skills](https://kwark.space/designSystem/agents/skills.md). Then ask: "Use kwark-ui to build the Scene notes panel."

### Cursor

1. Add a project rule: create `.cursor/rules/kwark.mdc` with the contents of [AGENTS.md](https://kwark.space/designSystem/AGENTS.md), or a single line pointing to it.
2. Add the MCP server in `.cursor/mcp.json` (the snippet is on [MCP server](https://kwark.space/designSystem/agents/mcp.md)).
3. Add `https://kwark.space/designSystem/llms.txt` as a documentation source and reference it with `@Docs`, or paste the `.md` URLs of the pages you need into the chat, then ask for the screen.

### Codex

1. Put the rules in the repository's `AGENTS.md`. Codex reads it automatically. Copy the file from `https://kwark.space/designSystem/AGENTS.md`, or add a section that links to it.
2. Add the MCP server in `~/.codex/config.toml` (snippet on [MCP server](https://kwark.space/designSystem/agents/mcp.md)).
3. Ask for one screen at a time and name the pages to read: "Read patterns/saving-and-sync.md and components/toast.md, then add the import toast."

### Gemini

1. Put the rules in `GEMINI.md` at the root of the project, or paste `AGENTS.md` at the start of the conversation.
2. With Gemini CLI, add the MCP server under `mcpServers` in `~/.gemini/settings.json` (snippet on [MCP server](https://kwark.space/designSystem/agents/mcp.md)).
3. Give it `llms.txt` to find pages, and load only the pages the task needs.

> **For agents:** If you are an agent reading this: read AGENTS.md before writing any UI, load the component and pattern pages for the parts you use, use only --k-* tokens and the components listed in components.json, and say plainly when the system does not cover something. Never invent a token, a component or a rule.

## What is here

- [AI context files](https://kwark.space/designSystem/agents/ai-context.md): The files an agent can load - llms.txt, llms-full.txt, the markdown twins, AGENTS.md, tokens.json and components.json - what each is for, how to load it, and which one to use for which task.
- [Prompt library](https://kwark.space/designSystem/agents/prompts.md): Copy-ready prompts for building with the Kwark system - a screen, a review, UX copy, a phone layout, a new component, a decision record and a readiness test - each with the context files it needs.
- [Design-to-code handoff](https://kwark.space/designSystem/agents/handoff.md): How Kwark hands a design to whoever builds it, a person or an agent - a spec that names components and tokens, covers phone and desktop, every state, every word, accessibility and edge cases, with a template to download.
- [MCP server](https://kwark.space/designSystem/agents/mcp.md): Install the Kwark design MCP server in Claude Code, Cursor, Codex or Gemini so an agent can search the docs, read any page, look up components and tokens, and audit its own code against the system.
- [Skills](https://kwark.space/designSystem/agents/skills.md): Fourteen downloadable agent skills that teach Claude (and any agent that reads SKILL.md files) to build, review, write copy, hand off, record decisions and start a creative app the Kwark way.
- [Readiness tests](https://kwark.space/designSystem/agents/readiness.md): How to test whether an agent really follows the Kwark system - the readiness test at the end of each page, how to run and grade it in a fresh conversation, what a reliable answer looks like, and every page that has one.
- [AI-ready roadmap](https://kwark.space/designSystem/agents/roadmap.md): Kwark's own model for a creative-app team adopting the system - six stages, seventeen steps, a "ready enough" line and an AI readiness check for each, statuses instead of scores, and the order the steps depend on.

## AI readiness test

**Task:** Set up a new repository so that Claude Code follows the Kwark system for all UI work.

**Give the agent:** This page, MCP server, Skills.

**Constraint:** Only files and commands named on these pages.

**A reliable answer:**
- Adds a CLAUDE.md line pointing to AGENTS.md
- Installs the MCP server with an absolute path
- Installs at least kwark-ui and kwark-ux-review
- Explains how to load a single page's .md twin
- Does not paste llms-full.txt into every conversation
