Mastering the Tailwind CSS v4 CSS-First Architecture

Tailwind CSS v4 is a ground-up reimagining of the world's most popular utility-first CSS framework. By shedding the legacy JavaScript runtime configuration (tailwind.config.js) in favor of native CSS stylesheets utilizing the new Lightning CSS compiler engine, builds execute up to 10x faster with dramatically reduced node_modules footprint.

1. The Paradigm Shift: From JS Config to @theme

In version 3, theme customization required exporting a JavaScript object containing colors, spacing scales, and font definitions. In Tailwind v4, all theme tokens are declared directly in your primary CSS entry point:

@theme {
  --color-brand-50: oklch(0.97 0.02 245);
  --color-brand-500: oklch(0.62 0.19 245);
  --color-brand-900: oklch(0.24 0.12 245);
  --font-display: 'Plus Jakarta Sans', sans-serif;
}

This eliminates the build-time overhead of parsing JavaScript files and makes every theme token accessible as a standard native CSS Custom Property throughout your entire codebase.

2. Why OKLCH is the Default Color Space

Legacy sRGB and HSL color models suffer from non-uniform perceived lightness. A yellow hue with 50% lightness looks blindingly bright, while a blue hue at 50% lightness appears dark and muddy. The OKLCH color space corrects this with perceptual uniformity:

• O (Lightness): Perceived luminance from 0 (black) to 1 (pure white).
• C (Chroma): Saturation intensity, supporting modern P3 wide-gamut displays on Apple and OLED devices.
• H (Hue): Angle in degrees (0° to 360°) on the perceptual color circle.

3. Seamless Migration Checklist

When upgrading legacy Tailwind v3 codebases to v4:

1. Remove postcss.config.js if utilizing the standalone Tailwind CLI or Vite plugin.
2. Replace @tailwind base; @tailwind components; @tailwind utilities; with a single @import "tailwindcss"; directive.
3. Port your custom utility plugins to native CSS cascade layers using @utility my-class { ... }.