---
title: 颜色
description: HeroUI v3 的调色板与主题系统
icon: bucket-paint
links:
  themes: true
  tailwind: theme
---

import {ColorSectionSideBySide, ColorSectionStacked, ColorSectionFormField, ColorSectionPrimitive} from "@/components/color-section";

HeroUI 的颜色体系围绕语义意图构建，而非堆砌视觉色板。系统不会暴露庞大的原始色表，而是定义一小套有意义的色彩角色，覆盖绝大多数界面需求。

系统中的多数颜色会由少量基础值自动派生。这样 HeroUI 能在保持对比度、层级与主题行为一致的同时，让整套体系易于理解与修改。

颜色应首先传达用途与状态；视觉变化来自尺度、强调与上下文。

<Callout type="info">
  **想要创建你自己的主题？** 试试 [主题构建器](/themes)，以可视化方式自定义颜色、圆角、字体等，然后导出 CSS 用于你的项目。
</Callout>

## 强调色

强调色代表品牌或产品的主识别色，用于吸引对关键操作、高亮与重点时刻的注意。

强调色应有意识地节制使用。滥用会削弱其冲击力，并破坏视觉层级。多数情况下，组件会从基础强调色自动派生悬停、柔和背景与聚焦等相关取值。

<ColorSectionSideBySide
  name="强调色"
  baseVariable="--accent"
  baseTooltip={"--accent: oklch(0.6204 0.195 253.83)"}
  hoverVariable="--accent"
  hoverCssValue="color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%)"
  hoverTooltip={"--color-accent-hover:\n  color-mix(\n    in oklab,\n    var(--accent) 90%,\n    var(--accent-foreground) 10%\n  )"}
  foregroundVariable="--accent-foreground"
  foregroundTooltip={"--accent-foreground: var(--snow)"}
  soft={{
    baseVariable: "--accent",
    baseCssValue: "color-mix(in oklab, var(--accent) 15%, transparent)",
    baseTooltip: "--color-accent-soft:\n  color-mix(\n    in oklab,\n    var(--accent) 15%,\n    transparent\n  )",
    hoverVariable: "--accent",
    hoverCssValue: "color-mix(in oklab, var(--accent) 20%, transparent)",
    hoverTooltip: "--color-accent-soft-hover:\n  color-mix(\n    in oklab,\n    var(--accent) 20%,\n    transparent\n  )",
    foregroundVariable: "--accent",
    foregroundCssValue: "var(--accent)",
    foregroundTooltip: "--color-accent-soft-foreground: var(--accent)",
  }}
/>

## 默认（中性色）

默认色构成系统的中性骨架，用于大多数非强调的界面元素。

<ColorSectionSideBySide
  name="默认"
  baseVariable="--default"
  baseTooltip={"--default: oklch(94% 0.001 286.375)"}
  hoverVariable="--default"
  hoverCssValue="color-mix(in oklab, var(--default) 96%, var(--default-foreground) 4%)"
  hoverTooltip={"--color-default-hover:\n  color-mix(\n    in oklab,\n    var(--default) 96%,\n    var(--default-foreground) 4%\n  )"}
  foregroundVariable="--default-foreground"
  foregroundTooltip={"--default-foreground: var(--eclipse)"}
/>

## 成功

成功色传达积极结果、确认与完成状态，常见于反馈组件、状态指示与校验通过等场景。

