Token Architecture
Design tokens that AI agents can reason about and compose correctly.
Key takeaways
- Layer tokens into raw, semantic, component, and state tiers so agents reason about intent rather than hard-coded values.
- Name tokens by purpose (
color.action.primary.bg) instead of appearance to reduce generated-UI drift. - Attach metadata like
description,allowedComponents,contrastPair, anddeprecatedso agents pick the right token. - Enforce agent rules: no raw values, prefer semantic over component tokens, and fail loudly instead of inventing names.
- Verify with schema validation, semantic-to-raw resolution checks, contrast pairs, CSS-variable snapshots, and a CI deprecation report.
Design tokens are the atomic unit of a design system. For AI agents, tokens are also a reasoning interface. If names, layers, and constraints are unclear, generated UI will drift.
Token Layers
| Layer | Purpose | Example |
|---|---|---|
| Raw | Platform-neutral values | color.blue.500, space.4 |
| Semantic | Product meaning | color.action.primary.bg |
| Component | Component-specific mapping | button.primary.bg |
| State | Interaction state | button.primary.hover.bg |
AI-Friendly Naming
Use names that explain intent, not only appearance.
export const tokens = {
color: {
action: {
primary: {
bg: '{color.brand.600}',
fg: '{color.white}',
hoverBg: '{color.brand.700}',
},
},
feedback: {
danger: {
bg: '{color.red.50}',
fg: '{color.red.700}',
},
},
},
}Token Metadata
Tokens should carry metadata that helps agents choose correctly.
| Metadata | Why it matters |
|---|---|
description | Explains when the token should be used. |
category | Separates layout, color, type, motion, and elevation. |
allowedComponents | Prevents accidental use outside intended components. |
contrastPair | Helps accessibility automation. |
deprecated | Allows migration without silent regressions. |
Rules for Agents
- Never use raw color or spacing values in generated UI.
- Prefer semantic tokens over component tokens unless implementing a component itself.
- Do not invent token names; fail loudly and request a token addition.
- Map every state to an approved token set.
- Generate token usage examples alongside token definitions.
Verification
- Run token schema validation.
- Check semantic tokens resolve to valid raw tokens.
- Check contrast pairs for text and interactive states.
- Snapshot generated CSS variables.
- Keep a deprecation report in CI.