DESIGN.md Design Tokens: A Guide

If you audit the mistakes an AI agent makes on UI work, a large share trace back to tokens — the small, reusable design values like colors, spacing steps, radii, and font sizes. The agent does not lack the ability to use them; it lacks knowledge of which ones exist and what each one is for. So it hardcodes a hex value here, invents a 13px font size there, and picks a radius that almost matches yours. Individually trivial, collectively the reason the output looks off.

Expressing tokens well in your DESIGN.md is therefore one of the highest-return things you can do. Done right, the agent stops guessing values and starts referencing yours — which is the entire point of having tokens in the first place.

A token entry needs three things to be usable by an agent: the name it should reference in code, the value that name resolves to, and the situations where it applies. Drop any one of the three and the agent has to guess the rest.

The intent column is the one people skip, and it is the most important. Two colors can have similar values but completely different jobs; without the intent, the agent picks by appearance and gets it wrong. Tell it that one muted gray is for secondary text and another is for disabled controls, and it will stop swapping them.

A common mistake is listing colors as a palette — every hue you own, sorted prettily. That is a swatch sheet, not an instruction. The agent needs semantic groups: which token is the background, which is the foreground, which is the primary action, which is the border. Semantic naming means the agent reaches for `--primary` when it needs an accent, without deciding which of your seven blues counts as primary.

### Surface
- `--bg`         #faf9f7  page background
- `--surface`    #ffffff  cards, panels, popovers
- `--muted`      #f2f0ec  subtle fills, hover backgrounds

### Content
- `--fg`         #1a1a1a  primary text
- `--muted-fg`   #6b6b6b  secondary text, meta, captions

### Action
- `--primary`    #d4502a  primary buttons, active nav, links
- `--border`     #e6e3dd  hairline dividers, input and card edges

Defining tokens is only half the job. Unless you say otherwise, an agent will happily mix your tokens with raw values in the same file — a `--primary` button next to a hand-typed `#d5512b`. State the rule directly: components reference tokens only, never literal colors, sizes, or radii. Then the agent has a clear line to hold, and your review gets easier because any raw value in a diff is obviously wrong.

This rule also future-proofs the codebase. When you retheme — a dark mode, a rebrand, a client white-label — token references update in one place while raw values would have to be hunted down individually. Agents that respect the rule produce code that rethemes cleanly; agents that do not leave you with a scavenger hunt.

A token section is only trustworthy if it matches the tokens actually defined in your code. The moment they drift — a value changed in CSS but not in the doc — the agent starts applying stale numbers with full confidence, which is worse than having no doc at all. Treat the DESIGN.md token list as something that must be updated in the same change that alters a token, the same way you would update a type when you change a schema.

For larger systems, consider generating the token table from your source of truth rather than maintaining it by hand. If your tokens live in a CSS file or a tokens JSON, a small script can emit the Markdown table on build, and the doc can never lie. But do not over-engineer this on day one — a hand-maintained table that you keep honest beats an automated pipeline you never finish.

However you manage it, the discipline is the same: the token section is a contract. The agent will follow it exactly, so it is worth exactly what its accuracy is worth. Keep it accurate, keep it semantic, and keep the intent column filled in — and tokens go from being the thing agents get most wrong to the thing they get reliably right.

The same rule applies when tokens have aliases or themes. Document the semantic name first, then explain how light and dark surfaces map to it. An agent should not have to infer whether a token is safe on both themes from the hex value alone. Name the role, the allowed contexts, and the fallback when contrast or state changes.