Shadcn

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 [blocked] - Configure components.json before adding components
• setup-path-aliases [blocked] - Configure TypeScript path aliases to match components.json
• setup-cn-utility [blocked] - Create the cn utility before using components
• setup-use-cli-not-copy [blocked] - Use CLI to add components instead of copy-paste
• setup-css-variables-theme [blocked] - Enable CSS variables for consistent theming
• setup-rsc-configuration [blocked] - Set RSC flag based on framework support

2. Component Architecture (CRITICAL)

• arch-use-asChild-for-custom-triggers [blocked] - Use asChild prop for custom trigger elements
• arch-preserve-radix-primitive-structure [blocked] - Maintain Radix compound component hierarchy
• arch-extend-variants-with-cva [blocked] - Use Class Variance Authority for type-safe variants
• arch-use-cn-for-class-merging [blocked] - Use cn() utility for safe Tailwind class merging
• arch-forward-refs-for-composable-components [blocked] - Forward refs for form and focus integration
• arch-isolate-component-variants [blocked] - Separate base styles from variant-specific styles

3. Accessibility Preservation (CRITICAL)

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

4. Styling & Theming (HIGH)

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

5. Form Patterns (HIGH)

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

6. Data Display (MEDIUM-HIGH)

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

7. Layout & Navigation (MEDIUM)

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

8. Component Composition (MEDIUM)

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

9. Performance Optimization (MEDIUM)

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

10. State Management (LOW-MEDIUM)

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

How to Use

Read individual reference files for detailed explanations and code examples:

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

Full Compiled Document

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

Reference Files