113k
New

主题化

PreviousNext

使用 CSS 变量和主题令牌。

我们使用并推荐使用 CSS 变量进行主题化。

这为你提供了语义化的主题令牌，如 background、foreground 和 primary，组件默认使用这些令牌。在 CSS 中覆盖这些令牌即可更改应用的外观，而无需重写组件类。

<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 将这些令牌映射为实用工具类，如 bg-background、text-foreground、border-border 和 ring-ring。

深色模式通过在 .dark 选择器内覆盖相同的令牌来工作。请参阅 深色模式文档 了解如何添加主题提供者并切换 .dark 类。

令牌约定

我们使用语义化的背景和前景配对。基础令牌控制表面颜色，而 -foreground 令牌控制位于该表面上的文本和图标颜色。

假设有如下 CSS 变量：

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

那么下面组件的背景色将是 var(--primary)，文本颜色为 var(--primary-foreground)。

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

主题令牌

这些令牌位于你的 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交互 hover、focus 和 active 表面。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基础圆角比例。卡片、输入框、按钮、popovers 和派生的 radius-* 令牌。

圆角比例

--radius 是你主题的基础圆角令牌。

我们从中派生出一个小的圆角比例，以便组件可以使用一致的圆角大小，同时共享单一事实来源。

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 会更新整个圆角比例。

添加新令牌

要添加新令牌，请在 :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 或使用预设时为项目生成的默认令牌值。

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

默认主题 CSS

以下是完整的默认 neutral 主题脚手架。将其复制到你的全局 CSS 文件中并根据需要调整令牌。

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" />