All posts
Product design

AI-Ready Design Systems: Making Components Coding Agents Use Correctly

How to build an AI ready design system: the naming, tokens, in-repo docs and usage rules coding agents need to pick the right component every time.

By Mehdi Hassan9 min read

The short answer

An AI ready design system is one a coding agent can read and use correctly without a designer in the loop. It needs unambiguous component names, semantic tokens instead of raw values, usage docs that live in the repo next to the code, a short rules file, and automated checks that catch drift before review.

Key takeaways

  • Agents read your repo, not your Figma file or Notion page, so the docs have to live beside the code.
  • One component per job and names that say the job stop agents from picking the wrong button.
  • Semantic tokens give agents a correct choice; a raw palette in autocomplete gives them a wrong one.
  • Rules files are context, not enforcement: back them with lint rules and a test prompt set.
  • Treat agent output as a design system test that runs every day, and fix the system, not just the diff.

Part of Design Systems for Startups: What You Need, When and How to Build One

What is an AI ready design system?

An AI ready design system is a design system built so coding agents like Cursor, Claude Code and Copilot reach for the right component, token and pattern on their own. It's the same tokens and components a startup design system already has, written down in a way a model can find and follow.

This is a different job from designing components for AI interfaces, such as chat bubbles or streaming text. Here the AI is the user of your design system. It reads files, guesses what a component is for from its name and props, and copies whatever pattern it saw last. If your system is ambiguous, the agent fills the gap with generic defaults, and you get a fourth button style.

The test is simple: give an agent a plain request like 'add a settings page with a save button and a danger zone' and check whether the result uses only your components and tokens. If it doesn't, the system has a gap the agent found before your next hire would have.

Why do coding agents pick the wrong component?

Coding agents pick the wrong component because they only see what's in their context: the files they open, the rules you give them and patterns in their training data. They can't see your Figma file, your Notion guidelines or the conversation where the team agreed to stop using the old modal.

In the codebases we work on, the same causes come up again and again:

  • Duplicates. A Button in components/ui and a PrimaryButton in an old feature folder. The agent finds whichever it opened last.
  • Vague names. Card, Box and Container tell the agent nothing about when to use each one.
  • Raw values in reach. If the full color palette and arbitrary Tailwind values are available, the agent uses them, because that's what most public code does.
  • Docs outside the repo. Usage rules in a wiki are invisible to a tool that only reads the working directory.
  • No negative rules. Agents follow 'use X' far better when you also say 'never build Y by hand'.

Each of these is also a problem for a new human engineer. Agents just hit them faster and more often, which makes them a useful early warning.

How should you name components and props for AI agents?

Name components and props after the job they do, and keep exactly one component per job. Agent friendly components have names a model can match to a plain-English request, and props that limit choices to the ones your design allows.

Instead of

Use

Why it helps the agent

Button, PrimaryButton, CTAButton

One Button with a variant prop

One place to look, no guessing between copies

color="blue"

variant="primary" | "secondary" | "danger"

The prop names intent, so the agent picks by meaning

Box, Wrapper, Container

Stack, Section, PageShell

The name says what the layout does

size="14px"

size="sm" | "md" | "lg"

A closed set the agent can't extend by accident

Modal2, NewModal

Dialog (and delete the old one)

Deprecated copies are the most common wrong pick

Typed props do a lot of quiet work here. A TypeScript union of allowed variants is documentation the agent reads every time it writes the component, and the type checker rejects anything outside it. Free-form string or className props invite the agent to invent its own styling.

How do design tokens keep agents on-brand?

Design tokens keep agents on-brand by giving them a small set of named, correct choices instead of hundreds of raw values. When the only colors an agent can reach are background, foreground, primary and muted, it can't pick a slightly wrong blue.

Use the three-layer structure from our guide to design tokens: primitives hold raw values, semantic tokens describe purpose, component tokens apply them. Then expose only the semantic layer to day-to-day code. In Tailwind v4 that means your theme maps utilities like bg-primary and text-muted-foreground to CSS variables, and the raw palette isn't the thing autocomplete offers first.

Keep the names identical in Figma and code. If your Figma variables say color/text/muted and your CSS says --muted-foreground, a design-to-code agent has to translate, and translation is where it drifts. A Figma variables to code pipeline that generates the CSS from one token file removes that step entirely.

What documentation does a design system for LLMs need?

A design system for LLMs needs short, opinionated usage notes stored in the repo, next to each component. The format matters less than the location: if an agent opens the component file, it should find the rules in the same file or the one beside it.

For each component, write down:

  • What it's for, in one sentence an agent can match to a request.
  • When not to use it, and what to use instead.
  • The allowed variants, with one line on when each applies.
  • One correct example of real usage, with real copy, not placeholder text.
  • Accessibility requirements the agent must keep, such as a visible label or a focus trap.

This is the same content our design system documentation guide recommends for people. The difference is placement and length. A doc comment at the top of the file and an examples file beside it beat a long docs site, because agents read what's nearby and skip what isn't.

