Communitygithub.com

ui-diff

視覺化呈現 Pull Request 的前端變更。渲染網頁應用在基準提交與頭提交的畫面,進行像素比對,測量精確的樣式變化(顏色、間距、字型、對比),為設計師與審查者生成白話摘要,並將前後對比圖片發佈至 PR 評論或描述中。

ui-diff 是什麼?

ui-diff 是一個專為前端開發者與設計審查流程設計的 AI 技能,能自動化擷取網頁應用在 Pull Request 前後的視覺差異。它支援 React、Next.js、Vue、Nuxt、Svelte、Angular、Astro 及純 HTML 等主流框架,只需專案能以本地開發伺服器啟動即可使用。技能包含智慧路由選擇(自動比對變更檔案對應的頁面或 Storybook 元件)、多裝置與多色彩模式渲染(桌面、手機、明暗主題)、像素級差異比對與計算樣式變更測量,並產出結構化摘要報告,特別標註可能問題(如文字截斷、橫向捲動、重疊、手機觸控目標過小、WCAG 對比度失敗等)。 使用流程分為六個步驟:取得 PR 脈絡、選擇要檢查的頁面(透過內建腳本分析變更檔案與路由對應)、執行渲染與比對、讀取結果並撰寫摘要(結合測量數據與截圖檢視)、發布至 PR(支援評論或描述模式,自動上傳圖片至 assets 分支),最後提供總結與設定檔儲存功能。關鍵設計在於 AI 負責需要判斷的部分(頁面選擇、變更意義、發布位置),而機械化工作由單一腳本完成,降低重複勞動。支援圖床自動部署(含私有倉庫)、Storybook 模式、Figma 設計稿比對,並可將常用設定儲存於 `.ui-diff.json` 以實現一鍵執行。

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

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

UI diff

審查者可以讀 CSS diff,但他們看不到實際畫面。這個技能會渲染應用程式在 PR 基準與頭提交的版本,進行比較,然後將前後對比圖片放到 PR 上。旁邊會附上一段簡短的摘要,說明使用者看到的變更,並附上測量數值。

機械化的工作是由單一腳本完成。你的工作是那些需要判斷的部分:要檢查哪些頁面、變更代表什麼意義,以及要發佈到哪裡。

下方的 $SKILL 指的是包含此 SKILL.md 的目錄。請設定一次,例如 SKILL=/path/to/skills/ui-diff。所有內容都會寫入儲存庫根目錄的 .ui-diff/,這個目錄已設為 git 忽略,因此不會有任何追蹤的檔案被變更。

1. 取得背景資訊

gh pr view --json number,url,baseRefName,headRefOid,body 2>/dev/null; git status --short

如果存在,請讀取儲存庫根目錄的 .ui-diff.json。這個檔案可能包含路由、開發指令、遮罩和驗證資訊(請參閱 references/config.md)。

要渲染哪個頭提交 取決於使用者的動作:

  • 發佈到 PR: 透過傳入 --head <headRefOid> 來精確渲染推送的內容。否則未提交的本機編輯內容會出現在號稱顯示 PR 的報告中。如果工作目錄有髒檔案或未推送的提交,請提醒使用者這些變更不會顯示。
  • 檢查進行中的工作("這樣看起來對嗎?"):使用工作目錄(預設值,不加 --head)。報告會標示「+ 未提交變更」。

2. 選擇頁面

node $SKILL/scripts/routes.cjs --base <base> --log   # 如果你稍後會將 --head 傳給 run.sh,請加上 --head <sha>

它會將變更的檔案對應到路由:頁面檔案、變更佈局下的路由、匯入了變更元件的頁面(會追蹤別名和工作區套件),以及首頁和幾個連結良好的頁面(針對全站樣式)。它會輸出 JSON,其中包含每個路由的理由和信心度、needsExample(無法填入的動態路由),以及 unmatched(無法歸類的 UI 檔案)。請將其視為起始清單,並根據 references/route-mapping.md 進行判斷:刪除差異不支援的低信心度選項,為 needsExample 尋找 ID,並自行安排 unmatched 檔案的位置。如果沒有任何與 UI 相關的變更(所有檔案都 ignored),請告知並停止。不要產生空的報告。

Storybook 專案(有 .storybook/ 資料夾或 storybook 指令):當變更主要是元件時,請使用 run.sh --storybook 對它們的 stories 進行差異比對,而不是頁面;它會自行從變更的檔案中挑選 stories。針對路由、佈局和應用程式層級的樣式,請繼續使用頁面。請參閱 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 "<cmd with {port}>"]

