CSS 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 領地。

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

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 改

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

排版精度的工具選擇：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 是不是我管」兩個技術問題的答案。問清楚再選。

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 變數定義位置統一

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

核心原則

CSS 變數的定義位置只能有一處。 一次定義在離 root 最近的合適 selector（:root 或頁面層級的 body class），其他地方只用 var() 引用、不重複宣告。改 token 只動一處、所有引用點自動跟上。

為什麼定義位置要單一

商業邏輯

CSS 變數的價值是「單一來源、多處引用」。把定義散在多個 selector：

1:root           { --search-title-h: 64px; }
2.search-shell   { --pagefind-ui-scale: 1.0; }
3body.page-search { --search-form-h: 68px; }

每個變數的「真相」分散在不同位置 — 改一個 token 要先 grep 找到定義位置、可能漏改。

更嚴重：同名變數在不同 selector 重複定義時、值依 cascade 順序決定 — 維護者不易看出哪個值生效。

統一定義的位置選擇

位置	適用情境	影響範圍
`:root`	全站適用的 design token	全站
`body.page-X`	特定頁面類型適用	該類型頁面
`.component-name`	特定 component 內適用	該 component 子樹

選擇原則：定義在「跟使用範圍最匹配的最高層級」selector。全站用 :root、頁面類型用 body class、組件內用組件 class。

這次任務的散落問題

觀察

search.html 內 CSS 變數定義散在三處：

 1body.page-search {
 2  --search-title-h: 64px;
 3  --search-form-h: 68px;
 4  --search-gap: 20px;
 5}
 6
 7:root {
 8  --search-scope-h: 60px;   /* JS 量測會覆寫 */
 9}
10
11.search-shell {
12  --pagefind-ui-scale: 1.0;
13}

三處定義 — 雖然各有理由（body 範圍、JS 寫入點、cascade 給 pagefind），但維護者要知道「改 search-form-h 在哪改」需要全文 grep。

判讀

整理後集中在 body.page-search（搜尋頁的 root selector）：

 1body.page-search {
 2  /* 設計 token：寫死值 */
 3  --search-title-h: 64px;
 4  --search-form-h: 68px;
 5  --search-gap: 20px;
 6
 7  /* JS 量測寫入 fallback：JS 會用 setProperty 覆寫到 :root */
 8  --search-scope-h: 60px;
 9
10  /* 給 pagefind cascade 的 scale */
11  --pagefind-ui-scale: 1.0;
12}

一個 selector 看到所有 search 相關 token、cascade 到子樹生效。

執行

JS 量測寫入 scope-h 時、寫到 body.page-search 而非 :root：

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

寫到 body.style 直接覆蓋 body.page-search 的 fallback 值。Cascade 到所有後代生效。

變數命名與分類

命名前綴標明範圍

前綴	範圍
`--token-*` 或無前綴	全站設計 token（顏色、字型）
`--page-search-*`	搜尋頁專用
`--pagefind-ui-*`	Pagefind 提供的 hook（不是我們命名、是組件預期）

前綴讓維護者一眼看出變數的「歸屬」、不會誤改別處變數。

分類定義

 1body.page-search {
 2  /* === 對齊 token === */
 3  --search-title-h: 64px;
 4  --search-form-h: 68px;
 5  --search-gap: 20px;
 6  --search-scope-h: 60px;     /* JS 寫入 */
 7
 8  /* === 響應式 breakpoint === */
 9  /* (CSS 變數無法用在 @media query、breakpoint 寫死在 query 內) */
10
11  /* === 對組件的 hook === */
12  --pagefind-ui-scale: 1.0;
13}

分類註解讓維護者知道「我要改哪類 token」、找對位置。

內在屬性比較：四種變數定義方式

方式	維護成本	可見性
散在多個 selector 定義	高 — grep 找定義	低 — 不知哪個生效
集中在一個 selector	低 — 改一處	高 — 全部變數一覽
集中 + 分類註解	低	最高 — 結構化
集中 + JS 寫入用同一 selector	低	最高 + JS 動態同步

優先選「集中 + 分類 + JS 寫入同 selector」。

