Design tokens: --primary, --bg, --text, --border

A small token set covers 80% of UI

:root {
  /* Semantic tokens — what they're used FOR, not what they ARE */
  --bg: white;
  --surface: oklch(0.98 0 0);            /* card / panel background */
  --text: oklch(0.20 0 0);
  --text-muted: oklch(0.50 0 0);
  --border: oklch(0.90 0 0);
  --primary: oklch(0.66 0.18 252);
  --primary-fg: white;                    /* text color ON primary background */
  --danger: oklch(0.62 0.20 27);
  --success: oklch(0.66 0.16 145);
  --warning: oklch(0.78 0.14 75);
  --radius: 8px;
  --space-sm: 8px;
  --space-md: 16px;
  --space-lg: 24px;
}

Semantic > literal

Compare:

/* DON'T — name colors by what they are */
:root { --blue-500: oklch(0.66 0.18 252); }
.btn { background: var(--blue-500); }

/* DO — name colors by what they're FOR */
:root { --primary: oklch(0.66 0.18 252); }
.btn { background: var(--primary); }

When you rebrand from blue to green, "blue-500" becomes a misnomer. "primary" still makes sense — it just maps to a different OKLCH value.

You can have BOTH layers: literal scale (--blue-50 to --blue-900) PLUS semantic tokens (--primary maps to --blue-500). Tailwind's color system works this way.

Why these 10 tokens are enough

• bg + surface — page and panel backgrounds.
• text + text-muted + primary-fg — three text colors covers everything.
• border — separators, inputs, panels.
• primary + danger + success + warning — every UI state.
• radius + space-sm/md/lg — geometry.

Anything more is usually scope creep. Start here, add more only when you need them.