shadcn

shadcn/ui 社区最佳实践

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

适用场景

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

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

按优先级划分的规则类别

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

快速参考

1. CLI 与项目设置（严重）

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

2. 组件架构（严重）

• 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. 无障碍功能保留（关键）

• 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 - 保留焦点可见样式，支持键盘导航

4. 样式与主题（高）

• 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-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-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-sidebar-provider - 使用 SidebarProvider 包裹布局
• layout-sidebar-collapsible - 配置侧边栏的折叠行为
• layout-sidebar-groups - 使用分组组织侧边栏导航
• layout-sheet-mobile-nav - 使用 Sheet 实现移动端导航覆盖层
• layout-breadcrumb-navigation - 为深层导航实现面包屑

8. 组件组合（中）

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

9. 性能优化（中）

• 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 - 对搜索和筛选输入进行防抖

10. 状态管理（低-中）

• 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	版本和参考信息