color-system

色彩系统

为此代码库生成经过对比度验证的色彩令牌文件——包括色阶、语义层和深色模式，并展示计算过程，而非讲解色彩理论。核心原则：色彩是一套系统，而不是一份列表：每种色相都配有完整的明度色阶，组件只使用语义令牌，任何文本与背景组合在发布前都必须计算对比度。

适用场景 / 交接

• 适用于调色板、色阶、深色模式、对比度修复、状态色与交互色、主题。
• 尚无令牌基础设施 → 先运行 skills/frontend-design/design-foundation，或将色彩部分作为其起点。
• “所有东西都灰蒙蒙、平平的／分不清重点”通常是层级问题，而非调色板问题 → skills/frontend-design/visual-hierarchy-refactoring。
• 要进行全面的 WCAG 审计（不只限于色彩） → skills/frontend-design/accessibility-excellence。

步骤 1 — 检查代码库

1. 收集调色板。 在源码和配置中搜索 #[0-9a-fA-F]{3,8}\b、rgba?\(、hsla?\(、oklch\(。去重并统计出现频次。将近似值（ΔL < ~5）归为一组——每组都对应一种发生偏移的预期色彩。
2. 查看现有令牌。 检查 Tailwind theme.colors、@theme 变量和 CSS 自定义属性。判断是否已有色阶，还是只有单个十六进制值。
3. 找出实际使用的品牌色——使用频率最高的饱和色相。
4. 检查深色模式状态：dark: 类、prefers-color-scheme、.dark 代码块。
5. 抽查对比度：找出代码中最常见的 3–5 组文本／背景组合，计算 WCAG 比率；未达标的组合应直接写入说明理由。

步骤 2 — 收集需求

一次性询问尚未明确的信息：要保留的品牌色，还是选择新颜色（若选择新颜色，还需了解其风格：可信、活力、高级或友好），以及深色模式：现在做、以后做还是不做。其余内容自行推断。**不要停滞不前：**若已有明确的实际品牌色，就保留它，说明这一假设并继续。

步骤 3 — 构建系统

1. 品牌色阶。 将品牌色扩展为 11 级明度色阶（50–950），尽量保持色相不变，并在两端降低色度。对于大多数色相，可用于白色文本的基础色通常位于 600 级。
2. 中性色阶——带色调，绝不使用纯灰。 大幅降低品牌色相的饱和度（约 5–15%），并据此构建 gray-50…950。禁止使用 #808080 和纯 #000；与任何品牌色并列时，它们都会显得格格不入。
3. 强调色／辅助色（仅在产品需要时）。 按色彩协调规则选择：注重统一／平静的产品使用类似色（±30–60°）；高能量 CTA 的强调色少量使用互补色（约 180°）；UI 需要为 ≥3 个类别编码时使用三角色。不要添加没有用途的色相。
4. 状态色。 成功色 ≈ 绿色，警告色 ≈ 琥珀色，错误色 ≈ 红色，信息色 ≈ 青色／蓝色——根据品牌色的冷暖进行微调。每种状态色至少配有 100／600／700 三级迷你色阶（背景浅色、基础色、浅色背景上的文本色）。
5. 语义层。 bg-primary/secondary/tertiary、text-primary/secondary/tertiary/disabled/inverse、border-primary/focus、interactive-primary/hover/active/disabled——映射到色阶。组件不得直接使用色阶值。
6. 深色模式（若纳入范围）。 只重新映射语义令牌：背景使用 gray-900/950（绝不使用 #000），文本使用 gray-50/300，品牌色调亮一级（浅色模式的 600 → 深色模式的 500）；若色彩产生振颤感，则略微降低饱和度。重新验证每组对比度——浅色模式的比率不能直接套用。
7. 验证所有发布组合的对比度。 计算 WCAG 相对亮度比率：普通文本 ≥4.5:1，大文本（≥24px，或粗体 ≥18.7px）及 UI 组件／焦点环 ≥3:1。这是通过与否的判定标准。如果某个组合虽符合 WCAG，但视觉效果偏弱（在饱和中间色上使用浅色文本），则将 APCA（正文 Lc ≈ 60+）作为参考性决胜依据，并将颜色加深一级。
8. 确保色盲用户也能区分。 状态色不能成为唯一信号——应搭配图标／标签（仅靠红／绿区分会让约 8% 的男性用户无法辨认）。避免仅用红色和绿色区分类别；蓝／橙是最安全的对比色组合。