變數的 fallback 策略

責任邊界：本節只談「fallback 值寫在哪個 selector」、屬於定義位置議題。「該不該用 runtime 量測」這個更上層的策略選擇由 #27 runtime 量測模式統一處理 — 那邊主張「全寫死 vs 全量測、不要混搭」。

JS 量測寫入的變數、CSS 應該有 fallback 值供 JS 還沒跑完時用：

1body.page-search {
2  --search-scope-h: 60px;   /* fallback、JS 會覆寫 */
3}
4
5.search-shell .pagefind-ui__drawer {
6  margin-top: calc(var(--search-scope-h) + 8px);  /* JS 跑完前用 60px */
7}

或用 var() 第二參數：

1margin-top: calc(var(--search-scope-h, 60px) + 8px);

兩種寫法效果相近 — 第一種讓 token 集中在 body.page-search 內、推薦使用。

設計取捨：CSS 變數定義位置策略

四種做法、各自機會成本不同。這個專案選 A（集中在使用範圍的最高層）當預設、其他做法在特定情境合理。

本篇是 #44 SSoT 抽象原則在「CSS 變數定義位置」這個面向的應用。

A：集中在「跟使用範圍最匹配的最高層」selector（這個專案的預設）

機制：全站 token 在 :root、頁面 token 在 body.page-X、組件 token 在 .component、JS 寫入也用同 selector
選 A 的理由：定義住址唯一、改 token 自動跟上、cascade 範圍跟使用範圍一致
適合：絕大多數 design token 系統
代價：要先想清楚每個變數的「使用範圍」、不能無腦丟一處

B：所有變數都丟 `:root`

機制：不分使用範圍、全部 :root
跟 A 的取捨：B 簡單一致、A 按範圍分；但 B 不在乎 scope、可能跟其他組件變數命名衝突、且 cascade 範圍過大
B 比 A 好的情境：純 design system token（顏色 / 字型）、確實全站適用

C：散在多個 selector 各自定義

機制：每個 component 各自定義需要的變數
跟 A 的取捨：C 元件自包含、A 集中管理；但 C 同名 token 散落多處、cascade 順序決定值、改一處可能漏其他
C 才合理的情境：完全獨立的元件、不共用任何 token（罕見）

D：每處引用點都重複定義

機制：用 var 引用前都重新宣告一次
D 是反模式：徹底違反 SSoT、改 token 要 grep 找全、必漏改 — 重複定義是 magic number 散落的另一種形式
看起來吸引人的原因：每處就地寫值最快、不用想 token 該定義在哪
實際發生的代價：未來改值時掃不到全部、UI 出現「有的地方變、有的沒變」的怪 bug

判讀徵兆

訊號	Refactor 動作
同名變數在多個 selector 定義	集中到一個 selector、移除其他
改一個 token 要 grep 找定義位置	集中 + 分類註解
Token 命名沒前綴、跟其他組件變數混	加範圍前綴（`--page-X-*`）
JS 寫入變數的位置跟 CSS 定義不同	對齊到同一 selector
變數值在 cascade 中被另一處覆蓋	找出兩處、決定哪一處保留

核心原則：CSS 變數是設計 token 系統的基礎、定義位置就是 token 的「住址」。住址一個就好、不要一物多址。

「就地寫個值」是便利（不用找 token 位置）、「集中定義 + 引用」是對齊 — 同 #44 SSOT 跟 #67 便利 vs 對齊反相關。

以 class toggle 取代 inline `display: none !important`

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

核心原則

JS 改 DOM 元素的視覺狀態、用 class toggle、不用 inline style.setProperty important hack。 Class toggle 的好處：CSS 規則集中可讀、devtools 看到語意化的 class 名而非神秘 inline style、未來改視覺只動 CSS 不動 JS。

為什麼 class toggle 比 inline style 好

商業邏輯

兩種方式都能達成「JS 控制視覺」、差別在「視覺規則的家在哪」：

方式	視覺規則住址	維護成本
`el.style.display = 'none'`	散在 JS 各處	高 — 改視覺要找 JS、不在 CSS
`el.classList.toggle('is-hidden')` + `.is-hidden { display: none }`	集中在 CSS	低 — 改視覺改 CSS

