UI 潤飾（UI polish）
一個畫面即使組織良好，仍可能給人未完成的感受：兩欄欄位差了 17px 沒對齊、390px 手機螢幕上出現 88px 的方框、每個欄位後面拖著單位文字、某個連結拇指按不到。使用者一眼就能察覺，但模型在審視截圖時幾乎看不到這些問題。這項技能先測量、再判斷，並且只在測量結果確認缺陷已修正時才認定完成。
輸入
只問缺少的資訊。
- 目標（Target）。 一個 URL，或一個 HTML 檔案，或儲存庫中的元件加上它渲染的 URL。你必須能夠讓它渲染；如果你無法渲染任何內容，請直接說明，並只依據評分表處理，將所有可測量的檢查標記為「未測量」。
- 範圍（Scope）（可選）。一個 CSS 選擇器，指定要潤飾的頁面部分，例如表單或
main。預設值：main，否則為body。 - 參考（Reference）（可選）。使用者認為較好的畫面（URL、檔案或螢幕截圖）。同樣對它進行測量，並以其視覺方向為參考；切勿複製其品牌、內容或主張。
工作流程
1. 測量當前畫面
執行整合腳本（需要 Node 和附帶 Chromium 的 Playwright；如果專案中尚未安裝，請執行 npm i -D playwright && npx playwright install chromium）：
node <skill-dir>/scripts/measure.cjs <file-or-url> --out ui-polish/before [--scope "<selector>"] [--primary "<selector>"] [--hide "<selector>,..."] [--profile form|content]
- 它會在手機（390×844）和桌面（1366×900）下渲染（錯誤存在時退出碼為 1，使用錯誤時為 2，執行本身失敗時為 3），將
measure.json寫入--out指定的目錄（相對於目前目錄解析），每個視角產生兩張截圖：<viewport>.png（第一畫面）和<viewport>-scope.png（整個範圍，包括摺頁以下的內容），並輸出每個發現的問題及其選擇器。共用同一個原因的元件視為一個發現項目，附上計數與範例選擇器；在手機和桌面上相同的發現項目只會輸出一次，並在viewports中列出兩個視角（在依視角過濾合併後的發現項目時，請使用viewports，而非viewport）。 - 腳本預設關閉，以測量靜態版面；對需要 JavaScript 才能渲染的頁面，請加上
--js。--offline會阻斷除了目標頁面之外的所有網路請求（隔離模式）；--assets-only則會允許遠端字型、樣式表和圖片載入，適用於需要保留字型的本地複本，並且會連線到這些主機。 --hide會在測量和截圖前將指定元素（如 cookie 橫幅或聊天啟動按鈕）設為display: none，避免它們遮蓋截圖或產生多餘的發現項目。如果--hide指定的選擇器沒有匹配到任何元素，會輸出警告。--profile content適用於文章或其他長篇內容頁面：它會跳過專為表單步驟設計的檢查項目（type-scale、action-distance、action-below-fold、dead-space）。預設值為form。- 若要一次測量多個目標（
measure.cjs <page1> <page2> ... --out dir），每個目標會存到dir/<slug>/目錄下，而dir/summary.json會將跨頁面重複的發現項目合併為一行，並列出涉及的頁面；共用元件只需修正一次。支援逐頁比較（--compare before/<slug>/measure.json after/<slug>/measure.json）。 - 檢查項目、閾值以及常見的修正方式，請參閱
reference/checks.md。錯誤（Errors）會導致執行失敗；警告（Warnings）則必須修正或提出理由。 - 理由只需陳述一次，不需每次執行都重複：在目前目錄下的
ui-polish.config.json檔案（或使用--config <file>）中列出已接受的決策，例如{ "ignore": [{ "check": "text-size", "selector": ".eyebrow", "reason": "品牌標籤" }] }。符合條件的發現項目會移至accepted區段，附上理由，並在專屬區域中顯示，且不影響退出碼。僅記錄專案擁有者所做的決策；切勿為了通過數字檢查而自行新增。
如果提供了參考畫面，請用相同方式將其測量結果存入 ui-polish/reference。
2. 檢視截圖
開啟截圖（-scope.png 顯示完整範圍），並逐一檢視 reference/rubric.md 中的十個評分項目。產出一個評分表，每個項目一行（第十項的每個子檢查各一行）：通過、未通過或不適用，並說明發現的問題與修正方式。只根據畫面上的內容進行評判。測量結果是評分的佐證，而非取代評分：一個零測量缺陷的畫面仍可能在層級結構、標籤與單位、分組或信任感上失敗，而這些通常是人們最先注意到的缺陷。
3. 規劃修正
列出每個測量發現的項目與每個失敗的評分項目，並附上修正方式，依其影響的元件分組。優先採用能一次解決多個發現項目的結構性修正（例如，在雙欄網格中將標籤置於欄位上方，可同時修正對齊、等寬、欄位填充、標籤位置和無障礙名稱等問題），而非逐項修補。依對使用者影響程度排序。
4. 對原始碼套用修正
編輯真實的原始碼：儲存庫中的元件及其樣式，或 HTML 檔案。規則：
- 保留用途與內容。 相同的問題、輸入與單位、操作、品牌。不要為了通過檢查而移除功能。
- 不要憑空發明。 不要加入畫面上沒有以文字陳述的事實：步驟數、時間、價格、臨床、法律或隱私聲明。即使你從程式碼中推斷出的數值（例如進度條的
aria-valuenow、CSS 寬度、路由名稱）仍屬於未陳述的事實，也必須加上方括號。如果設計需要這類文案，請使用方括號佔位符（例如「問題 [n] / [N]」、「約 [~3] 分鐘」、「[為何詢問：...]」），並列出供專案擁有者填寫。 - 使用現有系統。 重複使用專案的設計語彙、元件與間距尺度；只有在現有值都不適用時才新增。
- 保持功能正常。 每個控制項仍須執行原來的功能（若原本有問題，則須修正）。維持鍵盤焦點可見。
5. 重新測量直到通過
node <skill-dir>/scripts/measure.cjs <file-or-url> --out ui-polish/after [same options]
node <skill-dir>/scripts/measure.cjs --compare ui-polish/before/measure.json ui-polish/after/measure.json
比較步驟也會列出所有新增的文案以供專案擁有者檢視，並且在新增文案中包含未使用方括號括起的數字時失敗（例如「Step 2 of [5]」：其中的 2 從未被陳述過）。
重複步驟 4–5，直到沒有錯誤、所有剩餘的警告都已修正或有合理理由、且所有失敗的評分項目都已修正或有合理理由，最多三輪。每輪都針對新的截圖重新進行評分。零錯誤不代表完成：像 36px 的觸控目標或尾隨標籤這類警告，正是這項技能存在的意義。每輪都要開啟新的截圖：一個檢查項目可能通過，但畫面看起來卻變糟了，這屬於回歸。
6. 報告
- 手機與桌面版本的修正前後截圖。
- 比較輸出：已修正、剩餘（附理由）、新增、以及已接受（附設定檔中的理由）。
- 修正前後的評分表，以及任何仍失敗項目的原因。
- 專案擁有者需要填寫的每個方括號佔位符。
- 任何需要產品決策而非潤飾的事項（請移交給設計審查或專案擁有者）。
注意事項
- 截圖會隱藏幾何問題。 17px 的欄位移位，或 390px 螢幕上的 88px 欄位，對使用者而言一目瞭然，但在縮小的截圖中卻看不見。信賴數字來判斷幾何，信賴你的眼睛來判斷平衡與層級。
- 尾隨單位文字是欄位不對齊的常見原因。 「Feet」與「Stones」寬度不同，導致其後的所有內容都跟著偏移。請將標籤放在欄位上方。
- 大檔案的小編輯要保持小。 當原始碼是大型產生的檔案時，請將表單的標記與樣式作為一個區塊編輯，而不是逐個屬性修補，否則版面永遠不會改變。
- 數字過關就停手是典型失敗。 幾何只是潤飾的一半；另一半是評分表（真正的標題、一個開關而非每個欄位一個連結、敏感問題的理由、方向）。
- 一個設計語彙，多個發現項目。 在每個頁面上重複出現的小字型或觸控目標問題，通常來自一個設計系統的語彙或元件。請在那裡修正，或將專案擁有者的決策記錄在
ui-polish.config.json中，而不是逐頁處理。 - 通過檢查不是目標。 一個焦點明確、有清晰標題、欄位分組恰當、且主要操作按鈕近在咫尺的畫面才是。利用檢查來證明你達成了目標。
由 aictrl.dev 建構。 這項技能傳授工作流程；aictrl 將其操作化——立足於你的待辦事項、團隊標準與程式碼知識圖譜。了解更多 →