tailwind-v3-to-v4-migration

Solid

Migrate a project from Tailwind CSS v3 to v4 safely and completely. Runs the official `@tailwindcss/upgrade` codemod, then drives the judgment it 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: a fresh v4 setup with no v3 present, downgrading v4 to v3, or non-Tailwind CSS.

Web & Frontend 15 stars 1 forks Updated 2 weeks ago MIT

Install

View on GitHub

Quality Score: 84/100

Stars 20%
40
Recency 20%
90
Frontmatter 20%
70
Documentation 15%
100
Issue Health 10%
50
License 10%
100
Description 5%
100

Skill Content

# 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 are building a brand-new design system rather than migrating one. 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 ou...

Details

Author
a-tokyo
Repository
a-tokyo/agent-skills
Created
3 months ago
Last Updated
2 weeks ago
Language
JavaScript
License
MIT

Integrates with

Bundled in these plugins

Similar Skills

Semantically similar based on skill content — not just same category

Web & Frontend Listed

tailwind-patterns

Tailwind CSS v4 patterns, CSS-first config via @theme directive, v3-vs-v4 deltas, variant rules, and anti-patterns. Use whenever the project contains `tailwind.config.js`, `tailwind.config.ts`, `@import "tailwindcss"` in CSS, `@tailwindcss/postcss` or `@tailwindcss/vite` in `package.json` dependencies, OR the user asks about Tailwind, utility classes, CSS, styling in a Tailwind project, @theme, @apply, design tokens, dark mode strategy, or any work touching CSS class names or theme configuration, even if Tailwind is not mentioned by name.

0 Updated today
ku5ic
Web & Frontend Listed

tailwindcss-development

Always invoke when the user's message includes 'tailwind' in any form. Also invoke for: building responsive grid layouts (multi-column card grids, product grids), flex/grid page structures (dashboards with sidebars, fixed topbars, mobile-toggle navs), styling UI components (cards, tables, navbars, pricing sections, forms, inputs, badges), adding dark mode variants, fixing spacing or typography, and Tailwind v3/v4 work. The core use case: writing or fixing Tailwind utility classes in HTML templates (Blade, JSX, Vue). Skip for backend PHP logic, database queries, API routes, JavaScript with no HTML/CSS component, CSS file audits, build tool configuration, and vanilla CSS.

1 Updated yesterday
rcdelfin
Web & Frontend Listed

tailwind-design-system

Build scalable design systems with Tailwind CSS v4, design tokens, component libraries, and responsive patterns. Use when creating component libraries, implementing design systems, or standardizing UI patterns.

3 Updated 5 days ago
whimzyLive