Report — 開發過程的事後檢討 on Tarragon

在外部組件上加客製功能：以邊界為中心的方法選擇

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

核心原則

客製外部組件的穩定性與「離組件邊界多近」成正比。 組件作者維護組件內部的一致性；客製貼著組件的對外介面（CLI 參數、CSS reset 邊界、CSS layer）做，組件升級不會打到客製。深入組件內部（注入子節點、改 source 行為）的客製則仰賴組件的內部實作，作者不保證下個版本還相容。

這條原則對應到 Pagefind 整合時的三個具體情境，本文逐一拆解。

邊界概念：為什麼用「邊界」看外部組件

這類問題的本質（商業邏輯）

組件 = 一組對外契約 + 內部實作。對外契約是作者保證的東西（CLI 參數、CSS class name、CSS variable hooks），內部實作是達成契約的手段、可能在版本之間變動。

客製貼著對外契約做，等於跟作者站在同一邊；客製動到內部實作，等於跟作者每個版本對抗。

「邊界」這個概念把組件分成「契約面」與「實作面」 — 客製選位置時，依離邊界遠近排序：

客製位置	跨越時的依賴
組件對外介面	介面契約（穩定）
組件 DOM 邊界外	邊界元素的 class / id 名稱（半穩定）
組件 DOM 邊界內	內部 DOM 結構（隨框架渲染週期變動）
組件內部邏輯	source code（升級時必衝突）

這次任務涉及的邊界（CASE）

Pagefind 提供三條值得辨識的邊界：

邊界名稱	介面形式	範圍
索引邊界	`--root-selector` 參數	「組件看到什麼資料」
重置邊界	`.pagefind-ui--reset` class	對 UA 樣式的覆寫範圍
specificity 邊界	svelte hash class（雙寫到 30）	組件 CSS 的權重起點

每條邊界各有對應的客製介面 — 緊貼這些介面比繞道進內部安全得多。

索引邊界：用 root-selector 限縮搜尋範圍

核心定義：Pagefind 的索引流程透過 --root-selector 參數控制「哪些 HTML 進索引」。這是組件預期的客製介面。

這次的觀察

theme 的 site header 包含

`{{ .Site.Title }}`

，每一頁 DOM 上的第一個 h1 都是站名「Tarragon」。Pagefind 預設取頁面第一個 h1 當搜尋結果 title — 結果所有結果都顯示「Tarragon」。

判讀

第一個 h1 是站名而非文章名 — 索引「看到」的範圍跟我們以為的不同。要修的不是 theme（影響其他頁面），是 Pagefind 的 input 範圍。

執行

1npx -y pagefind --site public --root-selector main

內才包含文章 h1；site header 在直接子節點、不在

內，自然被排除。

完成標準：每一筆結果的 title 顯示文章 h1，而非站名。

重置邊界：在落腳處重建 UA 樣式

核心定義：CSS reset 的有效範圍與 ancestor class 綁定。元素換位置就換 reset context — 這是 CSS 的基本機制，不是 bug。

這次的觀察

Filter UI（.pagefind-ui__filter-panel，本質是

）需要從 .pagefind-ui 搬到外部 aside（左側 sidebar）。搬完後 fieldset 的瀏覽器預設邊框冒出來。

判讀

.pagefind-ui--reset 用 all: unset 重置所有後代元素的 UA 樣式。fieldset 搬出 .pagefind-ui 後，這個 ancestor 不在了，UA 樣式（包括 fieldset 預設邊框）回到原樣。

執行

在 fieldset 落腳處（aside 內）重新關掉 UA 樣式：

1.search-filter-slot fieldset {
2  border: 0;
3  padding: 0;
4  margin: 0;
5}

完成標準：fieldset 在新位置看起來跟在 .pagefind-ui 內一樣 — 沒有多餘邊框。

specificity 邊界：跳出線性比較戰場

核心定義：當組件透過 hash class 把 specificity 拉高到一般客製寫法蓋不過時，邊界落在 CSS 樣式分層機制 — 不在個別 selector 數字。

這次的觀察

Pagefind 透過 svelte 把 class name 加 hash 重複寫進 selector（.x.svelte-y.svelte-y），把 specificity 從 10 提升到 30。一般客製 CSS specificity 10-20、蓋不過去。

判讀

Specificity 是線性數字比較 — 跟組件作者比 specificity 是無贏的軍備競賽。要真正解這類覆寫戰、需要跳出「線性比較」這個維度本身。

執行

具體做法（@import url(...) layer(...)）與升級兼容性、其他外部組件的 layer 策略，由 #24 CSS Layers 取代 specificity 戰完整展開。在邊界辨識上、本篇要記住的是：遇到 specificity 30+ 的覆寫戰、不要往 !important / .x.x 雙寫的方向加碼、改去看 layer 維度。

完成標準：所有原本需要 !important 或 .x.x 雙寫的覆寫，可以用單純的 class selector 寫。

客製深度的內在屬性比較

選擇客製位置時，用三個內在屬性比較 — 不用「實作要多久」這類時間維度：

位置	依賴前提	升級風險	可逆性
組件對外介面	介面 stable across 版本	低 — 介面是公開契約	高 — 改一個參數即可還原
DOM 邊界外（class hooks）	邊界元素 class / id 穩定	中 — class 改名才打破	中 — 改選擇器即可
DOM 邊界內	內部 DOM 結構穩定	高 — 框架重繪可能即時打破	低 — 客製跟內部結構深度耦合
內部邏輯（fork / patch）	整個組件 source	最高 — 升級必衝突	最低 — 重新 merge

選擇順序：先試最外層；不夠用再往內推一層。每往內一層、依賴前提增加、升級風險上升、可逆性下降。

設計取捨：客製位置的層次選擇

四種做法、各自機會成本不同。預設選最外層（A）、不夠用才往內推一層。

本篇是 #45 跟外部組件合作的層次抽象原則在「客製位置選擇」這個面向的應用。

A：組件公開介面層（最佳）

機制：用組件提供的 CLI 參數、props、CSS variable hook、event API 客製
選 A 的理由：作者保證跨版本相容、客製跟組件升級無關
適合：能被介面覆蓋的客製需求（多數常見場景）
代價：受介面範圍限制、超出範圍只能往內推

B：鄰接層（class hooks、reset 邊界）（這個專案的次選）

機制：用組件邊界元素的 class / id / data attribute 寫客製 CSS、注意 CSS reset 邊界
跟 A 的取捨：B 介面外但仍貼著組件邊界、A 在介面內；B 在 class 名穩定時 OK、改名就壞
B 比 A 好的情境：組件未提供對應介面、但有穩定的 class 邊界可掛勾

C：邊界內 DOM 操作

機制：JS 改組件內部 DOM 結構 / 節點屬性 / 注入元素
跟 A/B 的取捨：C 直接操控、跟 framework reconciliation 競爭；風險顯著上升
C 才合理的情境：A/B 都無法達成、且能容忍每次升級重做（#13 的安全規則必看）

D：Fork / patch 組件 source

機制：fork 整個組件、改 source code、自家維護版本
成本特別高的原因：每次升級都要 merge upstream、客製永久綁在 fork
D 才合理的情境：客製需求超過所有其他選項、且願意承擔 fork 維護成本

判讀徵兆

下次遇到組件整合任務、看到這些訊號就走「找邊界」的路：

訊號	對應邊界類型	第一個該嘗試的動作
組件抓到的資料超過你想要的範圍	索引邊界	找組件的 `root` / `scope` / `selector` 參數
同一段 CSS 在不同位置表現不一致	重置邊界	比對兩個位置的 ancestor class、看 reset 是否還在
`!important` 寫了還是沒蓋過	specificity 邊界	看組件 CSS 是否用 hash class 提升 specificity；考慮 CSS Layers
組件渲染後客製 UI 消失	DOM 結構邊界	把客製 UI 搬出組件、用 CSS 控制視覺位置
組件升級後客製失效	內部邏輯邊界	把客製重寫到組件介面層

使用順序：訊號出現 → 對應邊界 → 嘗試該邊界提供的介面 → 介面不夠用、才考慮往內推一層。

跨 viewport 雙模式 UI 的物理空間預算

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

核心原則

雙模式 UI 的 breakpoint 是「物理空間預算的結果」、不是「設計選擇」。 把每個元件的固有尺寸與 gap 加總、得到「兩種模式各自能存活的最小 viewport」 — breakpoint 從這個數字往上取一個安全餘裕。憑感覺取（768、1024）會在中間過渡區看到元件擠壓、消失或溢出。

本篇焦點：breakpoint 數字怎麼推算。

stateful UI 怎麼跨兩個 slot 共用同一份節點由 #54 跨 slot 同節點搬遷 pattern 處理（兩議題機制不同：本篇是數字計算、#54 是 state 一致性）

breakpoint 從元件預算推算

商業邏輯

Responsive UI 的本質是「同一份內容、在不同寬度有不同的呈現方式」。每種模式（mobile / tablet / desktop）對應一個 layout、每個 layout 有自己的最小可生存寬度 — 這是元件尺寸與 gap 的加總、不是任意選擇。

當 breakpoint 取得比實際所需大、模式切換點與「真正放得下」的點不一致、使用者在過渡區看到擠壓、溢出、或元件神秘消失。

預算推算的步驟

步驟	動作
1	列出該模式下所有可見元件的固有寬度
2	列出元件之間的 gap 與 container 的 padding
3	加總得到「該模式所需的最小 viewport」
4	breakpoint = 最小 viewport + 安全餘裕（避免邊界情況閃爍）

這次任務的實際預算

觀察

搜尋頁的 desktop layout 包含：

main 內容欄寬度 = 70ch ≈ 720px（theme 預設）
filter sidebar 寬度 = 400px（自訂）
main 與 filter 之間 gap = 32px
body 左右 padding 各 64px = 128px

判讀

把 filter 放在 main 左外側、main 維持置中時、所需最小 viewport：

1最小 viewport ≈ main + 2 × (filter + gap) + body padding
2             = 720 + 2 × (400 + 32) + 128
3             = 1712px

但這是「左右對稱都放下」的條件。若允許 filter 溢出 body padding（仍在 viewport 內可見）、條件放寬為：

1最小 viewport ≈ main + filter + gap + body padding
2             = 720 + 400 + 32 + 128
3             = 1280px

選 1280 為下限、加餘裕後取 1400px。

執行

1@media (min-width: 1400px) {
2  .search-filter-slot { display: block; /* 桌面寬模式 */ }
3}

下方寬度時 filter 顯示在 pagefind 原生位置（drawer 內、結果上方）、由 pagefind 自己處理。

設計取捨：餘裕的取法

預算算出最小 viewport 後、breakpoint 加多少餘裕？四種做法：

A：加 ~10% 餘裕（這個專案的預設）

機制：1280 + 120 ≈ 1400
選 A 的理由：避免邊界情況閃爍（使用者視窗剛好在 1280 像素時、輕微 resize 會反覆觸發切換）
適合：一般情境
代價：1280-1400 區間其實能放下、但 CSS 仍走 mobile 模式

B：取整到常見裝置寬度

機制：1280 → 1366（MacBook Pro 寬度）或 1440（外接螢幕常見）
跟 A 的取捨：B 對齊裝置生態、A 對齊計算結果；B 對「設計給特定裝置的網站」較合理
B 比 A 好的情境：使用者群明確（公司內部工具、特定裝置網站）

C：完全等於最小值（無餘裕）

機制：breakpoint = 1280
跟 A 的取捨：C 把所有可放下的視窗都納入 desktop 模式、A 留空間給邊界閃爍
C 才合理的情境：實作上有 debounce 處理閃爍、且裝置寬度集中在某個值附近

D：用 container query 取代 viewport breakpoint

機制：CSS Container Queries — 元件根據父容器寬度切換、跟 viewport 解耦
跟 A 的取捨：D 更精準（容器寬度才是元件真正可用的空間）、A 簡單（viewport 是全局觀念）
D 比 A 好的情境：元件可能放在不同寬度的容器內（CMS 系統、可嵌入元件）

不該套用「物理空間預算」的情境

預算法有適用邊界：

情境	為什麼不套用
內容靜態、不依設計尺寸（純文字段落）	內容自然 reflow、不需要 breakpoint
流體 layout（純 % / fr 單位）	元件自動撐滿可用空間、無「最小寬度」概念
完全 mobile-first 設計	沒有「desktop 模式」這個分支
元件尺寸 runtime 才知道	用 ResizeObserver 動態調整、不是 breakpoint

核心判準：兩種模式之間有「明確的視覺結構切換」嗎？是 → 用預算法；否 → 用流體 layout 或動態量測。

跟其他原則的關係

抽象層原則	關係
#44 SSoT	breakpoint 數字是 fact、CSS 變數住址唯一才能集中管理
#7 量測值缺一不可	預算的每個分量都要有明確來源（寫死 / 量測）、不能估算

判讀徵兆

訊號	可能的根因	第一個該檢查的事
中間寬度時 UI 元件擠壓或重疊	breakpoint 比實際所需小	算物理空間預算、確認 breakpoint 對應的最小 viewport
元件在某些寬度下消失但 CSS `display` 是 `block`	元件被 absolute 定位推出 viewport	檢查 absolute 元件相對 viewport 的座標、是否為負
Breakpoint 取常見值（768 / 1024）就壞	那些值跟你的元件尺寸無關	重算預算、不要用「常見」值
Resize 過 breakpoint 時 layout 跳動	沒加餘裕、邊界震盪	加 10% 餘裕避開閃爍區

順序：看到擠壓或消失先量空間、不要立刻調 breakpoint 數字。數字背後有計算才不會反覆試錯。

視覺對齊用單一真實來源

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

核心原則

多個元素要對齊，每個元素的尺寸都需要「來源明確的數字」 — 寫死的 token 或 runtime 量測寫回變數，二選一不要混搭。 任何一個值含糊（猜的、估的、依字型自然渲染的），整條對齊基準就靠不住、修一處要找十處跟著改。

為什麼對齊需要單一來源

商業邏輯

對齊問題本質是線性方程組：每個參與對齊的元素貢獻一個未知數，要解出對齊的 padding / margin / position 等變數，所有未知數都要有確定值。任一個未知數憑感覺給，整組無解。

CSS 變數提供「一處定義、多處引用」的單一來源 — 改 token 只動一個值、所有引用點自動跟上。

兩種值來源、各用對應的定義方法

值的性質	確定方式	例子
設計可決定的固定值	CSS 變數寫死	H1 height、icon size
Runtime 依字型 / 內容變動	ResizeObserver 量測寫回 CSS 變數	多行文字區塊高度、圖片自適應高度

混搭的後果：寫死值跟實際渲染不一致時，對齊只在某些字型 / 螢幕 / 瀏覽器下成立、其他情境壞掉、且難以重現。

這次任務的實際應用

觀察

搜尋頁有四處要共用同一組視覺 token：

元素	為什麼需要這個值
H1「搜尋」	自身 height
Pagefind search input	自身 height
Filter sidebar `padding-top`	對齊到 results 頂端
Drawer `margin-top`	為 scope UI 讓出空間

判讀

H1 與 input 的 height 是設計可決定的固定值 — 用 CSS 變數寫死。Scope UI 的 height 受字型 / 換行影響、不可預測 — 用 ResizeObserver 量測寫回。

執行：CSS 變數定義

1body.page-search {
2 --search-title-h: 64px; /* 設計決定 */
3 --search-form-h: 68px; /* pagefind input 64 + border 4，鎖定 scale=1.0 */
4 --search-gap: 20px; /* drawer margin-top */
5 /* --search-scope-h 由 JS 量測寫入 :root */
6}

執行：JS 量測寫回

1function syncScopeHeight() {
2 var h = scopeEl.offsetHeight || 56;
3 document.documentElement.style.setProperty('--search-scope-h', h + 'px');
4}
5syncScopeHeight();
6new ResizeObserver(syncScopeHeight).observe(scopeEl);

執行：多處引用

1.search-title { height: var(--search-title-h); }
2.search-shell .pagefind-ui__drawer { margin-top: calc(var(--search-scope-h) + 8px); }
3.search-filter-slot {
4 padding-top: calc(
5 var(--search-title-h) + var(--search-form-h)
6 + var(--search-scope-h) + 8px + var(--search-gap)
7 );
8}

對齊問題的兩種失敗模式

失敗模式	表現	根因
寫死值與實際渲染不一致	字型變動或 scale 改變後對不齊	沒控制渲染參數（如 pagefind scale）
用估算值代替量測	邊界情境（短/長文字、特殊字型）壞掉	把不可預測的值當固定值處理

兩者共通的修法是：確認每個值的性質、按性質選來源。

鎖定渲染參數讓寫死值生效

當值「理論上可預測」但需要強制條件時，鎖定渲染參數。

核心定義：Pagefind input 高度 = 64px × --pagefind-ui-scale。把 scale 設成 1.0、input 自然渲染為 64px、加 border 4px 共 68px、剛好等於我們的 --search-form-h。

1.search-shell { --pagefind-ui-scale: 1.0; }

把組件提供的 scale 變數拉進自家設計系統 — 組件配合我們、不是我們配合組件。

設計取捨：對齊基準的值來源策略

四種做法、各自機會成本不同。這個專案選 A（CSS 變數寫死 + var 引用）當固定值預設、B（ResizeObserver 量測寫回變數）當 runtime 值預設、其他做法是反模式。

本篇是 #44 SSoT 抽象原則在「對齊基準」這個面向的應用。

A：CSS 變數寫死 + var() 引用（這個專案對固定值的預設）

機制：body.page-search { --search-title-h: 64px }、其他地方用 var(--search-title-h) 引用
選 A 的理由：定義住址唯一、改 token 自動跟上、無 runtime 開銷
適合：設計可決定的固定值（H1 height、icon size、間距）
代價：值不能跟 runtime 內容變動 — 字型大幅變化時 layout 可能不適配

B：ResizeObserver 量測寫回變數（這個專案對 runtime 值的預設）

機制：JS 量測元素實際渲染高度、setProperty('--search-scope-h', ...) 寫回變數
跟 A 的取捨：B 自動跟著實際渲染走、A 假設渲染條件穩定；B 多 JS 一層、A 純 CSS
B 比 A 好的情境：值受字型 / 換行 / 內容動態影響、無法 build time 預測

C：複製 magic number 在多處

機制：padding-top: 152px 在多個 selector 直接寫死
跟 A 的取捨：C 寫法直接、不用變數系統；但改一處要找全部、漏改一個就壞
C 是反模式：magic number 是「未來 debug 的潛在炸彈」（#44 SSoT） — 改一處要找全部、漏改一個就壞

D：估算值（不寫變數、不量測）

機制：執行者依感覺寫「padding-top: 152px、應該對齊」
成本特別高的原因：估值對 = 巧合、估值錯 = 看起來對但 +/- 幾 px、後者更糟（錯誤被視覺接受、不會被發現）
D 是反模式：任何寫死值都該標明來源（fact / 鎖定條件 / 量測）— 估值對 = 巧合、估值錯 = 看起來對但實際 +/- 幾 px、ship 後在邊界情境暴露

判讀徵兆

訊號	可能的根因	第一個該檢查的事
改一個 CSS 數字、要去 N 個地方跟著改	缺少單一來源	找出複製的 magic number、提成 CSS 變數
設計稿對齊但實作對不齊	把可變值當固定值	量測該元素的真實 height、決定改用 ResizeObserver
字型變動或 dark mode 後對齊壞掉	寫死值依賴某個沒鎖定的渲染參數	找出該渲染參數、用 CSS 變數鎖定
對齊「大部分時候對」、邊界 case 壞掉	沒處理動態高度	把該值用 ResizeObserver 量測寫回

核心原則：對齊不是視覺問題，是「每個參與元素是否有確定尺寸」的問題。任何一個值不確定、整組對齊就脆弱。

拓樸理解先行於 CSS 規則

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

核心原則

CSS 是基於 DOM tree 的規則系統 — 不知道 tree 的真實結構，寫的 CSS 規則無法生效。 看 class name 的命名規則（如 __form、__drawer 看起來像 sibling）容易推錯層級；寫 CSS 之前用工具直接讀 live DOM tree、確認哪些是 grid item、哪些是 grid item 內部的子元素。

層級必須從 live DOM 讀

商業邏輯

CSS class name 是「用途標記」、不是「結構描述」。.parent__child 這種 BEM 風格在很多框架裡只是作者方便辨認用途，跟元素之間的 DOM parent-child 關係無對應。

當作者在 wrapper 裡又加一層 wrapper，class name 不一定改 — 同一個 class name 在不同框架版本可能對應不同的 DOM 巢狀。

唯一能確定 DOM 層級的方法是讀 live DOM。

看 DOM 的工具選擇

