shadcn

shadcn/ui 社区最佳实践

涵盖 shadcn/ui 的 10 个类别、58 条规则，按影响优先级排序，为自动重构和代码生成提供指导。

技术栈基线

规则面向当前版本的 shadcn/ui：Tailwind CSS v4（以 CSS 为先，无 tailwind.config.*，在 @theme inline 中定义令牌）、React 19（将 ref 作为 prop，使用 data-slot 属性）、统一的 radix-ui 包、OKLCH 颜色令牌、tw-animate-css、Field + React Hook Form Controller 表单，以及 Bun（bunx --bun shadcn@latest ...）。示例使用 Radix 基础（--base radix）；CLI 也支持 Base UI 基础（--base base），此时触发器使用 render prop，而不是 asChild。对于 Tailwind v3 项目，请保留现有配置，并先遵循 shadcn 升级指南。

设置模式

在安装、修复或迁移 shadcn/ui 时使用（新项目、现有项目、从 Tailwind v3 迁移到 v4）。遵循 references/_setup-mode.md：选择 bunx --bun shadcn@latest init 路径，然后配置以 CSS 为先的 Tailwind v4（@theme inline、@custom-variant dark）、将 components.json 中的 tailwind.config 设为空、设置 cn() 辅助函数，并完成验证清单。只执行用户要求的设置；覆盖现有样式、配置或组件前，请先确认。设置完成后，以下规则即适用。

适用场景

• 在项目中安装和配置 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（v4 中的 tailwind.config 设为空）
• setup-path-aliases - 配置 TypeScript 路径别名，使其与 components.json 匹配
• setup-cn-utility - 创建 cn 辅助函数（从 cn 重新导出），然后再使用组件
• setup-use-cli-not-copy - 使用 CLI 添加组件，而不是复制粘贴
• setup-css-variables-theme - 启用 CSS 变量，以保持主题一致
• setup-rsc-configuration - 根据框架支持情况设置 RSC 标志

2. 组件架构（严重）

• arch-use-asChild-for-custom-triggers - 为自定义触发元素使用 asChild prop
• 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 - 将 refs 传递到底层元素（React 19 ref prop）
• 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 - 使用 @theme inline 在 CSS 中定义设计令牌
• style-consistent-spacing-scale - 使用一致的 Tailwind 间距比例
• style-responsive-design-patterns - 采用移动优先的响应式设计
• style-dark-mode-support - 使用 CSS 变量支持深色模式

5. 表单模式（高）

• form-use-react-hook-form-integration - 将 React Hook Form 与 Field 和 Controller 集成
• 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 - 将状态放在靠近其使用位置的地方

使用方法

阅读单独的参考文件，了解详细说明和代码示例：

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

参考文件

文件	说明
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板