Give an AI Coding Agent Your Design System

If you want an AI coding agent to use your design system, hand it three machine-readable files and delete the prose. A tokens file, a component inventory, and a lint rule that fails the build. Agents follow what they can read and what punishes them. A twelve-page brand guideline PDF is neither, which is why the agent keeps producing components that look almost right and use `#1E88E5` instead of your actual blue.

This is about visual and component conventions specifically. Naming, imports, and code structure are a separate problem, covered in making an agent follow your code style.

File one: tokens, as data

Agents are excellent at copying from a table of values and poor at inferring values from adjectives. "Our brand blue" produces a guess. A file produces the value.

{
  "color": {
    "brand": { "500": "#0B5FFF", "600": "#0847C4", "50": "#EAF1FF" },
    "text":  { "default": "#101828", "muted": "#667085" },
    "border":{ "subtle": "#E4E7EC" }
  },
  "space":  { "1": "4px", "2": "8px", "3": "12px", "4": "16px", "6": "24px" },
  "radius": { "sm": "4px", "md": "8px", "pill": "999px" },
  "font":   { "body": "Inter, system-ui, sans-serif", "size": { "sm": "13px", "base": "15px", "lg": "18px" } }
}

If you would rather not invent a shape, the W3C Design Tokens Community Group published a stable, vendor-neutral token format in October 2025 that most design tools now read. Using it costs nothing and means your tokens survive a change of tooling.

Two rules make this work in practice.

Keep the scale small. If your spacing scale has fourteen steps, the agent will pick a plausible wrong one. Six steps and it picks correctly, because there is less room to be wrong.

Do not include values you do not want used. A tokens file with a full 50-to-900 ramp for every colour invites the agent to reach for `brand.300` in a place your design system never uses it. Ship the subset you actually apply.

File two: a component inventory the agent can read

This is the file most teams do not have, and it is the one that stops the agent writing a new button. The agent's default behaviour is to build what it needs, because building is cheaper for it than searching. It only searches when it knows what exists.

Keep it flat, keep it current, and keep it in the repo:

# Components

| Component | Import | Use for | Do not use for |
|---|---|---|---|
| Button | @/ui/button | Any action the user takes | Navigation, use Link |
| Link | @/ui/link | Navigation between pages | Actions, use Button |
| Card | @/ui/card | Grouping related content | Modals, use Dialog |
| Dialog | @/ui/dialog | Blocking confirmations | Inline forms |
| Field | @/ui/field | Label, input, error together | Standalone inputs |
| Banner | @/ui/banner | Page-level status messages | Per-field validation |

The "do not use for" column does most of the work. It is the column that tells the agent a `Card` with a fixed overlay is not the answer, and it is the difference between an inventory and a list.

Point at it explicitly from your agent instructions file. Something as blunt as "before creating any UI component, read `docs/components.md` and use an existing component if one fits" belongs in there. The general shape of that file is covered in how to write an AGENTS.md file, and the same technique works for internal libraries generally, described in getting an agent to use your internal library.

File three: the rule that fails the build

Documentation is advice. A failing check is a fact. Give the agent a way to discover it broke the rules without you telling it.

The two checks worth having:

Ban raw values. A lint rule that rejects hex colours, raw pixel values, and hard-coded font families in component files. Stylelint, ESLint with a custom rule, or a five-line grep in CI all work. The mechanism does not matter, the failure does.

Ban duplicate primitives. A check that fails when a file outside `ui/` exports something called `Button`, `Modal`, `Input`, or any other name already in the inventory.

Then make sure the agent runs the check itself. An agent that runs `npm run lint` before finishing will fix its own violations without a review cycle. An agent that does not run it will hand you the violations to find.

What does not work

Screenshots as specification. Agents read screenshots well enough to describe them and not well enough to reproduce spacing, and they will confidently invent values that look close. A screenshot is useful for saying "this is broken", not for saying "build this". Prompting with a screenshot is worth its own read for the cases where it does help.

Brand guideline documents. Written for humans making judgement calls, and full of sentences like "use accent colours sparingly". An agent cannot act on sparingly.

Telling it once in chat. It holds for the current session and evaporates. If the instruction matters, it goes in a file the agent reads every time.

Asking it to "follow the existing patterns". It will find a pattern. There is no guarantee it finds yours, particularly in a codebase with three years of history and two abandoned design directions in it.

A one-hour setup

1. Write the tokens file from what your CSS actually contains, not what the design tool says. Where they disagree, the codebase is the truth.

2. Write the component inventory by listing what is in your `ui/` directory, then fill in the "do not use for" column from the mistakes you have already corrected in review.

3. Add one lint rule banning hex colours outside the tokens file. Just one, to start.

4. Add three lines to your agent instructions file pointing at all of the above and requiring the lint run before finishing.

5. Ask the agent to build one small component and read the diff carefully.

Step five is the test. If it imports from your inventory and uses tokens, the setup holds and you can expand it. If it invents a button, the instructions file is not being read, and that is a different problem worth solving before you write anything else.

Keeping it honest over time

The inventory drifts the moment someone adds a component without updating it, and a stale inventory is worse than none because the agent trusts it. The cheapest fix is a CI check that compares the exports of your `ui/` directory against the rows in the inventory file and fails when they disagree. Ten lines, and it removes the only way this setup rots. For the broader landscape of what agents will and will not respect, our overview of AI coding tools covers where these instructions sit relative to everything else you configure.

FAQ

Why does my AI agent ignore my design system?

Usually because it was given prose rather than data, or because the file describing the system is never loaded into context. Agents follow structured values and enforced checks far more reliably than written guidance.

Should I put design tokens in the agent instructions file?

Point at the tokens file, do not paste it. Duplicated values drift apart, and the agent will eventually read the stale copy.

Can I just give the agent a Figma link?

Not as your only input. It gives the agent an impression rather than exact values, and exactness is the entire point of a token scale.

How do I stop the agent creating duplicate components?

A component inventory it is told to read before building, plus a check that fails when a component name already in the inventory is exported from somewhere else.

Does this work with AI app builders as well as coding agents?

Partly. Builders that generate into a real repository can read the same files. Builders with no repository have nowhere to put them, so you are limited to restating the tokens in the prompt each time.