Design Systems for AI Agents: What to Document So They Stay On Brand

Ask an AI coding agent for a settings page and you'll get a settings page. It even uses your fonts. Then you notice the primary button is a hex value nobody has used since the rebrand, the empty state says "Oops! Nothing here yet!", and there's a new Card component sitting next to the three you already have.

The agent wasn't careless. It did exactly what your documentation told it to, and filled every gap with a guess. That's the real problem with AI and design systems: most systems were written for people who already know the unwritten rules. Agents don't. They read literally.

This guide covers what a design system needs to document so AI agents stay on brand, where each piece should live now that tools like Figma Specs and DESIGN.md exist, and how to keep those docs small, accurate and enforceable once agents depend on them.

AI agents go off-brand for three reasons: the design system never wrote down its judgment, the instructions drifted out of date, or there was so much context that the important rules got buried. Having a design system protects you from none of them.

The judgment lives in people's heads. A token file tells an agent what your primary color is. It doesn't say that color is reserved for one action per screen, or that the team retired a card variant two releases ago. Designers pick that up in reviews and Slack threads. Agents only know what's written down, so they choose a valid option for the wrong situation. The result looks almost right, which is the expensive kind of wrong, because someone has to catch it.

The instructions stop being true. A developer who follows a doc to a component that no longer exists asks someone. An agent fills the gap, usually by building a new one. Outdated docs don't just fail to help. They actively steer agents somewhere wrong, with full confidence.

The context gets too big. Teams often react to off-brand output by adding more rules. Past a point, a rules file stops working as a reference. The ten lines that matter sit next to hundreds that restate what the code already says, and the agent weighs them all the same.

The volume of AI-made UI is why this matters now. Figma's chief design officer Loredana Crisan told TechCrunch that 17 times more lines of code are being produced than before, but only 1.3 times more releases. Much of that output is exploration, and all of it gets reviewed by someone. Meanwhile, zeroheight reports that 56% of design system teams now use AI, but only 15% say it's living up to the hype. Most of that gap is a documentation problem, and it starts with deciding what to write down.

If your team is still sorting out what counts as a design system in the first place, start with our design system guide.

A design system built for AI agents documents six layers: tokens with intent, component rules, decision rules, hard constraints, voice and content rules, and golden examples. The first two describe what exists. The last four describe what to choose, which is where agents fail. For each layer, the test is simple: could an agent apply this rule correctly without asking anyone?

Tokens with intent

Tokens are the values: color, type, spacing, radius, elevation, motion. Agents need two things most token files skip. The first is semantic names, so color.action.primary instead of blue-500. The second is a line of intent next to each token, saying what it's for and what it's never for.

• Vague: Primary blue: #2F5BEA.
• Agent-readable: color.action.primary is the fill for the single main action on a screen. Never use it for links, icons or decoration. Links use color.text.link.

Component rules

For every component, document what it does, its props and variants, every state (loading, empty, error, disabled), and when not to use it. That last part matters most. Storybook's own AI docs use exactly this pattern in a component description: Button is for actions that stay on the page, and anything that navigates should use Link instead.

• Vague: Button: primary, secondary, ghost.
• Agent-readable: Button triggers an action on the current page. For navigation, use Link. One primary Button per view. Ghost buttons only inside toolbars.

Decision rules

Decision rules cover the choices between valid options: modal or page, toast or inline error, table or cards, when density changes. Humans learn these by watching senior designers. Agents need them as plain "if this, then that" sentences.

• Vague: Use modals sparingly.
• Agent-readable: Use a Modal only to confirm a destructive action or to finish a task of three fields or fewer. Anything longer gets its own page. Show form validation inline, never in a toast.

Hard constraints

Constraints are the non-negotiables: what's banned, what's deprecated and what replaces it, and the accessibility floor. Write them as short, absolute rules, then back each one with lint or a test where you can. A rule an agent can break without anything failing is a suggestion.

• Vague: Follow accessibility best practices.
• Agent-readable: Never hardcode color, spacing or radius values; import tokens. CardLegacy is deprecated; use Card. Body text contrast must meet WCAG AA (4.5:1).

Voice and content rules

This is the layer almost every "design system for AI" guide leaves out, and it's where AI output most obviously reads as generic. An on-brand screen with off-brand copy is still off-brand. Document tone by situation, plus a short word list.

• Vague: Our tone is friendly and professional.
• Agent-readable: Errors say what happened, then what to do next. No "Oops", no blame, no exclamation marks. Button labels start with a verb and stay under three words ("Save changes", not "OK"). Say "workspace", never "account".

Golden examples

Agents lean heavily on the code and screens around them, so the examples they see shape output more than any rule. Mark two or three screens and components as the reference for how things should be built, and keep known anti-patterns out of what agents read. Storybook, for instance, lets teams exclude stories that demonstrate anti-patterns, and docs for deprecated components, from the manifest agents use.

