tailwind-v4-shadcn
Skill0 starsChanged 27 days agoMITView on GitHub
| 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.
- Installs packages
14 other projects use a version of this, 14 of them edited.
Adopted by
Most recently taken up by
- ever-co/ever-worksedited, first seen Nov 8, 2026
- ever-works/ever-worksedited, first seen Nov 5, 2026
- davidanthonyn/claude-skillsedited, first seen Oct 20, 2026
- MaxMiksa/Autonomous-Companyedited, first seen Oct 15, 2026
- legions-developer/invoicelyedited, first seen Oct 8, 2026
- legions-developer/evilchartsedited, first seen Oct 8, 2026
Used with
Projects with it also use organization-best-practices, tailwind-css-patterns and 8 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
lukevellaSkillorganization-best-practices
This skill provides guidance and enforcement rules for implementing multi-tenant organizations, teams, and role-based access control using Better Auth's organization plugin.
Also in 4 projects that use this
midudevSkilltailwind-css-patterns
Provides comprehensive Tailwind CSS utility-first styling patterns including responsive design, layout utilities, flexbox, grid, spacing, typography, colors, and modern CSS best practices. Use when styling React/Vue/Svelte components, building responsive layouts, implementing design systems, or optimizing CSS workflow.
Also in 5 projects that use this
lukevellaSkilltwo-factor-authentication-best-practices
This skill provides guidance and enforcement rules for implementing secure two-factor authentication (2FA) using Better Auth's twoFactor plugin.
Also in 3 projects that use this
xenitV1Skillnodejs-best-practices
Node.js development principles and decision-making. Framework selection, async patterns, security, and architecture. Teaches thinking, not copying.
Also in 5 projects that use this
xfstudioSkillnodejs-backend-patterns
Build production-ready Node.js backend services with Express/Fastify, implementing middleware patterns, error handling, authentication, database integration, and API design best practices. Use when creating Node.js servers, REST APIs, GraphQL backends, or microservices architectures.
Also in 5 projects that use this
VercelSkillnext-cache-components
Next.js 16 Cache Components - PPR, use cache directive, cacheLife, cacheTag, updateTag
Also in 4 projects that use this
- +1 more from lukevella
Other versions14 projects use a version of this.
Word for word · 0
None found.
Edited · 14
- legions-developer/evilcharts★ 3.2k99% same
- MaxMiksa/Auto-Company★ 3.2k98% same
- MaxMiksa/Autonomous-Company★ 3.2k98% same
- legions-developer/invoicely★ 92399% same
- ever-co/ever-works★ 19999% same
- ever-works/ever-works★ 19999% same
- nicepkg/auto-company★ 18899% same
- NikitaDmitrieff/auto-co-meta★ 4399% same
- ai4brands-design/claude-skills★ 220% same
- Aver005/agent-skills★ 299% same
4 more not listed
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository33 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .agents/skills/vercel-react-best-practices/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- accessibilitySkill
- ask-mattSkill
- cavemanSkill
- codebase-designSkill
- code-reviewSkill
- diagnosing-bugsSkill
- domain-modelingSkill
- frontend-designSkill
- grill-with-docsSkill
- implementSkill
- implement-specSkill
- improve-codebase-architectureSkill
- prototypeSkill
- researchSkill
- retroSkill
- setup-matt-pocock-skillsSkill
- shadcnSkill
- tanstack-routerSkill
- tanstack-start-best-practicesSkill
- tanstack-startSkill
- tddSkill
- to-specSkill
- to-ticketsSkill
- triageSkill
- typescript-advanced-typesSkill
- ui-ux-pro-maxSkill
- vercel-react-best-practicesSkill
- wayfinderSkill
- web-design-guidelinesSkill
- wizardSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. 9 are common, 1 is distinctive, and 3 are very specific to this project.
9
Common
Most of the 14 edited versions we read keep these.
1
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Common: line 55
CRITICAL FOR AI AGENTS: If you're Claude Code helping a user set up Tailwind v4:
- Common: line 60
Don't guess: - if unsure, check the skill documentation
- Common: line 90
All of these are handled automatically when the skill is active.
- Common: line 339
Always use semantic names for colors:
- Very specific: line 376
All templates are available in the templates/ directory:
- Common: line 412
Custom Colors: Add semantic colors beyond default palette
- Common: line 491
common-gotchas.md: - All the ways it can break (and fixes)
- Distinctive: line 548
When installing Tailwind and shadcn/ui packages, follow supply chain security best practices:
- Common: line 564
All patterns in this skill have been validated in production.
- Common: line 571
Verify all steps in the 4-step architecture
- Very specific: line 572
Ensure components.json has "config": ""
- Very specific: line 573
Delete tailwind.config.ts if it exists
- Common: line 574
Check official docs: https://ui.shadcn.com/docs/tailwind-v4
“Common” is measured: kept by at least 6 in 10 of the 14 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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
- Before You Start
- Quick Start
- Four-Step Architecture
- Dark Mode Setup
- Critical Rules
- Semantic Color Tokens
- Common Issues & Fixes
- File Templates
- Setup Checklist
- Advanced Topics
- Dependencies
- Tailwind v4 Plugins
- Reference Documentation
- 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:
- Explicitly state you're using this skill at the start of the conversation
- Reference patterns from the skill rather than general knowledge
- Prevent known issues listed in
reference/common-gotchas.md - 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
- tw-animate-css import error (deprecated in v4)
- Duplicate @layer base blocks (shadcn init adds its own)
- Wrong template selection (vanilla TS vs React)
- Missing post-init cleanup (incompatible CSS rules)
- 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 init2. 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 fileThe 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
.darkfor 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-primaryetc. 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.tsx2. 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-menuSee reference/dark-mode.md for ModeToggle component code.
Critical Rules (MUST FOLLOW)
✅ Always Do:
- Wrap color values with
hsl()in:rootand.dark--background: hsl(0 0% 100%); /* ✅ Correct */ - Use
@theme inlineto map all CSS variables@theme inline { --color-background: var(--background); } - Set
"tailwind.config": ""in components.json{ "tailwind": { "config": "" } } - Delete
tailwind.config.tsif it exists - Use
@tailwindcss/viteplugin (NOT PostCSS) - Use
cn()for conditional classesimport { cn } from "@/lib/utils" <div className={cn("base", isActive && "active")} />
❌ Never Do:
- Put
:rootor.darkinside@layer base/* WRONG */ @layer base { :root { --background: hsl(...); } } - Use
.dark { @theme { } }pattern/* WRONG - v4 doesn't support nested @theme */ .dark { @theme { --color-primary: hsl(...); } } - Double-wrap colors
/* WRONG */ body { background-color: hsl(var(--background)); } - Use
tailwind.config.tsfor theme colors/* WRONG - v4 ignores this */ export default { theme: { extend: { colors: { primary: 'hsl(var(--primary))' } } } } - Use
@applydirective (deprecated in v4) - Use
dark:variants for semantic colors/* 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 |
bg-primary doesn't work | Missing @theme inline mapping | Add @theme inline block |
| Colors all black/white | Double hsl() wrapping | Use var(--color) not hsl(var(--color)) |
| Dark mode not switching | Missing ThemeProvider | Wrap app in <ThemeProvider> |
| Build fails | tailwind.config.ts exists | Delete the file |
| Text invisible | Wrong contrast colors | Check color definitions in :root/.dark |
See reference/common-gotchas.md for complete troubleshooting guide.
File Templates
All templates are available in the templates/ directory:
- index.css - Complete CSS setup with all color variables
- components.json - shadcn/ui v4 configuration
- vite.config.ts - Vite + Tailwind plugin setup
- tsconfig.app.json - TypeScript with path aliases
- theme-provider.tsx - Dark mode provider with localStorage
- utils.ts -
cn()utility for class merging
Copy these files to your project and customize as needed.
Complete Setup Checklist
- Vite + React + TypeScript project created
@tailwindcss/viteinstalled (NOT postcss)vite.config.tsusestailwindcss()plugintsconfig.jsonhas path aliases configuredcomponents.jsonexists with"config": ""- NO
tailwind.config.tsfile exists src/index.cssfollows v4 pattern::rootand.darkat root level (not in @layer)- Colors wrapped with
hsl() @theme inlinemaps all variables@layer baseuses unwrapped variables
- Theme provider installed and wrapping app
- Dark mode toggle component created
- Test theme switching works in browser
Advanced Topics
Load references/advanced-usage.md for advanced patterns including:
- Custom Colors: Add semantic colors beyond default palette
- v3 Migration: See
references/migration-guide.mdfor complete guide - Component Best Practices: Semantic tokens, cn() utility, composition patterns
Quick Example:
:root { --brand: hsl(280 65% 60%); }
@theme inline { --color-brand: var(--brand); }Usage: <div className="bg-brand">Branded</div>
For detailed patterns and component composition examples, load references/advanced-usage.md.
Dependencies
✅ Install These
{
"dependencies": {
"tailwindcss": "^4.1.17",
"@tailwindcss/vite": "^4.1.17",
"clsx": "^2.1.1",
"tailwind-merge": "^3.3.1",
"@radix-ui/react-*": "latest",
"lucide-react": "^0.554.0",
"react": "^19.2.0",
"react-dom": "^19.2.0"
},
"devDependencies": {
"@types/node": "^24.10.1",
"@vitejs/plugin-react": "^5.2.0",
"vite": "^7.2.4",
"typescript": "~5.9.3"
}
}❌ NEVER Install These (Deprecated in v4)
# These packages will cause build errors:
bun add tailwindcss-animate # ❌ Deprecated
# or: npm install tailwindcss-animate # ❌ Deprecated
bun add tw-animate-css # ❌ Doesn't existIf you see import errors for these packages, remove them and use native CSS animations or @tailwindcss/motion instead.
Tailwind v4 Plugins
Tailwind v4 supports official plugins using the @plugin directive in CSS.
Quick Example:
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";Common Error:
❌ WRONG: @import "@tailwindcss/typography" (doesn't work)
✅ CORRECT: @plugin "@tailwindcss/typography" (use @plugin directive)
Built-in Features: Container queries are now core (no @tailwindcss/container-queries plugin needed).
Load references/plugins-reference.md for complete documentation including Typography plugin (prose classes), Forms plugin, installation steps, and common plugin errors.
Reference Documentation
For deeper understanding, see:
- common-gotchas.md - All the ways it can break (and fixes)
- dark-mode.md - Complete dark mode implementation
- migration-guide.md - Migrating hardcoded colors to CSS variables
- plugins-reference.md - Official Tailwind v4 plugins (Typography, Forms)
- advanced-usage.md - Custom colors and advanced patterns
When to Load References
Load reference files based on user's specific needs:
Load references/common-gotchas.md when:
- User reports "colors not working" or "bg-primary doesn't exist"
- Dark mode not switching properly
- Build fails with Tailwind errors
- User encounters any CSS/configuration issue
- Debugging theme problems
Load references/dark-mode.md when:
- User asks to implement dark mode
- Theme switching not working
- Need ThemeProvider component code
- Questions about system theme detection
Load references/migration-guide.md when:
- Migrating from Tailwind v3 to v4
- User has hardcoded colors to migrate
- Questions about v3 → v4 changes
- Need migration checklist
Load references/plugins-reference.md when:
- User needs Typography plugin (prose class)
- User needs Forms plugin
- Questions about @plugin directive
- Plugin installation errors
Load references/advanced-usage.md when:
- User asks about custom colors beyond defaults
- Need advanced component patterns
- Questions about component best practices
- Component composition questions
Official Documentation
- shadcn/ui Vite Setup: https://ui.shadcn.com/docs/installation/vite
- shadcn/ui Tailwind v4 Guide: https://ui.shadcn.com/docs/tailwind-v4
- shadcn/ui Dark Mode (Vite): https://ui.shadcn.com/docs/dark-mode/vite
- Tailwind v4 Docs: https://tailwindcss.com/docs
- shadcn/ui Theming: https://ui.shadcn.com/docs/theming
Secure Installation
When installing Tailwind and shadcn/ui packages, follow supply chain security best practices:
- Block post-install scripts —
npm config set ignore-scripts true(or Bun: disabled by default) - Cooldown period — Wait 7 days for new package versions to be vetted by the community
- Audit before installing — Run
socket package score npm <pkg>or usesocket npm install <pkg>to check packages
Load the dependency-upgrade skill for full security configuration including Socket CLI integration, cooldown setup, lockfile validation, and CI enforcement.
Production Example
This skill is based on the WordPress Auditor project:
- Live: https://wordpress-auditor.webfonts.workers.dev
- Stack: Vite + React 19 + Tailwind v4 + shadcn/ui + Cloudflare Workers
- Dark Mode: Full system/light/dark support
- Version: Tailwind v4.1.17 + shadcn/ui latest (Nov 2025)
All patterns in this skill have been validated in production.
Questions? Issues?
- Check
reference/common-gotchas.mdfirst - Verify all steps in the 4-step architecture
- Ensure
components.jsonhas"config": "" - Delete
tailwind.config.tsif it exists - Check official docs: https://ui.shadcn.com/docs/tailwind-v4
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

