Impeccable colorize 命令全解：为灰度 UI 引入策略化色彩的设计方法论

在 Impeccable 这个面向 AI 设计 harness 的技能仓库中，colorize 是 Enhance 类别下的专用命令，负责把“灰、闷、缺乏温度”的单色界面升级为有层级、有意义、有氛围的配色系统。本文基于 reference/colorize.md 的完整方法论展开，并结合 SKILL.md、live.md 和 DESIGN.md 中的真实 token 体系，讲清楚一次 colorize [target] 调用从审计到验收的完整工作流，以及它在 Live 实时变体模式下的参数契约。

colorize 在命令体系中的定位

在 SKILL.md 的 Commands 表中，colorize 的定义是：

命令	类别	描述	参考文档
colorize [target]	Enhance	Add strategic color to monochromatic UIs	reference/colorize.md

command-metadata.json 进一步给出了它的触发语义和参数提示：

"colorize": {
  "description": "Add strategic color to features that are too monochromatic or lack visual interest, making interfaces more engaging and expressive. Use when the user mentions the design looking gray, dull, lacking warmth, needing more color, or wanting a more vibrant or expressive palette.",
  "argumentHint": "[target]"
}

这决定了 colorize 的适用边界：它针对的是已有界面中色彩策略缺失的场景（灰、平、缺层次），而不是从零开始的新表面——后者由 new-work.md 负责。colorize 文档开头也声明了它的前置上下文需求：“Additional context needed: existing brand colors”，并给出一条总原则：把色彩作为层级（hierarchy）、意义（meaning）和氛围（atmosphere）来引入；保留已确认的品牌约定和语义约定，绝不能在“着色”的名义下替换掉整个视觉世界。

第 1 步：选择色彩之前的审计

colorize 方法论的第一步不是选颜色，而是审计。文档要求先读 DESIGN.md、token、资产、当前主题和代表性状态，识别出：

• 哪些颜色是已确认的品牌承诺（confirmed brand commitments）；
• 当前 surface、text、action 和 semantic 各自的角色分配；
• 哪些地方灰度掩盖了层级或状态；
• 对比度失败点与仅靠颜色传达信息的位置；
• 是否存在 light/dark 双主题或数据可视化的要求；
• 任务本身是要求“更多色彩”，还是其实是一次新的身份（new identity）。

最后一条是路由判断：如果需要的是新身份，应切换到 new-work.md 而不是继续 colorize；只有在绑定性的品牌决策无法从现有材料推断时，才向用户提问。

第 2 步：按 Visitor Mode 决定色彩剂量

Impeccable 用“访客在这个界面上的成功是什么”来划分四种模式，colorize 文档将其归为两档不同的色彩职责：

• Persuade + Experience（营销页、作品集类）：当所选的视觉世界（world）需要时，色彩可以承载“声音”，并独占大区域。
• Operate + Read（工具 UI、文档类）：色彩主要编码动作、选中、状态、导航和阅读层级；因为稀缺，强调色才有力。

这一档位的意义在于：同一个 colorize 命令，落在落地页上可能是一次大面积的氛围着色，落在后台工具上则只应是一次克制的语义着色。

第 3 步：选择策略——建立色彩角色，而不是一堆色板

文档要求在动手编辑前，先书面化四个决策：预期情绪温度（emotional temperature）、主导关系（dominant relationship）、对比范围（contrast range）、色彩剂量（dosage）。策略可以是克制的，也可以是沉浸式的，但必须跟随 brief 和所选的视觉世界，而不是套用某种固定的百分比规则。

紧接着是核心方法——构建角色（roles），而不是一袋色板（a bag of swatches）：

• 画布与抬升的表面（canvas and elevated surfaces）；
• 主文本与次级文本（primary and secondary text）；
• 动作、焦点与选中（action, focus, and selection）；
• 边框与分隔线（borders and separators）；
• 成功、警告、错误、信息（success, warning, error, information）；
• 需要时的数据分类或色阶（data categories or scales）。

关于色彩空间的指导同样明确：沿用项目现有的色彩空间；对于全新的 Web 调色板，优先选择 OKLCH，因为其亮度（lightness）与彩度（chroma）可以可预测地调节。色相（hue）必须从产品含义和视觉方向中选取，绝不能从默认类目联想里挑（例如“金融所以用蓝色”这种惯性）。

仓库自身的 DESIGN.md 就是这条指导的实践样本：它的 token 全部使用 OKLCH 并成组命名——品牌锚点（如 kinpaku-gold: "oklch(84% 0.19 80.46)" 标注为 primary accent）、表面层（lacquer-black、raised-lacquer）、文本层（text-muted、text-faint）以及成组的 gold ramp（kinpaku-pale → kinpaku-rich → kinpaku-deep），每个 token 都带注释说明其角色。这正是“角色化色彩系统”而非“色板堆”的形态。

第 4 步：以系统尺度应用色彩

文档给出的八条系统级应用规则，是 colorize 最容易出效果的环节：

1. 让最强的色彩占有一个刻意的区域或角色，而不是把小强调色撒得到处都是；
2. 主操作必须容易被找到，不要把它专属的颜色花在装饰上；
3. 只有当品牌色相确实能带来凝聚力时才给中性色染色；如果服务于当前世界，中性灰本身是合法的；
4. 在彩色表面上，次级文本应从前景色或表面色相派生，而不是用漂白的通用灰；
5. 语义含义保持一致，但尊重平台与领域惯例，不要假设固定的色相（并非所有领域里错误都是红色）；
6. 数据可视化中，用不同的亮度、彩度、形状、标签或纹理编码，使颜色不是唯一的编码通道；
7. 深色模式下要显式设计表面抬升和对比，不要机械地反色浅色主题；
8. 项目有 token 体系时，定义原语值（primitive values）与语义 token（semantic tokens），主题切换通常只应重映射语义角色。

