113k
新建

主题设置

PreviousNext

使用 CSS 变量和主题 token。

我们使用并推荐用 CSS 变量来做主题。

这样你就能获得语义化的主题 token，比如 background、foreground 和 primary，组件默认就会使用它们。你只需在 CSS 中覆盖这些 token，就能改变应用外观，而无需重写组件类名。

<div className="bg-background text-foreground" />

要使用 CSS 变量进行主题配置，请在 components.json 文件中把 tailwind.cssVariables 设为 true。这也是默认值。

components.json
{
  "style": "base-nova",
  "rsc": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  }
}

Tailwind 会把这些 token 映射到诸如 bg-background、text-foreground、border-border 和 ring-ring 之类的工具类。

深色模式通过在 .dark 选择器内覆盖相同的 token 来工作。有关添加主题提供器和切换 .dark 类，请查看 深色模式文档。

Token 约定

我们使用语义化的 background 和 foreground 配对。基础 token 控制表面颜色，而 -foreground token 控制该表面上的文本和图标颜色。

给定以下 CSS 变量：

--primary: oklch(0.205 0 0);
--primary-foreground: oklch(0.985 0 0);

下面这个组件的 background 颜色会是 var(--primary)，foreground 颜色会是 var(--primary-foreground)。

<div className="bg-primary text-primary-foreground">Hello</div>

主题 Token

这些 token 位于 CSS 文件中的 :root 和 .dark 下。

Token控制内容用于
background / foreground应用默认背景色和文本颜色。页面壳层、页面区块和默认文本。
card / card-foreground提升层级的表面及其内部内容。Card、仪表盘面板、设置面板。
popover / popover-foreground浮层表面及其内部内容。Popover、DropdownMenu、ContextMenu 以及其他覆盖层。
primary / primary-foreground高强调度操作和品牌表面。默认 Button、选中状态、徽章和激活高亮。
secondary / secondary-foreground低强调度的填充操作和辅助表面。次级按钮、次级徽章和辅助 UI。
muted / muted-foreground柔和表面和低强调度内容。描述、占位符、空状态、辅助文本以及低对比度表面。
accent / accent-foreground交互性的悬停、聚焦和激活表面。Ghost 按钮、菜单高亮状态、悬停行和选中项。
destructive破坏性操作和错误强调。破坏性按钮、无效状态和破坏性菜单项。
border默认边框和分隔线。卡片、菜单、表格、分隔线和布局分割。
input表单控件边框和输入表面样式。Input、Textarea、Select 以及描边风格控件。
ring焦点环和轮廓。按钮、输入框、复选框、菜单和其他可聚焦控件。
chart-1 ... chart-5默认图表调色板。图表和由图表驱动的仪表盘块。
sidebar / sidebar-foreground侧边栏基础表面和默认文字。Sidebar 容器及其默认内容。
sidebar-primary / sidebar-primary-foreground侧边栏中的高强调度操作。激活项、图标块、徽章和侧边栏 CTA。
sidebar-accent / sidebar-accent-foreground侧边栏中的悬停和选中状态。侧边栏菜单悬停状态、展开项和交互行。
sidebar-border侧边栏专用边框和分隔线。侧边栏标题、分组和内部分隔线。
sidebar-ring侧边栏专用焦点环。侧边栏内的聚焦控件。
radius基础圆角尺度。卡片、输入框、按钮、弹出层以及派生的 radius-* token。

圆角尺度

--radius 是你主题中的基础圆角 token。

我们会基于它派生出一个小型圆角尺度，让组件既能使用一致的圆角大小，又仍然共享同一个单一来源。

app/globals.css
@theme inline {
  --radius-sm: calc(var(--radius) * 0.6);
  --radius-md: calc(var(--radius) * 0.8);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.4);
  --radius-2xl: calc(var(--radius) * 1.8);
  --radius-3xl: calc(var(--radius) * 2.2);
  --radius-4xl: calc(var(--radius) * 2.6);
}

这意味着：

  • radius-lg 是基础值。
  • 更小的圆角会从 --radius 缩小派生。
  • 更大的圆角会从 --radius 放大派生。
  • 修改 --radius 会更新整个圆角尺度。

添加新 Token

要添加新 token，请在 :root 和 .dark 下定义它，然后使用 @theme inline 将其暴露给 Tailwind。

app/globals.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);
}
 
@theme inline {
  --color-warning: var(--warning);
  --color-warning-foreground: var(--warning-foreground);
}

现在你就可以在组件中使用 bg-warning 和 text-warning-foreground 了。

<div className="bg-warning text-warning-foreground" />

基础颜色

tailwind.baseColor 控制你在运行 init 或使用预设时，为项目生成的默认 token 值。

可用的基础颜色有：Neutral、Stone、Zinc、Mauve、Olive、Mist 和 Taupe。

