概述
shadcn 是一个 shadcn/ui 社区最佳实践指南技能（原名 shadcn-ui）。它面向 shadcn/ui 应用，包含 58 条规则，分布于 10 个类别，并按影响程度划分优先级，用于指导自动化重构和代码生成。
适用时机
在以下情况参考这些指南：
- 在项目中安装和配置 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 - 配置 TypeScript 路径别名以匹配 components.json
- 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 - 为键盘导航保留 focus visible 样式
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 - 使用插槽模式实现灵活内容
9. 性能优化（中）
- perf-lazy-load-heavy-components - 对超过 50KB 的组件进行懒加载
- perf-memoize-expensive-renders - 对列表项和昂贵组件进行记忆化
- perf-optimize-icon-imports - 对 Lucide 图标使用直接导入
- perf-avoid-unnecessary-rerenders-in-forms - 隔离表单字段的 watch 行为
- 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 | 版本与参考信息 |