AGENTS.md and the AI Pack

A set of files that tells an AI agent how your UI should look, so it uses your tokens instead of guessing.

Why it helps

Coding agents guess when they don’t know your design system. They pick a blue that is close but not yours, or a gray that fails contrast. The AI Pack writes your rules down in files agents already look for, so they reuse your tokens and components instead.

The files are made from your system by the same engine as everything else. Nothing is sent to an AI service to make them. The AI Pack is one of the four free code formats.

What’s in it

File	What it holds
`AGENTS.md`	The rules: golden rules, a token map (token, CSS variable, Tailwind class), a type map, safe contrast pairs and a short “don’t” list.
`CLAUDE.md`	Two lines that point Claude Code to AGENTS.md.
`DESIGN.md`	The full spec: front matter with fonts and key colors, then color, type, spacing and component guidance.
`design-system/components.json`	A catalog of your components with the exact variant values.
`llms.txt`	A short index that tells an agent which file to read first.
`registry.json`, `registry/…-theme.json`	Your theme as a shadcn registry item.
`tokens.css`, `styles/typography.css`	CSS variables for light and dark, and plain HTML elements styled with your type.
`tokens/*.tokens.json`	W3C design tokens: primitives, the light theme and the dark theme.

Get the files

Open your code export
In Studio, go to Use it → Code. In the Figma plugin, go to Export → Code.
Pick AI Pack
Choose “AI Pack (AGENTS.md, DESIGN.md, shadcn)” and save the files.
Put it in your repo
Put them at the root of your project, next to package.json, keeping the folders. Commit it, so everyone’s agent reads the same rules.

Using the MCP server? The agent can fetch the same AGENTS.md and DESIGN.md live with get_design_system, so they never go stale.

A look at AGENTS.md

Trimmed from a real one, made for a teal system. Yours has your own names and numbers.

AGENTS.md

## Golden rules

1. Never hard-code colors, font sizes, spacing, radii, shadows or durations.
   Use the CSS variables / Tailwind utilities below.
2. Semantic over primitive: `bg-surface`, `text-fg-primary`, `border-line-default`,
   not `blue-500` or `#2563eb`.
3. Reuse before you build: check design-system/components.json first.
4. States are required: hover, active/pressed, focus-visible, disabled;
   inputs also error.
5. Accessibility: WCAG 2.2 AA. Use the safe pairs below; every icon-only
   button gets an aria-label; hit targets ≥ 40 px (44 on touch).
6. Dark mode: tokens switch with `data-theme` on <html>. Never write
   separate dark colors.

## Safe contrast pairs (Light theme)

| Foreground     | Background | Ratio   |
|----------------|------------|---------|
| text/primary   | bg/surface | 17.6:1 |
| text/secondary | bg/surface | 7.5:1  |
| text/on-brand  | bg/brand   | 7.9:1  |

Which agent reads what

Claude Code reads CLAUDE.md, which points it to AGENTS.md.
Cursor, Codex and many other agents look for AGENTS.md at the root of the repo.
Any agent can be told to “read DESIGN.md first”. It is plain Markdown.

Lovable, Bolt and v0

These tools work from a chat, not a repo. In Studio, open Use it → AI tools and press Copy prompt. Paste it into the tool’s chat as your first message. It carries your tokens and rules in a form the tool can follow.