Kwark. Design System
Open Kwark

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.

For agents

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

Give this Markdown to your coding agent or share its URL.

Open .mdllms.txt
Loading…