Design Review

design-review — Separate Evaluator for Design-Skill Output

Why this skill exists · 为什么独立出来

EN — Two rules carried over from Anthropic's harness design for long-running apps and the GAN paradigm:

1. The agent doing the work praises its own work. The 9 design skills (apple / anthropic / ember / sage / glass / eclat / lectern / atelier / primer) are generators — they know the style, they can produce HTML, and they will naturally rate their own output favourably.
2. An independent, skeptical evaluator is the real lever. This skill imports nothing from any generator. Its rules, scripts, known-bugs list, and critic agents live in one shared pool — the nine styles pay the same quality floor.

ZH — 两条原则来自 Anthropic harness-design 和 GAN 范式:(1) 做事的 agent 倾向自评过高;(2) 独立持怀疑的 evaluator 才是真正的杠杆。9 个 design skill 是 generator,会给自己打高分;design-review 脚本、规则、 已知 bug 清单 不属于任何一个风格,9 种风格共用同一套工艺底线。

检查模型 · The gate model(全仓唯一定义)

这一节是全仓"几道检查"的唯一出处。 其它任何文件说到检查数量,以这里为准、 引用这里,不要自己另报一个数(2026-08 之前全仓有三套互相矛盾的数法, 计数检查追着改了四轮 —— 根因就是没有唯一定义)。EN — this section is the single source of truth for the repo's gate counts; every other surface cites it instead of asserting its own number.

五道机械检查(bin/design-review 默认全跑,按序):

1. verify.py — 结构(静态)
2. visual-audit.mjs — 渲染(Playwright)
3. axe-audit.mjs — 可达性(axe-core;阻断规则四条:color-contrast、 link-name、aria-prohibited-attr、svg-img-alt。全仓两主题实测 0 违规 —— glass light 那 84 处欠账已于 2026-08-27 在 CSS token 层还清,见 known-bugs §6.6)
4. interaction-audit.mjs — 点开之后才存在的那些状态(2026-09-05 加)
5. screenshot.mjs — 全页截图(只产物;评判它的是人眼)

第四道在补什么(为什么前三道漏得掉)

前三道判的是同一个静止画面:verify 读源码,visual-audit 量首帧, axe 跑加载后的 DOM。于是标签页点了没反应、手风琴展开后文字读不清、 按钮一点就抛异常 —— 三道全绿照样发布。

第四道逐个操作可交互元素(button / summary / [role=tab] / [aria-expanded] / th[aria-sort] / input / select / 页内锚点),每点一次判五件事:

已经激活的控件不算死:带 aria-current / aria-selected="true" / aria-pressed="true",或 class 里有 active / selected / current 的, 点它本来就不该有反应。故意不接线的控件写 data-inert-by-design="理由" —— 跟 data-allow-overlap 同一个约定, 必须写理由,声明才是可复核的而不是一个静音开关;而且一旦它真的动了,这一条会报 error。

判「这个元素读者看得见吗」用浏览器自带的 checkVisibility(),不是手写那套判断。 收起的 <details> 不会给内容设 display:none —— 它保留一个真实的 640×122 盒子且 visibility:visible,这正是 known-bugs §1.40 那批幻觉重叠的根因。

代价:每个控件一次页面加载,一页 17-21 秒(前三道合计约 9 秒)。 同形状的控件只测前两个(--per-shape),八条一模一样的 FAQ 手风琴不必测八遍。 要跳过用 --no-interact,但默认是开的 —— 选配的检查等于没有检查。 自检:skills/design-review/scripts/interaction_selftest.sh —— 7 个故意做坏的测试页, 10 项检查,每一类判定的正反两面都测。

让它不靠记性:编辑触发的 hook

五道跑一页要 17-25 秒,因为其中三道要开浏览器。没人会在每次改动后都付这个代价, 于是实际情况是发布前才想起来跑一次 —— 而那正是结构问题最难改、可访问性问题最可能 带着上线的时刻。

verify.py 是唯一不需要浏览器的一道,0.05 秒,所以它可以每次写 HTML 都跑。

