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 |
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 |
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 |
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 |
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 |
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 |
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 |
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:
curl -s https://kwark.space/designSystem/llms-full.txt | wc -c
AGENTS.mdis short: about a thousand tokens. It fits in every conversation.llms.txtis a few thousand tokens: one line per page.- A component or pattern twin is usually between one and five thousand tokens.
llms-full.txtgrows with the site and is far larger than any single task needs. Use it only where the whole system is the subject.tokens.jsonandcomponents.jsonare 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
.mdURL directly: “Read https://kwark.space/designSystem/patterns/errors.md first.” - In the repository. Copy
AGENTS.mdinto the root of your repository (Codex and others read it automatically), or reference it fromCLAUDE.md,.cursor/rules/orGEMINI.md. - Through MCP. The MCP server serves every file on demand:
get_pagefor 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
htmlcode block that renders withkwark.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