shadcn/ui Best Practices

Comprehensive best practices guide for shadcn/ui applications, designed for AI agents and LLMs. Contains 48 rules across 8 categories, prioritized by impact to guide component composition, styling, accessibility, and performance optimization.

When to Apply

Reference these guidelines when:

• Installing and configuring shadcn/ui in a project
• Composing component structures with Dialog, Select, or Dropdown
• Implementing theming with CSS variables and dark mode
• Building accessible forms with validation and error handling
• Creating data tables with TanStack Table integration

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 Composition (CRITICAL)

• comp-edit-source-not-wrap – Edit component source instead of wrapping
• comp-use-aschild-for-custom-elements – Use asChild for custom element rendering
• comp-compose-dialog-parts – Compose Dialog with semantic parts
• comp-use-cva-for-variants – Use CVA for component variants
• comp-dropdown-menu-structure – Structure dropdown menus with required parts
• comp-card-semantic-structure – Use Card semantic parts for content organization
• comp-icons-data-attributes – Use data-icon attributes for icon spacing
• comp-select-controlled-value – Use value prop for controlled Select components

3. Styling & Theming (HIGH)

• style-use-cn-for-merging – Use cn() for all class merging
• style-css-variables-naming – Follow CSS variable naming convention
• style-dark-mode-class – Use class-based dark mode switching
• style-extend-not-override – Extend variants instead of overriding base styles
• style-oklch-colors – Use OKLCH color format for theme variables
• style-register-custom-colors – Register custom colors with Tailwind theme
• style-border-radius-variable – Use border radius variable for consistent corners

4. Accessibility Patterns (HIGH)

• access-dialog-title-required – Always include DialogTitle for screen readers
• access-form-field-labels – Associate labels with form controls
• access-aria-invalid-errors – Use aria-invalid for form error states
• access-icon-button-labels – Add accessible labels to icon-only buttons
• access-checkbox-label-association – Wrap Checkbox with Label for click target
• access-focus-visible-styles – Preserve focus visible styles for keyboard navigation

5. Form Integration (MEDIUM-HIGH)

• form-react-hook-form-integration – Integrate React Hook Form with Field components
• form-field-error-display – Display field errors with FieldError component
• form-select-with-form – Use Controller for Select in React Hook Form
• form-submit-button-loading – Disable submit button during form submission
• form-textarea-auto-resize – Use auto-resizing Textarea for long-form input
• form-combobox-async-search – Implement async search with Combobox

6. Data Display Components (MEDIUM)

• data-tanstack-table-setup – Configure TanStack Table with required row models
• data-column-definitions-separate – Define columns in separate file for reusability
• data-row-actions-dropdown – Use dropdown menu for row actions
• data-pagination-component – Extract pagination into reusable component
• data-empty-state – Handle empty table state gracefully

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. Performance Optimization (LOW-MEDIUM)

• perf-dynamic-import-heavy-components – Dynamic import heavy components
• perf-direct-lucide-imports – Import Lucide icons directly from path
• perf-avoid-rerender-callbacks – Stabilize callback props to prevent re-renders
• perf-skeleton-loading-states – Use Skeleton for loading states
• perf-virtualize-long-lists – Virtualize long lists in Select and Command

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