v3 to v4 Upgrade Trap Catalog

Every documented breaking change between Tailwind v3 and v4 with symptom, root cause, surgical fix, and (where applicable) a @layer base shim that restores v3 behavior during staged migration.

ALWAYS run the official codemod first :

npx @tailwindcss/upgrade

The codemod handles ~80% of the renames mechanically. This skill catalogs what it does NOT auto-fix, plus what to expect when visually-equivalent classes silently change meaning.

Companion skills :