tailwind-v3-to-v4-migration
Automates the mechanical parts of upgrading from Tailwind v3 to v4, then handles the judgment calls the codemod can't: reconciling dependencies, porting config to CSS-first `@theme`, auditing v4's changed defaults (border, ring, placeholder, cursor, dialog, hover), and verifying the rendered output stays identical. Works across Next.js, Vite, Tailwind CLI, and plain PostCSS setups.
tailwind-v3-to-v4-migration upgrades your Tailwind v3 codebase to v4 while preserving visual output.
AI-generated summary based on this skill's SKILL.md
Install
a-tokyo/agent-skills/tailwind-v3-to-v4-migration · repository language: JavaScript
git clone https://github.com/a-tokyo/agent-skills
cp -r agent-skills/skills/tailwind-v3-to-v4-migration ~/.claude/skills/tailwind-v3-to-v4-migrationnpx skillfed install a-tokyo/agent-skills/tailwind-v3-to-v4-migrationFrequently asked questions
AI-generated answers based on this skill's SKILL.md and metadata
How do I migrate Tailwind 3 to 4 with zero visual regressions?
tailwind-v3-to-v4-migration automates the initial upgrade, then guides you through the judgment calls a codemod cannot make. It reconciles dependencies, ports your config from JS to CSS-first @theme syntax, applies compat shims for v4's changed defaults (borders, rings, placeholders, cursor, dialog, hover), and runs visual parity testing to confirm your rendered output stays identical across Next.js, Vite, Tailwind CLI, and PostCSS setups.
What does tailwind-v3-to-v4-migration do about changed defaults?
tailwind-v3-to-v4-migration identifies and helps you apply compat shims for v4's changed defaults: border, ring, placeholder, cursor, dialog, and hover behavior. Rather than leaving you to hunt down visual breaks, it flags which defaults shifted and provides the configuration snippets to restore v3 appearance where you need it, letting you upgrade safely without surprise regressions.
Can tailwind-v3-to-v4-migration port my config from JS to CSS @theme?
Yes. tailwind-v3-to-v4-migration handles porting your Tailwind config from JavaScript to the CSS-first @theme syntax that v4 prefers. It translates your existing theme values, plugins, and customizations into the new format, reducing manual rewriting and helping you adopt v4's cleaner configuration model.
Does this tool resolve @tailwind directives errors in v4?
tailwind-v3-to-v4-migration addresses Tailwind v4 build errors and unknown utility class issues that arise during upgrade. It reconciles dependency versions, updates PostCSS configuration, and validates that your @tailwind directives and custom utilities work correctly in v4, whether you're using Next.js, Vite, Tailwind CLI, or plain PostCSS.
How does tailwind-v3-to-v4-migration verify the upgrade is complete?
tailwind-v3-to-v4-migration includes visual parity testing to confirm migration completeness. After applying the codemod, compat shims, and config changes, it helps you verify that your rendered output matches v3, catching any missed utility renames (like bg-gradient-to → bg-linear-to) or default shifts before they reach production.
What build systems does tailwind-v3-to-v4-migration support?
tailwind-v3-to-v4-migration works across Next.js, Vite, Tailwind CLI, and plain PostCSS setups. It reconciles dependencies and PostCSS configuration for each environment, so whether you're using a framework or standalone Tailwind, the migration path and compat shims apply correctly to your build.
SKILL.md
rendered from the published skill — quoted content, verbatim
name: tailwind-v3-to-v4-migration
version: 0.0.1
description: >-
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 design system from scratch, or non-Tailwind CSS.
license: MIT
compatibility: >-
(truncated - see the full file via the links below)
Read as markdown · JSON record · Browse the source repository
File tree — 8 files
skills/tailwind-v3-to-v4-migration/SKILL.md
skills/tailwind-v3-to-v4-migration/references/00-official-upgrade-guide.md
skills/tailwind-v3-to-v4-migration/references/01-breaking-changes.md
skills/tailwind-v3-to-v4-migration/references/02-css-first-config.md
skills/tailwind-v3-to-v4-migration/references/03-compat-shims.md
skills/tailwind-v3-to-v4-migration/references/04-framework-setups.md
skills/tailwind-v3-to-v4-migration/references/05-verification-playwright.md
skills/tailwind-v3-to-v4-migration/references/06-gotchas.md