impeccable colorize 指南：用角色化色彩系统为单色界面引入分层、语义与氛围

impeccable 是一个让 AI harness（编码代理框架）更擅长前端设计的开源设计语言仓库，其中的 colorize 子命令负责为偏灰、缺乏视觉层次的界面引入有策略的色彩。本文基于 reference/colorize.md 完整展开 colorize 的设计决策流程：先审计品牌承诺，再制定色彩策略，按系统级角色落地，最后用 WCAG 对比度与可访问性校验收尾；读完你可以掌握一套从「选色依据」到「token 落地」「Live 模式参数化（--p-color-amount 滑杆）」的可执行方法，并理解其背后 impeccable 技能包与运行时脚本的支撑机制。

colorize 在 impeccable 中的定位

impeccable 以技能包（skill）形式分发给 Claude Code、Codex、Cursor 等多种 harness，每个子命令对应一份 reference 文档，colorize 的入口是 reference/colorize.md（分发到各 harness 时位于 .agents/、.claude/、.cursor/ 等目录；构建态源文件在 skill/reference/colorize.md）。在主技能文件 SKILL.md 的命令表中它被登记为：

命令	分类	作用	参考文档
colorize [target]	Enhance	为单色 UI 增加有策略的色彩	reference/colorize.md

从 scripts/lib/skill-categories.js 的源码结构看，colorize 被归入 refine（改善现有设计）类别，与 typeset、layout、animate、bolder、quieter 等同组；而 skill/scripts/command-metadata.json 给出了面向意图匹配的官方描述：

"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."

也就是说，触发词是「灰、乏味、缺温度、需要更多色彩、想要更生动的调色板」。命令支持可选的 target 参数（command-metadata.json 中 argumentHint 为 [target]），把色彩改造限定到指定功能、页面或组件，而不必全仓库铺色。另外，当 harness 处于 Live 浏览器迭代模式时，colorize 也是浏览器侧可用的视觉动作之一——skill/scripts/live/vocabulary.mjs 把它列为 LIVE_COMMANDS 的一员，用户可以在浏览器覆盖层中直接选择「Colorize」，Agent 随即按本文的决策流程在页面内生成多个带参数的色彩变体。

前置条件与核心理念

文档开篇给出了两条硬前提：

1. Additional context needed: existing brand colors —— 动手前必须知道既有品牌色。
2. 色彩引入的目的是建立层次（hierarchy）、承载含义（meaning）、营造氛围（atmosphere）；必须保留已确认的品牌与语义约定，"不得以 colorize 为名替换掉整个视觉世界"。

这两句话框定了 colorize 与 new-work 的边界：colorize 是在现有设计世界里做色彩手术，而整体身份重塑属于另一条流程。文档明确：如果任务实际要求的是新身份（new identity），应改走 reference/new-work.md；只有当某个具有约束力的品牌决策无法从现有材料推断出来时，才向用户提问。

访客模式：Persuade 与 Operate 两种色彩职责

文档按 impeccable 的访客模式（Visitor mode）划分色彩的职责侧重：

• Persuade + Experience（说服/体验类场景，如营销页）：当所选视觉世界（world）要求时，色彩可以承载「声音」并独占大面积区域——大面积色块、沉浸式底色都是合法手段。
• Operate + Read（操作/阅读类场景，如仪表盘、文档）：色彩主要用于编码操作、选中态、状态、导航指引与阅读层次。此时强调"稀缺赋予强调色力量"（Rarity gives an accent force）——强调色越稀缺，每次出现越有力。

这一节是后续所有决策的判据：先判定目标界面属于哪种模式，再决定色彩剂量（dosage）是克制还是沉浸。

选色前审计：六项检查清单

colorize 要求先审计、后选色。文档要求通读 DESIGN.md、设计 token、既有资产、当前主题与代表性状态，并识别出以下六类事实：

• 哪些颜色是已确认的品牌承诺（confirmed brand commitments），不可擅动；
• 当前各颜色的角色分工：surface（表面）、text（文本）、action（操作）、semantic（语义色）分别是谁；
• 哪些地方灰度掩盖了层次或状态——这是 colorize 要修复的核心病灶；
• 对比度失败与仅靠颜色传达信息（color-only communication）的位置；
• 是否存在明暗主题或数据可视化需求；
• 任务到底是要"更多色彩"，还是要求一套新身份（后者转 new-work）。