默认主题 CSS

下面是完整的默认 neutral 主题骨架。将它复制到你的全局 CSS 文件中，并按需调整这些 token。

app/globals.css
@import "tailwindcss";
@import "shadcn/tailwind.css";
 
@custom-variant dark (&:is(.dark *));
 
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-card: var(--card);
  --color-card-foreground: var(--card-foreground);
  --color-popover: var(--popover);
  --color-popover-foreground: var(--popover-foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-secondary-foreground: var(--secondary-foreground);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-accent: var(--accent);
  --color-accent-foreground: var(--accent-foreground);
  --color-destructive: var(--destructive);
  --color-border: var(--border);
  --color-input: var(--input);
  --color-ring: var(--ring);
  --color-chart-1: var(--chart-1);
  --color-chart-2: var(--chart-2);
  --color-chart-3: var(--chart-3);
  --color-chart-4: var(--chart-4);
  --color-chart-5: var(--chart-5);
  --color-sidebar: var(--sidebar);
  --color-sidebar-foreground: var(--sidebar-foreground);
  --color-sidebar-primary: var(--sidebar-primary);
  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
  --color-sidebar-accent: var(--sidebar-accent);
  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
  --color-sidebar-border: var(--sidebar-border);
  --color-sidebar-ring: var(--sidebar-ring);
  --radius-sm: calc(var(--radius) * 0.6);
  --radius-md: calc(var(--radius) * 0.8);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) * 1.4);
  --radius-2xl: calc(var(--radius) * 1.8);
  --radius-3xl: calc(var(--radius) * 2.2);
  --radius-4xl: calc(var(--radius) * 2.6);
}
 
:root {
  --radius: 0.625rem;
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --card: oklch(1 0 0);
  --card-foreground: oklch(0.145 0 0);
  --popover: oklch(1 0 0);
  --popover-foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --secondary-foreground: oklch(0.205 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --accent: oklch(0.97 0 0);
  --accent-foreground: oklch(0.205 0 0);
  --destructive: oklch(0.577 0.245 27.325);
  --border: oklch(0.922 0 0);
  --input: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --chart-1: oklch(0.646 0.222 41.116);
  --chart-2: oklch(0.6 0.118 184.704);
  --chart-3: oklch(0.398 0.07 227.392);
  --chart-4: oklch(0.828 0.189 84.429);
  --chart-5: oklch(0.769 0.188 70.08);
  --sidebar: oklch(0.985 0 0);
  --sidebar-foreground: oklch(0.145 0 0);
  --sidebar-primary: oklch(0.205 0 0);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.97 0 0);
  --sidebar-accent-foreground: oklch(0.205 0 0);
  --sidebar-border: oklch(0.922 0 0);
  --sidebar-ring: oklch(0.708 0 0);
}
 
.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --card: oklch(0.205 0 0);
  --card-foreground: oklch(0.985 0 0);
  --popover: oklch(0.205 0 0);
  --popover-foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
  --secondary: oklch(0.269 0 0);
  --secondary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.269 0 0);
  --muted-foreground: oklch(0.708 0 0);
  --accent: oklch(0.269 0 0);
  --accent-foreground: oklch(0.985 0 0);
  --destructive: oklch(0.704 0.191 22.216);
  --border: oklch(1 0 0 / 10%);
  --input: oklch(1 0 0 / 15%);
  --ring: oklch(0.556 0 0);
  --chart-1: oklch(0.488 0.243 264.376);
  --chart-2: oklch(0.696 0.17 162.48);
  --chart-3: oklch(0.769 0.188 70.08);
  --chart-4: oklch(0.627 0.265 303.9);
  --chart-5: oklch(0.645 0.246 16.439);
  --sidebar: oklch(0.205 0 0);
  --sidebar-foreground: oklch(0.985 0 0);
  --sidebar-primary: oklch(0.488 0.243 264.376);
  --sidebar-primary-foreground: oklch(0.985 0 0);
  --sidebar-accent: oklch(0.269 0 0);
  --sidebar-accent-foreground: oklch(0.985 0 0);
  --sidebar-border: oklch(1 0 0 / 10%);
  --sidebar-ring: oklch(0.556 0 0);
}
 
@layer base {
  * {
    @apply border-border outline-ring/50;
  }
 
  body {
    @apply bg-background text-foreground;
  }
}

不使用 CSS 变量

如果你不想使用 CSS 变量，CLI 也可以改为生成带有内联 Tailwind 颜色工具类的组件。

pnpm dlx shadcn@latest init --no-css-variables

这会把你 components.json 文件中的 tailwind.cssVariables 设为 false。

<div className="bg-zinc-950 text-zinc-50 dark:bg-white dark:text-zinc-950" />