shadcn-code-review

shadcn/ui 代码审查

快速参考

问题类型	参考
CVA 中的 className、缺少 VariantProps、复合变体	references/cva-patterns.md
使用 asChild 但未使用 Slot、缺少 Context、组件组合	references/composition.md
缺少 focus-visible、aria-invalid、禁用状态	references/accessibility.md
缺少 data-slot、CSS 定位错误	references/data-slot.md

审查清单

• cn() 接收 className，而不是 CVA 变体
• 导出 VariantProps<typeof variants>，供使用者使用
• 复杂状态组合使用复合变体
• asChild 模式使用 @radix-ui/react-slot
• 组件组合（Card、Accordion 等）使用 Context
• 使用 focus-visible: 状态，而不只是 :focus
• 表单状态使用 aria-invalid、aria-disabled
• 所有交互元素都使用 disabled: 变体
• 屏幕阅读器文本使用 sr-only
• 可定位的组合部件使用 data-slot 属性
• CSS 使用 has() 选择器设置基于状态的样式
• 不直接使用 className 覆盖变体样式

硬性关卡（编写问题报告前）

按顺序运行以下检查。对于即将报告的批次，只有所有关卡都通过后，才能起草面向用户的问题报告。

1. 位置证据 — 通过： 每个问题都列出仓库路径，以及行号范围或你读过的文件中的简短原文引用（不能凭记忆或仅根据差异猜测）。

2. 豁免检查 — 通过： 对于每个问题，你都能用一行说明其不属于 有效模式（不要标记） 的涵盖范围。

3. 上下文敏感声明 — 通过： 对于无障碍或 Radix 相关问题，你已检查文件中实际运行逻辑对应的导入或封装（或指出具体缺失之处）。

4. 协议 — 通过： 你已按照本次审查的要求，完成 审查验证协议 中的报告前验证清单。

有效模式（不要标记）

以下模式是正确的，不应标记为问题：

• max-h-(--var) — 正确的 Tailwind v4 CSS 变量语法（不是 v3 方括号表示法）
• text-[color:var(--x)] — 有效的任意值语法
• 将 shadcn 组件代码复制到项目中 — 预期的使用模式
• 未记录复制的 shadcn 组件 — 属于库内部实现，而非自定义代码
• 在 cn() 中使用大量参数 — 这是组合模式
• 在 cn() 数组中使用条件类 — 有效的 Tailwind 模式
• 扩展原始组件但不补充文档 — 众所周知的基础组件

上下文敏感规则

根据具体上下文应用以下规则：

• 仅当底层未由 Radix 原语处理时，才标记无障碍问题
• 仅当组件未使用无障碍的 Radix 原语时，才标记缺失的 aria 标签
• 仅当变体可以由现有变体组合而成时，才标记变体过多
• 仅当组件文档针对自定义代码而非复制的 shadcn 代码时，才标记文档问题

库约定说明

shadcn/ui 组件的设计初衷是供人复制和修改。代码审查应重点关注：

• 对复制组件所做的自定义修改
• 与应用状态／数据的集成
• 在自定义使用场景中的无障碍性

不要标记：

• 标准 shadcn 组件内部实现
• Radix 原语使用模式
• 默认变体实现

何时加载参考资料

• 审查变体定义 → cva-patterns.md
• 审查使用 asChild 的组件组合 → composition.md
• 审查表单组件或交互元素 → accessibility.md
• 审查多部件组件（Card、Select 等）→ data-slot.md

审查问题

1. CVA 变体是否与 className 属性正确分离？
2. 使用 Slot 时，asChild 组合是否正常工作？
3. 是否处理了所有无障碍状态（焦点、无效、禁用）？
4. 是否使用 data-slot 属性来定位组件部件？
5. 消费者能否扩展变体而不破坏组合？

提交发现前

完成 硬性门槛（尤其是门槛 4），然后仅报告仍通过 review-verification-protocol 提交前检查的问题。