<ColorSectionSideBySide
  name="成功"
  baseVariable="--success"
  baseTooltip={"--success: oklch(0.7329 0.1935 150.81)"}
  hoverVariable="--success"
  hoverCssValue="color-mix(in oklab, var(--success) 90%, var(--success-foreground) 10%)"
  hoverTooltip={"--color-success-hover:\n  color-mix(\n    in oklab,\n    var(--success) 90%,\n    var(--success-foreground) 10%\n  )"}
  foregroundVariable="--success-foreground"
  foregroundTooltip={"--success-foreground: var(--eclipse)"}
  soft={{
    baseVariable: "--success",
    baseCssValue: "color-mix(in oklab, var(--success) 15%, transparent)",
    baseTooltip: "--color-success-soft:\n  color-mix(\n    in oklab,\n    var(--success) 15%,\n    transparent\n  )",
    hoverVariable: "--success",
    hoverCssValue: "color-mix(in oklab, var(--success) 20%, transparent)",
    hoverTooltip: "--color-success-soft-hover:\n  color-mix(\n    in oklab,\n    var(--success) 20%,\n    transparent\n  )",
    foregroundVariable: "--success",
    foregroundCssValue: "var(--success)",
    foregroundTooltip: "--color-success-soft-foreground: var(--success)",
  }}
/>

## 警告

警告色表示需谨慎、存在风险，或需要留意但非破坏性的操作，常用于提示、消息以及用户应暂停或复核信息的过渡状态。

<ColorSectionSideBySide
  name="警告"
  baseVariable="--warning"
  baseTooltip={"--warning: oklch(0.7819 0.1585 72.33)"}
  hoverVariable="--warning"
  hoverCssValue="color-mix(in oklab, var(--warning) 90%, var(--warning-foreground) 10%)"
  hoverTooltip={"--color-warning-hover:\n  color-mix(\n    in oklab,\n    var(--warning) 90%,\n    var(--warning-foreground) 10%\n  )"}
  foregroundVariable="--warning-foreground"
  foregroundTooltip={"--warning-foreground: var(--eclipse)"}
  soft={{
    baseVariable: "--warning",
    baseCssValue: "color-mix(in oklab, var(--warning) 15%, transparent)",
    baseTooltip: "--color-warning-soft:\n  color-mix(\n    in oklab,\n    var(--warning) 15%,\n    transparent\n  )",
    hoverVariable: "--warning",
    hoverCssValue: "color-mix(in oklab, var(--warning) 20%, transparent)",
    hoverTooltip: "--color-warning-soft-hover:\n  color-mix(\n    in oklab,\n    var(--warning) 20%,\n    transparent\n  )",
    foregroundVariable: "--warning",
    foregroundCssValue: "var(--warning)",
    foregroundTooltip: "--color-warning-soft-foreground: var(--warning)",
  }}
/>

## 危险

危险色表示破坏性、不可逆或关键的操作与状态，应一眼可辨，并稳定用于错误、危险按钮与严重告警。

<ColorSectionSideBySide
  name="危险"
  baseVariable="--danger"
  baseTooltip={"--danger: oklch(0.6532 0.2328 25.74)"}
  hoverVariable="--danger"
  hoverCssValue="color-mix(in oklab, var(--danger) 90%, var(--danger-foreground) 10%)"
  hoverTooltip={"--color-danger-hover:\n  color-mix(\n    in oklab,\n    var(--danger) 90%,\n    var(--danger-foreground) 10%\n  )"}
  foregroundVariable="--danger-foreground"
  foregroundTooltip={"--danger-foreground: var(--snow)"}
  soft={{
    baseVariable: "--danger",
    baseCssValue: "color-mix(in oklab, var(--danger) 15%, transparent)",
    baseTooltip: "--color-danger-soft:\n  color-mix(\n    in oklab,\n    var(--danger) 15%,\n    transparent\n  )",
    hoverVariable: "--danger",
    hoverCssValue: "color-mix(in oklab, var(--danger) 20%, transparent)",
    hoverTooltip: "--color-danger-soft-hover:\n  color-mix(\n    in oklab,\n    var(--danger) 20%,\n    transparent\n  )",
    foregroundVariable: "--danger",
    foregroundCssValue: "var(--danger)",
    foregroundTooltip: "--color-danger-soft-foreground: var(--danger)",
  }}
/>

## 前景色

前景色用于正文级内容，如文字与图标。这些颜色针对可读性与无障碍优化，并会随背景与表面上下文自动适配。请勿在组件内硬编码前景色。

