Tailwind CSS v4 Migration: New Features Guide 2026

1. What Changed in v4

Tailwind v4 introduces five architectural changes that collectively improve DX, performance, and CSS standards alignment. Understanding these changes at a conceptual level before running the migration tool prevents confusion when reviewing diffs.

2. Canonical Class Renames

The utility rename table covers every deprecated class and its v4 canonical replacement. The @tailwindcss/upgrade CLI handles all of these automatically. The table is provided for manual review and to understand the naming rationale.

3. CSS Variables System

The CSS variables system is v4's most powerful new capability. Every design token defined in @theme is automatically exposed as a CSS custom property and generates corresponding utilities. This eliminates the disconnect between Tailwind utilities and raw CSS.

Defining Tokens in @theme

@import "tailwindcss";

@theme {
  /* Colors — auto-generates: bg-brand, text-brand, border-brand */
  --color-brand: #4f46e5;
  --color-brand-light: #818cf8;

  /* Typography */
  --font-sans: "Geist", "Inter", system-ui, sans-serif;
  --font-mono: "Geist Mono", monospace;

  /* Spacing — extends default scale */
  --spacing-18: 4.5rem;
  --spacing-22: 5.5rem;

  /* Breakpoints */
  --breakpoint-3xl: 1920px;
}

/* Use tokens in custom CSS */
.custom-component {
  background: var(--color-brand);
  font-family: var(--font-sans);
}

Using Tokens in JSX

{/* Generated utilities from @theme tokens */}
<div className="bg-brand text-white">Brand background</div>
<span className="text-brand-light">Light brand text</span>

{/* Arbitrary values using CSS custom properties */}
<div className="bg-[--color-brand] p-18">Custom spacing token</div>

{/* Inline style using CSS variable */}
<div style={{ "--accent": "var(--color-brand)" }}>...</div>

4. Configuration Migration

The configuration migration converts your tailwind.config.js theme extensions into CSS @theme blocks. The mapping is direct — every key in your theme.extend becomes a CSS custom property under the corresponding namespace.

module.exports = {
  theme: {
    extend: {
      colors: {
        brand: "#4f46e5",
        "brand-light": "#818cf8",
      },
      fontFamily: {
        sans: ["Geist", "Inter"],
      },
      spacing: {
        18: "4.5rem",
      },
    },
  },
  darkMode: "class",
};

@import "tailwindcss";

@theme {
  --color-brand: #4f46e5;
  --color-brand-light: #818cf8;
  --font-sans: "Geist", "Inter",
    system-ui, sans-serif;
  --spacing-18: 4.5rem;
}

/* Class-based dark mode */
@variant dark (&:is(.dark *));

5. Plugin Compatibility

Plugin compatibility is the primary source of migration complexity. Check each plugin in your plugins array against the table below before migrating.

6. Performance Gains

The switch to Lightning CSS delivers measurable build performance improvements that directly impact development speed and CI/CD pipeline costs.

For SEO implications of CSS performance improvements, see our guide on SEO optimization services. Faster CSS rendering contributes to LCP improvements that affect search rankings.

7. Step-by-Step Migration

Follow this sequence in order. Do not skip steps — particularly the branch creation and backup steps. The migration involves automated file modifications across your entire codebase.

git checkout -b feat/tailwind-v4-migration

npm install tailwindcss@latest @tailwindcss/vite
npx @tailwindcss/upgrade

@import "tailwindcss";
/* Remove: @tailwind base; @tailwind components; @tailwind utilities; */

# Check each plugin in your config
npm update @tailwindcss/typography @tailwindcss/forms

@variant dark (&:is(.dark *));

npm run build 2>&1 | grep -E 'error|warn'

# Test in Chrome, Firefox, Safari
# Test light + dark mode toggle
# Verify responsive breakpoints

For React Server Components and architecture patterns that work with Tailwind v4, see our React Server Components Production Pattern Guide. RSC architecture aligns naturally with v4's CSS-native approach.

Frequently Asked Questions