Shadcn

shadcn/ui

一个用于构建 UI、组件和设计系统的框架。组件通过 CLI 以源码形式添加到用户的项目中。

重要提示： 请使用项目的包运行器执行所有 CLI 命令：npx shadcn@latest、pnpm dlx shadcn@latest 或 bunx --bun shadcn@latest —— 取决于项目的 packageManager。以下示例使用 npx shadcn@latest，但在实际操作中请替换为项目正确的运行器。

当前项目上下文

!`npx shadcn@latest info --json`

上面的 JSON 包含了项目配置和已安装的组件。使用 npx shadcn@latest docs <component> 获取任何组件的文档和示例 URL。

原则

1. 优先使用现有组件。 在编写自定义 UI 之前，先运行 npx shadcn@latest search 检查注册表。同时也检查社区注册表。
2. 组合而非重造。 设置页面 = Tabs + Card + 表单控件。仪表板 = Sidebar + Card + Chart + Table。
3. 优先使用内置变体而非自定义样式。 如 variant="outline", size="sm" 等。
4. 使用语义化颜色。 如 bg-primary, text-muted-foreground —— 绝不使用原始值如 bg-blue-500。

关键规则

这些规则是 强制执行 的。每个链接都指向包含“错误/正确”代码示例的文件。

样式与 Tailwind → styling.md

• className 用于布局而非样式。 绝不覆盖组件的颜色或字体。
• 禁止使用 space-x-* 或 space-y-*。 使用 flex 搭配 gap-*。对于垂直堆叠，使用 flex flex-col gap-*。
• 当宽高相等时使用 size-*。 使用 size-10 而非 w-10 h-10。
• 使用 truncate 简写。 而非 overflow-hidden text-ellipsis whitespace-nowrap。
• 禁止手动使用 dark: 颜色覆盖。 使用语义化 Token（bg-background, text-muted-foreground）。
• 使用 cn() 处理条件类名。 不要手动编写模板字符串三元表达式。
• 禁止在覆盖层 (overlay) 组件上手动设置 z-index。 Dialog, Sheet, Popover 等组件会自行处理层级。

表单与输入框 → forms.md

• 表单使用 FieldGroup + Field。 绝不使用原始 div 配合 space-y-* 或 grid gap-* 进行表单布局。
• InputGroup 使用 InputGroupInput/InputGroupTextarea。 在 InputGroup 内部绝不使用原始 Input/Textarea。
• 输入框内的按钮使用 InputGroup + InputGroupAddon。
• 选项集（2–7 个选项）使用 ToggleGroup。 不要循环渲染带有手动激活状态的 Button。
• 使用 FieldSet + FieldLegend 对相关复选框/单选框进行分组。 不要使用带有标题的 div。
• 字段验证使用 data-invalid + aria-invalid。 在 Field 上使用 data-invalid，在控件上使用 aria-invalid。禁用状态同理：Field 使用 data-disabled，控件使用 disabled。

组件结构 → composition.md

• 子项始终位于其分组 (Group) 内部。 SelectItem → SelectGroup。DropdownMenuItem → DropdownMenuGroup。CommandItem → CommandGroup。
• 自定义触发器使用 asChild (Radix) 或 render (Base)。 通过 npx shadcn@latest info 检查 base 字段。 → base-vs-radix.md
• Dialog, Sheet 和 Drawer 始终需要标题。 出于无障碍考虑，必须包含 DialogTitle, SheetTitle, DrawerTitle。如果视觉上需要隐藏，请使用 className="sr-only"。
• 使用完整的 Card 组合。 CardHeader/CardTitle/CardDescription/CardContent/CardFooter。不要将所有内容塞进 CardContent。
• Button 没有 isPending/isLoading。 使用 Spinner + data-icon + disabled 进行组合。
• TabsTrigger 必须位于 TabsList 内部。 绝不直接在 Tabs 中渲染触发器。
• Avatar 始终需要 AvatarFallback。 以防图片加载失败。

使用组件而非自定义标记 → composition.md

• 优先使用现有组件。 在编写带有样式的 div 之前，先检查组件是否存在。
• 提示框使用 Alert。 不要构建自定义样式的 div。
• 空状态使用 Empty。 不要构建自定义空状态标记。
• 通过 sonner 发送 Toast。 使用来自 sonner 的 toast()。
• 使用 Separator 而非 <hr> 或 <div className="border-t">。
• 使用 Skeleton 作为加载占位符。不要使用自定义的 animate-pulse div。
• 使用 Badge 而非自定义样式的 span。

图标 → icons.md