<ColorSectionStacked
  lightColors={[
    { label: "前景", variable: "--foreground", tooltip: "--foreground: var(--eclipse)" },
    { label: "弱化", variable: "--muted", tooltip: "--muted: oklch(0.5517 0.0138 285.94)" },
    { label: "分段", variable: "--segment", tooltip: "--segment: var(--white)" },
    { label: "遮罩", variable: "--overlay", tooltip: "--overlay: var(--white)" },
    { label: "链接", variable: "--link", tooltip: "--link: var(--foreground)" },
  ]}
  darkColors={[
    { label: "前景", variable: "--foreground", border: true, tooltip: "--foreground: var(--snow)" },
    { label: "弱化", variable: "--muted", border: true, tooltip: "--muted: oklch(70.5% 0.015 286.067)" },
    { label: "分段", variable: "--segment", border: true, tooltip: "--segment: oklch(0.3964 0.01 285.93)" },
    { label: "遮罩", variable: "--overlay", border: true, tooltip: "--overlay: oklch(0.2103 0.0059 285.89)" },
    { label: "链接", variable: "--link", border: true, tooltip: "--link: var(--foreground)" },
  ]}
/>

## 背景色

背景色定义界面的基底画布，在保持视觉克制的前提下建立整体对比与氛围。

<ColorSectionStacked
  lightColors={[
    { label: "背景", variable: "--background", border: true, tooltip: "--background: oklch(0.9702 0 0)" },
    { label: "次级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 96%, var(--foreground) 4%)", border: true, tooltip: "--color-background-secondary:\n  color-mix(\n    in oklab,\n    var(--background) 96%,\n    var(--foreground) 4%\n  )" },
    { label: "第三级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 92%, var(--foreground) 8%)", border: true, tooltip: "--color-background-tertiary:\n  color-mix(\n    in oklab,\n    var(--background) 92%,\n    var(--foreground) 8%\n  )" },
    { label: "反色", variable: "--foreground", tooltip: "--color-background-inverse: var(--foreground)" },
  ]}
  darkColors={[
    { label: "背景", variable: "--background", border: true, tooltip: "--background: oklch(12% 0.005 285.823)" },
    { label: "次级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 96%, var(--foreground) 4%)", border: true, tooltip: "--color-background-secondary:\n  color-mix(\n    in oklab,\n    var(--background) 96%,\n    var(--foreground) 4%\n  )" },
    { label: "第三级", variable: "--background", cssValue: "color-mix(in oklab, var(--background) 92%, var(--foreground) 8%)", border: true, tooltip: "--color-background-tertiary:\n  color-mix(\n    in oklab,\n    var(--background) 92%,\n    var(--foreground) 8%\n  )" },
    { label: "反色", variable: "--foreground", border: true, tooltip: "--color-background-inverse: var(--foreground)" },
  ]}
/>

## 表面色

表面色叠在背景之上，用于卡片、面板、模态与下拉等容器。表面通过抬升、对比与分层形成区隔与层级，而非依赖强烈的色相跳跃。

<ColorSectionStacked
  lightColors={[
    { label: "表面", variable: "--surface", border: true, tooltip: "--surface: var(--white)" },
    { label: "次级", variable: "--surface-secondary", border: true, tooltip: "--surface-secondary: oklch(0.9524 0.0013 286.37)" },
    { label: "第三级", variable: "--surface-tertiary", border: true, tooltip: "--surface-tertiary: oklch(0.9373 0.0013 286.37)" },
  ]}
  darkColors={[
    { label: "表面", variable: "--surface", border: true, tooltip: "--surface: oklch(0.2103 0.0059 285.89)" },
    { label: "次级", variable: "--surface-secondary", border: true, tooltip: "--surface-secondary: oklch(0.257 0.0037 286.14)" },
    { label: "第三级", variable: "--surface-tertiary", border: true, tooltip: "--surface-tertiary: oklch(0.2721 0.0024 247.91)" },
  ]}
/>

## 表单字段

