wehub/skillhub-098-shadcn

Fork 0

Files

T

wehub-skill-sync c77e6c2d17 chore: import zh skill shadcn

2026-07-13 21:36:22 +08:00

5.9 KiB

Raw Permalink Blame History

name, description, metadata

name

description

metadata

customization-theming

shadcn/ui 定制与主题系统文档

type
reference

定制与主题

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

工作原理

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

颜色变量

每种颜色遵循 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：

import { ThemeProvider } from "next-themes"

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

更改主题

# 应用来自 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 文件。

/* 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);
}

/* 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 中注册：

// 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>)",
      },
    },
  },
}

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

边框圆角

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

定制组件

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

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

1. 内置变体

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

2. 通过 `className` 使用 Tailwind 类

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

3. 添加新变体

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

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

4. 包装器组件

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

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>
  )
}

检查更新

npx shadcn@latest add button --diff

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

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

完整智能合并工作流请参阅 SKILL.md 中的更新组件。

5.9 KiB Raw Permalink Blame History Unescape Escape