• Button 中的图标使用 data-icon。 在图标上使用 data-icon="inline-start" 或 data-icon="inline-end"。
• 禁止在组件内部的图标上使用尺寸类。 组件通过 CSS 处理图标尺寸。禁止使用 size-4 或 w-4 h-4。
• 以对象形式传递图标，而非字符串键。 使用 icon={CheckIcon}，而非字符串查找。

CLI

• 禁止手动解码或获取预设代码。 对于现有项目直接传递给 npx shadcn@latest apply --preset <code>，或在初始化时使用 npx shadcn@latest init --preset <code>。

关键模式

这些是正确 shadcn/ui 代码中最常见的差异化模式。对于特殊情况，请参阅上面链接的规则文件。

// 表单布局：FieldGroup + Field，而非 div + Label。
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>

// 验证：Field 使用 data-invalid，控件使用 aria-invalid。
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <Input aria-invalid />
  <FieldDescription>无效的邮箱。</FieldDescription>
</Field>

// 按钮中的图标：使用 data-icon，无尺寸类。
<Button>
  <SearchIcon data-icon="inline-start" />
  搜索
</Button>

// 间距：使用 gap-*，而非 space-y-*。
<div className="flex flex-col gap-4">  // 正确
<div className="space-y-4">           // 错误

// 相等维度：使用 size-*，而非 w-* h-*。
<Avatar className="size-10">   // 正确
<Avatar className="w-10 h-10"> // 错误

// 状态颜色：使用 Badge 变体或语义化 Token，而非原始颜色。
<Badge variant="secondary">+20.1%</Badge>    // 正确
<span className="text-emerald-600">+20.1%</span> // 错误

组件选择

关键字段

注入的项目上下文包含以下关键字段：

• aliases → 使用实际的导入别名前缀（如 @/, ~/），绝不硬编码。
• isRSC → 当为 true 时，使用 useState, useEffect, 事件处理器或浏览器 API 的组件需要在文件顶部添加 "use client"。在建议指令时务必参考此字段。
• tailwindVersion → "v4" 使用 @theme inline 块； "v3" 使用 tailwind.config.js。
• tailwindCssFile → 定义自定义 CSS 变量的全局 CSS 文件。始终编辑此文件，绝不创建新文件。
• style → 组件视觉处理（如 nova, vega）。
• base → 基础库（radix 或 base）。影响组件 API 和可用 Props。
• iconLibrary → 决定图标导入。lucide 使用 lucide-react，tabler 使用 @tabler/icons-react 等。绝不假设是 lucide-react。
• resolvedPaths → 组件、工具类、Hooks 等的准确文件系统目标。
• framework → 路由和文件约定（如 Next.js App Router vs Vite SPA）。
• packageManager → 用于任何非 shadcn 的依赖安装（如 pnpm add date-fns vs npm install date-fns）。

完整字段参考见 cli.md — info 命令。

组件文档、示例与用法

运行 npx shadcn@latest docs <component> 获取组件的文档、示例和 API 参考 URL。获取这些 URL 以获取实际内容。

npx shadcn@latest docs button dialog select

在创建、修复、调试或使用组件时，务必先运行 npx shadcn@latest docs 并获取 URL。 这能确保你基于正确的 API 和用法模式工作，而非凭空猜测。

工作流