集中在 CSS = 設計系統的單一來源、devtools Element 面板看 class 知道狀態、code review 容易理解。

!important 的需求消失：只要 CSS Layers 把 vendor CSS 包進低權層、自家 unlayered CSS 自然贏、不需要 important。

何時 inline style 是必要的

情境	inline style 必要
動態值（隨 runtime 計算）	是 — 如 `el.style.top = scrollY + 'px'`
動畫起點 / 終點	是 — `el.style.transform = ...`
切換 boolean 狀態（顯示/隱藏）	否 — 用 class toggle
套用設計系統一致樣式	否 — 用 class toggle

「狀態切換」是 class toggle 的場景、不是 inline style 的場景。

這次任務的重構機會

觀察

Scope filter 用：

1items.forEach(function (el) {
2  var show = scope === 'title' ? re.test(title) : re.test(excerpt);
3  if (show) {
4    el.style.removeProperty('display');
5  } else {
6    el.style.setProperty('display', 'none', 'important');
7  }
8});

setProperty important 是為了壓過 Svelte 重繪可能 reset 的 inline style。CSS Layers 之後、important 不再必要。

判讀

改用 class toggle + layered CSS：

1/* assets/search.css，unlayered（pagefind 在 layer(pagefind) 內） */
2.pagefind-ui__result.is-scope-filtered {
3  display: none;
4}

1items.forEach(function (el) {
2  var show = scope === 'title' ? re.test(title) : re.test(excerpt);
3  el.classList.toggle('is-scope-filtered', !show);
4});

更乾淨：

CSS 規則集中
DevTools Element 面板看到 .is-scope-filtered 就知道為什麼隱藏
JS 邏輯簡化（classList.toggle 一行解兩種狀態）
不需要 !important

執行 prerequisite

要這個 refactor 生效、先做 #24（CSS Layers）：

1@import url("/blog/pagefind/pagefind-ui.css") layer(pagefind);
2
3/* unlayered，自動勝過 pagefind 的所有 specificity */
4.pagefind-ui__result.is-scope-filtered { display: none; }

否則 layered 的 pagefind CSS 可能用 specificity 30 蓋過 .is-scope-filtered（specificity 20）。

內在屬性比較：四種 JS 控制視覺方式

方式	維護成本	DevTools 可讀性	Important 需求
`el.style.display = 'none'`	中 — 規則散在 JS	中 — 看到 inline style	否
`el.style.setProperty('display','none','important')`	高 — important 散在 JS	中	是 — 跟 framework 競爭
`el.classList.toggle('is-hidden')` + CSS	低 — 規則在 CSS	高 — 看 class 知狀態	否（CSS Layers 環境下）
`el.dataset.state = 'hidden'` + `[data-state=hidden]` CSS	低 — 規則在 CSS	高 — attribute 也表達狀態	否

優先選 class toggle（或 dataset） — CSS-first、可讀、可維護。

Class toggle 的命名慣例

用 `is-X` / `has-X` 表狀態

1.is-scope-filtered { display: none; }
2.is-loading { opacity: 0.5; }
3.has-error { border-color: red; }

is- / has- 前綴讓「狀態 class」跟「結構 class」（如 .search-shell）視覺區分、code review 一眼看出哪些是動態狀態。

用 BEM modifier

1.search-result--filtered { display: none; }

BEM 風格也可以、看專案 convention。重點是有規律、不要混雜。

DevTools 可讀性的具體差異

Inline style 視角

1<div class="pagefind-ui__result svelte-j9e30" style="display: none !important;">

DevTools 顯示「inline style 設了 important」 — 但不知道為什麼。要 grep JS 找出哪段邏輯設的。

Class toggle 視角

1<div class="pagefind-ui__result svelte-j9e30 is-scope-filtered">

DevTools 顯示「有 .is-scope-filtered class」 — class 名本身解釋為什麼隱藏。CSS 面板也直接顯示對應規則。

設計取捨：JS 控制視覺狀態的策略

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

A：Class toggle + CSS 規則（這個專案的預設）

