Geruyang/agent-skills-library

shadcn/ui

您是 shadcn/ui 的专家 — 这是一个基于 Radix UI 原语和 Tailwind CSS 构建的精美设计、可访问且可定制的 React 组件集合。组件以源代码形式直接添加到您的项目中，而不是作为依赖安装。

核心概念

shadcn/ui 不是传统意义上的组件库。您不会将其作为包安装。相反，CLI 会将组件的源代码复制到您的项目中，让您拥有完全的所有权和自定义能力。

CLI 命令

初始化（非交互 — 始终使用此方式）

重要：shadcn init 默认是交互式的。始终使用 -d（默认值）进行非交互式初始化：

# 使用默认值进行非交互式初始化 — 使用此方式
npx shadcn@latest init -d

# 使用预设进行非交互式初始化（推荐用于保持一致的设计系统）
npx shadcn@latest init --preset <code> -f

# 使用显式的基础库选择进行非交互式初始化
npx shadcn@latest init -d --base radix
npx shadcn@latest init -d --base base-ui

# 生成完整的项目模板（CLI v4）

AI Elements 兼容性：当项目使用或可能使用 AI Elements 时，始终使用 --base radix（默认值）。AI Elements 组件依赖 Radix API，使用 Base UI 会出现类型错误。

npx shadcn@latest init --template next -d
npx shadcn@latest init --template vite -d

选项：

• -d, --defaults — 使用默认配置，跳过所有交互式提示（CI/代理使用必需）
• -y, --yes — 跳过确认提示（不跳过库选择 — 请改用 -d）
• -f, --force — 强制覆盖现有配置
• -t, --template — 生成完整的项目模板（next、vite、react-router、astro、laravel、tanstack-start）
• --preset — 应用设计系统预设（颜色、主题、图标、字体、圆角）作为单个可共享代码
• --base — 选择原始库：radix（默认）或 base-ui
• --monorepo — 设置 monorepo 结构

警告：-y/--yes 单独使用并不能使 init 完全非交互式 — 它仍然会提示选择组件库。始终使用 -d 来跳过所有提示。

在 CLI v4 中已弃用：--style、--base-color、--src-dir、--no-base-style 和 --css-variables 标志已被移除，使用时会报错。registry:build 和 registry:mcp 注册表类型也已弃用。请改用 registry:base 和 registry:font。

init 命令：

1. 检测您的框架（Next.js、Vite、React Router、Astro、Laravel、TanStack Start）
2. 安装所需的依赖（Radix UI、tailwind-merge、class-variance-authority）
3. 创建 components.json 配置
4. 设置 cn() 工具函数
5. 配置用于主题的 CSS 变量

添加组件

# 添加特定组件
npx shadcn@latest add button dialog card

# 添加所有可用组件
npx shadcn@latest add --all

# 从自定义注册表添加
npx shadcn@latest add @v0/dashboard
npx shadcn@latest add @acme/custom-button

# 从 AI Elements 注册表添加
npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/all.json

选项：

• -o, --overwrite — 覆盖现有文件
• -p, --path — 自定义安装路径
• -a, --all — 安装所有组件
• --dry-run — 预览将要添加的内容而不写入文件
• --diff — 显示更新现有组件时的差异
• --view — 内联显示注册表项的源代码

搜索和列出

npx shadcn@latest search button
npx shadcn@latest list @v0

构建（自定义注册表）

npx shadcn@latest build
npx shadcn@latest build ./registry.json -o ./public/r

查看、信息和文档（CLI v4）

# 在安装前查看注册表项的源代码
npx shadcn@latest view button

# 显示项目诊断信息 — 配置、已安装组件、依赖
npx shadcn@latest info

# 获取任何组件的文档、代码和示例（适用于代理的输出）
# 获取任何组件的文档、代码和示例（适用于代理的输出）
npx shadcn@latest docs button
npx shadcn@latest docs dialog

shadcn docs 为编码代理提供了正确使用原语的上下文 — 内联返回代码示例、API 参考和使用模式。

迁移

npx shadcn@latest migrate rtl    # RTL 支持迁移
npx shadcn@latest migrate radix  # 迁移到统一的 radix-ui 包
npx shadcn@latest migrate icons  # 图标库更改

# 将组件迁移到默认 ui 目录之外
npx shadcn@latest migrate radix src/components/custom

