shadcn

---
name: shadcn
description: Current shadcn/ui component guidance for projects generated with Radix UI or Base UI, including primitive-specific composition, Tailwind CSS v4 theming, accessibility, forms, tables, and state patterns. Inspect the checked-in component implementation before applying Radix asChild or Base UI render APIs.
---

# shadcn/ui Community Best Practices

Current best-practices guide for shadcn/ui applications. Before applying primitive-specific guidance, inspect whether the checked-in components use Radix UI or Base UI; current shadcn supports both (Base UI is the default for new projects) and their composition APIs differ. Component installs and upgrades go through the current CLI (v4), which resolves namespaced registries.

## When to Apply

Reference these guidelines when:
- 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

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Component Architecture | CRITICAL | `arch-` |
| 2 | Accessibility Preservation | CRITICAL | `ally-` |
| 3 | Styling & Theming | HIGH | `style-` |
| 4 | Form Patterns | HIGH | `form-` |
| 5 | Data Display | MEDIUM-HIGH | `data-` |
| 6 | Component Composition | MEDIUM | `comp-` |
| 7 | Performance Optimization | MEDIUM | `perf-` |
| 8 | State Management | LOW-MEDIUM | `state-` |

## Quick Reference

### 1. Component Architecture (CRITICAL)

- [`arch-use-asChild-for-custom-triggers`](references/arch-use-asChild-for-custom-triggers.md) - Use the generated primitive's composition API
- [`arch-current-cli-registry`](references/arch-current-cli-registry.md) - Use the current CLI for component lifecycle (v4, registries, MCP)
- [`arch-unified-radix-package`](references/arch-unified-radix-package.md) - Import primitives from the unified radix-ui package
- [`arch-preserve-radix-primitive-structure`](references/arch-preserve-radix-primitive-structure.md) - Maintain Radix compound component hierarchy
- [`arch-extend-variants-with-cva`](references/arch-extend-variants-with-cva.md) - Use Class Variance Authority for type-safe variants
- [`arch-use-cn-for-class-merging`](references/arch-use-cn-for-class-merging.md) - Use cn() utility for safe Tailwind class merging
- [`arch-forward-refs-for-composable-components`](references/arch-forward-refs-for-composable-components.md) - Forward refs for form and focus integration
- [`arch-isolate-component-variants`](references/arch-isolate-component-variants.md) - Separate base styles from variant-specific styles

### 2. Accessibility Preservation (CRITICAL)

- [`ally-preserve-aria-attributes`](references/ally-preserve-aria-attributes.md) - Keep Radix ARIA attributes intact
- [`ally-provide-sr-only-labels`](references/ally-provide-sr-only-labels.md) - Add screen reader labels for icon buttons
- [`ally-maintain-focus-management`](references/ally-maintain-focus-management.md) - Preserve focus trapping in modals
- [`ally-preserve-keyboard-navigation`](references/ally-preserve-keyboard-navigation.md) - Keep WAI-ARIA keyboard patterns
- [`ally-ensure-color-contrast`](references/ally-ensure-color-contrast.md) - Maintain WCAG color contrast ratios

### 3. Styling & Theming (HIGH)

- [`style-use-css-variables-for-theming`](references/style-use-css-variables-for-theming.md) - Use CSS variables for theme colors
- [`style-avoid-important-overrides`](references/style-avoid-important-overrides.md) - Prefer variants and class composition over important overrides
- [`style-use-tailwind-theme-extend`](references/style-use-tailwind-theme-extend.md) - Define Tailwind v4 theme tokens in CSS
- [`style-consistent-spacing-scale`](references/style-consistent-spacing-scale.md) - Use consistent Tailwind spacing scale
- [`style-responsive-design-patterns`](references/style-responsive-design-patterns.md) - Apply mobile-first responsive design
- [`style-dark-mode-support`](references/style-dark-mode-support.md) - Support dark mode with CSS variables

### 4. Form Patterns (HIGH)

- [`form-use-react-hook-form-integration`](references/form-use-react-hook-form-integration.md) - Integrate with React Hook Form
- [`form-use-zod-for-schema-validation`](references/form-use-zod-for-schema-validation.md) - Use Zod for type-safe validation
- [`form-show-validation-errors-correctly`](references/form-show-validation-errors-correctly.md) - Show errors at appropriate times
- [`form-handle-async-validation`](references/form-handle-async-validation.md) - Debounce async validation calls
- [`form-reset-form-state-correctly`](references/form-reset-form-state-correctly.md) - Reset form state after submission

### 5. Data Display (MEDIUM-HIGH)

- [`data-use-tanstack-table-for-complex-tables`](references/data-use-tanstack-table-for-complex-tables.md) - Use TanStack Table for sorting/filtering
- [`data-virtualize-large-lists`](references/data-virtualize-large-lists.md) - Virtualize lists with 100+ items
- [`data-use-skeleton-loading-states`](references/data-use-skeleton-loading-states.md) - Use Skeleton for loading states
- [`data-paginate-server-side`](references/data-paginate-server-side.md) - Paginate large datasets server-side
- [`data-empty-states-with-guidance`](references/data-empty-states-with-guidance.md) - Provide actionable empty states

### 6. Component Composition (MEDIUM)

- [`comp-compose-with-compound-components`](references/comp-compose-with-compound-components.md) - Use compound component patterns
- [`comp-use-drawer-for-mobile-modals`](references/comp-use-drawer-for-mobile-modals.md) - Use Drawer on mobile devices
- [`comp-combine-command-with-popover`](references/comp-combine-command-with-popover.md) - Create searchable selects with Command
- [`comp-nest-dialogs-correctly`](references/comp-nest-dialogs-correctly.md) - Manage nested dialog focus correctly
- [`comp-create-reusable-form-fields`](references/comp-create-reusable-form-fields.md) - Extract reusable form field components
- [`comp-use-slot-pattern-for-flexibility`](references/comp-use-slot-pattern-for-flexibility.md) - Use slot pattern for flexible content

### 7. Performance Optimization (MEDIUM)

- [`perf-lazy-load-heavy-components`](references/perf-lazy-load-heavy-components.md) - Lazy load components over 50KB
- [`perf-memoize-expensive-renders`](references/perf-memoize-expensive-renders.md) - Memoize list items and expensive components
- [`perf-optimize-icon-imports`](references/perf-optimize-icon-imports.md) - Use direct imports for Lucide icons
- [`perf-avoid-unnecessary-rerenders-in-forms`](references/perf-avoid-unnecessary-rerenders-in-forms.md) - Isolate form field watching
- [`perf-debounce-search-inputs`](references/perf-debounce-search-inputs.md) - Debounce search and filter inputs

### 8. State Management (LOW-MEDIUM)

- [`state-prefer-uncontrolled-for-simple-inputs`](references/state-prefer-uncontrolled-for-simple-inputs.md) - Use uncontrolled for simple forms
- [`state-lift-state-to-appropriate-level`](references/state-lift-state-to-appropriate-level.md) - Lift state to lowest common ancestor
- [`state-use-controlled-dialog-state`](references/state-use-controlled-dialog-state.md) - Control dialogs for programmatic access
- [`state-colocate-state-with-components`](references/state-colocate-state-with-components.md) - Keep state close to where it's used

## How to Use

Read individual reference files for detailed explanations and code examples:

## Full Compiled Document

For a single-file reference containing all rules, see [AGENTS.md](AGENTS.md).

## Reference Files

| File | Description |
|------|-------------|
| [AGENTS.md](AGENTS.md) | Complete compiled guide with all rules |

More agent context in PyModel/react-frontend-skills

32 other files this repository gives its agents.