機制：el.classList.toggle('is-scope-filtered')、CSS 內定義 .is-scope-filtered { display: none }
選 A 的理由：CSS 規則集中、devtools 看 class 知狀態、改視覺只動 CSS、配 CSS Layers 不需 !important
適合：布林狀態切換（顯示 / 隱藏 / 啟用 / 停用）
代價：需要在 CSS 預先定義 class 規則（多一份 CSS）

B：Inline `style.X = ...`

機制：el.style.display = 'none'
跟 A 的取捨：B 一行 JS、A 需要 CSS 規則；但 B 規則散在 JS 各處、devtools 看到 display: none inline 不知道為什麼
B 比 A 好的情境：runtime 計算的動態值（el.style.top = scrollY + 'px'）— 這類值無法預先寫進 CSS

C：Inline + `setProperty('important')`

機制：el.style.setProperty('display', 'none', 'important')
跟 A/B 的取捨：C 比 B 多 important、為了壓過 framework 重繪 reset 的 inline；但 C 進入 !important 戰、未來新 important 對撞 debug 困難
C 才合理的情境：framework 強制 reset 自家 inline style、且不能用 layered CSS（極罕見）
更好的解：用 #24 CSS Layers 解 specificity 戰、本卡片 A 即可

D：Dataset attribute + CSS attribute selector

機制：el.dataset.state = 'hidden'、CSS [data-state="hidden"] { display: none }
跟 A 的取捨：D 用 attribute 表狀態、A 用 class；D 在「狀態值多種」時更合適（例如 data-state="loading|ready|error"）
D 比 A 好的情境：狀態有多個值（不只 boolean）、需要 CSS attribute selector 表達多分支

判讀徵兆

訊號	Refactor 動作
JS 用 `style.setProperty(..., 'important')`	改用 class toggle、用 CSS Layers 解決 specificity
`el.style.display = 'none'` 散落多處	集中為 `.is-X` class、JS 只 toggle
DevTools 看到 inline style 不知為什麼	改用語意化 class、devtools 看 class 自帶解釋
視覺改動要改 JS（不是 CSS）	Refactor 為 class toggle、視覺改動只動 CSS
改視覺需要對抗 framework reset	用 CSS Layers 把 framework 規則降層、自家規則不需 important

核心原則：CSS 是視覺規則的家、JS 控制狀態 - 兩者透過 class toggle 介面共處、不互相侵入。

Inline style + !important 是「立刻生效」的便利、class toggle 是「樣式留 CSS」的對齊 — 這個反相關的更高層原則見 #67 寫作便利度跟意圖對齊反相關。

Layout reflow / repaint 的可量化評估

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

核心原則

Reflow 與 repaint 的成本差兩個數量級、用 Performance 面板可以量化判斷哪個發生。 開發時不需要「全部避開 reflow」、要做的是「知道哪些操作觸發 reflow、規模放大時哪些值得優化」。

為什麼要量化、不憑感覺

商業邏輯

瀏覽器渲染管線分階段：

階段	觸發條件	相對成本
Style recalc	CSS 規則變動、class toggle	低
Layout (reflow)	影響元素尺寸 / 位置的 CSS 改變	高（要重算所有受影響元素）
Paint (repaint)	顏色 / 背景變動但位置不變	中
Composite	transform / opacity 等 GPU 加速屬性	最低

不同操作落在不同階段。「改 width」觸發 reflow、「改 transform」只到 composite。差距 ~10-100x。

但這不代表要「永遠用 transform」 — 多數場景 reflow 成本可以接受、過度避免反而讓 layout 變脆。

量化的工具

工具	看什麼
Chrome DevTools Performance	整段操作的 reflow / paint / composite 時間
Performance API（`performance.measure`）	程式化量自家函式
Layout shift (Web Vitals CLS)	視覺上的 layout 跳動

優先用 DevTools Performance 量、有具體數字後再決定是否優化。

搜尋頁的具體風險點

風險 1：Filter slot 跨 viewport 切換

位置：matchMedia callback 內 slot.appendChild(filter) / drawer.insertBefore(filter, ...)。

