Design tokens: the atoms

The foundation of any modern design system is design tokens — the atomic, named design decisions that everything else is built from. Get tokens right and consistency, theming, and design-to-code all fall into place. This lesson covers design tokens: the atoms. Let's start at the atomic level. Let's master tokens.

What design tokens are

DESIGN TOKENS = the smallest, named, reusable design decisions — the ATOMS of a design system.
Instead of a raw value (#2563EB, 16px), you name it (color-primary, spacing-4) + use the NAME
everywhere. A token = a NAME + a VALUE, stored once + referenced everywhere.

EXAMPLES:
- color-primary = #2563EB;  color-text = #1A1A2E;  color-surface = #FFFFFF;  color-error = #DC2626
- spacing-4 = 16px;  spacing-2 = 8px;  radius-md = 8px
- font-size-body = 16px;  font-weight-bold = 700;  line-height-normal = 1.5
- shadow-1 = 0 1px 3px rgba(0,0,0,.1);  duration-fast = 150ms

WHAT KINDS OF TOKENS (categories):
- COLOUR (brand, neutral scale, semantic: text/surface/border/success/error), TYPOGRAPHY (font
  family/size/weight/line-height/letter-spacing), SPACING (the spacing scale), SIZING, RADIUS (corner
  rounding), BORDER (width), SHADOW/ELEVATION, MOTION (durations/easings), Z-INDEX, opacity, + more.
Everything visual can be a token.

WHY TOKENS ARE POWERFUL (they solve the core problems):
- SINGLE SOURCE OF TRUTH — the value lives in ONE place (the token). Change it once -> everywhere
  using it updates. The atomic "update once" power.
- CONSISTENCY — everyone uses color-primary, not their own hex. No drift, no 20-different-blues.
- THEMING — swap a set of token VALUES (light/dark, brand A/brand B) + the whole product re-themes
  (because everything references tokens, not hard-coded values). Tokens make theming possible.
- DESIGN <-> CODE BRIDGE — the SAME named tokens exist in design (Figma variables/styles) + in code
  (CSS variables / a tokens file). Designers + devs share one vocabulary + one source of values. A
  token changed in design maps to code.
- SCALE + MAINTAINABILITY — systematic values, not magic numbers. Easy to reason about + change.
Tokens are why modern design systems are consistent, themeable, + design-code aligned.

Design tokens are the smallest, named, reusable design decisions — the atoms of a design system — instead of a raw value (#2563EB, 16px), you name it (color-primary, spacing-4) and use the name everywhere — a token = a name + a value, stored once + referenced everywhere. Examples: color-primary = #2563EB; color-text = #1A1A2E; color-error = #DC2626; spacing-4 = 16px; spacing-2 = 8px; radius-md = 8px; font-size-body = 16px; font-weight-bold = 700; line-height-normal = 1.5; shadow-1 = 0 1px 3px rgba(0,0,0,.1); duration-fast = 150ms. What kinds of tokens (categories): colour (brand, neutral scale, semantic: text/surface/border/success/error), typography (font family/size/weight/line-height/letter-spacing), spacing (the spacing scale), sizing, radius (corner rounding), border (width), shadow/elevation, motion (durations/easings), z-index, opacity — everything visual can be a token. Why tokens are powerful (they solve the core problems): single source of truth (the value lives in one place — the token — change it once → everywhere using it updates — the atomic "update once" power); consistency (everyone uses color-primary, not their own hex — no drift, no 20-different-blues); theming (swap a set of token values — light/dark, brand A/brand B — and the whole product re-themes, because everything references tokens, not hard-coded values — tokens make theming possible); design ↔ code bridge (the same named tokens exist in design — Figma variables/styles — and in code — CSS variables / a tokens file — designers + devs share one vocabulary + one source of values; a token changed in design maps to code); and scale + maintainability (systematic values, not magic numbers — easy to reason about + change). Tokens are why modern design systems are consistent, themeable, and design-code aligned.

Tiers of tokens and using them well

TIERED / SEMANTIC TOKENS (the pro structure — layers of tokens referencing each other):
- 1. PRIMITIVE / GLOBAL tokens (the raw palette) — the base values: blue-500 = #2563EB, gray-100,
     gray-900, red-500, size-16. Just the raw options; no meaning/usage attached.
- 2. SEMANTIC / ALIAS tokens (meaning) — reference primitives + describe ROLE/intent:
     color-text-primary = gray-900; color-action-primary = blue-500; color-surface = white;
     color-border = gray-200; color-danger = red-500. These say WHAT a colour is FOR, not which hue.
- 3. COMPONENT tokens (optional, most specific) — per-component: button-primary-bg =
     color-action-primary; card-padding = spacing-4. Map semantics to specific components.
WHY TIERS: you use SEMANTIC tokens in designs (color-text-primary), which point to primitives. To
re-theme (dark mode), you remap the semantic tokens to different primitives (color-surface = gray-900
in dark) — components don't change, only the token mapping. Semantic tokens enable theming +
meaningful, maintainable naming. (naming/tiers/themes lesson goes deeper.)

DOING IT WELL:
- USE SEMANTIC TOKENS in components/designs (by ROLE: text-primary, surface, action) — NOT raw
  primitives or hex. So intent is clear + theming works.
- NAME BY ROLE/MEANING, not appearance — "color-danger" not "color-red" (red might change; "danger"
  is stable). "spacing-4" or "space-md", not "16px". Semantic, systematic names.
- BUILD ON SCALES — colour scales, a spacing scale, a type scale (next lessons) — tokens from
  systematic scales, not random values.
- KEEP TOKENS THE SINGLE SOURCE — never hard-code a raw value in a component; always reference a
  token. If you need a new value, add a token.
- KEEP IT LEAN + ORGANISED — enough tokens to cover needs, well-categorised + named. Not thousands of
  one-offs.
- SYNC DESIGN + CODE — the same tokens in Figma (variables) + code (a tokens file / CSS vars), ideally
  via a tokens pipeline (tooling lesson).

THE PRINCIPLE: DESIGN TOKENS are the named, atomic design decisions (color-primary, spacing-4) —
stored ONCE, referenced everywhere — giving a SINGLE SOURCE OF TRUTH, CONSISTENCY, THEMING, + a
design<->code BRIDGE. Use TIERED tokens (primitive -> SEMANTIC -> component), name by ROLE/meaning,
build on scales, + always reference tokens (never hard-code). Tokens are the atomic foundation
everything else in the system is built from. Get the atoms right.

Tiered / semantic tokens (the pro structure — layers of tokens referencing each other): 1. primitive / global tokens (the raw palette) — the base values: blue-500 = #2563EB, gray-100, gray-900, red-500, size-16 — just the raw options; no meaning/usage attached; 2. semantic / alias tokens (meaning) — reference primitives + describe role/intent: color-text-primary = gray-900; color-action-primary = blue-500; color-surface = white; color-border = gray-200; color-danger = red-500 — these say what a colour is for, not which hue; 3. component tokens (optional, most specific) — per-component: button-primary-bg = color-action-primary; card-padding = spacing-4. Why tiers: you use semantic tokens in designs (color-text-primary), which point to primitives — to re-theme (dark mode), you remap the semantic tokens to different primitives (color-surface = gray-900 in dark) — components don't change, only the token mapping — semantic tokens enable theming + meaningful, maintainable naming. Doing it well: use semantic tokens in components/designs (by role: text-primary, surface, action — not raw primitives or hex — so intent is clear + theming works); name by role/meaning, not appearance ("color-danger" not "color-red" — red might change; "danger" is stable; "spacing-4" or "space-md", not "16px"); build on scales (colour scales, a spacing scale, a type scale — tokens from systematic scales, not random values); keep tokens the single source (never hard-code a raw value in a component; always reference a token — if you need a new value, add a token); keep it lean + organised (enough tokens, well-categorised + named — not thousands of one-offs); and sync design + code (the same tokens in Figma variables + code — a tokens file / CSS vars — ideally via a tokens pipeline). The principle: design tokens are the named, atomic design decisions (color-primary, spacing-4) — stored once, referenced everywhere — giving a single source of truth, consistency, theming, and a design↔code bridge; use tiered tokens (primitive → semantic → component), name by role/meaning, build on scales, and always reference tokens (never hard-code) — tokens are the atomic foundation everything else is built from.

The mistake beginners make

The first mistake is hard-coding raw values — using #2563EB / 16px directly instead of tokens, losing single-source + theming; always reference a token. The second mistake is no semantic layer — using only raw primitives (color-blue-500) in components, so you can't theme + intent is unclear; use semantic tokens (color-action-primary). The third mistake is naming by appearance — "color-red" instead of "color-danger", breaking when the hue changes; name by role/meaning. And random values (no scales) — arbitrary token values with no systematic scale; build tokens on scales. And design + code out of sync — different values in Figma vs code; sync them (one source). Use tokens not raw values, add a semantic layer, name by role, build on scales, and sync design + code.

Your turn

---

Your turn

1. Define tokens: understand a design token as a NAME + a VALUE (color-primary = #2563EB, spacing-4 = 16px) stored once and referenced everywhere - the atomic, named design decisions everything is built from.
2. Cover the categories: create tokens for colour (brand/neutral/semantic), typography (size/weight/line-height), spacing, radius, border, shadow/elevation, and motion (durations/easings).
3. Use tiers: build PRIMITIVE tokens (raw palette: blue-500, gray-900), SEMANTIC/alias tokens that reference them by ROLE (color-text-primary = gray-900, color-action-primary = blue-500), and optionally COMPONENT tokens (button-primary-bg = color-action-primary).
4. Use semantic tokens + name by role: in components/designs, use semantic tokens (text-primary/surface/action) not raw hex, and name by MEANING ('color-danger' not 'color-red', 'spacing-4' not '16px') so intent is clear and theming works.
5. Sync + keep it the single source: never hard-code a raw value (always reference a token - add one if needed), build tokens on systematic scales, and keep the same tokens in design (Figma variables) + code (CSS variables / a tokens file).

Key points

• DESIGN TOKENS = the smallest, NAMED, reusable design decisions — the ATOMS of a design system. A token = a NAME + a VALUE (color-primary = #2563EB; spacing-4 = 16px), stored ONCE + referenced everywhere. Categories: colour, typography, spacing, sizing, radius, border, shadow/elevation, motion, z-index, opacity.
• Why powerful: SINGLE SOURCE OF TRUTH (change once -> everywhere updates), CONSISTENCY (everyone uses color-primary not their own hex), THEMING (swap token VALUES -> whole product re-themes — light/dark/brand), DESIGN<->CODE BRIDGE (same named tokens in Figma variables + CSS variables/a tokens file), and SCALE/maintainability (systematic values, not magic numbers).
• TIERED tokens (the pro structure): 1) PRIMITIVE/global (raw palette — blue-500, gray-900; no meaning), 2) SEMANTIC/alias (reference primitives by ROLE — color-text-primary = gray-900, color-action-primary = blue-500 — WHAT it's for), 3) COMPONENT (most specific — button-primary-bg = color-action-primary). Use SEMANTIC in designs; RE-THEME by remapping semantics to different primitives.
• Do it well: use SEMANTIC tokens in components (not raw primitives/hex), NAME BY ROLE/meaning ('color-danger' not 'color-red'; 'spacing-4' not '16px'), build on SCALES, keep tokens the SINGLE SOURCE (never hard-code — add a token), keep it lean/organised, and SYNC design + code (a tokens pipeline).
• The mistakes: hard-coding raw values (use tokens), no semantic layer (can't theme / unclear intent), naming by appearance ('color-red' breaks when the hue changes), random values (build on scales), and design + code out of sync.