Tailwind CSS v3 to v4: renamed utilities and breaking changes

Tailwind CSS v4 is configured in CSS instead of tailwind.config.js, ships its build tools in separate packages, and renames several utility scales. The official upgrade tool, npx @tailwindcss/upgrade, rewrites most of a project automatically; review the diff, because the renamed utilities change how things look.

Setup changes

@tailwind base;
@tailwind components;
@tailwind utilities;

@import "tailwindcss";

@theme {
  --color-brand: #0e7c86;
  --font-display: "Inter", sans-serif;
}

Renamed utilities

See the new names compiled

npm init -y >/dev/null
npm install --silent --no-audit --no-fund tailwindcss@4 @tailwindcss/cli@4 >/dev/null 2>&1
echo '@import "tailwindcss";' > in.css
echo '<div class="shadow-xs rounded-xs ring-3 outline-hidden bg-linear-to-r"></div>' > index.html
npx @tailwindcss/cli -i in.css -o out.css 2>/dev/null
grep -oE '^\s*\.(shadow-xs|rounded-xs|ring-3|outline-hidden|bg-linear-to-r)' out.css | sed 's/^ *//' | sort -u

.bg-linear-to-r
.outline-hidden
.ring-3
.rounded-xs
.shadow-xs

Other behaviour changes

• Border colour: border and divide use currentColor instead of gray-200; add border-gray-200 where you relied on the old default.
• Variants stack left to right: *:first:pt-0 instead of v3's right-to-left order.
• Hover only applies on devices that support hover (@media (hover: hover)).
• Browsers: v4 depends on @property and color-mix() and targets Safari 16.4, Chrome 111 and Firefox 128. Stay on v3.4 if you must support older browsers.