# 颜色 · HeroUI

> HeroUI v3 的调色板与主题系统

- 页面: https://jiguang132.com/zh/systems/heroui/docs/getting-started/colors
- 改编自: HeroUI 文档 (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af

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

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

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


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


## 强调色

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

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


## 默认（中性色）

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


## 成功

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


## 警告

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


## 危险

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


## 前景色

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


## 背景色

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


## 表面色

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


## 表单字段

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


## 分隔线

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


## 其他

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


## 基础色

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


## 如何使用颜色

**在组件中：**
```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"` 属性在明暗模式间自动切换。


## 自定义颜色

**覆盖已有颜色：**

```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)。

---

JGuang 全部资源索引: https://jiguang132.com/llms.txt