这份审计清单把选色从审美判断变成了事实核对：每一项都有仓库内可验证的对象（DESIGN.md、token 文件、主题状态），避免凭印象调色。impeccable 仓库自身就有 DESIGN.md 作为范本，说明设计决策被固化为文件、供 Agent 在每次任务中读取。

制定色彩策略：先命名，后动手

文档要求在下任何一行样式之前，先明确说出四个维度：

1. 目标情绪温度（emotional temperature）；
2. 主从关系（dominant relationship，谁是主导色、谁陪衬）；
3. 对比范围（contrast range）；
4. 色彩剂量（color dosage）。

策略可以是克制的也可以是沉浸式的，但"必须跟随 brief 与所选视觉世界，而不是套固定百分比规则"。随后是本文最核心的产出形式——构建角色，而不是一袋色板（Build roles, not a bag of swatches）。一个完整的色彩系统应覆盖这些角色：

• canvas（画布/背景）与 elevated surfaces（浮层表面）；
• 主文本与次文本（primary / secondary text）;
• 操作、聚焦、选中（action / focus / selection）；
• 边框与分隔线（borders and separators）；
• 成功、警告、错误、信息（success / warning / error / information）；
• 数据类别或数据色阶（如界面含图表）。

关于色彩空间，文档的推荐是：沿用项目既有色彩空间；如果是全新 Web 调色板，优先使用 OKLCH，因为其明度（lightness）与彩度（chroma）可以被可预测地调节——这对后续推导深浅色阶、明暗两套主题尤其重要。色相（hue）则应从产品含义与视觉方向出发选取，"绝不能从默认类别联想出发"（例如"金融就该是蓝色"这类捷径）。

系统级应用：八条落地规则

策略选定后，文档给出系统尺度（system scale）上的八条落地规则，每一条都针对一类常见的调色翻车方式：

1. 让最强色拥有刻意划定的区域或角色，而不是撒一地小面积强调色；
2. 保持主操作易被找到，不把它专属的色彩花在装饰上；
3. 中性色只有当品牌色相确实带来凝聚力时才染色；为视觉世界服务的纯中性灰是合法的；
4. 在有色表面上，次级文本应从前景色或表面色相推导，而不是套一个洗白过的通用灰；
5. 语义含义保持一致，但尊重平台与领域惯例，不假定固定色相（不同平台的"错误色"未必都是纯红）；
6. 数据可视化中，用不同的明度、彩度、形状、标签或纹理共同编码，让颜色不是唯一的通道；
7. 深色模式下显式设计表面层级与对比，不要机械反色（mechanically invert）浅色主题；
8. 项目有 token 体系时，同时定义 primitive 值与 semantic token，主题切换通常只应重映射语义角色，而不是到处改具体色值。

文档最后用一句话划清底线："与层次、状态、内容或视觉世界没有关系（a relationship to hierarchy, state, content, or the visual world）的装饰，不是色彩策略。"

对比度与感知：可量化、可复核的验收标准

colorize 不接受"看着差不多"，它要求对计算后的前景/背景配对逐项验证。文档给出的 WCAG AA 下限表：

内容	WCAG AA 最低对比度
正文（body text）	4.5:1
大字号文本（large text）	3:1
控件、图标、聚焦指示器（controls, icons, focus indicators）	3:1

并且强调不能只靠肉眼：要检查交互状态、浮层（overlay）、图上的文字、禁用态内容，以及明暗两套主题；要模拟常见色觉缺陷；所有由颜色传达的信息还必须同时具备文字、形状、图标或位置上的冗余通道。

在 OKLCH 推导色阶（ramps）时，文档给出两条工艺细节：

• 靠近白与黑的极端明度处，要降低彩度，不要为了"数学上均匀"而在极端明度上保留高彩度（极端明度+高彩度会产生刺眼的灰紫/灰绿脏色）；
• 当 alpha 会让对比度依赖上下文时，优先使用显式颜色而非透明叠层链。

这两条规则保证了色阶在任何背景上的对比度都是可静态计算的——这也正好对接 impeccable 的自动化检测能力：仓库内置了针对色彩与对比度的反模式检测器（如 tests/fixtures/oklch-neon-text.html、tests/fixtures/cream-palette.html、tests/fixtures/dark-theme-modern-color.html 等测试夹具），detect.mjs 会把"灰调/低饱和调色板"这类信号输出给上层命令路由——reference/routing.md 明确写着：flat or gray palette → colorize。也就是说，即便用户没点名 colorize，检测器发现的"色彩缺失"信号也会把它推荐为下一步命令。

