Tailwind v4 Color: OKLCH, @theme, and the New Defaults
Tailwind v4 (released 2024) is a major rewrite that changes how color is defined and consumed. The default palette is now OKLCH-native, configuration moves from `tailwind.config.js` to a `@theme` block in CSS, and the build is dramatically faster.
This article covers the changes that affect color specifically and how to extend the palette in v4.
The default palette in OKLCH
Tailwind v3 shipped its default palette in HEX. v4 ships the same colors (slate, gray, ..., rose) but defined in OKLCH. The visible result is identical for sRGB displays - the change only matters when you customize.
Why? OKLCH lets Tailwind extend cleanly into wide-gamut P3 territory and produces more even results when you use `color-mix` to derive variants.
The @theme directive
In v3 you edited `tailwind.config.js`. In v4 you write CSS:
@import "tailwindcss";
@theme {
--color-brand-50: oklch(0.97 0.02 250);
--color-brand-500: oklch(0.62 0.18 250);
--color-brand-900: oklch(0.28 0.10 250);
}
/* Now bg-brand-500, text-brand-50 etc. work */Every CSS custom property under `@theme` becomes a Tailwind utility. No build config, no JS plugin.
Extending with a full scale
For a brand color, define the full 50-950 scale. Use OKLCH so the steps look perceptually uniform:
@theme {
--color-brand-50: oklch(0.97 0.02 250);
--color-brand-100: oklch(0.93 0.04 250);
--color-brand-200: oklch(0.86 0.08 250);
--color-brand-300: oklch(0.78 0.12 250);
--color-brand-400: oklch(0.70 0.16 250);
--color-brand-500: oklch(0.62 0.18 250);
--color-brand-600: oklch(0.54 0.18 250);
--color-brand-700: oklch(0.46 0.16 250);
--color-brand-800: oklch(0.38 0.12 250);
--color-brand-900: oklch(0.28 0.10 250);
--color-brand-950: oklch(0.18 0.06 250);
}Hold hue (250) constant, taper chroma at the extremes (where the gamut is narrower), step lightness on a smooth curve. The /css-vars tool generates this for any brand HEX.
Migrating from v3
- Move palette extensions from `theme.extend.colors` in JS to `@theme` in CSS.
- Replace HEX values with OKLCH if you want wide-gamut behavior.
- Remove the JS config file unless you have plugin code that requires it.
- Run the official upgrade tool: `npx @tailwindcss/upgrade`.
Most v3 projects upgrade in under an hour. Custom plugins are the main friction point.
Try the related tools
Frequently asked questions
Will my v3 sites still work?
Yes. Tailwind v3 is still maintained. Migrate when you have time, not in a panic.
Do I have to use OKLCH for custom colors?
No - v4 accepts HEX, RGB, HSL, OKLCH, and any CSS color value in `@theme`. OKLCH is recommended but not required.
How do I do dark mode in v4?
Same as v3: `dark:` variants, plus `@variant dark` in CSS for fine-grained control. Define dark-mode tokens in a separate `@theme dark` block or use `[data-theme=dark]` selectors.