Developer workflow · Tailwind CSS v4

Structuring color tokens in Tailwind CSS v4 (@theme)

Tailwind v4 moves color definitions out of JavaScript into standard CSS using @theme. Separating semantic role tokens from raw swatch scales keeps components resilient when a brand palette evolves.

Two-layer token architecture

@import "tailwindcss";

@theme {
  /* Layer 1: Semantic UI roles */
  --color-background: oklch(98.4% 0.003 248);
  --color-surface: #FFFFFF;
  --color-foreground: #0F172A;
  --color-primary: oklch(54.6% 0.215 262);
  --color-accent: oklch(71.5% 0.143 215);

  /* Layer 2: Tonal scale for borders, badges, and hover states */
  --color-brand-50: #EFF6FF;
  --color-brand-500: #2563EB;
  --color-brand-900: #1E3A8A;
}

Components reference bg-surface, text-foreground, and bg-primary directly, while illustrations and chart states reach into numbered 50–950 steps. ColorStory's Export modal outputs both layers in either #HEX or native oklch().