颜色 Colors

用法

请始终使用语义令牌，而不是原始的 Tailwind 颜色。这能确保你的 UI 自动适配浅色与深色模式，并让组件在各主题间保持一致。

正确

<div className="bg-kumo-base text-kumo-default border-kumo-hairline">
  <button className="bg-kumo-brand text-white">Primary</button>
  <button className="bg-kumo-control text-kumo-default">Secondary</button>
</div>

错误

{
  /* 切勿使用原始的 Tailwind 颜色 */
}
<div className="bg-white dark:bg-gray-900 text-black dark:text-white">
  <button className="bg-blue-500">Primary</button>
</div>;

Lint 规则会强制这一点：no-primitive-colors 规则会标记任何类似 bg-blue-500 的原始 Tailwind 颜色。

模式

在父元素上设置 data-mode 来控制浅色/深色模式。切勿使用 Tailwind 的 dark: 变体——语义令牌会通过 CSS light-dark() 自动处理深色模式。

// 在 html 或 body 上设置模式
<html data-mode="light">  // 浅色模式
<html data-mode="dark">   // 深色模式

// 组件会自动适配 —— 无需 dark: 变体
<div className="bg-kumo-base text-kumo-default" />

主题

主题会覆盖语义令牌的值，同时保留相同的令牌名称。在父元素上设置 data-theme 即可应用主题。

可用主题

• kumo — 默认主题 (无需任何属性)
• fedramp — 政府合规样式

// 将主题应用到某个区块或整个应用
<div data-theme="fedramp">
  {/* 内部所有 Kumo 组件都使用 fedramp 令牌覆盖 */}
  <Button>FedRAMP Styled</Button>
</div>

// 主题同时适用于浅色和深色模式
<html data-mode="dark" data-theme="fedramp">

主题生成器

主题在集中式配置中定义，并生成为 CSS 文件。主题生成器确保所有主题之间的一致性。

# 列出所有令牌及其主题覆盖

pnpm --filter @cloudflare/kumo codegen:themes --list

# 生成主题 CSS 文件

pnpm --filter @cloudflare/kumo codegen:themes

# 预览更改但不写入文件

pnpm --filter @cloudflare/kumo codegen:themes --dry-run

主题配置：packages/kumo/scripts/theme-generator/config.ts

创建新主题

在配置文件中添加主题覆盖。只需覆盖需要更改的令牌——其余所有令牌都会从基础 kumo 主题继承。

// 在 scripts/theme-generator/config.ts 中
export const THEME_CONFIG: ThemeConfig = {
  color: {
    "kumo-base": {
      newName: "",
      theme: {
        kumo: {
          light: "var(--color-white, #fff)",
          dark: "var(--color-black, #000)",
        },
        // 添加你自己的主题覆盖
        myTheme: {
          light: "#f0f4f8",
          dark: "#1a1f2e",
        },
      },
    },
    // ... 其他令牌
  },
};

// 添加到可用主题列表
export const AVAILABLE_THEMES = ["kumo", "fedramp", "myTheme"] as const;

然后运行 pnpm codegen:themes 生成 CSS。

语义令牌

我们使用语义令牌按用途对颜色分组。请选择与元素角色相匹配的令牌，而不是你想要呈现的颜色。

语义令牌按角色命名，而非色相。像 bg-kumo-danger 这样的令牌传达的是意图——它并不暗示某种特定的红色深浅，其具体值可以随主题或颜色模式变化，而无需改动你的组件代码。

表面层级

表面用于在 UI 中建立深度与层次。请从最外层背景向内按顺序使用它们。

品牌色

语义状态色

每种状态色都有两种变体：一种是用于图标和指示器的实色，另一种是 -tint 变体，用于内容背后的背景填充 (即 Badge 或 Banner)。

状态点使用实色令牌 bg-kumo-*,图标使用 fill-kumo-*,边框和轮廓使用 border-kumo-*、ring-kumo-*。Banner 和 Badge 使用 -tint 变体，并配合不同的透明度值。

import { WarningIcon } from "@phosphor-icons/react";

export function StatusBannerDemo() {
  return (
    <div className="flex items-center gap-2 rounded-lg bg-kumo-danger-tint/70 p-4">
      <WarningIcon weight="fill" className="fill-kumo-danger" />
      <span className="text-sm text-kumo-danger">Something went wrong.</span>
    </div>
  );
}

文本颜色

语义文本色 (即 text-kumo-success) 默认更深，以便在 tint-* 背景上获得更好的对比度和可读性。

边框与轮廓

令牌参考

在页头切换主题，即可查看令牌如何适配。标记为「全局」的令牌是显式选择加入的类，不依赖主题始终可用。