验证清单：colorize 的六项交付判据

文档的 Verify 一节定义了收尾前的自验清单，六条全部满足才算完成：

• 每一种颜色都有稳定的角色或世界专属的氛围目的；
• 注意力落在预期的操作、内容或状态上；
• 调色板在安静、密集、交互、错误、空态五类页面状态下都成立；
• 明暗主题各自是完整的设计，而不是机械反色；
• 对比度与非颜色冗余通道在所有相关状态下通过；
• 结果可被认作这个产品，而不是一个通用的"彩色化"处理。

全部通过后，文档建议移交给 $impeccable polish 做最后打磨——这在 SKILL.md 的命令体系里是标准流转：colorize 完成"有没有色、颜色对不对"，polish 负责细节收尾。

Live 模式签名参数：color-amount

colorize 与 impeccable Live 模式（浏览器内多变体迭代）深度集成，这是该 reference 区别于普通设计清单的部分。文档规定：

当从 live mode 调用时，每个变体必须声明一个 color-amount 参数，并且 CSS 要对着 var(--p-color-amount, 0.5) 编写，使用户可以在不重新生成的情况下，从"中性"滑到该变体的完整色彩策略。

参数声明的完整 JSON 如下（字段名与取值直接引自原文档）：

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

除签名参数外，还允许最多两个变体专属参数（例如调色板、温度、染色行为），并须遵守 reference/live.md 的参数契约。对照 live.md 可以还原出这套机制的完整生命周期：

1. 声明：在 HTML/JSX 路径上通过 data-impeccable-params 属性声明，schema 与上面的 JSON 一致。range 类型驱动 CSS 自定义属性 --p-<id>，所以变体 CSS 里写 var(--p-color-amount, 0.5)；浏览器端运行时确实把滑杆值注入为该自定义属性——skill/scripts/live-browser.js 中对 range/toggle 参数执行 variantEl.style.setProperty('--p-' + param.id, ...)，这正是 color-amount 滑杆能实时改变页面色彩浓度的底层原因。
2. 预算约束：每个变体的参数上限为 4 个（live.md 第 7 节的硬上限），且"命名的子命令（如 colorize）在 reference 中要求的 MUST 参数不可妥协"——color-amount 就是 colorize 的这个 MUST 参数；再叠加最多两个变体专属参数，正好压在上限内。
3. 验收烘焙：用户点击接受后，浏览器把当前参数值发给 skill/scripts/live-accept.mjs，随后进入 carbonize 清理流程；此时 var(--p-color-amount, 0.5) 会被替换为最终字面量。具体实现见 skill/scripts/live/accept-css.mjs 中的 substituteParamVar（约 L292 起）——它做的是"括号感知"的替换，能正确处理 fallback 里嵌套 calc() 或嵌套 var 的情况，把 var(--p-color-amount, 0.5) 收敛为用户滑定的数值（或更新 var 默认值），再删除其余 [data-p-…] 分支与临时 wrapper。同时 skill/scripts/live/accept-verify.mjs 设有校验器：若源码中残留未烘焙的 var(--p-*)，会以 "preview parameter variable not baked to a literal" 报告，防止预览参数泄漏进正式源码。

这套机制的意义在于：colorize 在 Live 模式下产出的不是"一次定死的配色"，而是一个从 0（中性）到 1（满剂量）连续可调的色彩系统——用户先决定"要多少色"，再决定"什么色"，两个决策被参数解耦，且最终落回源码的是确定性的字面量，不留下任何预览期残留。

小结：一套可复用的色彩改造流程

把整份 reference 串起来，colorize 给出的工作流是：确认品牌承诺 → 按访客模式定职责 → 六项审计 → 命名策略（温度/主从/对比/剂量）→ 构建角色化色板（沿用既有色彩空间，新板首选 OKLCH）→ 八条系统级规则落地 → WCAG AA 对比度与色觉模拟校验 → 六项交付判据 → 移交 polish；若处于 Live 模式，则全程围绕 color-amount 参数编写 CSS，接受时由 accept 流程烘焙成最终值。文中所有规则均可在仓库内核对：决策文档本体在 .agents/skills/impeccable/reference/colorize.md，命令元数据在 skill/scripts/command-metadata.json，参数运行时在 skill/scripts/live-browser.js 与 skill/scripts/live/accept-css.mjs，参数契约全文在 skill/reference/live.md。