工具	適用情境	限制
瀏覽器 DevTools Elements 面板	手動探索、單次確認	截圖溝通慢、不能寫成測試
`playwright browser_evaluate`	程式化讀 parent chain、computed style、bounding rect	需要 server 跑著
框架原始碼（svelte template、JSX）	確認靜態 DOM 結構	動態渲染情境看不到

優先用 playwright — 同一段 query 可以重複跑、結果可以寫進測試。

這次任務的拓樸誤判

觀察

要把 search scope UI 放在「搜尋輸入框與結果之間」。基於 class name 推測 DOM 結構：

1.pagefind-ui
2├── .pagefind-ui__form        ← 搜尋輸入框
3└── .pagefind-ui__drawer      ← 結果（與 filter）

Class name __form 與 __drawer 都用 __ 前綴、並列在 .pagefind-ui 下、看起來是 sibling。

判讀

依此假設寫 CSS Grid：把 .pagefind-ui 設為 grid、用 display: contents 串接、把 form 放 row 2、scope 放 row 3、drawer 放 row 4。

實際渲染後：scope 跑到頁尾。

用 playwright browser_evaluate 讀 live DOM tree：

1const drawer = document.querySelector('.pagefind-ui__drawer');
2let parents = [], el = drawer;
3while (el && el !== document.body) {
4  parents.push(el.tagName + '.' + el.className);
5  el = el.parentElement;
6}

結果：

1DIV.pagefind-ui__drawer
2FORM.pagefind-ui__form        ← drawer 在 form 內！
3DIV.pagefind-ui
4DIV#search

drawer 是 form 的 child、不是 sibling。我們的 grid 規則把 form（含 drawer 全部結果）放在 row 2、scope 放 row 3 — scope 自然跑到所有結果之後。

執行

確認 DOM 後改用「scope absolute 浮在 form 上、drawer 用 margin-top 讓位」的策略 — 不再嘗試把 form 與 drawer 拆到不同 grid row。

內在屬性比較：拓樸推理的可靠性

推理來源	可靠性	適用情境
Live DOM（playwright / DevTools）	最高 — 反映實際渲染	Debug、整合外部組件
框架 source / template	高 — 靜態結構	自家組件、可讀的 source
Class name 命名規則	低 — 命名是慣例、不是契約	僅參考、不依賴
視覺截圖推測	最低 — 看不到 DOM 包裹層	不應作為唯一依據

選擇順序：Live DOM > source > 命名 > 視覺。Class name 與視覺只能形成假設、必須用前兩者驗證。

display: contents 的拓樸限制

當決定用 display: contents 串接讓子元素參與外層 grid，必須注意：contents 只能讓直接子節點上去、不能跨越多層 box。

例：要讓 form 內的 drawer 參與 search-shell 的 grid，需要 form 也設 display: contents。但 form 設 contents 後：

form 自己的 box 消失
依賴 form 為 offset parent 的子元素（如 absolute 定位的 clear button）失去定位基準
form 的 ::before / ::after 偽元素可能不渲染

display: contents 適用條件：中間層 box 沒有自己的視覺責任（背景、邊框、定位、尺寸） — 否則拆開後視覺破壞。

設計取捨：拓樸理解的方法

四種做法、各自機會成本不同。這個專案選 A（讀 live DOM）當預設、其他做法在特定情境合理。

A：讀 live DOM（playwright / DevTools）（這個專案的預設）

機制：用 playwright browser_evaluate 讀 ancestor chain、computed style、bounding rect；或 DevTools Elements 面板手動探索
選 A 的理由：反映實際渲染結果、跨 framework 都對、可寫成測試
適合：debug、整合外部組件、寫第一版 CSS 之前
代價：需要 server 跑著（可用 hugo dev / static server）

B：讀框架 source / template

機制：直接看 svelte / react component 的 template
跟 A 的取捨：B 看靜態結構、A 看 runtime 結構；B 對自家組件夠用、對動態渲染（runtime wrapper / portal）會漏
B 比 A 好的情境：自家組件、template 跟 DOM 1:1 對應、不需要 runtime 確認

C：用 class name 命名規則推測

機制：看 .parent__child 推測 DOM 巢狀
跟 A 的取捨：C 完全不需要工具、A 需要 server；但 C 命名是慣例不是契約、容易錯
C 才合理的情境：初步假設、必須用 A/B 驗證後才能寫 CSS — 不應作為唯一依據

D：視覺截圖推測

機制：看截圖猜 DOM 結構
成本特別高的原因：截圖看不到 wrapper、看不到 display: contents 等不可視結構
D 是反模式：視覺上看起來相同的 DOM 可能完全不同 — 截圖驗收的盲區會在規則寫了不生效時才被發現、debug 成本指數放大

判讀徵兆

訊號	可能的根因	第一個該嘗試的動作
寫好的 CSS 規則完全沒生效	元素根本不在預期的 DOM 位置	用 playwright `browser_evaluate` 讀 ancestor chain
Grid / flex 排序與預期不符	子元素不是直接 grid item	確認 grid container 的 direct children
設了 `display: contents` 後某些定位元素跑掉	那層 box 是 absolute 元素的 offset parent	把該層 box 留下、找其他方式達成 layout
框架重繪後 layout 完全變了	框架增加了 wrapper 元素	重新讀 live DOM、更新 CSS 假設

核心原則：CSS 行為與預期不符 ≥ 1 次，先回去看 DOM tree、不要繼續調 CSS 規則。先看才不會試錯。

客製 UI 留 framework 邊界外、用 CSS 控制視覺位置

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

核心原則

客製 UI 留在 framework 管轄的 DOM 邊界外、用 CSS（absolute、margin spacer、grid）達成想要的視覺位置。 注入 framework 子樹的客製元素會被 reconciliation 清掉、跟渲染週期競爭、行為不可預測。邊界外的客製跟 framework 解耦、命運由我們自己決定。

本篇焦點：客製 UI 該放哪。framework 元件本身需要動（搬節點、改順序、改 attribute）的安全規則由 #13 JS 操作 framework 元件：邊界辨識與安全規則處理。

為什麼 framework 管轄區會清外來節點

Reconciliation 機制

Svelte / React 等框架透過「component tree → DOM tree」的 reconciliation 機制保持 UI 與 state 同步。框架在 patch 時：

比對 component tree 的當前狀態與目標狀態
計算 DOM 需要的最小變動
套用變動到實際 DOM

關鍵是步驟 2：框架只認得自己 create 的節點。外來節點（我們手動 appendChild 進去的）不在它的 component tree 裡、被視為「該節點不該存在」、清掉。

這不是 bug、是 reconciliation 的正常行為 — 框架要保證 DOM 跟 component state 一致、外來節點屬於不一致的部分。

外來節點的命運是不可預測的

不同框架 / 不同 reconciliation 策略對外來節點的處理：

框架	外來節點命運
Svelte	多數情境清掉、視 patch 點而定
React	通常清掉（Virtual DOM diff 時）
Vue	通常清掉、但 v-pre 包裹可保留
Web Components	由 component 內部邏輯決定

「不可預測」本身就是問題 — 即使某次測試沒清、下次升級或 patch 時可能清。設計時不該依賴未明確保證的行為。

這次任務的具體情境

觀察

要把搜尋範圍切換 UI（scope radio group）放在「pagefind 搜尋輸入框與結果之間」 — 視覺上希望它就在 form 與 drawer 中間。

第一次嘗試：JS 把 scope element 用 form.insertAdjacentElement('afterend', scopeEl) 注入 .pagefind-ui 內部。

結果：使用者打字後 scope 消失。

判讀

Pagefind 用 svelte 構建 UI、reactivity 監聽 search query 變動。Query 改變時 svelte 會 patch .pagefind-ui 的子樹 — 我們注入的 scope 不是 svelte 認得的節點、被視為差異清掉。

執行：邊界外 + CSS 控制位置

策略改為「scope 留在 .search-shell 裡（framework 邊界外）、用 CSS absolute 浮在 form 上」：

1<div class="search-shell">
2  <h1>...h1>
3  <div class="search-scope">...div>      
4  <div id="search">...div>               
5div>

1.search-shell { position: relative; }
2.search-scope {
3  position: absolute;
4  top: calc(var(--search-title-h) + var(--search-form-h) + 4px);
5  /* ... */
6}
7.search-shell .pagefind-ui__drawer {
8  margin-top: calc(var(--search-scope-h) + 8px);  /* 為 scope 讓位 */
9}

scope 不在 svelte 管轄區、永遠不被清；視覺位置靠 absolute + drawer 的 margin-top 共同決定。

CSS 達成視覺位置的設計工具

工具 1：Absolute + 容器 relative

把客製 UI 設 position: absolute、容器設 position: relative 當定位基準。

1.search-shell { position: relative; }
2.search-custom { position: absolute; top: ...; left: ...; }

客製 UI 跟 framework 元素脫離 layout flow、各自獨立。

工具 2：Margin spacer 推開 framework 元素

要在 framework 元素之間插入空間放客製 UI、改 framework 元素的 margin / padding 推出空間：

1.framework-element { margin-top: var(--custom-height); }
2.custom-ui { position: absolute; top: 0; height: var(--custom-height); }

framework 元素留出空間、客製 UI 浮在空間上。

工具 3：Grid 容器讓 framework 元件當 grid item

1.search-shell {
2  display: grid;
3  grid-template-rows: auto auto 1fr;
4}
5.search-shell > .search-scope { grid-row: 2; }
6.search-shell > #search { grid-row: 3; }

把 framework 元件當 grid 的一個 item — grid 控制 layout、framework 不知道有 grid 在外層、繼續管它的子樹。

工具 4：用 CSS variables 共享尺寸

framework 元素的尺寸需要參考客製 UI 時、用 CSS variable 傳遞：

1:root { --custom-height: 60px; }
2.framework-element { margin-top: var(--custom-height); }
3.custom-ui { height: var(--custom-height); }

或用 ResizeObserver 量測寫回 variable（#27 runtime 量測模式統一）。

設計取捨：客製 UI 的位置選擇

四種做法、各自機會成本不同。這個專案選 A（邊界外 + CSS）當預設、其他做法在特定情境合理。

A：framework 邊界外 + CSS 視覺定位（這個專案的預設）

機制：客製 UI 放在 framework 元件的 sibling 位置、用 CSS absolute / grid / margin spacer 達成視覺位置
選 A 的理由：跟 framework reconciliation 完全解耦、命運由自己決定、升級不影響
適合：絕大多數需要在 framework UI 旁 / 上 / 下加客製內容的情境
代價：CSS 定位邏輯比 DOM 巢狀複雜、需要正確處理 stacking context / z-index

B：framework 邊界外 + JS 量測位置

機制：用 ResizeObserver 量 framework 元素的 bounding rect、JS 算出客製 UI 該擺哪
跟 A 的取捨：A 用 CSS 表達靜態關係、B 處理 runtime 才知道的尺寸；B 多一層 JS、但能達成 CSS 表達不出的精確定位
B 比 A 好的情境：客製 UI 位置依賴 framework 元件的 runtime 尺寸（內容換行、字型變化）

C：framework 邊界內注入

機制：JS 把客製 element 直接 appendChild 到 framework 子樹內
跟 A 的取捨：C 看似省事（少一層 wrapper）、實際把客製命運綁在 framework reconciliation 上
C 才合理的情境：該 framework 子樹確認「不會被 reconcile」（極罕見、需要讀框架 source 確認）
代價：客製可能在任何 patch 時消失、需要 MutationObserver 補打、跟渲染週期賽跑

D：Fork framework source

機制：fork 整個 framework、改 reconciliation 行為讓它認得我們的客製
成本特別高的原因：每次升級都要重新 merge、客製永久綁在 fork 版本
D 才合理的情境：framework 已停止維護、且客製需求超過所有其他選項

不該套用「邊界外」的情境

A 是預設、但不是萬靈丹：

情境	為什麼不適合 A
客製內容必須在 framework 元件的內部視覺脈絡內（共享 inline flow）	Absolute 跳出 flow、達不到 inline 的視覺效果
Framework 元件本身就是要客製化（改 row、改 cell）	動的是 framework 本身、不是「在旁邊加東西」
Framework 提供了官方擴展介面（slot、render prop）	用官方介面更穩、不需要邊界外 hack
客製需要訪問 framework 的內部 state	邊界外的客製跟內部 state 隔離、訪問成本高

核心判準：客製是「在 framework 旁邊加東西」還是「改 framework 本身」？前者用本策略、後者另想辦法。

跟其他原則的關係

抽象層原則	關係
#45 跟外部組件合作的層次	「邊界外 + CSS」是「不要挖 framework 內部」的具體應用 — 客製貼著外部介面（DOM sibling）做、不挖內部
#42 2 次門檻	第 1 次注入失敗（被清掉）= 第 2 次該換策略到邊界外、不該繼續嘗試「換種方式注入」
#13 JS 操作 framework 元件：邊界辨識與安全規則	互補關係 — 本篇處理「客製 UI 該放哪」、#13 處理「framework 元件本身要動時怎麼動」

判讀徵兆

訊號	該怎麼處理
注入 framework DOM 的元素在使用者互動後消失	把該元素搬出 framework 邊界、用 CSS 控制視覺位置
客製 UI 在 framework 更新後 attribute 被 revert	客製 UI 不該在 framework 內、wrapper 在外、attribute 套 wrapper
看不出哪些 DOM 是 framework 管的	讀 framework 的 mount root、從那裡往內都是管轄區
Stacking context 衝突、z-index 失靈	確認 absolute 的 containing block 是預期的 relative parent
Framework 元件位置不固定、客製 UI 對不齊	用 ResizeObserver 量 framework 元素、寫回 CSS variable

核心原則：客製 UI 的存活壽命 = 「離 framework 管轄區多遠」。最遠 = 永遠不被清；注入內部 = 隨時可能消失。預設選邊界外、不要為了「省一層 wrapper」進入 framework 領地。

Filter 順序由使用者掃描成本決定

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

核心原則

選項清單按使用者掃描順序排序、不按資料來源預設。 短清單先看完、長清單花更多時間 — 把短清單放前面讓使用者先排除一個維度、再面對長清單。字母排序對「找已知名稱」有效；多選 facet 場景下使用者通常不知道確切選項名、需要 scan，這時候掃描成本主導。

為什麼掃描成本優先於字母排序

商業邏輯

當清單有多個選項供使用者挑選，選項數量影響掃描時間。使用者在 facet UI 的行為不是「找已知 tag」、是「看到有什麼可選、選有興趣的」 — 這是探索式行為、不是查找式行為。

行為類型	適合的排序
查找式（知道要什麼）	字母排序 — 二分查找
探索式（看有什麼）	掃描成本排序 — 短清單先

字母排序是資料庫思維（穩定、可預測），掃描成本排序是 UX 思維（縮短決策時間）。Facet 場景幾乎都是後者。

兩條維度收斂的順序

當有多個 facet 維度可選、使用者通常逐維度收斂：先用一個維度砍掉一半結果、再用第二個維度精選。短清單放前面讓「第一刀」決策快速。

這次任務的應用

觀察

Pagefind filter 預設按 filter key 字母排序：tag < type，所以 Tag 先顯示。

實際內容：

Filter	選項數量
Type	~5 個（post / card / glossary 等 section）
Tag	~80 個（站上所有 tags）

判讀

Type 短、Tag 長 — 預期使用者行為是「先按 type 收斂（這是 post 還是 glossary？）、再進 tag 找主題」。Tag 在前等於要使用者先面對 80 個選項，認知成本高。

把順序倒過來：Type 先顯示讓使用者先用 section 收斂、再進 Tag 找。

執行

 1function reorderFilters() {
 2 var blocks = filter.querySelectorAll('.pagefind-ui__filter-block');
 3 var desiredOrder = ['type', 'tag'];
 4 var byKey = {};
 5 blocks.forEach(b => {
 6 var key = b.querySelector('.pagefind-ui__filter-name').textContent.trim().toLowerCase();
 7 byKey[key] = b;
 8 });
 9 desiredOrder.forEach(k => byKey[k] && filter.appendChild(byKey[k]));
10}

內在屬性比較：四種排序策略

策略	適合場景	失敗模式
字母排序	使用者知道確切選項名	探索式場景下掃描慢
掃描成本排序（短先長後）	探索式 facet	「短」「長」邊界模糊時不穩
使用頻率排序	有 analytics 資料	冷啟動時無資料、需要默認
語意分組排序	選項有明顯子類別	子類別劃分本身需要設計

選擇順序：有 analytics → 頻率排序；沒有 → 掃描成本排序；都不適用 → 字母排序。

排序原則的延伸應用

Tag 內部的 80 個 tag 怎麼排？

內部排序方式	適用
字母排序	使用者知道想找哪個 tag
計數排序（最多文章的 tag 在前）	探索式、引導使用者進熱門主題
編輯精選	站方有特定主題策略

當前接受 pagefind 的字母排序（成本最低、且 80 個 tag 做計數排序需要額外索引處理）。

選項數量門檻

短清單跟長清單的邊界沒有絕對值，常用啟發：

≤ 7 個選項：可一眼掃完、放前面
8-20 個：中等、需要結構（縮排、分組）
20+ 個：長清單、放後面或加搜尋框

Type 5 個落在「短」、Tag 80 個落在「長」 — 順序明顯。

設計取捨：選項清單的排序策略

四種做法、各自機會成本不同。預設依使用者行為性質選 — 探索式 → A、查找式 → B、有 analytics → C、有子類別 → D。

機制：選項數量少的維度放前面（type 5 個 → 先；tag 80 個 → 後）
選 A 的理由：使用者先用短清單收斂一刀、再面對長清單；認知成本低
適合：探索式 facet（使用者不知道確切選項名）
代價：需要主動覆寫資料來源預設（不能直接用 DB 順序）

B：字母排序

機制：按 alphabetical 排
跟 A 的取捨：B 對「找已知名稱」高效（二分查找）、A 對「探索式選擇」高效；但 facet 場景幾乎都是探索式
B 比 A 好的情境：使用者通常知道確切選項名（國家清單、語言清單）

C：使用頻率排序（最常用在前）

機制：按 analytics 統計、最高頻選項在前
跟 A/B 的取捨：C 比 A 更精準（用真實資料）、但需要 analytics + 冷啟動時無資料
C 比 A 好的情境：有足夠 analytics、且使用者偏好集中（80/20 分布明顯）

D：語意分組排序

機制：把選項分子類別、組內再排
跟 A 的取捨：D 對「選項有明顯子類別」更直觀（產品類別 / 功能類別）、A 對純扁平清單夠用
D 比 A 好的情境：選項有清楚的層級結構（電商 facet：類別 > 子類別 > 選項）

判讀徵兆

訊號	排序問題	修正動作
使用者抱怨「選項太多找不到」	長清單在前、掃描負擔大	把短清單前移、或加搜尋框
同類選項使用者卡在第一步	第一個維度選項過多	換成更少選項的維度當第一步
預設排序看起來「隨機」	資料來源排序與 UX 不符	主動 reorder、不接受預設
新增選項後順序錯亂	reorder 邏輯依賴 hardcoded list	改用屬性分類（例如選項數量自動排）

核心原則：UI 排序是設計決策、不是技術選擇。預設順序通常反映資料來源結構、不反映使用者行為 — 主動覆寫是常態、不是例外。

量測值缺一不可：依賴未測量值會錯位

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

核心原則

對齊基準上的每個未知數都要解出來、整組才有解。 這跟線性方程組一樣 — 任何一個變數靠估算、整條基準線就不準。每個參與對齊的元素都需要「來源明確的數字」（寫死或量測），不能依賴「應該差不多吧」的視覺直覺。

為什麼缺一個值整個壞

商業邏輯

對齊不是「視覺感」、是「相對位置的數學關係」。filter 的 padding-top 要等於右側「H1 + input + gap」的總和；任何一個值不準、padding 就錯、視覺上看起來就是沒對齊。

人眼可以分辨 1px 的差異 — 估算「大概 60px」實際上 56 或 64 都可能、視覺一眼看出。

解線性方程組需要所有變數

步驟	動作
1	列出對齊基準上的所有元素
2	對每個元素標註「值的來源」：寫死 / 量測 / 未知
3	任何「未知」都要先解決（決定寫死或量測）才能寫對齊規則

跳過第 2 步直接寫對齊規則 = 拿一組有未知數的方程組嘗試代入解 — 不會對。

這次任務的實際情境

觀察

要把 filter sidebar 的內容上緣對齊到右側 results 上緣。filter 用 padding-top 把內容下推。

第一次嘗試：估 padding-top: 152px（H1 64 + input 68 + gap 20）。

實際渲染：filter 上緣比 results 上緣高了 ~10px。

判讀

152px 的計算用了估算的 H1 height（64px）。實際 H1 受 theme 的 margin-block-end 影響、總高度可能 ~70px。差了 ~6px。

進一步檢查：--pagefind-ui-scale: 0.8 時 input 高度 = 64 × 0.8 = 51.2px、不是 68px。又差 ~17px。

