UI 差异截图 是做什么的?
评审者可以阅读 CSS diff,但他们无法直观“看到”它。本技能会渲染 PR 的 base 和 head 版本,进行比较,并将前后对比图发布到 PR 上。同时,还会附带一个简短的用户视角变更摘要,并附上测量值。
机械性工作由单个脚本完成。你的职责是需要判断的部分:检查哪些页面、变更意味着什么以及发布到哪里。
下面的 $SKILL 表示包含此 SKILL.md 的目录。请预先设置一次,例如 SKILL=/path/to/skills/ui-diff。所有内容都写入仓库根目录下的 .ui-diff/ 文件夹,该文件夹已通过 .gitignore 本地忽略,因此不会影响任何已跟踪文件。
1. 上下文
gh pr view --json number,url,baseRefName,headRefOid,body 2>/dev/null; git status --short
如果存在,请读取仓库根目录下的 .ui-diff.json。它可能包含路由、开发命令、遮罩和认证信息(参见 references/config.md)。
要渲染哪个 head取决于用户正在做什么:
- **发布到 PR:**通过传递
--head <headRefOid>来渲染确切推送的内容。否则,未提交的本地编辑会出现在声称显示 PR 的报告中。如果工作目录有未提交的更改或未推送的提交,请说明这些更改不会显示。 - 检查工作中的进度(“这样看起来对吗?”):使用工作目录(默认,不使用
--head)。报告会标注为“+ 未提交的更改”。
2. 选择页面
node $SKILL/scripts/routes.cjs --base <base> --log # 如果你将 --head 传给 run.sh,请添加 --head <sha>
它会将变更文件映射到路由:页面文件、布局下的路由、导入变更组件的页面(遵循别名和 workspace 包),以及主页和一些用于应用级样式的链接良好的页面。它会输出 JSON,包含每个路由的原因和置信度、needsExample(无法填充的动态路由)和 unmatched(无法定位的 UI 文件)。将其作为起始列表,并使用 references/route-mapping.md 中的判断:删除 diff 不支持的低置信度选择,查找 needsExample 的 ID,并亲自放置 unmatched 文件。如果没有任何 UI 相关变更(所有文件都被 ignored),请说明情况并停止。不要生成空报告。
Storybook 项目(存在 .storybook/ 文件夹或 storybook 脚本):当变更主要是组件时,使用 run.sh --storybook 对它们的故事进行差异对比,而不是页面;它会自动从变更文件中选取故事。对于路由、布局和应用级样式,仍使用页面。请参见 references/route-mapping.md 中的 Storybook 章节。
用一两行向用户说明你将捕获哪些路由以及原因,然后继续。仅当无法找到任何路由,或动态路由需要找不到的 ID 时,才询问用户。记录下受影响但未捕获的路由(太多无法检查、需要登录、模态状态)。这些信息会放在摘要中,这样“没有视觉变化”就不会被当作安全信号。
3. 运行
bash $SKILL/scripts/run.sh --routes "/,/pricing" [--head <sha>] [--base <ref>] \
[--viewports "desktop:1440x900,mobile:iPhone 13"] [--schemes light,dark] [--dev "<包含 {port} 的命令>"]
(--auto-routes 会添加 routes.cjs 选取的路由,并记录原因;当你无需更正时使用。)
它一次性完成以下操作:
- 首次使用时安装工具(Playwright + Chromium 在
~/.cache/ui-diff中,大约一分钟;不影响项目自身的依赖); - 在 git worktrees 中检出 base,如果提供了
--head则检出 head,并将未跟踪的.env*文件复制到其中; - 当 lockfile 匹配时重用已安装的依赖,并保留每个检出的构建缓存,否则进行安装;
- 在各自的进程组中,在空闲端口上启动两个开发服务器。之后只会停止这些服务器,用户的其它服务器不受影响;
- 捕获每个路由 × 视口组合。移动端使用真实设备模拟(触摸、移动 UA)。动画被冻结,框架开发工具栏被隐藏;
- 对截图进行像素级差异(
results.json,全页和缩放图像),并运行计算样式差异(measured.md)。
Storybook 模式(--storybook,或使用 --stories "button--primary,card--*" 自行选择故事)会启动 Storybook 而非开发服务器,记录它选取了哪些故事及原因,并按故事 ID 命名结果。如果没有匹配的故事,则退出并建议 ID。
它会输出计数,例如 {"changed":2,"added":1,"unchanged":3,...}。默认值:base = PR 的 base 分支(否则为默认分支),视口 = desktop 1440×900 + iPhone 13,亮色模式。当变更涉及主题、颜色或 token 时,添加 --schemes light,dark。
如果运行失败,错误信息会说明哪一步失败以及其日志位置(.ui-diff/server-*.log、install-*.log、capture-*.log)。常见原因包括缺失的环境变量、错误的开发命令(传递 --dev)或工作目录中未安装的依赖。修复原因后重新运行。不要跳过任何一侧。
4. 阅读结果并编写摘要
先阅读 .ui-diff/report/measured.md。如果它以 可能的问题 开头,请首先检查这些问题:文字被截断、横向滚动、重叠、屏幕外的控件、小型移动端点击目标以及 head 版本的 axe-core 可访问性违规(是 head 上新增的)。这些是启发式规则,因此请打开每个缩放图像(report/issues/)并加以判断。将真正严重的问题标为“值得一看”,并删除或弱化那些看起来像是故意的。measured.md 的其余部分包含 测量到 的事实:跨元素分组的计算样式变更、大小改变的元素、布局偏移、复制文本变更以及 新出现的 WCAG 对比度失败。然后,使用你有的任何文件或图像查看工具打开缩放图像(report/zoom/*__after.png 和 __before.png)以及差异叠加图,看看这些事实在上下文中如何呈现。如果你无法查看图像,则仅根据 measured.md 编写摘要并说明未审查截图。还要检查 results.json 中的 warnings:HTTP 错误、框架错误叠加、未捕获的异常。
提供了 Figma 链接(或者 .ui-diff.json 中的某个路由有 figma 字段)?还要将 head 版本与设计稿进行比较。请遵循 references/figma.md。
为不会阅读代码的设计师或产品经理编写 .ui-diff/report/summary.md:
**变更内容**
- **定价卡片** — CTA 按钮现在为药丸形状(圆角 4 → 999px),内边距增大(8×14 → 12×20px);Pro 卡片带有高亮(2px `#2563EB` 边框,`#EFF6FF` 填充)和“最受欢迎”标签。
- **头部(所有页面)** — 导航链接从蓝色 `#2563EB` 变为灰色 `#9CA3AF`。
**值得一看**
- ⚠️ 导航链接在白色背景上的对比度现在为 2.5:1(原为 5.2:1);正文文本需要 4.5:1。
- ⚠️ `/settings` 发生了更改,但其文件未变动——它继承了新的 `Button` 内边距,导致移动端“保存”/“取消”按钮换行。
**未检查:** `/admin/*`(需要登录)、删除账户模态框。
指南:
- 使用
measured.md中的测量值来表示颜色、大小和间距。不要根据像素估算。如果某些内容在图像中可见但不在measured.md中(图片、画布、SVG 内容),请按所见描述。 - 较大的像素变化百分比伴随着“偏移……布局偏移”行,通常意味着内容被推下,而不是所有内容都变了。请这样解释。
- “值得一看”列表的首项应为 可能非预期的 变更:文件未变动但页面变了、仅在某个视口出现异常、溢出、消失的元素、页面错误。然后是对比度失败和小型触摸目标(移动端小于约 44px)。
- 说“发生了变化”,而不是“故意发生了变化”。你能看到什么变了,而不是为什么。
- 保持比例。仅改动一种颜色就用一个要点。
然后运行 node $SKILL/scripts/viewer.cjs --report .ui-diff/report 来刷新本地审查页面(report/index.html:滑块、并排、差异叠加、摘要置顶),并提示用户打开它(macOS 上使用 open,Linux 上使用 xdg-open)。
5. 发布
发布会将内容写入共享的 PR,并推送一个分支。首先向用户展示摘要并确认,除非用户已明确要求发布。然后:
PREFIX=$(bash $SKILL/scripts/publish.sh .ui-diff/report <pr> <head-short-sha>)
node $SKILL/scripts/comment.cjs --report .ui-diff/report --base-url "$PREFIX" \
--summary .ui-diff/report/summary.md --out .ui-diff/comment.md
node $SKILL/scripts/post.cjs --pr <pr> --body .ui-diff/comment.md --mode comment # 或 --mode description
publish.sh将图像推送到ui-diff-assets分支(一个提交,每次发布替换)从一个一次性克隆中。图像随后会在 GitHub 上内联渲染,包括私有仓库中有读取权限的任何人。- 退出码 3 表示没有推送权限(通常是 fork 的 PR)。切换到手动模式。
- 如果提示仓库是 公开的,请告知用户截图将是公开的。当
storageState以真实账户登录时,这一点尤为重要。在发布前获得用户确认。
post.cjs会替换之前的 ui-diff 评论或描述部分,而不是叠加新的。描述中的其他内容保持不变。- 仅当
.ui-diff.json中设置了"requireApproval": true(仓库运行设计审查工作流)时,才向comment.cjs添加--approval:它会添加一个“设计已批准”框。 - 手动模式(没有资产分支,或没有推送权限):不带
--base-url运行comment.cjs,然后运行open .ui-diff/report。用户需要自行将图像拖放到 PR 评论框中(GitHub 没有用于此上传的 API)。告诉他们哪张图像放在哪里。 - 尚未创建 PR: 保留
.ui-diff/comment.md,并在 PR 创建时提供将其放入描述的功能。
6. 收尾
报告返回链接、计数和“值得一看”的项目。如果你自己确定了开发命令、路由、遮罩或动态 ID,请主动提出将它们保存到 .ui-diff.json 中,以便下次运行时一步到位。一旦 PR 被合并或关闭,运行 bash $SKILL/scripts/prune.sh <pr> 从资产分支中删除其图像(先询问是否有人可能还需要该评论)。