← ClaudeAtlas

tailwind-v3-to-v4-migrationlisted

Migrate a project from Tailwind CSS v3 to v4 safely and completely. Runs the official `@tailwindcss/upgrade` codemod, then drives the judgment the codemod 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: setting up Tailwind v4 in a fresh project (no v3 present), downgrading v4→v3, building a new
a-tokyo/agent-skills · ★ 11 · Web & Frontend · score 79
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