tailwind-impl-migration-v3-v4

name	tailwind-impl-migration-v3-v4
description	Use when migrating a project from Tailwind CSS v3.4 to v4.0+, deciding between the automated upgrade tool and manual conversion, planning a dual-version monorepo transition, auditing a codebase before the upgrade, or verifying behaviour after the upgrade. Prevents the five most damaging migration mistakes: assuming the automated tool covers 100 percent (it does not handle runtime opacity classes built from strings, scoped @apply blocks, or visual regressions from default border-color changes), running the tool without first auditing corePlugins/safelist/separator usage (all three removed or relocated in v4), missing the shadow/blur/rounded scale shift (shadow-sm in v3 is shadow-xs in v4, an entire visual layer jumps), ignoring the variant stacking-order flip (first:*:pt-0 becomes *:first:pt-0), and forgetting that @apply in Vue/Svelte/CSS-modules requires @reference in v4. Covers the npx @tailwindcss/upgrade tool (Node 20+, branch workflow, what it converts), the complete breaking-changes catalogue (renamed utilities, removed utilities, opacity syntax, prefix syntax, default ring/border/placeholder colours, space/divide selector rewrites, hover gating to (hover: hover), individual transform properties, theme() function deprecation, corePlugins removal, resolveConfig removal, Sass/Less/Stylus incompatibility), the dual- version strategy for monorepos with shared component libraries, the pre-migration audit checklist, the post-migration verification procedure including visual regression and scoped-style @apply scan. Keywords: tailwind v3 to v4, tailwind v4 upgrade, @tailwindcss/upgrade, npx tailwindcss upgrade, tailwind migration, tailwindcss v4 breaking changes, @tailwind to @import tailwindcss, bg-opacity removed, shadow-sm renamed, shadow-xs, blur-xs, rounded-xs, outline-hidden, ring-3, default border color currentColor, default ring width 1px, prefix tw-flex to tw:flex, variant stacking left to right, first:* to *:first, @apply scoped style @reference, hover (hover: hover) gating, transform-none replaced, theme() deprecated, corePlugins removed, safelist removed @source inline, resolveConfig removed, Sass incompatible v4, monorepo dual version tailwind, audit corePlugins, audit safelist, audit separator, my classes broke after upgrade, visual regression after tailwind v4, can I keep v3, gradient reset via-none, transition outline-color, dialog margin auto, button cursor pointer.
license	MIT
compatibility	Designed for Claude Code. Tailwind CSS v3.4 source + v4.0+ target.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

Tailwind CSS v3 to v4 Migration

The path. Audit first, automate second, verify third. Skipping the audit produces a build that compiles and renders wrong.

Companion skills :

• tailwind-core-v3-vs-v4 : decision tree for staying vs upgrading
• tailwind-errors-v4-migration : trap catalogue after upgrade
• tailwind-impl-config-v4 : v4 CSS-first config surface
• tailwind-impl-config-v3 : v3 JS config surface (source state)

Decision : Do You Even Migrate

Constraint	Stay on v3.4	Migrate to v4
Must support Safari < 16.4, Chrome < 111, Firefox < 128	yes	no
Uses Sass / Less / Stylus around Tailwind	yes	no
Heavy reliance on corePlugins: { x: false } to disable utilities	stay or accept utility cannot be disabled in v4	no
Uses resolveConfig in JS at runtime	yes	only if you rewrite to getComputedStyle
Greenfield project, modern browsers	no	yes
Want CSS-first config and faster builds	no	yes

v3.4 still receives security patches. There is NO urgency to migrate purely for the sake of being current.

Quick Path : Automated Upgrade

git checkout -b chore/tailwind-v4
npx @tailwindcss/upgrade

Requires Node.js 20 or higher. The tool runs in three phases :

1. Dependency updates : removes tailwindcss@^3, autoprefixer, postcss-import ; installs tailwindcss@^4, @tailwindcss/postcss or @tailwindcss/vite based on detected build setup.
2. Config conversion : reads tailwind.config.js, converts theme.extend.colors, fontFamily, spacing, etc. into a CSS @theme { ... } block in the entry stylesheet. Leaves the JS file in place with a comment, or removes it (review diff).