tailwind-v3-to-v4-migrationlisted
Install: claude install-skill a-tokyo/agent-skills
# 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 only need a brand-new design
system (use `tailwind-design-system`). 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