shadcn/ui Community Best Practices

Current best-practices guide for shadcn/ui applications. Before applying primitive-specific guidance, inspect whether the checked-in components use Radix UI or Base UI; current shadcn supports both and their composition APIs differ.

When to Apply

Reference these guidelines when:

• 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. Component Architecture (CRITICAL)

• [arch-use-asChild-for-custom-triggers](references/arch-use-asChild-for-custom-triggers.md) - Use the generated primitive's composition API
• [arch-preserve-radix-primitive-structure](references/arch-preserve-radix-primitive-structure.md) - Maintain Radix compound component hierarchy
• [arch-extend-variants-with-cva](references/arch-extend-variants-with-cva.md) - Use Class Variance Authority for type-safe variants
• [arch-use-cn-for-class-merging](references/arch-use-cn-for-class-merging.md) - Use cn() utility for safe Tailwind class merging
• [arch-forward-refs-for-composable-components](references/arch-forward-refs-for-composable-components.md) - Forward refs for form and focus integration
• [arch-isolate-component-variants](references/arch-isolate-component-variants.md) - Separate base styles from variant-specific styles

2. Accessibility Preservation (CRITICAL)

• [ally-preserve-aria-attributes](references/ally-preserve-aria-attributes.md) - Keep Radix ARIA attributes intact
• [ally-provide-sr-only-labels](references/ally-provide-sr-only-labels.md) - Add screen reader labels for icon buttons
• [ally-maintain-focus-management](references/ally-maintain-focus-management.md) - Preserve focus trapping in modals
• [ally-preserve-keyboard-navigation](references/ally-preserve-keyboard-navigation.md) - Keep WAI-ARIA keyboard patterns
• [ally-ensure-color-contrast](references/ally-ensure-color-contrast.md) - Maintain WCAG color contrast ratios

3. Styling & Theming (HIGH)

• [style-use-css-variables-for-theming](references/style-use-css-variables-for-theming.md) - Use CSS variables for theme colors
• [style-avoid-important-overrides](references/style-avoid-important-overrides.md) - Prefer variants and class composition over important overrides
• [style-use-tailwind-theme-extend](references/style-use-tailwind-theme-extend.md) - Define Tailwind v4 theme tokens in CSS
• [style-consistent-spacing-scale](references/style-consistent-spacing-scale.md) - Use consistent Tailwind spacing scale
• [style-responsive-design-patterns](references/style-responsive-design-patterns.md) - Apply mobile-first responsive design
• [style-dark-mode-support](references/style-dark-mode-support.md) - Support dark mode with CSS variables

4. Form Patterns (HIGH)

• [form-use-react-hook-form-integration](references/form-use-react-hook-form-integration.md) - Integrate with React Hook Form
• [form-use-zod-for-schema-validation](references/form-use-zod-for-schema-validation.md) - Use Zod for type-safe validation
• [form-show-validation-errors-correctly](references/form-show-validation-errors-correctly.md) - Show errors at appropriate times
• [form-handle-async-validation](references/form-handle-async-validation.md) - Debounce async validation calls
• [form-reset-form-state-correctly](references/form-reset-form-state-correctly.md) - Reset form state after submission

5. Data Display (MEDIUM-HIGH)

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

6. Component Composition (MEDIUM)

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

7. Performance Optimization (MEDIUM)

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

8. State Management (LOW-MEDIUM)

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

How to Use

Read individual reference files for detailed explanations and code examples:

Full Compiled Document

For a single-file reference containing all rules, see [AGENTS.md](AGENTS.md).

Reference Files