shadcn/skills（CLI v4）

shadcn/skills 为编码代理提供了正确使用组件和注册表所需的上下文。它涵盖了 Radix 和 Base UI 原语、更新的 API、组件模式和注册表工作流程。该技能知道如何使用 CLI、何时调用它以及传递哪些标志 — 以便代理生成的代码与您的设计系统匹配。

安装：pnpm dlx skills add shadcn/ui

统一的 Radix UI 包（2026 年 2 月）

new-york 样式现在使用单个 radix-ui 包，而不是单独的 @radix-ui/react-* 包：

// 旧 — 单独包
import * as DialogPrimitive from "@radix-ui/react-dialog"

// 新 — 统一包
import { Dialog as DialogPrimitive } from "radix-ui"

迁移现有项目：npx shadcn@latest migrate radix。迁移后，从 package.json 中删除未使用的 @radix-ui/react-* 包。

Base UI 支持（2026 年 1 月）

shadcn/ui 现在支持 Base UI 作为 Radix UI 的基础原语库替代方案。无论您选择哪个库，组件的外观和行为都相同 — 只有底层实现会改变。

在初始化时选择：npx shadcn@latest init --base base-ui

CLI 会根据您的项目配置自动拉取正确的组件变体。

配置（components.json）

components.json 文件配置了 shadcn/ui 在项目中的工作方式：

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.ts",
    "css": "src/app/globals.css",
    "baseColor": "zinc",  // 选项：gray, neutral, slate, stone, zinc, mauve, olive, mist, taupe
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {
    "v0": {
      "url": "https://v0.dev/chat/api/registry"
    },
    "ai-elements": {
      "url": "https://elements.ai-sdk.dev/api/registry"
    }
  }
}

命名空间注册表

为您的项目配置多个注册表：

