Tailwind v4 shipped. Here are the renames that will bite you.

We upgraded a mid-sized app to Tailwind v4 last month. The codemod ran in seconds, the build got dramatically faster, and then the design looked subtly wrong on about forty screens. None of it was broken, exactly. It was just off. Here is what actually changed, and the handful of renames that will quietly shift your UI if you are not watching for them.

The engine is the easy part

The headline feature is the new Rust engine, Oxide. The numbers are real: full builds run several times faster, and incremental rebuilds that produce no new CSS are effectively instant. You also stop maintaining a content array, because v4 detects your template files automatically and respects your .gitignore. If it misses a path, like a component library buried in node_modules, you point it there with @source.

Configuration moved into CSS. Instead of a JavaScript object, you define your design tokens in a stylesheet:

@import "tailwindcss";

@theme {
  --color-brand: oklch(0.62 0.19 29);
  --font-display: "Space Grotesk", sans-serif;
  --breakpoint-3xl: 120rem;
}

Every token becomes a real CSS custom property on :root, which means your design system is now readable from plain CSS and from the browser devtools. This alone is worth the move. Your old tailwind.config.js still works if you load it with @config, so you do not have to convert everything in one sitting.

The renames that bite

Here is the part nobody warns you about. Several scales were renamed, and the old names still exist but now mean something different. The migration tool updates your class names, but it cannot update your intent, so the safest move is to diff the rendered output, not the diff in Git.

The shadow scale shifted down a step. The old shadow-sm is now shadow-xs, and the old shadow is now shadow-sm. The same shift hit blur, drop-shadow, backdrop-blur, and rounded.

Default border color changed from gray-200 to currentColor. Any element with a bare border and no explicit color now draws its border in the text color. On a page of dark headings, that reads as heavy black hairlines you never asked for.

The default ring went from a 3px blue glow to a 1px currentColor outline. If you relied on ring for focus styling, you now want ring-3 ring-blue-500 to get the old look.

outline-none became outline-hidden. The new outline-none genuinely removes the outline, which is an accessibility footgun if you swap them blindly.

There are syntax shifts too. Important is now a trailing flex! rather than a leading !flex, CSS variable shorthands use parentheses like bg-(--brand), and hover: is gated behind @media (hover: hover), so it no longer fires on touch devices. That last one is correct behavior, but it will surprise you if a tap state quietly stops working on mobile.

The cost of admission

v4 raises the browser floor: Safari 16.4, Chrome 111, Firefox 128. It leans on @property and color-mix() with no graceful fallback, so this is a hard cutoff, not a progressive enhancement. If a meaningful slice of your traffic runs older enterprise Safari, check your analytics before you commit. We did, decided the long tail was small enough, and shipped. A team with a different audience might reasonably wait.

The honest summary: the engine and the CSS-first config are a genuine upgrade, and container queries plus 3D transforms in core are a nice bonus. But "v4 is just a faster v3" is the line that gets people. It is faster, and it also moves your shadows, your borders, and your rings half a notch. Budget an afternoon to walk the real UI, not just the build log.