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().