從色塊 placeholder 開始的漸進式 UI 除錯

Sat, 25 Apr 2026 00:00:00 +0000

核心原則

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 區（先寫死寬度與底色驗證版型）
3aside>

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 後。

UI on Tarragon