tailwind-v3-to-v4-migration

tailwind-v3-to-v4-migration

Upgrade a codebase from Tailwind CSS v3 to v4. The codemod does ~80% of the mechanical work; this skill supplies the 20% of judgment where migrations actually break — changed defaults, config porting, plugin/animation swaps, and proving nothing moved.

When to use

• Upgrading any project from Tailwind v3.x to v4.x.
• Build errors after a partial upgrade: @tailwind directives unknown, missing @tailwindcss/postcss, Cannot apply unknown utility class, tailwind.config no longer picked up.
• Converting tailwind.config.{js,ts} to CSS-first @theme.

Skip if: the project is already on v4; you need to downgrade; or you are building a brand-new design system rather than migrating one. Note v4 targets Safari 16.4+, Chrome 111+, Firefox 128+ — if you must support older browsers, stay on v3.4 (flag this to the operator before proceeding).

The one idea that makes this safe

A correct migration is a visual no-op. Every renamed utility is a pure alias — shadow-sm→ shadow-xs, rounded→rounded-sm, ring→ring-3, outline-none→outline-hidden all compile to the same CSS as before. So what changes pixels is almost entirely v4's changed defaults (Step 3); the few non-default exceptions — the space-x/y-* & divide-* selector change, gradient-variant preservation, and container config removal — are flagged in Step 4. Rename mechanically, neutralize the changed defaults, fix those few exceptions, and the rendered output is identical. That is also how you verify success (Step 5): capture the UI before, prove it's unchanged after.

Procedure

Always work on a branch. Run the steps in order; do not skip Step 0 or Step 3.

Step 0 — Pre-flight & baseline (do not skip)

1. Confirm Node 20+ (node -v) and that the working tree is clean. Create a branch (e.g. tailwind-v4).
2. Inventory every Tailwind entry point — there may be more than one: each CSS file with @tailwind/@import "tailwindcss", every tailwind.config.*, every postcss.config.*, the bundler config (next/vite/webpack), and package.json. Monorepos: do this per package.
3. Record the current setup: darkMode value, custom theme.extend, plugins, the package manager (npm/yarn/pnpm/bun), and two easy-to-miss config options that need special handling later: prefix (v4 changes tw-flex→tw:flex) and theme.container (center/padding are gone in v4 — recreate via @utility container).
4. Capture a baseline of how the app looks now so you can prove the migration changed nothing: a screenshot set or a visual-regression run on v3 (see references/05-verification-playwright.md), or at minimum a list of key pages to eyeball. Confirm the project builds green on v3 first.