name: shadcn description: shadcn/ui组件库最佳实践和模式（原名shadcn-ui）。此技能应用于编写、审查或重构shadcn/ui组件，以确保正确的架构、可访问性和性能。触发于涉及Radix原语、Tailwind样式、使用React Hook Form的表单验证、数据表、主题或组件组合模式的任务。
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.jsonsetup-path-aliases- 配置TypeScript路径别名以匹配components.jsonsetup-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- 转发引用以支持表单和焦点集成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- 始终为屏幕阅读器包含DialogTitleally-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- 在移动设备上使用Drawercomp-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- 隔离表单字段监视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 | 版本和参考信息 |