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
Decision gist · record as of 2026-07-26
tailwind-v3-to-v4-migration upgrades your Tailwind v3 codebase to v4 while preserving visual output. 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.
Use it when
- tailwind-v3-to-v4-migration identifies and helps you apply compat shims for v4's changed defaults: border, ring, placeholder, cursor.
- Yes.
Verify before relying
Read SKILL.md below before installing (8 files). Open directory: indexed for reading, not audited.
Install
a-tokyo/agent-skills/tailwind-v3-to-v4-migration · repository language: JavaScript
Open directory. Skills are indexed for reading, not audited. Review a skill's body before installing it.
Frequently 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)
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
Let your AI agent find skills like this
Example. Real query, live index.
You found this page by searching. An agent finds it by wishing: SkillFed indexes 56,283 agent skills by what they can do, searchable in plain language.
wish › “Upgrade an existing Tailwind v3 project to v4 with zero visual regressions”
Give your agent the search over MCP, or paste the wish link into any chat. No install? Search from any chat →
Related skills
This skill corrects AI agents that generate outdated Tailwind v3 code by teaching v4 syntax and configuration patterns. It covers 12 critical rules including CSS @import statements, @theme directives, modern opacity syntax, container queries, and renamed utilities, plus anti-patterns to avoid.
Master Tailwind CSS with 29 rules spanning responsive layouts, dark mode setup, reusable component patterns, and configuration across v3.4+ and v4. Learn mobile-first design, conditional styling with utilities, and how to migrate projects from v3 to v4 using the new CSS-first approach.
This skill guides you through building modern frontend projects with Vite, React, and TailwindCSS v4, including proper configuration, project structure, and component patterns. It covers environment setup, TypeScript configuration pitfalls to avoid, and practical development conventions using lucide-react icons.
Master Tailwind CSS v4's CSS-first configuration model, Rust-powered engine, and modern setup across Vite and PostCSS. This skill covers installation methods, @theme-based theming, custom utilities and variants, plugin loading, and the shift from JavaScript config to pure CSS. Includes v3-to-v4 migration guidance and reference for new v4 utilities.
Resolve Tailwind CSS styling problems with structured troubleshooting for classes that won't apply, dynamic class generation failures, and version migration conflicts. Get decision trees, configuration templates, and debugging steps for content detection, IntelliSense setup, and build cache issues.
Tailwind CSS v4 is a utility-first framework for building styled interfaces by composing single-purpose classes directly in markup. Configuration happens entirely in CSS through @theme and @layer directives, eliminating separate config files. Works with Next.js, Vite, and the CLI.
More skills hebrew-tailwind-preset (MIT) · Heroui (MIT) · skill-tailwind (MIT) · tailwindcss-performance (MIT)