What is Design Tokens?
Named, platform-neutral values for design decisions such as colors, spacing, and type, stored once and transformed into code for every platform.
Definition
A design token gives a design decision a name and a single source of truth. Instead of hard-coding #0055FF in a stylesheet, an iOS file, and a Figma style, a team defines a token such as color.action.primary and generates each platform's representation from it: a CSS custom property, a Swift constant, an Android resource, a Tailwind theme entry. Changing the token and rebuilding updates every product consistently. Tokens are usually layered. Primitive (or reference) tokens hold raw palette and scale values, like blue.500 or space.4. Semantic tokens describe intent and point to primitives, like color.text.danger referencing red.600. Component tokens, like button.background, reference semantic ones. Because each layer is an alias of the one below, theming becomes a matter of swapping which primitives the semantic layer points to: dark mode, high contrast, or a white-label brand is another token set, not a forked stylesheet. In October 2025 the W3C Design Tokens Community Group published the first stable version of its format, Design Tokens Format Module 2025.10. It is a Community Group report, not a W3C Standard, but it gives tools a shared JSON format: a token is an object with a $value and optional $type and $description, aliases use curly-brace references like "{color.blue.500}", groups can inherit with $extends, and files use the .tokens or .tokens.json extension. Defined types include color, dimension, fontFamily, fontWeight, duration, cubicBezier, number, and composites such as shadow, border, gradient, and typography. Style Dictionary, Tokens Studio, and Terrazzo are common tools for authoring and transforming tokens.
When to Use Design Tokens
Tokens pay off when the same visual language must stay consistent across several codebases or platforms, when you support multiple themes or brands, or when designers and developers keep drifting apart. A single small web app with one theme can get most of the benefit from CSS custom properties alone. Adopt the DTCG format for new token files so they stay portable between tools. Name semantic tokens by purpose (surface, text-muted, border-focus) rather than by appearance (light-gray), or the names become wrong after the next redesign. Keep the primitive layer out of component code so themes can be swapped. Expect some ongoing work: tokens need ownership, review, and a build step in CI.
Design Tokens in Practice
- A DTCG-format token file with primitives and a semantic alias: { "color": { "$type": "color", "blue-600": { "$value": "#1d4ed8" }, "action-primary": { "$value": "{color.blue-600}" } } }
- The CSS a build tool generates from those tokens; components use only the semantic variable: :root { --color-blue-600: #1d4ed8; --color-action-primary: var(--color-blue-600); } .btn-primary { background: var(--color-action-primary); }
- Dark mode as an alternate token set: a [data-theme="dark"] block reassigns --color-surface and --color-text, and no component CSS changes.
- A company with web, iOS, and Android apps runs Style Dictionary in CI on every token change, publishing an npm package, a Swift package, and an Android resource file from one tokens repository.
Common Mistakes
- Naming tokens after their value (blue, gray-light) at the semantic layer. A rebrand then leaves names that lie; name semantic tokens by role.
- Letting components reference primitive tokens directly, which makes theming impossible without touching component code. Route through semantic tokens.
- Creating a token for every one-off value, producing hundreds of near-duplicates. Tokenize repeated decisions and keep the scale small.
- Treating the DTCG format as a finished W3C Standard. It is a stable Community Group report; check which version your tools support.
- Editing generated CSS or platform files by hand. Changes are lost on the next build; edit the token source.