用途:为 UI 智能体补上“眼睛”,把开环的文字指导变成 构建→查看→评审→修复 的闭环,验证已渲染界面是否符合设计系统。它不生成审美(那是 frontend-aesthetics),也不做静态强制(那是 design-conformance 钩子与 theme-consistency 规则)。
前提:UI 必须可渲染,即有运行中的开发服务器 URL/路由或静态 HTML 产物。若无法渲染,应说明并启动预览或退回静态审查,不得假装看过。
主要能力与流程(默认最多 3 次迭代):
- 渲染与捕获:用 Playwright MCP 的 browser_navigate 打开路由,按 references/viewport-matrix.md 逐个视口 browser_resize(375 → 768 → 1440)并 browser_take_screenshot;通过 browser_evaluate 模拟 prefers-color-scheme: dark 后在主视口重截。若设计系统未声明深色模式则跳过并注明。PNG 存于 .claude/workflow/vision/<route>-<viewport>[-dark].png。
- 第一层确定性门禁:先跑 design-conformance 检查(硬编码 hex/px 与 token、混用组件库、缺少 prefers-reduced-motion),并读取 browser_console_messages,运行时报错或资源加载失败即缺陷。任何 FAIL 先修复,再进入视觉评审。
- 第二层视觉评审:读取截图,按 references/critique-rubric.md 打分,对照 .claude/design/design-system.md(调色板/字号阶梯/间距/签名元素);若有 Stitch 屏幕 PNG 或 Figma 画板,仅做布局层面比较(结构、层级、间距节奏),不做像素级 diff。输出结构化结论:status 为 PASS 或 ITERATE,defects 列出 element、viewport、expected、actual。
- 迭代:逐项修复缺陷后重新渲染与捕获,达到 PASS 或迭代预算即停;预算用尽仍失败则如实报告剩余缺陷。
- 收尾(强制):到达 PASS 或迭代上限后立即调用 browser_close,不要留下浏览器;@playwright/mcp 的 Chrome 不会自行关闭,未关闭会残留甚至被孤立运行数天。
输出:将结论、截图路径与缺陷日志写入 .claude/workflow/vision-report-<route>.md,供评审者或用户查看视觉证据;没有附带截图不得声称“看起来不错”。
限制与诚实原则:截图与视觉调用消耗 token,迭代上限与“先跑第一层”的顺序用于控制成本;若无法渲染、无法进入深色模式或触及上限,必须说明是哪一种。把跳过的检查报告为通过,正是本技能要防止的失败模式。相关文件:references/critique-rubric.md、references/viewport-matrix.md、rules/agent/design-system-persistence.md、skills/frontend-aesthetics/SKILL.md、hooks/design-conformance.cjs、skills/stitch-design/SKILL.md。