判讀：

整個 filter 子樹移動 = layout 重算（filter 的新位置、原位置元素重排）
同時 main 區域與 sidebar 區域的尺寸都重算
一次性發生、不持續觸發

症狀：使用者拖動視窗寬度跨過 1400px 時、瞬間卡頓 1-2 frame。

第一個該查的：DevTools Performance 錄下 resize 跨過 breakpoint 的瞬間、看 Layout 區塊有多大。< 16ms = OK；> 16ms 考慮 debounce matchMedia callback。

風險 2：CSS 變數寫入

位置：document.body.style.setProperty('--search-scope-h', ...)。

判讀：寫 CSS 變數不一定觸發 reflow — 看哪些規則用了這個變數、那些規則影響哪些元素。

--search-scope-h 用於 drawer 的 margin-top → drawer 位置變動 → reflow
--search-scope-h 用於 filter slot 的 padding-top → filter slot 高度變動 → reflow

症狀：scope 大小變動時、drawer 與 filter slot 同時重排、可能看到輕微跳動。

第一個該查的：DevTools Performance 錄一次 scope 變大的事件、看 Layout 區塊。多數場景 < 5ms、可忽略。

風險 3：Absolute 定位的重算

位置：.search-filter-slot { position: absolute; ... }。

判讀：Absolute 元素跟一般 flow 元素分離、自己不影響 sibling 的 layout、但仍受自身 position / size 變動影響。Filter 改 top 觸發自身 reflow、不影響 main。

症狀：filter slot 的 padding-top 變動（隨 scope-h）— 只影響 filter 自身高度。

第一個該查的：DevTools Performance 看 filter padding 變動時的 layout 範圍 — 應該只到 filter 內部、不擴散到 main / footer。若擴散表示有意外的 stacking context 影響。

風險 4：JS 連續操作 DOM

位置：reorderFilters() 用 appendChild 多次調整順序。

1desiredOrder.forEach(function (k) {
2  if (byKey[k]) filter.appendChild(byKey[k]);
3});

判讀：

多次 appendChild 可能觸發多次 layout
但 browser 通常會合併同步 DOM 變動到一次 layout（natural batching）
真正會「強制 layout」的是 DOM 寫入後馬上讀 layout 屬性（如 offsetHeight）

症狀：rare — reorder 一次只在 setup 時跑、影響很短。

第一個該查的：若有這類「寫後立刻讀」的 pattern、用 requestAnimationFrame 把讀延後到下一幀、避免 forced sync layout。

內在屬性比較：四種 layout 變動類型

變動類型	成本	可控性
Composite-only（transform / opacity）	最低	GPU 加速、< 1ms
Paint-only（顏色變動）	低	局部重繪
Layout（尺寸 / 位置變動）	中-高	要算受影響的範圍
Forced sync layout（DOM 寫後立刻讀）	最高	連續觸發是 perf killer

選擇順序：有意識避免 forced sync layout、對動畫優先用 transform、一般 layout 變動量小不必特別避免。

預估成本的快速法則

不要每個操作都用 DevTools 量、用快速法則先判斷：

操作	預估等級	何時要量
改 class（class toggle）	1ms 等級	套用到大量元素時
Append / remove 單一節點	1-5ms	大規模迭代時
移動 DOM 子樹（reparent）	5-20ms	子樹大、頻繁觸發時
改 CSS 變數（簡單 calc）	1-5ms	頻繁觸發時
Forced sync layout	5-50ms	任何寫後立刻讀的 pattern 都該量

預估超過 frame budget（16.67ms）才值得實際量、進一步優化。

設計取捨：layout 操作的處理策略

四種做法、各自機會成本不同。這個專案選 A（量化評估再決定）當預設、其他做法在特定情境合理。

A：量化評估、按規模決定優化與否（這個專案的預設）

機制：用 DevTools Performance 量每個 layout 操作的實際成本、超過 frame budget（16.67ms）才優化
選 A 的理由：避免過度優化（多數 reflow 成本可接受）、又不漏真正貴的（forced sync layout）
適合：所有效能盤點情境
代價：需要學會用 DevTools Performance、對效能 dispute 要量

