9.7k
新建

主题化

上一页下一页

使用 CSS 变量和主题令牌。

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

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

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

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

components.json
{
  "style": "default",
  "typescript": true,
  "tailwind": {
    "config": "",
    "css": "assets/css/tailwind.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);

以下组件的 background 颜色将为 var(--primary)，而 foreground 颜色将为 var(--primary-foreground)。

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

主题令牌

这些令牌存在于您 CSS 文件的 :root 和 .dark 选择器下。

令牌控制内容用途
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交互式悬停、焦点和激活状态表面。幽灵按钮、菜单高亮状态、悬停行和选中项。
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-* 令牌。

圆角比例

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

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

assets/css/tailwind.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。

assets/css/tailwind.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 class="bg-warning text-warning-foreground" />

基础颜色

tailwind.baseColor 控制当您运行 init 或使用预设时，为您项目生成的默认令牌值。

可用的基础颜色包括：Neutral（中性色）、Gray（灰色）、Zinc（锌色）、Stone（石色）和 Slate（蓝灰色）。

默认主题 CSS

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

assets/css/tailwind.css
@import "tailwindcss";

@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-vue@latest init --no-css-variables

这会在您的 components.json 文件中将 tailwind.cssVariables 设置为 false。

<div class="bg-zinc-950 text-zinc-50 dark:bg-white dark:text-zinc-950" />
components.json深色模式