Tailwind V4 Shadcn

Tailwind v4 + shadcn/ui Production Stack

Production-tested: WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev) Last Updated: 2025-12-04 Status: Production Ready ✅

Table of Contents

1. Before You Start
2. Quick Start
3. Four-Step Architecture
4. Dark Mode Setup
5. Critical Rules
6. Semantic Color Tokens
7. Common Issues & Fixes
8. File Templates
9. Setup Checklist
10. Advanced Topics
11. Dependencies
12. Tailwind v4 Plugins
13. Reference Documentation
14. When to Load References

⚠️ BEFORE YOU START (READ THIS!)

CRITICAL FOR AI AGENTS: If you're Claude Code helping a user set up Tailwind v4:

1. Explicitly state you're using this skill at the start of the conversation
2. Reference patterns from the skill rather than general knowledge
3. Prevent known issues listed in reference/common-gotchas.md
4. Don't guess - if unsure, check the skill documentation

USER ACTION REQUIRED: Tell Claude to check this skill first!

Say: "I'm setting up Tailwind v4 + shadcn/ui - check the tailwind-v4-shadcn skill first"

Why This Matters (Real-World Results)

Without skill activation:

• ❌ Setup time: ~5 minutes
• ❌ Errors encountered: 2-3 (tw-animate-css, duplicate @layer base)
• ❌ Manual fixes needed: 2+ commits
• ❌ Token usage: ~65k
• ❌ User confidence: Required debugging

With skill activation:

• ✅ Setup time: ~1 minute
• ✅ Errors encountered: 0
• ✅ Manual fixes needed: 0
• ✅ Token usage: ~20k (70% reduction)
• ✅ User confidence: Instant success

Known Issues This Skill Prevents

1. tw-animate-css import error (deprecated in v4)
2. Duplicate @layer base blocks (shadcn init adds its own)
3. Wrong template selection (vanilla TS vs React)
4. Missing post-init cleanup (incompatible CSS rules)
5. Wrong plugin syntax (using @import or require() instead of @plugin directive)

All of these are handled automatically when the skill is active.

Quick Start (5 Minutes - Follow This Exact Order)

1. Install Dependencies

bun add tailwindcss @tailwindcss/vite
# or: npm install tailwindcss @tailwindcss/vite

bun add -d @types/node

# Note: Using pnpm for shadcn init due to known Bun compatibility issues
# (bunx has "Script not found" and postinstall/msw problems)
pnpm dlx shadcn@latest init

2. Configure Vite

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

3. Update components.json

{
  "tailwind": {
    "config": "",              // ← CRITICAL: Empty for v4
    "css": "src/index.css",
    "cssVariables": true
  }
}

4. Delete tailwind.config.ts

rm tailwind.config.ts  # v4 doesn't use this file

The Four-Step Architecture (CRITICAL)

This pattern is mandatory - skipping steps will break your theme.

Step 1: Define CSS Variables at Root Level

/* src/index.css */
@import "tailwindcss";

:root {
  --background: hsl(0 0% 100%);      /* ← hsl() wrapper required */
  --foreground: hsl(222.2 84% 4.9%);
  --primary: hsl(221.2 83.2% 53.3%);
  /* ... all light mode colors */
}

.dark {
  --background: hsl(222.2 84% 4.9%);
  --foreground: hsl(210 40% 98%);
  --primary: hsl(217.2 91.2% 59.8%);
  /* ... all dark mode colors */
}

Critical Rules:

• ✅ Define at root level (NOT inside @layer base)
• ✅ Use hsl() wrapper on all color values
• ✅ Use .dark for dark mode (NOT .dark { @theme { } })

Step 2: Map Variables to Tailwind Utilities

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  /* ... map ALL CSS variables */
}

Why This Is Required:

• Generates utility classes (bg-background, text-primary)
• Without this, bg-primary etc. won't exist

Step 3: Apply Base Styles

@layer base {
  body {
    background-color: var(--background);  /* NO hsl() here */
    color: var(--foreground);
  }
}

Critical Rules:

• ✅ Reference variables directly: var(--background)
• ❌ Never double-wrap: hsl(var(--background))

Step 4: Result - Automatic Dark Mode

<div className="bg-background text-foreground">
  {/* No dark: variants needed - theme switches automatically */}
</div>

Dark Mode Setup

1. Create ThemeProvider

See reference/dark-mode.md for full implementation or use template:

// Copy from: templates/theme-provider.tsx

2. Wrap Your App

// src/main.tsx
import { ThemeProvider } from '@/components/theme-provider'

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <ThemeProvider defaultTheme="dark" storageKey="vite-ui-theme">
      <App />
    </ThemeProvider>
  </React.StrictMode>,
)

3. Add Theme Toggle

pnpm dlx shadcn@latest add dropdown-menu

See reference/dark-mode.md for ModeToggle component code.

Critical Rules (MUST FOLLOW)

✅ Always Do:

1. Wrap color values with `hsl()` in `:root` and `.dark` ``css --background: hsl(0 0% 100%); /* ✅ Correct */ ``

1. Use `@theme inline` to map all CSS variables ``css @theme inline { --color-background: var(--background); } ``

1. Set `"tailwind.config": ""` in components.json ``json { "tailwind": { "config": "" } } ``

1. Delete `tailwind.config.ts` if it exists

1. Use `@tailwindcss/vite` plugin (NOT PostCSS)

1. Use `cn()` for conditional classes ``typescript import { cn } from "@/lib/utils" <div className={cn("base", isActive && "active")} /> ``

❌ Never Do:

1. Put `:root` or `.dark` inside `@layer base` ``css /* WRONG */ @layer base { :root { --background: hsl(...); } } ``

1. Use `.dark { @theme { } }` pattern ``css /* WRONG - v4 doesn't support nested @theme */ .dark { @theme { --color-primary: hsl(...); } } ``

1. Double-wrap colors ``css /* WRONG */ body { background-color: hsl(var(--background)); } ``

1. Use `tailwind.config.ts` for theme colors ``typescript /* WRONG - v4 ignores this */ export default { theme: { extend: { colors: { primary: 'hsl(var(--primary))' } } } } ``

1. Use `@apply` directive (deprecated in v4)

1. Use `dark:` variants for semantic colors ```tsx / WRONG / <div className="bg-primary dark:bg-primary-dark" />

/ CORRECT / <div className="bg-primary" />

---

## Semantic Color Tokens

Always use semantic names for colors:

:root { --destructive: hsl(0 84.2% 60.2%); / Red - errors, critical / --success: hsl(142.1 76.2% 36.3%); / Green - success states / --warning: hsl(38 92% 50%); / Yellow - warnings / --info: hsl(221.2 83.2% 53.3%); / Blue - info, primary / }

**Usage:**

<div className="bg-destructive text-destructive-foreground">Critical</div> <div className="bg-success text-success-foreground">Success</div> <div className="bg-warning text-warning-foreground">Warning</div> <div className="bg-info text-info-foreground">Info</div>

---

## Common Issues & Quick Fixes

| Symptom | Cause | Fix |
|---------|-------|-----|