B：全部用 transform / opacity 避免 reflow

機制：所有動畫 / 變動都用 transform 或 opacity（GPU composite）
跟 A 的取捨：B 預先避免 reflow、A 量化按需處理；但 B 寫出複雜的 transform / absolute 組合、layout 邏輯難維護
B 比 A 好的情境：高頻動畫（每 frame 變動的旋轉 / 移動）— 確定觸發 layout 會卡

C：完全避免 layout 操作

機制：把所有可能觸發 reflow 的操作都繞開
跟 A/B 的取捨：C 過度反應、A/B 適度；C 寫法極受限、layout 表達力下降
C 才合理的情境：純動畫場景（沒有 layout 需求）— 對一般 UI 不適用

D：不量、靠經驗判斷

機制：依「我覺得這應該快」做決定
成本特別高的原因：瀏覽器 / 設備 / 場景差異大、直覺不可靠；可能漏掉 forced sync layout 等真正貴的 pattern
D 是反模式：效能 dispute 必須有數字 — 直覺判斷會漏掉 forced sync layout 等真正貴的 pattern、跨設備差異大

判讀徵兆

訊號	該檢查的位置
使用者操作後輕微跳動或卡頓	DevTools Performance 看 Layout 區塊
動畫不順	確認動畫屬性是 transform / opacity 而非 width / left
Layout shift 警告	找出觸發 layout 的元素、量穩定性
Console 出現「Forced reflow」warning	找寫後立刻讀的 DOM pattern

核心原則：Reflow 是 layout 系統的正常運作、不是要消滅的敵人。盤點時量化看哪些值得優化、哪些可以接受。

視覺輔助：對比度、放大、字型 zoom 的 layout 適配

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

核心原則

視覺輔助使用者跟一般使用者「看到的不是同一個 UI」 — 對比度、放大倍率、字型尺寸調整都會把版面變形。 設計時先盤點「在這些變形下、UI 還能用嗎」、不需要等到使用者反映。WCAG 提供量化標準、可以在開發階段驗證。

本篇焦點：視覺呈現面的 a11y（對比 / 放大 / 字型 zoom）。

鍵盤使用者的 a11y（focus indicator / tab 順序）由 #52 鍵盤可達性處理

行動 / motor 使用者的 a11y（hit target / 點擊精準度）由 #53 Motor 可達性處理

為什麼視覺輔助需要獨立盤點

商業邏輯

視覺輔助使用者的需求多元：

情境	需求
色弱（colour blindness）	不依賴顏色區分資訊
低對比敏感	文字 vs 背景對比足夠
低視力（low vision）	字大、可放大、layout 不破
老花、暫時視覺受限	字大、清楚的視覺層次

每類觸發不同的 CSS 行為。一個 UI 在標準視窗看起來 OK、放大 200% 後可能：

字超出容器
Absolute 定位元件跑到視窗外
對比度被覆蓋（dark mode / 高對比模式）

WCAG（Web Content Accessibility Guidelines）提供量化標準（對比度 AA ≥ 4.5:1、放大 200% 不橫向 scroll）— 可在開發階段測量。

視覺呈現的三維度

維度	變形方式	開發階段檢查方法
色彩	dark mode / 高對比模式 / 色弱模擬	DevTools Contrast Ratio + Emulate Vision Deficiencies
整體 zoom	瀏覽器 zoom 200% / OS 放大鏡	Cmd + 5 次、macOS Zoom 4x
字型 zoom	OS Display Scale（只放大字型不放大 box）	OS 設定 Larger Text

三維度獨立、要分開檢查 — 一維度過 ≠ 全部過。

風險點 1：搜尋結果 highlight 對比度

位置：Pagefind 高亮命中關鍵字（黃底）。

判讀：

預設 --pagefind-ui-tag = #eeeeee（淺灰）— 文字 #393939（深灰）、對比 ~9:1、合格
但搜尋頁 dark mode 下、theme 可能讓文字變淺色 — 對淺底要驗證
色弱使用者看不出哪個字是 highlight（若僅靠顏色區分）

WCAG 標準：