hooks/design-gate/ 两个 hook:

• post-edit.sh(PostToolUse)—— 每次写 HTML 跑一遍 verify.py,不过就把结果 送回给模型;同时把这一版的内容哈希记进 .design-gate/pending.tsv。 路径不是 .html、或者这个项目没声明过它在意设计,立刻退出不作声。 「这一页归谁管」看的是项目自己放的 DESIGN.md,不是「检查器源码在哪」 —— 第一版按后者找,于是只有 sky-skills 自己能命中,而用这套东西的下游项目一个都收不到, 偏偏最容易忘记跑检查的正是它们。verify.py 的位置从钩子脚本自身路径反推, 跟被编辑的文件在哪毫无关系(见 hooks/design-gate/owner.sh)。
• stop.sh(Stop)—— 回合结束时,报出哈希在 pending.tsv 里、 却不在 passed.tsv 里的文件。bin/design-review 五道全过才写这条回执, 带 --no-interact 或 --no-axe 的部分运行不写(部分运行的回执是假的)。 改文件会改哈希,回执自动失效,不用谁记得作废它。

它只拦一次,然后清账。 一个"条件不满足就一直不放行"的 Stop hook, 在条件根本达不到的时候会一直不放行,记录里就是 hook 和模型互相重复八轮 直到被强制放行。所以这个只拦一次,把待办清空,然后闭嘴 —— 目的是让漏掉这件事被看见,不是强制执行。

装:hooks/design-gate/install.sh(先 --dry-run 看它要改什么)。 单次关掉:DESIGN_GATE_HOOK=off。自检 hooks/design-gate/selftest.sh,21 项。

项目自己的决定:DESIGN.md

九套语言是通用的,一个用它们的项目却有自己的决定:写哪一套、哪些提示看过了并且 决定就这样、这一页到底想让谁看懂什么。这些今天没有落点,于是每次跑都在重新争 同样的 warning,而口味评审判的是一个虚构记事本应用的样张,不是这个项目的意图。

在页面旁边(或往上任一层)放一个 DESIGN.md:

---
skill: anthropic
monolingual: false
waivers:
  - check: visual-audit:figure-no-caption
    reason: 这里的图就是章节头,配图注等于把上面的 h2 再说一遍
    until: 2026-12-31
---

# 这个项目的设计决定
...给口味评审看的散文...

三条硬规矩,都有检查:

1. 理由必填且要写成句。这是豁免可复核与静音开关的分界。
2. check 必须是真实存在的检查 id。id 是从 visual-audit.mjs 源码里现读的, 所以上游改名会在这里报错,而不是让豁免安静地什么都不做。
3. until 过期就校验失败,逼你重新决定一次。 另外豁免了一条这一页根本没触发的检查也会被报出来 —— 那行字在骗下一个读者。

monolingual: 不是豁免。豁免说的是「这条发现我们看过了,决定就这样」,它降级不隐藏; monolingual: 说的是「那条规则不是冲我们来的」—— 两句话不是一个意思,所以是两个字段。

DESIGN.md 写坏了整轮不跑,在第一道之前就停 —— 它决定检查怎么做, 半读半猜比直接拒绝更坏。模板见 references/DESIGN.md.template, 自检 scripts/design_md_selftest.sh,36 项。--no-design-md 可以忽略它。

五道之外,按需叠加,不计入"五道":

• pixel-gate.mjs(--pixel)— 可选的第六道机械检查,像素回归比对已提交基线
• LLM critic(--critic solo / --multi-critic 4 专家)— 口味评审。 critic 不是第五道机械检查,它在机械检查之外
• 人眼看截图 — 机械检查是必要条件,不是充分条件

(上面这行注释是机器可读形态,scripts/count-check.py 解析它做全仓计数判定。 改模型 = 改这一节 + 让 count-check 的探针继续过。)

What ships today · 当前交付

Entry points · 入口

一条命令跑完(推荐)

~/.claude/skills/design-review/dr-cli [--repo=<path>] [--skill=<name>] [--css=<path>]... \
                  [--critic | --multi-critic] [--learn] [--allow-monolingual] \
                  <html> [...]

