Shipping Tailwind CSS v4 in production: what changed

I moved one of my own projects to Tailwind CSS v4 and hit a few surprises. Here's what changed in the upgrade and what I'd watch for.

I moved one of my projects to Tailwind v4 halfway through this year. The upgrade itself was quick, but a few things behaved differently than the old version, and it took a couple of builds to sort out.

The config moved into CSS

In v3, design tokens lived in tailwind.config.js. In v4 they're CSS custom properties in a @theme block, right next to the styles that use them:

@theme {
  --color-paper: #f2f0ea;
  --color-brand: #ff4d00;
  --font-display: "Archivo Black", sans-serif;
}

Once declared, bg-paper, text-brand and font-display just work in the markup. There's no separate config file to keep in sync.

Utilities are now layered

v4 emits utilities into real CSS @layer blocks instead of one flat compiled file. The result is a sensible order: reset, base, then utilities. My own custom CSS, written outside any layer, wins over utilities — which made overriding and composing more predictable.

Builds got noticeably faster

The new engine scans the source with Lightning CSS and only generates what it actually finds. With the Vite plugin, dev builds are near-instant and the production CSS only contains the utilities that appear in the code.

Things that tripped me up

• Some custom variants needed a :where() wrapper to keep specificity flat on hover and focus states.
• The default ring colour changed to currentColor; anything that relied on ring-brand had to spell it out.
• Files far from the project root sometimes needed adding to the scanner's source paths.
• The output assumes modern browsers. That's fine for the sites I build, but worth checking before shipping to older browsers.

Is the upgrade worth it?

For new projects, yes — it's where the tool is heading. For existing v3 sites, the migration is mostly mechanical: port the theme block to @theme, re-check custom variants, and let the build surface what's missing. Budget an afternoon for a small site.

This portfolio runs on v4. I'd probably start any new project the same way.