tailwind-v4-shadcn

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.

---

1. Install Dependencies

```bash

pnpm add tailwindcss @tailwindcss/vite

pnpm add -D @types/node

pnpm dlx shadcn@latest init

```

2. Configure Vite

```typescript

// 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

```json

{

"tailwind": {

"config": "", // ← CRITICAL: Empty for v4

"css": "src/index.css",

"baseColor": "slate", // Base color palette

"cssVariables": true,

"prefix": "" // No prefix for utility classes

}

}

```

4. Delete tailwind.config.ts

```bash

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

```

---

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

Step 1: Define CSS Variables at Root Level

```css

/ 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

```css

@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

```css

@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

```tsx

```

---

1. Create ThemeProvider

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

```typescript

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

```

2. Wrap Your App

```typescript

// src/main.tsx

import { ThemeProvider } from '@/components/theme-provider'

ReactDOM.createRoot(document.getElementById('root')!).render(

,

)

```

3. Add Theme Toggle

```bash

pnpm dlx shadcn@latest add dropdown-menu

```

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

---

✅ 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"