shadcn/ui

Version 0.1.0
shadcn/ui Community
January 2026

Note:
This document is mainly for agents and LLMs to follow when maintaining,
generating, or refactoring codebases. Humans may also find it useful,
but guidance here is optimized for automation and consistency by AI-assisted workflows.

Abstract

Comprehensive best practices guide for shadcn/ui applications, designed for AI agents and LLMs. Contains 42 rules across 8 categories, prioritized by impact from critical (component architecture, accessibility preservation) to incremental (state management). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.

Table of Contents

1. Component Architecture — CRITICAL
   • 1.1 Extend Variants with Class Variance Authority — CRITICAL (maintains type safety and design consistency)
   • 1.2 Forward Refs for Composable Components — CRITICAL (enables integration with form libraries and focus management)
   • 1.3 Isolate Component Variants from Base Styles — CRITICAL (prevents style bleeding and maintains component reusability)
   • 1.4 Preserve Radix Primitive Structure — CRITICAL (maintains keyboard navigation and focus management)
   • 1.5 Use asChild for Custom Trigger Elements — CRITICAL (preserves accessibility and event handling)
   • 1.6 Use cn() for Safe Class Merging — CRITICAL (prevents Tailwind class conflicts)
2. Accessibility Preservation — CRITICAL
   • 2.1 Ensure Color Contrast Meets WCAG Standards — CRITICAL (enables readability for low vision users)
   • 2.2 Maintain Focus Management in Modals — CRITICAL (prevents 100% keyboard user navigation failure)
   • 2.3 Preserve ARIA Attributes from Radix Primitives — CRITICAL (maintains screen reader compatibility)
   • 2.4 Preserve Keyboard Navigation Patterns — CRITICAL (enables non-mouse users to navigate components)
   • 2.5 Provide Screen Reader Labels for Icon Buttons — CRITICAL (enables navigation for visually impaired users)
3. Styling & Theming — HIGH
   • 3.1 Apply Mobile-First Responsive Design — HIGH (prevents mobile usability failures on 50%+ of traffic)
   • 3.2 Avoid !important Overrides — HIGH (maintains style specificity and component customization)
   • 3.3 Extend Tailwind Theme for Custom Design Tokens — HIGH (maintains design system consistency)
   • 3.4 Support Dark Mode with CSS Variables — HIGH (provides user preference compliance and reduces eye strain)
   • 3.5 Use Consistent Spacing Scale — HIGH (creates visual rhythm and reduces design inconsistency)
   • 3.6 Use CSS Variables for Theme Colors — HIGH (enables runtime theme switching and consistency)
4. Form Patterns — HIGH
   • 4.1 Handle Async Validation with Debouncing — HIGH (prevents excessive API calls during validation)
   • 4.2 Reset Form State Correctly After Submission — HIGH (prevents stale data and submission errors)
   • 4.3 Show Validation Errors at Appropriate Times — HIGH (improves user experience and reduces frustration)
   • 4.4 Use React Hook Form with shadcn/ui Forms — HIGH (eliminates re-renders and provides validation)
   • 4.5 Use Zod for Schema Validation — HIGH (eliminates runtime type errors with full TS inference)
5. Data Display — MEDIUM-HIGH
   • 5.1 Paginate Large Datasets Server-Side — MEDIUM-HIGH (reduces initial payload by 90%+ for large datasets)
   • 5.2 Provide Actionable Empty States — MEDIUM-HIGH (increases user action rate by 2-4×)
   • 5.3 Use Skeleton Components for Loading States — MEDIUM-HIGH (reduces perceived load time and prevents layout shift)
   • 5.4 Use TanStack Table for Complex Data Tables — MEDIUM-HIGH (eliminates 200-500 lines of manual table logic)
   • 5.5 Virtualize Large Lists and Tables — MEDIUM-HIGH (10-100× rendering performance for large lists)
6. Component Composition — MEDIUM
   • 6.1 Combine Command with Popover for Searchable Selects — MEDIUM (reduces selection time by 3-5× for long lists)
   • 6.2 Compose with Compound Component Patterns — MEDIUM (reduces prop count by 60-80% vs monolithic components)
   • 6.3 Create Reusable Form Field Components — MEDIUM (reduces boilerplate and ensures consistency)
   • 6.4 Nest Dialogs with Proper Focus Management — MEDIUM (maintains focus trap hierarchy in nested modals)
   • 6.5 Use Drawer for Mobile Modal Interactions — MEDIUM (reduces touch distance by 40-60% on mobile)
   • 6.6 Use Slot Pattern for Flexible Content Areas — MEDIUM (enables custom content injection without prop explosion)
7. Performance Optimization — MEDIUM
   • 7.1 Avoid Unnecessary Re-renders in Forms — MEDIUM (prevents full form re-render on every keystroke)
   • 7.2 Debounce Search and Filter Inputs — MEDIUM (reduces API calls by 80-90% during typing)
   • 7.3 Lazy Load Heavy Components — MEDIUM (reduces initial bundle by 30-50%)
   • 7.4 Memoize Expensive Component Renders — MEDIUM (prevents unnecessary re-renders in lists and data displays)
   • 7.5 Optimize Icon Imports from Lucide — MEDIUM (reduces bundle by 200-500KB with direct imports)
8. State Management — LOW-MEDIUM
   • 8.1 Colocate State with the Components That Use It — LOW-MEDIUM (improves code organization and reduces unnecessary coupling)
   • 8.2 Lift State to the Appropriate Level — LOW-MEDIUM (prevents prop drilling and enables component communication)
   • 8.3 Prefer Uncontrolled Components for Simple Inputs — LOW-MEDIUM (reduces state management overhead for simple cases)
   • 8.4 Use Controlled State for Dialogs Triggered Externally — LOW-MEDIUM (enables programmatic dialog control from parent components)

References

1. https://ui.shadcn.com/
2. https://www.radix-ui.com/primitives/docs/overview/accessibility
3. https://vercel.com/academy/shadcn-ui
4. https://react-hook-form.com/
5. https://tailwindcss.com/
6. https://cva.style/docs
7. https://tanstack.com/table/latest
8. https://tanstack.com/virtual/latest

Source Files

This document was compiled from individual reference files. For detailed editing or extension: