---
name: customization-theming
description: shadcn/ui 定制与主题系统文档
metadata:
  type: reference
---

# 定制与主题

组件引用语义化的 CSS 变量令牌。修改变量即可更改所有组件。

## 目录

- 工作原理（CSS 变量 → Tailwind 工具类 → 组件）
- 颜色变量与 OKLCH 格式
- 深色模式设置
- 更改主题（预设、CSS 变量）
- 添加自定义颜色（Tailwind v3 和 v4）
- 边框圆角
- 定制组件（变体、className、包装器）
- 检查更新

---

## 工作原理

1. 在 `:root`（浅色）和 `.dark`（深色模式）中定义 CSS 变量。
2. Tailwind 将其映射为工具类：`bg-primary`、`text-muted-foreground` 等。
3. 组件使用这些工具类——更改某个变量即可更改所有引用它的组件。

---

## 颜色变量

每种颜色遵循 `name` / `name-foreground` 命名约定。基础变量用于背景，`-foreground` 用于该背景上的文本/图标。

| 变量                                        | 用途                          |
| -------------------------------------------- | -------------------------------- |
| `--background` / `--foreground`              | 页面背景与默认文本 |
| `--card` / `--card-foreground`               | 卡片表面                    |
| `--primary` / `--primary-foreground`         | 主要按钮与操作      |
| `--secondary` / `--secondary-foreground`     | 次要操作                |
| `--muted` / `--muted-foreground`             | 弱化/禁用状态            |
| `--accent` / `--accent-foreground`           | 悬停与强调状态          |
| `--destructive` / `--destructive-foreground` | 错误与破坏性操作    |
| `--border`                                   | 默认边框颜色             |
| `--input`                                    | 表单输入边框               |
| `--ring`                                     | 聚焦环颜色                 |
| `--chart-1` 至 `--chart-5`              | 图表/数据可视化         |
| `--sidebar-*`                                | 侧边栏专用颜色          |
| `--surface` / `--surface-foreground`         | 次级表面                |

颜色使用 OKLCH 格式：`--primary: oklch(0.205 0 0)`，其中各值分别为明度（0–1）、色度（0 = 灰色）和色相（0–360）。

---

## 深色模式

通过根元素上的 `.dark` 类进行切换。在 Next.js 中，使用 `next-themes`：

```tsx
import { ThemeProvider } from "next-themes"

<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
  {children}
</ThemeProvider>
```

---

## 更改主题

```bash
# 应用来自 ui.shadcn.com 的预设代码。
npx shadcn@latest init --preset a2r6bw --force

# 切换到命名预设。
npx shadcn@latest init --preset radix-nova --force
npx shadcn@latest init --reinstall  # 更新现有组件以匹配

# 使用自定义主题 URL。
npx shadcn@latest init --preset "https://ui.shadcn.com/init?base=radix&style=nova&theme=blue&..." --force
```

或者直接在 `globals.css` 中编辑 CSS 变量。

---

## 添加自定义颜色

将变量添加到 `npx shadcn@latest info` 返回的 `tailwindCssFile` 所指向的文件中（通常为 `globals.css`）。切勿为此创建新的 CSS 文件。

```css
/* 1. 在全局 CSS 文件中定义。 */
:root {
  --warning: oklch(0.84 0.16 84);
  --warning-foreground: oklch(0.28 0.07 46);
}
.dark {
  --warning: oklch(0.41 0.11 46);
  --warning-foreground: oklch(0.99 0.02 95);
}
```

```css
/* 2a. 在 Tailwind v4 中注册（@theme inline）。 */
@theme inline {
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
}
```

当 `tailwindVersion` 为 `"v3"` 时（通过 `npx shadcn@latest info` 检查），改为在 `tailwind.config.js` 中注册：

```js
// 2b. 在 Tailwind v3 中注册（tailwind.config.js）。
module.exports = {
  theme: {
    extend: {
      colors: {
        warning: "oklch(var(--warning) / <alpha-value>)",
        "warning-foreground":
          "oklch(var(--warning-foreground) / <alpha-value>)",
      },
    },
  },
}
```

```tsx
// 3. 在组件中使用。
<div className="bg-warning text-warning-foreground">Warning</div>
```

---

## 边框圆角

`--radius` 全局控制边框圆角。组件从其派生值（`rounded-lg` = `var(--radius)`，`rounded-md` = `calc(var(--radius) - 2px)`）。

---

## 定制组件

另请参阅：[rules/styling.md](./rules/styling.md) 中的错误/正确示例。

按以下顺序优先选择这些方法：

### 1. 内置变体

```tsx
<Button variant="outline" size="sm">Click</Button>
```

### 2. 通过 `className` 使用 Tailwind 类

```tsx
<Card className="max-w-md mx-auto">...</Card>
```

### 3. 添加新变体

编辑组件源码，通过 `cva` 添加变体：

```tsx
// components/ui/button.tsx
warning: "bg-warning text-warning-foreground hover:bg-warning/90",
```

### 4. 包装器组件

将 shadcn/ui 基础组件组合成更高级的组件：

```tsx
export function ConfirmDialog({ title, description, onConfirm, children }) {
  return (
    <AlertDialog>
      <AlertDialogTrigger asChild>{children}</AlertDialogTrigger>
      <AlertDialogContent>
        <AlertDialogHeader>
          <AlertDialogTitle>{title}</AlertDialogTitle>
          <AlertDialogDescription>{description}</AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Cancel</AlertDialogCancel>
          <AlertDialogAction onClick={onConfirm}>Confirm</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  )
}
```

---

## 检查更新

```bash
npx shadcn@latest add button --diff
```

要在更新前预览具体变化，请使用 `--dry-run` 和 `--diff`：

```bash
npx shadcn@latest add button --dry-run        # 查看所有受影响的文件
npx shadcn@latest add button --diff button.tsx # 查看特定文件的差异
```

完整智能合并工作流请参阅 [SKILL.md 中的更新组件](./SKILL.md#updating-components)。