shadcn-errors-tailwind-v3-v4-migration

name	shadcn-errors-tailwind-v3-v4-migration
description	Use when a shadcn ui project must move from Tailwind CSS v3 to v4, when colors break or look washed out after a Tailwind upgrade, when the dark mode toggle stops applying after switching the stylesheet, when `bg-background` renders transparent instead of the theme color, when `tailwindcss-animate` is missing in `package.json` but components still try to animate, when the Tailwind build emits "unknown at-rule @theme" or "unknown at-rule @custom-variant", when `tailwind.config.js` is still present in a project that imports the v4 stylesheet, when ring outlines on Button or Input changed thickness after the upgrade, when PostCSS fails with "tailwindcss is not a PostCSS plugin", or when AI-generated code mixes v3 syntax (`@tailwind base`, `hsl(var(--background))`, `darkMode: ['class']`) with v4 syntax (`@import "tailwindcss"`, `oklch()`, `@custom-variant dark`) in the same file. Prevents the canonical migration bugs: keeping `tailwind.config.js` alongside `@theme inline` so two config sources fight, leaving HSL space-separated tokens after switching to v4 so colors silently fail to parse, keeping the deprecated `tailwindcss-animate` plugin after v4 removes it, leaving `ring-2` in code that was upgraded so default ring width changed, leaving `darkMode: ['class']` in the JS config while also adding `@custom-variant dark` in CSS so dark mode runs twice or not at all, and using `bg-[hsl(var(--background))]` arbitrary classes in v4 where `bg-background` resolves directly. Covers the detection rules (which files signal v3 vs v4), the exact migration runbook (codemod, dependencies, CSS rewrite, plugin swap, verification), the per-file diffs for `globals.css`, `tailwind.config.js`, `postcss.config.js`, `vite.config.ts`, and `package.json`, the v3 vs v4 syntax reference per concept (theme, colors, dark mode, animate plugin, ring utility, PostCSS, Vite), and six common anti-patterns that surface as silent visual regressions. Keywords: tailwind v3 to v4, tailwind v4 migration shadcn, oklch migration, @theme inline, tw-animate-css, tailwindcss-animate removed, ring utility v4, ring-3 vs ring-2, dark mode v4, @custom-variant dark, darkMode class v3, tailwind upgrade shadcn, tailwind config removed, @tailwindcss/postcss, @tailwindcss/vite, why my colors broke after tailwind upgrade, bg-background transparent, hsl var background, oklch var background, @import tailwindcss, @tailwind base removed, npx @tailwindcss/upgrade, shadcn evergreen-2026 tailwind, postcss tailwindcss is not a PostCSS plugin, unknown at-rule @theme, unknown at-rule @custom-variant, animations stopped working tailwind v4, accordion not animating shadcn, sheet not sliding shadcn, dialog not fading shadcn, ring focus too thin, ring focus too thick, my dark toggle stopped, tailwind config conflict, v3 v4 mixed syntax, tailwind upgrade codemod.
license	MIT
compatibility	Designed for Claude Code. Requires shadcn ui evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

shadcn ui Errors: Tailwind v3 to v4 Migration

Tailwind CSS v4 (Jan 2025) rewrote the configuration model, the color format, the animation plugin, the dark mode trigger, the ring utility default, and the PostCSS integration. shadcn ui projects bootstrapped before v4 cannot be upgraded by npm install alone: the CSS file, the config file, the PostCSS file, and the package.json plugin list must all change in lockstep, or the project enters a half-migrated state where some classes resolve and others fail silently. This is the single largest hallucination risk in AI-generated shadcn code, because training data spans both generations and the v3 patterns look syntactically valid when pasted into a v4 project.

This skill gives a deterministic migration runbook and the detection rules to identify which generation a project is on before changing any code.

Quick Reference

Major shifts table (v3 -> v4)

Concept	v3 (pre-2025)	v4 (evergreen-2026)
Config location	tailwind.config.js (JS)	@theme inline block in CSS
CSS import	@tailwind base; @tailwind components; @tailwind utilities;	@import "tailwindcss";
Color format	--background: 0 0% 100% (HSL space-separated)	--background: oklch(1 0 0)
Color reference	bg-[hsl(var(--background))] or tailwind.config.js color extension	bg-background (direct, via @theme inline)
Animation plugin	tailwindcss-animate (npm package, in plugins)	tw-animate-css (CSS @import, no plugin entry)
Dark mode trigger	darkMode: ['class'] in tailwind.config.js	@custom-variant dark (&:is(.dark *)); in CSS
Ring default width	ring = 3px, ring-2 = 2px	ring = 1px, ring-3 = 3px
PostCSS plugin