Communitygithub.com

UI 差异截图

可视化 Pull Request 的前端变更。自动渲染受影响页面、像素级对比截图、精确测量样式变化(颜色、间距、字体、对比度),并生成面向设计师和评审者的自然语言摘要,将前后对比图发布到 PR 评论或描述中。

UI 差异截图 是什么?

UI 差异截图(ui-diff)是一个专为 AI 代码助手(如 Claude Code、Cursor、Codex)设计的前端 PR 可视化技能。它的核心价值在于将 CSS diff 这种「只能看不能见」的代码变更转化为直观的截图对比,让设计评审者和开发者能够“看见” PR 的实际视觉效果。该技能适用于任何基于本地开发服务器的 Web 应用(React、Next.js、Vue、Nuxt、Svelte、Angular、Astro、原生 HTML 等)。其工作流程包括:自动检测受影响的页面或组件(基于文件变更分析)、在两个 git worktree 中分别启动 base 和 head 版本的开发服务器、使用 Playwright 捕获每个路由在多个视口(桌面、移动)和配色方案(亮色、暗色)下的截图、进行像素级差异分析和计算样式对比,最后生成包含精确测量值(颜色、尺寸、间距、对比度)和视觉问题警告(文字截断、滚动溢出、布局偏移、可访问性问题)的总结报告。报告会以注释或描述形式发布到 PR 上,支持 Storybook 模式、Figma 设计稿对比、手动模式和资产分支发布,确保即使在没有推送权限的 fork 仓库中也能工作。技能强调 AI 的判断力介入:选择哪些页面、理解变更含义、决定发布位置,因此它能处理复杂的动态路由、需要登录保护的页面以及模态状态等场景。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/davidamunga/ui-diff/tree/main/skills/ui-diff

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

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> 从资产分支中删除其图像(先询问是否有人可能还需要该评论)。

相关技能