Design systems guide

Design Tokens: From Primitives to Interface Roles

A token system names reusable decisions, connects design intent to implementation, and makes themes consistent across components.

Primitive and semantic tokens

Primitive tokens describe raw values such as a blue shade, a spacing step, or a shadow. Semantic tokens assign those values to roles such as surface, body text, link, focus, and error. Components should normally consume semantic roles; the theme maps those roles to primitives.

RoleLightDark
Surfacewhiteneutral-900
Body textneutral-950neutral-100
Linkblue-700blue-300
Borderneutral-300neutral-700
Focusblue-700blue-300
Errorred-700red-300

A themed settings card

This small component uses semantic roles for text and surface while its primitive spacing, type, and elevation choices remain reusable. Both themes use readable text; validate actual color pairs with the Color Contrast Checker when available in the app.

css
:root {
  --blue-600: oklch(0.52 0.18 255);
  --gray-950: oklch(0.15 0.02 255);
  --space-4: 1rem;
  --space-6: 1.5rem;
  --type-step-0: 1rem;
  --type-step-1: 1.25rem;
  --shadow-card: 0 12px 30px rgb(15 23 42 / 0.14);
  --color-surface: white;
  --color-text: var(--gray-950);
  --color-link: var(--blue-600);
}
[data-theme="dark"] {
  --color-surface: oklch(0.19 0.02 255);
  --color-text: oklch(0.94 0.01 255);
  --color-link: oklch(0.78 0.12 255);
}
.settings-card { color: var(--color-text); background: var(--color-surface); padding: var(--space-6); border-radius: 1rem; box-shadow: var(--shadow-card); }
.settings-card h2 { font-size: var(--type-step-1); }
.settings-card a { color: var(--color-link); }

Account settings

Manage your profile and notification preferences.

Review preferences

Export to your stack

CSS variables are a platform-neutral runtime layer. Tailwind’s `@theme` maps selected primitives into utilities. The JSON below illustrates the Design Tokens Community Group format, including typed values and aliases; validate against the current official format before adopting it.

css
@theme {
  --color-brand: oklch(0.52 0.18 255);
  --font-size-base: 1rem;
  --spacing-4: 1rem;
  --spacing-6: 1.5rem;
  --shadow-card: 0 12px 30px rgb(15 23 42 / 0.14);
}
json
{
  "$schema": "https://design-tokens.github.io/community-group/format/",
  "color": {
    "neutral": { "0": { "$type": "color", "$value": "#FFFFFF" } },
    "brand": { "$type": "color", "$value": "oklch(0.52 0.18 255)" },
    "surface": { "$type": "color", "$value": "{color.neutral.0}" }
  },
  "space": { "6": { "$type": "dimension", "$value": "1.5rem" } },
  "semantic": {
    "link": { "$type": "color", "$value": "{color.brand}" }
  }
}

Design Tokens Community Group format specification

Build a useful token set

  1. Name primitives by scale and family, not component: `blue-600`, `space-4`, `shadow-2`.
  2. Define semantic roles around product language: `surface`, `text-muted`, `focus-ring`, `danger`.
  3. Assign ownership and review rules so tokens remain stable shared contracts.
  4. Introduce component tokens only when a real component needs a distinct contract or lifecycle.
  5. Test both themes, contrast, zoom, and states before treating token names as accessible outcomes.

Generate primitives with the OKLCH Palette, a type scale with Modular Type Scale, fluid spacing with CSS Clamp, and elevation with Box Shadow.