差距加總超過視覺可接受範圍。

執行

把所有變數轉為「來源明確」：

元素	解決方式
H1	寫死 height + line-height + margin: 0，強制等於 token
Pagefind input	設 `--pagefind-ui-scale: 1.0`，加 border 共 68px、強制等於 token
Scope UI（高度受字型換行影響）	用 ResizeObserver 量測寫回 CSS 變數
Gap（drawer margin-top）	從 pagefind CSS 取得固定值 20px

padding-top 用 calc() 加總所有變數、永遠跟著走。

內在屬性比較：值的「來源」分類

來源	適用情境	維護負擔
Design token（CSS 變數寫死）	設計可決定的固定值	低 — 改一處全部跟上
組件提供的 hook（如 pagefind scale）	透過組件 API 鎖定渲染參數	低 — 跟組件升級走
Runtime 量測（ResizeObserver）	內容動態決定的值	中 — JS 程式要寫對
估算 / magic number	不適用 — 永遠錯	不該存在

不要把「估算 / magic number」當作來源。每個 magic number 都是未來 debug 的潛在炸彈。

把對齊看成方程組的步驟

1基準線 P 的位置 = sum(每個前置元素的 height + margin + padding + gap)

例：filter 的 padding-top = H1.height + input.height + drawer.margin-top。

把每個變數列出、確認來源、用 CSS calc() + 變數寫成 single source。

1.search-filter-slot {
2  padding-top: calc(
3    var(--search-title-h)        /* 寫死 64px */
4    + var(--search-form-h)       /* 鎖 scale=1.0、寫死 68px */
5    + var(--search-scope-h)      /* ResizeObserver 量測 */
6    + 8px                        /* 固定 padding */
7    + var(--search-gap)          /* pagefind drawer margin 20px */
8  );
9}

設計取捨：對齊基準上每個值的來源

四種做法、各自機會成本不同。預設選擇取決於值的可預測性 — 設計可決定 → A、組件提供 hook → B、內容動態 → C、估算永遠不是答案。

A：Design token（CSS 變數寫死）

機制：--search-title-h: 64px 寫成設計系統 token
選 A 的理由：build time 確定、純 CSS、改 token 全部跟上
適合：設計可決定的固定值（spacing、typography scale、icon size）
代價：值無法跟 runtime 內容變動 — 字型大幅變化時可能不適配

B：組件提供的 hook（如 pagefind scale）

機制：.search-shell { --pagefind-ui-scale: 1.0 }、透過組件 API 鎖定渲染參數
跟 A 的取捨：B 把組件納入自家設計系統、A 自己決定值；B 在「組件渲染參數可調」時最乾淨
B 比 A 好的情境：值由組件決定但組件提供 hook 可控（例如 vendor library 的 size variant）

C：Runtime 量測（ResizeObserver 寫回 CSS 變數）

機制：JS 量元素實際渲染尺寸、寫回 CSS 變數、其他元素引用
跟 A/B 的取捨：C 自動跟著實際走、A/B 假設條件穩定；C 多 JS 一層
C 比 A 好的情境：值受字型 / 換行 / 內容動態影響、無法 build time 預測

D：估算 / magic number

機制：執行者依感覺給數字、不寫變數、不量測
成本特別高的原因：未來 debug 的潛在炸彈、估錯時錯誤被視覺接受不被發現、跨情境（字型 / scale / theme）必壞
D 是反模式：任何「沒來源」的值都是 unsolved 變數、會在邊界情境爆掉

判讀徵兆

訊號	可能的根因	第一個該檢查的事
視覺對齊「看起來差幾 px」	某個元素的高度估算不準	量測該元素真實 height、跟假設值比對
換 viewport 對齊壞掉	某個值依賴 viewport 但沒處理	找出該值、改用響應式變數
換字型 / 縮放後對齊壞掉	某個值受字型影響但寫死了	改用 ResizeObserver 量測
改某個 token 要去多處跟改	沒用 CSS 變數	把 magic number 提成變數、calc 串起來

核心原則：對齊問題的根因永遠是「某個變數沒解出來」。先找出那個變數、確定來源、再寫對齊規則。

「估值補方程式」是便利（用感覺寫死）、「找變數真實來源」是對齊（量測或從 token 算）— 同 #67 寫作便利度跟意圖對齊反相關。對齊問題的 silent 失敗常常是估值的後果。

置中元件與絕對定位元件並存：用疊層而非排擠

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

核心原則

置中元件與指定位置元件共存，正確做法是讓兩者位於不同 layout 層。 Layout 流負責「以內容驅動的尺寸與置中」；絕對定位負責「貼在 layout 流之上的固定位置元件」。兩者用疊層共存、不互相排擠。

為什麼排擠式做法行不通

商業邏輯

排擠式：把兩個元件放進同一個 grid / flex container、各佔一個欄位。問題在於「容器寬度有限、加一個欄位就壓縮另一個」 — 中央欄想置中時，加 sidebar 後整個 layout 重新分佈、中央欄被推到非置中位置。

疊層式：sidebar 用 position: absolute 從 layout 流跳出 — 中央欄看不到 sidebar、繼續按自己的規則置中。

兩種共存模式比較

模式	中央欄置中	維護成本	適用情境
排擠式（同 layout 流）	受 sidebar 影響、需要重算	低 — 純 CSS	兩個元件都要自然撐開
疊層式（absolute）	不受影響、永遠按 viewport 置中	中 — absolute 需要定位基準	中央欄要嚴格置中、sidebar 是「附加」

選擇疊層式的時機：中央欄的位置是設計重點、sidebar 是補充。本案搜尋頁的 main 是內容主體、filter 是輔助 — 適合疊層。

這次任務的實際做法

觀察

搜尋頁 desktop layout：

寬度 70ch、theme 預設 margin-inline: auto 置中
想加 filter sidebar 在 main 左外側、寬度 400px

判讀

把 filter 放進 main 的 grid（變成 main 的子 column），main 內容會被推到右半邊、不再置中。

讓 filter 用 position: absolute 相對 main 定位 — main 完全不知道 filter 存在、繼續置中。filter 在 main 外側「貼著」main 的左邊緣。

執行

 1body.page-search main#main-content {
 2  position: relative;   /* filter 的 offset parent */
 3  /* main 的 max-width: 70ch 與 margin-inline: auto 由 theme 提供，不動 */
 4}
 5
 6.search-filter-slot {
 7  position: absolute;
 8  top: 0;
 9  right: calc(100% + 2rem);   /* main 的左外側、間距 2rem */
10  width: 400px;
11}

right: calc(100% + 2rem) 的含義：filter 的右邊緣 = main 左邊緣 - 2rem。filter 從這個 anchor 往左展開 400px。

main 永遠按 viewport 置中、filter 永遠貼在 main 左外側。

疊層共存的三個關鍵要素

1. Offset parent 的選擇

絕對定位元件的座標相對於「最近的 positioned ancestor」。要讓 sidebar 跟著 main 一起移動（不要跟 viewport 走），就把 main 設為 position: relative 當作 offset parent。

1body.page-search main { position: relative; }
2.search-filter-slot { position: absolute; /* 相對 main */ }

2. Anchor 點的選擇

right: calc(100% + 2rem)、left: -432px、right: 100%; margin-right: 2rem 三種寫法視覺上等價。選擇可讀性最高的 — 通常是 right: calc(100% + 2rem)，意義最直接（「我的右緣 = parent 寬度 + 2rem 之外」）。

3. 物理空間檢查

絕對定位不檢查 viewport 邊界 — sidebar 可能被推到 viewport 外。需要在 breakpoint 確認「viewport 夠寬時才顯示 sidebar」：

1.search-filter-slot { display: none; }
2@media (min-width: 1400px) {
3  .search-filter-slot { display: block; }
4}

物理空間預算的細節參見〈跨 viewport 雙模式 UI 的物理空間預算〉。

內在屬性比較：兩種共存做法

屬性	排擠式（grid / flex）	疊層式（absolute）
中央欄位置	隨 sidebar 寬度變動	不受影響、嚴格置中
Sidebar 寬度限制	來自 grid container	來自 viewport（需 breakpoint 控制）
Layout 重算成本	改 sidebar 寬度時 main 跟著動	main 永遠不動
適用情境	兩個元件都要自然撐開	中央嚴格置中、sidebar 附加

選擇順序：先確認中央欄的位置要求。要嚴格置中 → 疊層式；可隨 sidebar 浮動 → 排擠式。

設計取捨：兩元件共存的 layout 策略

四種做法、各自機會成本不同。這個專案選 A（疊層 absolute）當預設、其他做法在特定情境合理。

A：疊層式（中央 layout flow + 附加 absolute）（這個專案的預設）

機制：嚴格置中的元件留 layout flow、附加元件 position: absolute 跳出 flow
選 A 的理由：中央位置不受附加元件影響、改附加元件不需重算中央
適合：中央嚴格置中 + sidebar 是「附加」的場景（搜尋頁、文章閱讀頁）
代價：absolute 需要明確 offset parent、要做物理空間檢查避免溢出

B：排擠式（同 layout flow、grid / flex）

機制：把兩元件放進同一 grid / flex container、各佔一個欄位
跟 A 的取捨：B 兩元件都自然撐開、A 中央嚴格置中；B 改一邊另一邊跟著動、A 完全解耦
B 比 A 好的情境：兩元件都是內容主體、需要互相適應寬度（dashboard 多面板）

C：Fixed（相對 viewport）

機制：附加元件 position: fixed、永遠在 viewport 同位置
跟 A 的取捨：C 永遠可見（隨 scroll 不動）、A 跟內容一起 scroll；C 適合 always-on UI
C 比 A 好的情境：浮動操作鈕、頂部 nav、使用者隨時要 access 的元件

D：重新設計 layout（取消共存需求）

機制：把附加元件搬到完全不同位置（footer、modal、抽屜）
跟 A/B/C 的取捨：D 完全避開共存問題、A/B/C 解決共存
D 比 A 好的情境：附加元件使用頻率低（offset 很大價值低）— 例如 settings 改放 modal 內

判讀徵兆

訊號	可能的根因	第一個該嘗試的動作
加了 sidebar 後中央內容不再置中	用了排擠式、中央欄被推	改用 absolute、main 設 `position: relative`
Absolute sidebar 跟著 viewport 跑、不貼 main	沒設 offset parent	給 main 加 `position: relative`
Sidebar 在窄 viewport 溢出畫面	沒做物理空間檢查	加 breakpoint、寬度不夠時 `display: none`
改 sidebar 寬度時要回頭調 main 樣式	排擠式造成 layout 耦合	改用疊層、main 永遠不需要因 sidebar 改

核心原則：兩個元件的視覺關係用疊層描述、不用排擠描述。疊層 = 兩層獨立 = 改一邊不影響另一邊。

同一個元件在三種互動狀態下顯示位置不同的 root cause

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

核心原則

元件位置 = 定位基準（anchor）+ 相對基準的偏移。元件「跟著狀態飄」不是元件本身的問題、是它的 anchor 隨狀態在動。 Debug 時把元件位置拆成「找錨點 → 算偏移」兩層、確認哪一層在隨狀態變化。

為什麼狀態化錯位的根因不在元件本身

商業邏輯

CSS 計算元件位置時，元件總是「相對某個 reference」 — block flow 是「上一個 sibling 的下緣」、absolute 是 offset parent、grid item 是 grid container。這個 reference 才是元件位置的決定因素。

當 reference 在不同狀態下尺寸或位置變動，元件被動跟著動 — 看起來是元件「自己飄」，根因卻在 reference。

三層拆解 debug 法

層	問題	修法
1. 元件本身	元件 CSS 規則錯了？	看元件的 computed style
2. 元件的 reference	reference 在動嗎？尺寸隨狀態變動？	量 reference 在每個狀態下的 bounding rect
3. Reference 的 reference	上一層也在動嗎？	一層一層往上追

多數狀態化錯位的根因在第 2 或第 3 層、不在第 1 層。

這次任務的實際情境

觀察

新加 scope UI（搜尋範圍 radio group）後出現三個狀態的位置不一致：

狀態	scope UI 位置
初始載入（pagefind 還沒 mount）	緊接 H1 下方
點擊 input（focus、空查詢）	在 input 與 results 區之間（如預期）
輸入查詢（results 載入後）	跑到所有結果的最下方

判讀

第一輪猜測：scope UI 自己的 CSS 在不同狀態下不同 — 用 playwright 看 computed style，發現三狀態下 scope 的 grid-row 都是 3、CSS 屬性沒變。

第二輪：用 playwright getBoundingClientRect() 量 scope 的位置，發現 y 座標確實在三狀態下不同。

第三輪：往上一層看「scope 的 grid container 是誰、container 的 grid template 在不同狀態下變了嗎」。發現 search-shell 的 grid template-rows 是 auto、自動依子元素內容撐開。

關鍵發現：.pagefind-ui__drawer 不是 .pagefind-ui 的直接子節點 — 它在

內。

1.pagefind-ui (display: contents)
2└── form.pagefind-ui__form (grid-row: 2)
3    └── div.pagefind-ui__drawer (grid-row: 4 設了沒生效)

於是：

初始：form 只含 input、row 2 矮、scope 在 row 3 緊接 row 2 下。
輸入後：form 含 input + drawer（187 個結果）、row 2 撐到全頁高。grid-row 4 比 row 2 後 — 但 drawer 被 form 包住、整個 form 在 row 2 — scope（row 3）在 form 之後 = 結果之後。

scope 的 anchor（grid container 的 row 排列）在 form 撐開時改變 — anchor 在動、scope 跟著動。

執行

確認 anchor 問題後改用 absolute 定位：scope 浮在 form 之上、drawer 用 margin-top 讓位。scope 的 anchor 改為 .search-shell 的 position: relative、不再依賴 form 的尺寸。三狀態下位置一致。

拆解 anchor 的四個工具

1. 找元件的 reference

元件的 position	Reference
static（預設）	上一個 sibling 的下緣 / 父 container
relative	元件原本在 flow 中的位置
absolute	最近的 positioned ancestor
fixed	viewport
sticky	滾動容器
Grid item	Grid container 的 cell
Flex item	Flex container 的軸線

2. 用 `getBoundingClientRect` 量

1const el = document.querySelector('.search-scope');
2console.log(el.getBoundingClientRect());

在三個狀態下分別量、比對 y 座標。差異對應到「reference 在動」。

3. 往上追 ancestor chain

1let parents = []; let el = target;
2while (el) {
3  parents.push(el.tagName + '.' + el.className);
4  el = el.parentElement;
5}
6console.log(parents);

找出 reference 是誰、reference 的 reference 是誰、一層一層追到「不會動」的元素。

4. Computed style vs DOM tree 一起看

CSS 規則在 computed style 顯示為「我設了什麼」、DOM tree 顯示「實際巢狀關係」。兩者一起看才知道規則為什麼沒生效。

內在屬性比較：三種定位策略對狀態化錯位的抵抗

策略	Anchor 穩定性	狀態化飄移風險
Static / block flow	低 — 任何前置元素變動都影響	高 — sibling 撐高就被推下去
Grid / Flex item	中 — 跟 container 設計綁定	中 — container row 撐開時跟著動
Absolute（自定義 offset parent）	高 — anchor 是固定 ancestor	低 — anchor 不變則元件不動
Fixed	最高 — anchor 是 viewport	不會因內容變動飄移、但會因捲動變化

當一個元件需要在多種狀態下保持固定位置 — 優先 absolute（搭配明確的 offset parent）。

設計取捨：對抗狀態化飄移的定位策略

四種做法、各自機會成本不同。這個專案選 A（absolute + 自定義 offset parent）當預設、其他做法在特定情境合理。

A：Absolute + 穩定 offset parent（這個專案的預設）

機制：元件 position: absolute、選定一個尺寸不隨狀態變動的 ancestor 作為 offset parent
選 A 的理由：anchor 不變則元件不動、跨所有互動狀態位置一致
適合：需要在多狀態下保持固定位置的元件
代價：跳出 layout flow、附近元件需要手動讓位（margin spacer）

B：Grid / Flex item

機制：把元件當 grid / flex container 的子項、用 grid-row / flex-order 排
跟 A 的取捨：B 自然 reflow、A 完全 anchor-driven；B 在 container 內容隨狀態撐開時、grid 排序跟著重算
B 比 A 好的情境：container 尺寸不隨狀態變動的場景（純 layout、內容靜態）

C：Static / block flow（預設 layout）

機制：不設 position、跟 sibling 自然排
跟 A/B 的取捨：C 最簡單、A/B 主動處理 anchor；C 完全受前置 sibling 影響、狀態化飄移風險最高
C 才合理的情境：頁面內容極穩定、無狀態切換 — 否則第 N 個元素位置受前 N-1 個元素影響

D：Fixed（相對 viewport）

機制：position: fixed、anchor 是 viewport
跟 A 的取捨：D 永遠在 viewport 同位置、A 跟著內容；D 對「導航類元件」合理、對「內容相關元件」不合理
D 比 A 好的情境：永遠可見的功能元件（toolbar、scroll-to-top button）

判讀徵兆

訊號	可能的根因	第一個該嘗試的動作
元件位置在不同互動狀態下不同	Anchor 隨狀態變動	用 playwright 量三個狀態下的 bounding rect
Computed style 三狀態下都一樣、但位置不同	Reference 元素的尺寸在動	量 reference 元素的尺寸、確認哪個狀態下變大
改元件 CSS 一個狀態好了、另一個壞	用了 reference-dependent layout	改用 absolute、選擇穩定的 offset parent
元件初始正確、互動後跑掉	Reference 因 reactivity 撐開	找出該 reference、用 absolute 跳出其影響

核心原則：元件「會飄」不是元件的個性、是它依賴的東西在飄。先找飄的源頭，不要追著元件改。

從色塊 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 後。

在開發循環裡早一點用 playwright 看真實結果

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

核心原則

Playwright 不是最後手段、是縮短診斷迴圈的工具。 當靜態 CSS 推理 + 視覺截圖溝通的循環失敗 ≥ 2 次、就應該停止推理、改用 playwright browser_evaluate 直接讀 live DOM 與 computed style。早一點用 = 試錯次數更少、心智負擔更輕。

為什麼推理迴圈有極限

商業邏輯

CSS 行為由「規則 + DOM tree + 樣式繼承 + 框架渲染」四個變數共同決定。靜態推理只能基於假設的 DOM tree — 假設錯了、推理就錯。視覺截圖溝通只能傳達「結果是什麼」、無法傳達「為什麼是這個結果」。

Playwright 的 browser_evaluate 直接執行 JS 在 live page、返回真實的 DOM tree、computed style、bounding rect — 把「四個變數」全部變成已知。

推理 vs 量測的成本曲線

方法	第 1 次嘗試	第 2 次	第 3 次以上
靜態推理 + 截圖	快 — 假設正確時一次到位	慢 — 假設錯了得重來	越來越慢 — 假設錯誤累積
Playwright 量測	中 — 起 server、寫 evaluate	快 — server 已在跑	快 — 重用 setup

第 1 次推理快、後續成本爆炸；playwright 起步慢、後續穩定。門檻在第 2 次。

這次任務的實際情境

觀察

要把 search scope UI 放在「搜尋輸入框與結果之間」。

第一輪：基於 class name 推測 DOM tree、用 grid + display:contents 設 grid-row 排序。第二輪：發現 scope 跑到頁尾、嘗試調 grid-template-rows。第三輪：嘗試 absolute 定位但時機不對。第四輪：使用者說「思路錯了」、要我換方向。

判讀

四輪推理都基於同一個假設：drawer 是 .pagefind-ui 的直接子節點、跟 form 並列。實際用 playwright 一查：

1const drawer = document.querySelector('.pagefind-ui__drawer');
2let parents = []; let el = drawer;
3while (el && el !== document.body) {
4  parents.push(el.tagName + '.' + el.className);
5  el = el.parentElement;
6}

1DIV.pagefind-ui__drawer
2FORM.pagefind-ui__form    ← drawer 在 form 內！
3DIV.pagefind-ui

假設錯了 — drawer 是 form 的 child、不是 sibling。grid 規則無論怎麼寫都不會生效，因為 drawer 跟 form 共用同一個 grid cell。

四輪推理 ≈ 30 分鐘。Playwright 一次查清楚 ≈ 2 分鐘。

執行

確認 DOM 結構後：grid 不適合這個場景、改用 absolute + drawer margin-top spacer。一次到位。

Playwright 在開發循環的三個位置

1. 假設驗證

寫 CSS 規則前先量 DOM、確認結構符合假設。

1async () => ({
2  parents: [].slice.call(document.querySelectorAll('.target')).map(el => {
3    let chain = []; let n = el;
4    while (n) { chain.push(n.tagName + '.' + n.className); n = n.parentElement; }
5    return chain;
6  })
7})

2. 行為驗證

