從色塊 placeholder 開始的漸進式 UI 除錯
核心原則
UI 除錯的最小可驗證單位是「一個有明顯邊界的色塊」。 版型用色塊先驗證 grid / flex / absolute 是否如預期排在該在的位置，確定後再串實際內容。一次組裝完整 UI 在版型錯時 debug 困難 — 顏色、字型、邊距、padding 全部一起出問題、根因混雜難辨。
為什麼色塊比實際內容更適合 debug
商業邏輯
UI 由「位置、尺寸、視覺樣式、互動」四層組成。Debug 時要分層處理 — 一次只解一層、解完再下一層。
色塊把後三層都拿掉、只留「位置與尺寸」 — 看到的就是 layout 規則的純粹結果。實際內容把所有層混在一起、看到的位置可能受字型 advance、line-height、margin collapse 等多重因素影響、難以歸因。
漸進式組裝順序
| 階段 | 內容 | 驗證重點 |
|---|---|---|
| 1 | 色塊（紅 / 藍背景、固定 width / height） | grid / flex / absolute 排對位置嗎？ |
| 2 | 加 placeholder 文字 | 文字尺寸符合預期嗎？換行行為對嗎？ |
| 3 | 加 padding / border / 圓角等視覺樣式 | 視覺樣式不破壞 layout 嗎？ |
| 4 | 換上實際內容 / 接上資料 | 動態內容變動時 layout 還對嗎？ |
| 5 | 加互動（hover / click / focus） | 互動狀態下 layout 還對嗎？ |
每階段獨立驗證、有問題就停在那階段修。
這次任務的實際應用
觀察
要驗證搜尋頁的版型：「左側 filter sidebar + 右側中央內容（H1、search input、results）」。
第一次嘗試：直接把 Pagefind UI 組起來、調 CSS。結果版型錯時不知道是哪層問題 — 是 grid 排序錯？是 sidebar 寬度錯？是 padding 推到位置不對？
判讀
退回最小可驗證單位：把 filter 整個換成一個寫死寬度的紅色色塊：
1<aside class="search-filter-debug">
2 filter 區（先寫死寬度與底色驗證版型）
3</aside>1.search-filter-debug {
2 width: 400px;
3 background: red;
4 min-height: 240px;
5 position: absolute;
6 /* ... */
7}紅色背景一眼看出色塊在哪 — 確認了：
- 色塊在 main 左外側（符合）
- 色塊頂端對齊 H1（符合）
- 寬度 400px、與 main 間距 2rem（符合）
版型驗證後再換上實際 filter UI。
執行的迭代步驟
| 步驟 | 動作 | 驗證 |
|---|---|---|
| 1 | 紅色色塊代替 filter | layout 對嗎？看色塊的位置 |
| 2 | 色塊頂端對齊 results 頂端（用 padding-top） | 對齊基準對嗎？看頂緣連線 |
| 3 | 確認多 viewport 下色塊行為 | 響應式 OK 嗎？拉視窗 |
| 4 | 拿掉色塊、JS 把 pagefind filter 搬進來 | 真實內容套上後位置一致嗎？ |
| 5 | 細部視覺調整（邊框、間距） | 視覺樣式 OK 嗎？ |
每步只驗證一件事、有問題就停。
內在屬性比較：兩種除錯起點
| 起點 | Debug 難度 | 修復速度 | 適用情境 |
|---|---|---|---|
| 一次組裝完整 UI | 高 — 多層問題交織 | 慢 — 不知該改哪層 | UI 簡單、一次到位有把握 |
| 從色塊漸進組裝 | 低 — 每階段問題單純 | 快 — 一次解一個 | 複雜 layout、多元件協作 |
漸進的成本是「多寫一個過渡版本」、收益是「debug 範圍縮到最小」。多元件 layout 永遠選漸進。
色塊的設計要點
1. 顏色明顯、易於辨識
紅色、洋紅、亮藍 — 跟頁面其他元素差異大。debug 完拿掉、不影響正式設計。
2. 邊界清楚
寫死 width / height / min-height、不要讓色塊「自適應」 — 自適應時看不出色塊本身有沒有按預期擺放（可能是它縮成 0 還是真的擺對位置）。
3. 內含可辨識的標籤
1<aside>filter 區（先寫死寬度與底色驗證版型）</aside>文字標明這是什麼、目前是「驗證版型」狀態 — 不會被誤認為正式設計。
4. 拆解成最小可驗證的單位
要驗證「左欄 + 右欄」就用兩個色塊。不要在第一階段就加 filter 內容、search input 等元件 — 那些是後續階段。
設計取捨：UI debug 的起點選擇
四種做法、各自機會成本不同。這個專案選 A（色塊漸進組裝）當預設、其他做法在特定情境合理。
A：色塊 placeholder 漸進組裝（這個專案的預設）
- 機制：先用寫死寬度的彩色色塊代替每個區塊、確認 layout 後再加內容、再加樣式
- 選 A 的理由：每階段只解一個問題、debug 範圍縮到最小
- 適合：複雜 layout、多元件協作、不確定 layout 規則對不對
- 代價：多一個過渡版本、總時間略長（但 debug 時間短得多）
B：一次組裝完整 UI
- 機制：直接把 layout + 內容 + 樣式全部寫好、看結果
- 跟 A 的取捨：B 一次到位（如果一次對）、A 漸進；B 在版型錯時 debug 困難（多層問題交織）
- B 比 A 好的情境：簡單 layout（< 3 元件、無複雜共存）、有 100% 把握一次到位
C：用 wireframe 工具（Figma / Sketch）
- 機制：先在設計工具畫 wireframe、確認設計後再進實作
- 跟 A 的取捨：C 在設計階段確認、A 在實作階段確認；C 適合「設計尚未確定」、A 適合「設計確定但實作有 layout 風險」
- C 比 A 好的情境：設計階段 — 還沒進實作、不確定要做什麼
D：直接用真實內容 debug 版型
- 機制：拿真實 pagefind UI / 文章內容當 debug 對象
- 成本特別高的原因：內容自帶字型 / padding / margin、跟版型問題混在一起、debug 從哪下手都可能錯
- D 是反模式：真實內容適合驗證、不適合 debug — 內容自帶字型 / padding / margin、跟版型問題混在一起、debug 從哪下手都可能錯
判讀徵兆
| 訊號 | 對應的階段問題 | 第一個該嘗試的動作 |
|---|---|---|
| Layout 一試就錯、不知改哪 | 沒做色塊驗證、多層問題交織 | 退回色塊 placeholder、單獨驗證 layout |
| 改 padding 視覺對了、互動後又壞 | 樣式調整跑在 layout 確認之前 | 退回最簡 layout、確認穩定後再加樣式 |
| 真實內容套上後位置變了 | 內容尺寸跟色塊預設不一樣 | 量真實內容尺寸、回頭調 layout 規則或固定容器尺寸 |
| Debug 時間遠超估算 | 起點選錯（從複雜 UI 開始） | 退到色塊重來、會比繼續調快 |
核心原則：UI 除錯的速度跟「起點的簡單度」成正比。從色塊出發、永遠比從完整 UI 出發快。
跟 #68 驗收的時間軸 的關係：placeholder 漸進是 Checkpoint 2「開發中」的具體做法 — 每階段只引入一個變數、邏輯錯誤跟視覺錯誤能即時 catch。跳階段（直接寫真實內容 + 完整樣式）= 把開發中 checkpoint collapse 成單次驗收、漏掉的失敗會推到 ship 前 / ship 後。