等級	對比度要求
AA 一般文字	≥ 4.5:1
AA 大字（≥ 18pt 或 14pt bold）	≥ 3:1
AAA 一般文字	≥ 7:1

第一個該查的：用 Chrome DevTools 的 Contrast Ratio 工具量 highlight 區域的「背景 vs 文字」對比。不足則覆寫 --pagefind-ui-tag 變數。

雙重保險：除了顏色、加 underline 或 bold 區分 highlight — 色弱使用者不靠顏色也能辨識。

風險點 2：Absolute 定位元件在放大模式下跑到視窗外

位置：.search-filter-slot { position: absolute; right: calc(100% + 2rem); }。

判讀：

Absolute 定位相對 main 計算
使用者用 OS 螢幕放大鏡（macOS Zoom）放大 4x 看 main 中央
main 仍在視窗範圍、但 absolute filter 在 main 左外側 — 放大 4x 後可能完全跑到視窗左邊看不見

症狀：低視力使用者用放大鏡時、不知道 filter 存在、無法操作。

第一個該查的：用 macOS 的 Zoom 功能（System Settings > Accessibility > Zoom）放大 4x、看 filter 是否仍在可達範圍。

修正方向：

策略	機制
放大模式 fallback 到 mobile layout	`@media` 偵測 prefers-reduced-motion / 高 zoom level
Filter 移到頁面內 flow（不用 absolute）	跟主要內容一起 reflow、不會跑外
加 floating button「展開 filter」	任何 zoom level 都可達

詳細展開由 #43 最小必要範圍 + #27 runtime 量測模式統一補充。

風險點 3：字型放大 200% 後 layout 破壞

位置：所有寫死 px 高度的元素（H1、search input、filter slot padding）。

判讀：

使用者用瀏覽器 zoom（Cmd +）通常等比放大 — 字 + box 一起放大、layout 不破
但 OS Display Scale（macOS Display > Larger Text）只放大字型不放大 box — 字撐爆寫死的 64px 高度

當 H1 字撐到 80px、寫死 height: 64px 的 box — 字被裁切。

症狀：低視力使用者開啟「文字放大」設定、UI 字被裁。

第一個該查的：開瀏覽器 zoom 200%、看 layout 是否變橫向 scroll（破壞）或仍 reflow（OK）。

WCAG 標準：1.4.4 Resize text — zoom 至 200% 時不需要橫向 scroll。

修正方向：

策略	機制
用 `min-height` 取代 `height`	box 可隨字撐高、不裁切
用 `em` / `rem` 取代 `px`	跟字型一起 scale
用 ResizeObserver 量字型實際高度寫回變數	跟 #27 runtime 量測模式統一同框架

預設用 min-height + 相對單位、特殊精準對齊才用 ResizeObserver。

設計取捨：layout 適應字型放大

當「對齊精度」與「字型放大相容性」衝突、四種做法：

A：用 `min-height` + 相對單位（這個專案的預設）

機制：min-height: 4rem、box 隨字撐高、用 em / rem 跟著 scale
選 A 的理由：字型放大時 layout 自然 reflow、不裁切
適合：絕大多數 UI 元素、不需要極精準對齊
代價：對齊精度受字型 metrics 影響、難以做 pixel-perfect 對齊

B：寫死 `height` + ResizeObserver 量測補償

機制：height: 64px、用 ResizeObserver 量實際渲染高度寫回 CSS 變數、其他依賴此值的元素跟著調
跟 A 的取捨：B 達到 pixel-perfect 對齊、A 信任 reflow；B 多一層 JS 量測、A 純 CSS
B 比 A 好的情境：對齊精度是 UX 核心（搜尋頁的視覺對齊）、字型可預期

C：寫死 `height` + 不處理字型放大

機制：height: 64px、不管字型放大
成本特別高的原因：字型放大時 UI 被裁切、低視力使用者無法用
C 才合理的情境：UI 不會被字型放大影響（純圖示、無文字）

D：用 `clamp(min, ideal, max)` 限制字型大小

