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

setup-

arch-

ally-

style-

form-

data-

layout-

comp-

perf-

state-

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