shadcn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

shadcn/ui Community Best Practices

shadcn/ui 社区最佳实践

Comprehensive best practices guide for shadcn/ui applications, maintained by the shadcn/ui community. Contains 58 rules across 10 categories, prioritized by impact to guide automated refactoring and code generation.

这是由 shadcn/ui 社区维护的 shadcn/ui 应用综合最佳实践指南，包含10个类别共58条规则，按影响优先级排序，可指导自动化重构和代码生成。

When to Apply

适用场景

Reference these guidelines when:

Installing and configuring shadcn/ui in a project
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
编写新的 shadcn/ui 组件或组合原语
使用 React Hook Form 和 Zod 实现表单
构建数据表格或处理大型数据集展示
定制主题或添加深色模式支持
评审代码的可访问性合规性

Rule Categories by Priority

按优先级划分的规则类别


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

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


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

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

Quick Reference

快速参考

1. CLI & Project Setup (CRITICAL)

1. CLI 与项目配置（关键）

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

```
setup-components-json
```
- 添加组件前配置components.json
```
setup-path-aliases
```
- 配置TypeScript路径别名以匹配components.json
```
setup-cn-utility
```
- 使用组件前创建cn工具函数
```
setup-use-cli-not-copy
```
- 使用CLI添加组件而非复制粘贴
```
setup-css-variables-theme
```
- 启用CSS变量以实现一致的主题定制
```
setup-rsc-configuration
```
- 根据框架支持设置RSC标志

2. Component Architecture (CRITICAL)

2. 组件架构（关键）

```
arch-use-asChild-for-custom-triggers
```
- Use asChild prop for custom trigger elements
```
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
```
- 使用asChild属性实现自定义触发元素
```
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
```
- 将基础样式与变体特定样式分离

3. Accessibility Preservation (CRITICAL)

3. 可访问性保障（关键）

```
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-dialog-title-required
```
- Always include DialogTitle for screen readers
```
ally-form-field-labels
```
- Associate labels with form controls
```
ally-aria-invalid-errors
```
- Use aria-invalid for form error states
```
ally-checkbox-label-association
```
- Wrap Checkbox with Label for click target
```
ally-focus-visible-styles
```
- Preserve focus visible styles for keyboard navigation

```
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颜色对比度标准
```
ally-dialog-title-required
```
- 始终为模态框添加DialogTitle以支持屏幕阅读器
```
ally-form-field-labels
```
- 将标签与表单控件关联
```
ally-aria-invalid-errors
```
- 使用aria-invalid标识表单错误状态
```
ally-checkbox-label-association
```
- 用Label包裹Checkbox以扩大点击区域
```
ally-focus-visible-styles
```
- 保留键盘导航的focus visible样式

4. Styling & Theming (HIGH)

4. 样式与主题（高）

```
style-use-css-variables-for-theming
```
- Use CSS variables for theme colors
```
style-avoid-important-overrides
```
- Never use !important for style overrides
```
style-use-tailwind-theme-extend
```
- Extend Tailwind theme for design tokens
```
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
```
- 扩展Tailwind主题以实现设计令牌
```
style-consistent-spacing-scale
```
- 使用统一的Tailwind间距比例
```
style-responsive-design-patterns
```
- 应用移动端优先的响应式设计
```
style-dark-mode-support
```
- 使用CSS变量支持深色模式

5. Form Patterns (HIGH)

5. 表单模式（高）

```
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
```
- 提交后正确重置表单状态

6. Data Display (MEDIUM-HIGH)

6. 数据展示（中高）

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
```
- 提供可操作的空状态提示

7. Layout & Navigation (MEDIUM)

7. 布局与导航（中）

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

```
layout-sidebar-provider
```
- 用SidebarProvider包裹布局
```
layout-sidebar-collapsible
```
- 配置侧边栏的可折叠行为
```
layout-sidebar-groups
```
- 使用分组组织侧边栏导航
```
layout-sheet-mobile-nav
```
- 使用Sheet实现移动端导航弹窗
```
layout-breadcrumb-navigation
```
- 实现面包屑导航以支持深层页面跳转

8. Component Composition (MEDIUM)

8. 组件组合（中）

```
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与Popover实现可搜索选择器
```
comp-nest-dialogs-correctly
```
- 正确管理嵌套模态框的焦点
```
comp-create-reusable-form-fields
```
- 提取可复用的表单字段组件
```
comp-use-slot-pattern-for-flexibility
```
- 使用插槽模式实现灵活的内容定制

9. Performance Optimization (MEDIUM)

9. 性能优化（中）

```
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
```
- 对列表项和性能开销大的组件进行 memoization
```
perf-optimize-icon-imports
```
- 直接导入Lucide图标
```
perf-avoid-unnecessary-rerenders-in-forms
```
- 隔离表单字段的监听以避免不必要的重渲染
```
perf-debounce-search-inputs
```
- 对搜索和过滤输入进行防抖处理

10. State Management (LOW-MEDIUM)

10. 状态管理（中低）

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:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件获取详细说明和代码示例：

Section definitions - 类别结构与影响级别说明
Rule template - 添加新规则的模板

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
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
AGENTS.md	包含所有规则的完整编译指南
references/_sections.md	类别定义与排序说明
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息