Design Tokens Explained
By CodexierPublished 5 min read
Every interface is built from hundreds of small decisions: this blue, this grey, this spacing, this corner radius. When those decisions are copied by hand into each screen and each file, changing one means hunting for every copy. Design tokens store each decision once, under a name both designers and developers use. This guide explains what tokens are, how they are organised, how they get from Figma into code and how to start without a big project.
What a design token is
Consider a button. Without tokens, its background is a hex code typed into the design file and again into the stylesheet. With tokens, the design says colour-action-primary and so does the code. When marketing adjusts the brand blue, one value changes and every button, link and highlight that uses it follows, in the design file and on the live site. The mechanism is indirection: components refer to names, names refer to values.
Core, semantic and component tokens
Most token systems use three layers. The layering is what makes changes cheap, because each layer answers a different question and can change independently.
| Layer | Example name | Answers the question |
|---|---|---|
| Core | blue-600, space-4, radius-2 | What values do we have? |
| Semantic | colour-text-default, colour-action-primary, colour-feedback-error | What is this value used for? |
| Component | button-primary-background, card-padding | What does this component use? |
Components should use semantic tokens, not core ones. A button that uses blue-600 directly breaks the moment dark mode needs a different blue.
Small teams can skip the component layer at first. Core plus semantic tokens cover most needs, and component tokens are worth adding only where one component genuinely needs to differ from the general rule.
From Figma to code
In Figma, tokens live as variables, grouped into collections with modes such as light and dark. The practical question is how they reach the code without being retyped. The common path is to export them as a JSON file, following the format being standardised by the W3C design tokens community group, and transform that file into CSS custom properties, a Tailwind theme or native values for iOS and Android with a build tool.
- Define tokens as Figma variables with agreed names.
- Export them to a JSON file stored in the code repository, not on someone's laptop.
- Run a transform step that generates CSS variables or platform files from the JSON.
- Use only the generated variables in components; a raw hex code in a component is a bug.
- Change tokens through the same route every time, so design and code never drift.
Theming and dark mode
Semantic tokens make theming straightforward. Dark mode is a second set of values for the same semantic names: colour-surface-default is near-white in light mode and near-black in dark mode, and no component needs to know. The same approach handles a white-label product with one theme per customer or a sub-brand. Check contrast for every theme, since a colour pair that passes in light mode can fail in dark; the guide to brand colours that pass contrast explains the ratios.
Starting small
Colour
A core palette plus semantic names for text, surfaces, borders, actions and feedback states.
Typography
Font families, a type scale with sizes and line heights, and weights.
Spacing
A spacing scale, such as steps of four or eight pixels, used for padding, gaps and margins.
When you do not need tokens: a small marketing site with one developer and no plans for themes can live with a well-organised stylesheet. Tokens pay off when several people design and build, when there is more than one product or platform, or when a rebrand or dark mode is coming. Read does your company need a design system first; if the answer is yes, our design system and UI kit sets up tokens in Figma and code together. See the pricing page or book a call.
Frequently asked questions
Are design tokens the same as CSS variables?
No, but they are often delivered as CSS variables. A token is the design decision and its name; CSS variables are one output format. The same token can also become a Tailwind setting or an iOS or Android value.
Do we need a design system before using tokens?
No. Tokens are often the first step towards a design system and useful on their own. Even without a component library, shared colour, type and spacing tokens remove a lot of inconsistency.
How should tokens be named?
Name semantic tokens after their purpose, not their appearance: colour-text-muted rather than grey-light. Agree the naming pattern before creating many tokens, because renaming later touches every file that uses them.
Who owns the tokens?
Ideally design and development together, with one source file in the code repository and a simple review process for changes. When only one side owns them, the other side starts working around them.
Set up tokens that design and code share
Book a short call and tell us about your products, platforms and team. We tell you whether tokens would pay off now and what a first set should cover.
Book a free 15-minute call