Design Tokens

Design tokens are the smallest building blocks of a design system. They are named values that store visual design decisions — colors, spacing, font sizes, border radii, shadows, and more. Instead of hardcoding #2563eb throughout your codebase, you reference --color-primary, making it trivial to update the value in one place and have it propagate everywhere.

Why Tokens Matter

Without tokens, design decisions are scattered across CSS files, component styles, and design tools. When your brand blue changes from #2563eb to #3b82f6, you are hunting through hundreds of files. With tokens, you change one variable.

Tokens also create a shared language between designers and developers. When a designer says "use spacing-md," both parties know exactly what that means — no ambiguity, no misinterpretation.

Types of Tokens

Color Tokens

Colors are usually the first tokens a team defines. Organize them in tiers:

:root {
  /* Primitive tokens — raw color values */
  --blue-500: #3b82f6;
  --blue-600: #2563eb;
  --blue-700: #1d4ed8;
  --gray-50: #f9fafb;
  --gray-900: #111827;

  /* Semantic tokens — what the color means */
  --color-primary: var(--blue-600);
  --color-primary-hover: var(--blue-700);
  --color-background: var(--gray-50);
  --color-text: var(--gray-900);
  --color-error: #dc2626;
  --color-success: #16a34a;
  --color-warning: #ca8a04;
}

Primitive tokens define the raw palette. Semantic tokens assign meaning. This separation lets you swap entire themes (like dark mode) by remapping semantic tokens to different primitives.

Spacing Tokens

A consistent spacing scale prevents the "4px here, 5px there, 7px somewhere else" chaos:

:root {
  --spacing-0: 0;
  --spacing-1: 0.25rem;  /* 4px */
  --spacing-2: 0.5rem;   /* 8px */
  --spacing-3: 0.75rem;  /* 12px */
  --spacing-4: 1rem;     /* 16px */
  --spacing-6: 1.5rem;   /* 24px */
  --spacing-8: 2rem;     /* 32px */
  --spacing-12: 3rem;    /* 48px */
  --spacing-16: 4rem;    /* 64px */
}

Most teams use a base-4 or base-8 scale. The key is picking one system and sticking with it.

Typography Tokens

Typography tokens cover font families, sizes, weights, and line heights:

:root {
  --font-family-sans: 'Inter', system-ui, sans-serif;
  --font-family-mono: 'JetBrains Mono', monospace;

  --font-size-xs: 0.75rem;
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-size-xl: 1.25rem;
  --font-size-2xl: 1.5rem;
  --font-size-3xl: 1.875rem;

  --line-height-tight: 1.25;
  --line-height-normal: 1.5;
  --line-height-relaxed: 1.75;

  --font-weight-normal: 400;
  --font-weight-medium: 500;
  --font-weight-bold: 700;
}

Other Common Tokens

• Border radius — --radius-sm, --radius-md, --radius-lg, --radius-full
• Shadows — --shadow-sm, --shadow-md, --shadow-lg
• Breakpoints — --breakpoint-sm: 640px, --breakpoint-md: 768px
• Z-index — --z-dropdown: 1000, --z-modal: 1050, --z-tooltip: 1100

Naming Conventions

Good token names are readable, predictable, and scalable. A common pattern is:

--{category}-{property}-{variant}-{state}

Examples:

• --color-primary — category: color, variant: primary
• --color-primary-hover — adds state
• --font-size-lg — category: font, property: size, variant: lg
• --spacing-4 — category: spacing, variant: 4

Avoid names tied to specific values like --blue-button or --padding-16px. If the blue changes to purple or the padding changes to 20px, the name becomes misleading.

Token Formats for Different Platforms

Design tokens can be expressed in multiple formats for different consumers:

{
  "color": {
    "primary": { "value": "#2563eb" },
    "error": { "value": "#dc2626" }
  },
  "spacing": {
    "sm": { "value": "0.5rem" },
    "md": { "value": "1rem" }
  }
}

Tools like Style Dictionary or Tokens Studio transform this single source into CSS custom properties, JavaScript objects, iOS Swift values, or Android XML resources. Define once, use everywhere.