表单字段色是面向输入、控件与可交互字段的专用令牌，覆盖默认、聚焦与悬停等多种状态。将其独立出来，可让表单元素在视觉上与按钮及界面其余部分保持清晰区分。

<ColorSectionFormField
  colors={{
    bg: "--field-background",
    bgTooltip: "--field-background: var(--white)",
    bgHover: "color-mix(in oklab, var(--field-background) 90%, var(--field-foreground) 10%)",
    bgHoverTooltip: "--color-field-hover:\n  color-mix(\n    in oklab,\n    var(--field-background, var(--default)) 90%,\n    var(--field-foreground, var(--foreground)) 2%\n  )",
    bgFocusTooltip: "--color-field-focus:\n  var(--field-background, var(--default))",
    placeholder: "--field-placeholder",
    placeholderTooltip: "--field-placeholder: var(--muted)",
    foreground: "--field-foreground",
    foregroundTooltip: "--field-foreground: oklch(0.2103 0.0059 285.89)",
  }}
/>

## 分隔线

分隔线色用于分割线、描边与轻量边界，用来组织内容、引导视线而不增加噪点。分隔线色应保持低对比、不抢眼。

<ColorSectionStacked
  lightColors={[
    { label: "分隔线", variable: "--separator", border: true, tooltip: "--separator: oklch(92% 0.004 286.32)" },
    { label: "次级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%)", border: true, tooltip: "--color-separator-secondary:\n  color-mix(\n    in oklab,\n    var(--surface) 85%,\n    var(--surface-foreground) 15%\n  )" },
    { label: "第三级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%)", border: true, tooltip: "--color-separator-tertiary:\n  color-mix(\n    in oklab,\n    var(--surface) 81%,\n    var(--surface-foreground) 19%\n  )" },
  ]}
  darkColors={[
    { label: "分隔线", variable: "--separator", border: true, tooltip: "--separator: oklch(25% 0.006 286.033)" },
    { label: "次级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 85%, var(--surface-foreground) 15%)", border: true, tooltip: "--color-separator-secondary:\n  color-mix(\n    in oklab,\n    var(--surface) 85%,\n    var(--surface-foreground) 15%\n  )" },
    { label: "第三级", variable: "--surface", cssValue: "color-mix(in oklab, var(--surface) 81%, var(--surface-foreground) 19%)", border: true, tooltip: "--color-separator-tertiary:\n  color-mix(\n    in oklab,\n    var(--surface) 81%,\n    var(--surface-foreground) 19%\n  )" },
  ]}
/>

## 其他

其他颜色在界面中承担特定工具性角色，用于组织内容、引导视线而不增加噪点。

<ColorSectionStacked
  lightColors={[
    { label: "边框", variable: "--border", tooltip: "--border: oklch(90% 0.004 286.32)" },
    { label: "背衬", variable: "--backdrop", tooltip: "--backdrop: rgba(0, 0, 0, 0.5)" },
    { label: "遮罩", variable: "--overlay", border: true, tooltip: "--overlay: var(--white)" },
    { label: "分段", variable: "--segment", border: true, tooltip: "--segment: var(--white)" },
  ]}
  darkColors={[
    { label: "边框", variable: "--border", tooltip: "--border: oklch(28% 0.006 286.033)" },
    { label: "背衬", variable: "--backdrop", tooltip: "--backdrop: rgba(0, 0, 0, 0.6)" },
    { label: "遮罩", variable: "--overlay", border: true, tooltip: "--overlay: oklch(0.2103 0.0059 285.89)" },
    { label: "分段", variable: "--segment", border: true, tooltip: "--segment: oklch(0.3964 0.01 285.93)" },
  ]}
/>

## 基础色

基础色是与模式无关的底层取值，作为语义色令牌的根基，在明暗主题之间不会改变。