• Vague: See the component library for examples.
• Agent-readable: For any new settings screen, copy the structure of AccountSettings. Never use LegacyDashboard as a pattern; it predates the current system.

Each layer belongs where an agent will actually read it at the moment it needs it: values in machine-readable files, judgment in plain Markdown, examples in real code, and constraints in lint. The tooling for this changed fast in 2026, so here's where things stand as of October.

Sources: TechCrunch on Figma Specs, the DESIGN.md repository, Storybook's AI docs and zeroheight AI.

Whichever tools you pick, give every fact one home. If your token values live in DESIGN.md, your AGENTS.md should point to that file, not repeat the values. Two copies of the same rule will drift apart, and agents can't tell which one is current. Some agents read only one of the files, so the stale copy is the one they'll trust.

You don't need all five tools. A small team can start with a token file and one well-written Markdown rules file. An MCP server earns its place once your component library is large enough that agents can't hold it in context, or once several tools need the same source.

Shorter design docs produce better agent output, because every line an agent reads competes for its attention. The fix for off-brand output is rarely more rules. It's the right rules, loaded at the right moment.

A structure that holds up as a system grows:

1. 1.A short root file. What the system is, where each layer lives, and the five to ten rules that apply everywhere. This is what AGENTS.md or CLAUDE.md should contain.
2. 2.Area files loaded on demand. Forms, data tables, navigation, marketing pages. Each gets its own file of decision rules, read only when the agent works in that area.
3. 3.A glossary. One line per term your product uses, so the agent says "workspace" when you mean workspace.
4. 4.Decision records. A short note for each choice that's hard to reverse, with the reason. These stop agents from "fixing" a deliberate decision.

In a repo, that can look like this:

Then cut. Delete any line that restates what the code or token file already says, because the agent can read the source. Delete any line that would be true of any product ("keep layouts clean"), because it tells the agent nothing. What's left should be specific to your brand, and short enough that a new designer would actually read it too.

A wrong rule costs more than a missing one. When a rule is missing, an agent guesses and sometimes guesses well. When a rule is wrong, the agent follows it every time, with full confidence. Design system docs drift the moment someone renames a component, moves a folder or retires a token, so accuracy needs a process, not good intentions.

What that process looks like in practice:

• Docs change with the system. A pull request that renames, moves or deprecates anything updates the docs in the same PR. Make it part of review.
• References must resolve. Every file path, component name and token named in your rules should exist. This is easy to check automatically in CI, and DESIGN.md's CLI already flags broken token references.
• Diff before you merge. Treat a change to your rules file like a change to code. Read the diff and ask what it will change in agent output.
• Deprecations name their replacement. "Don't use X" leaves a gap the agent fills with a guess. "Use Y instead of X" doesn't.
• One owner. Someone on the design system team owns the agent-facing docs and reviews them on a schedule, quarterly at minimum.

One side effect is worth knowing: everything you do to keep docs accurate for agents also helps the humans who were quietly working from outdated docs all along.

You can tell agent-ready documentation is working when reviewers stop fixing the same things. "On brand" feels subjective, but most of what goes wrong is countable. These are the signals we'd track, before and after you rework your docs:

Lint will never catch everything. An agent can pass every check and still pick the wrong pattern for the job. That's why the review comments matter most: each repeated comment is a rule that should have been written down.

Use this to audit an existing design system before you hand it to AI agents. Every "no" is a gap an agent will fill with a guess.

Tokens

• Tokens have semantic names, not raw color or size names
• Each token has one line on what it's for and what it's never for
• Tokens live in a machine-readable file (W3C DTCG JSON or DESIGN.md)

Components

• Every component lists its props, variants and states
• Every component says when not to use it, and what to use instead
• Two or three reference screens are marked as golden examples

Decisions and constraints

• Common choices (modal or page, toast or inline, table or cards) have if/then rules
• Deprecated components and patterns name their replacements
• Accessibility minimums are written as numbers
• Hard constraints are backed by lint or tests

Voice

• Tone rules exist per situation: errors, empty states, confirmations, buttons
• A word list covers terms you always use and terms you never use

Structure and upkeep

• The root rules file is short and points to everything else
• Every fact has one home; other files link to it
• Every path, component and token named in the docs exists
• Docs update in the same PR as system changes
• One person owns the agent-facing docs

A design system used to be a library people browsed and interpreted. For an AI agent, it's a set of instructions followed to the letter. The teams that get on-brand output from agents aren't the ones with the biggest systems. They're the ones that wrote down their judgment, kept it short and kept it true.

If your design system was built for people and now has agents reading it, our product design team can help make it agent-ready.