文档以一句硬约束收尾：与层级、状态、内容或视觉世界没有关系的装饰，不是色彩策略。

第 5 步：对比度与感知边界

色彩引入后的验收底线是计算出来的前景/背景对，而不是“看起来还行”。文档给出的 WCAG AA 最小值：

内容	WCAG AA 最低对比度
正文（body text）	4.5:1
大文本（large text）	3:1
控件、图标、焦点指示器	3:1

不能只靠肉眼：要逐一检查交互状态、遮罩层、图片上的文字、禁用态内容，以及两个主题下的表现；还应模拟常见色觉缺陷。任何由颜色传达的信息，都必须同时有文字、形状、图标或位置作为冗余通道。

针对 OKLCH 色阶的推导技巧，文档特别指出：派生色阶时随亮度变化调节光度，并在接近白色和黑色时降低彩度——不要为了“数学上均匀”而在极高/极低亮度处保留高彩度（那会产生刺眼的霓虹效果）。另外，当 alpha 会让对比度依赖上下文时，优先使用显式颜色而不是半透明叠层。

这些约束在仓库其他文档中是一致交叉引用的。例如 craft-floor.md（编辑 UI 前必须加载的质量底线）中有与 colorize 对应的规则：

• Contrast: 正文与占位符文本 ≥4.5:1，大文本 ≥3:1；在彩色表面上，次级文本要从该色相或前景派生，绝不用灰；
• Depth: 零偏移的彩色光晕是装饰而非深度，阴影必须带偏移和柔化模糊。

这意味着 colorize 产出的 CSS 不是孤立通过验收的，它还会被 craft-floor 的自动检测规则复核。

验收清单：色彩配得值不值

colorize 文档最后给出一份可勾选的验收标准，任何一条不成立都不算完成：

• 每个颜色都有稳定的角色，或有明确的世界氛围用途；
• 注意力落在预期的动作、内容或状态上；
• 调色板在安静、密集、交互中、错误、空状态五种状态下都成立；
• 明暗两个主题都是各自构图过的，而不是机械反转；
• 对比度与非色彩线索在所有相关状态下都通过；
• 结果是“可辨认地属于这个产品”，而不是一种通用的“彩色化处理”。

全部通过后，文档指示交接给 /impeccable polish（见 polish.md）做最终打磨——colorize 负责建立色彩策略，polish 负责收口细节。

Live 模式下的签名参数：color-amount

colorize 有一个独特的“签名参数”（signature params）约定：当它从 Live 实时变体模式 被调用时，每个变体都必须声明一个 color-amount 参数：

{"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"}

配套要求是：CSS 必须写成针对 var(--p-color-amount, 0.5) 的形式，这样用户在浏览器里拖动滑杆就能从“中性”平滑过渡到“该变体的完整色彩策略”，而不需要重新生成变体。此外还可声明至多两个变体专属参数（如调色板、温度、染色行为），并遵循 live.md 的参数契约。

对照 live.md 的参数契约，这条约定的完整含义是：

• 参数是粗粒度的调节轴：range 类型驱动 --p-<id> CSS 变量，声明字段为 min/max/step/default/label；变体在 HTML 包裹元素上以 data-impeccable-params 属性声明；
• 每个变体参数硬上限为 4 个（color-amount 必占其一，故变体专属参数最多两个，正好与 colorize 文档的“至多两个”吻合）；live.md 明确写着：命名子命令的 MUST 参数在可表达时不可协商；
• 用户接受（accept）变体后，浏览器把当前参数值回传，live-accept 会写成注释 <!-- impeccable-param-values SESSION_ID: {"color-amount":0.7} -->；随后的 carbonize 清理阶段把 var(--p-color-amount) 烘焙为字面量或更新变量默认值，只保留匹配的样式分支，最终源码里不再残留预览机制的痕迹。

从这套机制可以看到 colorize 在 Live 模式中的完整闭环：生成时以 color-amount 为 0 到 1 的连续轴着色，用户实时调参选定剂量，接受后按选定值固化为静态 CSS——策略化的“色彩剂量”最终落地为可审计的确定性代码。

小结：一次标准 colorize 工作流

综合文档全文，一次完整的 colorize [target] 执行可以归纳为：

1. 审计：读 DESIGN.md、token、主题与代表性状态，区分品牌承诺、现有角色、灰度盲区、对比失败与色觉单一通道；判断任务是否实为 new-work；
2. 定模式：按 Persuade/Experience 与 Operate/Read 确定色彩是承担氛围还是编码状态；
3. 定策略：写出情绪温度、主导关系、对比范围、剂量；建立 canvas/文本/动作/边框/语义/数据六类角色；沿用既有色彩空间或新选 OKLCH；
4. 系统级应用：最强色占区域、主操作保色、彩色表面派生次级文本、深色模式显式设计、token 分层；
5. 对比验收：4.5:1 / 3:1 计算验证 + 交互态/双主题/色觉缺陷/非色彩冗余通道；
6. 验收清单：六项全过后交接 /impeccable polish；若处于 Live 模式，则额外满足 color-amount 签名参数契约并在 accept 后烘焙参数值。

colorize 文档的价值不在于给出一张色板，而是把“给界面加颜色”这件事约束成了有审计、有策略、有角色、有对比度证明、有验收标准、可交接的流程——这正是 Impeccable 让 AI harness 稳定产出可辨认于产品本身的色彩设计的核心手段。