A design token is a named value, like color-primary or space-4, that stores a single design decision so it can be reused across a product. Instead of hardcoding #3B82F6 in fifty places, you point them all at one token and change it once. Tokens are the shared language between design and code, and the backbone of any design system. They turn theming like dark mode or multi-brand into a config change instead of a rewrite.
Use cases
Skip tokens and your "design system" is a pile of components with hex codes baked in, where every rebrand becomes a find-and-replace nightmare.
The rebrand from hell. Marketing changes the brand blue, and a team without tokens hunts through hundreds of files. With a token, you edit color-brand-primary once and it cascades everywhere.
Dark mode bolted on too late. A team that jumped from raw values straight to components can't theme cleanly.
Design and code disagree on blue. A designer tweaks a color in Figma, devs never hear about it, and the app drifts. Tokens synced from Figma to code keep one source of truth.
How it's used in practice
Structure in three tiers: global/primitive (blue-500: #3B82F6) → semantic (color-action: blue-500) → component (button-bg: color-action). Components reference the semantic layer, never raw values.
Name by purpose, not appearance:color-error, not color-red. A red error today might be orange tomorrow, and the name should survive that.
Store platform-agnostic, then transform: keep tokens in JSON and run a tool to output CSS, Swift, and Android from one source.
Document the convention before scaling: write the naming pattern ({category}-{property}-{variant}-{state}) down so nobody invents duplicates.
🪄
Pro-tip: Don't build a three-tier token pipeline for a two-person MVP. The full setup (Style Dictionary, CI/CD, multi-platform export) is overkill until you actually have multiple themes or platforms to sync.
Start with primitives plus a thin semantic layer in CSS variables, and add tooling only when the pain of not having it gets real.
Challenges & limitations
Naming is the hardest part, and teams underestimate it. "Global," "semantic," "primitive," and "alias" overlap and confuse people, and a vague convention breeds duplicates fast.
Tooling is still fragmented. The DTCG format is stabilizing, but token sync between Figma, code, and build tools breaks in annoying ways, and round-tripping changes is rarely clean.
Over-tokenizing buries you. Make a token for everything and you get a sprawling list nobody understands. A value earns a token when it's shared (rule of thumb: three or more uses), not by default.