规范形态（CSS 变量；根据检测到的技术栈调整）

:root {
  --brand-600: #2563EB;  --brand-700: #1D4ED8;   /* full 50–950 ramp in the real file */
  --gray-600: #475569;   --gray-900: #0F172A;    /* brand-tinted neutrals, full ramp */
  --red-600: #DC2626;    --red-100: #FEE2E2;     /* status mini-ramps: green/amber/red/cyan */

  --color-bg-primary: #FFFFFF;
  --color-text-primary: var(--gray-900);      /* on bg-primary: 17.8:1 ✓ */
  --color-text-secondary: var(--gray-600);    /* on bg-primary: 7.6:1 ✓ */
  --color-interactive-primary: var(--brand-600); /* white on it: 5.2:1 ✓ */
}
.dark {
  --color-bg-primary: var(--gray-950);
  --color-text-primary: var(--gray-50);
  --color-interactive-primary: var(--brand-500);
}

Harmony 理论、色彩心理学、色阶构建技巧和色盲友好型调色板：references/color-theory.md。

第 4 步 — 接入并迁移

将令牌写入检测到的入口点（扩展现有内容，而非另起分支）。在 1–3 个高流量文件中迁移第 1 步中发现的主要偏差集群；为其余部分建立映射。

必需的输出格式

交付代码以及以下摘要：

## Color tokens
[file path + full code]

## Palette decisions
- Brand: [hex] — [kept from code / chosen for [personality]]
- Neutrals: tinted toward [hue]
- Harmony: [mono/analogous/complementary/triadic] because [job it does]
- Dark mode: [shipped/deferred] — strategy: [.dark class / media query]

## Contrast verification
| Pair | Ratio | Standard | Pass |
| text-primary on bg-primary (light) | 17.8:1 | 4.5:1 | ✓ |
| white on interactive-primary | 5.2:1 | 4.5:1 | ✓ |
| text-secondary on bg-primary (dark) | ... | ... | ... |
[every shipped text and UI pairing, both modes]

## Migration map
| Found (cluster) | Count | Replace with |
| #3B82F6 / #3b82f7 / #3a80f0 | 23 | var(--color-interactive-primary) |
| ... |

## Migrated now
[files edited]

质量标准（交付前检查）

• 已交付的每组文本/背景配对都在表格中列出计算后的对比度；两种模式下均达到 ≥4.5:1（普通文本）/ ≥3:1（大号文本和 UI）
• 中性色带有品牌色调；没有 #808080，没有纯 #000 背景
• 每种色相都构成一个色阶，而非单独的十六进制值；每种色相都有明确用途
• 组件/示例仅引用语义令牌
• 状态含义绝不只通过颜色传达（须搭配图标/标签）
• 深色模式：背景为深灰色，品牌色调亮一档，所有配对均已重新验证
• 焦点指示器颜色与相邻颜色的对比度 ≥3:1
• 迁移映射涵盖第 1 步中发现的所有偏差集群

集成

• 输入：来自 skills/frontend-design/design-foundation 的令牌骨架；用于大号文本对比度阈值的文本尺寸来自 skills/frontend-design/typography-system。
• 输出：供 skills/frontend-design/visual-hierarchy-refactoring（基于亮度的对比度层级）、skills/frontend-design/component-architecture（组件颜色绑定）使用的颜色令牌，并由 skills/frontend-design/accessibility-excellence 审核。

参考资料

• references/color-theory.md — 和谐配色技巧及示例、按色相划分的色彩心理学、手动构建色阶的方法、色盲友好型调色板，以及对深色模式陷阱的深入讲解。从零开始选择调色板或排查色阶显示异常时请阅读。