A token is a decision with a name.
"Define, name, and enforce design tokens so the same decision is not made twelve different ways."
Ali AhmedWhy this exists
Hardcoded hex values are technical debt designers accumulate and engineers pay down. Every time someone types #1A1A2E into a CSS file instead of var(--color-surface-inverse), that project becomes harder to re-theme, audit, and hand over. Tokens enforce vocabulary. Without them, a design system is just a collection of screenshots.
Operational Flow
Define primitives first: Establish the raw scale like spacing-4, color-blue-600, or font-size-14 before you create semantic tokens. Primitives are the alphabet. Semantics are the words.
Name semantics by role, not value: Use color-text-danger instead of color-red. The token name must survive a rebrand without becoming a lie.
Store tokens in one source: Tokens live in a single tokens.json file. Figma variables and CSS custom properties are generated from this file, not maintained separately.
Use a three-tier structure: Component tokens (button-primary-background) reference semantic tokens (color-action-primary), which reference primitives (color-blue-600). No component token should reference a primitive directly.
Enforce tokens in code review: Every PR that introduces a raw color, spacing, or font value that bypasses the token system gets a blocking comment. No exceptions.
Audit quarterly: Run a script against the codebase to catch hardcoded values that slipped through. Fix them in the same sprint. The audit takes under two hours if you maintain discipline.
What good looks like
- A brand color change propagates across every screen in under thirty minutes, with no component-level overrides to hunt down.
- A new engineer reads color-text-muted in a codebase and immediately understands it means secondary text, without opening Figma.
- Dark mode is implemented by swapping semantic token values, not by writing a parallel stylesheet.
What NOT to do
- Don't create tokens for one-off values. If a spacing value is used once and never again, it is a magic number that should stay in a local comment.
- Don't let Figma variables and CSS custom properties drift out of sync for more than one sprint. The divergence compounds.
- Don't name tokens after their current value, like color-grey-text. Name them after what they mean, like color-text-secondary.
The worst token system we ever inherited was on a two-year-old project. The designer named tokens by their Figma layer position, like Text/Body/01 and Text/Body/02. Meanwhile, the developer pulled hex values directly from the inspect panel. By the time we took over, the stylesheet had over two hundred unique color values. A brand color change request landed us in a two-week project that should have taken two days. Nobody was lazy. They just never agreed on where decisions would live.
Tokens are a shared contract between design and engineering. The naming convention, the tier structure, and the source file must be agreed on at project kickoff. Treat them as seriously as the database schema. A messy token system remains invisible until the moment it becomes catastrophic.