Design tokens are named, platform-neutral values that store the visual decisions of a design system, such as colors, spacing, typography, radii, shadows and motion timings, in a single source of truth. In the design workflow, they replace hard-coded values like #1A73E8 or 16px with meaningful names like color.action.primary or space.md, which design tools and code on every platform can reference.
Because the same token feeds design files, web CSS, iOS and Android code, one change propagates everywhere. This makes tokens the connective layer between design and engineering, and the foundation for theming, dark mode and multi-brand products.
How design tokens work
A design token is a name-value pair with a type, stored in a structured, tool-agnostic format, usually JSON. A build step transforms these source files into platform outputs such as CSS custom properties, Sass variables, Swift constants or Android resources.
Tokens can reference other tokens through aliases. A semantic token such as color.text.danger points to a primitive token such as color.red.600, so changing the primitive updates every dependent decision while the names used in components stay stable.
The Design Tokens Community Group of the W3C has published a specification for a common interchange format, defining token types, the $value and $type properties and the curly-brace alias syntax such as {color.red.600}. Shared formats let design tools and build pipelines exchange tokens without custom converters, although tool support still varies.
Token tiers and naming
Mature systems organize tokens in three tiers of increasing specificity. Each tier answers a different question, and components should consume the semantic or component tier rather than raw primitives.
| Tier | Also called | Example | Purpose |
|---|---|---|---|
| Primitive tokens | Global, core or base tokens | color.blue.500 | Define the full available palette and scales |
| Semantic tokens | Alias or decision tokens | color.action.primary | Assign meaning and intent to primitives |
| Component tokens | Specific tokens | button.primary.background | Bind a decision to one component part |
Names follow a consistent structure from general to specific, typically category, property, variant and state, as in color.background.surface.hover. Names describe purpose, not appearance: color.text.subtle survives a palette change, while color.text.gray becomes misleading the moment the value turns blue.
Token categories and typical values
Design tokens cover any visual property that should be decided once and reused. The table lists the categories most systems define and how values are usually expressed.
| Category | Example token | Typical value | Common output |
|---|---|---|---|
| Color | color.border.default | Hex, RGB or OKLCH value | CSS custom property |
| Spacing | space.400 | Multiples of a 4 or 8 px base | rem or density-independent pixels |
| Typography | font.body.md | Family, size, weight, line height | Composite text style |
| Border radius | radius.sm | 2 to 8 px | Corner radius values |
| Elevation | shadow.overlay | Offset, blur, spread, color | Box shadow or platform elevation |
| Motion | duration.fast | 100 to 200 ms with easing curve | Transition timing values |
| Breakpoints | breakpoint.lg | 1024 px | Media query values |
Composite tokens group several values, such as a typography token combining family, size, weight and line height. They reduce mismatches but are harder to transform for platforms that handle the properties separately.
Design tokens compared with related approaches
Design tokens are often confused with style variables, shared styles and component libraries. The differences lie in scope and in whether a value can travel across platforms.
| Approach | Where it lives | Cross-platform | Main limitation |
|---|---|---|---|
| Hard-coded values | Scattered in code and files | No | Every change is manual and error-prone |
| CSS or Sass variables | One web codebase | No | Locked to one technology |
| Shared styles in a design tool | One design tool library | No | Not readable by code directly |
| Design tokens | Platform-neutral source files | Yes | Needs a build pipeline and governance |
| Component library | Coded and designed components | Partly | Consumes tokens rather than replacing them |
Tokens feed the component library rather than compete with it, and they make developer handoff more precise because specifications reference token names instead of raw numbers that developers must interpret.
Theming, governance and common pitfalls
The strongest argument for tokens is theming. Light and dark modes, high-contrast themes and sub-brands are implemented by remapping semantic tokens to different primitives while component code stays unchanged.
- Too many tokens: hundreds of one-off component tokens make the system harder to use than the values they replaced.
- Appearance-based names: names like
blue-buttonbreak as soon as the brand or theme changes. - Skipping the semantic tier: components that use primitives directly cannot be themed without editing each component.
- Two sources of truth: if designers edit the design tool and developers edit JSON separately, values drift within weeks.
- No versioning: renaming or deleting tokens without semantic versioning and deprecation notices breaks consuming products.
Healthy token workflows keep the source in version control, run automated builds on every change, and treat renames as breaking changes that require release notes and a migration period.
Explained without jargon
Design tokens are a shared dictionary of style decisions. Instead of every designer and developer typing the exact shade of blue or the exact amount of space by hand, they all use the same agreed name, such as primary color or medium spacing.
It works like a recipe that says use the house sauce rather than listing its ingredients each time. If the chef changes the house sauce, every dish that uses it changes too. In the same way, changing one token updates the website and the apps at once.
A typical use case
A bank runs a web portal, an iOS app and an Android app, maintained by three separate teams. A brand refresh requires a new primary color and a dark mode, and a first estimate shows more than 1,400 hard-coded color values spread across the three codebases.
The design system team defines about 120 primitive and 90 semantic tokens in DTCG-format JSON, links them to the design tool library, and uses a build pipeline to generate CSS custom properties, Swift constants and Android resources. Each team then replaces raw values with semantic token references over two sprints.
The brand color change itself becomes a single edit to one primitive token, and dark mode ships as a second mapping of the same semantic tokens. Later contrast fixes are made once and reach all three platforms in the next release.