Design Systems That AI Agents Understand

Your design system is documentation for humans. But now your AI agent is reading it too. Is it designed for both?

This question feels theoretical until you ask an agent to generate a component and it returns bg-blue-500 instead of bg-brand-500. Or uses padding: 24px instead of your p-card token. The agent isn't guessing wrong — it's working with what you gave it. And what you gave it is probably ambiguous.

The problem: documentation for humans, confusing for agents

Most design systems have inconsistencies that humans compensate for without thinking. You know "primary blue" is brand-500 because you've been on the project for months. You know a card's padding is always 24px because you've built it twenty times. That tribal knowledge lives in your head, not in the system.

An AI agent doesn't have that context. It reads your design system literally: token names, component APIs, CSS variables. If naming is inconsistent, if props are ambiguous, if you don't document when not to use something — the agent will produce code that's technically correct but semantically wrong.

The result: you spend more time fixing the output than you would have spent writing it yourself. The agent isn't helping because your system doesn't give it enough context to help.

What makes a design system AI-readable

You don't need to rewrite everything. Four principles that amplify what you already have.

1. Consistent naming conventions

A token's name should communicate its function, not its visual value. color-brand-500 tells the agent what role that color plays in your system. primary-blue tells it a color and an adjective — but primary of what? Buttons? Backgrounds? Links?

A predictable schema like {category}-{property}-{variant} lets the agent infer tokens it hasn't seen directly. If color-surface-default exists, it can anticipate color-surface-raised.

2. Explicit component APIs

Props with descriptive names and strict types. variant="primary" is clear. type="1" isn't. If your Button accepts a generic string as a variant, the agent doesn't know what values are valid.

TypeScript interfaces are executable documentation. An agent reading variant: "primary" | "secondary" | "ghost" knows exactly what it can use. An agent reading variant: string has to guess.

3. Documented constraints

Don't just document what a component does — document when not to use it. "Don't use Card for content that needs internal scrolling" is information that prevents errors before they happen.

Agents are good at generating code but bad at intuiting design decisions. If you don't document the limits, the agent will use your component in contexts where it doesn't make sense.

4. Token hierarchy mapped to CSS variables

Your tokens should map directly to CSS variables without a mental translation layer. If your token is called spacing-4 but the CSS variable is --sp-md, you're creating unnecessary friction — for humans and agents alike.

Flat tokens vs. semantic tokens

This is where the difference hits. Compare how an agent interprets the same card with two different token systems.

With flat tokens, the agent applies correct values but without context. bg-gray-100 works in light mode. But in dark mode? The agent has no information to adapt.

With semantic tokens, the agent understands intent. bg-surface adapts automatically to the theme. p-card ensures consistent spacing with other cards in the system. The token communicates the why, not just the what.

This difference isn't aesthetic — it's functional. A system with semantic tokens produces output that needs less manual correction. The agent makes better decisions because it has more context.

Your CLAUDE.md is part of your design system

If you use Claude Code, your CLAUDE.md is the first file the agent reads before writing code. The conventions you document there directly affect output quality.

This means your CLAUDE.md is, in practice, an extension of your design system. When you write "colors are referenced as bg-brand-500, not bg-blue-500", you're creating a design rule the agent respects consistently.

What works to document in your CLAUDE.md:

• Token naming schema (brand-500 not primary-blue)
• Base components and their available variants
• Preferred layout patterns (when flex, when grid)
• Spacing conventions (4px scale, semantic tokens)
• Explicit anti-patterns (what not to do)

Checklist: audit your design system for agents

Six questions that reveal whether your system is ready:

1. Do token names communicate function? surface-raised > gray-100. If you need human context to understand a token, an agent won't understand it either.
2. Are component props explicit? Union types with concrete values > generic strings. TypeScript is your best documentation.
3. Do you document when NOT to use each component? Negative constraints prevent more errors than positive examples.
4. Do tokens map directly to CSS variables? No translation layer. Token -> variable -> value. Direct.
5. Does your CLAUDE.md reflect your design system? The conventions the agent needs should be accessible in the first file it reads.
6. Is naming predictable? If an agent can infer tokens it hasn't seen based on the pattern of those it knows, your system scales.

A design system for agents is better for everyone

You're not making two versions of your design system — one for humans and one for AI. You're making one better version that works for both.

Consistent naming, explicit APIs, documented constraints, semantic tokens — all of this improves the experience for anyone using your system. Juniors understand faster. Seniors waste less time looking up conventions. And agents generate code that actually integrates.

The irony is that designing for agents forces you to solve the same problems you've been postponing for years: inconsistent naming, incomplete documentation, design decisions that only live in the head of whoever made them.

A design system that an agent can read correctly is a design system that anyone can use correctly. And that was always the goal.

---

This is the seventh article in the series. The first was about the tools I use. The second about why they fail and how to fix them. The third about building a skill system. The fourth about the Figma-to-code workflow. The fifth about MCP servers. This one bridges design systems and AI agents — where your system's structure determines output quality.