Design Tokens
The layered token architecture that connects Figma designs to production code.
Design tokens are the single source of truth for visual style. They flow from Figma exports through a build pipeline into CSS custom properties.
Token layers
The system uses four layers. Each layer references only the layer above it.
| Layer | Purpose | Example |
|---|---|---|
| Core (Primitives) | Raw values — spacing, radii, borders, typography | --size-spacing-200 |
| Color Modes | Light and dark color palettes, no semantics | --color-blue-500 |
| Semantics (Roles) | Intent-based names for surfaces, text, borders | --color-text-default |
| Components (UI) | Component-specific tokens referencing semantics | --button-solid-background-default |
Naming convention
- Component tokens:
--component-variant-part-property-state - Semantic tokens: role-based (e.g.
--color-text-default,--color-fill-brand) - States are always the last segment:
default,hover,active,focus,disabled
Pipeline
Figma exports JSON token files to figma/exports/. The build step
npm run tokens:generate transforms them into CSS custom properties in dist/tokens/css/.
Generated files in dist/ are never edited directly.
Brand and mode
Brand and color mode are orthogonal concerns controlled by data-brand and
data-mode attributes on the root element. Switching either attribute swaps the
active token values without changing component markup.
Rules
- Components reference only Semantic or Core tokens — never raw color values.
- Never mix token layers in a single declaration.
- Never hardcode hex, rgb, or hsl values in component CSS.
- Always use
var(--...)for every visual property.
Reference
- All Tokens — complete tabular index of all generated tokens