Hypothetical example: the doc block on a Dialog component

For example, suppose a SaaS team writes this at the top of its Dialog file.

Purpose: a blocking overlay for decisions the user must make before continuing, such as confirming a delete.

Don't use for: success messages (use Toast), forms longer than three fields (use a page or a Sheet), or marketing content.

Variants: default for neutral decisions, danger when the primary action destroys data. Danger dialogs must name the thing being deleted in the title.

Accessibility: always pass a title; focus returns to the trigger on close.

That's about 70 words. An agent asked to 'confirm before deleting a project' now has the component, the variant and the copy rule in one read.

How do you write usage rules agents follow?

Write usage rules as a short project-level instructions file that points to your components and tokens and lists the patterns you never want. Cursor reads project rules from .cursor/rules and AGENTS.md files; Claude Code reads CLAUDE.md and can also read AGENTS.md, according to each tool's documentation. Formats change, so check the current docs for the tools your team uses.

  1. Name the sources of truth

    Point to the components folder and the token file by path. Tell the agent to read them before writing UI.

  2. List the component for each job

    A short map: forms use Input, Select and Field; confirmations use Dialog; feedback uses Toast. Agents follow maps better than principles.

  3. Ban the drift patterns

    No hex values, no arbitrary spacing values, no new button or card components, no inline styles. Negative rules are specific and easy to check.

  4. Say what to do when nothing fits

    Tell the agent to stop and ask, or to compose from existing primitives and flag it in the summary. This stops silent new components.

  5. Keep it short and scoped

    Claude Code's docs suggest keeping each CLAUDE.md under 200 lines, and Cursor's docs suggest rules under 500 lines. Put component-folder rules in a scoped rule so they load only when relevant.

How do you check that agents use your design system correctly?

Check agent output the way you'd test code: with automated rules that fail the build and a fixed set of prompts you rerun when the system changes. Claude Code's own docs describe its instruction files as context, not enforced configuration, and that's true of every agent's rules. Enforcement has to come from tooling.

  • Lint for drift. ESLint's no-restricted-imports can block old component paths, and a Tailwind or stylelint rule can reject arbitrary values and raw color classes.
  • Type-check variants. Closed unions on props turn an invented variant into a compile error.
  • Keep a prompt set. Ten or so plain requests (a settings page, an empty state, a pricing table) that you run through your agent after each system change. Review the diffs for new components or raw values.
  • Review for system gaps. When an agent builds something by hand, ask whether the system was missing a piece. Often it was, and the fix is a new component, not a stricter rule.

Who should build and own an AI ready design system?

An AI ready design system should be owned by someone who works in both Figma and code, because most agent mistakes happen in the gap between the two. If design owns the components and engineering owns the rules file, nobody owns the mismatch the agent falls into.

For an early startup, the fastest route is usually a themed shadcn/ui base with your tokens and a short rules file. Our shadcn/ui vs custom design system comparison covers when to grow beyond that, and what a design system costs sets realistic budgets. If you want a team to build it, our design system service covers tokens, components and docs, and a design retainer keeps it current as your product and your agents change.

It isn't the right investment for everyone. If one engineer ships all the UI and rarely uses agents, a token file and a component folder are enough for now. The work pays off once several people, or several agents, are writing UI every week.

Frequently asked questions

Do AI coding agents read Figma files?
Some can, through tools like Figma's MCP server or design-to-code plugins, but most day-to-day agent work happens in the repo without Figma open. That's why usage rules and token names need to live in code. When an agent does read Figma, clean variable names that match your code tokens make its output far closer to the design.
Is shadcn/ui a good base for an AI ready design system?
Yes, for most startups. Because shadcn/ui puts the component source in your repo, agents can read exactly how each component works and what variants exist. It's also the component base v0 builds on, so AI tools tend to know its patterns well. You still need to theme it with your tokens and remove anything your design doesn't allow.
Should I write one rules file for every AI tool?
Keep one source of truth and point each tool at it. Cursor and Claude Code can both read an AGENTS.md file according to their docs, and Claude Code can import other files into CLAUDE.md. Duplicated rule files drift apart over time, and then each agent follows a slightly different version of your system.
How long should component documentation be for agents?
Short. A purpose line, when not to use it, the allowed variants, one real example and any accessibility rules usually fit in under 100 words per component. Agents follow specific, nearby instructions more reliably than long pages, and short docs are also the ones people keep up to date.
Can a design system stop agents from writing inconsistent UI completely?
No system stops it completely, because rules files guide agents rather than control them. Lint rules, typed props and a review step catch most drift before it ships. The remaining cases usually show a missing component or an unclear rule, which is useful feedback for improving the system itself.

· CEO & Design Director

Copywriter, designer and developer, and founder of Designify Studio. Over five years, 60+ projects across 14+ industries, for startups that have raised $300M+.

Want this done for you? Monthly retainer, $6,000.

Your ongoing design and development team, for products that keep shipping. $6,000, per month, flat fee. Book a free 30-minute call to see if it fits.

Schedule Call