Tailwind CSS 4 Migration: What Actually Changes

Tailwind 4 is a substantial rewrite. The marketing focuses on speed; here is what actually breaks (and what doesn’t).

The big changes

1. New Oxide engine in Rust — order-of-magnitude faster builds, smaller CSS.
2. CSS-first config. tailwind.config.js is replaced by @theme directives in your CSS.
3. Native CSS layers (@layer base, @layer components, @layer utilities) are now standard, not Tailwind-specific.
4. Dynamic utilities — arbitrary values for nearly everything: m-[17.5px], bg-[oklch(70%_0.2_180)].

Syntax changes that bite

Old (v3)	New (v4)
bg-gradient-to-r	bg-linear-to-r
shadow-sm	shadow-xs
text-opacity-50	text-blue-500/50
flex-shrink-0	shrink-0

The official @tailwindcss/upgrade codemod handles ~90% of these.

CSS-first config example

@import "tailwindcss";

@theme {
  --color-brand: oklch(67% 0.18 250);
  --font-display: "Inter", sans-serif;
  --breakpoint-3xl: 1920px;
}

Use them as standard utilities: bg-brand, font-display, 3xl:text-2xl.

Real migration tips

1. Run the upgrade codemod first on a clean branch.
2. Search for bg-gradient- — codemods sometimes miss template strings.
3. Check dark-mode classes — the default strategy moved to @variant dark and CSS variables.
4. Re-audit your design tokens; v4 makes it cheap to express them in OKLCH.

Should you migrate?

If you are on v3 with a stable codebase and no DX issues — there is no rush. If you are starting a new project, v4 is the obvious choice for build speed and modern color spaces.