shadcn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

shadcn/ui Community Best Practices

shadcn/ui 社区最佳实践

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 and their composition APIs differ.

当前shadcn/ui应用的最佳实践指南。在应用特定原语的指南之前，请检查已签入的组件是使用Radix UI还是Base UI；当前shadcn同时支持两者，且它们的组合API有所不同。

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

在以下场景中参考本指南：

编写新的shadcn/ui组件或组合原语
使用React Hook Form和Zod验证实现表单
构建数据表格或处理大型数据集展示
自定义主题或添加深色模式支持
审查代码的可访问性合规性

Rule Categories by Priority

按优先级划分的规则类别


arch-
ally-
style-
form-
data-
comp-
perf-
state-

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-`


arch-
ally-
style-
form-
data-
comp-
perf-
state-

优先级	类别	影响程度	前缀
1	组件架构	关键	`arch-`
2	可访问性保留	关键	`ally-`
3	样式与主题	高	`style-`
4	表单模式	高	`form-`
5	数据展示	中高	`data-`
6	组件组合	中	`comp-`
7	性能优化	中	`perf-`
8	状态管理	中低	`state-`

Quick Reference

快速参考

1. Component Architecture (CRITICAL)

1. 组件架构（关键）

```
arch-use-asChild-for-custom-triggers
```
- Use the generated primitive's composition API
```
arch-preserve-radix-primitive-structure
```
- Maintain Radix compound component hierarchy
```
arch-extend-variants-with-cva
```
- Use Class Variance Authority for type-safe variants
```
arch-use-cn-for-class-merging
```
- Use cn() utility for safe Tailwind class merging
```
arch-forward-refs-for-composable-components
```
- Forward refs for form and focus integration
```
arch-isolate-component-variants
```
- Separate base styles from variant-specific styles

```
arch-use-asChild-for-custom-triggers
```
- 使用生成的原语组合API
```
arch-preserve-radix-primitive-structure
```
- 维护Radix复合组件层级
```
arch-extend-variants-with-cva
```
- 使用Class Variance Authority实现类型安全的变体
```
arch-use-cn-for-class-merging
```
- 使用cn()工具安全合并Tailwind类

arch-forward-refs-for-composable-components

- 转发ref以实现表单和焦点集成

```
arch-isolate-component-variants
```
- 将基础样式与变体特定样式分离

2. Accessibility Preservation (CRITICAL)

2. 可访问性保留（关键）

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

```
ally-preserve-aria-attributes
```
- 保持Radix ARIA属性完整
```
ally-provide-sr-only-labels
```
- 为图标按钮添加屏幕阅读器标签
```
ally-maintain-focus-management
```
- 保留模态框中的焦点捕获
```
ally-preserve-keyboard-navigation
```
- 保留WAI-ARIA键盘交互模式
```
ally-ensure-color-contrast
```
- 维持WCAG颜色对比度标准

3. Styling & Theming (HIGH)

3. 样式与主题（高）

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

```
style-use-css-variables-for-theming
```
- 使用CSS变量定义主题颜色
```
style-avoid-important-overrides
```
- 优先使用变体和类组合而非!important覆盖
```
style-use-tailwind-theme-extend
```
- 在CSS中定义Tailwind v4主题令牌
```
style-consistent-spacing-scale
```
- 使用统一的Tailwind间距比例
```
style-responsive-design-patterns
```
- 应用移动端优先的响应式设计
```
style-dark-mode-support
```
- 使用CSS变量支持深色模式

4. Form Patterns (HIGH)

4. 表单模式（高）

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

```
form-use-react-hook-form-integration
```
- 集成React Hook Form
```
form-use-zod-for-schema-validation
```
- 使用Zod实现类型安全的验证
```
form-show-validation-errors-correctly
```
- 在合适时机显示错误信息
```
form-handle-async-validation
```
- 防抖异步验证调用
```
form-reset-form-state-correctly
```
- 提交后重置表单状态

5. Data Display (MEDIUM-HIGH)

5. 数据展示（中高）

data-use-tanstack-table-for-complex-tables

- Use TanStack Table for sorting/filtering

```
data-virtualize-large-lists
```
- Virtualize lists with 100+ items
```
data-use-skeleton-loading-states
```
- Use Skeleton for loading states
```
data-paginate-server-side
```
- Paginate large datasets server-side
```
data-empty-states-with-guidance
```
- Provide actionable empty states

data-use-tanstack-table-for-complex-tables

- 使用TanStack Table实现排序/筛选

```
data-virtualize-large-lists
```
- 对100+条目的列表进行虚拟化处理
```
data-use-skeleton-loading-states
```
- 使用Skeleton实现加载状态
```
data-paginate-server-side
```
- 对大型数据集进行服务端分页
```
data-empty-states-with-guidance
```
- 提供可操作的空状态提示

6. Component Composition (MEDIUM)

6. 组件组合（中）

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

```
comp-compose-with-compound-components
```
- 使用复合组件模式
```
comp-use-drawer-for-mobile-modals
```
- 在移动端使用Drawer组件
```
comp-combine-command-with-popover
```
- 结合Command组件创建可搜索的选择器
```
comp-nest-dialogs-correctly
```
- 正确管理嵌套对话框的焦点
```
comp-create-reusable-form-fields
```
- 提取可复用的表单字段组件
```
comp-use-slot-pattern-for-flexibility
```
- 使用插槽模式实现灵活的内容布局

7. Performance Optimization (MEDIUM)

7. 性能优化（中）

```
perf-lazy-load-heavy-components
```
- Lazy load components over 50KB
```
perf-memoize-expensive-renders
```
- Memoize list items and expensive components
```
perf-optimize-icon-imports
```
- Use direct imports for Lucide icons

perf-avoid-unnecessary-rerenders-in-forms

- Isolate form field watching

```
perf-debounce-search-inputs
```
- Debounce search and filter inputs

```
perf-lazy-load-heavy-components
```
- 懒加载超过50KB的组件
```
perf-memoize-expensive-renders
```
- 对列表项和性能开销大的组件进行记忆化处理
```
perf-optimize-icon-imports
```
- 直接导入Lucide图标
```
perf-avoid-unnecessary-rerenders-in-forms
```
- 隔离表单字段监听以避免不必要的重渲染
```
perf-debounce-search-inputs
```
- 对搜索和筛选输入进行防抖处理

8. State Management (LOW-MEDIUM)

8. 状态管理（中低）

state-prefer-uncontrolled-for-simple-inputs

- Use uncontrolled for simple forms

```
state-lift-state-to-appropriate-level
```
- Lift state to lowest common ancestor
```
state-use-controlled-dialog-state
```
- Control dialogs for programmatic access
```
state-colocate-state-with-components
```
- Keep state close to where it's used

state-prefer-uncontrolled-for-simple-inputs

- 简单表单优先使用非受控组件

```
state-lift-state-to-appropriate-level
```
- 将状态提升到合适的层级
```
state-use-controlled-dialog-state
```
- 控制对话框状态以支持程序化访问
```
state-colocate-state-with-components
```
- 将状态放在靠近使用它的组件处

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	Complete compiled guide with all rules

文件	描述
AGENTS.md	包含所有规则的完整编译指南