Design tokens are the named variables that turn brand decisions into engineering primitives. Colour, typography, spacing, radius, shadow — each captured as a named token that designers reference in Figma and engineers reference in code. Change the token once and every surface updates.
This is the 2026 guide. What design tokens are, why they matter, the three-tier structure that holds up at scale, and how to set up a token system that designers and engineers actually share.
Quick answer: A design token is a named variable holding a single design decision —
color.brand.primary,space.4,font.size.body. Tokens are the bridge between brand decisions and code. They are platform-agnostic (web, iOS, Android, email, Figma) and the standard structure has three tiers: primitive, semantic, component.
What a Design Token Actually Looks Like
A token is just a name pointing at a value. The simplest form:
{
"color": {
"brand": {
"primary": { "value": "#FF4F01" }
}
}
}
That tiny JSON snippet is the source of truth. Now:
- The web team's CSS pulls
--color-brand-primary: #FF4F01;from it. - The iOS team's Swift file gets
Color.brandPrimary = UIColor(hex: "FF4F01"). - The Figma library exposes a style called
color/brand/primary. - The documentation site renders a swatch automatically.
Change #FF4F01 to a new orange in the JSON. Every platform updates on next build.
The Three-Tier Token Structure
The pattern that survives a re-brand is primitive → semantic → component.
Primitive tokens — raw values
The base layer. Just the colours, sizes, and other values in their unopinionated form.
color.orange.500 = #FF4F01
color.gray.900 = #070707
space.4 = 16px
font.size.6 = 32px
Primitive tokens have no opinion about where they're used. They are just the palette.
Semantic tokens — intent
The middle layer. Names that describe what the token is for, referencing primitives.
color.brand.primary = color.orange.500
color.text.body = color.gray.900
color.surface.canvas = color.white
space.gutter = space.4
font.size.body = font.size.4
Semantic tokens are where the design language lives. When a designer says "use the body text colour" they mean color.text.body, not a specific hex code.
Component tokens — usage
The top layer. Component-specific tokens that reference semantic tokens.
button.primary.background = color.brand.primary
button.primary.text = color.text.inverse
card.background = color.surface.canvas
card.padding = space.gutter
Component tokens are optional but powerful — they let a component author capture the intent of every visual decision without inventing new names.
Why three tiers matter. A brand re-skin (new colour palette but same product structure) updates only the primitive tier. A design-language refresh (same colours but different uses) updates only the semantic tier. Components keep working because they reference semantics. Skip the tiers and a re-brand turns into a global find-and-replace across thirty repositories.
The Categories Worth Tokenising
Most production token systems cover seven categories:
- Colour — brand, semantic (text, surface, border), state (success, warning, error, info).
- Typography — font family, size scale, weight scale, line-height scale, letter-spacing.
- Spacing — a single spacing scale used for padding, margin, gap.
- Sizing — icon sizes, container max-widths, breakpoints.
- Radius — border-radius scale (none, sm, md, lg, full).
- Shadow — elevation scale (sm, md, lg, xl).
- Motion — duration tokens (fast, base, slow) and easing functions.
Some systems also tokenise z-index, opacity, and border-width. The set should be the minimum needed to compose every component without one-off magic numbers — not every value in the design.
Why Tokens Beat Hard-Coded Values
Three concrete payoffs that every brand discovers within six months of adopting tokens:
1. Re-brand becomes one PR. Change color.brand.primary in the source-of-truth JSON, run the build, ship. Every surface updates. The alternative — searching for #FF4F01 across thirty repos, replacing it in CSS, Swift, Kotlin, Figma, email templates — is a six-week project that always misses a corner.
2. Light mode and dark mode become a theme swap. Each theme is just a different set of values for the same token names. The components don't change; the underlying tokens do.
3. White-label and brand variants are nearly free. A SaaS product that wants to let enterprise customers re-brand the interface ships a token override. The customer's colours, typography, and spacing flow through every component without per-component changes.
How Designers and Engineers Stay in Sync
The standard 2026 stack:
- Source of truth — a JSON or YAML file (often using the W3C Design Tokens Community Group format) lives in a dedicated repository owned by the design-system team.
- Style Dictionary (or a similar transformer) exports the JSON to platform-specific files — CSS variables for web, Swift constants for iOS, Kotlin objects for Android, XML for older Android, JSON for docs.
- Figma reads the same JSON via a plugin (Tokens Studio is the most common). Designers work with Figma styles that map to tokens by name.
- Documentation site auto-generates from the JSON — swatches, scale tables, usage examples.
The discipline that makes this stack work: the source of truth is the only place anyone changes a value. No one edits the CSS variable directly. No one hard-codes a colour in Swift. Every platform pulls from the export step, and any change starts in the source.
Common Token Mistakes
- Tokenising too early. A site with one colour palette doesn't need a three-tier token system. Start with CSS variables and well-named values. Graduate to a full token system once you have two or more surfaces to keep in sync.
- Skipping the semantic tier. Going straight from primitives to component-level usage means every component depends on raw colour names, and a re-brand touches every component file.
- Magic numbers everywhere. A spacing scale is only useful if components reference it instead of inventing one-off paddings. Audit your component CSS — any number that isn't a token reference is a maintenance liability.
- Designer-engineer divergence. Designers updating Figma colours without pushing through tokens, or engineers tweaking CSS without going through the source of truth. The discipline has to hold or the token system quietly degrades.
Tokens in the Broader Design System
Design tokens are one layer of a design system — the layer below components and above raw values. The system stack roughly:
- Brand guidelines — the human-readable rules.
- Design tokens — the same rules expressed as named variables.
- Components — buttons, cards, forms built using tokens.
- Patterns — combinations of components for common UI tasks.
- Templates — page-level structures built from patterns.
Each layer references the one below. Tokens sit at the boundary where brand becomes code.
Bottom Line
Design tokens are the named variables that turn brand decisions into engineering primitives. Structure them in three tiers — primitive, semantic, component — and keep a single source of truth that every platform pulls from. The investment pays back the first time you re-brand, the first time you ship dark mode, or the first time you white-label.
If you're building a design system and need a partner who delivers on-brand work across web, mobile, marketing collateral and print without coordinating three vendors, DigitalPolo's unlimited graphic design subscription ships from one team for one flat monthly fee. See the plans →