Skip to content
UX Atlas
Design systemCraft conventionIntermediate

Design Tokens

Named values that carry design decisions, so a change happens once rather than in every consuming file.

Definition

A design token is a named entity storing a design decision: a colour, a spacing step, a font size, a duration. Tokens are consumed by designs and by code, which is what keeps the two in sync.

Craft convention. True because the industry converged on it. Breaking it costs familiarity, not correctness.

On this page
  1. Definition
  2. Three layers, and why the middle one matters
  3. Naming that survives
  4. In practice
  5. Sources
  6. Continue from here

Three layers, and why the middle one matters

LayerExampleWho uses it
Primitiveblue-600, space-4, size-16Only the semantic layer. Never a component.
Semanticaction-primary, surface-raised, text-secondaryComponents and designers. This is the API.
Componentbutton-primary-backgroundOne component. Optional, and only where a component genuinely needs its own decision.

Naming that survives

  • Name by role, not by appearance. text-secondary survives a palette change; text-grey does not.
  • Use a consistent structure, such as category, role, variant, state.
  • Do not encode the value in the name. space-16 breaks when the scale changes.
  • Keep the set small enough that people can hold it in mind. A hundred colour tokens will be used inconsistently.
  • Document what each token is for, with an example of the wrong choice.

In practice

Rebranding without touching components

Multi-brand products

A product supporting several brands changes only the semantic token mapping per brand. Component code is untouched, which is what makes multi-brand maintainable at scale.

Sources

Where a source establishes something narrower than the popular reading of it, the note says so.

Continue from here

Each link says what the connection is, so you can tell a principle from an alternative from a thing people mix this up with.

Principles behind this

The reasoning this solution is an application of.

Relied on by

Entries that assume this is already in place.

  • ThemingDesign system

    Theming is token remapping. Without a semantic token layer there is nothing to remap.

Often used with

These usually appear in the same screen or the same decision.

Practical example

A worked decision where this was the deciding factor.

Short definition

The one-paragraph version, for when that is all you need.

Related concept

Connected closely enough to change how you apply this.