Layout Witness
讓頁面更容易掃視和使用。為相關元素建立清晰的群組，保持重複元件的恆常性，並在內容和視窗大小變化時維持這些關係。利用輔助線來決定編輯時需要修正的項目。
在現有的開發分頁上使用 Chrome 擴充功能。搭配其本地代理連線，即可在終端機中以 JSON 格式控制輔助線並讀取頁面與元素測量結果。也可選擇使用 Playwright CLI 在全新的瀏覽器環境中進行無人值守的擷取。
連接到現有分頁
從 chrome://extensions 載入完整的 layout-witness 技能目錄作為未封裝擴充功能。使用 Chrome 116 或更新版本。
- 設定
WITNESS_DIR為已安裝的技能目錄。執行(cd "$WITNESS_DIR" && npm ci --omit=dev)一次，然後在持續執行的終端機中啟動node "$WITNESS_DIR/scripts/agent.mjs" serve。 - 在開發分頁的工具列上開啟 Layout Witness。在 Agent access 下，貼上終端機輸出的配對 URL，然後選擇 Connect agent。這會授權該分頁。如果存取權限遺失，請要求使用者配對該分頁一次。
- 在同一台機器的任何終端機中使用 CLI。在編輯期間保持本地伺服器運作。
node "$WITNESS_DIR/scripts/agent.mjs" start
node "$WITNESS_DIR/scripts/agent.mjs" select 'header [aria-label="Search"]'
node "$WITNESS_DIR/scripts/agent.mjs" measure
# 編輯專案的 CSS 並等待開發伺服器套用變更。
node "$WITNESS_DIR/scripts/agent.mjs" measure
measure 會列印頁面區域、檢查結果，以及當下選取的元素（如果有的話）。該元素可包含其渲染區塊、外邊距、邊框、內邊距、網格與間隙值、排版（包括可測量的視口基線 Y），以及 SVG 幾何資訊。使用一個能匹配單一可見元素的選擇器。在編輯時保持選取狀態，並在瀏覽器套用變更後再次讀取其 JSON。
使用 status 檢查連線，clear 僅移除元素輔助線，pick 進行手動點擊選取，import <rules.json> 載入專案規則，defaults 恢復預設規則。使用 stop 移除兩條輔助線並清除選取以進行乾淨的檢視。使用 start 和 select 恢復。使用 disconnect 在完成時斷開連線，使分頁停止接受指令。相同來源的重新載入可以在相同路由上恢復輔助線和選取。不同的來源或分頁關閉則會結束配對。
對於手動檢視，請使用工具列彈出視窗中的 Start guides、Inspect element 和 Stop guides。當您想要儲存副本時，可以使用 Download report。
使用輔助線進行工作
- 設定預期佈局。 讀取專案的佈局和元件規則，然後檢查現有的 token 和可接受的同層元件。記下與任務相關的關係，例如共享的閱讀邊緣、導覽群組之間的間隙，或按鈕的行內內邊距。在新的頁面上，從簡報中選擇這些關係並記錄您的假設。將擴充功能的預設網格視為探索性指南。
- 從頁面檢查到元素。 在編輯前啟動輔助線。擷取渲染的起點，並選取擁有問題的元素。當標籤過於擁擠時，使用報告獲取精確測量值。對於新頁面，在 shell 渲染完成後啟動輔助線，並在新增區塊和控件時保持輔助線開啟。
- 在選取保持活躍時編輯原始碼。 將測量值與預期值進行比較。修正擁有該關係的 CSS 或共享元件。當開發伺服器套用編輯時，在選擇另一個元素之前，先檢查同一個元素的輔助線和測量值。如果重新載入取代了元素，請確認恢復的選取仍指向預期的控件。記錄實際值、預期值和測量結果。
- 檢視乾淨的渲染結果。 首先擷取修正後的輔助線，然後關閉輔助線並檢查實際頁面。檢查群組、層級、對齊、換行以及在佈局變更的寬度下可見的焦點。包含長標籤或翻譯後的內容，以及相關的展開、折疊或密集狀態。回報剩餘問題以及您檢查的寬度和狀態。
| 範圍 | 檢查內容 |
|---|---|
| 頁面外殼 | 使用頁面輔助線檢查共享的閱讀邊緣、外側邊距，以及頁首、側邊欄、主要區域和頁尾在斷點處的適應方式。在乾淨的渲染中，檢查重複的動作是否容易找到，以及主要任務是否獲得最多的視覺強調。 |
| 群組和重複元件 | 使用局部網格軌道檢查區域內的對齊和跨度。分別比較群組間的空間與每個元件的內邊距和間隙。保持相關項目在視覺上分組，並在群組堆疊時驗證閱讀順序。 |
| 個別元素 | 選取控件以檢查其區塊、內邊距以及圖示到標籤的間隙。比較需要對齊的標籤之間的行高和基線。在同一系列中檢查圖示大小和筆劃，然後在渲染大小下判斷視覺平衡。將其互動目標與字形分開測量。 |
對於擁擠的側邊欄，首先檢查相關連結是否形成一個群組，相鄰區塊是否有清晰的間隙。然後選取一個行，並將其嵌入距離和圖示到標籤的間隙與等效的行進行比較。如果共享元件要求每側 16 px，而輔助線顯示一側為 8 px，則恢復 token 並重新測量相同的選取。關閉輔助線以檢查展開和折疊的側邊欄的實際狀況。
對於明確的期望值，例如 token 值、命名邊緣之間的對齊以及溢出，請使用嚴格檢查。在渲染的頁面中判斷層級和視覺平衡。使用專案的字體尺度來決定基線是否應對齊。
設計參考
- Adobe Spectrum 2 解釋了鄰近性如何表示關係、間距如何因範圍而異，以及如何在系列中檢查圖示間距和筆劃。間距 · 圖示基礎
- Figma 展示了如何為頁面、巢狀區域、元件內邊距和文字基線選擇輔助線。佈局網格
- Linear 的設計更新是關於在高密度工作區中可預測的頁首操作和視覺層級的案例研究。設計更新
當無障礙納入範圍時，請使用 WCAG 檢查重新流動、使用者文字間距覆寫以及實際指標目標，包括適用的例外情況。重新流動 · 文字間距 · 目標大小
可選的無人值守擷取
當自動化需要在不同視口寬度或主題下使用全新的瀏覽器環境時，請使用 CLI。它需要 Node.js 22+ 和 Playwright Chromium。將 WITNESS_DIR 設定為已安裝的技能目錄，並在其中安裝其依賴項：
(cd "$WITNESS_DIR" && npm ci && npx --no-install playwright install chromium)
從專案目錄執行 CLI，以便其配置和輸出路徑在該目錄下解析：
node "$WITNESS_DIR/scripts/witness.mjs" capture http://localhost:3000 \
--config ./layout-witness.json --width 1440 --width 390 --strict \
--out .layout-witness/review
讀取生成的覆蓋層和 JSON 報告。擷取模式會為每個寬度和主題開啟一個新頁面。請參閱規則參考以了解區域和檢查定義。使用 watch 進行互動式 CLI 工作流程。