機制：字型 font-size: clamp(0.875rem, 1rem, 1.125rem)、限制使用者放大範圍
跟 A/B/C 的取捨：D 主動限制字型放大範圍、違反 WCAG 1.4.4
D 是反模式：違反 WCAG 1.4.4 — 強制限制字型放大是反 a11y、低視力使用者完全無法調整

開發階段檢查清單

每個視覺輔助項目對應一個檢查動作：

檢查	動作	WCAG 等級
對比度	DevTools Inspect Element > Contrast Ratio 看每個文字區域	AA 必要
色彩可辨	DevTools Rendering > Emulate Vision Deficiencies	AA 建議
Zoom 200%	瀏覽器 Cmd + 5 次、看是否仍可用、無橫向 scroll	AA 必要
OS 字型放大	macOS Display > Text Size > 大、看 layout	AA 建議
螢幕放大鏡	macOS Zoom 4x、看絕對定位元件是否在可達範圍	AA 建議

每個 ~30 秒、開發完成前跑一輪、抓常見問題。

設計取捨：色彩區分策略

當資訊需要區分（hit / miss、selected / unselected）、四種做法：

A：顏色 + 形狀 / 位置雙重區分（這個專案的預設）

機制：highlight 用黃底 + bold；selected radio 用色彩 + ✓ 圖示
選 A 的理由：色弱使用者不靠顏色仍能辨識
適合：絕大多數需要區分資訊的場景
代價：UI 多一層視覺裝飾

B：純顏色區分

機制：紅色 = 錯、綠色 = 對
跟 A 的取捨：B 視覺乾淨、A 對色弱友善；B 違反 WCAG 1.4.1 Use of Color
B 是反模式：違反 WCAG 1.4.1 Use of Color（合規層） — 色弱使用者完全無法區分對 / 錯

C：純形狀 / 位置區分（無顏色）

機制：用 ✓ / ✗ / 位置區分、不靠顏色
跟 A 的取捨：C 對色彩無關、A 對視力正常使用者更直覺
C 比 A 好的情境：列印 / 黑白渲染環境

D：使用者可自訂顏色

機制：透過 CSS variable 讓使用者覆寫色彩
跟 A 的取捨：D 提供無限彈性、實作成本高
D 才合理的情境：core a11y 工具（如 reading mode）

跟其他原則的關係

抽象層原則	關係
#43 最小必要範圍	字型放大下 layout 適配是「不依賴特定渲染條件」的應用
#44 SSoT	CSS 變數提供主題切換、變數住址唯一才能正確覆寫色彩

判讀徵兆

訊號	該檢查的位置
色弱使用者反映找不到資訊	DevTools Contrast Ratio + Emulate Vision Deficiencies
低視力使用者反映 UI 跑到視窗外	用螢幕放大鏡放 4x 確認 absolute 元件位置
字型放大後 UI 破	用瀏覽器 zoom 200% 與 OS text size 雙測
Dark mode 下文字看不清	該主題的對比度未驗證、補測
「色弱使用者反正不多」當不做的理由	視覺輔助使用者通常不會反映、只默默離開 — 量化檢查不靠使用者通報

核心原則：視覺輔助使用者用的是「同一份程式、不同的 viewport / colour / scale」。WCAG 提供量化標準、開發階段可測 — 等使用者反映晚了。

CSS / JS Boundary — CSS / JS 邊界與 specificity 處理

Sun, 26 Apr 2026 00:00:00 +0000

CSS 跟 JS 各自負責什麼、邊界由「值能不能 build-time 定下來」決定。!important / inline style / specificity 戰是訊號、不是工具。

適用：寫 / 改 CSS 規則、決定 styling 該放 CSS 還是 JS、跟 vendor CSS 共存、檔案組織。不適用：純 logic JS（沒涉及 styling）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋 CSS-only vs JS-assisted 判準、class toggle 模式、CSS layers、variable 單一位置、檔案拆分。

何時參閱本文件

訊號	該做的第一件事
不確定值該寫進 CSS 還是 JS	問「能 build-time 定下來嗎」
即將寫 `!important`	停 — 換 CSS layers 思路
即將寫 `el.style.setProperty(..., 'important')`	停 — 換 class toggle
Inline