shadcn

shadcn/ui 社区最佳实践

由 shadcn/ui 社区维护的 shadcn/ui 应用全面最佳实践指南。包含 8 个类别中的 42 条规则，并按影响程度排序，用于指导自动重构和代码生成。

适用场景

在以下情况下，请参考这些指南：

• 编写新的 shadcn/ui 组件或组合基础组件
• 使用 React Hook Form 和 Zod 验证实现表单
• 构建数据表格或处理大型数据集的展示
• 自定义主题或添加深色模式支持
• 检查代码是否符合无障碍要求

按优先级划分的规则类别

优先级	类别	影响	前缀
1	组件架构	CRITICAL	arch-
2	无障碍保留	CRITICAL	ally-
3	样式与主题	HIGH	style-
4	表单模式	HIGH	form-
5	数据展示	MEDIUM-HIGH	data-
6	组件组合	MEDIUM	comp-
7	性能优化	MEDIUM	perf-
8	状态管理	LOW-MEDIUM	state-

快速参考

1. 组件架构（CRITICAL）

• 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 - 将基础样式与特定变体的样式分开

2. 无障碍保留（CRITICAL）

• 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. 样式与主题（HIGH）

• 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 变量支持深色模式

4. 表单模式（高）

• 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-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. 组件组合（中）

• 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 - 使用 slot 模式实现灵活的内容

7. 性能优化（中）

• 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-prefer-uncontrolled-for-simple-inputs - 简单表单使用非受控模式
• state-lift-state-to-appropriate-level - 将状态提升到最近的公共祖先
• state-use-controlled-dialog-state - 通过受控状态实现对话框的编程式访问
• state-colocate-state-with-components - 将状态放在靠近其使用位置的地方

使用方法

阅读各个参考文件，了解详细说明和代码示例：

• 章节定义 - 分类结构和影响级别
• 规则模板 - 添加新规则的模板

完整汇编文档

如需包含所有规则的单文件参考，请参阅 AGENTS.md。

参考文件

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