颜色

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

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

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

强调色

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

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

默认（中性色）

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

成功

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

警告

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

危险

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

前景色

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

背景色

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

表面色

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

表单字段

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

分隔线

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

其他

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

基础色

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

如何使用颜色

在组件中：

<div className="bg-background text-foreground">
  <button className="bg-accent text-accent-foreground hover:bg-accent-hover">
    点击我
  </button>
</div>

在 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。该主题会根据 class="dark" 或 data-theme="dark" 属性在明暗模式间自动切换。

@layer base {
  /* HeroUI 默认主题 */
  :root {
    color-scheme: light;

自定义颜色

覆盖已有颜色：

: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 转换颜色。

添加自定义颜色：

: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);
}

随后即可使用：

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

注意： 若要进一步了解主题变量及其在 Tailwind CSS v4 中的行为，请参阅 Tailwind CSS 主题文档。