Design Tokens
Design tokens are named, portable records of design decisions such as color roles, spacing, type, borders, and motion values.
Download Markdown (.md)Soroush’s Product Wiki · https://wiki.soroush.uk/topic/design-tokens/
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]
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
- List repeated decisions and distinguish raw values from semantic roles.
- Choose stable names based on purpose rather than a current visual appearance.
- Store values, types, descriptions, and aliases in a version-controlled source.
- Transform the source into platform formats and validate generated output.
- Use tokens in components instead of bypassing them with local values.
- Review changes for accessibility, theme coverage, and downstream breakage.
05A 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.
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
- Design Tokens Community GroupDesign Tokens Community Group · Community specification overviewDesign Tokens Community Group
- Design Tokens Format Module 2025.10Design Tokens Community Group · Community group reportDesign Tokens Format Module 2025.10
- Design tokensU.S. Web Design System · Design system guidanceDesign tokens