Design Tokens: How to Build a Scalable Design System from Scratch

What Are Design Tokens?

Design tokens are the smallest indivisible units of a design system — the named variables that store visual design decisions. Instead of hardcoding #1A1A2E across 200 components, you define color.text.primary = #1A1A2E once and reference the token everywhere.

When the primary text color changes (brand refresh, dark mode), you update one value. Every component in every product surface updates automatically.

The Three-Tier Token Architecture

The most robust token systems use a three-tier hierarchy: Global → Alias → Component.

Tier 1: Global (Primitive) Tokens

Global tokens are raw values with no semantic meaning. They are never used directly in components.

color.green.500 = #22c55e
color.green.600 = #16a34a
color.slate.900 = #0f172a
spacing.4 = 16px
spacing.8 = 32px
font.size.base = 16px
font.size.lg = 18px

Tier 2: Alias (Semantic) Tokens

Alias tokens map semantic meaning to global values. These are what you use in components.

color.text.primary = {color.slate.900}
color.text.success = {color.green.600}
color.background.page = #ffffff
space.component.padding-md = {spacing.4}
type.body.size = {font.size.base}

Tier 3: Component Tokens

Component tokens are scoped to a specific component. They reference alias tokens and allow per-component overrides without breaking the global system.

button.primary.background = {color.brand.primary}
button.primary.text = {color.text.inverse}
button.primary.padding-x = {space.component.padding-md}
input.border.color = {color.border.default}
input.border.color.focus = {color.brand.primary}

Syncing Figma and Code with Tokens

The holy grail of design systems is a single source of truth that works in both Figma and code. The tooling has matured significantly:

• Figma Variables — Figma's native token system (released 2023). Supports modes (light/dark), string, color, number, and boolean types.
• Style Dictionary — Amazon's open-source token transformer. Takes a JSON token file and outputs CSS custom properties, SCSS variables, iOS Swift, Android XML — from one source.
• Token Studio (Figma plugin) — Syncs tokens between Figma and a JSON file in your Git repo. Change a token in Figma → PR is created → CSS variables update automatically.

Dark Mode With Tokens

Dark mode is trivial if your tokens are well-structured. You define two modes for your alias tokens:

/* Light mode */
[data-theme="light"] {
  --color-text-primary: #0f172a;
  --color-background-page: #ffffff;
  --color-border-default: #e2e8f0;
}

/* Dark mode */
[data-theme="dark"] {
  --color-text-primary: #f1f5f9;
  --color-background-page: #0f172a;
  --color-border-default: #334155;
}

Components that use semantic tokens (not raw color values) automatically adapt to both modes with zero additional work.

Common Token Architecture Mistakes

• Using global tokens in components directly — Using color.green.500 in a button component means you lose the semantic layer. When "success" becomes a different shade of green, nothing updates automatically.
• Too many token tiers — Global → Alias → Component is sufficient for 99% of products. Adding a fourth tier creates complexity without benefit.
• Inconsistent naming conventions — Pick a convention (kebab-case, dot.notation, or camelCase) and enforce it across both Figma and code.
• Tokens without documentation — A token named color.surface.3 tells nobody anything. Document the intent: "Used for elevated card surfaces in the dashboard layout."