secondsky/claude-skills / plugins/tailwind-v4-shadcn/skills/tailwind-v4-shadcn
tailwind-v4-shadcn
Verified| Production-tested setup for Tailwind CSS v4 with shadcn/ui, Vite, and React. Use when: initializing React projects with Tailwind v4, setting up shadcn/ui, implementing dark mode, debugging CSS variable issues, fixing theme switching, migrating from Tailwind v3, or encountering color/theming problems. Covers: @theme inline pattern, CSS variable architecture, dark mode with ThemeProvider, component composition, vite.config setup, common v4 gotchas, and production-tested patterns.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.5 KB |
| references/advanced-usage.md | markdown | 3.6 KB |
| references/common-gotchas.md | markdown | 7.4 KB |
| references/dark-mode.md | markdown | 5.3 KB |
| references/migration-guide.md | markdown | 6.8 KB |
| references/plugins-reference.md | markdown | 3.1 KB |
| templates/components.json | config | 396 B |
| templates/index.css | other | 4.5 KB |
| templates/theme-provider.tsx | other | 2.2 KB |
| templates/tsconfig.app.json | config | 719 B |
| templates/utils.ts | script | 166 B |
| templates/vite.config.ts | script | 337 B |
references/common-gotchas.md
View on GitHub# Common Gotchas & Solutions
## Critical Failures (Will Break Your Build)
### 1. `:root` Inside `@layer base`
❌ **WRONG:**
```css
@layer base {
:root {
--background: hsl(0 0% 100%);
}
}
```
✅ **CORRECT:**
```css
:root {
--background: hsl(0 0% 100%);
}
@layer base {
body {
background-color: var(--background);
}
}
```
**Why:** Tailwind v4 strips CSS outside `@theme`/`@layer`, but `:root` must be at root level.
---
### 2. Nested `@theme` Directive
❌ **WRONG:**
```css
@theme {
--color-primary: hsl(0 0% 0%);
}
.dark {
@theme {
--color-primary: hsl(0 0% 100%);
}
}
```
✅ **CORRECT:**
```css
:root {
--primary: hsl(0 0% 0%);
}
.dark {
--primary: hsl(0 0% 100%);
}
@theme inline {
--color-primary: var(--primary);
}
```
**Why:** Tailwind v4 doesn't support `@theme` inside selectors.
---
### 3. Double `hsl()` Wrapping
❌ **WRONG:**
```css
@layer base {
body {
background-color: hsl(var(--background));
}
}
```
✅ **CORRECT:**
```css
@layer base {
body {
background-color: var(--background); /* Already has hsl() */
}
}
```
**Why:** Variables already contain `hsl()`, double-wrapping creates `hsl(hsl(...))`.
---
### 4. Colors in `tailwind.config.ts`
❌ **WRONG:**
```typescript
// tailwind.config.ts
export default {
theme: {
extend: {
colors: {
primary: 'hsl(var(--primary))'
}
}
}
}
```
✅ **CORRECT:**
```typescript
// Delete tailwind.config.ts entirely OR leave it empty
export default {}
// components.json
{
"tailwind": {
"config": "" // ← Empty string
}
}
```
**Why:** Tailwind v4 completely ignores `theme.extend.colors`.
---
### 5. Missing `@theme inline` Mapping
❌ **WRONG:**
```css
:root {
--background: hsl(0 0% 100%);
}
/* No @theme inline block */
```
Result: `bg-background` class doesn't exist
✅ **CORRECT:**
```css
:root {
--background: hsl(0 0% 100%);
}
@theme inline {
--color-background: var(--background);
}
```
**Why:** `@theme inline` generates the utility classes.
---
## Configuration Gotchas
### 6. Wrong components.json Config
❌ **WRONG:**
```json
{
"tailwind": {
"config": "tailwind.config.ts" // ← No!
}
}
```
✅ **CORRECT:**
```json
{
"tailwind": {
"config": "" // ← Empty for v4
}
}
```
---
### 7. Using PostCSS Instead of Vite Plugin
❌ **WRONG:**
```typescript
// vite.config.ts
export default defineConfig({
css: {
postcss: './postcss.config.js' // Old v3 way
}
})
```
✅ **CORRECT:**
```typescript
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [react(), tailwindcss()] // v4 way
})
```
---
### 8. Missing Path Aliases
❌ **WRONG:**
```typescript
// tsconfig.json has no paths
import { Button } from '../../components/ui/button'
```
✅ **CORRECT:**
```json
// tsconfig.app.json
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"]
}
}
}
```
```typescript
import { Button } from '@/components/ui/button'
```
---
## Color System Gotchas
### 9. Using `dark:` Variants for Semantic Colors
❌ **WRONG:**
```tsx
<div className="bg-primary dark:bg-primary-dark" />
```
✅ **CORRECT:**
```tsx
<div className="bg-primary" />
```
**Why:** With proper CSS variable setup, `bg-primary` automatically responds to theme.
---
### 10. Hardcoded Color Values
❌ **WRONG:**
```tsx
<div className="bg-blue-600 dark:bg-blue-400" />
```
✅ **CORRECT:**
```tsx
<div className="bg-primary" /> {/* Or bg-info, bg-success, etc. */}
```
**Why:** Semantic tokens enable theme switching and reduce repetition.
---
## Component Gotchas
### 11. Missing `cn()` Utility
❌ **WRONG:**
```tsx
<div className={`base ${isActive && 'active'}`} />
```
✅ **CORRECT:**
```tsx
import { cn } from '@/lib/utils'
<div className={cn("base", isActive && "active")} />
```
**Why:** `cn()` properly merges and deduplicates Tailwind classes.
---
### 12. Empty String in Radix Select
❌ **WRONG:**
```tsx
<SelectItem value="">Select an option</SelectItem>
```
✅ **CORRECT:**
```tsx
<SelectItem value="placeholder">Select an option</SelectItem>
```
**Why:** Radix UI Select doesn't allow empty string values.
---
## Installation Gotchas
### 13. Wrong Tailwind Package
❌ **WRONG:**
```bash
npm install tailwindcss@^3.4.0 # v3
```
✅ **CORRECT:**
```bash
npm install tailwindcss@^4.1.0 # v4
npm install @tailwindcss/vite
```
---
### 14. Missing Dependencies
❌ **WRONG:**
```json
{
"dependencies": {
"tailwindcss": "^4.1.0"
// Missing @tailwindcss/vite
}
}
```
✅ **CORRECT:**
```json
{
"dependencies": {
"tailwindcss": "^4.1.0",
"@tailwindcss/vite": "^4.1.0",
"clsx": "^2.1.1",
"tailwind-merge": "^3.3.1"
},
"devDependencies": {
"@types/node": "^24.0.0"
}
}
```
---
### 17. tw-animate-css Import Error (REAL-WORLD ISSUE)
❌ **WRONG:**
```bash
npm install tailwindcss-animate # Deprecated package
```
```css
@import "tw-animate-css"; # Package doesn't exist in v4
```
✅ **CORRECT:**
```bash
# Don't install tailwindcss-animate at all
# Use native CSS animations or @tailwindcss/motion
```
**Why:**
- `tailwindcss-animate` is deprecated in Tailwind v4
- Causes import errors during build
- shadcn/ui docs may still reference it (outdated)
- The skill handles animations differently in v4
**Impact:** Build failure, requires manual CSS file cleanup
---
### 18. Duplicate @layer base After shadcn init (REAL-WORLD ISSUE)
❌ **WRONG:**
```css
/* After running shadcn init, you might have: */
@layer base {
body {
background-color: var(--background);
}
}
@layer base { /* ← Duplicate added by shadcn init */
* {
border-color: hsl(var(--border));
}
}
```
✅ **CORRECT:**
```css
/* Merge into single @layer base block */
@layer base {
* {
border-color: var(--border);
}
body {
background-color: var(--background);
color: var(--foreground);
}
}
```
**Why:**
- `shadcn init` adds its own `@layer base` block
- Results in duplicate layer declarations
- Can cause unexpected CSS priority issues
- Easy to miss during setup
**Prevention:**
- Check `src/index.css` immediately after running `shadcn init`
- Merge any duplicate `@layer base` blocks
- Keep only one base layer section
**Impact:** CSS priority issues, harder to debug styling problems
---
## Testing Gotchas
### 15. Not Testing Both Themes
❌ **WRONG:**
Only testing in light mode
✅ **CORRECT:**
Test in:
- Light mode
- Dark mode
- System mode
- Both initial load and toggle
---
### 16. Not Checking Contrast
❌ **WRONG:**
Colors look good but fail WCAG
✅ **CORRECT:**
- Use browser DevTools Lighthouse
- Check contrast ratios (4.5:1 minimum)
- Test with actual users
---
## Quick Diagnosis
**Symptoms → Likely Cause:**
| Symptom | Likely Cause |
|---------|-------------|
| `bg-primary` doesn't work | Missing `@theme inline` mapping |
| Colors all black/white | Double `hsl()` wrapping |
| Dark mode not switching | Missing ThemeProvider |
| Build fails | `tailwind.config.ts` exists with theme config |
| Text invisible | Wrong contrast colors |
| `@/` imports fail | Missing path aliases in tsconfig |
---
## Prevention Checklist
Before deploying:
- [ ] No `tailwind.config.ts` file (or it's empty)
- [ ] `components.json` has `"config": ""`
- [ ] All colors have `hsl()` wrapper in `:root`
- [ ] `@theme inline` maps all variables
- [ ] `@layer base` doesn't wrap `:root`
- [ ] Theme provider wraps app
- [ ] Tested in both light and dark modes
- [ ] All text has sufficient contrast
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |