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 11 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 清单 不属于任何一个风格,11 种风格共用同一套工艺底线。

检查模型 · 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)。双语页跑两遍:页面默认的那一边,加 --lang=zh 一遍 —— 2026-09-23 之前这道检查只看过英文那一半(Playwright 默认 en-US,页面按浏览器语言选边)。切不过去就 exit 4、不出结果,不拿另一种语言的结果 冒充。两类语言检查:lang-both-showing(另一边还显示着)、lang-leak(英文视图里的汉字; 中文视图里的月份 / 星期名、页面别处翻译过的词、英文句子)—— 有意保留的另一种语言写 lang="en" / lang="zh-CN" / translate="no"。窄屏扫描:390 / 600 / 768 / 900 四个宽度下整页横滚是 error(narrow-overflow-x,报出是谁撑宽的),1024 那一趟仍只报 warn;390 和 768 两个宽度每次都跑整套页面内检查:横向滚动容器里拖不到的内容是 error (pan-unreachable),重叠 / 溢出 / 图里的字 < 9px(diagram-tiny-text)报 warn。 窄屏下讲解图不跟着缩:包进各家的图框 <div class="<skill>-scroll" style="--pan-w:…">, --pan-w 用检查报出的数(最小字到 9px 时图要多宽),在框里左右拖;产品界面示意、 缩略图、插画整张缩,<svg> 上标 data-allow-shrink。known-bugs §1.65–1.71。 自检 scripts/visual_selftest.sh,53 项。
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)。 另有一条不是 axe 的规则 svg-text-contrast(2026-10-10 加):axe 的 color-contrast 不查 SVG <text>,图里的字从来没人量过。由 scripts/_svg_contrast.mjs 量 —— 字设透明拍一张取底色,字涂黑、涂白各拍一张找出笔画,只看笔画底下的像素, 笔画像素对比度的第 20 百分位低于 AA(4.5:1,渲染后 ≥ 24px 或粗体 ≥ 18.66px 的大字 3:1)就报。 每页打一行「svg text: N measured · not measured: …」,0 处和什么都没量分得开。 目前只报不拦:全仓 143 次页面运行量了 13806 段字,2924 处不到 AA, 几乎都来自三家图例模板库的固定配色(known-bugs §7.11 第 5 条),还清后再升阻断。 check_objective.mjs 的 O6 用的是同一个模块。自检 scripts/svg_contrast_selftest.sh,12 项。
4. interaction-audit.mjs — 点开之后才存在的那些状态(2026-09-05 加)
5. screenshot.mjs — 全页截图(只产物;评判它的是人眼)。截之前先把整页滚一遍 再回到顶部 —— 九套里有四套(anthropic / apple / ember / sage)的 references/motion.md 教项目写「滚动才浮现」:元素初始 opacity:0,靠 IntersectionObserver 加 .is-visible。不滚的话,首屏以下这类元素在截图里 全是空白。这一道没有机器判读它,所以错的截图不会失败、只会误导 —— 一块空白读起来像「这节漏配图了」,人会去改一个根本不存在的问题; 把同一张图喂给模型,得到的是同样自信的错结论。 滚完之后仍然停在 opacity:0 的 reveal 元素会被数出来单独提示。 自检 scripts/screenshot_selftest.sh,28 项。 ⚠ reducedMotion:'reduce' 不覆盖这件事:它收的是过渡时长, 不会替你加那个 class。

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

前三道判的是同一个静止画面: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,43 项。--no-design-md 可以忽略它。

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

• pixel-gate.mjs(--pixel)— 可选的第六道机械检查,像素回归比对已提交基线。 每张基线旁边有一份同名 .json,记着它是在什么环境下录的(Chromium 版本、 视口、真正加载成功的字体)。比对前先比这些,不一样就单独报「环境变了,不是页面变了」, 退出码 3,跟真回归的 1 分开。

  为什么要分开:2026-09-11 那 7 张基线全部报回归(dashboard 1.65%),查了一下午才确定 页面一个字没改 —— 基线录于 Chromium 147,机器换到了 148。把图缩到 1/16 差异归零, 说明差的是字形边缘而不是有东西移位;换回 147 渲染,差距缩小 4.5 倍。 毛病不在基线过期,在于「设计变了」和「浏览器变了」从这个脚本出来长得一模一样 —— 一个百分比,没法判断是哪种。看不懂的数字不算结果。 字体也记进去,是因为断网渲染跟基线差 3.55%,比换浏览器还严重(字体从 CDN 现取)。 自检 scripts/pixel_selftest.sh,28 项 —— 其中最要紧的一条是 环境不同的页面里塞一个真改动,必须仍然报回归,防止新机制把信号一起吞掉。

• 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(条数跑 --facts --list,每条写 Reader sees / Why / Defense)
• references/cross-skill-rules.md(11 种风格共通工艺底线 · 有 §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 之间没有 任何东西,阈值是画在空隙里的,不是拍的。代价说清楚:长段落里的过期数字这一问看不见, 那是前一问的活。

2026-10-10 前一问又漏一次:八个 demo 页和五份路线图写「九种美学」「nine voices」「九个生成器」,<!-- facts-ignore: quotes the stale phrasings this paragraph is about --> 磁盘上是 11 个设计 skill,它照样说 clean —— 这些写法清单里一条都没有,中英两半又都是旧的, 第二问也看不见。补了设计数的 9 种写法、路线图分项里的系统类计数(skills-systems)、 到三十的英文 / 中文数词;补完放到改之前的版本(99b234c)上跑,这些页面都被报出来, 旧清单在同一版本上说 clean。同一天又补 canonical 数:路线图写「N/N matrix」「N/N 整张覆盖表」 「Done · N/N」,图里把「N / N」和「page-types covered」分在两个 <text> 里 —— 逐行读, 哪一行都不算一句声明。所以整行只有「N / N」的也和下一行拼起来读(joinStats), 原来只拼纯数字行。自检 scripts/facts_selftest.sh,47 项(其中 27 项是 2026-10-10 补的写法: 18 项必须报、9 项不许报)。

生命周期规则

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(58 项)
• scripts/axe-audit.mjs — Gate 3 可达性 check(axe-core + SVG 文字对比度)
• scripts/_svg_contrast.mjs — SVG 文字对比度的测量模块(axe-audit 和 check_objective O6 共用;自检 svg_contrast_selftest.sh 12 项)
• scripts/screenshot.mjs — Gate 4 全页截图(截前滚一遍;自检 screenshot_selftest.sh 28 项)
• scripts/count-check.py — 全仓计数判定(承载短语 vs 磁盘真值 + 检查模型)
• scripts/learning-loop.mjs — 组件 07 · critic verdict → design-learner prompt
• references/known-bugs.md — bug 大全(条数跑 --facts --list)
• references/cross-skill-rules.md — 11 种风格共通规则(含 §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 组件路线图)