If your design system has a component library in Figma and a component library in code, and the two are slowly drifting apart, design tokens are the solution you are looking for.
A design token is a named variable that stores a design decision. Instead of hardcoding hex values, spacing numbers, and font sizes throughout your codebase, you define them once — as tokens — and reference them everywhere. When a decision changes, you change it once.
What tokens actually solve
The token layer solves the synchronisation problem. Without tokens, a designer changes a colour in Figma and then hopes the engineer updates the same colour in every place it appears in code. With tokens, there is a single source of truth — and it is the same source for both.
Tokens also enable theming at scale. Light mode, dark mode, brand variants, high-contrast mode — all of these become manageable when the underlying decisions are stored as named variables.
The three tiers of tokens
A robust token architecture has three tiers. Global tokens are the raw values: blue-500 = #2f6aff. Semantic tokens are the decisions: color-action-primary = blue-500. Component tokens are the application: button-background = color-action-primary.
Most teams implement global tokens and stop there. The result is a design system where you can change the blue across the board, but you cannot distinguish between 'the blue we use for actions' and 'the blue we use for information states'.
Common implementation mistakes
Too many tokens. A token for every individual value creates a system that is as hard to maintain as no system at all. Start with colour, spacing, and typography. Add tokens when you identify a specific synchronisation problem they would solve.
Names that describe appearance, not intent. color-blue is an appearance token. color-interactive-primary is an intent token. In six months when you want to try a green CTA, the second name still makes sense. The first does not.
Design tokens are named variables that store design decisions (like colors, spacing, typography) and act as a single source of truth shared between design tools (e.g. Figma) and code. Instead of hardcoding values everywhere, you define tokens once and reference them across your system, so changing a decision means updating it in one place.
They solve the synchronization problem between Figma and code, and they make theming (light/dark modes, brand variants, high-contrast modes) scalable: a theme is just a different set of values for the same token names.
A robust token architecture has three tiers:
- Global tokens: raw values (e.g. blue-500 = #2f6aff).
- Semantic tokens: intent-based decisions (e.g. color-action-primary = blue-500).
- Component tokens: application in components (e.g. button-background = color-action-primary).
Most teams stop at global tokens, which makes it hard to distinguish different uses of the same color. The semantic layer is where the real value lies because it encodes purpose (e.g. color-feedback-error) instead of appearance (e.g. red-600).
Common mistakes include:
- Too many tokens: creating a token for every single value makes the system unmanageable. Start with core areas (color, spacing, typography) and add tokens only when they solve a real synchronization problem.
- Appearance-based names: names like color-blue don’t age well. Intent-based names like color-interactive-primary remain meaningful even if the visual choice (e.g. blue vs green) changes.
When Figma components and code both use the same token names (e.g. color-action-primary), design changes propagate consistently. Tools like Style Dictionary can convert a central token definition into platform-specific outputs (CSS, iOS, Android), making tokens the single place where decisions live.
Beyond technical convenience, tokens are a governance mechanism. They make the intent behind every design decision explicit and reviewable. One-off values stand out in code review, and accessibility checks can be done at the token level (e.g. verifying contrast for text-related tokens and then rolling out changes everywhere).
To get started, don’t wait for a perfect architecture. Begin with a small, semantic, three-tier system (even if the component tier is mostly empty at first): a handful of tokens for primary color, background, text, borders, and spacing. Prioritize semantic naming and consistency, then refine as the system grows.
Design tokens are named variables that store design decisions (like colours, spacing, typography) and act as a single source of truth shared between design tools (such as Figma) and code. Instead of hardcoding values everywhere, you define tokens once and reference them across your system, so changing a decision means updating it in one place.
They solve the synchronisation problem between Figma and code, and they make theming (light/dark modes, brand variants, high-contrast modes) scalable: a theme is just a different set of values for the same token names.
A robust token architecture has three tiers:
- Global tokens: raw values (e.g. blue-500 = #2f6aff).
- Semantic tokens: intent-based decisions (e.g. color-action-primary = blue-500).
- Component tokens: application in components (e.g. button-background = color-action-primary).
Most teams stop at global tokens, which makes it hard to distinguish different uses of the same colour. The semantic layer is where the real value lies because it encodes purpose (e.g. color-feedback-error) instead of appearance (e.g. red-600).
Common mistakes include:
- Too many tokens: creating a token for every single value makes the system unmanageable. Start with core areas (colour, spacing, typography) and add tokens only when they solve a real synchronisation problem.
- Appearance-based names: names like color-blue don’t age well. Intent-based names like color-interactive-primary remain meaningful even if the visual choice (e.g. blue vs green) changes.
When Figma components and code both use the same token names (e.g. color-action-primary), design changes propagate consistently. Tools like Style Dictionary can convert a central token definition into platform-specific outputs (CSS, iOS, Android), making tokens the single place where decisions live.
To get started, begin with a small, semantic, three-tier system: a handful of tokens for primary colour, background, text, borders, and spacing. Prioritise semantic naming and consistency, then refine as the system grows.