• --critic / --multi-critic 跑 LLM 口味评审(五道机械检查之外;solo 或 4 专家并行)
• --learn 跑完把 verdict 喂 learning-loop.mjs 产出 design-learner prompt
• --allow-monolingual 对内部单语 memo 豁免双语强制(issue #2)
• --audit <dir> 整树批量检查;加 --discover 只列出树里所有 .html(分目录,不跑检查),确认没有藏在子目录里漏检的页 —— 详见下面「多页交付」
• 第二视口几何复查默认开:Gate 2 主跑(1440)后,把 overlap/overflow 几类在更窄视口(默认 1024)再跑一遍,宽度相关的碰撞作 warn 标 [at Npx](known-bugs §1.34)。--viewport2=WxH 调宽度、--no-second-viewport 关掉
• 任一步 exit 非 0 整体 fail,截图存 --out= 或默认 <repo>/shots/

本仓用例:

~/.claude/skills/design-review/dr-cli index.html docs/HARNESS-ROADMAP.html
~/.claude/skills/design-review/dr-cli --multi-critic demos/gated-dual-clone/index.html

跨仓用例(例:engram):

~/.claude/skills/design-review/dr-cli --repo=/path/to/engram --skill=anthropic \
  --css=/path/to/engram/docs/assets/app.css \
  docs/en/index.html

多页交付:发布前整树批量检查(防漏页)

逐页跑 dr-cli <file> 是写每一页时的常规做法,但多页 deck 发布前要整树跑一遍,否则放在子目录里的页(_demos/ 样例、复制进来的报告产物等)很容易忘了过检查,带着真 bug 上线也没人发现。

# 整树批量检查(verify + visual-audit,递归子目录,一份汇总报告)
~/.claude/skills/design-review/dr-cli --audit <deck-dir>

# 只列出会被检查到的页(分目录,不跑检查)—— 先确认没有漏页
~/.claude/skills/design-review/dr-cli --audit --discover <deck-dir>

• --audit <dir> 递归走子目录,_demos/ 这类装内容的下划线目录也会进(纯资源目录 _assets/ 无 html 自动跳过)。逐页检查只覆盖你显式传的那一个文件,--audit <dir> 是发布前的兜底。
• --audit --discover <dir> 先把树里所有 .html 按目录列出来(不跑检查),一眼看清有没有藏在子目录里没被检查的页。

分别调用(调试用)

# 1) 结构检查(静态)
python3 skills/design-review/scripts/verify.py \
  [--skill=<name>] [--css=<path>]... [--allow-monolingual] <html> [...]

# 2) 视觉检查(Playwright 渲染) · 加 --ignore-intentional 消掉 brand-intentional 噪音
node skills/design-review/scripts/visual-audit.mjs \
  [--ignore-intentional] <html>

# 3) 可达性检查(axe-core · --strict 让阻断规则真的阻断)
node skills/design-review/scripts/axe-audit.mjs --strict <html>

# 4) 肉眼检查(全页截图)
node skills/design-review/scripts/screenshot.mjs <html> shot.png

# 5) 口味评审(五道之外)· solo / multi critic
#    在 Claude Code 里:
Task(subagent_type="design-critic",              ...)  # 单专家
# or 4 并行:
Task(subagent_type="design-composition-critic",  ...)
Task(subagent_type="design-copy-critic",         ...)
Task(subagent_type="design-illustration-critic", ...)
Task(subagent_type="design-brand-critic",        ...)

# 6) 回灌成规则(critic 发现 → known-bugs + 机器 check)
node skills/design-review/scripts/learning-loop.mjs \
  --verdict=<path/to/verdict.json>  # 产出 design-learner prompt
# 然后在 Claude Code 里 Task(subagent_type="design-learner", ...)

任一步 exit 非 0 = 没完成。修完再跑。

每道检查覆盖的 bug 类

具体清单在:

• references/known-bugs.md(84 条,每条写 Reader sees / Why / Defense)
• references/cross-skill-rules.md(9 种风格共通工艺底线 · 有 §G 双语规则 + §I 卡片分组规则)
• references/dos-and-donts.md(每 skill 下的风格特定反例)

Learning-loop · 回灌成规则的流程

目标:同一类 bug 不被抓两次。

1. Critic 抓到新问题 → learning-loop.mjs --verdict=<json> 解析 verdict
2. 调 design-learner subagent → 产出 paste-ready 三件套:
   • known-bugs.md 新行
   • visual-audit.mjs 新机器 check(若能渲染时扫到)
   • <skill>-design/references/dos-and-donts.md 新行(若 style-specific)
3. 人审 paste → commit closes #N

首次实战(2026-04-22):13 条原始 issue → 5 类新 bug → 3 新 known-bugs(1.17/1.18/1.19)+ 1 新机器 check(figure-no-caption)+ 8 条 dos-and-donts。

Roadmap · 对应 HARNESS-ROADMAP

facts 是两问,不是一问。 前一问「页面说的跟磁盘对不对得上」靠一份手写措辞清单 (facts.mjs 里那批正则),它只认有人想到过要写的写法。2026-09-08 实测这不是理论 缺口:它报了 18 处过期数字,全改完之后说 clean,同一批页面上还剩 17 处 —— 漏掉的那些长一个样:同一行里英文那半改了,中文那半没改,而且方向不固定(另一页反过来)。

所以加了第二问:同一处声明的中英两半必须说同一个数。 不认措辞,只问两边一不一致。 它跟前一问抓的是两类东西 —— 页面可以自己跟自己一致但整体是旧的 —— 谁也替代不了谁。

规则窄得有理由,是量出来的(本仓 2667 处配对):只比数字集合 → 50 处不同、47 处是好的; 再要求两边数字个数相同 → 6 处、3 处是好的;再要求每侧不超过 4 个数字 → 3 处、 0 处是好的。个数相同这条挡掉的是「英文写单词中文写数字」(Four scripts / 4 个脚本), 占原始差异的 44/50;上限 4 这条的理由是一句计数声明活在标题、图注或数据标签里, 带一两个数字,而本仓唯一超过 4 的是三段 45 个数字的变更记录 —— 2 和 45 之间没有 任何东西,阈值是画在空隙里的,不是拍的。代价说清楚:长段落里的过期数字这一问看不见, 那是前一问的活。自检 scripts/facts_selftest.sh,20 项。

生命周期规则

design-review 发现一个 不在 known-bugs.md 里 的新问题 → 必须补:

1. known-bugs.md 追加 1 行,写清 Reader sees / Why / Defense
2. 能静态扫 → 加 check 到 verify.py
3. 能渲染时扫 → 加 check 到 visual-audit.mjs
4. Style-specific → 同步更新对应 <skill>-design/dos-and-donts.md

repo 级硬规则:同一类问题不能被抓两次。

Files · 文件

• ~/.claude/skills/design-review/dr-cli — 一条命令跑完 5 道检查 + 可选 --multi-critic / --learn
• scripts/verify.py — Gate 1 结构 check
• scripts/visual-audit.mjs — Gate 2 渲染 check(51 项)
• scripts/axe-audit.mjs — Gate 3 可达性 check(axe-core)
• scripts/screenshot.mjs — Gate 4 全页截图
• scripts/count-check.py — 全仓计数判定(承载短语 vs 磁盘真值 + 检查模型)
• scripts/learning-loop.mjs — 组件 07 · critic verdict → design-learner prompt
• references/known-bugs.md — 84 条 bug 大全
• references/cross-skill-rules.md — 9 种风格共通规则(含 §G 双语 / §I 卡片分组)
• references/canonical/README.md — canonical 参考库说明 + 扩库流程

Reference

• Anthropic · harness design for long-running apps — "separate doing from judging"
• 同仓 pair:skills/gated-dual-clone-audit/(第 2 个独立 evaluator)
• 指南:docs/HARNESS-ROADMAP.html(9 组件路线图)