A token is a promise between design and engineering. If it only lives in Figma, it isn’t a system. We name for use, not for decoration — spacing, type, and surface tokens map to what ships.
Handoff health (last audit)
- 94% — tokens used in CSS (vs Figma source)
- 12 — orphaned names removed (one cleanup PR)
- <1d — new token to main (median)
Naming rules we enforce
| Layer | Example | Anti-pattern |
|---|---|---|
| Primitive | --gray-500 | --almost-black |
| Semantic | --border | --line-soft-2 |
| Component | --header-bg | --navBlue |
Ship the same names
// tokens.ts
export const space = {
1: "0.25rem",
2: "0.5rem",
3: "0.75rem",
4: "1rem",
6: "1.5rem",
8: "2rem",
} as const;
export const color = {
background: "var(--background)",
foreground: "var(--foreground)",
border: "var(--border)",
muted: "var(--muted-foreground)",
} as const;
// Figma plugin exports the same keys — no rename pass.
Docs are part of the product. If a new teammate can’t find the rule, the rule doesn’t exist.
“If it only lives in Figma, it isn’t a system.”