(--auto-routes 會加入 routes.cjs 選取的路由,並記錄原因;當你不需要更正時使用此選項。)

這個腳本會一口氣完成以下動作:

  • 首次使用時安裝工具(Playwright + Chromium 在 ~/.cache/ui-diff 中,大約一分鐘;專案的依賴不會受影響);
  • 在 git worktrees 中籨出基準和頭提交(如果指定了 --head),並將未追蹤的 .env* 檔案複製進去;
  • 當 lockfile 相符時重複使用已安裝的依賴(每個籨出目錄會有各自的建置快取),否則就安裝;
  • 在各自的行程群組中,於空閒埠號啟動兩個開發伺服器。之後只會停止這些伺服器,因此使用者的其他伺服器不會受到影響;
  • 捕捉每個路由 × 視埠的畫面。行動版使用真實裝置模擬(觸控、行動 UA)。動畫會被凍結,框架的開發者疊加層會被隱藏;
  • 對螢幕截圖進行像素差異比對(results.json、全頁與縮放圖片),並執行計算樣式差異(measured.md)。

Storybook 模式(--storybook,或 --stories "button--primary,card--*" 自行選取 story)會啟動 Storybook 而非開發伺服器,記錄它選取了哪些 story 以及原因,並以 story ID 命名結果。如果沒有符合的 story,它會結束並建議 ID。

它會輸出類似 {"changed":2,"added":1,"unchanged":3,...} 的計數。預設值:基準 = PR 的基準分支(否則為預設分支),視埠 = 桌面 1440×900 + iPhone 13,淺色模式。當變更涉及主題、顏色或 token 時,請加上 --schemes light,dark。

如果失敗了,錯誤訊息會指出哪個步驟失敗以及紀錄檔的位置(.ui-diff/server-*.log、install-*.log、capture-*.log)。常見原因為缺少環境變數、開發指令錯誤(請傳入 --dev),或工作目錄中未安裝依賴。修正原因後重新執行。不要跳過其中一邊。

4. 閱讀結果並撰寫摘要

首先閱讀 .ui-diff/report/measured.md。如果它以 可能的問題 開頭,請優先檢查這些問題:文字截斷、橫向捲動、重疊、螢幕外的控制項、過小的行動觸控目標,以及在頭提交新出現的 axe-core 無障礙違規。這些只是啟發式規則,請開啟每個縮放圖片(report/issues/)並自行判斷。將「值得一看」的項目保留給真正有問題的,並刪除或淡化那些看起來是故意的變更。measured.md 的其餘部分包含測量到的事實:跨元素分組的計算樣式變更、尺寸改變的元素、版面位移、文字變更,以及新的 WCAG 對比度失敗。然後使用你擁有的任何檔案或圖片檢視工具開啟縮放圖片(report/zoom/*__after.png 和 __before.png)以及差異疊加層,看看這些事實如何在上下文中呈現。如果你無法檢視圖片,請僅根據 measured.md 撰寫摘要,並說明未檢視螢幕截圖。也請檢查 results.json 中的 warnings:HTTP 錯誤、框架的錯誤疊加層、未捕獲的例外。

有提供 Figma 連結?(或 .ui-diff.json 中的某個路由有 figma 欄位?)請同時將頭提交與設計稿進行比較。請遵循 references/figma.md。

為不會閱讀程式碼的設計師或 PM 撰寫 .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 中沒有的內容(圖片、canvas、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 分支(一個提交,每次發佈時取代),使用一個一次性 clone。圖片隨後可以在 GitHub 上內嵌顯示,包括私有儲存庫中具有讀取權限的任何使用者。
    • 結束碼 3 表示沒有推送權限(通常是來自 fork 的 PR)。請切換到手動模式。
    • 如果它指出儲存庫是公開的,請告知使用者螢幕截圖將會公開。這在使用 storageState 以真實帳號登入時尤其重要。在發佈前取得同意。
  • post.cjs 會取代先前的 ui-diff 評論或描述區塊,而不是疊加新的。描述中的其他內容會保持原樣。
  • 只有在 .ui-diff.json 中有 "requireApproval": true 時(該儲存庫使用設計審查工作流程),才在 comment.cjs 中加入 --approval:它會新增一個「設計已核准」方塊。
  • 手動模式(沒有 assets 分支,或沒有推送權限):執行不帶 --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> 從 assets 分支移除其圖片(如果有人可能還需要其評論,請先詢問)。

相關技能