skills.rest
Impertio-Studio
Impertio-StudioOFFICIAL
Explore all skills by this author →
WebsiteGitHub

shadcn-errors-tailwind-v3-v4-migration

Migrate shadcn ui projects from Tailwind CSS v3 to v4 with a deterministic runbook.

Updated May 19, 2026
Search Tags:#dark mode#shadcn ui#postcss#globals.css#tailwind v3 v4#migration runbook#focus ring
One-click install
npx skills add https://github.com/Impertio-Studio/shadcn-ui-Claude-Skill-Package --skill shadcn-errors-tailwind-v3-v4-migration
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: shadcn-errors-tailwind-v3-v4-migration
Source: https://github.com/Impertio-Studio/shadcn-ui-Claude-Skill-Package/tree/main/skills/source/shadcn-errors/shadcn-errors-tailwind-v3-v4-migration
Command: npx skills add https://github.com/Impertio-Studio/shadcn-ui-Claude-Skill-Package --skill shadcn-errors-tailwind-v3-v4-migration

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This skill prevents shadcn ui projects from breaking during a Tailwind CSS v3 to v4 upgrade by giving a deterministic way to detect the current Tailwind generation and apply the correct migration steps in the right order, avoiding half-migrated states that cause silent color, dark mode, animation, and focus-ring regressions.

Core Features & Use Cases

  • Detects v3 vs v4 before edits using signals like tailwind.config.js presence, globals.css directives/imports, token formats (0 0% 100% vs oklch(...)), animate plugin entries, PostCSS plugin names, and component code shape (v3 forwardRef vs v4 data-slot).
  • Provides a deterministic migration runbook covering codemod execution, dependency swaps, CSS rewrites (@import "tailwindcss", @theme inline, @custom-variant dark, token formatting), PostCSS/Vite integration, and required component refresh via shadcn CLI.
  • Covers common anti-pattern bugs like mixed v3/v4 syntax in the same file, leaving tailwindcss-animate installed, using bg-[hsl(var(--background))] in v4, keeping ring-2 after v4, and wiring dark mode in both JS and CSS.

Quick Start

Use the shadcn-errors-tailwind-v3-v4-migration skill to migrate your project to Tailwind v4 by first running the official upgrade codemod, then swapping the animate plugin, rewriting globals.css tokens and variants, and finally re-pulling shadcn components with overwrite to eliminate silent regressions.

Frequently Asked Questions about shadcn-errors-tailwind-v3-v4-migration

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why are my shadcn ui colors transparent or washed out after upgrading to Tailwind v4?▼

Tailwind v4 migration causes transparent or washed out colors when v3 HSL token formats remain in `globals.css` instead of being rewritten to v4 `oklch(...)` syntax. Rewriting CSS tokens and applying the `@theme inline` directive resolves the rendering regression.

How do I fix dark mode not flipping correctly in Tailwind v4?▼

Dark mode stops flipping in Tailwind v4 when the `dark` variant is wired in both JS and CSS or uses v3 syntax. You fix dark mode by replacing the old configuration with `@custom-variant dark` in your `globals.css` file during the migration runbook.

How to migrate shadcn ui from Tailwind v3 to v4 step by step?▼

Migrate shadcn ui to Tailwind v4 by running the official upgrade codemod, swapping `tailwindcss-animate` for `tw-animate-css`, rewriting `globals.css` tokens and variants, updating PostCSS or Vite integration, and re-pulling shadcn components via CLI to eliminate silent regressions.

What causes PostCSS Tailwind plugin errors and unknown at-rules like @theme after upgrading?▼

PostCSS emits Tailwind plugin errors and unknown at-rules like `@theme` or `@custom-variant` when the PostCSS or Vite integration is not updated to recognize Tailwind v4 syntax. Updating the PostCSS configuration and dependency versions in lockstep resolves these build errors.

Do I need to replace tailwindcss-animate when migrating to Tailwind v4?▼

Yes, you must replace `tailwindcss-animate` with `tw-animate-css` when migrating to Tailwind v4. Leaving `tailwindcss-animate` installed causes animations to stop working and creates a half-migrated state with conflicting syntax.

Why did my focus ring change thickness or stop working in shadcn ui after Tailwind v4?▼

Focus rings change thickness or stop working because Tailwind v4 alters ring utility behaviors. Adjusting ring utilities and replacing `ring-2` in your component code during the migration runbook restores the correct focus ring rendering.

Related Skills

Explore More Software Engineering Skills→
TimeKastTimeKast

kb-tailwind-v4

Standardize Tailwind CSS v4 utility generation for Next.js CSS-first @theme token systems.

Official
Intermediate
Owl-ListenerOwl-Listener
2.0k

color-system

Generate scalable color systems with tonal scales and AA/AAA contrast mappings.

Community
Advanced
bluebricks-nlbluebricks-nl

shadcn-code-review

Review React components using shadcn/ui, Radix primitives, and Tailwind CSS for best practices.

Official
Intermediate
Impertio-StudioImpertio-Studio

tailwind-impl-build-postcss-cli

Integrate Tailwind CSS into non-Vite build systems via PostCSS or standalone CLI.

Official
Intermediate