<ColorSectionPrimitive
  colors={[
    { label: "白", variable: "--white", border: true, tooltip: "--white: oklch(100% 0 0)" },
    { label: "黑", variable: "--black", tooltip: "--black: oklch(0% 0 0)" },
    { label: "雪白", variable: "--snow", border: true, tooltip: "--snow: oklch(0.9911 0 0)" },
    { label: "月蚀", variable: "--eclipse", tooltip: "--eclipse: oklch(0.2103 0.0059 285.89)" },
  ]}
/>

## 如何使用颜色

**在组件中：**
```jsx
<div className="bg-background text-foreground">
  <button className="bg-accent text-accent-foreground hover:bg-accent-hover">
    点击我
  </button>
</div>
```

**在 CSS 文件中：**

```css title="global.css"
/* 直接使用 CSS 变量 */
.my-component {
  background: var(--accent);
  color: var(--accent-foreground);
  border: 1px solid var(--border);
}

/* 配合 @apply 与 @layer */
@layer components {
  .button {
    @apply bg-accent text-accent-foreground;

    &:hover,
    &[data-hovered="true"] {
      @apply bg-accent-hover;
    }

    &:active,
    &[data-pressed="true"] {
      @apply bg-accent-hover;
      transform: scale(0.97);
    }
  }
}
```

## 默认主题

完整主题定义见仓库中的 [variables.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/default/variables.css)。该主题会根据 `class="dark"` 或 `data-theme="dark"` 属性在明暗模式间自动切换。

