Framework · AI & design · 3 min read
Design tokens
Named design decisions (colour, spacing, type, radius) stored as data in one place, so design tools, code and AI agents all use the same values and you can check that they do.
- 1Name
Name each decision by its purpose, with the raw value underneath.
color.status.error, not #D32F2F - 2Store once
Keep one source of truth in the design system, in a standard format.
One token file, one owner - 3Sync
Generate Figma variables, code variables and agent context from that source.
Same value in every tool - 4Check
Reference tokens in specs and context files, and lint for raw values.
"Never hard-code colours"
Use it when
- AI-generated screens or prototypes use colours and spacing that are "almost" your design system.
- Design and code drift apart: the Figma value and the coded value are no longer the same.
- You are making the design system machine-readable so agents can build on-system UI.
How to use it
- Name decisions by purpose. Give each value a name that says what it is for (for example "surface", "text-muted", "status-error", "space-md"), not what it looks like. Keep raw values underneath and point the named tokens at them. Output: a token list with purpose-based names.
- Keep one source of truth. Store the tokens in one place owned by the design system, in a standard format such as the W3C Design Tokens Community Group (DTCG) format. Everything else is generated from it. Output: one token file or repository with an owner.
- Sync it to every consumer. Generate the Figma variables, the code variables and the design context file from that source, so nobody copies values by hand. Output: the same tokens in Figma, in code and in agent context.
- Reference tokens in specs and context files. Write token names, not values, in feature specs and in
CLAUDE.mdorDESIGN.md, with an explicit rule such as "never hard-code colours, spacing or font sizes". See Context files. Output: specs and context files that name tokens. - Lint for raw values. Add a check in code review or design QA that flags hard-coded colours, spacing and font sizes, including in AI-generated code. Track the share of raw values over time as a design-system health signal. Output: an automated check and a number you can follow.
Worked example
An internal operations platform with 6 product teams. Designers generate code prototypes with an agent, and the review finds four different reds for error states.
| Before | After |
|---|---|
| Error red is pasted as hex in Figma, in code and in a prompt template, and the values differ | One token, color.status.error, in the design system's token file |
| The agent picks "a red that looks right" | CLAUDE.md says "use var(--ds-*) tokens; never hard-code colours" |
| Reviewers spot off-palette colours by eye | A linter flags every raw colour in the prototype repository |
| Changing the error colour means a search across files | Changing the token updates Figma variables and code from one place |
In the next design review, the "system drift" findings drop from the top issue to an occasional one, and the remaining cases are new needs that go to the Contribution process.
Watch out for
- Names that describe looks. "red-500" used for errors breaks when the brand changes. Name by purpose, and keep the visual scale underneath.
- Two sources of truth. If Figma and code are edited separately, they will drift. Choose one source and generate the rest.
- Tokens nobody checks. Without a lint or a review step, agents and people will keep using raw values. Make the check automatic.
- Too many tokens. Hundreds of near-identical tokens are as hard to use as raw values. Add a token only when it represents a real decision.
Template
Copy this into your design-system docs to describe a token, and into your context file as the rule.
Token: color.status.error
Purpose: Text and icons for errors that block the user
Value (source): -> palette.red.600 (defined in the token file only)
Used in: Figma variable · code variable · DESIGN.md
Do: Error messages, invalid field borders, failed status
Don't: Decoration, charts, "delete" buttons that are not errors
Owner: Design system team
Context file rule:
- Use design tokens (<prefix>-*). Never hard-code colours, spacing or font sizes.
- If no token fits, stop and list it as an open question.