Design Tokens

Shared design values belong in one authoritative place — not scattered magic numbers.

01 — Purpose

One source of truth for design values

Design tokens are shared values — colour, spacing, type — stored once and reused everywhere.

Magic numbers scattered across CSS and JavaScript drift apart. Tokens give teams one authoritative place to update spacing scale, brand colour, or motion duration — and see the change propagate consistently.

On LSCSS projects, tokens live in the settings layer — see CSS standard for naming rules.

02 — Principles

Semantic, central, consistent

Shared values should exist in one authoritative location.

  • semantic names — --space-m, --color-accent — not --blue-47 tied to today's brand
  • central management — settings layer, not sprinkled in components
  • cross-system consistency — same tokens in CSS; export to JS only when needed

03 — Practice

Common token categories

Start with what changes together.

  • colour — text, surface, border, accent, state colours
  • spacing — stepped scale used for margin, padding, gap
  • typography — family, size scale, line height, weight tokens
  • radii, shadows, motion duration and easing
  • use tokens in components — font-weight: var(--font-weight-bold) not raw 700 where the project standardises weights 
:root {
  --space-m: 1rem;
  --color-accent: #ff2d8a;
  --font-weight-bold: 700;
}

.card {
  padding: var(--space-m);
  border-color: var(--color-accent);
}

04 — Avoid

Token anti-patterns

Tokens should simplify — not multiply indirection for its own sake.

  • magic numbers beside tokens — padding: 13px next to a spacing scale
  • duplicate tokens with different names for the same value
  • inconsistent spacing systems — mixing rem, px, and arbitrary gaps
  • presentation names in tokens — --hero-pink breaks when brand shifts

05 — Close

Consistency and maintainability

If a global rebrand takes a find-and-replace on six files, your tokens are working.

Audit new UI for hard-coded values before merge. Tokens are a gate, not a migration you finish someday.

Related: cascade layers, CSS architecture, font loading.