shadcn

shadcn/ui Community Best Practices

58 rules across 10 categories for shadcn/ui, prioritized by impact to guide automated refactoring and code generation.

Stack baseline

Rules target current shadcn/ui: Tailwind CSS v4 (CSS-first, no tailwind.config.*, tokens in @theme inline), React 19 (ref as a prop, data-slot attributes), the unified radix-ui package, OKLCH color tokens, tw-animate-css, Field + React Hook Form Controller forms, and Bun (bunx --bun shadcn@latest ...). Examples use the Radix base (--base radix); the CLI also supports a Base UI base (--base base), where triggers take a render prop instead of asChild. For a Tailwind v3 project, keep the existing config and follow the shadcn upgrade guide first.

Setup mode

Use when installing, repairing or migrating shadcn/ui (new project, existing project, Tailwind v3 to v4). Follow references/_setup-mode.md: pick the bunx --bun shadcn@latest init path, then wire Tailwind v4 CSS-first (@theme inline, @custom-variant dark), components.json with an empty tailwind.config, the cn() helper, and the validation checklist. Do only the requested setup and confirm before overwriting existing styles, config or components. After setup, the rules below apply.

When to Apply

• Installing and configuring shadcn/ui in a project (see Setup mode)
• Writing new shadcn/ui components or composing primitives
• Implementing forms with React Hook Form and Zod validation
• Building data tables or handling large dataset displays
• Customizing themes or adding dark mode support
• Reviewing code for accessibility compliance

Rule Categories by Priority

Priority	Category	Impact	Prefix
1	CLI & Project Setup	CRITICAL	setup-
2	Component Architecture	CRITICAL	arch-
3	Accessibility Preservation	CRITICAL	ally-
4	Styling & Theming	HIGH	style-
5	Form Patterns	HIGH	form-
6	Data Display	MEDIUM-HIGH	data-
7	Layout & Navigation	MEDIUM	layout-
8	Component Composition	MEDIUM	comp-
9	Performance Optimization	MEDIUM	perf-
10	State Management	LOW-MEDIUM	state-

Quick Reference

1. CLI & Project Setup (CRITICAL)

• setup-components-json - Configure components.json (empty tailwind.config for v4) before adding components
• setup-path-aliases - Configure TypeScript path aliases to match components.json
• setup-cn-utility - Create the cn utility (re-export from cn) before using components
• setup-use-cli-not-copy - Use CLI to add components instead of copy-paste
• setup-css-variables-theme - Enable CSS variables for consistent theming
• setup-rsc-configuration - Set RSC flag based on framework support

2. Component Architecture (CRITICAL)

• arch-use-asChild-for-custom-triggers - Use asChild prop for custom trigger elements
• arch-preserve-radix-primitive-structure - Maintain Radix compound component hierarchy
• arch-extend-variants-with-cva - Use Class Variance Authority for type-safe variants
• arch-use-cn-for-class-merging - Use cn() utility for safe Tailwind class merging
• arch-forward-refs-for-composable-components - Pass refs through to the underlying element (React 19 ref prop)
• arch-isolate-component-variants - Separate base styles from variant-specific styles

3. Accessibility Preservation (CRITICAL)

• ally-preserve-aria-attributes - Keep Radix ARIA attributes intact
• ally-provide-sr-only-labels - Add screen reader labels for icon buttons
• ally-maintain-focus-management - Preserve focus trapping in modals
• ally-preserve-keyboard-navigation - Keep WAI-ARIA keyboard patterns
• ally-ensure-color-contrast - Maintain WCAG color contrast ratios
• ally-dialog-title-required - Always include DialogTitle for screen readers
• ally-form-field-labels - Associate labels with form controls
• ally-aria-invalid-errors - Use aria-invalid for form error states
• ally-checkbox-label-association - Wrap Checkbox with Label for click target
• ally-focus-visible-styles - Preserve focus visible styles for keyboard navigation

4. Styling & Theming (HIGH)

• style-use-css-variables-for-theming - Use CSS variables for theme colors
• style-avoid-important-overrides - Never use !important for style overrides
• style-use-tailwind-theme-extend - Define design tokens in CSS with @theme inline
• style-consistent-spacing-scale - Use consistent Tailwind spacing scale
• style-responsive-design-patterns - Apply mobile-first responsive design
• style-dark-mode-support - Support dark mode with CSS variables

5. Form Patterns (HIGH)

• form-use-react-hook-form-integration - Integrate React Hook Form with Field and Controller
• form-use-zod-for-schema-validation - Use Zod for type-safe validation
• form-show-validation-errors-correctly - Show errors at appropriate times
• form-handle-async-validation - Debounce async validation calls
• form-reset-form-state-correctly - Reset form state after submission

6. Data Display (MEDIUM-HIGH)

• data-use-tanstack-table-for-complex-tables - Use TanStack Table for sorting/filtering
• data-virtualize-large-lists - Virtualize lists with 100+ items
• data-use-skeleton-loading-states - Use Skeleton for loading states
• data-paginate-server-side - Paginate large datasets server-side
• data-empty-states-with-guidance - Provide actionable empty states

7. Layout & Navigation (MEDIUM)

• layout-sidebar-provider - Wrap layout with SidebarProvider
• layout-sidebar-collapsible - Configure sidebar collapsible behavior
• layout-sidebar-groups - Organize sidebar navigation with groups
• layout-sheet-mobile-nav - Use Sheet for mobile navigation overlay
• layout-breadcrumb-navigation - Implement breadcrumbs for deep navigation

8. Component Composition (MEDIUM)

• comp-compose-with-compound-components - Use compound component patterns
• comp-use-drawer-for-mobile-modals - Use Drawer on mobile devices
• comp-combine-command-with-popover - Create searchable selects with Command
• comp-nest-dialogs-correctly - Manage nested dialog focus correctly
• comp-create-reusable-form-fields - Extract reusable form field components
• comp-use-slot-pattern-for-flexibility - Use slot pattern for flexible content

9. Performance Optimization (MEDIUM)

• perf-lazy-load-heavy-components - Lazy load components over 50KB
• perf-memoize-expensive-renders - Memoize list items and expensive components
• perf-optimize-icon-imports - Use direct imports for Lucide icons
• perf-avoid-unnecessary-rerenders-in-forms - Isolate form field watching
• perf-debounce-search-inputs - Debounce search and filter inputs

10. State Management (LOW-MEDIUM)

• state-prefer-uncontrolled-for-simple-inputs - Use uncontrolled for simple forms
• state-lift-state-to-appropriate-level - Lift state to lowest common ancestor
• state-use-controlled-dialog-state - Control dialogs for programmatic access
• state-colocate-state-with-components - Keep state close to where it's used

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules