/tailwind-v3-to-v4-migration

name: tailwind-v3-to-v4-migration
version: 0.0.2
description: >-
  Migrate a project from Tailwind CSS v3 to v4 safely and completely. Runs the official
  `@tailwindcss/upgrade` codemod, then drives the judgment it can't: reconciling dependencies and
  PostCSS/Vite/CLI plumbing, porting JS config to CSS-first `@theme` (or keeping it via `@config`),
  auditing the v4 changed-defaults that silently alter appearance
  (border/ring/placeholder/cursor/dialog/hover) and applying compat shims, sweeping for
  renamed/removed utilities, and proving the migration is a visual no-op. Framework-agnostic
  (Next.js, Vite, Tailwind CLI, plain PostCSS; Vue/Svelte/Astro/CSS-module caveats). USE FOR: upgrading Tailwind 3 to 4, "tailwind v4
  migration", `@tailwind` directives error, `@tailwindcss/postcss` setup, tailwind.config.js to CSS
  @theme, shadow-sm/rounded/ring/outline-none renames, bg-gradient-to to bg-linear-to. Activate only
  when an existing Tailwind v3 install is being upgraded. DO NOT USE FOR: a fresh v4 setup with no v3
  present, downgrading v4 to v3, or non-Tailwind CSS.
license: MIT
compatibility: >-
  The upgrade tool requires Node.js 20+. Works best in a git repo (run in a branch, review the
  diff). A way to view the app in a browser (or a screenshot/visual-regression harness) is needed
  for the verification step.

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.

Step 1 — Run the official upgrade tool

npx @tailwindcss/upgrade@latest          # clean git tree required…
npx @tailwindcss/upgrade@latest --force  # …or pass --force if untracked/uncommitted files exist

The tool refuses to run on a dirty tree (so you can review its diff). Commit/stash unrelated changes, or use `--force`. It updates dependencies, migrates the config to CSS where it can, rewrites `@tailwind` directives, and codemods most renamed/removed utilities in templates. **Review the full diff** — it is a starting point, not the finish line. If it errors (offline, exotic setup, unsupported config), fall back to the manual path in `references/01-breaking-changes.md` + `references/02-css-first-config.md` and continue. **Monorepos:** run the tool once per package root and confirm `tailwindcss` resolves to 4.x in *every* package's `node_modules` — a half-migrated workspace compiles some packages against v3.

Step 2 — Reconcile dependencies & build plumbing

Verify the tool did these; finish any it missed (`references/04-framework-setups.md` for your stack):

• **Deps:** remove `tailwindcss@3`; add `tailwindcss@^4`. Remove `autoprefixer` and `postcss-import`

(v4 does prefixing + import inlining itself).

• **PostCSS:** `postcss.config.*` → `{ plugins: { '@tailwindcss/postcss': {} } }` (add the

`@tailwindcss/postcss` dep). **Vite:** prefer `@tailwindcss/vite` over PostCSS. **CLI:** `npx tailwindcss` → `npx @tailwindcss/cli`.

• **CSS entry:** `@tailwind base/components/utilities;` → `@import "tailwindcss";`.
• **Plugins:** delete now-built-in ones (`@tailwindcss/container-queries`, `@tailwindcss/aspect-ratio`,

line-clamp) — and remove their dead `theme`/usage. **`@tailwindcss/typography` stays** but is loaded in CSS via `@plugin "@tailwindcss/typography";` and must be bumped to a v4-compatible rel