shadcn-component-review

shadcn 组件审查

系统化审计流程，确保自定义组件符合 shadcn 设计模式、项目选用的视觉风格以及现代组合规范。

如何与官方 shadcn 技能互补

官方 shadcn 技能（随 CLI v4 一同发布）会在生成时强制执行规则——告诉 Agent“使用 gap-*，而不是 space-y-*；使用语义化颜色；宽度和高度相等时使用 size-*”等。这是在编写新代码时的正确做法。

此技能用于事后审计——根据同样的规则，再加上因主题而异的视觉风格专属模式（Vega 的间距不同于 Maia，也不同于 Mira），审查已存在的组件（由 Claude、队友或前一次迭代编写）。两种技能同时适用时，官方技能负责前向生成，本技能负责回顾审查。它们不会相互冲突——只是从不同方向检查相同的规则。

核心原则

审查可以发现偏差。即使官方技能在生成时强制执行规则，组件仍会随时间产生偏差：有人从旧项目复制代码，大模型建议使用 space-y-4 却无人发现，某个组件是在项目统一采用 Maia 之前构建的，或者贡献者使用了 Tailwind 的颜色等级，而非语义化令牌。此技能可以系统地找出这些问题。

何时触发

主动触发（组件编写完成后启用）：

• Claude 刚刚编写或修改了自定义组件
• 用户说“这是我做的”，并粘贴了一个组件
• 用户要求为现有元素添加样式
• 用户正在迭代布局

显式触发（用户直接请求审查）：

• “审查这个组件”
• “检查我的间距”
• “这符合 shadcn 惯用写法吗？”
• “这遵循了这些模式吗？”
• “审计这个布局”

审查前：了解项目上下文

应用主题专属模式之前，先了解项目。如果 shadcn CLI 可用，请运行：

npx shadcn@latest info --json

此命令会返回：框架（Next.js / Vite / 等）、Tailwind 版本、基础库（radix 或 base）、已安装的组件、图标库、解析后的文件路径以及当前样式。使用此输出来：

• 根据项目的视觉风格匹配间距和形状预期
• 根据基础组件基元的类型（Radix 与 Base UI——API 不同）应用正确的组合模式
• 确认哪些组件已安装，哪些需要建议安装

如果 CLI 不可用，请直接从 components.json 推断，或询问用户：“此项目使用哪种视觉风格——Vega、Nova、Maia、Lyra 还是 Mira？”

审查工作流

步骤 1：结构与组合

检查组件是否采用 shadcn 约定的结构。

data-slot 属性。 组件中的每个语义元素都应带有用于命名其角色的 data-slot 属性。这有助于提供样式钩子、测试选择器和一致的主题化支持。已在 shadcn 源码中确认当前模式（例如 <button data-slot="button" data-variant={variant} data-size={size}>）。

