企业官网建设流程全解析

• 后端
• 前端
• CMS

本文档是 talebook 仓库内嵌的前端设计审查技能better-colors的输出格式规范解析（源文档位于 review-output.md）。它定义了一份独立色彩审查报告（standalone color review）的完整交付物形态：如何把已确认的配色问题组织成可检索、可复现的 Findings 表格，如何按严重度分级（HIGH / MEDIUM / LOW），如何给出可验证的对比度与色域证据，以及最终如何输出 Block / Needs changes / Approve 三种裁决。读完本文，你将能按照该规范撰写一份专业、可被审阅者直接执行修复的色彩审查报告，并可将其应用于 talebook 前端（app 目录）主题与界面配色的质量把关。

一、审查报告的定位：独立输出与编排者模式

在better-colors技能体系里，review-output.md定义的是独立色彩审查（standalone color review）的格式。当由better-interface这类上层技能统一编排审查时，格式、严重度、问题合并、数量上限（cap）与最终裁决都由编排者接管，此时色彩技能只需提供领域证据与发现（domain evidence and findings），不必自行组织报告结构。

因此，独立审查报告按两个部分组织：

1. Findings（发现问题）：按原则分组的确认问题表；
2. Verification and Verdict（验证与裁决）：列出实际执行的检查与观测结果，并给出最终裁决。

这样的结构保证了每份报告都包含「问题是什么、在哪、怎么改、为什么改、改了之后怎么验证」的完整证据链，方便后续审阅者逐条核验与复现。

二、Findings：按原则分组的五列表格

所有已确认的问题必须按原则（principle）分组，统一使用 Markdown 表格呈现，固定五个列：Severity、Location、Before、After、Why。严禁拆成独立的「Before:」/「After:」两行——表格的横向对比正是为了在一行之内看清「现值 → 目标值 → 依据」的完整关系。

2.1 Severity：三级严重度

2.2 Location：可定位的出处

• 若产物有源码文件，必须写path/to/file:line形式的精确定位；
• 若产物没有源文件（如设计稿、运行时渲染结果），则注明确切的界面与组件（exact screen and component），保证审阅者能定位到可见位置。

2.3 Before / After：现值与精确替换值

• Before：当前使用的颜色值或 token，如实记录；
• After：建议替换的精确值，给出可直接落地的代码。在 talebook 技能语境下，After 通常以oklch(L C H)形式给出（详见 color-conversion.md 的转换约定）。

2.4 Why：违规原则 + 实测证据

• 指出违反了哪条原则（如「新项目色系应使用 OKLCH token」「等幅度的绝对 C 在不同色相下观感不同」）；
• 相关时附上实测的对比度（contrast）或色域（gamut）数据，让问题可量化、可复现，而非主观感觉。

2.5 合并规则与省略规则

• 同构系统性问题只占一行（consolidate a repeated systemic issue into one row），并在该行内列出所有受影响位置，避免同一问题重复刷屏；
• 没有任何发现的原则不设小节（omit principles with no findings），报告只呈现真实存在的问题。

2.6 官方示例表

下表来自源文档的 Example 小节，展示了三行典型发现——分别覆盖「新项目色系规范」「等视觉强度」「P3 色域回退」三类原则：

三、Verification and Verdict：验证清单与最终裁决

Findings 表格之后，报告必须依次完成两部分收尾：

3.1 Verification（验证）

列出实际执行的检查及其观测结果，包括：

• 对比度实测（contrast measurements，如 APCA 的Lc值或 WCAG 2 的比率）；
• 色域检查（gamut checks，如 oklch 值是否落在 sRGB 可显示范围内）；
• 明亮模式与暗黑模式的呈现（both light and dark appearances），当适用时必须分别核验。

如果某项检查尚未执行，必须明确说明「仍需验证什么」（state what still needs verification），不能含糊带过。

3.2 Verdict（裁决）——三态判定

3.3 无发现时的报告形态

当没有任何发现时：

1. 省略 Findings 表格；
2. 明确写出「No actionable color findings」；
3. 照常报告验证情况（verification）；
4. 以Approve结尾。

四、严重度背后的原则体系：报告判据从何而来

review-output.md中的 Severity 判据并非凭空定义，而是better-colors技能整体原则的投影。理解这些判据，才能在写 Findings 时准确归类（对应 SKILL.md 的 Core Principles）：

• 知觉均匀（Perceptual uniformity）：OKLCH 中相等 L 步进 = 相等亮度；而 HSL 的lightness: 50%在不同色相下亮度差异悬殊。这是「同 C 跨色相观感不一致」问题被定为 MEDIUM 的底层原因。
• 稳定色相（Stable hue）：HSL 蓝色随亮度变化向紫色漂移（示例中hsl(240,80%,90%)转换后色相偏移约 18°），OKLCH 色相全程稳定。这就是「色相漂移 > 10° = 可见漂移」的检测阈值（accessibility-contrast.md 的 Hue drift detection）。
• 独立色度（Independent chroma）：色度是独立于亮度的绝对彩色度量；色域是有限的，并非每个 oklch 值都能映射为可显示的 sRGB 颜色——高色度值在部分色相会被裁剪（clipping），因此「P3 无回退」会被记入报告。
• 一个颜色一个含义（One color, one meaning）：品牌色同时用于「链接」与「装饰标题」即构成HIGH级「误导性语义颜色」；修复方式是让交互元素独占品牌色相，标题改用中性色（color-usage.md）。
• 语义 token 而非裸值（Semantic tokens over raw values）：颜色应按角色命名（--color-text-secondary等）并只在该角色内使用，不得「按值借用」其他角色的 token。

