Tailwind CSS v4 is a ground-up rewrite. The JavaScript configuration files are gone, LightningCSS is running under the hood, and the entire default palette has been rewritten using the perceptually uniform OKLCH color space.
If you are migrating a production application from v3 to v4, you need to understand the new CSS-first @theme block and why OKLCH matters for defining design tokens. Below, we cover the new syntax, registering brand scales, and streamlining the process with the OKLCH color picker.
The Death of tailwind.config.js
For years, developers managed their Tailwind design systems inside tailwind.config.js. This approach worked, but it created a disconnect between CSS variables and JavaScript objects. Tailwind v4 introduces a modern, CSS-first configuration paradigm.
Instead of writing JavaScript, you now define your custom colors, fonts, and spacing directly in your main CSS file using the @theme directive. This change aligns Tailwind closer to native CSS Custom Properties and significantly improves developer experience and tooling integration.
Registering Custom OKLCH Colors
With the new @theme block, adding a brand color scale is as simple as writing native CSS variables inside the --color-* namespace. Tailwind v4 natively supports the oklch() color function, which has been widely available across all major browser engines since May 2023.
Here is an example of defining a primary brand scale in your main stylesheet:
@import "tailwindcss";
@theme {
--color-brand-50: oklch(0.97 0.01 250);
--color-brand-400: oklch(0.75 0.15 250);
--color-brand-500: oklch(0.65 0.20 250);
--color-brand-600: oklch(0.55 0.22 250);
--color-brand-950: oklch(0.20 0.05 250);
}
Because OKLCH separates perceived lightness from hue and chroma (color intensity), generating a consistent scale from 50 to 950 is far more predictable than using HSL or RGB. A lightness value of 0.65 in OKLCH will appear equally bright whether the hue is yellow, blue, or red.
No More HEX Fallbacks
A common concern when adopting OKLCH is backward compatibility. Legacy tools often relied on PostCSS plugins to compile modern color functions back to standard RGB or HEX values.
Tailwind v4 relies heavily on modern CSS features, including @property and color-mix(). Because these features share the same baseline engine requirements as oklch(), the framework intentionally does not compile OKLCH fallbacks. If your application must support extremely outdated browsers, you will need to stick with Tailwind v3. However, with global browser support for OKLCH at around 96%, the vast majority of modern web applications can safely embrace the new syntax.
Streamlining Palette Generation
Building an enterprise-grade tonal palette requires careful balancing. To ensure visual harmony, you shouldn't just scale lightness linearly. Modern palettes use a non-linear lightness curve and a Gaussian chroma curve—keeping saturation low at the extreme light and dark ends to prevent neon glowing or muddy tones.
Manually calculating these curves is tedious. To instantly generate highly accurate, v4-ready @theme code blocks, you can use the OKLCH color picker. It visualizes out-of-gamut boundaries and exports clean CSS Custom Properties optimized for your Tailwind configuration. If you are also experimenting with smooth color transitions, check out our CSS gradient generator to see how OKLCH interpolates colors without the muddy gray dead zones common in legacy RGB gradients.