Layout 規則寫完後驗證實際結果。

1async () => ({
2  rect: document.querySelector('.target').getBoundingClientRect(),
3  computed: getComputedStyle(document.querySelector('.target')).gridRow,
4})

3. 互動驗證

驗證使用者互動後的狀態。

1async () => {
2  const input = document.querySelector('.search-input');
3  input.value = 'pre';
4  input.dispatchEvent(new Event('input', { bubbles: true }));
5  await new Promise(r => setTimeout(r, 1000));
6  return Array.from(document.querySelectorAll('.result'))
7    .filter(el => getComputedStyle(el).display !== 'none')
8    .map(el => el.textContent.slice(0, 50));
9}

內在屬性比較：四種 debug 方法

方法	取得資訊量	重複成本	可寫成測試
靜態 CSS 推理	低 — 全是假設	高 — 每次重思考	否
視覺截圖溝通	中 — 只有結果	中 — 截圖 / 描述慢	否
瀏覽器 DevTools	高 — DOM + computed	中 — 每次手點	否
Playwright `browser_evaluate`	最高 — 程式化任意查詢	低 — 改 query 重跑	是 — 同樣 query 可寫測試

選擇順序：簡單 layout 用 DevTools；複雜 / 反覆 debug 用 playwright；推理只在第 1 次試錯前。

引入 playwright 的最低門檻

1# 啟動本地 server（任何方式）
2python3 -m http.server 8000 --directory public
3
4# 或專案有 hugo
5hugo server

Playwright MCP 提供：

browser_navigate(url) — 開頁
browser_evaluate(fn) — 執行 JS 拿結果
browser_take_screenshot() — 截圖
browser_snapshot() — accessibility tree

寫一個 evaluate fn ≈ 30 行 JS，比反覆推理快得多。

設計取捨：CSS / DOM debug 工具選擇

四種做法、各自機會成本不同。這個專案在推理 ≥ 2 次失敗後選 A（playwright browser_evaluate）當預設、其他做法在特定情境合理。

本篇是 #42 2 次門檻抽象原則在「debug 工具切換」這個面向的應用。

A：Playwright `browser_evaluate` 程式化讀 live DOM（這個專案的預設）

機制：起 server、用 browser_evaluate 寫 JS query 讀 DOM tree / computed style / bounding rect
選 A 的理由：取得資訊量最大、可重跑、可寫成測試
適合：推理失敗 ≥ 2 次、複雜或反覆 debug 的情境
代價：起步成本中（需要 server + 寫 evaluate）

B：靜態 CSS 推理 + 視覺截圖溝通

機制：純看 CSS 與假設的 DOM 推測、用截圖跟使用者溝通
跟 A 的取捨：B 起步成本 0、A 起步成本中；但 B 第 2 次以後成本爆炸（每輪都基於前輪錯誤假設）
B 比 A 好的情境：第 1 次嘗試、預估假設正確機率高（簡單修改）

C：瀏覽器 DevTools 手動查

機制：開 DevTools 切 Elements / Computed / Layout 面板手動探索
跟 A 的取捨：C 不需 server / playwright setup、但每次手點切面板慢、不能寫成測試
C 比 A 好的情境：一次性確認、不需要重複 query 同樣資訊

D：寫成 playwright 測試固化

機制：把 debug 過程寫成 playwright 測試、未來自動跑
跟 A 的取捨：D 是 A 的延伸 — 第 2 次 debug 同個版型時、值得固化（#15 layout tests）
D 比 A 好的情境：版型 bug 出現第 2 次以上、值得寫測試防止回歸

判讀徵兆

訊號	工具切換時機	第一個該寫的 evaluate
推理 ≥ 2 次失敗	切到 playwright	量目標元素的 ancestor chain
Layout 在某些狀態下錯、其他狀態下對	切到 playwright	量該元素在不同狀態下的 bounding rect
改 CSS 不生效、specificity 看起來對	切到 playwright	量 computed style 看真正套到的值
動態 DOM 結構不確定	切到 playwright	列出目標 container 的子節點

核心原則：縮短診斷迴圈的工具該早一點用、不該等到推理徹底失敗。第 2 次推理失敗就切換、別等第 5 次。

延伸應用：playwright 也用來查「資料層 vs 視覺層的層錯位」 — 見 #55 Filter 與 Source 的抽象層錯位用 browser_evaluate 量 source 真實 cardinality 與分批機制。

排版精度的工具選擇：CSS-only vs JS-assisted

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

核心原則

CSS 處理 build-time 可決定的 layout、JS 處理 runtime 才知道的尺寸與 stateful DOM 移動。 邊界誤判：硬要 CSS 解決 runtime 問題會反覆試錯；硬要 JS 解決 layout 問題會跟 framework 渲染競爭。

選擇問題簡化為兩問：

這個值在 build time 能定下來嗎？能 → CSS；不能 → JS 量測寫回 CSS 變數。
這個 DOM 變動是 framework 管的嗎？是 → 不要動；不是 → JS 可動。

為什麼分工是必要的

商業邏輯

CSS 的設計假設是「規則在 build time 決定、瀏覽器渲染時應用」。CSS 沒有 reactive 機制 — 沒辦法「等元素渲染完才知道高度然後對齊」。

JS 的設計假設是「runtime 可以讀寫 DOM 與 style」。JS 可以在元件渲染後量測尺寸、可以隨 viewport 變動 reparent 節點。

用錯工具不只「不太優雅」、是直接做不到。要 CSS 解決動態尺寸只能寫 magic number（猜的）；要 JS 解決靜態 layout 寫了一堆 imperative 代碼還可能跟 framework 衝突。

這次任務的工具分配

CSS 處理的部分

任務	CSS 寫法	為什麼用 CSS
H1 / search input 的固定高度	`height: 64px` 寫死	Build time 可決定的設計 token
搜尋頁主欄置中、breakpoint 切換	`@media (min-width: 1400px)`	純宣告式 layout
Filter sidebar absolute 定位	`position: absolute; right: calc(100% + 2rem)`	靜態定位關係
Drawer 留出 scope 空間	`margin-top: calc(var(--search-scope-h) + 8px)`	引用變數的 calc

JS 處理的部分

任務	JS 寫法	為什麼用 JS
量測 scope 高度寫回 CSS 變數	ResizeObserver	Runtime 才知道（字型、換行）
Filter sidebar 切換到 mobile drawer	matchMedia + appendChild	跨 viewport 的 stateful DOM 移動
Scope filter（regex 比對標題 / 內文）	event listener + setProperty	純 runtime 邏輯、無 build time 解
Scope UI 寫死值與量測值的橋	`style.setProperty('--search-scope-h', ...)`	JS 寫回讓 CSS 用

兩問判斷法

問 1：這個值在 build time 能定下來嗎

值	Build time 知道嗎	工具
設計 token（spacing、typography scale）	是	CSS 變數寫死
元件固定尺寸（icon size、button height）	是	CSS height / width
響應式 breakpoint	是（設計決定）	`@media` query
動態文字塊高度（受字型 / 換行）	否	JS ResizeObserver
元件位置（隨 viewport 變化）	否	JS getBoundingClientRect

知道 → CSS 解。不知道 → JS 量測寫回 CSS 變數、CSS 從變數計算。

問 2：這個 DOM 變動是 framework 管的嗎

變動	Framework 管	工具
自家 DOM 內元素加 / 移 / 改	否	JS 自由動
Framework 元素的整節點 reparent	不管內部	JS 可搬
Framework 元素內部的子節點	是	不要動
Framework 元素的 attribute	視 framework 而定	通常不要動

是 → 不要動，用 CSS 視覺解。不是 → JS 可動。

內在屬性比較：兩種工具的特性

屬性	CSS-only	JS-assisted
知識成本	低（語言簡單）	中（需要 DOM API）
執行時機	渲染前 / 樣式重新計算	DOMContentLoaded 後 / 事件觸發
是否阻塞首次渲染	是（CSS 是 render-blocking）	否（async）
Framework 衝突風險	無	有（若動到 framework 管的 DOM）
可維護性	高（純 declarative）	中（imperative）
跨瀏覽器一致性	高（CSS 標準清楚）	中（API 差異）

優先 CSS — declarative、無 framework 衝突、首次渲染就生效。JS 補 CSS 做不到的部分。

邊界誤判的兩種失敗

CSS 解 runtime 問題

例：用 CSS magic number 寫死 scope-h（猜 56px），實際渲染 73.5px、對齊壞掉。

修法：認知到「scope-h 是 runtime 才能知道的值」、改用 ResizeObserver 量測寫回 CSS 變數。

JS 解 framework-managed layout

例：用 JS appendChild 把 scope UI 注入 .pagefind-ui 內、Svelte 重繪時清掉。

修法：認知到「.pagefind-ui 是 framework 邊界內」、改用 CSS absolute 把 scope 浮在外部。

設計取捨：CSS / JS 工具分配策略

四種做法、各自機會成本不同。這個專案以 A（CSS-first、JS 透過變數補）為主、其他做法在特定情境合理。

A：CSS-first、JS 透過 CSS 變數補 runtime 值（這個專案的預設）

機制：CSS 處理 build time 可決定的 layout、JS 量測 runtime 值寫回 CSS 變數、CSS 從變數計算
選 A 的理由：CSS 是 declarative 不阻塞首次渲染、跟 framework 不衝突；變數是 JS-CSS 介面、單向資料流
適合：絕大多數客製情境
代價：需要明確分辨「值能在 build time 定下來嗎」、JS 寫法要是「寫回變數」而不是「直接改 inline style」

B：純 CSS-only（無 JS）

機制：純宣告式、不寫 JS
跟 A 的取捨：B 完全無 JS 維護成本、A 多一層 JS；但 B 對 runtime 才知道的尺寸（內容動態）束手無策
B 比 A 好的情境：所有值都能 build time 確定、layout 完全靜態

C：JS-imperative layout（每次重算）

機制：JS 監聽變動、每次重新計算所有元素位置、寫 inline style
成本特別高的原因：imperative 代碼難維護、首次渲染慢（要等 JS 跑）、跟 framework 渲染衝突
C 才合理的情境：CSS 表達不出的複雜 layout（極罕見、現代 CSS 已涵蓋大多數）

D：CSS magic number 估算 runtime 值

機制：CSS 內寫死「應該差不多」的值（不量測）
跟 A 的取捨：D 看似省 JS、實際對齊在邊界情境（字型 / theme）必壞
D 是反模式：「runtime 才知道的值」用 CSS 估算是錯誤工具選擇 — 對齊在邊界情境（字型 / theme）必壞

判讀徵兆

訊號	工具誤用方向	修正動作
CSS 寫了 magic number、改字型後對不齊	用 CSS 解 runtime 問題	量測該值、改 ResizeObserver 寫回變數
JS 寫了 100+ 行做 layout	用 JS 解靜態 layout 問題	退回 CSS、用 grid / flex / absolute 達成
JS 改 framework DOM 後，framework 更新就失效	JS 動到 framework 管的領域	改用 CSS 視覺定位、不動 framework DOM
Inline style 散落多處難 debug	JS 直接寫 style 而非透過變數	重構成「JS 寫 CSS 變數、CSS 從變數計算」

核心原則：選工具不是品味問題、是「值能不能在 build time 定下來」「DOM 是不是我管」兩個技術問題的答案。問清楚再選。

JS 操作 framework 元件：邊界辨識與安全規則

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

核心原則

JS 操作 framework 元件前先界定邊界、選對應的安全規則執行。 邊界 = 契約 = 安全範圍。整節點搬遷安全、改節點內部不安全、改節點 attribute 是灰區。每類操作有對應的安全規則 — 不是「能不能動」、是「動了之後 framework 會不會 revert」。

本篇焦點：framework 元件本身需要動時的安全規則。「客製 UI 該放哪」由 #5 客製 UI 留 framework 邊界外處理 — 預設應該完全不動 framework、需要動時才參考本篇。

為什麼邊界要先界定

商業邏輯

每個元件（自家或 framework 提供）有「對外契約」與「內部實作」。對外契約包括：

契約類型	內容
DOM identity	哪些 class / id / attribute 是穩定的
State 來源	元件內部 state 由誰寫、何時改
渲染週期	元件何時重繪、重繪時影響哪些 DOM
對外介面	提供哪些 props / events / API hooks

JS 操作前不知道這些 = 黑箱操作。動了什麼、會觸發什麼、誰會被影響、不可預測。

邊界宣告的格式

開始 JS 操作之前、寫一段註解或 mental note：

1動什麼：filter-panel 的 parent
2邊界：filter-panel 整個節點 OK，內部子節點屬於 pagefind 管
3State：checkbox 勾選狀態存在 panel 子節點上、由 pagefind 維護
4動作：appendChild 整節點 reparent
5為什麼安全：節點 identity 不變、pagefind 在下次 patch 時看到節點還在

這段宣告把「動什麼」「不能動什麼」「為什麼安全」說清楚 — 不是儀式、是強迫自己想清楚再動。

三類操作的安全度

從最安全到最不安全：

1. 整節點 reparent（安全）

把 framework 管的整個節點搬到別處 — 節點 identity 不變、framework 在下次 patch 時仍認得它。

1// 安全 — 整節點搬位置
2sidebar.appendChild(filterPanel);
3drawer.insertBefore(filterPanel, drawer.firstChild);

2. 改節點內部子節點（不安全）

在 framework 管的節點內 appendChild / removeChild / 改子節點屬性 — framework 會 revert。

1// 不安全 — 在 framework 子樹內加東西
2filterPanel.appendChild(myCustomDiv);
3filterPanel.querySelector('.x').setAttribute('data-y', 'z');

3. 改節點自身的 attribute / inline style（灰區）

改 framework 管的節點本身的 attribute、看 framework 是否認為這屬於 reactive：

1// 灰區 — 看 framework 怎麼處理
2el.style.display = 'none';
3el.classList.add('my-state');
4el.setAttribute('aria-hidden', 'true');

下節展開三類各自的設計細節。

整節點 reparent：為什麼安全、怎麼做才安全

為什麼安全

Framework 的 reconciliation 通常以「節點 identity」為依據 — 同一個節點在哪裡不重要、節點存不存在才重要。

把 .pagefind-ui__filter-panel 從 drawer 移到外部 aside：

Framework 看到	反應
節點還在（identity 沒變）	繼續更新它的內部
節點的 parent 變了	Framework 不關心 — parent 不在 component tree 內
節點內的 children 不變	Framework 不需要重建

reconciliation 不會因為「位置變了」而重建節點 — 重建只發生在「節點消失了 + 新節點出現」的情境。

安全 reparent 的 do / don’t

Do	Why
`parent.appendChild(node)` 整節點搬	identity 保留
`parent.insertBefore(node, ref)` 整節點搬到特定位置	identity 保留
搬之前 `node.cloneNode(true)` 為複本（如果要保留原位）	複本是新 identity、原節點仍由 framework 管
搬完後不動 node 內部	framework 繼續正常更新

Don’t	Why
`parent.appendChild(node.firstChild)` 搬 framework 子節點	把節點抽出原 parent、framework 認為消失了
`node.innerHTML = node.innerHTML` 重設內部	創造一堆新 identity、framework 認不得
搬完後在 node 內 appendChild 加東西	加的東西不在 framework 認知中、被清
搬完後改 node 內子節點的 text / attribute	framework 在下次 patch 時 revert

核心規則：搬節點 = 操作 node 本身；不要操作 node 的 children。

跟 framework reactivity 的對齊

某些 framework 對節點的「內部值」是 reactive 的（例如的 value），改了會被 reconcile 回來。對這類屬性：

屬性類型	操作策略
Reactive value（input.value、textContent）	透過 framework API 改、不要直接改 DOM
純展示 attribute（class、aria-* 多數情境）	直接改 DOM 通常 OK、但仍是灰區（見下節）
Layout-relevant style（display、position）	直接改 DOM 通常 OK、可能需要 fail-safe

不確定某屬性是否 reactive：讀框架 source / 文件確認、或加 fail-safe 防意外。

改節點內部：為什麼不安全、有什麼例外

為什麼不安全

在 framework 管的節點內 appendChild / removeChild — framework 不認得這些操作的結果、下次 patch 時：

Framework 比對 component tree 的目標狀態
看到 DOM 多了不該有的節點 → 移除
或看到 DOM 少了該有的節點 → 重建

我們手動加的節點屬於前者、被移除。我們手動移除的子節點屬於後者、被重建（且重建的 identity 不同）。

唯一的例外：靜態元件 + 確認 patch 不重設

如果該 framework 子樹「初次 mount 後不再 patch」、改內部可能安全。但這是框架實作細節、隨版本可能變動。

例：當前 pagefind 的 filter 順序在初次 mount 時生成、後續 patch 不重排 — 所以 reorder filter 子節點實際安全。但這是「當前版本碰巧」、不是「框架保證」。

操作規則：不要依賴「碰巧安全」。如果必須改內部、加 MutationObserver 監聽 framework 是否 revert、必要時補打。

改節點 attribute / inline style：灰區的 fail-safe 設計

為什麼是灰區

Framework 通常不主動管理節點的 inline style 與非 reactive attribute — 但「通常」不是「永遠」。某些 framework 會在 patch 時把 inline style 重設、或把 attribute 跟 component state 強制同步。

Fail-safe 工具 1：`!important` 提升優先級

1el.style.setProperty('display', 'none', 'important');

important 把 inline style 的優先級提升 — 即使 framework 套了同屬性的低優先 style、也蓋不過。

Fail-safe 工具 2：MutationObserver 補打

1function reapply() {
2  el.style.setProperty('display', 'none', 'important');
3}
4reapply();
5new MutationObserver(reapply).observe(parent, {
6  childList: true, subtree: true,
7});

Framework 在重繪後可能把 element 替換成新的 — observer 監聽到變動、立刻補套 style。

詳細設計（observer 範圍 / 觸發頻率 / self-mutation 處理）由 #29 MutationObserver 範圍與觸發頻率處理。

Fail-safe 工具 3：CSS class toggle 取代 inline style

1// 不用 inline style
2el.classList.toggle('is-hidden');

1/* CSS 內定義行為、layered CSS 不需要 important */
2@layer base {
3  .is-hidden { display: none; }
4}

詳細展開由 #28 class toggle 取代 important 處理。

選擇順序：能用 class toggle 就用（最乾淨）；framework 會清 class 才用 inline + important + observer。

這次任務的邊界辨識實例

四個 JS 操作場景、各有不同邊界：

場景	動的對象	操作類別	安全度	處理
把 filter-panel 從 drawer 搬到 sidebar	整節點 reparent	1（安全）	高	直接搬、不動內部
Reorder type / tag filter	filter 子節點順序	2（不安全）	中 — 視 framework 而定	確認框架不 reset 順序、加 observer 防護
注入 scope UI	自家新元件	N/A（自家領域）	高	放 framework 邊界外（#5）
Filter 結果 hide / show	pagefind 結果元素的 display	3（灰區）	中	inline + important + observer 補打

每個場景操作前的 mental check：「這是哪一類？該用什麼安全規則？」

設計取捨：操作 framework 元件的策略

四種策略、各自機會成本不同。預設追求「最高安全度的方式達成需求」、成本太高再降級。

A：完全不動 framework、客製留邊界外（這個專案的預設）

機制：把客製 UI 放在 framework sibling 位置、用 CSS 達成視覺效果
選 A 的理由：跟 framework 完全解耦、命運自主
適合：需求是「在 framework 旁加東西」（多數情境）
代價：CSS 定位可能複雜
詳細：#5 客製 UI 留 framework 邊界外

B：整節點 reparent

機制：把 framework 管的節點搬位置、不動內部
跟 A 的取捨：A 不動 framework、B 搬 framework 元件本身；B 換到的是「能改變 framework 元件位置」、付出的是「節點內部仍由 framework 管、外部行為仍可能變」
B 比 A 好的情境：framework 元件位置決定權需要奪回（例如 sidebar 切換）

C：改節點 attribute + fail-safe

機制：改 inline style / class、加 important + observer 補打
跟 A/B 的取捨：A 不碰 framework、C 介入 framework 元件本身的視覺行為；C 比 A 侵入性高、但比直接改內部安全
C 比 B 好的情境：需要的不是搬位置、是改顯隱 / 顏色 / state

D：改節點內部（最後手段）

機制：在 framework 子樹內 appendChild、改子節點屬性
成本特別高的原因：跟 framework reconciliation 直接競爭、bug 不可預測、升級可能徹底打破
D 才合理的情境：當前 framework 確認「該子樹不 reconcile」+ 升級時會重新驗證 — 通常不值得

邊界宣告的實踐

