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