# Design Tokens

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

- Type: artifact
- Domain: Experience & interface
- Level: Intermediate
- Last reviewed: 2026-09-21
- Original: [Soroush’s Product Wiki](<https://wiki.soroush.uk/topic/design-tokens/>)

## What 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.

## Why 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.

## When 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.

## How 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.

## A practical 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.

## Where 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.

## Visualization

[View the visualization on the website](<https://wiki.soroush.uk/topic/design-tokens/#visualization-design-tokens>)

## Sources

1. [Design Tokens Community Group](<https://www.designtokens.org/>) — Design Tokens Community Group · Community specification overview
2. [Design Tokens Format Module 2025.10](<https://www.designtokens.org/tr/2025.10/format/>) — Design Tokens Community Group · Community group report
3. [Design tokens](<https://designsystem.digital.gov/design-tokens/>) — U.S. Web Design System · Design system guidance

## Related topics

- [Design System](<https://wiki.soroush.uk/topic/design-system/>)
- [Color Contrast](<https://wiki.soroush.uk/topic/color-contrast/>)
- [Component Library](<https://wiki.soroush.uk/topic/component-library/>)