1. 获取项目上下文 —— 已在上方注入。如需刷新，请再次运行 npx shadcn@latest info。
2. 优先检查已安装组件 —— 在运行 add 之前，始终从项目上下文中检查 components 列表或列出 resolvedPaths.ui 目录。不要导入尚未添加的组件，也不要重复添加已安装的组件。
3. 查找组件 —— npx shadcn@latest search。
4. 获取文档与示例 —— 运行 npx shadcn@latest docs <component> 获取 URL 并提取内容。使用 npx shadcn@latest view 浏览尚未安装的注册表项。要预览已安装组件的更改，使用 npx shadcn@latest add --diff。
5. 安装或更新 —— npx shadcn@latest add。更新现有组件时，使用 --dry-run 和 --diff 预检更改（见下文 更新组件）。
6. 修复第三方组件的导入 —— 从社区注册表（如 @bundui, @magicui）添加组件后，检查新增的非 UI 文件中是否存在硬编码的导入路径（如 @/components/ui/...）。这些可能与项目实际别名不符。使用 npx shadcn@latest info 获取正确的 ui 别名（如 @workspace/ui/components）并重写导入。CLI 会重写其自身 UI 文件的导入，但第三方注册表组件可能使用不匹配的默认路径。
7. 检查新增组件 —— 从任何注册表添加组件或区块后，务必阅读新增文件并验证其正确性。检查是否缺少子组件（如只有 SelectItem 缺少 SelectGroup）、缺少导入、组合错误或违反了 关键规则。同时根据项目上下文中的 iconLibrary 替换图标导入。在继续之前修复所有问题。
8. 注册表必须明确 —— 当用户要求添加区块或组件时，不要猜测注册表。如果没有指定注册表（如用户说“添加登录区块”而未指明 @shadcn, @tailark 等），请询问使用哪个注册表。绝不代表用户默认选择注册表。
9. 切换预设 —— 先询问用户：覆盖 (overwrite)、部分 (partial)、合并 (merge) 还是 跳过 (skip)？
   • 覆盖：npx shadcn@latest apply --preset <code>。覆盖检测到的组件、字体和 CSS 变量。
   • 部分：npx shadcn@latest apply --preset <code> --only theme,font。仅更新选定的预设部分，不重新安装 UI 组件。支持的值为 theme 和 font；允许逗号分隔的组合。icon 故意不予支持，因为图标更改可能需要全组件重新安装和转换。
   • 合并：执行 npx shadcn@latest init --preset <code> --force --no-reinstall，然后运行 npx shadcn@latest info 列出已安装组件，接着对每个已安装组件使用 --dry-run 和 --diff 进行智能合并。
   • 跳过：npx shadcn@latest init --preset <code> --force --no-reinstall。仅更新配置和 CSS，保留组件不变。
   • 重要提示：始终在用户项目目录内运行预设命令。apply 仅适用于已有 components.json 文件的现有项目。CLI 会自动保留 components.json 中的当前基础（base vs radix）。如果必须使用临时目录（如进行 --dry-run 对比），请显式传递 --base <current-base> —— 预设代码不包含基础库信息。

更新组件

当用户要求从上游更新组件并保留本地修改时，使用 --dry-run 和 --diff 进行智能合并。绝不手动从 GitHub 获取原始文件 —— 始终使用 CLI。

1. 运行 npx shadcn@latest add <component> --dry-run 查看受影响的文件。
2. 对每个文件，运行 npx shadcn@latest add <component> --diff <file> 查看上游与本地的差异。
3. 根据差异决定：
   • 无本地修改 → 可安全覆盖。
   • 有本地修改 → 阅读本地文件，分析差异，并在保留本地修改的同时应用上游更新。
   • 用户说“全部更新” → 使用 --overwrite，但需先确认。
4. 未经用户明确同意，绝不使用 --overwrite。

快速参考

# 创建新项目
npx shadcn@latest init --name my-app --preset base-nova
npx shadcn@latest init --name my-app --preset a2r6bw --template vite

# 创建 Monorepo 项目
npx shadcn@latest init --name my-app --preset base-nova --monorepo
npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo

# 初始化现有项目
npx shadcn@latest init --preset base-nova
npx shadcn@latest init --defaults  # 快捷方式：--template=next --preset=nova (隐含 base 样式)

# 对现有项目应用预设
npx shadcn@latest apply --preset a2r6bw
npx shadcn@latest apply a2r6bw
npx shadcn@latest apply --preset a2r6bw --only theme
npx shadcn@latest apply --preset a2r6bw --only font
npx shadcn@latest apply --preset a2r6bw --only theme,font

# 添加组件
npx shadcn@latest add button card dialog
npx shadcn@latest add @magicui/shimmer-button
npx shadcn@latest add --all

# 添加/更新前预览更改
npx shadcn@latest add button --dry-run
npx shadcn@latest add button --diff button.tsx
npx shadcn@latest add @acme/form --view button.tsx

# 搜索注册表
npx shadcn@latest search @shadcn -q "sidebar"
npx shadcn@latest search @tailark -q "stats"

# 获取组件文档和示例 URL
npx shadcn@latest docs button dialog select

# 查看注册表项详情（针对未安装项）
npx shadcn@latest view @shadcn/button

命名预设 (Named presets)： nova, vega, maia, lyra, mira, luma 模板 (Templates)： next, vite, start, react-router, astro (均支持 --monorepo) 以及 laravel (不支持 monorepo) 预设代码 (Preset codes)： 版本前缀的 base62 字符串 (如 a2r6bw 或 b0)，来自 ui.shadcn.com。

详细参考

• rules/forms.md — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, 验证状态
• rules/composition.md — 分组, 覆盖层, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button 加载状态
• rules/icons.md — data-icon, 图标尺寸, 以对象形式传递图标
• rules/styling.md — 语义化颜色, 变体, className, 间距, 尺寸, truncate, 暗黑模式, cn(), z-index
• rules/base-vs-radix.md — asChild vs render, Select, ToggleGroup, Slider, Accordion
• cli.md — 命令, 标志, 预设, 模板
• customization.md — 主题化, CSS 变量, 扩展组件