五、Why 列的量化证据：对比度与色域测量基准

Findings 表中要求「附上实测对比度或色域证据」，因此报告的书写者需要一套可引用的测量基准。better-colors技能给出了两套体系：

5.1 APCA 阈值（推荐默认）

APCA（感知对比度算法）与 oklch 同源于感知亮度，是技能默认的对比度量纲。Lc（Lightness Contrast）为有符号值：正值 = 深色文字配浅色背景，负值反之，阈值比较取绝对值。

Lc 30 同时也是禁用态与占位文本的最低要求；非文本元素可辨识的绝对下限为 Lc 15。

5.2 WCAG 2 阈值（合规声明场景）

如需对外做 WCAG 2.x 一致性声明，则以比率体系为准：普通文本 AA 4.5:1 / AAA 7:1，大字号文本（≥24px，或粗体 ≥18.5px）AA 3:1 / AAA 4.5:1，UI 组件与图形对象 3:1。

5.3 色域边界与检查方法

sRGB 与 Display P3 的关系是：每个 sRGB 颜色都在 P3 内，但并非每个 P3 颜色都在 sRGB 内（P3 约多覆盖 50% 色彩）。最大色度随亮度与色相变化，边界并不规则——在 L=0.5 的 sRGB 中，紫色（H≈285）最大 C 约 0.29，红橙（H≈0–30）约 0.20，而青色（H≈195）最低仅约 0.09；峰值色相还会随亮度迁移。检查方法：若某颜色的 C 超过其 L/H/色彩空间的色度上限即发生裁剪，修复方式是保持 L 与 H 不变、下调 C（示例：oklch(0.7 0.35 150)越界，压到oklch(0.7 0.22 150)）。相关细节见 gamut-and-tailwind.md。

5.4 明亮 / 暗黑双态核验

技能要求每个自定义颜色都有明暗两套变体，且报告必须在两种外观下逐一重测每个前景/背景对——明暗两套色板并非镜像，明模式通过的对在暗模式可能失败（color-usage.md）。若元素位于半透明表面（如带backdrop-filter的头部、浮层），还需在最浅与最深的内容上分别测试，或使表面足够不透明以免对比度被背景滚动破坏。

六、在 talebook 项目中的落地方式

6.1 技能在仓库中的组织

talebook 将整套前端设计审查技能内嵌于.agents/skills/目录：better-colors技能由 SKILL.md（总览与原则）、六个主题参考文档（转换、调色板、对比度、色域与 Tailwind、用法、输出格式）以及agents/openai.yaml组成。review-output.md正是其中的「输出格式」约定，供独立色彩审查或上层better-interface编排消费。

6.2 面向的审查对象

从源码结构看，该技能面向 talebook 的 Vue/Nuxt 前端界面（app 目录）：内置主题系统位于 builtin-themes.ts 与 theme-display.ts，运行时主题状态由 theme.ts 管理，并提供多套内置主题组件（见 app/components/themes 下的 brass、graphite、light-gray、minimal、warm-red 等）。当对某一主题或组件开展色彩审查时，可套用本报告的格式：

• 每个主题色板的阶梯一致性、明暗双态的前景/背景对比，对应Findings → Why中的 APCA/WCAG 实测数据；
• 新引入的主题色是否使用 OKLCH token、是否在明暗模式下各自核验，对应Verification中的检查清单；
• 若存在使内容不可读的对比失败，裁决应为Block；仅剩孤立的打磨问题则为Needs changes；全部通过且完成验证后以Approve收尾。

6.3 实操建议

• 写 Findings 时先按原则分组再填表，同构问题合并为一行、逐条列出位置；
• Before/After 严格给出「当前值 → 精确替换值」，并注明文件:行号；
• 无论裁决结果如何，Verification 部分必须记录真实执行的检查与观测，未执行的项明确标注待验证；
• 遵循 color-conversion.md 的转换约束：仅在项目已标准化 OKLCH 或明确进行色系迁移时才转换记法，currentColor、inherit、transparent等关键字与渐变插值方式一律不动。

七、总结

一份合格的独立色彩审查报告，本质是一份可执行、可验证、可裁决的变更单：五列 Findings 表承载「在哪、现值、目标值、为什么」的完整证据，Verification 承载「测了什么、结果如何、还差什么」，Verdict 则用Block/Needs changes/Approve三态给出无歧义的合入结论。掌握这套格式后，无论是为 talebook 新增主题、调整组件配色，还是评审他人提交的色值变更，都能以一致、严谨、可复现的方式输出结论——这正是该规范写在better-colors技能中的价值所在。

• 后端
• 前端
• CMS