<CollapsibleCode lang="css" code={`  @layer base {
    /* HeroUI 默认主题 */
    :root {
      color-scheme: light;

      /* == 通用变量 == */

      /* 基础色（在明暗模式下勿改动） */
      --white: oklch(100% 0 0);
      --black: oklch(0% 0 0);
      --snow: oklch(0.9911 0 0);
      --eclipse: oklch(0.2103 0.0059 285.89);

      /* 间距刻度 */
      --spacing: 0.25rem;

      /* 边框 */
      --border-width: 1px;
      --field-border-width: 0px;
      --disabled-opacity: 0.5;

      /* 聚焦环偏移，用于聚焦环 */
      --ring-offset-width: 2px;

      /* 光标 */
      --cursor-interactive: pointer;
      --cursor-disabled: not-allowed;

      /* 圆角 */
      --radius: 0.5rem;
      --field-radius: calc(var(--radius) * 1.5);

      /* == 浅色主题变量 == */

      /* 基础颜色 */
      --background: oklch(0.9702 0 0);
      --foreground: var(--eclipse);

      /* 表面：用于非浮层组件（卡片、手风琴、折叠组等） */
      --surface: var(--white);
      --surface-foreground: var(--foreground);

      /* 遮罩层：用于悬浮/浮层组件（工具提示、气泡、模态框、菜单） */
      --overlay: var(--white);
      --overlay-foreground: var(--foreground);

      --muted: oklch(0.5517 0.0138 285.94);
      --scrollbar: oklch(87.1% 0.006 286.286);

      --default: oklch(94% 0.001 286.375);
      --default-foreground: var(--eclipse);

      --accent: oklch(0.6204 0.195 253.83);
      --accent-foreground: var(--snow);

      /* 表单字段默认值 - 颜色 */
      --field-background: var(--white);
      --field-foreground: oklch(0.2103 0.0059 285.89);
      --field-placeholder: var(--muted);
      --field-border: transparent; /* 表单字段默认无边框 */

      /* 状态色 */
      --success: oklch(0.7329 0.1935 150.81);
      --success-foreground: var(--eclipse);

      --warning: oklch(0.7819 0.1585 72.33);
      --warning-foreground: var(--eclipse);

      --danger: oklch(0.6532 0.2328 25.74);
      --danger-foreground: var(--snow);

      /* 组件颜色 */
      --segment: var(--white);
      --segment-foreground: var(--eclipse);

      /* 杂项颜色 */
      --border: oklch(92% 0.004 286.32);
      --separator: oklch(92% 0.004 286.32);
      --focus: var(--accent);
      --link: var(--foreground);

      /* 背衬 */
      --backdrop: rgba(0, 0, 0, 0.5);

      /* 阴影 */
      --surface-shadow:
        0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
        0 0 1px 0 rgba(0, 0, 0, 0.06);
      /* 遮罩层阴影 */
      --overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
      --field-shadow:
        0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
        0 0 1px 0 rgba(0, 0, 0, 0.06);
      /* 骨架屏全局默认动画 */
      --skeleton-animation: shimmer; /* shimmer, pulse, none */

      /* Tooltip 默认延迟 */
      --tooltip-delay: 1500ms;
      --tooltip-close-delay: 500ms;
    }

    .dark,
    [data-theme="dark"] {
      color-scheme: dark;
      /* == 深色主题变量 == */

      /* 基础颜色 */
      --background: oklch(12% 0.005 285.823);
      --foreground: var(--snow);

      /* 表面：用于非浮层组件（卡片、手风琴、折叠组等） */
      --surface: oklch(0.2103 0.0059 285.89);
      --surface-foreground: var(--foreground);

      /* 遮罩层：用于悬浮/浮层组件（工具提示、气泡、模态框、菜单）——略浅于表面以提高对比度 */
      --overlay: oklch(0.22 0.0059 285.89); /* 比表面色略浅，便于在深色模式下辨识 */
      --overlay-foreground: var(--foreground);

      --muted: oklch(70.5% 0.015 286.067);
      --scrollbar: oklch(70.5% 0.015 286.067);

      --default: oklch(27.4% 0.006 286.033);
      --default-foreground: var(--snow);

      /* 表单字段默认值 - 颜色（仅列出与浅色主题不同的项） */
      --field-background: var(--default);
      --field-foreground: var(--foreground);

      /* 状态色 */
      --warning: oklch(0.8203 0.1388 76.34);
      --warning-foreground: var(--eclipse);

      --danger: oklch(0.594 0.1967 24.63);
      --danger-foreground: var(--snow);

      /* 组件颜色 */
      --segment: oklch(0.3964 0.01 285.93);
      --segment-foreground: var(--foreground);

      /* 杂项颜色 */
      --border: oklch(22% 0.006 286.033);
      --separator: oklch(22% 0.006 286.033);
      --focus: var(--accent);
      --link: var(--foreground);

      /* 背衬 */
      --backdrop: rgba(0, 0, 0, 0.6);

      /* 阴影 */
      --surface-shadow: 0 0 0 0 transparent inset; /* 深色模式下无阴影 */
      --overlay-shadow: 0 0 0 0 transparent inset; /* 深色模式下无阴影 */
      --field-shadow: 0 0 0 0 transparent inset; /* 透明阴影，以便环形工具类生效 */
    }
  }
`}
/>

## 自定义颜色

**覆盖已有颜色：**

```css
:root {
  /* 覆盖默认颜色 */
  --accent: oklch(0.7 0.15 250);
  --success: oklch(0.65 0.15 155);
}

[data-theme="dark"] {
  /* 覆盖深色主题颜色 */
  --accent: oklch(0.8 0.12 250);
  --success: oklch(0.75 0.12 155);
}
```

**提示：** 可在 [oklch.com](https://oklch.com) 转换颜色。

**添加自定义颜色：**

```css
:root,
[data-theme="light"] {
  --info: oklch(0.6 0.15 210);
  --info-foreground: oklch(0.98 0 0);
}

.dark,
[data-theme="dark"] {
  --info: oklch(0.7 0.12 210);
  --info-foreground: oklch(0.15 0 0);
}

/* 将颜色暴露给 Tailwind */
@theme inline {
  --color-info: var(--info);
  --color-info-foreground: var(--info-foreground);
}
```

随后即可使用：

```tsx
<div className="bg-info text-info-foreground">提示信息</div>
```

> **注意：** 若要进一步了解主题变量及其在 Tailwind CSS v4 中的行为，请参阅 [Tailwind CSS 主题文档](https://tailwindcss.com/docs/theme)。
