# AI context files

> 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.

Source: https://kwark.space/designSystem/agents/ai-context

## The files

All of them are generated by the same build as the pages, so none of them can fall behind the site.

| File | What it is | Load it when |
|---|---|---|
| [`AGENTS.md`](https://kwark.space/designSystem/AGENTS.md) | The rules, in one short file: colour, type, space, phones, writing, motion, accessibility, and the checks before you finish. | Always. It is the first thing any agent writing Kwark UI reads. |
| [`llms.txt`](https://kwark.space/designSystem/llms.txt) | The map: every page with its one-line summary and the URL of its markdown twin. | The agent needs to find the right page. |
| Markdown twins | Every page as clean markdown, at the page's URL plus `.md`. Live demos become HTML code blocks; do and don't pairs become two labelled lines; swatches become a table with light and dark values. | The task touches that page. Load the few pages the task needs. |
| [`components.json`](https://kwark.space/designSystem/components.json) | Every component: name, slug, summary, status, React import and props when it is in the app, the HTML, the tokens it uses and its rules. | The agent is building UI and must use real parts. |
| [`tokens.json`](https://kwark.space/designSystem/tokens.json) | Every token as DTCG 2025.10 values, with exact CSS in the org.kwark.css extension: `light`, `dark`, and `rooms` for the five writing rooms. | The agent needs values: generating a native theme, checking a contrast, mapping another system's tokens. |
| [`llms-full.txt`](https://kwark.space/designSystem/llms-full.txt) | `AGENTS.md` plus every page's markdown in one file. | A large-context review of the whole system, or offline use. Not for everyday work. |
| `search.json` | Title, summary, group and keywords of every page. The site's search and the MCP server use it. | You are building a tool, not prompting. |
| [`kwark.css`](https://kwark.space/designSystem/kwark.css) | The tokens and the component styles. | The agent is writing HTML that must render. |

## Which file for which task

Load the least that answers the question. A long context the agent does not need makes its answer worse, not better: the rules that matter get diluted by pages that do not.

| Task | Load |
|---|---|
| Build or change a screen | `AGENTS.md` + the `.md` of each component you use + the pattern page if one applies (saving, errors, empty states, phones) |
| Write or review UX copy | `AGENTS.md` + `foundations/ux-writing.md` + the pattern page for that moment |
| Review a diff | `AGENTS.md` + the pages for every part the diff touches; with the MCP server, `audit_code` on each file |
| Phone layout | `AGENTS.md` + `patterns/phones.md` + `components/page-header.md` + `components/sheet.md` |
| Anything inside the screenplay editor | add `foundations/rooms.md` |
| Anything a machine proposes or writes | add `foundations/ai-and-authorship.md` and `components/revision-mark.md` |
| Generate a native or Tailwind theme | `tokens.json` only |
| "Which component should I use for…" | `llms.txt`, then the page it points to; or `search_docs` with the MCP server |
| Audit the whole system, or write a guide | `llms-full.txt`, in a model with a large context window |

> **For agents:** Load AGENTS.md first. Then load only the markdown twins the task touches. Do not load llms-full.txt for a single screen. If a page you need is not listed in llms.txt, say so instead of guessing what it would say.

## Token budget

A rough rule: one token is about four characters of English. Check a file's size before loading it whole:

```bash
curl -s https://kwark.space/designSystem/llms-full.txt | wc -c
```

- `AGENTS.md` is short: about a thousand tokens. It fits in every conversation.
- `llms.txt` is a few thousand tokens: one line per page.
- A component or pattern twin is usually between one and five thousand tokens.
- `llms-full.txt` grows with the site and is far larger than any single task needs. Use it only where the whole system is the subject.
- `tokens.json` and `components.json` are dense; ask for one component (`get_component`) or a filtered set of tokens (`get_tokens`) through the MCP server rather than loading the whole file.

## How to load them

- **Paste.** Open the page, switch to **Agent**, press **Copy markdown**, paste it into the chat.
- **By URL.** Agents that can fetch (Claude Code, Codex, Cursor) can be given the `.md` URL directly: "Read https://kwark.space/designSystem/patterns/errors.md first."
- **In the repository.** Copy `AGENTS.md` into the root of your repository (Codex and others read it automatically), or reference it from `CLAUDE.md`, `.cursor/rules/` or `GEMINI.md`.
- **Through MCP.** The [MCP server](https://kwark.space/designSystem/agents/mcp.md) serves every file on demand: `get_page` for a twin, `get_component`, `get_tokens`, `search_docs`.

## What the twins contain

A twin is the page, not a summary. It starts with the title, the summary and the source URL, then the content in order. Things built for the eye are converted:

- A live demo becomes an `html` code block that renders with `kwark.css`.
- A do and don't pair becomes `**Do:**` and `**Don't:**` lines.
- A swatch list becomes a table of token, name, light value, dark value and use.
- A readiness test becomes the task, the context to give, the constraint and the list of things a reliable answer contains.
- Links between pages point to the other pages' twins, so an agent following a link stays in markdown.

## AI readiness test

**Task:** An agent is asked to build the phone version of the Characters list. Say exactly which files it should load and in what order, and which it should not.

**Give the agent:** This page, llms.txt.

**Constraint:** Keep the context under ten thousand tokens.

**A reliable answer:**
- AGENTS.md first
- patterns/phones.md, components/page-header.md, components/list-row.md and components/sheet.md
- Not llms-full.txt
- Uses llms.txt or search_docs to find any page it is unsure of
- Says it will check the layout at 375 and 320
