Design Tokens & CSS Variables

Design tokens are the atomic visual building blocks of a design system — standardizing values for colors, typography scale, spacing grids, border radii, and shadows across platforms. Storing design tokens as CSS variables (custom properties) enables runtime theme swapping without recompiling CSS stylesheets.

Modern design systems use HSL or OKLCH color spaces for tokens (--primary: 222.2 47.4% 11.2%). By referencing CSS variables in utility classes (e.g., bg-background text-foreground), components automatically adapt when dark mode classes or theme overrides modify the variable definitions.

Before

Hard-Coded Hex Palette (Maintenance Nightmare)

1/* ❌ Hard-coded hex values break theme switching */2.button {3  background-color: #3b82f6;4  color: #ffffff;5  border-radius: 6px;6}

After

Design Token Variable System

1:root {2  --primary: 221.2 83.2% 53.3%;3  --primary-foreground: 210 40% 98%;4  --radius: 0.5rem;5}6 7.dark {8  --primary: 217.2 91.2% 59.8%;9  --primary-foreground: 222.2 47.4% 11.2%;10}11 12.button {13  background-color: hsl(var(--primary));14  color: hsl(var(--primary-foreground));15  border-radius: var(--radius);16}

Exercise

Define a set of CSS color tokens for background, foreground, primary, and accent in both light and dark mode classes.

Check your understanding

Why use HSL or OKLCH color definitions for CSS variables in Tailwind?Show answerHide answer
Answer
They allow utility classes to easily append opacity modifiers (e.g., bg-primary/80) dynamically.
What is the primary benefit of design tokens over hard-coded CSS values?Show answerHide answer
Answer
Tokens centralize design decisions so updating a single variable updates the entire application UI instantly.