shadcn-v3

Skill: shadcn

Scope

• Applies to: Tailwind v4 with shadcn/ui setup, CSS variable architecture, dark mode, theme configuration, component composition patterns, accessibility, form integration
• Does NOT cover: Tailwind v3, PostCSS configuration

Assumptions

• Tailwind CSS v4+
• shadcn/ui latest
• Next.js 16 (this repo); CSS-first Tailwind v4, not Vite
• React 18+ or Next.js 14+
• TypeScript 6+

Principles

• Use @theme inline to map CSS variables to Tailwind tokens
• Use hsl() wrapper for color values in :root and .dark
• Set "tailwind.config": "" in components.json (empty for v4)
• Delete tailwind.config.ts if it exists (v4 uses CSS-based config)
• Use CSS-first Tailwind v4 in the Next app (not @tailwindcss/vite)
• Use cn() utility for conditional classes
• Semantic colors automatically adapt to dark mode (no dark: variants needed)
• Use @plugin directive for plugins (not @import or require())
• Compose complex components from smaller shadcn primitives
• Extend components via wrapper pattern (don't modify originals)
• Use CVA (class-variance-authority) for variant systems
• Use forwardRef only when a parent must attach a ref (React 19 does not require it by default)
• Leverage Radix UI primitives for built-in accessibility

Constraints

MUST

• Wrap color values with hsl() in :root and .dark
• Use @theme inline to map all CSS variables
• Set "tailwind.config": "" in components.json
• Delete tailwind.config.ts if it exists
• Use CSS-first Tailwind v4 in Next apps (@import "tailwindcss" in CSS)

SHOULD

• Use semantic color tokens (--background, --foreground, etc.)
• Use cn() utility for conditional classes
• Use @plugin directive for plugins
• Compose components from smaller shadcn primitives
• Use wrapper pattern to extend components (don't modify originals)
• Use CVA for variant systems in custom components
• Use forwardRef when a parent must attach a ref
• Test accessibility with keyboard navigation and screen readers
• Use Radix UI primitives for complex interactions (dialogs, dropdowns, etc.)
• Provide ARIA labels for icon-only buttons and interactive elements
• Use @tailwindcss/vite only when the app is Vite-based (not Next.js)