寫成 JSDoc 或 inline 註解

 1/**
 2 * 把 .pagefind-ui__filter-panel 從 drawer 搬到外部 sidebar。
 3 *
 4 * 邊界：
 5 *   - 動：filter-panel 整節點的 parent
 6 *   - 不動：filter-panel 內部子節點（由 pagefind 管）
 7 *   - State：checkbox 勾選由 pagefind 維護、跟著節點走
 8 *
 9 * 為什麼安全：節點 identity 不變、pagefind 在下次 patch
10 * 時看到節點還在、繼續更新內部。
11 */
12function place() {
13  if (mql.matches) sidebar.appendChild(filter);
14  else drawer.insertBefore(filter, drawer.firstChild);
15}

註解是給未來的自己 / 同事看的「契約備忘」 — 看到操作時知道為什麼安全。

跟其他原則的關係

抽象層原則	關係
#45 跟外部組件合作的層次	本篇是「邊界內 DOM 層」操作的具體規則 — 接受要進入這層、用本篇規則限制傷害
#43 最小必要範圍	操作範圍越小越安全 — 整節點 reparent 比改內部範圍小、改 attribute 比改子樹範圍小
#5 客製 UI 留邊界外	互補關係 — #5 處理「不動 framework 的策略」、本篇處理「必須動 framework 時的安全規則」

判讀徵兆

訊號	邊界問題	第一個該檢查的事
JS 操作後 framework 行為異常	動到內部子節點	確認操作只動「整節點 identity」、不動內部
Inline style 在某些互動後消失	動到 framework 管的 attribute	加 observer 補打、或改用 CSS class toggle
reparent 後 framework state 重置	整節點移動但 framework 看作刪除	確認框架對節點 identity 的追蹤機制（少數框架不靠 identity）
某些 querySelector 命中不該命中的元素	Selector 範圍超過自家元件	把 query 限縮到 self 元件根節點下（#14 selector 精準度）
「再加一段防禦邏輯應該就好了」第 2 次	整體策略可能該換層級（從 D 升到 C 或 B）	#42 2 次門檻、考慮換策略

核心原則：JS 動 framework 元件前、邊界先界定、選對應的安全規則。預設追求「完全不動 framework」(A)、必須動時用層級遞減的策略（B / C / D）— 每往下一層付的是「跟 framework 競爭」的成本。

Selector 精準度：讓 query 只命中你想要的元素

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

核心原則

JS 的 DOM query 從具體開始、發現不夠用再放寬。 Selector 涵蓋「最少必要範圍」、避免誤命中其他元素、避免未來頁面結構變動讓 query 撈到不該撈的東西。精準度有三個收斂維度：起點（從哪開始找）、範圍（找多深）、過濾（哪些不要）— 三者一起設計才完整。

為什麼精準度是 default

商業邏輯

DOM selector 的範圍越寬、被誤命中的可能性越高。寬泛 selector 像「網撈」 — 當下頁面只有一個目標元素時看不出問題、未來頁面結構變動（加第二個同類元件、加 demo 區塊、加 widget）就壞。

精準度的成本是「寫 selector 時多想一點」、收益是「行為可預測、不會被未來變動打破」。這不是優化、是 sanity 防線。

寬泛 selector 的失敗模式

失敗模式	表現	根因
跨元件誤命中	該動的動了、不該動的也動了	沒指定 ancestor scope
同名 class 誤命中	demo 區塊 / 文檔截圖也被處理	沒過濾「處於展示用途」的元素
未初始化元素被處理	元件還沒 mount 完就被操作	沒過濾「狀態未就緒」的元素
已處理元素重複處理	apply 被 observer 觸發又處理一次	沒標記「已處理」

四種失敗都來自「query 範圍 > 真實需要的範圍」。從具體開始就避免。

三層收斂維度

Selector 精準度不是單一參數、是三個維度的組合。每個維度都該設計、不能只想其中一個。

維度 1：起點（從哪個 root 開始找）

核心定義：query 的起點決定「最大可能範圍」。從 document 起 = 全頁面；從元件根起 = 子樹內。

1// 寬：全頁面搜尋
2document.querySelector('.pagefind-ui__result');
3
4// 收斂：從元件根開始
5var shell = document.querySelector('.search-shell');
6shell.querySelector('.pagefind-ui__result');

從元件根開始等於把 selector 的作用範圍收斂到「我管的子樹」 — 即使未來頁面其他地方出現同名元素、跟我無關。

起點選擇的決策：

起點	適用情境
`document`	確定全頁只有一個目標、且未來不會增加同類
元件根（變數存好）	一般情境（推薦預設）
函式參數傳入根	同頁面有多個元件實例、各自獨立 setup
事件 `closest` 反向找根	動態多實例、用事件驅動

多元件 setup pattern：

1function setupSearchShell(shell) {
2  var ui     = shell.querySelector('.pagefind-ui');
3  var input  = shell.querySelector('.pagefind-ui__search-input');
4  var drawer = shell.querySelector('.pagefind-ui__drawer');
5  // ... 其他 setup
6}
7
8document.querySelectorAll('.search-shell').forEach(setupSearchShell);

頁面有 N 個 shell、自動 setup N 次、各自獨立。當前只一個也適用、未來加更多無痛 — 這是「起點當參數」帶來的擴展性。

例外處理：當目標元素不在元件子樹內（例如同層的 sibling），保留 document.querySelector 但加註解說明：

1// slot 是 main 的子節點、跟 shell 同層、不能從 shell 找
2var slot = document.querySelector('.search-filter-slot');

註解讓未來維護者知道這是「明知故為」的例外、不是疏忽。

維度 2：範圍（找多深）

核心定義：起點確定後、要找直接子、特定層、還是任意深度。

querySelector 預設找任意深度 — 大部分情況沒問題、但結構穩定時可以更精準：

1// 預設：任意深度
2shell.querySelector('.pagefind-ui');
3
4// 限縮：只找直接子
5shell.querySelector(':scope > .pagefind-ui');
6
7// 限縮：只找特定層
8shell.querySelector(':scope > div > .pagefind-ui');

:scope 在 querySelector 內表示 query 的起始元素 — 配合 > 就能精準匹配「直接子」。

範圍選擇的決策：

範圍	適用情境
任意深度（預設）	結構可能變動、目標可能搬位置
直接子 `:scope > X`	結構穩定、避免深層誤命中
特定路徑 `:scope > A > B`	結構非常穩定、想要結構變動立即察覺

選太寬未來誤命中、選太窄未來結構微調就壞 — 預設選任意深度、結構穩定的關鍵 query 才用 :scope >。

維度 3：過濾（哪些元素不要）

核心定義：起點 + 範圍確定後、可能還是命中過多 — 用 attribute filter 與否定 selector 排除不要的。

1// 寬：所有 result
2shell.querySelectorAll('.pagefind-ui__result');
3
4// 過濾：只取已 rank 過的（排除初始化中的）
5shell.querySelectorAll('.pagefind-ui__result[data-pagefind-rank]');
6
7// 過濾：排除已處理過的
8shell.querySelectorAll('.pagefind-ui__result:not([data-scoped])');

過濾技巧：

技巧	用法
Attribute filter	`[data-state="ready"]` 只取狀態就緒的
`:not()` 排除	`:not([data-scoped])` 排除已處理
Attribute exists	`[data-pagefind-rank]` 只取有特定屬性的
處理後標記	處理完 `el.setAttribute('data-scoped', 'true')` 避免重複處理

「處理後標記」是 idempotency 工具：apply 函式可能被多次呼叫（observer 觸發、event 觸發），標記 + :not() 過濾確保每個元素只處理一次。

三維度的組合範例

完整的精準 selector 設計：

 1var shell = document.querySelector('.search-shell');           // 維度 1：起點
 2if (!shell) return;
 3
 4var results = shell.querySelectorAll(                          // 維度 2：任意深度
 5  '.pagefind-ui__result[data-pagefind-rank]:not([data-scoped])'  // 維度 3：過濾
 6);
 7
 8results.forEach(function (el) {
 9  // ... 處理
10  el.setAttribute('data-scoped', 'true');                      // 處理後標記
11});

每個維度都有意識地選擇 — 不是把所有預設值疊一起。

內在屬性比較：四種 selector 設計

設計	誤命中風險	未來結構變動的容忍度	多元件支援
`document.querySelector('.x')`	高	低 — 任何同名出現就壞	否（只取第一個）
`shell.querySelector('.x')`	低	中 — shell 內變動才影響	部分
`shell.querySelector(':scope > .x')`	最低	低 — 結構微調就壞	部分
起點當參數 + 過濾 + 標記	最低	高 — 顯式聲明所有假設	完整

推薦：起點當參數 + 過濾。:scope > 只在「結構保證穩定」的關鍵 query 用。

進階技巧

1. 把元件根存成變數一次

1var shell = document.querySelector('.search-shell');
2if (!shell) return;
3// 之後所有 query 都從 shell 開始

避免每次 query 都重新從 document 找元件根 — 一是效能（小）、二是 query 範圍仍維持在 shell 內。

2. 用 closest 反向找根

1function getShell(el) {
2  return el.closest('.search-shell');
3}
4
5document.addEventListener('click', function (e) {
6  var shell = getShell(e.target);
7  if (!shell) return;
8  // 在這個 shell 內處理
9});

事件委派 + closest 適合「多元件實例 + 動態事件處理」 — 各 shell 不需要各自綁 listener、共用一個 listener 用 closest 區分。

3. 起點不存在時提早 return

1var shell = document.querySelector('.search-shell');
2if (!shell) return;

頁面可能沒有 shell（不是搜尋頁），所有後續 query 都會失敗。提早 return 比後續一連串 null check 乾淨。

4. WeakMap 替代 attribute 標記

當不想污染 DOM attribute 時、用 WeakMap 紀錄已處理的元素：

1var processed = new WeakMap();
2
3shell.querySelectorAll('.pagefind-ui__result').forEach(function (el) {
4  if (processed.has(el)) return;
5  // ... 處理
6  processed.set(el, true);
7});

WeakMap 在元素 GC 時自動清理、不留下 DOM 痕跡。適合短生命週期的 idempotency。

設計取捨：起點選擇

Selector 的「起點」有四種做法、各自機會成本不同。這個專案選 B（元件根存變數）當預設、其他做法在特定情境也合理。每張卡片獨立展開該做法的設計細節。

A：`document.querySelector` 全文件搜

機制：每處 query 都從 document 開始、靠 class name 唯一性命中目標
適合：原型階段、demo 程式碼、確定全頁只有一個目標且未來不會變
代價：未來頁面結構變動（加同類 widget、加 demo 區塊）就壞、且失敗模式是安靜地操作錯元素、不報錯
選 A 的時機：「快速看會不會動」的探索期

B：元件根存變數、之後從變數 query（這個專案的預設）

機制：var shell = document.querySelector('.search-shell') 一次、之後所有 query 用 shell.querySelector(...)
選 B 的理由：當前頁面只有一個 shell、未來可能加（站內搜尋 widget、相關搜尋）— 用變數隔離成本低、提早預防
適合：一般客製情境、預期未來結構可能擴展
代價：多一個變數、多一次 query;函式內邏輯變得依賴外部變數

C：函式接受元件根當參數

機制：function setup(shell) { shell.querySelector(...) }、外部呼叫 document.querySelectorAll('.shell').forEach(setup)
跟 B 的取捨：B 假設只有一個 shell、C 直接支援多 shell；C 的設計成本前期較高（每函式多一個參數）、但多實例支援是免費的
C 比 B 好的情境：頁面同時有多個 shell（例如多語切換頁面）、或計劃中要重用組件到不同頁面

D：事件 + `closest` 反向找根

機制：監聽全域事件、事件處理時 e.target.closest('.shell') 反向找元件根
跟 B/C 的取捨：B/C 是「初始化時綁定」、D 是「事件發生時動態判斷」— D 適合元件動態出現 / 消失（SPA 路由切換、AJAX 注入）
D 比 C 好的情境：元件實例在 runtime 動態增減、用 mutation observer 補打成本反而更高
代價：事件委派的調試比直接綁定難（不知道事件實際從哪傳上來）

設計取捨：範圍深度

querySelector 預設找任意深度、可以收緊到直接子。三種做法：

A：任意深度（這個專案的預設）

機制：shell.querySelector('.target') — 子樹任何深度都接受
選 A 的理由：結構可能因 framework 升級微調、容忍微調換取維護彈性
代價：深層結構意外多出同名元素時可能誤命中

B：直接子 `:scope > X`

機制：shell.querySelector(':scope > .target') — 只找直接子
跟 A 的取捨：A 容忍結構微調、B 強制結構穩定 — B 帶來「結構變動立即報錯」的早期偵測
B 比 A 好的情境：自家完全控制的結構、想用 selector 失敗當回歸測試訊號

C：特定路徑 `:scope > A > B`

機制：強制一條精確路徑
代價：結構任何微調都壞、維護成本高
C 才合理的情境：寫整合測試的結構斷言、不是 production query

設計取捨：過濾與 idempotency

apply 函式可能被多次觸發（observer / event / 初始化）、過濾保證每元素只處理一次。三種做法：

A：DOM attribute 標記（這個專案的預設）

機制：:not([data-scoped]) 過濾 + 處理後 el.setAttribute('data-scoped', 'true')
選 A 的理由：標記跟著 DOM 元素走、元素被移除時自動清理；標記在 devtools 可見、debug 直接
代價：DOM 上多了一個自家用的 attribute（命名衝突風險小）

B：WeakMap 紀錄

機制：var processed = new WeakMap(); processed.set(el, true)
跟 A 的取捨：B 不污染 DOM、適合「不想留 attribute 痕跡」的場景；A 在 devtools 可見、debug 較直接
B 比 A 好的情境：寫成第三方函式庫、不想對使用者 DOM 加屬性

C：依賴外部呼叫者保證只呼叫一次

機制：apply 內不防護、依賴 init 時只綁一次 listener
成本特別高的原因：observer 觸發 / 事件觸發 / 初始化任一處多呼叫、就產生重複處理 bug；錯誤難以追蹤
C 才合理的情境：apply 本身是 idempotent 的（例如 set class 設成已是的值、無副作用）— 此時不需過濾

判讀徵兆

訊號	Selector 精準度問題	修正動作
多處 `document.querySelector` 同類元素	起點太寬	把元件根存變數、之後 query 從變數開始
同頁加第二個元件實例後行為錯亂	起點 hardcode	改「起點當參數」pattern
Selector 命中了不該命中的元素	範圍 / 過濾不足	加 ancestor scope、或加 attribute filter
Apply 被多次呼叫產生重複處理	沒 idempotency 防線	加 `:not([data-flag])` + 處理後標記
結構微調後 selector 失效	`:scope >` 用得太死	換成任意深度（預設）
事件處理時不知是哪個元件實例	沒反向找根機制	用 `closest`

核心原則：Selector 精準度不是極致最佳化、是 sanity 防線。三維度（起點 / 範圍 / 過濾）一起設計、每個維度都顯式選擇 — 比從寬泛開始一路追 bug 容易得多。

寬 selector（querySelectorAll('.title')）是「便利位置」、窄 selector 是「對齊位置」 — 這個反相關的更高層原則見 #67 寫作便利度跟意圖對齊反相關。

用前端測試把排版問題自動化

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

核心原則

當一個版型被 debug 兩次以上、就值得寫成 playwright 測試。 測試替代「手動檢查 + 截圖」的循環、讓版型回歸可被機器發現。下次有人改 CSS 時、測試會立刻指出哪個假設被破壞。

為什麼版型問題適合自動化

商業邏輯

排版問題的特徵：

特徵	對手動檢查的不利
邊界條件多（viewport、字型、互動狀態）	人眼難以涵蓋全部組合
變動觸發點不明顯（改 token、改 theme）	改一處不知道哪裡會壞
視覺問題往往來自相對關係	截圖只看絕對位置、看不出關係

人腦適合「驚訝時注意」、不適合「重複檢查 100 個 case 是否如預期」。後者是機器擅長的。

兩種測試層次

層次	測什麼	工具
視覺迴歸	整頁與基準截圖比對	Percy / Chromatic / Playwright snapshot
結構斷言	特定元素的位置 / 尺寸 / 順序	Playwright `browser_evaluate` + `expect`

兩種互補。視覺迴歸抓「整頁有沒有變」、結構斷言抓「特定關係有沒有保持」。

這次任務的測試機會

觀察

搜尋頁的版型在這次開發中被 debug 多輪：

場景	Debug 次數
Filter sidebar 跨 viewport 顯示 / 隱藏	5+
Scope UI 三狀態下的位置	4+
結果區跟 sidebar 頂端對齊	3+
Filter 順序 type 在前	2

判讀

每個 debug 過 ≥ 2 次的版型場景都值得寫測試 — 表示這個地方很容易壞、未來改 CSS 還會踩。

執行：寫 playwright 測試

 1// tests/search-layout.spec.js
 2import { test, expect } from '@playwright/test';
 3
 4test.describe('search page layout', () => {
 5  test('desktop ≥ 1400 顯示左側 filter sidebar', async ({ page }) => {
 6    await page.setViewportSize({ width: 1440, height: 900 });
 7    await page.goto('/blog/search/');
 8    await page.fill('.pagefind-ui__search-input', 'pre');
 9    await page.waitForSelector('.pagefind-ui__filter-panel');
10
11    const slot = await page.$('.search-filter-slot');
12    const isVisible = await slot.isVisible();
13    expect(isVisible).toBe(true);
14
15    const filterParent = await page.evaluate(() =>
16      document.querySelector('.pagefind-ui__filter-panel').parentElement.className
17    );
18    expect(filterParent).toContain('search-filter-slot');
19  });
20
21  test('viewport < 1400 filter 留在 pagefind drawer', async ({ page }) => {
22    await page.setViewportSize({ width: 1024, height: 900 });
23    await page.goto('/blog/search/');
24    await page.fill('.pagefind-ui__search-input', 'pre');
25    await page.waitForSelector('.pagefind-ui__filter-panel');
26
27    const filterParent = await page.evaluate(() =>
28      document.querySelector('.pagefind-ui__filter-panel').parentElement.className
29    );
30    expect(filterParent).toContain('pagefind-ui__drawer');
31  });
32
33  test('scope UI 在三互動狀態下都在 input 與 results 之間', async ({ page }) => {
34    await page.setViewportSize({ width: 1440, height: 900 });
35    await page.goto('/blog/search/');
36
37    async function getY(selector) {
38      return page.evaluate(s => document.querySelector(s).getBoundingClientRect().y, selector);
39    }
40
41    // 狀態 1：初始載入
42    let scopeY = await getY('.search-scope');
43    let inputY = await getY('.pagefind-ui__search-input');
44    expect(scopeY).toBeGreaterThan(inputY);
45
46    // 狀態 2：點 input
47    await page.click('.pagefind-ui__search-input');
48    scopeY = await getY('.search-scope');
49    inputY = await getY('.pagefind-ui__search-input');
50    expect(scopeY).toBeGreaterThan(inputY);
51
52    // 狀態 3：輸入字
53    await page.fill('.pagefind-ui__search-input', 'pre');
54    await page.waitForSelector('.pagefind-ui__results .pagefind-ui__result');
55    scopeY = await getY('.search-scope');
56    inputY = await getY('.pagefind-ui__search-input');
57    const resultsY = await getY('.pagefind-ui__results');
58    expect(scopeY).toBeGreaterThan(inputY);
59    expect(scopeY).toBeLessThan(resultsY);
60  });
61});

每個 expect 對應一條版型契約 — 這條被破壞時測試紅、改 CSS 的人立刻知道。

測試的維護成本與收益

內在屬性比較

屬性	手動檢查	Playwright 測試
首次成本	低 — 開頁面看	中 — 寫測試
重複成本	高 — 每次回歸都要全部看	低 — 自動跑
涵蓋率	低 — 受人記憶限制	高 — 跑所有 case
規範化	否 — 知識在腦中	是 — 寫成可讀的 expect
教學價值	低 — 新人需要被告知	高 — 測試本身是文件

第 1 次寫成本中、第 2 次以後成本碾壓手動。門檻在「會 debug 第 2 次嗎」。

測試什麼、不測什麼

適合測試的版型場景

跨 viewport 的元件顯示 / 隱藏切換
元件相對位置（A 在 B 上方 / 下方 / 左右）
元件順序（type 在 tag 前）
互動狀態下的位置不變（scope 在三狀態下都在 input 與 results 之間）

不適合用 playwright 測

純視覺差異（顏色微差、圓角 1px 差） — 用 visual regression 工具
動畫過程 — 不穩定、容易 flaky
字型 rendering 細節 — 跨 OS / 瀏覽器差異大

選擇原則：測「結構性契約」、不測「畫素」。畫素級檢查交給 visual regression。

設計取捨：版型驗證機制的選擇

四種做法、各自機會成本不同。這個專案在版型 debug ≥ 2 次後選 A（結構斷言測試）當預設、其他做法在特定情境合理。

本篇是 #42 2 次門檻抽象原則在「驗證機制升級」這個面向的應用。

