artifactExperience & interface

Design Tokens

Design tokens are named, portable records of design decisions such as color roles, spacing, type, borders, and motion values.

Download Markdown (.md)

01What it means

A design token pairs a stable name with a value and supporting metadata so a design decision can travel between tools and platforms. Semantic tokens describe intent, such as text-danger, while lower-level tokens may represent palette values; aliases connect these layers without copying raw values everywhere.[1][2][3]

Named decisions translated across design and code Semantic roles reference foundations and resolve into platform values
Design intent
EmphasisSpacing rhythmSurface hierarchyMotion character
Semantic tokens
color.text.primaryspace.component.gapradius.control
Foundation values
PaletteScaleType metricsDurations
Modes + themes
LightDarkHigh contrastDensity
Platform transforms
CSS variablesiOSAndroidDesign tools
Components + products
Consistent applied decisions

Tokens are governed decisions, not a flat list of constants; naming, aliasing, modes, versioning, and migration determine whether they remain portable.

02Why it matters

Tokens give designers and engineers a shared vocabulary, reduce arbitrary values, and make broad changes such as theming more controlled. A machine-readable source can generate platform-specific outputs while preserving the intent behind the decision.

03When to use it

Use tokens when the same visual or behavioral decisions recur across components, themes, brands, or platforms. Introduce them gradually around proven needs, especially when design and code assets otherwise drift.

04How it works

  1. List repeated decisions and distinguish raw values from semantic roles.
  2. Choose stable names based on purpose rather than a current visual appearance.
  3. Store values, types, descriptions, and aliases in a version-controlled source.
  4. Transform the source into platform formats and validate generated output.
  5. Use tokens in components instead of bypassing them with local values.
  6. Review changes for accessibility, theme coverage, and downstream breakage.

05A practical example

Example

A team defines color.action.primary rather than scattering a particular blue hex value through web and mobile code. A dark theme remaps that semantic token to a lighter value, while automated contrast checks and component review catch combinations that no longer work.

06Where it breaks

Tokens do not guarantee coherent design or accessible color combinations. Too many layers can obscure what a value controls, while names tied to appearance become misleading. Tool interoperability also depends on which parts of a format each tool supports.

Common mistakes

  • Turning every numeric value into a token before a reuse case exists.
  • Naming semantic tokens after colors, such as blue-button.
  • Changing a foundational token without reviewing all aliases and components.
  • Letting design-tool variables and production tokens become separate sources of truth.

07Sources

  1. Design Tokens Community GroupDesign Tokens Community Group · Community specification overviewDesign Tokens Community Group
  2. Design Tokens Format Module 2025.10Design Tokens Community Group · Community group reportDesign Tokens Format Module 2025.10
  3. Design tokensU.S. Web Design System · Design system guidanceDesign tokens
View saved topics

Start typing to search titles, definitions, categories, and frameworks.