Tailwind v4 + shadcn/ui Skill

Status: Production Ready ✅ Last Updated: 2026-01-03 Production Tested: WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev)

---

Auto-Trigger Keywords

This skill should be invoked when user mentions ANY of:

Primary Triggers:

• tailwind v4
• tailwind css v4
• shadcn/ui
• shadcn ui
• vite + react + tailwind
• @tailwindcss/vite

Secondary Triggers:

• dark mode setup
• theme provider
• theme switching
• @theme inline
• css variables not working
• colors not applying
• tailwind utilities missing

Error-Based Triggers:

• tw-animate-css (common error)
• @apply deprecated
• dark: variant not working
• colors all black/white
• bg-primary doesn't work
• @import typography (wrong v4 syntax)
• require @tailwindcss/typography (v3 syntax in v4)
• prose class not working
• @plugin directive

---

What This Skill Does

Sets up production-ready Vite + React + Tailwind CSS v4 + shadcn/ui with:

✅ Correct v4 architecture - @theme inline pattern, no config file ✅ Dark mode - ThemeProvider with system/light/dark support ✅ Error prevention - Fixes tw-animate-css, duplicate @layer, @apply deprecation ✅ Semantic colors - Full color palette with proper CSS variables ✅ Path aliases - @/* imports configured ✅ TypeScript - Full type safety ✅ Templates - Proven file templates ready to copy

---

Known Issues This Skill Prevents

Issue	Why It Happens	How Skill Fixes It
tw-animate-css import error	shadcn init adds non-existent import	Provides clean CSS template
Duplicate @layer base	shadcn init adds second block with @apply	Single clean @layer block
Colors don't work	Missing @theme inline mapping	Complete mapping provided
Dark mode broken	No ThemeProvider or wrong setup	Full ThemeProvider template
Wrong config	tailwind.config.ts used for theme	Empty config, CSS-only theme
Double hsl() wrapping	Common pattern mistake	Correct variable usage
Wrong plugin syntax	Using @import or require() for plugins	Correct @plugin directive documented

---

When to Use This Skill

✅ Use When:

• Starting a new Vite + React project with Tailwind v4
• Adding Tailwind v4 to existing Vite project
• Migrating from Tailwind v3 to v4
• Integrating shadcn/ui components
• Setting up dark mode with theme switching
• Debugging Tailwind v4 color/theme issues
• Need production-tested v4 patterns

❌ Don't Use When:

• Using Tailwind v3 (different architecture)
• Using Next.js (different setup, use Next.js skill instead)
• Using PostCSS instead of Vite plugin
• Building pure CSS library (no React needed)
• User specifically requests manual setup for learning

---

Template Structure

~/.claude/skills/tailwind-v4-shadcn/
├── README.md                  # This file - auto-trigger keywords
├── SKILL.md                   # Complete documentation (623 lines)
├── templates/                 # Ready-to-copy file templates
│   ├── index.css              # v4 CSS architecture
│   ├── components.json        # shadcn/ui v4 config
│   ├── vite.config.ts         # Vite + Tailwind plugin
│   ├── tsconfig.app.json      # TypeScript with aliases
│   ├── theme-provider.tsx     # Dark mode provider
│   └── utils.ts               # cn() utility
└── reference/                 # Deep-dive docs
    ├── architecture.md
    ├── dark-mode.md
    ├── common-gotchas.md
    └── migration-guide.md

---

Quick Usage

When Claude detects trigger keywords, it should:

1. Confirm with user: "I found the tailwind-v4-shadcn skill. Use it?"
2. Explain benefits: "This prevents tw-animate-css errors and includes dark mode"
3. Use templates: Copy from templates/ directory
4. Follow SKILL.md: Complete step-by-step in SKILL.md
5. Verify: Test dev server, check dark mode toggle

---

Token Efficiency

Approach	Tokens Used	Errors
Manual setup (no skill)	~65,000	2-3 common errors
With this skill	~20,000	0 (prevented)
Savings	~70%	100% reduction

---

Dependencies Installed

{
  "dependencies": {
    "tailwindcss": "^4.1.18",
    "@tailwindcss/vite": "^4.1.18",
    "clsx": "^2.1.1",
    "tailwind-merge": "^3.4.0",
    "react": "^19.2.0",
    "react-dom": "^19.2.0"
  },
  "devDependencies": {
    "@types/node": "^25.0.3",
    "@vitejs/plugin-react": "^5.1.2",
    "vite": "^7.3.0",
    "typescript": "~5.9.0",
    "tw-animate-css": "^1.4.0"
  }
}

---

Example Skill Invocation

User: "Set up a new Vite + React project with Tailwind v4"
↓
Claude: [Checks ~/.claude/skills/tailwind-v4-shadcn/]
↓
Claude: "I found the tailwind-v4-shadcn skill. Use it?
        (Prevents tw-animate-css error, includes dark mode)"
↓
User: "Yes"
↓
Claude: [Uses templates/ + follows SKILL.md]
↓
Result: Working project in ~1 minute, 0 errors

---

Skill Metadata

name: tailwind-v4-shadcn
version: 2.0.1
category: frontend-setup
stack: [vite, react, tailwind-v4, shadcn-ui]
confidence: high  # Production-tested pattern
auto_invoke_threshold: 0.7  # Invoke if 70%+ match
maintained_by: jeremy@jezweb.net
last_tested: 2026-01-03

---

Related Skills

• react-vite-base - Vite + React without Tailwind
• cloudflare-react-full-stack - Adds Cloudflare Workers
• react-form-zod - React Hook Form + Zod validation

---

Support

• Full Documentation: See SKILL.md (623 lines)
• Troubleshooting: See reference/common-gotchas.md
• Official Docs: https://ui.shadcn.com/docs/tailwind-v4