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

Priority	Category	Impact	Prefix
1	CLI & Project Setup	CRITICAL	setup-
2	Component Composition	CRITICAL	comp-
3	Styling & Theming	HIGH	style-
4	Accessibility Patterns	HIGH	access-
5	Form Integration	MEDIUM-HIGH	form-
6	Data Display Components	MEDIUM	data-
7	Layout & Navigation	MEDIUM	layout-
8	Performance Optimization	LOW-MEDIUM	perf-

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

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information