shadcn/ui Community Best Practices

Comprehensive best practices guide for shadcn/ui applications, maintained by the shadcn/ui community. Contains 58 rules across 10 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

• •Installing and configuring shadcn/ui in a project
• •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

Quick Reference

1. CLI & Project Setup (CRITICAL)

• •setup-components-json - Configure components.json before adding components
• •setup-path-aliases - Configure TypeScript path aliases to match components.json
• •setup-cn-utility - Create the cn utility 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 - Forward refs for form and focus integration
• •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 - Extend Tailwind theme for design tokens
• •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 with React Hook Form
• •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

Full Compiled Document

For a single-file reference containing all rules, see AGENTS.md.

Reference Files