UI 預覽閘門

UI 預覽閘門 是做什麼的？

每一個改變畫面的變更都應經過四個階段。切勿因為變更看似微小就跳過階段；核准者審核的是影像，而非文字描述。

1. 檢查當前狀態
2. 預覽並取得核准（在開始工作前）
3. 實作
4. 驗證結果是否符合已核准的預覽（工作結束後）

例外： 如果是一個不會改變預期畫面的錯誤修正，則可跳過第二階段。但如果使用者仍能看到差異，則必須附上修正前後的對比影像。若顯示的畫面、對話框、工作表或訊息與先前不同，則屬於畫面變更，不適用此例外——即使重複使用了現有元件也不例外。此類變更必須先取得第二階段的核准。

適用時機

• 無需使用者要求即可自動啟用。使用者不應自行指定這項技能。
• 每一輪對話都需檢查，不限於第一輪。原本是支援、研究、審查或錯誤報告的對話，常在中途轉為「如果畫面改成這樣會怎樣？」；從該輪對話起，此技能即適用。
• 對於畫面的「你覺得如何？」、「有什麼想法嗎？」或「看起來會怎樣？」等提問，都視為提案。
• 一旦啟用，在後續對話中持續遵循，直到已核准的變更完成驗證（第四階段），或使用者放棄該變更。
• 僅以散文或案例表格回覆的提案是不完整的。必須在回覆中附上前後對比影像，或說明為何目前無法製作以及預計何時能提供。
• 當 UI 變更正在等待核准或進行中時，進度報告、選項清單或相關提問都必須重新附上其前後對比影像，或提供影像路徑。切勿僅以散文描述已變更的畫面。

技能通常是每輪根據其描述來選取，因此對話中途的回合可能被忽略。位於此檔案旁的 agent-instructions.md 是一條簡短的規則，應加入 AGENTS.md / CLAUDE.md，以便代理人在每一輪重新檢查。

1. 檢查當前狀態

切勿僅憑記憶或猜測提出提案。

• 從正在執行的開發伺服器或構建中擷取真實畫面。預設視口為行動裝置 375px 寬；若變更影響桌面佈局，則需額外擷取桌面版。
• 讀取渲染該畫面的程式碼：頁籤/路由結構、元件、當前文案。
• 以 path/to/file:line 加上擷取內容作為證據。對當前 UI 的每一項主張都應指向至少其中一項。
• 優先使用現有元件、模式和文案。如果需要新的模式，需說明為何現有模式不適用。

使用 scripts/capture.mjs 進行擷取（請參閱腳本），以確保前後對照、預覽和驗證截圖使用相同的視口、縮放比例和資料狀態。

案例盤點（在首次預覽前自動執行）

核准者不應需要詢問「點擊後會怎樣？」或「如果有資料會怎樣？」。在發送任何預覽之前，應根據程式碼和實際應用程式列出變更所觸及的所有案例：

• 變更畫面的狀態： 空白 / 有資料 / 多筆項目（截斷、「顯示全部」）/ 載入中 / 錯誤 / 因方案、角色或權限而鎖定 / 其他配置（單店 vs. 多店、功能標誌）。
• 從新增或變更的控制項進入的每個畫面： 表單、選擇器、對話框、驗證錯誤、取消/返回、確認、成功、失敗。
• 操作完成後： 原始畫面在操作完成後的樣貌（新項目出現、計數器變更），以及如何復原或編輯。
• 顯示相同資料的其他位置： 清單、詳細畫面、歷史記錄、報表、匯出、其他平台（桌面版、Web、LINE、客戶端）。分別標記為「已變更 / 未變更但顯示新資料 / 不受影響」。

在首次預覽時以表格形式發送盤點結果：案例、使用者看到的內容、重複使用的現有元件、以及影像狀態（已附上 / 需要測試資料及其準備方式 / 超出範圍及其原因）。預覽可以分批發送，但第一則訊息必須包含完整的盤點結果，且核准其中一張影像並不代表未顯示的案例也已通過核准。對於未決的決策，請提出合理的預設值，而不僅僅是列出問題。

2. 預覽並取得核准

在撰寫實作程式碼之前，向核准者展示一張雙欄並排影像和一份簡短摘要，然後等待明確的確認。

影像規則：

