CSS and design tokens pipelines

Design token pipelines – how colour, spacing, and typography tokens move from design tools into CSS custom properties, stay in sync, and do not become a second codebase nobody dares touch.

What tokens are

A token is a named design decision: color.brand.primary, space.4, radius.md. The name is stable; the value can change per theme or brand. CSS exposes them as custom properties on :root or a theme scope.

:root {
  --color-brand: oklch(0.55 0.18 250);
  --color-text: oklch(0.2 0.02 250);
  --color-surface: oklch(0.99 0.005 250);
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-4: 1rem;
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
}

Tiered tokens

Three tiers keep themes manageable:

• Global / primitive – raw palette, base spacing unit.
• Semantic – --color-text-muted, --color-border-subtle (meaning, not hue).
• Component – --button-bg aliases a semantic token; rarely a raw hex.

:root {
  --gray-9: oklch(0.35 0.02 250);
  --gray-3: oklch(0.92 0.01 250);

  --color-text-muted: var(--gray-9);
  --color-border: var(--gray-3);

  --button-bg: var(--color-brand);
  --button-fg: var(--color-brand-on);
}

Dark mode swaps semantic mappings, not every component rule.

Design tool to CSS

Common flow: Figma variables or Tokens Studio export JSON, a build step transforms JSON to CSS, the app imports one tokens.css. Tools like Style Dictionary, Terrazzo, or a small Node script map nested JSON to flat custom properties:

/* generated/tokens.css - do not edit by hand */
:root {
  --color-brand-primary: #2563eb;
  --color-brand-primary-hover: #1d4ed8;
  --space-inline-md: 1rem;
  --font-size-body: 1rem;
}

Hand-editing generated files guarantees drift. Change the source JSON or Figma library, regenerate, commit the output.

Multi-brand and themes

[data-theme="light"] {
  --color-surface: oklch(0.99 0.005 250);
  --color-text: oklch(0.2 0.02 250);
}

[data-theme="dark"] {
  --color-surface: oklch(0.18 0.02 250);
  --color-text: oklch(0.95 0.01 250);
}

[data-brand="acme"] {
  --color-brand: oklch(0.5 0.2 30);
}

Theme scopes override semantic tokens. Components keep using var(--color-surface) – no .dark .card forks.

Governance

• One owner for token names – renames break consumers.
• Deprecate before delete; alias old names for a release cycle.
• Document which tokens are public API vs internal primitives.
• CI diff on generated CSS catches accidental manual edits.

The SCSS intermediate tutorials covers token maps in Sass. Here the output is plain CSS custom properties – usable without a preprocessor.

The next tutorial covers critical CSS and delivery strategies – what to inline, what to defer, and how first paint stays fast.