组合，而非修改。 自定义组件应组合来自 @/components/ui/* 的组件基元，而不是分叉并修改它们。如果某个组件基元需要不同的行为，应对其进行封装，而不要编辑源代码。

了解组件基元的基础库。 如果项目使用 Radix（--base radix），应使用 asChild 和 Slot 模式以及 Radix 的 data-state 属性。如果使用 Base UI（--base base），则应使用不同的组合 API。请参考已安装组件基元的当前文档：npx shadcn@latest docs <component>。

步骤 2：间距审查

间距是最容易出现偏差的地方。请对照项目的视觉风格进行检查——各风格的具体模式请参阅 references/theme-styles.md。

通用规则（适用于所有主题）：

• 在 flex/grid 容器中使用 gap-*，绝不使用 space-y-* / space-x-* 或外边距
• 使用 Tailwind 的标准间距刻度（4px 的倍数：1、1.5、2、4、6、8——避免使用 3、5、7）
• 宽度和高度相等时使用 size-*（用 size-10，而不是 w-10 h-10）
• 响应式间距采用 gap-X md:gap-Y 模式

风格特定规则： 不同风格对密度和圆角的要求有所不同。具体要求请参阅 references/theme-styles.md。

步骤 3：设计令牌

仅验证语义令牌——不要使用硬编码的 Tailwind 色阶值。

类别	使用	避免
文本颜色	text-foreground、text-muted-foreground、text-primary	text-neutral-500、text-gray-900、text-slate-700
背景	bg-background、bg-card、bg-muted、bg-accent	bg-gray-100、bg-white、bg-neutral-50
边框	border-border、border-input	border-gray-200、border-neutral-300
圆角	rounded-md、rounded-lg（使用 --radius）	rounded-[20px]、rounded-[8px]

快速 grep，标记硬编码颜色：

grep -rE '\b(neutral|gray|slate|zinc|stone)-[0-9]{2,3}\b' <path>

步骤 4：可组合性

检查组件是否可以在无需修改的情况下重复使用。

• 接受 className 属性，并通过 cn() 合并
• 在可能需要变化的地方通过 CVA 暴露变体
• 不要硬编码内容；接受 children 或符合内容形态的属性
• 不要与特定数据模型或路由紧密耦合

步骤 5：响应式与无障碍

• 以移动端为优先的基线设计（< 768px），通过 md:、lg: 逐步增强
• 交互元素的触控目标最小约为 44px
• 在 flex 子元素上使用 min-w-0，以防止溢出
• 使用语义化 HTML（按钮使用 <button>，而不是设置样式的 <div>）
• 提供焦点可见状态（focus-visible:ring-*、focus-visible:border-*）
• 动效需遵循 motion-safe: / prefers-reduced-motion

完整检查清单请参阅 references/review-checklist.md。

基础模式

CVA（Class Variance Authority）

通过 cva() 声明变体，通过 VariantProps 添加类型：

import { cva, type VariantProps } from "class-variance-authority"

const buttonVariants = cva(
  "inline-flex items-center justify-center gap-2 rounded-md text-sm font-medium transition-all",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        outline: "border bg-background hover:bg-accent",
      },
      size: {
        default: "h-9 px-4 py-2",
        sm: "h-8 px-3 text-xs",
      },
    },
    defaultVariants: { variant: "default", size: "default" },
  }
)

type ButtonProps = React.ComponentProps<"button"> & VariantProps<typeof buttonVariants>

通过新增变体进行扩展；不要修改基础层。

cn() 工具函数

组合 clsx（条件处理）和 tailwind-merge（冲突解决）。组合 className 时始终使用：

import { cn } from "@/lib/utils"

<div className={cn(
  "base-classes",
  isActive && "active-classes",
  className // consumer overrides win
)} />

适配主题的样式

shadcn 主题使用 CSS 变量（自 2025 年起基于 OKLCH）。关键变量：--radius、--background、--foreground、--primary、--secondary、--accent、--muted、--card、--popover、--destructive、--border、--input、--ring。

使用映射到这些变量的 Tailwind 语义类名（rounded-md → --radius、bg-primary → --primary），而不是硬编码值。

动画

简要约定：

• 悬停/焦点/激活：使用 Tailwind 过渡，150ms
• 颜色/状态过渡：200ms
• DOM 元素的进入/退出：使用 Tailwind animate-in/animate-out 配合 Radix data-state，或使用 Motion 的 AnimatePresence
• 基于变换的动画始终遵循 motion-safe:

完整指南请参阅 references/animation-patterns.md。

视觉样式参考

shadcn 提供五种官方视觉样式，可通过 npx shadcn create 或预设代码（CLI v4）进行配置：

样式	密度	形状	典型用途
Vega	标准	经典	默认的 shadcn 外观
Nova	紧凑	标准	高密度 UI、数据密集型应用
Maia	宽松	柔和/圆润（通常为药丸形）	面向消费者的应用、友好的界面
Lyra	标准	方正/锐利	开发者工具、等宽字体
Mira	密集	紧凑	管理仪表板、高级用户

每种样式都会影响间距比例、边框圆角和组件尺寸。有关各样式的间距模式和常见错误，请参阅 references/theme-styles.md。

预设（CLI v4 新增）会将样式、主题、字体、图标和圆角打包为一个简短代码，通过 npx shadcn@latest apply --preset <code> 应用。审查时，如果项目配置了预设，请检查该预设——它是许多此类约定的权威依据。

范围：此技能不会强制执行的内容

请明确区分 shadcn 的规范和项目特定约定。此技能依据 shadcn 规范进行审查。项目特定约定（例如“我们团队总是在表单字段之间使用 gap-4”）应写入项目自己的样式指南或项目专用技能，而不是此技能。

有疑问时，请注明来源：“shadcn 组件使用 data-slot——请参阅 ui.shadcn.com/docs/components/button 中的按钮源码”，而不是“你的项目始终在表单字段之间使用 gap-4”。

输出格式

一份好的审查应：

1. 用一行概述审查内容
2. 按类别标记问题（结构、间距、设计令牌、可组合性、响应式/无障碍）
3. 为每个问题标注严重程度：✅ 通过，⚠️ 建议，❌ 阻断
4. 展示修复方式：修复简短且显而易见时直接展示；修复较复杂时引用相关模式文件
5. 主动提出可按用户意愿应用修复

保持内容易于浏览。不要过度描述通过项——用一行 ✅ 概述优点即可。

审查输出示例

## Review: `<PageHeader />`

**Structure** ✅ `data-slot` present, composition clean
**Spacing** ⚠️ Uses `space-y-4` in flex container — swap to `gap-4`
**Tokens** ❌ `text-neutral-500` on line 12 — use `text-muted-foreground`
**Composability** ✅ Accepts className, variant props via CVA
**Responsive/a11y** ⚠️ Missing `min-w-0` on flex child (may overflow on narrow screens)

Fixes:
- Line 8: `space-y-4` → `gap-4`
- Line 12: `text-neutral-500` → `text-muted-foreground`
- Line 18: Add `min-w-0` to wrapping `<div>`

Want me to apply these?

参考文件

• references/theme-styles.md — 各样式的间距、形状和常见错误
• references/review-checklist.md — 按类别扩展的审查清单
• references/animation-patterns.md — 时间、缓动、Radix data-state、Motion 模式

资源

• shadcn 官方文档： ui.shadcn.com
• 组件参考（实时）： npx shadcn@latest docs <component> — 返回当前文档和示例 URL
• 项目上下文： npx shadcn@latest info --json
• 主题创建器： ui.shadcn.com/create
• TweakCN（交互式主题编辑器）： tweakcn.com