Design tokens that survive a rebrand

A brand refresh or full visual rebrand should be a single, clean Pull Request — not a 3-month engineering migration nightmare across hundreds of UI components. That speed is only possible if your frontend codebase abides by one strict rule: no component ever references a literal hex value or raw scale color directly.

Primitive, semantic, component

To build a design token system that effortlessly scales and survives rebrands, structure your token architecture into three distinct, hierarchical tiers:

• Primitive tokens (Raw Values) — Direct scale values such as red-500, slate-900, or blue-600. These define your base palette and should never be imported directly inside component markup.
• Semantic tokens (Intent) — Abstract tokens that express design purpose, such as --primary, --surface, --muted-foreground, or --border-danger. They map directly to primitive values.
• Component-level tokens (Overrides) — Specific scoped tokens reserved for complex UI elements where a component genuinely requires custom behavior (e.g., --button-primary-bg).

:root {
  /* Semantic Tokens (Intent) using OKLCH color space */
  --primary: oklch(0.59 0.21 25);
  --surface: oklch(1 0 0);
  --muted-foreground: oklch(0.52 0.012 18);
}

@theme inline {
  /* Mapping tokens to utility classes (Tailwind v4 style) */
  --color-primary: var(--primary);
  --color-surface: var(--surface);
}

By binding your components strictly to semantic CSS variables or utility classes (bg-primary, text-muted-foreground), swapping out an entire color palette or enabling Dark Mode requires updating a few root variable declarations rather than refactoring thousands of component files.

Use OKLCH so lightness is honest

Legacy color formats like HSL and HEX fail at human perceptual uniformity. For example, pure yellow (hsl(60, 100%, 50%)) looks significantly brighter to the human eye than pure blue (hsl(240, 100%, 50%)), despite sharing the exact same HSL lightness percentage.

Switching your color tokens to the OKLCH color space fixes this fundamental flaw:

• Perceptual lightness matching — An OKLCH lightness value of 0.7 feels visually consistent across every hue from red to cyan.
• Algorithmic hover & focus states — Instead of hand-picking arbitrary hex codes for interactive states, generating WCAG-compliant hover states becomes predictable math (e.g., subtracting 0.08 from lightness).
• Wider gamut support — Unlocks vibrant Display P3 colors on modern monitors that standard sRGB hex codes cannot reach.

A hardcoded hex value inside a component is a silent promise that your brand will never change.