A：Playwright 結構斷言測試（這個專案的預設）

機制：寫 expect(scopeY > inputY) 這類斷言、自動跑、跨字型 / 主題都對
選 A 的理由：規範化（測試本身是文件）、跨環境穩定、回歸自動偵測
適合：debug ≥ 2 次的版型場景、需要長期保護的 layout 契約
代價：寫測試的初始成本、需要 playwright runtime

B：手動截圖檢查

機制：開頁面、看截圖、人眼確認
跟 A 的取捨：B 起步成本 0、A 起步成本中；但 B 重複成本高（每次回歸都要看）
B 比 A 好的情境：第 1 次驗證（debug 過 1 次、不確定值不值得寫測試）、純探索期

C：Visual regression snapshot

機制：截整頁圖跟 baseline 比對、像素級差異
跟 A 的取捨：C 涵蓋率廣（整頁所有變動都偵測）、A 只測指定契約；但 C false positive 多（字型微調 / theme 換色都觸發）
C 比 A 好的情境：純視覺驗證（marketing page）、設計穩定不常改

D：不寫測試

機制：純信任手動驗證
跟 A 的取捨：D 0 維護成本、A 有測試維護；但 D 在版型反覆壞時累積「腦中知識」、新人接手不知道
D 才合理的情境：純探索期 / prototype、確定不上 production

判讀徵兆

訊號	應該寫測試的時機	第一個該寫的 expect
同一個版型 bug 出現第 2 次	立刻寫	把當時的 fix 寫成 expect
改 token / theme 時不確定哪些頁面會壞	把對 token 敏感的頁面寫測試	元件相對位置、寬度比例
跨 viewport 的響應式邏輯複雜	寫 viewport 切換測試	不同寬度下元件顯示 / 位置
互動狀態下版型不穩定	寫狀態切換測試	各狀態下關鍵元素的位置關係

核心原則：版型契約用測試固定 — 測試紅了表示契約被打破、不是測試壞了。每個紅色測試都是有人改了不該改的東西的訊號。

跟 #68 驗收的時間軸的關係：layout test 是 Checkpoint 3「Ship 前」的具體做法 — 跨 viewport / 跨狀態 / 跨資料規模驗收、catch 開發中 checkpoint 看不到的整合錯。沒寫 layout test = 把 ship 前 checkpoint 跳過、所有版型回歸都進 ship 後（使用者反映才修）。

寫完 layout test 必須在「未修版型」跑 RED 確認測試會抓到該抓的、再在「修後版型」跑 GREEN 確認修對了 — 兩個訊號都看到、測試才被驗證。詳見 #69 Test-First：先看到 RED 才相信 GREEN。

空間 / 尺寸類指令的澄清時機

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

核心原則

空間 / 尺寸類指令缺少明確數值時、先列計算過程或假設、確認後再實作。 直接用估算寫死會在使用者實際看到結果時才被發現不對、引起多輪試錯。澄清的成本是「多打一句話」、收益是「一次到位」。

為什麼空間指令需要澄清

商業邏輯

「對齊」「擺在旁邊」這類描述是關係性指令 — 描述了兩個元素的相對位置，但沒給絕對數值。實作時需要把關係轉成具體數字（padding 多少、top 多少）。

執行者依憑感覺取數字 = 用自己的估算代替使用者的意圖。估算與意圖不一致時、使用者看到結果才知道、糾正成本高。

把計算過程列出來確認 = 把「估算」變成「協商」 — 使用者有機會在實作前指正。

這次任務的實際情境

觀察

情境	指令	我的處理	結果
Filter 的 padding 對齊	「padding 對齊到搜尋欄下緣」	估算 padding-top: 152px 寫死	視覺差 ~10px、要重做
Breakpoint 取值	「桌面顯示左欄、手機隱藏」	取 768px 寫死	視窗 1200 時看不到 filter、要重做
Filter 寬度	「左欄 400px」	直接用 400	一次到位

第三個是少數有明確數值的情境、那次一次到位。前兩個沒給數字、靠估算、結果都要重做。

判讀

差別在「使用者有沒有給確定值」。沒給時、執行者該做的不是「自己決定」、是「把計算列出來確認」。

執行：澄清 protocol

收到空間 / 尺寸類指令時、先檢查：

檢查項	動作
使用者給了具體數值嗎？	是 → 直接用；否 → 進下一步
我能依據已知元件尺寸推算嗎？	是 → 列出計算過程確認；否 → 直接問
推算依賴的假設明確嗎？	是 → 列出假設與數字；否 → 列出選項供選擇

例：

「padding 對齊到搜尋欄下緣 — 我會用 H1 64px + form 68px = 132px 當基準、加 8px buffer 共 140px、OK 嗎？或是你想要其他數字？」

把計算過程攤開、使用者可以指正「H1 沒這麼高、應該 70px」、避免實作後重做。

內在屬性比較：四種空間指令處理方式

處理方式	一次到位機率	重做成本	適用情境
直接照使用者給的數值寫	100%	無	使用者明確給數值
列計算過程確認後寫	高	低	數值可推算
用估算值寫、之後再調	中	中 — 一兩輪	視覺差容易調的場景
不確認直接寫死	低	高 — 多輪試錯	不適用

優先順序：有數值用、可算就算、估算寫死最後選。

列計算的好習慣

1. 攤開假設

1計算 filter padding-top：
2  H1 height = 64px（假設、實際看 theme 渲染可能不同）
3  Form height = 68px（pagefind input 64 + border 4，鎖定 scale=1.0）
4  Gap = 20px（pagefind drawer 預設 margin-top）
5  Total = 152px

每個值來源寫清楚 — 使用者可以指出某個假設錯了。

2. 用變數表達

1padding-top: calc(var(--search-title-h) + var(--search-form-h) + var(--search-gap));

使用變數取代 magic number — 改一處全部跟著動、未來調整成本低。

3. 區分「設計值」與「量測值」

值類型	來源	例子
設計值	設計師決定的固定值	filter 寬度 400px
量測值	runtime 才知道	scope UI 高度（受字型換行）
推算值	由其他值計算	filter padding = title + form + gap

確認時把每個值的類型寫清楚、使用者知道哪些是「我可以決定」、哪些是「實作時才知道」。

設計取捨：空間/尺寸指令的處理策略

四種做法、各自機會成本不同。這個專案在缺數值時選 A（列計算過程確認）當預設、其他做法在特定情境合理。

A：列計算過程確認後實作（這個專案的預設）

機制：把計算過程與假設攤開、給使用者確認、再用 calc(var(...) + var(...)) 實作
選 A 的理由：使用者能指正特定假設（不只「對」「不對」）、實作後改 token 自動跟上
適合：缺數值的空間 / 尺寸指令（大多數情境）
代價：多一輪對話確認

B：直接照使用者給的數值寫

機制：使用者給「filter 寬 400px」就直接 width: 400px
跟 A 的取捨：B 一次到位、無需確認；前提是使用者已給確切數值
B 比 A 好的情境：使用者明確指定數值、執行者只需照寫

C：用估算值寫、之後再調

機制：執行者依感覺給數字（「padding-top: 152px」）、寫了之後等使用者試
跟 A 的取捨：C 看似省溝通成本、實際把確認延後到實作後；C 在估算錯時要重做
C 才合理的情境：視覺差容易調（< 5px 微差）、且確認成本比實作高（罕見）

D：不確認直接寫死

機制：執行者自己決定數值、不問也不告知
成本特別高的原因：跟使用者意圖不一致時要重做、多輪試錯
D 是反模式：「使用者會看到的數字」屬於該確認的決定（#21 可決定 vs 該先確認）— 自決會跟意圖不一致、被退回時白做

判讀徵兆

訊號	應該觸發澄清的指令	第一個該確認的
「對齊到 X」	對齊基準是 X 的哪個邊（top / bottom / center）？	基準位置
「靠在 Y 旁邊」	多近？同 row 還是 above / below？	相對方向與距離
「desktop 顯示、mobile 隱藏」	Breakpoint 多少 px？	viewport 切換點
「跟 Z 一樣高」	Z 的高度是固定還是動態？	量測 vs 寫死
「適中的 padding」	「適中」對應多少 px？	給選項供選擇

核心原則：空間關係描述只是意圖、不是實作數字。把意圖翻譯成數字的過程要對外可見、讓使用者參與。

第三輪指令類型現有五類：空間（本卡）/ 相對位置（#17）/ 隔離（#18）/ 決定權（#21）/ 篩選（#58）。前四類缺幾何 / 邊界 / 拍板資訊、第 5 類缺操作層級資訊。

元件相對位置類指令的澄清時機

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

核心原則

相對位置指令（「X 在 Y 旁邊」「Y 顯示在 main 左側」）是模糊的 — 同一句話可以對應多種 layout 結構。實作前用文字描述意圖中的 layout 草圖、讓使用者確認後再寫 CSS。沒確認直接擺、實作出來常與使用者預期不同、要重做。

為什麼相對位置需要澄清

商業邏輯

「X 在 Y 旁邊」這類描述至少對應四種 layout 實作：

實作方式	視覺結果
Y 與 X 同 row、grid / flex 並排	並排、Y 影響 X 寬度
X absolute 浮在 Y 旁邊	並排、X 不影響 Y
Y 與 X 不同層、Y 在 main 內、X 在 main 外	跨 main 邊界、視覺感不同
X fixed 永遠在 viewport 同位置	隨捲動固定、Y 隨內容捲動

執行者選哪種、結果不同。憑直覺選 ≠ 使用者意圖。

這次任務的實際情境

觀察

指令	我的初次理解	使用者實際意圖
「scope UI 在搜尋框附近」	放搜尋框上方	應該在搜尋框下方
「filter 在主欄左側」	放進 main 的 grid 左 column	是 main 外的 absolute sidebar
「左右兩欄獨立排版」	同 grid container 兩個 column	兩個獨立 layer、用 absolute 疊層

每個指令都讓我選了使用者沒想要的實作。

判讀

問題在「相對位置」這類描述本質就是模糊的 — 沒指定座標系、沒指定相對層級、沒指定誰是 layout flow 主角。

執行前該做的：把我準備寫的 layout 用文字描述出來、讓使用者確認意圖一致。

執行：layout 草圖 protocol

收到相對位置指令時、先寫文字草圖：

1我準備這樣寫：
2  - main 維持 70ch 置中（layout flow 主角）
3  - filter 用 absolute 浮在 main 左外側、寬 400px、間距 2rem
4  - scope UI 在 main 內、緊接 search input 下方、結果上方
5  - 三者位置關係：filter 與 main 同 viewport 中段、scope 在 main 內
6
7確認對應你的意圖嗎？或是想要不同安排？

把意圖中的 layout 結構攤開 — 使用者可以指正「filter 應該在 grid 內、不是 absolute」、避免實作後重做。

內在屬性比較：四種相對位置描述

描述方式	模糊度	適用情境
純位置詞（「在旁邊」「在下方」）	高	初步對話、需要追問
加層級指示（「在 main 內」「跨 main 外」）	中	縮小範圍
加 layout 結構（「同 grid」「absolute 疊層」）	低	接近實作
文字草圖 + 確認	最低	實作前最後確認

執行者該主動把對話從「純位置詞」推到「文字草圖 + 確認」 — 縮小模糊範圍。

文字草圖的好習慣

1. 描述 layout 主角

哪個元素是「決定其他元素位置的 anchor」？通常是內容主體（main、article）。其他元素相對這個主角描述。

1Layout 主角：main（70ch 置中）
2其他元素：
3  - H1：main 內、第一個元素
4  - filter：main 左外側 400px
5  - footer：main 之後

2. 描述層級關係

哪些元素在同一 layout 流、哪些是疊層？

1Layout flow 內：H1、search input、results
2疊層：
3  - filter：absolute、浮在 main 左外
4  - scope UI：absolute、浮在 search input 下方

3. 描述 viewport 行為

不同 viewport 下、layout 怎麼變？

1Desktop ≥ 1400：filter 顯示在左外、scope UI 浮在 input 下方
2Mobile < 1400：filter 移到 pagefind drawer 內、scope UI 維持原位

對使用者描述 layout 的格式

Inline ASCII 草圖

文字環境下、ASCII 比 PNG 圖更實用：

1┌────────────┬──────────────────┐
2│            │ H1 搜尋           │
3│ filter     ├──────────────────┤
4│ (sticky)   │ Search input     │
5│            ├──────────────────┤
6│            │ Scope UI         │
7│            ├──────────────────┤
8│            │ Results          │
9└────────────┴──────────────────┘

幾秒鐘畫出來、使用者一眼看出意圖、可以指正特定區域。

敘述列表

不畫圖也可以列：

1從上到下、從左到右：
2  1. 左欄：filter（400px、main 外、sticky）
3  2. 右欄：
4     a. H1 搜尋
5     b. Search input（中央欄）
6     c. Scope UI（input 下、results 上）
7     d. Results

兩種格式選一種、確認後再寫 CSS。

設計取捨：相對位置指令的處理策略

四種做法、各自機會成本不同。這個專案選 A（文字草圖確認）當預設、其他做法在特定情境合理。

A：文字 layout 草圖 + 主角/疊層說明確認（這個專案的預設）

機制：把意圖翻成「main 70ch 置中、filter absolute 浮在 main 左外、scope 在 main 內 absolute 浮在 input 下」這類具體描述、使用者確認
選 A 的理由：草圖 30 秒打完、使用者 30 秒內 yes/no、避免寫完 CSS 才被指正
適合：相對位置指令的多數情境
代價：多 30 秒對話成本

B：ASCII 圖更詳細

機制：用 box-drawing 字元畫實際 layout 草圖
跟 A 的取捨：B 視覺直觀、A 文字描述更精確；B 對複雜 layout 表達力強
B 比 A 好的情境：layout 涉及 ≥ 4 個區塊、文字描述容易混淆

C：加層級指示（中間步驟）

機制：「filter 在 main 外的 sidebar」（不是「在 main 旁邊」）
跟 A 的取捨：C 比純位置詞具體、比草圖簡略；用於初步對話
C 比 A 好的情境：對話初期、還沒到實作決策的階段

D：純位置詞直接實作

機制：照「filter 在 main 旁邊」字面意思挑一種實作
成本特別高的原因：同一句話對應多種 layout 結構、選錯就重做
D 是反模式：「相對位置」永遠模糊、跳過確認等於賭 — 選錯重做的成本遠大於確認的對話成本

判讀徵兆

訊號	應該觸發澄清的指令	第一個該確認的
「X 在 Y 旁邊」	同 row 還是疊層？X 影響 Y 的位置嗎？	Layout 結構（grid / absolute）
「Y 顯示在 main 左側」	在 main 內的 column 還是 main 外的 sidebar？	跨界與否
「左右兩欄獨立」	「獨立」是 DOM 獨立、layout 獨立、還是 state 獨立？	隔離程度
「跟 Z 對齊」	Z 的哪個邊（top / bottom / left / right）？	對齊基準

核心原則：相對位置描述只是意圖、不是實作藍圖。實作前先把意圖畫成 layout 草圖、確認後再開工。

第三輪指令類型現有五類：空間（#16）/ 相對位置（本卡）/ 隔離（#18）/ 決定權（#21）/ 篩選（#58）。

隔離程度類指令的澄清時機

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

核心原則

「隔離」「不要動 X」是描述意圖的詞、不是描述實作的詞。 實作前先確認隔離邊界是哪一種：DOM 結構、layout flow、state、framework 管轄區。每種邊界的實作策略不同、混淆會做出不符合使用者意圖的隔離。

為什麼隔離需要澄清

商業邏輯

「隔離」這個詞涵蓋多種獨立的概念：

隔離類型	含義	實作策略
DOM 結構隔離	兩個元件不在同一 DOM 子樹	分開放在不同 ancestor
Layout flow 隔離	一個元件的 layout 不影響另一個	absolute / fixed 跳出 flow
State 隔離	兩個元件的 state 互不影響	各自有獨立 state container
Framework 管轄區隔離	客製 UI 與 framework UI 各自管自己	客製 UI 留在 framework 邊界外

每種需要的實作完全不同。執行者選錯邊界 = 做了不符合使用者意圖的「隔離」。

這次任務的實際情境

觀察

指令	我的初次理解	使用者實際意圖
「不動 pagefind 行為」	不改 pagefind 的 search 邏輯	包含「不在 pagefind DOM 內塞客製元素」
「左右不要在同一層」	DOM 層級分開	Layout flow 互不影響（用 absolute 疊層）

「不動 pagefind 行為」這句、我多次把 scope UI 注入 pagefind DOM、違反使用者的隔離意圖 — 我以為「不動」只指邏輯、實際包含 DOM 結構。

判讀

執行前該確認：「不動 / 隔離」的邊界是哪一種類型？

執行：邊界類型確認 protocol

收到隔離類指令時、列四種可能的邊界：

1你說的「不動 pagefind」涵蓋哪些？
2  □ 不改 pagefind 的搜尋邏輯（不 fork / patch source）
3  □ 不改 pagefind 渲染的 DOM 結構（不在內部 appendChild）
4  □ 不改 pagefind 的 state（checkbox 勾選等）
5  □ 完全不互動（連 CSS 都不覆寫）

使用者勾選對應項、執行者照那個邊界實作。

或更簡單的問法：「具體來說、什麼算動、什麼不算動？」

內在屬性比較：四種隔離邊界的特徵

邊界類型	偵測方式	違反的後果
DOM 結構	看 ancestor chain 是否相同	一個元件可能影響另一個的 layout / 樣式
Layout flow	看是否在同一 flow（grid / flex / block）	一個元件撐開影響另一個位置
State	看 state 是否共用 store	一個元件改 state 影響另一個顯示
Framework 管轄區	看是否在 framework 渲染週期內	Framework patch 時客製被清掉

執行前確認邊界類型 — 不確定就問。

隔離邊界的辨識技巧

1. 從「會發生什麼」反推

問使用者：「如果 X 改了、Y 應該也跟著改嗎？」

答案	對應邊界
是 — Y 跟著動	沒有隔離、共用 state
否 — Y 不動	State 隔離
否 — 連 layout 都不變	Layout flow 隔離
否 — Y 完全感知不到 X	DOM 隔離

2. 從「動誰會壞」反推

問：「我能在哪個 DOM 區域加東西？」

答案	對應邊界
任何地方都可以	沒有隔離
自家元件內可以、X 元件內不行	Framework 管轄區隔離
自家元件內也要小心、不能影響 X 的 layout	Layout flow 隔離
完全分開、不能放在同一 DOM 子樹	DOM 結構隔離

3. 從「升級時誰要動」反推

問：「X 升級時、我們要回頭改什麼嗎？」

答案	對應邊界
不用、客製跟 X 完全分開	DOM + framework 管轄區隔離
可能要調整客製 CSS	Layout / state 邊界內客製
客製要重做	沒有隔離、客製深入 X 內部

設計取捨：隔離指令的處理策略

四種做法、各自機會成本不同。這個專案選 A（列邊界類型確認）當預設、其他做法在特定情境合理。

A：列四種邊界類型確認（這個專案的預設）

機制：列出 DOM 結構 / layout flow / state / framework 管轄區四選項、使用者勾選對應項
選 A 的理由：明確 + 完整、使用者快速指出真正想要的隔離
適合：隔離意圖不明確的情境
代價：多一段四選項描述

B：反推法（從「會發生什麼」「動誰會壞」反推）

機制：問「如果 X 改了、Y 應該也跟著改嗎？」「我能在哪個區域加東西？」根據答案歸類邊界
跟 A 的取捨：B 對使用者比較不負擔（不需理解四種邊界術語）、A 直接呈現答案空間
B 比 A 好的情境：使用者不熟悉 DOM / layout / framework 術語

C：依直覺選一種實作

機制：執行者自己解讀「隔離」、選一種實作
跟 A/B 的取捨：C 跳過確認、A/B 確認；C 在意圖一致時省時間、不一致時重做
C 是反模式：「隔離」這個詞本身就太模糊、跳過確認等於賭 — 意圖不一致時重做的成本遠大於確認的對話成本

D：通用問法「具體什麼算動」

機制：直接問「具體來說、什麼算動、什麼不算動？」
跟 A 的取捨：D 比 A 更簡略、把分類負擔丟給使用者；A 直接給選項使用者只需勾選
D 比 A 好的情境：使用者已經想得很清楚、只需要表達 — A 反而過於 structured

判讀徵兆

訊號	應該觸發澄清的指令	第一個該確認的
「不要動 X」	動哪個層面（邏輯 / DOM / state / 樣式）？	邊界類型
「X 跟 Y 隔離」	隔離 DOM、layout、state、還是 framework？	邊界類型
「X 跟 Y 獨立」	獨立指什麼？哪個改不影響另一個？	哪個維度獨立
「X 不能影響 Y」	影響的方式（layout / state / 樣式）？	影響途徑

