Design Tokens: The Practical Guide
Design tokens are design decisions stored as data — named values for color, type, spacing and radius that live in one file and export to every tool that needs them: CSS, Tailwind, Figma, native code. They are the layer that keeps a design system honest: when design files and stylesheets read the same source, they cannot drift apart. This hub collects our guides on the format, the naming, and the workflow; the one-screen version is one token source rendered as four exports.
The idea in one move
A token replaces a value with a reference. Instead of #2563eb appearing in
forty stylesheets and thirty Figma fills, brand-600 appears everywhere and
resolves to the value in exactly one place. The intuitive gain is that a
name carries intent where a value cannot: #2563eb says nothing about when
to use it, brand-600 does — and a change made behind a name is made once,
reviewed once, and trusted everywhere the name appears. Every hard question
in token work — naming, layering, theming, migration — is a variation on
making that one move at scale, and the guides here take them in turn.
What are design tokens is
the ground-floor introduction;
design tokens vs CSS variables
untangles the distinction the terminology blurs — custom properties are one
export of a token file, not the thing itself.
The format that won
The DTCG format — the W3C community group’s JSON — is the closest thing
tokens have to a standard: $value and $type per token, references
between tokens, composite types for typography and shadows. Our guides
cover reading it, writing it, and the round-trip discipline that lets a
tokens file be edited by tools without losing what humans added:
the DTCG format explained walks a real
file line by line,
importing existing tokens
covers the round trip itself, and
Style Dictionary vs direct export
weighs when a transform pipeline earns its place over writing the exports
directly.
Naming and layers — where token systems stand or fall
Most token systems fail socially before they fail technically: names nobody
can predict, layers nobody respects. The load-bearing decision is the split
into primitive, semantic and component
layers — primitives hold values
(brand-600), semantics hold roles (text-primary), components consume
the roles — because that indirection is what lets a rebrand or a theme
switch re-point roles without touching a single component.
Naming conventions make the
layers legible, and
five token anti-patterns
catalogs the ways they erode in practice. From there the workflow guides
take over: one source of
truth describes the
loop end to end,
reviewing token changes in git makes
design decisions diffable like any other code, and
how developers actually consume tokens
is the reality check from the receiving end. For organizations still
keeping a PDF style guide,
design tokens vs style guide
lays out what each can do that the other cannot.
Where tokens meet the rest of the system
Tokens carry the values other systems decide: the scale mathematics from type scales and spacing, the derived roles from color scales, the theme pairs from dark mode. The token layer is where all of it becomes shippable — which is why this hub reads best after the others and gets referenced by all of them. It is also the layer Scale Composer writes: every scale decision made there — color, typography, spacing, grid — lands in one DTCG file, ready for the exports this hub describes.
Guides in this hub
- Design Token Naming Conventions
Design token naming conventions: the category-concept-variant-state anatomy, five rules that survive rebrands, and the micro-decisions to settle once.
- Design Tokens vs CSS Variables: What's the Difference?
Design tokens vs CSS variables: tokens are the tool-neutral source, custom properties one generated export. How they relate and when variables are enough.
- Design Tokens vs Style Guide
Design tokens vs style guide: the guide carries intent and usage for humans, tokens carry the values for machines — and how the two compose without drift.
- Five Token Anti-Patterns
Design tokens best practices taught by failure: five anti-patterns — sprawl, layer skipping, escape hatches, appearance names and write-only files.
- How Developers Actually Consume Tokens
Design tokens handoff from the developer's chair: CSS custom properties, Tailwind themes, Figma Variables — and why the token file should be treated as an API.
- Importing Existing Tokens Without Losing Anything
How to import design tokens without losing hand-built work: the round-trip contract, a five-minute fixpoint test, and what to audit before trusting a tool.
- One Source of Truth: The Token Workflow
Design tokens single source of truth: the five-step token workflow — decide, export, commit, consume, change — and the failure each skipped step lets back in.
- Primitive, Semantic, Component: The Three Token Layers
Semantic design tokens sit between primitives and components. How the three-layer architecture turns rebrands, themes and exceptions into one-layer changes.
- Reviewing Token Changes in Git
Design tokens version control: why token changes belong in git, how to read a six-line token diff, and the review checklist that catches silent design changes.
- Style Dictionary vs Direct Export
Style Dictionary vs direct export: what a token transform pipeline buys, when built-in exports cover you, and how a standard DTCG file keeps both roads open.
- The DTCG Token Format Explained
The DTCG format explained: $value and $type on every token, groups, references and composite types — plus what a real generated design tokens file contains.
- What Are Design Tokens?
What are design tokens? Named design decisions — brand-600 holds one exact blue — composed through references and exported to CSS, Figma and native code.
Feel the single source
The argument for tokens compresses into one interaction: change one scale parameter and watch every export update — DTCG, CSS custom properties, Tailwind theme and Figma Variables moving together, because all four are read from the same decisions. That simultaneity is what a token layer buys; everything else is implementation.