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.
| Role | Light | Dark |
|---|---|---|
| Surface | white | neutral-900 |
| Body text | neutral-950 | neutral-100 |
| Link | blue-700 | blue-300 |
| Border | neutral-300 | neutral-700 |
| Focus | blue-700 | blue-300 |
| Error | red-700 | red-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.
: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); }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.
@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);
}{
"$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}" }
}
}Build a useful token set
- Name primitives by scale and family, not component: `blue-600`, `space-4`, `shadow-2`.
- Define semantic roles around product language: `surface`, `text-muted`, `focus-ring`, `danger`.
- Assign ownership and review rules so tokens remain stable shared contracts.
- Introduce component tokens only when a real component needs a distinct contract or lifecycle.
- 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.