shadcn

shadcn/ui 社区最佳实践

面向 shadcn/ui 应用的最新最佳实践指南。在应用针对特定基元的指导前，请检查已提交到代码库的组件使用的是 Radix UI 还是 Base UI；当前 shadcn 同时支持两者（新项目默认使用 Base UI），且它们的组合 API 有所不同。组件的安装和升级需通过当前 CLI（v4）进行，它可以解析带命名空间的注册表。

适用场景

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

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

按优先级划分的规则类别

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

快速参考

1. 组件架构（严重）

• arch-use-asChild-for-custom-triggers - 使用生成的基元组合 API
• arch-current-cli-registry - 使用当前 CLI 管理组件生命周期（v4、注册表、MCP）
• arch-unified-radix-package - 从统一的 radix-ui 软件包导入基元
• 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. 保持无障碍性（严重）

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

• style-use-css-variables-for-theming - 使用 CSS 变量设置主题颜色
• style-avoid-important-overrides - 优先使用变体和类组合，而非 important 覆盖
• style-use-tailwind-theme-extend - 在 CSS 中定义 Tailwind v4 主题令牌
• 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 - 将状态放在使用它的组件附近

使用方法

先在项目根目录运行：

npx -y @pymodel/react-frontend-skills detect  # installed vs. targeted versions

对于上述与任务相关的规则，请阅读 references/<rule-id>.md：了解其重要性，以及错误与正确的代码示例。