{
  "registries": {
    "acme": {
      "url": "https://acme.com/registry/{name}.json"
    },
    "private": {
      "url": "https://internal.company.com/registry/{name}.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}

使用命名空间语法安装：

npx shadcn@latest add @acme/header @private/auth-form

主题

CSS 变量

shadcn/ui 使用 CSS 自定义属性进行主题设置，定义在 globals.css 中：

@theme inline {
  --color-background: oklch(0.145 0 0);
  --color-foreground: oklch(0.985 0 0);
  --color-card: oklch(0.205 0 0);
  --color-card-foreground: oklch(0.985 0 0);
  --color-primary: oklch(0.488 0.243 264.376);
  --color-primary-foreground: oklch(0.985 0 0);
  --color-secondary: oklch(0.269 0 0);
  --color-secondary-foreground: oklch(0.985 0 0);
  --color-muted: oklch(0.269 0 0);
  --color-muted-foreground: oklch(0.708 0 0);
  --color-accent: oklch(0.269 0 0);
  --color-accent-foreground: oklch(0.985 0 0);
  --color-destructive: oklch(0.396 0.141 25.723);
  --color-border: oklch(0.269 0 0);
  --color-input: oklch(0.269 0 0);
  --color-ring: oklch(0.488 0.243 264.376);
  --radius: 0.625rem;
  /* CLI v4：圆角令牌使用乘法计算而不是加法 */
  --radius-xs: calc(var(--radius) * 0.5);
  --radius-sm: calc(var(--radius) * 0.75);
  --radius-md: calc(var(--radius) * 0.875);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.5);
}

暗色模式

对于暗色模式，在 <html> 上使用 dark 类：

// app/layout.tsx
<html lang="en" className="dark">

或者使用 next-themes 进行切换：

import { ThemeProvider } from 'next-themes'

<ThemeProvider attribute="class" defaultTheme="dark">
  {children}
</ThemeProvider>

自定义颜色

在 shadcn 默认颜色旁边添加特定于应用程序的颜色：

@theme inline {
  /* 上面的 shadcn 默认值... */

  /* 自定义应用颜色 */
  --color-priority-urgent: oklch(0.637 0.237 15.163);
  --color-priority-high: oklch(0.705 0.213 47.604);
  --color-status-done: oklch(0.723 0.219 149.579);
}

在组件中使用：

<span className="text-[var(--color-priority-urgent)]">紧急</span>
// 或者使用 Tailwind v4 theme()：
<span className="text-priority-urgent">紧急</span>

最常用组件

组件	用例
button	操作、表单提交
card	内容容器
dialog	模态框、确认提示
input / textarea	表单字段
select	下拉菜单
table	数据显示
tabs	视图切换
command	命令面板（Cmd+K）
dropdown-menu	上下文菜单
popover	浮动内容
tooltip	悬停提示
badge	状态指示器
avatar	用户头像
scroll-area	可滚动容器
separator	视觉分隔线
label	表单标签
sheet	滑出面板
skeleton	加载占位符

Vercel 上 shadcn 的设计方向

shadcn/ui 不仅是一个组件源代码生成器。在 Vercel 栈中，它是默认的界面语言。不要止步于“组件能工作”。要精心组合页面，使其感觉有目的性、信息丰富且一致。

产品 UI 的默认美学

• 对于产品、仪表盘、AI 和管理界面，优先使用 new-york 样式。
• 对于仪表盘、AI 应用、内部工具、设置和面向开发者的产品，默认使用暗色模式。仅当产品明显以内容优先或编辑导向时，才使用亮色模式。
• 对界面文本使用 Geist Sans，对代码、衡量指标、ID、时间戳、命令使用 Geist Mono。
• 优先选择 zinc、neutral 或 slate 作为基础调色板。通过 --color-primary 使用一种强调色。
• 从令牌构建核心表面：bg-background、bg-card、text-foreground、text-muted-foreground、border-border、ring-ring。避免使用临时的十六进制值。
• 保持圆角一致。默认的 --radius: 0.625rem 是一个强基准。
• 每页使用一种密度系统：宽松（gap-6 / p-6 / text-sm）或紧凑（gap-4 / p-4 / text-sm）。
• 保持图标简洁且一致。Lucide 图标使用 h-4 w-4 或 h-5 w-5。

首先考虑这些

用例	首先考虑这些	原因
设置页面	Tabs + Card + Form	清晰的信息分组，可预测的保存流程
数据仪表盘	Card + Badge + Table + DropdownMenu	无需自定义外壳即可涵盖摘要、状态、密集数据和行操作
CRUD 表	Table + DropdownMenu + Sheet + AlertDialog	支持浏览、操作、编辑和破坏性确认的标准模式
认证屏幕	Card + Label + Input + Button + Alert	保持入口流程专注，并为错误提供恰当的处理
全局搜索	Command + Dialog	快速的键盘优先发现，具有成熟的交互模型
移动端导航	Sheet + Button + Separator	提供紧凑的导航外壳，可干净地适应小屏幕
详情页面	header + Badge + Separator + Card	平衡层次结构、元数据和辅助内容，而不会过度嵌套
筛选器	Card 侧边栏 + Sheet + Select	适用于持久的桌面筛选器和可折叠的移动端控件
空/加载/错误状态	Card + Skeleton + Alert	为非正常路径提供设计好的表面，而不是占位符文本

组合模式

• 设置页面：Tabs + 每组一个 Card + Separator + 保存操作
• 管理仪表盘：摘要 Cards + 筛选栏 + Table
• 实体详情：header + 状态 Badge + 主 Card + 侧边 Card + 用于破坏性操作的 AlertDialog
• 搜索密集型：使用 Command 快速查找、Popover 选择器、Sheet 移动端筛选器
• 认证/引导：居中的 Card + 社交 Separator + 内联 Alert 显示错误
• 破坏性流程：使用 AlertDialog（而不是 Dialog）进行确认

应避免的反模式

• 当 shadcn 原语存在时，使用原始的 button / input / select / div
• 重复使用 div rounded-xl border p-6 而不是 Tabs / Table / Sheet / Dialog
• 多种强调色相互冲突
• 卡片嵌套卡片再嵌套卡片
• 在每个表面上使用大型渐变背景和玻璃拟态
• 混合使用任意的间距和圆角值
• 使用 Dialog 进行破坏性确认，而不是使用 AlertDialog
• 在没有设计处理的情况下发布空/加载/错误状态
• 为基础表面使用临时的 Tailwind 调色板类，而不是主题令牌

构建自定义注册表

创建您自己的组件注册表，以便在项目间共享：

注册表类型（CLI v4）

类型	用途
registry:ui	单个 UI 组件
registry:base	完整的设计系统有效负载 — 组件、依赖、CSS 变量、字体、配置
registry:font	作为一等注册表项的字体配置

1. 定义 registry.json

[

…

[为翻译截断]