核心原則：隔離指令的核心是「隔離邊界類型」 — 這個答案決定實作策略。沒確認邊界就動手 = 隨機選一種隔離、可能與使用者意圖不一致。

第三輪指令類型現有五類：空間（#16）/ 相對位置（#17）/ 隔離（本卡）/ 決定權（#21）/ 篩選（#58）。

覆寫深度的成本告知

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

核心原則

覆寫成本要在開工前報、不能默默承擔。 客製要對抗多層（UA 預設 + 跨瀏覽器 + framework specificity）時、先把「需要寫多少 / 哪幾條 / 是否有殘留風險」攤開、讓使用者用「視覺改善 vs 維護成本」的角度判斷值不值。

為什麼成本要事先告知

商業邏輯

執行者單方決定「這客製值不值得做」會出現兩種失敗：

失敗模式	表現
執行者覺得值得、使用者覺得太貴	寫了 5 條 CSS 後使用者說「先還原」、白做
執行者覺得不值、使用者覺得很重要	沒做、使用者覺得敷衍

兩種失敗都來自「成本與價值的判斷沒對齊」。把成本攤開讓使用者參與判斷、避免兩種失敗。

這次任務的實際情境

觀察

要移除 Pagefind filter 的

disclosure 三角圖示。

我嘗試了：

 1/* 1. UA 預設 marker（Chrome / Firefox） */
 2summary::marker { content: ""; color: transparent; font-size: 0; }
 3/* 2. UA 預設 marker（Safari / 老 Chrome） */
 4summary::-webkit-details-marker { display: none; }
 5/* 3. 改 summary display 避免 list-item 行為 */
 6summary { display: block; list-style: none; }
 7/* 4. 蓋過 pagefind 的 ::after 自訂 chevron */
 8.pagefind-ui__filter-name::after { display: none !important; }
 9/* 5. 處理 reset 邊界外的 fallback */
10/* ... */

寫完後使用者說：「如果要做到這麼大的複寫原設計、先還原回去、先不要做這個變更」。

判讀

我的失敗：開工前沒報「這個客製需要對抗 UA + 跨瀏覽器 + framework 三層、預估 5+ 條 CSS、跨瀏覽器有殘留風險」。直接做、使用者看到改動規模才退回。

正確流程應該在嘗試第 2 條 CSS 時就停下來報告：

移除 disclosure 三角需要對抗：

UA 預設 marker（Chrome / Firefox 的 ::marker、Safari / 老 Chrome 的 ::-webkit-details-marker）

Summary 預設 display: list-item 行為

Pagefind 的自訂 ::after chevron

預估 4-5 條 CSS 跨 3 種瀏覽器寫法、可能有殘留風險（::marker 在某些瀏覽器版本不能用 display: none）。

視覺改善：filter 名稱旁邊少一個小三角。

值得做嗎？

讓使用者判斷再決定。

執行：覆寫成本告知 protocol

開始任何客製前、先評估這三個累積層：

層	評估問題
UA 預設	跨瀏覽器有差異嗎？需要寫幾種 pseudo？
Framework specificity	框架 CSS 用 hash class 提升 specificity 嗎？需要 layers / important / 雙寫嗎？
Framework 渲染週期	改了會被 reset 嗎？需要 observer 補打嗎？

任一層有「需要對抗」就把成本報出來、讓使用者參與決定。

內在屬性比較：四種覆寫深度

深度	成本	適合的視覺改善
1 條 CSS、單一瀏覽器	低	任何
1-2 條 CSS、跨瀏覽器（用 layers / important）	中	影響 UX 的視覺改善
3+ 條 CSS、跨瀏覽器 + framework	高	必要的核心客製
跨 framework 渲染週期、需要 observer 補打	最高	改善價值極高才值得

「成本 vs 改善價值」的對應 — 高成本只用在高價值場景。

告知時機與格式

觸發點

訊號	應該停下來告知
寫到第 2 條 CSS 還沒蓋過原設計	是 — 這通常表示有第二、第三層問題
跨瀏覽器寫法（`-webkit-`、`::marker` 雙寫）	是 — 跨層成本累積
加 `!important`	是 — specificity 戰開始
加 observer 補打防 reset	是 — 跟 framework 渲染週期競爭

報告格式

1這個客製需要：
2  - 對抗 [UA / framework / 跨瀏覽器]：N 條 CSS
3  - 殘留風險：[列出可能在某些情境失效的 case]
4  - 改善價值：[視覺差異、UX 改善]
5  
6值得做嗎？或先接受原設計？

讓使用者用「成本 vs 價值」做決定。

設計取捨：客製深度告知的時機

四種做法、各自機會成本不同。這個專案選 A（開工前評估 + 第 2 條 CSS 失敗即告知）當預設、其他做法在特定情境合理。

A：開工前評估三層成本、開工後第 2 條失敗即告知（這個專案的預設）

機制：開工前評估 UA / framework / 渲染週期三層；開工後寫到第 2 條 CSS 還沒蓋過就停下告知
選 A 的理由：使用者參與「值不值」判斷、避免做到一半被退回
適合：所有有覆寫嫌疑的客製
代價：對話成本（一段成本評估 + 等決定）

B：寫到第 N 條才告知（N > 2）

機制：執行者自己加碼、到 4-5 條才停
跟 A 的取捨：B 給執行者更多嘗試空間、A 早提早決；B 在 N 增加時白費時間放大
B 是反模式：第 2 次失敗就是 #42 2 次門檻的訊號、繼續加碼只是放大沉沒成本

C：默默寫到底、不告知

機制：執行者自己承擔、不報告成本
成本特別高的原因：使用者看到改動規模才退回、所有時間白費
C 才合理的情境：客製極簡（< 1 條 CSS）、確定不會對抗任何層

D：開工前直接接受原設計、不嘗試

機制：看到客製需求是「對抗多層」就直接拒絕、不寫
跟 A 的取捨：D 完全省成本、A 留空間給「值得做」的客製
D 比 A 好的情境：使用者明確說「這是視覺微調」+ 對抗三層、且預估成本高 — 直接接受原設計

判讀徵兆

訊號	該觸發告知的時機	報告內容
寫到第 2 條 CSS 還沒蓋過原設計	立刻	列出對抗的層、預估還要寫多少
加跨瀏覽器寫法（pseudo 雙寫）	立刻	UA 差異、各瀏覽器寫法
加 `!important`	立刻	Specificity 戰開始、考慮 layers
加 observer 補打	立刻	跟 framework 渲染競爭、可能不穩
改善價值不明顯（純視覺微調）	開工前	列改善內容、讓使用者衡量

核心原則：客製成本是使用者該知道的資訊、不是執行者單方承擔。事先告知 = 共同決定 = 不會做到一半被退回。

成本告知有兩種時機 — 本卡聚焦「實作前告知工程成本」、runtime 持續顯示掃描成本見 #62 Pattern：誠實進度 UX。共同精神是「不 silent 累積負擔」。

同方向反覆失敗的轉折點

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

核心原則

第 2 次同方向失敗、停下來回報「假設可能錯了、要不要換思路」。 失敗 ≥ 2 次大多是底層假設有問題、不是執行細節有問題。繼續沿同一方向加碼（換更複雜的 selector、加 !important、再寫一層 polyfill）只會放大原本的問題。

為什麼第 2 次是轉折點

商業邏輯

第 1 次失敗常是執行細節（typo、特定 syntax、瀏覽器 cache）— 修正後可能就過。

第 2 次失敗、用同樣的方法但更小心、還是失敗 — 這個訊號的重量遠大於兩次失敗的相加。它說的是「我以為的問題不在這層、根本問題在別處」。

第 3 次以上的失敗、加上「再試一次更小心」的努力、產生的副作用會超過解決的問題：

嘗試次數	心理狀態	行動模式	可能副作用
1	信心足	直接做	無
2	信心動搖	加碼（更複雜的 selector / important）	可控
3	焦慮	全面反擊（layers + important + polyfill）	大 — 改動範圍擴張
4+	沉沒成本綁住	不肯放棄已寫的	嚴重 — 為前面的錯買單

第 2 次是還能優雅切換方向的最後機會。

這次任務的實際情境

觀察

要把 search scope UI 放在「搜尋框與結果之間」。我嘗試了：

嘗試	方向	結果
1	Display: contents 串接 + grid-row 排序	失敗 — scope 跑到頁尾
2	加 `!important` 強化 grid-row	失敗 — 沒改善
3	Specificity 雙寫（`.x.x`）	失敗 — 沒改善
4	加更多 display: contents 層	失敗 — 同樣結果
5（被使用者制止）	「思路錯了、換方向」	改用 absolute 定位、一次成功

四次失敗都基於同一假設：「drawer 是 .pagefind-ui 的直接子節點」。實際 drawer 在 form 內。

判讀

第 2 次失敗時就應該停下來檢查假設、不該再往同方向加碼。

正確流程：第 1 次失敗修細節；第 2 次失敗用 playwright 量 DOM 確認假設；發現假設錯就立刻換方向、不要為前面的努力買單。

執行：失敗計數與行動

失敗次數	行動
第 1 次	修細節（typo、cache、syntax）
第 2 次	停下來 — 用工具驗證底層假設（DOM tree、computed style、framework 行為）
第 2 次驗證後	假設對 → 繼續修；假設錯 → 換方向、不為前面買單

關鍵是第 2 次的「停」 — 把行動從「執行更努力」切換到「驗證假設」。

內在屬性比較：四種失敗應對

應對	適用次數	風險
修細節再試	1 次	低 — 假設沒問題的話通常成功
停下來驗證假設	2 次	低 — 確認方向是否正確
加碼（important / 雙寫 / polyfill）	不適用	高 — 假設錯時放大問題
換方向（重新設計實作）	2 次後驗證假設錯	中 — 一次性成本、後續穩定

選擇規則：第 1 次修細節、第 2 次驗證、第 2 次後驗證假設決定繼續或換方向。不該有第 3 次同方向加碼。

假設驗證的具體方法

1. 用工具讀真實狀態

假設類型	驗證工具
DOM 結構	playwright `browser_evaluate` 讀 ancestor chain
Computed style	playwright `getComputedStyle`
元素位置	playwright `getBoundingClientRect`
Framework 行為	讀框架 source、看 reconcile 條件

2. 反問「如果假設錯了會怎樣」

假設	如果錯了
Drawer 是 form 的 sibling	那 grid-row 完全無效（drawer 跟 form 共用 cell）
Specificity 30 是上限	那 layers 才是解、不是雙寫

「如果錯了會怎樣」的答案是「跟我看到的失敗一致」 → 假設可能錯。

3. 對外回報

1我嘗試了兩次 [方向 X]、結果都 [現象 Y]。
2我的假設是 [假設 Z]、但驗證 [假設 Z] 似乎不成立。
3要不要換 [方向 W]、或是有什麼資訊我沒看到？

對外回報 = 把問題放到使用者視野、避免繼續單方面加碼。

設計取捨：失敗應對的策略

四種做法、各自機會成本不同。這個專案選 A（第 2 次失敗驗證假設）當預設、其他做法在特定情境合理。

本篇是 #42 2 次門檻抽象原則在「同方向失敗」這個面向的應用。

A：第 2 次失敗停下驗證假設（這個專案的預設）

機制：第 1 次修細節再試；第 2 次失敗 → 用工具驗證底層假設（DOM tree、computed style、framework 行為）；驗證錯就換方向
選 A 的理由：早一點切換、雙方時間都省；2 次失敗的證據量足以判斷「路徑問題」
適合：所有除錯情境
代價：第 2 次後的「停下」需要心理紀律（克服繼續加碼的衝動）

B：第 4-5 次才停（沉沒成本綁住）

機制：繼續加碼直到使用者制止
跟 A 的取捨：B 給更多嘗試空間、A 早決；B 在沉沒成本累積後更難切換
B 是反模式：沉沒成本是認知偏誤、不是合理應對 — 「再試一次更小心」的衝動是訊號、不是解法

C：第 1 次失敗就換方向（過度反應）

機制：每次失敗都假設方向錯、立即換
跟 A 的取捨：C 太敏感、A 適度；C 在「修細節就能過」的場景過度切換
C 才合理的情境：嘗試成本極高（每次失敗 = 半天工作）— 即使單次失敗、也值得停下重新評估

D：永不換方向

機制：認定方向對、無限加碼
D 是反模式：方向錯時無法收斂、最後產生脆弱的 patchwork
看起來吸引人的原因：心理上不想承認方向錯、繼續加碼比放棄好受
實際發生的代價：失敗訊號被忽略、產生脆弱的 patchwork、修復成本指數放大

判讀徵兆

訊號	該觸發的行動	第一個該做的事
第 2 次同方向失敗	停下來驗證假設	用 playwright / DevTools 量真實狀態
加 `!important` 解 specificity	停 — 切換到 layers 思路	評估用 CSS Layers
加第 2 條 polyfill 補跨瀏覽器	停 — 評估值不值得繼續	報告成本、問使用者意願
用 imperative JS 補宣告式 layout	停 — 切換到 CSS-first 思路	評估能否用 grid / flex 解決
內心 OS：「再試一次更小心」	停 — 這是沉沒成本綁住的訊號	對外回報、邀請換方向

核心原則：第 2 次失敗的最佳行動是「驗證假設」、不是「再試一次」。早一點切換方向、節省的是雙方時間。

「再試一次」是當下便利的選項（不需要重新分析）、「驗證假設換方向」是對齊正確性的選項 — 這個反相關見 #67 寫作便利度跟意圖對齊反相關。

「可決定」與「該先確認」的邊界

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

核心原則

「可決定」與「該先確認」的分界線是「使用者會看到嗎」。 純技術實作細節（用 grid 或 flex、用 ResizeObserver 或 setInterval）可以自決；但只要結果會在 UI 上出現（數字、順序、文字、配色），就要先給選項讓使用者點頭。

為什麼要分這條線

商業邏輯

執行者自決所有事 = 強迫使用者用「視覺驗收」做決定 — 看到結果才能說「這不對」、不對就要重做。

把「使用者會看到的決定」拉出來事先確認 = 在實作前讓使用者參與決策、避免實作後被退回。

但所有事都要確認 = 對話成本爆炸、使用者疲勞、效率低。

兩者的平衡點：只把使用者實際在乎的決定攤出來確認、技術細節不打擾。

這次任務的實際情境

觀察

我自決後被肯定或否定的決定：

決定	應該的處理	實際處理
Filter sidebar breakpoint = 1400px	該確認 — 使用者視窗大小不確定	自決寫死
Filter 順序 type → tag	該確認 — UX 偏好	自決寫死、後被肯定
Scope-h 預設值 = 56px	該確認 — 視覺差異明顯	自決寫死、後被否定
Filter 寬度 400px	使用者已給數值	直接用
用 absolute 定位而非 grid	純技術選擇	自決、無需確認
用 ResizeObserver 而非 setInterval	純技術選擇	自決、無需確認

可以看出規則：使用者會看到的視覺結果（breakpoint 對應的 viewport 行為、順序對應的閱讀體驗、預設值對應的初始視覺）都該確認；底層工具選擇（grid / flex / absolute、ResizeObserver / setInterval）可以自決。

判讀

判斷標準是「這個決定會在 UI 上產生使用者能感知的差異嗎」：

維度	該先確認	可自決
Visible 數字	breakpoint、預設尺寸、初始值	內部 calculation 細節
順序	filter 排序、選單排序	DOM tree 排序（不影響視覺）
文字	UI 標籤、訊息	內部變數名
配色 / 視覺樣式	使用者看得到	不適用
技術選擇	不適用	grid / flex / observer 等

執行：自決前的兩問

每個決定執行前先問：

這個決定在 UI 上會產生使用者能感知的差異嗎？
是不是有多個合理選項、選不同會影響使用者體驗？

兩個都「是」 → 該確認。

兩個都「否」或只有一個「是」 → 可自決。

確認的格式：給選項而非開放問

較差的問法

「Breakpoint 應該設多少？」

開放問題、使用者要自己想出答案。

較好的問法

「Breakpoint 我預估三個選項：

1280px：物理上能放下、但邊緣情境可能擠壓

1400px：較安全、有 120px 餘裕

1564px：完全不溢出 body padding、最保守

我會選 1400px 作為平衡。OK 嗎？或要其他？」

給選項 + 推薦 + 開放修改空間 — 使用者可以「OK」「換 1280」「再放寬到 1600」三種回應。對話成本低。

內在屬性比較：四種決策模式

模式	對話成本	重做風險	適用情境
全部自決	0	高	純技術實作細節
全部確認	高	0	不適用、太煩
自決技術細節、確認 visible 決定	低	低	一般情境
列選項 + 推薦讓使用者選	低	最低	涉及 UX 偏好的決定

優先「自決技術細節 + 列選項確認 visible 決定」 — 對話成本低、重做風險低。

「使用者會看到嗎」的測試

當不確定某個決定該確認還是自決時、用三個測試：

1. UI 變動測試

「不同選擇會在 UI 上看到差異嗎？」

例	答	結論
用 grid 還是 flex 排兩欄	否（最終視覺一樣）	自決
Breakpoint 1280 vs 1400	是（不同 viewport 下行為不同）	確認

2. UX 偏好測試

「選不同會讓使用者覺得體驗不同嗎？」

例	答	結論
Filter 順序 type 在前 vs tag 在前	是（掃描成本不同）	確認
用 ResizeObserver 還是 setInterval	否（使用者感知不到差異）	自決

3. 不可逆測試

「這個決定寫進 commit 後、之後改成本高嗎？」

例	答	結論
Section 名稱（content/report/）	是（改動要 redirect、broken link）	確認
內部 helper function 名稱	否（rename 一行 grep）	自決

三個測試任一個「是」 → 確認。

設計取捨：決定權分配的策略

四種做法、各自機會成本不同。這個專案選 A（visible 決定先確認 + 技術自決 + 給選項）當預設、其他做法在特定情境合理。

A：Visible 決定先確認、技術自決、確認時給選項（這個專案的預設）

機制：使用者會看到的數字 / 順序 / 文字先列選項給使用者選；純技術實作（grid / flex / observer）自決
選 A 的理由：對話成本低（只確認該確認的）+ 重做風險低（visible 決定使用者參與）
適合：所有客製情境
代價：執行者要主動分辨「visible vs 技術細節」、給選項時要先想出選項

B：全部自決

機制：執行者自己決定所有事
跟 A 的取捨：B 對話成本 0、A 適度；B 容易做到使用者不要的東西
B 才合理的情境：純內部工具、執行者就是使用者；或時間極緊、優先求動

C：全部確認

機制：每個決定都先問
跟 A 的取捨：C 重做風險 0、A 適度；C 對話成本爆炸、使用者疲勞
C 才合理的情境：完全不熟悉的領域、執行者沒有判斷能力（罕見、應透過學習脫離此狀態）

D：開放問題、不給選項

機制：直接問「breakpoint 應該設多少」
跟 A 的取捨：D 把分析負擔丟給使用者、A 執行者先做分析給選項
D 才合理的情境：使用者已經有明確答案、只需要傳達 — 否則 A 的「給選項 + 推薦」更有效率

判讀徵兆

訊號	應該的行動
即將寫死一個 visible 數字（padding、margin、breakpoint）	列選項確認、不要自決
即將決定一個 visible 順序（filter、選單）	列選項確認
即將寫使用者會看到的文字（label、訊息）	確認措辭
即將選擇技術實作（grid / flex / observer）	自決
即將命名內部 helper / 變數	自決

核心原則：能影響使用者體驗的決定屬於使用者、能影響執行者效率的決定屬於執行者。分清楚就不會把該確認的事自決、也不會把該自決的事拿去煩使用者。

第三輪指令類型現有五類：空間（#16）/ 相對位置（#17）/ 隔離（#18）/ 決定權（本卡 #21）/ 篩選（#58）。前四類缺幾何 / 邊界 / 拍板資訊、第 5 類缺操作層級資訊。

「先還原」「先重來」類退出指令的處理

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

核心原則

退出指令（「先還原」「先重來」「先放著」）的執行前要先確認兩件事：還原到哪個狀態、要不要先存 checkpoint。 直接刪掉當前進度、未來想比較沒得比、想恢復也找不到。

為什麼退出指令需要 protocol

商業邏輯

退出指令的字面意思是「拿掉現在做的東西」、但背後通常有更複雜的意圖：

字面	可能的真實意圖
「先還原」	暫時不用、之後可能重做
「先還原」	完全放棄、不會再做
「先還原」	換個方向重做
「先重來」	從上一個 commit 重新試
「先重來」	從更早的點重新試

執行者不確認意圖、直接刪 = 把使用者的選項收窄成「沒有了」。事先確認 = 為使用者保留可能性。

這次任務的實際情境

觀察

使用者說：「如果要做到這麼大的複寫原設計、我們先還原回去、先不要做這個變更」。

