Design tokens without the drama
Design tokens are promises between design and code. Here is how to keep them without endless meetings.
- Design tokens
- Figma
- CSS
- Systems
Most design token rollouts fail for the same reason: they try to model every conceivable variation before shipping a single button. We treat tokens as living contracts that start tiny and grow with proof.
in short
Key takeaways
- 01
Three tiers are enough
Global values (colors, scale), semantic roles (surface, ink), and component overrides. Never add a fourth tier.
- 02
Automate the boundary
Figma variables should compile straight to CSS custom properties and typed TypeScript enums on commit.
- 03
Lint for rogue values
A pull request that introduces an arbitrary hex code or pixel spacing fails in CI before human review.
the details
The deep dive
The abstraction trap
When teams decide to create a design system, enthusiasm frequently outpaces discipline. Within three weeks, someone has invented a five-tier ontology with names like color-brand-primary-interactive-subtle-hover-active. No one can remember what it does, so developers inspect the Figma canvas and hardcode #7193ed anyway.
The cure is strict minimalism. Start with global raw values (your literal palette and scales), map them to semantic intents (--surface-page, --ink-primary, --border-default), and stop. If a component needs something special, let it declare a local token rather than polluting the shared lexicon.
/* 1. Global palette primitives */
:root {
--blue-500: #7193ed;
--blue-600: #4468d8;
--void-900: #121213;
--void-100: #f1f1f4;
}
/* 2. Semantic roles that components actually consume */
:root {
--surface-page: var(--void-900);
--ink-primary: var(--void-100);
--accent: var(--blue-500);
--accent-hover: var(--blue-600);
}The best token system is the one that prevents arguments. If a designer changes a radius, code shouldn't need a PR discussion. — Alex Vance, Design systems lead
Automate or perish
Manual token sync is a fiction. If a designer tweaks an opacity token in Figma and has to paste a Slack message asking an engineer to update a JSON file, drift has already begun.
We wire Figma Variables directly to a GitHub Action via the Figma REST API. When variables are published in Figma, a workflow generates typed TypeScript definitions and CSS variables, runs visual regression tests, and opens an automated pull request with a visual diff summary.
- drift between design & code
- 0
- from Figma publish to PR
- <30s
- maximum token depth
- 3 tiers