Agent skill · software engineering · secondsky
tailwind-v4-shadcn
| 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.
Why this skill is useful
Adds a complete production-ready setup script for Tailwind CSS v4 with shadcn/ui, including configuration patterns and common issue resolutions that aren't widely documented.
What it needs
Requires @tailwindcss/vite, @types/node, pnpm, tailwindcss installed locally. About 8k tokens when loaded. Last updated 2026-08-06. 204 stars on the source repository.
What this skill does
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 2. Configure Vite 3. Update components.json 4. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills secondsky/tailwind-v4-shadcn