A design system AI can read: tokens, rules and examples

What does an agent need to know to design well?

An agent building an interface needs three kinds of information. First, the values: colors, typography, spacing, radii and shadows. Second, the components: what exists, which props they accept and which variants they have. Third, the rules: when to use a component and when not to, what hierarchy a screen follows, what should not be done.

The first two usually live in the code. The third is almost never written anywhere. A design system that only has tokens and components leaves the agent to guess the hardest part, which is intent.

Which format should you use?

There are several options, and they are not mutually exclusive:

• Tokens in JSON using the Design Tokens Community Group (DTCG) format, as explained in design tokens an agent can understand. Version 2025.10 was published as a final community group report and is considered stable, although it is not a W3C standard. They are normative values, with no intent.
• Component documentation that the agent queries through the Storybook MCP server, as we saw in Storybook with AI. According to its documentation, the docs-list and docs-show tools return the component index and, per component, its props and first stories. It is in preview, so its API may change, and the documentation part requires enabling componentsManifest in the Storybook configuration.
• DESIGN.md, a format published by Google Labs. It combines tokens in YAML (at the top of the file, between --- lines) with Markdown text under ## headings that explains the reasoning. The tokens are the normative values and the text gives the context for applying them. Its version is alpha. It ships with a CLI (@google/design.md) that validates structure, checks broken references and WCAG contrast, and exports the tokens to formats such as DTCG or Tailwind.
• llms.txt, a Markdown file proposed by Jeremy Howard in September 2024 that works as an index so a model can find your documentation. It is useful if you want third parties to query your system too. See llms.txt for more detail.

The Figma MCP server adds two useful things. The get_variable_defs tool returns the variables and styles in the selection (colors, spacing, typography), and the create_design_system_rules prompt generates a rules file so the code fits your project; you save the result in a folder such as rules/ or instructions/. It is one way to start without writing everything by hand. You can also link Figma components to their code with Code Connect.

Which rules should you write?

The most useful rules are the ones that prevent repeated decisions:

• When to use each component, in one sentence. “Use Modal only for confirmations. For navigation, use a page.”
• Which states exist and how they look: error, empty, loading, disabled.
• What to forbid, with concrete examples. “Do not put a primary button inside another primary button.”
• How to name tokens and components, so the agent finds what it needs.

The “Do’s and Don’ts” section in DESIGN.md is a good template for the last part: short examples of what to do and what not to do. If the system is small, that section alone already changes the result.

How do you keep it up to date without going crazy?

A rules file nobody updates is worse than none. A few simple practices:

• Keep the source of truth in the repo, next to the code, and point to it from CLAUDE.md or AGENTS.md.
• Generate what you can: tokens come from a single file, documentation comes from stories.
• Validate automatically. If you use DESIGN.md, its lint command catches broken references between tokens before the agent uses them.
• Review the file when a component changes. A code change without a rules change creates contradictions.

When should you NOT do this?

• When the system is redefined every month. Writing rules for something unstable means rewriting them.
• When the goal is a prototype. A readable design system has a maintenance cost that does not pay off in a two-day test.
• When you want the agent to invent the system from scratch. An agent without a system will generate one, but it will not be yours.
• When the file becomes very long. A faithful summary is worth more than a dump the agent will not process well. Be careful with overly long context files, because they take up space in every session.

Example

Illustrative example: a small team has tokens in JSON, seven components in Storybook and no written rules. An agent designs a settings screen and uses three different button styles. The team creates a DESIGN.md with a components section, three usage rules for buttons and a “don’t” section: no multiple primary buttons in the same view. In the next task, the agent uses one primary button and the correct secondary one.

What changed was not the code. It was that the agent no longer had to decide which style to use.

Common mistakes

• Documenting only the tokens and believing that is enough to convey intent.
• Writing generic rules, such as “use good design,” that the agent cannot apply.
• Copying the entire system into a file nobody can read in a single session.
• Leaving contradictions between the rules file and the actual code.
• Depending on an alpha format without keeping the JSON tokens as a backup.

Sources

• DESIGN.md: format specification (google-labs-code/design.md)
• Figma Developers: tools and prompts
• Storybook: MCP overview for agents
• Design Tokens Format Module 2025.10 (DTCG)
• llms.txt (Jeremy Howard)