我立刻刪掉那段 CSS、繼續往下做其他事。沒問「還原到哪」、沒先 commit checkpoint。

判讀

後來想比較「複雜覆寫版本」與「接受原設計版本」的差異 — 沒得比。「複雜覆寫版本」已經不存在於 git 歷史。

正確流程應該是：

收到「還原」指令時、先回應「我會先 commit 當前進度（即使未採用）作為 checkpoint，再還原到 X 狀態。OK 嗎？」
確認後、commit 當前狀態（不 push）、commit message 標明「探索版本、未採用」
還原到 X 狀態
繼續做後續事

未來想比較或恢復、checkpoint 都還在。

執行：退出指令的 protocol

收到退出指令時、依序處理：

步驟	動作
1	暫停執行、不要立刻刪
2	確認「還原到哪個狀態」（上個 commit / 特定 commit / 完全乾淨）
3	評估「當前進度有保留價值嗎」 — 探索成果、未採用方案、可能未來重用
4	有保留價值 → 先 commit checkpoint、message 標明「探索、未採用」
5	執行還原（reset / checkout / revert）
6	確認還原後狀態符合使用者意圖

Checkpoint 的命名與 commit message

當前進度作為 checkpoint commit、message 應該包含：

1chore(explore): N+1 attempts to remove disclosure marker
2
3探索方向：用 ::-webkit-details-marker / ::marker / display: block 三層
4覆寫移除 disclosure 三角圖示。
5寫了 5 條 CSS 跨 3 種瀏覽器、覆寫成本過高。
6
7最終決定：接受原設計、不採用此方向。
8此 commit 保留探索成果、未來若評估值得做時可參考。

關鍵元素：

chore(explore): prefix — 標明非正式採用
探索方向 — 說明做了什麼
最終決定 — 為什麼不採用
保留理由 — 未來何時可能重用

未來人看到這個 commit、知道「這是探索、不是當前實作」、不會誤用。

內在屬性比較：四種退出處理

處理	可逆性	比較成本	適用情境
直接刪、不留紀錄	最低 — 永久失去	不可比較	不適用
`git reset --hard`（未 commit 直接丟）	低 — git reflog 短期還在	困難	確定不要
`git stash`（暫存到 stash）	中 — stash 可隨時恢復	中	短期暫停
`git commit` checkpoint 後 reset / revert	高 — commit 永久存在	容易	探索性嘗試、未採用方案

優先選 checkpoint 方式 — 為未來保留比較與恢復的可能性。

退出意圖的辨識

從語氣判斷

語氣	對應意圖	推薦處理
「先還原」	暫時、可能重做	Checkpoint + 還原
「先還原、不要做了」	確定放棄	Checkpoint（小機率重看） + 還原
「重來」	換個方向	Checkpoint + 還原到起點
「不要這樣寫」	局部修正、不是全還原	局部改、不要全還原

不確定就問。「不要這樣寫」這類指令容易被理解成「全還原」、實際只是「這段重寫」。

確認意圖的問法

1你想要：
2  □ 完全還原、刪掉這次的 CSS
3  □ 還原但保留 commit checkpoint、未來可能參考
4  □ 局部修正（哪一段保留、哪一段重寫）
5
6或是其他？

設計取捨：退出指令的處理策略

四種做法、各自機會成本不同。這個專案選 A（Checkpoint + 確認還原範圍）當預設、其他做法在特定情境合理。

A：Commit checkpoint + 確認還原範圍（這個專案的預設）

機制：commit 當前進度（標明「探索、未採用」）+ 問「還原到哪個 commit」+ 執行還原
選 A 的理由：未來想比較或恢復都還在、checkpoint 成本只是多一個 commit
適合：探索性嘗試、未採用方案的退出
代價：多一個 commit 在歷史中（可後續 squash 或保留）

B：`git stash` 暫存

機制：把未 commit 的變更存到 stash、不污染 commit 歷史
跟 A 的取捨：B 不留 commit、A 留 commit；B 適合「短期暫停、之後恢復」、A 適合「長期探索紀錄」
B 比 A 好的情境：暫時切到別的工作、之後一定會回來繼續

C：`git reset --hard`（直接丟）

機制：reset 到指定 commit、未 commit 的變更全失去
跟 A 的取捨：C 完全清乾淨、A 保留紀錄；C 在 git reflog 內短期還能恢復、但之後永久消失
C 才合理的情境：確定不要的探索、且確認不需要未來參考

D：直接刪檔案、不留 git 紀錄

機制：手動刪 / 改、不 commit
成本特別高的原因：未來想比較或恢復都做不到、使用者選項被收窄
D 是反模式：git 是免費的紀錄工具、不用反而是浪費 — 未來想比較或恢復都做不到、使用者選項被收窄

判讀徵兆

訊號	應該觸發的處理	第一個該做的事
「先還原」	確認還原範圍 + checkpoint	問「還原到哪」
「重來」	確認重做起點 + checkpoint	問「從哪重來」
「不要做了」	評估保留價值	探索成本高就 checkpoint、否則直接刪
「先放著」	Stash 或 branch 保留	不要刪、要留可恢復路徑
「換個方法試試」	Checkpoint + 換方向	保留現方法的進度

核心原則：退出指令的執行不該收窄使用者的未來選項。Checkpoint = 給未來保留可能性、成本只是多一個 commit。

驗證方法的選擇時機

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

核心原則

驗證工具的引入時機不該等推理徹底失敗。 靜態 CSS 推理或視覺截圖溝通連續失敗 ≥ 2 次、立刻主動提「我們啟個 server、我用 playwright 看 live DOM」 — 工具的價值是縮短診斷迴圈、不是最後手段。

為什麼要主動提工具

商業邏輯

執行者堅持靠推理 = 把使用者拖進「截圖 - 反饋 - 再試」的長循環。每輪都消耗使用者時間（看截圖、描述問題、回應）— 對使用者是負擔。

主動提工具切換 = 把循環從「視覺溝通」改成「程式量測」。執行者直接讀 live DOM、診斷一輪到位、使用者只需要在最終確認。

主動提的成本是「打一句話建議」、收益是「省 N 輪截圖溝通」。

這次任務的實際情境

觀察

drawer 在 form 內、不是 sibling 這個假設錯誤、靠推理 + 截圖溝通走了多輪：

輪	溝通方式	結果
1	推理 + 寫 CSS + 使用者截圖回報	失敗、看不出根因
2	改 CSS + 使用者截圖回報	失敗、累積錯誤假設
3	加更多覆寫 + 使用者截圖回報	失敗、使用者「思路錯了」
4	「我啟個 server 看看」	立刻發現 drawer 在 form 內

第 4 輪用 playwright browser_evaluate 讀 ancestor chain — 一個 query、一個答案、兩分鐘解。前三輪 ≈ 30 分鐘。

判讀

第 2 輪失敗時就應該主動提：

「我嘗試了兩次都失敗、根因可能在我對 DOM 結構的假設。要不要啟個 server、我用 playwright 直接讀 live DOM 確認？這樣比繼續用截圖溝通快。」

使用者啟 server、我跑 query、一輪解。

執行：主動提工具的 protocol

驗證工具該在這些時機主動提：

訊號	應該提的工具
推理連續失敗 ≥ 2 次	playwright `browser_evaluate` 讀 live DOM
不確定元素的真實位置	`getBoundingClientRect`
不確定 computed style 套到什麼值	`getComputedStyle`
不確定 framework 渲染後的 DOM	playwright snapshot
不確定跨 viewport 行為	playwright 切換 viewport 重測

工具引入的成本與價值

內在屬性比較

方法	起步成本	每輪成本	涵蓋
推理 + 截圖	0	高 — 截圖、描述、再試	有限 — 看截圖看不到 DOM
瀏覽器 DevTools 手動查	0	中 — 切面板、讀	中 — 互動成本高
Playwright `browser_evaluate`	中 — 起 server	低 — 寫一段 evaluate	高 — 任意 JS query
Playwright 寫成測試	中 — 起 server + 寫測試	0 — 自動跑	高 + 持續

「起步成本」是一次性、「每輪成本」是重複的。第 2 輪以後、playwright 的 ROI 已經正向。

主動提的具體話術

較差的提法

「要不要試試 playwright」

模糊、使用者不一定知道為什麼要試、可能答「先這樣吧」。

較好的提法

「我嘗試了兩次都失敗、根因可能不在 CSS、在我對 DOM 結構的假設。要不要啟個 server（python3 -m http.server 8000 在 public/）、我用 playwright browser_evaluate 直接讀 ancestor chain 確認？這樣比繼續用截圖快很多。」

說明：

為什麼提：兩次失敗、推理迴圈成本超過工具迴圈
要使用者做什麼：啟 server、給一行指令
我會做什麼：用 playwright evaluate 讀
預期收益：縮短迴圈

使用者明確知道 trade-off、決定簡單。

工具迴圈的標準流程

11. 使用者啟 server（python3 -m http.server / hugo server）
22. 執行者 navigate 到目標頁面
33. 執行者寫 evaluate fn 讀真實狀態
44. 執行者根據結果定位根因
55. 執行者改 CSS / JS
66. 執行者再 evaluate 驗證修復
77. 使用者目視最後確認（可選）

整個流程多數步驟在執行者這邊、使用者只在頭尾參與 — 對使用者負擔輕。

設計取捨：驗證工具引入的時機

四種做法、各自機會成本不同。這個專案選 A（推理 ≥ 2 次失敗主動提）當預設、其他做法在特定情境合理。

本篇是 #42 2 次門檻抽象原則在「驗證工具切換」這個面向的應用。

A：推理 ≥ 2 次失敗主動提工具切換（這個專案的預設）

機制：靜態推理連續失敗 2 次、立刻提「啟個 server、我用 playwright 看 live DOM」+ 附啟用步驟與預期收益
選 A 的理由：對使用者透明（看到 trade-off）、縮短診斷迴圈
適合：CSS / DOM 行為跟預期不符的除錯
代價：執行者要主動辨識「推理迴圈成本」與「工具迴圈成本」的交叉點

B：等使用者要求才用工具

機制：執行者繼續推理、使用者覺得太慢時提
跟 A 的取捨：B 對使用者更被動、A 主動；B 在使用者不知道有 playwright 選項時、會一直繼續
B 才合理的情境：使用者明確表達「想用推理練習」、把工具切換當成放棄

C：全程靜態推理、不用工具

機制：堅持推理到底
C 是反模式：推理迴圈成本累積、最後可能需要 4-5 輪才解決
看起來吸引人的原因：覺得用工具是「能力不足」、想撐到自己想出來
實際發生的代價：時間成本指數放大（每輪推理基於前輪錯假設）、最後還是要切工具

D：一開始就用 playwright、不嘗試推理

機制：跳過推理、直接用工具量
跟 A 的取捨：D 跳過推理階段省去 2 次嘗試、但前期 setup 成本投入比例較高（簡單問題不值得）
D 比 A 好的情境：問題明確需要 live DOM 才能診斷（例如「framework 渲染後的結構」）— 推理本來就無法解

判讀徵兆

訊號	應該主動提的工具	提的話術重點
推理 + 截圖溝通 ≥ 2 輪	playwright `browser_evaluate`	我假設可能錯、用工具讀 live DOM 確認
修了 CSS 但使用者截圖看起來沒變	playwright `getComputedStyle`	確認 CSS 真的套到、不是 cache 問題
不確定哪個 viewport 下會有問題	playwright 多 viewport 測	一次跑多 viewport、找出哪個壞
互動狀態下行為不一致	playwright 模擬互動 + 量測	自動操作、量結果
修好了想固化規範	playwright 寫測試	把這次發現的契約寫成 expect、未來破壞會被抓

核心原則：工具引入時機是「推理迴圈成本超過工具迴圈成本」的點 — 大多在第 2 次推理失敗時。早一點提、雙方都省時間。

跟 #68 驗收的時間軸的關係：本卡是「debug 工具切換時機」、#68 是「驗收動作分散在四個時點」 — 兩者共用「動作該分配到哪個時點才有 ROI」這個結構。本卡的「第 2 次推理失敗就切工具」≈ #68 的「ship 前要設計 E2E case」 — 都是「把高 ROI 的動作放在對的時點、不要延後」。

CSS Layers 取代 specificity 戰

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

核心原則

CSS Layers 把樣式覆寫從「線性 specificity 數字戰」改成「分組權重順序」。 把外部組件 CSS @import 進一個 layer、自家 CSS 留在 unlayered，自家規則自動贏 — 不論個別 selector specificity 數值。一次設定、所有 !important 與 .x.x 雙寫 hack 可以拿掉。

為什麼 specificity 戰沒有贏家

商業邏輯

CSS specificity 是線性數字比較。組件作者用 .x.svelte-yyy.svelte-yyy 雙寫 specificity 30 → 自家用 .search-shell .x specificity 20 蓋不過 → 加 .x.x 雙寫到 30 → 還是看 source order → 加 !important → 跟其他 important 對撞 → 寫死多層 fallback。

每加一層覆寫成本累積、未來 debug 越來越難。每個 !important 都是一個 future debugging burden、!important 之間沒有層級可言。

CSS Layers 的解法

CSS @layer 提供「分組權重」 — unlayered CSS > layered CSS（layer 越早宣告越低權）、跟 selector specificity 無關：

1unlayered { ... }              ← 最高權
2@layer high { ... }
3@layer medium { ... }
4@layer low { ... }             ← 最低權

把組件 CSS 整包丟進某個 layer、自家 CSS 留 unlayered、自家規則自動贏所有組件規則 — 不論 specificity。

這次任務的覆寫戰場

觀察

現在 search.html 內為了蓋過 pagefind specificity 30 的寫法：

1.pagefind-ui__filter-block { border-bottom: 0 !important; }
2.pagefind-ui__filter-panel { display: none !important; }
3.search-filter-slot fieldset { border: 0; padding: 0; margin: 0; }

每條都靠 !important 或 source order 取勝。可維護性低。

判讀

把 pagefind-ui.css 用 @import 包進 layer：

1@import url("/blog/pagefind/pagefind-ui.css") layer(pagefind);

自家 CSS 不加 layer 宣告、留 unlayered。自家規則優先級自動高於 layer(pagefind)。

執行：refactor 步驟

 1/* search.html / assets/search.css */
 2
 3/* 把 pagefind 的整包 CSS 包進 layer */
 4@import url("/blog/pagefind/pagefind-ui.css") layer(pagefind);
 5
 6/* 自家 CSS 留 unlayered、自動贏 */
 7.pagefind-ui__filter-block {
 8  border-bottom: 0;            /* 不需要 !important */
 9}
10.pagefind-ui__filter-panel {
11  display: none;               /* 不需要 !important */
12}
13@media (min-width: 1400px) {
14  .pagefind-ui__filter-panel { display: none; }
15}

原本的改成上方 @import 寫法、確保 import 在自家 CSS 之前發生（layered CSS 不會阻擋 unlayered CSS 的優先級）。

內在屬性比較：四種 specificity 應對

方法	維護成本	可讀性	升級兼容性
`!important` 對抗	高 — 每加一條未來 debug 成本上升	低 — 不知為什麼要 important	中 — 組件變更可能讓 important 用錯
雙寫 class（`.x.x`）	中 — selector 看起來奇怪	低 — 維護者不知為什麼	中 — 組件改 class 名就失效
Inline style + setProperty important	高 — 散落在 JS 各處	最低 — 不在 CSS 找不到	低 — JS 規則容易被 framework 重繪打破
CSS Layers	低 — 一次設定、規則簡單	高 — 結構化分層	高 — 跟組件升級無關

Layers 的所有指標都最佳。其他三種是 Layers 之前的 workaround、現在沒理由繼續用。

Layers 的進階用法

多個外部組件分別 layer

1@import url("vendor-a.css") layer(vendor-a);
2@import url("vendor-b.css") layer(vendor-b);
3
4@layer vendor-a, vendor-b;   /* 後宣告的優先 */
5
6/* 自家 unlayered */
7.my-overrides { ... }

@layer name1, name2; 顯式宣告 layer 順序、後宣告的權重高。

自家 CSS 也分層

 1@layer base, components, utilities;
 2
 3@layer base {
 4  body { font-family: ... }
 5}
 6@layer components {
 7  .button { padding: ... }
 8}
 9@layer utilities {
10  .text-center { text-align: center; }
11}

自家 CSS 內部也分層、避免 utilities 被 components 蓋過。

跟 unlayered 並存

不是所有自家 CSS 都要分 layer。最高優先的自家規則留 unlayered、其他規則可以分層。

瀏覽器支援

CSS Layers 在所有主流瀏覽器（Chrome 99+、Firefox 97+、Safari 15.4+）支援、2022 年起。當前（2026）所有現代瀏覽器都支援。

對舊瀏覽器降級：不支援 @layer 的瀏覽器會把整個 @layer { ... } block 當作 invalid 跳過 — 自家 unlayered 規則仍然適用、效果一樣（但 vendor CSS 完全失效）。實務上不需要擔心。

設計取捨：覆寫外部組件 CSS 的策略

四種做法、各自機會成本不同。這個專案選 A（CSS Layers）當預設、其他做法在特定情境合理。

A：CSS Layers（這個專案的預設）

機制：@import url(...) layer(vendor) 把外部 CSS 包進低權層、自家 unlayered CSS 自動贏
選 A 的理由：跨組件升級穩定、規則簡單、!important 完全不需要、跳出 specificity 線性比較戰場
適合：所有現代瀏覽器（Chrome 99+ / Firefox 97+ / Safari 15.4+）的客製情境
代價：需要重新引入 vendor CSS（從改 @import）

B：雙寫 class 提升 specificity

機制：.pagefind-ui__filter-block.pagefind-ui__filter-block 寫兩次提升 specificity 從 10 到 20
跟 A 的取捨：B 不需要改 vendor CSS 引入方式、A 需要；但 B 跟組件 specificity 競賽（組件作者改 hash 寫法就壞）、A 跳出競賽
B 是反模式：跟組件 specificity 競賽（組件作者改 hash 寫法就壞） — 唯一例外是 vendor CSS 不能用 @import 引入（極罕見的 build pipeline 限制）

C：`!important` 對抗

機制：每條覆寫加 !important、用 importance 取勝
跟 A 的取捨：C 短期有效、長期 important 之間沒層級可言；多個 important 對撞時 debug 困難
C 才合理的情境：CSS Layers 不支援的舊瀏覽器（< 2022 的版本）、且確認沒其他 important 對撞

D：Inline style + `setProperty('important')`

機制：JS 用 el.style.setProperty('display', 'none', 'important')
成本特別高的原因：規則散落在 JS 各處、devtools 看不出意圖、跟 framework 重繪競爭
D 才合理的情境：動態值（runtime 算的位置 / 尺寸）必須用 inline 表達 — 但即使這樣、也建議用 class toggle + CSS 變數（#28）取代

判讀徵兆

訊號	Refactor 動作
為了蓋過組件規則寫了 `!important`	評估改用 CSS Layers
Selector 寫成 `.x.x` 雙寫只為了 specificity	評估改用 CSS Layers
覆寫邏輯散落在多個檔案 / inline style	集中到一份 CSS、用 layers 分層
組件升級後覆寫失效	用 layers 隔離、跟組件 specificity 變動脫鉤

核心原則：跟組件 CSS 競爭 specificity 是不必要的戰爭。Layers 提供更高層的權重機制、把覆寫簡化成「自家 vs 別人」的二元決定。

CSS / JS 拆出獨立檔案

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

核心原則

Inline CSS / JS 超過 ~30 行就值得拆出獨立檔案、走 Hugo resources.Get | minify | fingerprint 引入。 Template 變單純、editor 對 .css/.js 有 syntax highlight、minify 自動化、cache-busting fingerprint 自動處理。

為什麼 inline 有上限

商業邏輯

Inline CSS / JS 在 Hugo template 內看似省事（一個檔案搞定），但隨著規模上升出現多個成本：

規模	Inline 的代價
< 10 行	幾乎無 — 一目了然
10-30 行	中 — Editor 不太能 highlight、template 開始混雜
30+ 行	高 — 找東西要在 template 模式間切換、minify 沒做、cache 控制困難

拆檔的成本是「多 1-2 個檔案」、收益是「multiple」 — 過了 30 行門檻、ROI 已正向。

拆檔的實際得益

維度	Inline	拆檔 + Resources Pipeline
Editor syntax highlight	部分 — 看 editor 是否支援 mixed mode	完整 — 純 .css / .js 檔
Minify	手動或 hugo template minify	Hugo `minify` pipe 自動
Cache-busting	手動加版本號	`fingerprint` 自動
程式碼重用	難 — 跟 template 綁	容易 — 多 template 共用
Version control diff	跟 template 改動混	純檔案改動、清楚
測試	難	可單獨測

這次任務的拆檔目標

觀察

layouts/_default/search.html 現況：

段落	行數
Hugo template 與 HTML	~30
Inline