Migrating From v3 to v4

CSS-first and renamed utilities

Tailwind v4 replaces @tailwind base; @tailwind components; @tailwind utilities; with @import "tailwindcss";, moves configuration from tailwind.config.js to @theme in CSS (a JS config can still be loaded with @config), detects content automatically, and uses separate packages for PostCSS, Vite and the CLI. Several utilities were renamed or rescaled (for example the old shadow-sm is now shadow-xs and shadow is shadow-sm; outline-none became outline-hidden), and default border and ring colours changed. The official upgrade tool (npx @tailwindcss/upgrade) automates most changes.

Before and after

The main stylesheet change.

/* v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;
/* + tailwind.config.js with theme.extend.colors.brand ... */

/* v4 */
@import "tailwindcss";
@theme {
  --color-brand-500: oklch(0.62 0.13 200);
}

Upgrade on a branch and compare visually

Run the upgrade tool, then review screenshots of key pages because renamed scales change appearance subtly.

Quick check: Where do design tokens usually live in Tailwind v4?

• In package.json
• Only in tailwind.config.js
• In an @theme block in CSS
• In HTML meta tags