• 左側為「變更前」，右側為「變更後」，整合為一張圖片。
• 框選所有變更區域：變更前使用紅色框，變更後使用綠色框。
• 配對框：每一項變更在兩側的對應位置都需有框。對於新增項目，在變更前圖的插入點使用細線標記（"pad": 0，小 h）；對於移除項目，在變更後圖的空白處標記。切勿框選不相關的相鄰元素（例如用下方的列來代替缺失的元素）。
• 框選座標來自 capture.mjs --selector 的輸出（或當狀態需要互動時（例如輸入後開啟的對話框），使用 Playwright 在 e2e 測試中測量的元素矩形），而非憑目測。在發送組合後的影像前，應仔細檢查每個框是否確實對準目標。
• 兩側使用相同的視口、滾動位置和範例資料。
• 若畫面會因狀態（有資料/無資料、錯誤、空白、角色或配置）而分支，則需為變更觸及的每一種狀態提供一組變更前/變更後對比影像。未顯示的狀態視為未核准。每種狀態製作一張影像，切勿將多組對比放入同一張圖片。
• 僅透過暫存（暫時修改程式碼以開啟畫面）才能到達的真實畫面，必須在規格中標記 "staged"，以便影像上顯示該資訊。
• 發送前檢查：compose.mjs 會拒絕違反這些規則的規格，並列印出檢查清單。開啟影像，逐一回答每個項目，並將答案寫在訊息中（請參閱範本）。若某項目失敗，請修正並重新組合；切勿以文字解釋失敗的項目。
• 遵守以下的影像政策。

影像政策

使用者或專案可以決定是否允許使用模擬圖。請在請求或專案說明文件（AGENTS.md、CLAUDE.md、貢獻文件）中尋找相關設定。若無明確說明，則使用 real-only。切勿因為擷取困難而自行切換為 mockup-allowed；應先詢問。

• real-only（預設）：兩側均為實際執行中應用程式的全螢幕截圖。在原型分支或功能標誌後方構建變更後的畫面並進行擷取。嚴禁使用裁切或拼貼的片段、根據程式碼或手動重新繪製的模擬圖（包括生成的圖片）、將一整列裁半的截圖，或與實際應用程式顯示內容不同的假資料。
• mockup-allowed：僅在使用者或專案明確允許時，變更後的畫面才可使用模擬圖。變更前的畫面仍須為真實截圖。每個模擬圖面板必須在組合規格中標記 "mockup": true，以便影像上顯示該資訊，並在核准請求中說明。模擬圖絕不能作為第四階段的驗證證據：驗證時必須使用實作後畫面的真實截圖。

較嚴格的專案規則優先於較寬鬆的使用者偏好；若兩者衝突，應指出衝突點並遵循專案規則。

摘要（使用 references/templates.md）：

• 哪裡： 變更出現在哪個畫面/頁籤及頁面上的具體位置
• 什麼變得可能： 針對不同使用者類型（例如管理員、客戶）
• 什麼不變： 以及受影響的平台/表面

核准的範圍僅限於所展示的內容。超出此範圍的任何內容都需要新的預覽。

3. 實作

依據已核准的預覽進行建構。如果實作過程被迫產生可見的偏差（佈局、文案、行為、新平台影響），請停止並返回第二階段，提供更新後的預覽，而非直接交付有差異的結果。

這包括因程式碼審查而進行的細微文案編輯和修正：如果修正改變了使用者看到的內容（超出已核准的影像範圍），請先停止並取得新的預覽核准。事後以文字報告並不計入。

4. 與已核准的預覽進行驗證

切勿僅依據程式碼差異就報告完成。

1. 使用與預覽時相同的擷取設定和狀態，重新擷取實作後的畫面。
2. 組合驗證影像：已核准的預覽 | 實際結果。框選每一項承諾的變更；所有與已核准預覽的差異均以琥珀色框選，即使是微小的位移。僅以文字描述的差異不算驗證通過。
3. 逐項檢查：
   • 每一項承諾的變更都存在且與預覽相符；
   • 所有列為「不變更」的項目確實未改變；
   • 框選區域之外的任何內容都沒有移動、換行或溢出；
   • 已變更的互動在實際操作時確實有效，而不僅僅是渲染出來。通過的 e2e 測試僅確認行為，不能取代對每個看似未改變狀態的影像檢查。
4. 決定：
   • 相符： 連同驗證影像和檢查結果一併報告。
   • 輕微偏差（仍在核准意圖內）： 修正、重新擷取、重新檢查。
   • 偏差改變了已核准的內容： 報告偏差並重新取得核准。

將任何無法驗證的項目（例如某個平台、裝置、真實資料）分別列出，而非直接視為完成。

腳本

這兩個腳本都需要 Node 18+ 和 Playwright（npm i -D playwright && npx playwright install chromium）。設定 PLAYWRIGHT_MODULE 環境變數為模組路徑，以重複使用現有的安裝。

擷取畫面並取得元素的框選座標：

node scripts/capture.mjs --url http://localhost:3000/menu --out before.png \
  --width 375 --selector ".category-tabs" --selector ".menu-list"

它會以 CSS 像素為單位輸出選擇器的矩形範圍，可直接貼上作為 boxes。

從 JSON 規格組合面板：

node scripts/compose.mjs spec.json

規格格式、色調和驗證佈局請參閱 references/compose-spec.md。