Tailwind v4 is a full rewrite, not an incremental update, and the mental model shift is larger than the changelog suggests.

The most significant change is that the framework now generates CSS custom properties by default for every design token. Colors, spacing, fonts — all become CSS variables at the :root level. This means you can read and override any design token from plain CSS or from JavaScript, without a PostCSS plugin or theme extension.

The config file is gone. In v4, configuration lives in CSS itself using the @theme directive. This feels odd at first — you're used to a JavaScript object with type-safe keys. In practice, it's a better separation: your config is in the same layer as your styles, not in a side-channel JS file.

Lightning CSS. Tailwind v4 ships with Lightning CSS as the bundler and transformer. You get nesting, oklch(), color-mix(), and modern range queries compiled for you without configuring PostCSS at all. For Next.js, this required switching from the postcss plugin to the new @tailwindcss/vite (or @tailwindcss/next for App Router). The migration is one dependency swap and a CSS import change.

What didn't land as smoothly: the utility purging. In v3, you control the content glob explicitly. In v4, it auto-detects, but it's not perfect. In one of my apps, utility classes inside dynamically-built class strings (from a Zustand store) were being purged. The fix is @source directives in your CSS — explicit opt-ins for directories that may contain dynamic class strings.

After two production deployments, the bundle is visibly smaller (20-30% in my cases), the DX is faster (Lightning CSS is quick), and the custom property system makes runtime theming — dark/light, user-chosen accent colors — genuinely easy without JS-in-CSS hacks.