Design tokens 101: from hex codes to a shared language
Tokens are the smallest, most boring part of a design system, and the part that saves the most time. What they are, how to name them, and where to start.
A design token is a named decision. Instead of writing #FF6B3D in fifty places across your design files and codebase, you name that value once — say color.brand.500 — and reference the name everywhere. When the brand colour shifts, you change one value and the whole product follows. That sounds trivial until you have tried to rebrand a five-year-old app without tokens.
Three tiers of tokens
Most mature systems settle on a layered structure:
- Primitive (or global) tokens describe raw values with no meaning attached:
blue.600,space.4,radius.lg. - Semantic tokens describe intent:
color.text.primary,color.background.danger,space.inset.card. They point at primitives. - Component tokens are optional, scoped to one component:
button.primary.background. They point at semantic tokens.
The semantic layer is the important one. It lets you build a dark theme by remapping color.text.primary from a near-black primitive to a near-white one, without touching a single component.
Naming without tears
Good token names read from general to specific: category, property, variant, state. color.border.input.focus is long, but it is unambiguous and searchable. Avoid names that describe appearance in the semantic layer — color.lightGrey will become a lie the day you ship dark mode. And agree on the vocabulary early: is it “danger”, “error” or “critical”? Pick one.
What to tokenise first
Do not try to tokenise everything on day one. Start with colour, then spacing, then typography, then radius and shadow. Those five categories cover the vast majority of visual decisions in a typical interface. Motion durations and z-index layers can follow later.
Tokens in Figma and in code
Figma variables let you store primitives and semantic aliases directly in your files, complete with modes for light and dark themes. On the engineering side, tokens are usually stored as JSON and transformed into CSS custom properties, platform-specific constants for iOS and Android, or a theme object for a component library. The W3C Design Tokens Community Group has been working on a shared file format so that tools can exchange tokens without custom glue code, and many tools already support its draft structure.
Governance is the hard part
The technical setup takes days. Keeping tokens healthy takes discipline. Decide who can add a new token, document why each semantic token exists, and periodically hunt for hard-coded values that slipped through. A token nobody uses is noise; a value used in thirty places without a token is a future bug.
Start small, name things carefully, and treat your token file like any other piece of shared infrastructure. Your future self, mid-rebrand, will be grateful.
