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}

原本的 <link href="...pagefind-ui.css" rel="stylesheet"> 改成上方 @import 寫法、確保 import 在自家 CSS 之前發生（layered CSS 不會阻擋 unlayered CSS 的優先級）。

內在屬性比較：四種 specificity 應對

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（從 <link> 改 @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）取代

判讀徵兆

核心原則：跟組件 CSS 競爭 specificity 是不必要的戰爭。Layers 提供更高層的權重機制、把覆寫簡化成「自家 vs 別人」的二元決定。

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 內看似省事（一個檔案搞定），但隨著規模上升出現多個成本：

拆檔的成本是「多 1-2 個檔案」、收益是「multiple」 — 過了 30 行門檻、ROI 已正向。

拆檔的實際得益

這次任務的拆檔目標

觀察

layouts/_default/search.html 現況：

220 行的 single-file template、CSS / JS 各超過拆檔門檻 3-4 倍。

判讀

把 CSS 拆到 assets/search.css、JS 拆到 assets/search.js、template 只剩 HTML 結構與 Hugo 引入。

執行：拆檔步驟

Step 1：建立 assets 檔

1assets/
2├── search.css      # 原本 inline <style> 內容
3└── search.js       # 原本 inline <script> 內容

Step 2：template 引入

 1{{ define "main" }}
 2{{- $css := resources.Get "search.css" | minify | fingerprint -}}
 3<link href="{{ $css.RelPermalink }}" rel="stylesheet" integrity="{{ $css.Data.Integrity }}">
 4
 5<div data-pagefind-ignore class="search-shell">
 6  ...
 7</div>
 8
 9{{- $js := resources.Get "search.js" | minify | fingerprint -}}
10<script src="{{ $js.RelPermalink }}" integrity="{{ $js.Data.Integrity }}" defer></script>
11{{ end }}

Step 3：JS 從全域 window.PagefindUI 改為 module 模式

如果原本 inline JS 用 new PagefindUI(...) 直接執行、拆檔後仍然可以這樣寫。但若想進一步，把 init 包成 function：

 1// assets/search.js
 2(function () {
 3  function init() {
 4    new PagefindUI({ ... });
 5    // ... rest of setup
 6  }
 7  if (document.readyState === 'loading') {
 8    document.addEventListener('DOMContentLoaded', init);
 9  } else {
10    init();
11  }
12})();

Step 4：清理 template

Template 從 220 行降到 ~30 行 — 只剩 HTML 結構。

內在屬性比較：四種引入方式

優先選 fingerprint — Hugo 自動處理快取、瀏覽器看到內容變動的 fingerprint 一定 reload。

Hugo Resources Pipeline 的細節

resources.Get

1{{ $css := resources.Get "search.css" }}

讀 assets/search.css。如果路徑下沒有、回傳 nil（要做 nil 檢查）。

| minify

去除空白、註解、合併 selector — 減少傳輸大小。

| fingerprint

對檔案內容做 hash、加到 URL（search.abc123.css）。內容變動時 fingerprint 變、瀏覽器把它當新檔案。

.RelPermalink / .Permalink

RelPermalink — site root 相對路徑（/search.abc123.css）
Permalink — 完整 URL（https://site.com/search.abc123.css）

通常用 RelPermalink 即可。

.Data.Integrity

Subresource Integrity hash — 給 integrity attribute 用、瀏覽器驗證下載內容沒被篡改。

拆檔的判斷門檻

當前 search.html 的 ~190 行 inline 程式碼遠超門檻、屬於「強烈建議拆」。

設計取捨：CSS / JS 引入策略

四種做法、各自機會成本不同。這個專案在 inline > 30 行時選 A（拆檔 + Hugo pipeline）當預設、其他做法在特定情境合理。

A：拆檔 + Hugo resources.Get | minify | fingerprint（這個專案的預設）

• 機制：CSS / JS 拆到 assets/、template 用 resources.Get | minify | fingerprint 引入
• 選 A 的理由：minify 自動、cache-bust 自動、editor syntax highlight、跨 template 重用
• 適合：規模超過 30 行、預期長期維護的客製
• 代價：多 1-2 個檔案、template 跟 assets 分屬兩處（grep 多一步）

B：拆檔 + 直接 <link> / <script> tag

• 機制：拆檔到 static/ 或 assets/、template 直接 link
• 跟 A 的取捨：B 簡單、A 自動處理 minify / fingerprint；B 改檔案後 cache 可能用舊版（要手動加版本號）
• B 比 A 好的情境：簡單 prototype、確定不需要 cache-bust（純內部工具）

C：保持 inline

• 機制：CSS / JS 寫在 template 的 <style> / <script> 內
• 跟 A 的取捨：C 一個檔案搞定、A 拆兩個；但 C 在 30+ 行時 syntax highlight 失效、難維護
• C 比 A 好的情境：< 10 行的小段、跟 template 邏輯緊密相關

D：CDN 引入第三方資源

• 機制：<script src="https://cdn.../lib.js">
• 成本特別高的原因：依賴第三方可用性、跨域 CORS / SRI 處理、隱私問題（追蹤）
• D 才合理的情境：第三方明確支援 SRI 且 CDN 是官方建議方式（少數 vendor library）

判讀徵兆

核心原則：Template 是 markup 的家、CSS / JS 是各自獨立檔案的家。三者混在一個檔案是過渡狀態、不是長期方案。

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 順序決定 — 維護者不易看出哪個值生效。

統一定義的位置選擇

選擇原則：定義在「跟使用範圍最匹配的最高層級」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 到所有後代生效。

變數命名與分類

命名前綴標明範圍

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

分類定義

 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」、找對位置。

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

優先選「集中 + 分類 + 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

判讀徵兆

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

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

對齊基準上的尺寸值、要嘛統一寫死、要嘛統一 runtime 量測 — 不要混搭。 混搭時某些變化（字型替換、scale 改變、theme 切換）會打破對齊、且問題只在特定情境出現、難以重現。選一邊走到底。

為什麼混搭會不穩

商業邏輯

對齊問題本質是「方程組」 — 每個變數的值都要正確、結果才對。

寫死值的特徵：

• 來源是 build time 設計決定
• 變動需要手動改 CSS
• 假設某個渲染條件成立（特定字型、特定 scale）

量測值的特徵：

• 來源是 runtime DOM 量測
• 自動跟著實際渲染走
• 不依賴特定渲染條件

混搭時的失敗模式：寫死值依賴的渲染條件變了、但量測值跟著變、寫死值沒跟 — 兩者錯位、對齊壞掉。

統一往一邊靠的選擇

選擇看「願意接受多少不確定性」 — 全寫死要鎖很多條件、全量測要寫多個 ResizeObserver。

這次任務的混搭問題

觀察

對齊基準上四個值的處理：

混搭：前三個寫死、第四個量測。

判讀

當前情境穩定 — pagefind scale 鎖在 1.0、theme h1 高度可預測。但若：

• Theme 升級改 h1 line-height → 寫死 64px 不準
• 使用者裝置字型不同 → form 內容寬度變動可能間接影響高度
• pagefind 升級 input 高度算法 → 寫死 68px 不準

寫死值「假設某些條件成立」、條件變了寫死值就錯。

執行：兩種統一方向

方向 1：全部寫死、鎖更多渲染條件

 1body.page-search {
 2  --search-title-h: 64px;
 3  --search-form-h: 68px;
 4  --search-gap: 20px;
 5  --search-scope-h: 56px;            /* 不再 JS 量測 */
 6  --pagefind-ui-scale: 1.0;
 7}
 8
 9.search-title {
10  height: var(--search-title-h);
11  line-height: var(--search-title-h);
12  margin: 0;                         /* 鎖 H1 margin */
13}
14
15.search-scope {
16  height: var(--search-scope-h);     /* 鎖 scope 高度、超過裁掉 */
17  overflow: hidden;
18}

代價：scope 內容超過時被裁、UI 可能不適合動態內容。

方向 2：全部量測、ResizeObserver 同步所有

 1function measureAll() {
 2  setVar('--search-title-h', titleEl.offsetHeight);
 3  setVar('--search-form-h', formEl.offsetHeight);
 4  setVar('--search-scope-h', scopeEl.offsetHeight);
 5  // gap 是 pagefind drawer 內建、無法從外部量測
 6}
 7function setVar(name, val) {
 8  document.body.style.setProperty(name, val + 'px');
 9}
10
11[titleEl, formEl, scopeEl].forEach(el => {
12  new ResizeObserver(measureAll).observe(el);
13});

代價：JS 多了一層、初始載入時 fallback 值不對齊（直到 JS 跑完）。

推薦

這個專案選方向 1（全寫死）：

• Pagefind scale 已能鎖定
• Theme 由本人控制、h1 變動可預期
• Scope UI 設計成單行、不需要動態高度

把當前 scope-h 從量測改寫死、移除 ResizeObserver。混搭問題消失。

內在屬性比較：四種對齊值來源策略

選擇順序：內容靜態 → 全寫死；內容動態 → 全量測；不要混搭。

鎖定渲染條件的具體技巧

1. 使用組件提供的 scale hook

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

讓組件按我們指定的 scale 渲染、寫死值才有意義。

2. 寫死 H1 height + line-height + margin

1.search-title {
2  height: 64px;
3  line-height: 64px;
4  margin: 0;
5  /* 確保 box height 永遠是 64、不受 font / padding 影響 */
6}

不留任何「看 box-sizing 與 inheritance 決定」的空間。

3. 用 box-sizing: border-box 確保 padding 不影響 box height

1.search-scope {
2  box-sizing: border-box;
3  height: var(--search-scope-h);
4  padding: 8px 16px;
5  /* total height 還是 var(--search-scope-h)、padding 算在內 */
6}

設計取捨：對齊基準上來源機制的選擇

四種做法、各自機會成本不同。預設依內容性質選 — 內容靜態 → A、內容動態 → B、混搭 / 估算永遠不是答案。

本篇是 #44 SSoT 抽象原則在「來源機制統一」這個面向的應用。

A：全寫死 + 鎖渲染條件（內容靜態的預設）

• 機制：所有對齊基準值用 CSS 變數寫死、同時鎖定相關渲染條件（pagefind scale、H1 line-height、box-sizing）
• 選 A 的理由：純 CSS 不依 JS、值 build time 確定、改 token 自動跟上
• 適合：對齊內容靜態、可預測（設計穩定的搜尋頁、文章頁）
• 代價：需要鎖很多渲染條件（scale / line-height / box-sizing 等）、scope 內容超過寫死值會被裁

B：全量測 ResizeObserver 寫回變數（內容動態的預設）

• 機制：所有對齊基準值用 ResizeObserver 量、寫回 CSS 變數、其他元素引用
• 跟 A 的取捨：B 自動跟著實際渲染、A 假設條件穩定；B 多 JS 一層、初始 fallback 值不對齊（直到 JS 跑完）
• B 比 A 好的情境：內容動態（字型可能變、theme 切換、跨環境部署）

C：混搭（部分寫死、部分量測）

• 機制：「主要值寫死、邊界值量測」混合策略
• C 是反模式：邊界情境（字型變、scale 變、theme 切換）下兩者錯位、對齊在某些 case 壞、難以重現
• 看起來吸引人的原因：「主要情境寫死、邊界情境量測」聽起來合理、實際「主要 vs 邊界」判斷不可靠
• 實際發生的代價：邊界常常變主要、混搭策略下 debug 範圍從「某情境」擴張到「整套是不是錯」

D：Magic number 估算

• 機制：執行者依感覺給數字、不寫變數、不量測
• D 是反模式：任何「沒來源」的值都會在邊界情境爆掉 — 跨情境（字型 / scale / theme）必壞
• 看起來吸引人的原因：執行者依感覺給數字最快、不用 query 也不用 query DevTools
• 實際發生的代價：估錯時錯誤被視覺接受、ship 後在邊界情境暴露、信任損失

判讀徵兆

核心原則：對齊問題的根因常常是「混搭」 — 用統一策略消除這個根因、debug 範圍從「某個情境」縮到「整套策略對嗎」。

混搭通常是便利驅動的結果（每處用最快的方式）、統一策略需要先對齊原則 — 同 #44 SSOT 跟 #67 便利 vs 對齊反相關。

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

為什麼 class toggle 比 inline style 好

商業邏輯

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

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

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

何時 inline style 是必要的

「狀態切換」是 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 控制視覺方式

優先選 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 表達多分支

判讀徵兆

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

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

等待元素出現用 MutationObserver、不用 setTimeout 輪詢。 Observer 是 event-driven、元素出現的瞬間觸發、無延遲；輪詢是 time-based、最快回應時間 = 輪詢間隔、且 CPU 一直跑。

輪詢只在「沒有事件可監聽」時才用。

為什麼 observer 比輪詢好

商業邏輯

「等待某個 DOM 元素出現」這件事的本質是「監聽 DOM 變化、出現時觸發」 — 完全是 event-driven 場景。

setTimeout 輪詢的特徵：

• 每隔 N ms 檢查一次、最快 N ms 才能回應
• 即使元素已經出現、要等到下次檢查才知道
• CPU 持續被佔用（即使元素永遠不出現）

MutationObserver 的特徵：

• 元素出現的瞬間觸發 callback
• 0 延遲
• DOM 沒變動時 observer 不耗 CPU

兩者效能差異在現代設備上不明顯、但設計上 observer 才是「適合這個場景」的工具。

何時輪詢是必要的

「無事件可監聽」時才輪詢 — 這類場景在現代 Web 開發少見。

這次任務的輪詢

觀察

search.html 用 setTimeout 等 pagefind UI mount：

 1function waitAndInit() {
 2  filter = document.querySelector('.pagefind-ui__filter-panel');
 3  drawer = document.querySelector('.pagefind-ui__drawer');
 4  if (!filter || !drawer) {
 5    setTimeout(waitAndInit, 100);
 6    return;
 7  }
 8  // 找到了、開始 setup
 9  place();
10  reorderFilters();
11  setupScopeFilter();
12  mql.addEventListener('change', place);
13}
14waitAndInit();

每 100ms 檢查一次、有延遲、CPU 一直跑（雖然輕）。

判讀

改用 MutationObserver 監聽 #search（pagefind mount target）的子節點變化：

 1function waitForPagefind(searchRoot, onReady) {
 2  // 已經存在則立即觸發
 3  if (searchRoot.querySelector('.pagefind-ui__drawer')) {
 4    onReady();
 5    return;
 6  }
 7  // 否則 observe DOM 變動
 8  var observer = new MutationObserver(function () {
 9    if (searchRoot.querySelector('.pagefind-ui__drawer')) {
10      observer.disconnect();
11      onReady();
12    }
13  });
14  observer.observe(searchRoot, { childList: true, subtree: true });
15}
16
17waitForPagefind(document.getElementById('search'), function () {
18  filter = document.querySelector('.pagefind-ui__filter-panel');
19  drawer = document.querySelector('.pagefind-ui__drawer');
20  place();
21  reorderFilters();
22  setupScopeFilter();
23  mql.addEventListener('change', place);
24});

特性：

• pagefind 渲染完瞬間觸發、無延遲
• disconnect() 後 observer 不再耗資源
• 已存在時 fast path 直接觸發

執行：通用 helper

 1/**
 2 * 等待 selector 在 root 內出現、觸發 callback。
 3 * 已存在則 sync 觸發；不存在則用 MutationObserver 等待。
 4 */
 5function waitForElement(root, selector, callback) {
 6  var existing = root.querySelector(selector);
 7  if (existing) {
 8    callback(existing);
 9    return;
10  }
11  var observer = new MutationObserver(function () {
12    var el = root.querySelector(selector);
13    if (el) {
14      observer.disconnect();
15      callback(el);
16    }
17  });
18  observer.observe(root, { childList: true, subtree: true });
19}
20
21// 用法
22waitForElement(searchRoot, '.pagefind-ui__drawer', function (drawer) {
23  // 開始 setup
24});

把 wait 抽成 helper、setup code 變得更簡潔。

內在屬性比較：四種等待機制

優先順序：event-driven > async > polling > timeout。輪詢是最後選擇。

MutationObserver 的細節

Observe option 選對

1observer.observe(root, {
2  childList: true,    // 直接子節點增減
3  subtree: true,      // 包含深層子節點
4  attributes: false,  // 不看 attribute 變動
5  characterData: false,
6});

只勾必要的、不要全部勾 — 觸發頻率影響效能。

找到目標後 disconnect

1var observer = new MutationObserver(function () {
2  if (found) {
3    observer.disconnect();   // 立刻停、不要繼續監聽
4    callback();
5  }
6});

不 disconnect 的話、observer 一直 active、未來任何 DOM 變動都觸發 callback。

已存在的 fast path

1if (root.querySelector(selector)) {
2  callback();   // 已存在則直接觸發、不需 observer
3  return;
4}

避免「元素已經存在但還是要等下次變動才觸發」的延遲。

設計取捨：等待 DOM 元素出現的策略

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

A：MutationObserver + already-exists fast path（這個專案的預設）

• 機制：先檢查目標是否已存在（直接觸發）、否則 observe DOM 變動、找到後 disconnect
• 選 A 的理由：0 延遲、CPU 不被輪詢吃、找到後立即停
• 適合：等待 framework / 第三方 library 動態 mount 的元素
• 代價：需要寫 fast path + observer + disconnect 三段邏輯（用 helper 包裝即可一行調用）

B：setTimeout 輪詢

• 機制：每隔 N ms 檢查、找到就停
• 跟 A 的取捨：B 寫法簡單、A 設計嚴謹；但 B 有最快回應 = N ms 的延遲、CPU 一直跑
• B 比 A 好的情境：等待對象是無事件可監聽的狀態（全局變數出現、外部 API 結果且無 promise 介面），MutationObserver 無處掛載

C：Promise / async（如果 API 提供）

• 機制：await framework.ready() 等 framework 提供的 promise
• 跟 A 的取捨：C 是最乾淨的解、但需要 framework / library 提供 promise API
• C 比 A 好的情境：等的目標有官方 promise 介面（避免自行 observe 內部 DOM）

D：requestAnimationFrame 迴圈

• 機制：每個 frame 檢查一次
• 跟 B 的取捨：D 跟著 frame、不會在 idle 時跑；但仍是輪詢、延遲 16ms
• D 才合理的情境：等待動畫 frame 相關狀態（罕見）— 純等 DOM 元素仍應用 A

判讀徵兆

核心原則：DOM 變動有對應的 event 機制可監聽 — 用對機制就有 0 延遲、無 CPU 浪費。輪詢是「沒辦法的辦法」、不是 default。

單一函式做 ≥ 3 件無關的事就拆。 每個函式只負責一個職責、有明確的 input / output、可以獨立 debug 與測試。Init function 變成「組合各職責 function 的 orchestrator」。

為什麼拆函式

商業邏輯

單一函式做多件事的成本：

拆函式的成本是「多寫幾個函式名與簽名」、收益是「每個函式範圍小、debug 容易、可單獨重用」。

拆的依據是「職責」、不是行數

按職責拆的判斷：能不能用一個動詞片語描述函式做什麼？做不到 → 多個職責、該拆。

這次任務的拆分機會

觀察

setupScopeFilter() 現況做 5 件事：

 1function setupScopeFilter() {
 2  // 1. 找元素
 3  var scopeEl = document.querySelector('.search-scope');
 4  var input   = document.querySelector('.pagefind-ui__search-input');
 5  // ...
 6
 7  // 2. 量測 scope 高度寫回 CSS 變數
 8  function syncScopeHeight() { ... }
 9  syncScopeHeight();
10  new ResizeObserver(syncScopeHeight).observe(scopeEl);
11
12  // 3. 把 filter-panel 搬到 sidebar (position function)
13  function place() { ... }
14
15  // 4. 註冊 scope filter listener + apply
16  function apply() { ... }
17  scopeEl.addEventListener('change', apply);
18  // ...
19
20  // 5. Reorder filter blocks
21  function reorderFilters() { ... }
22  reorderFilters();
23}

5 個職責塞在一個函式：找元素、量高度、搬 slot、scope filter、reorder filter。

判讀

按職責拆成獨立函式：

 1function findSearchElements(shell) {
 2  return {
 3    shell:  shell,
 4    ui:     shell.querySelector('.pagefind-ui'),
 5    input:  shell.querySelector('.pagefind-ui__search-input'),
 6    drawer: shell.querySelector('.pagefind-ui__drawer'),
 7    filter: shell.querySelector('.pagefind-ui__filter-panel'),
 8    scope:  shell.querySelector('.search-scope'),
 9  };
10}
11
12function syncScopeHeight(scopeEl) {
13  function update() {
14    var h = scopeEl.offsetHeight || 56;
15    document.body.style.setProperty('--search-scope-h', h + 'px');
16  }
17  update();
18  new ResizeObserver(update).observe(scopeEl);
19}
20
21function setupFilterSlotSwap(filter, drawer, slot, breakpoint) {
22  var mql = window.matchMedia('(min-width: ' + breakpoint + 'px)');
23  function place() {
24    if (mql.matches) slot.appendChild(filter);
25    else drawer.insertBefore(filter, drawer.firstChild);
26  }
27  place();
28  mql.addEventListener('change', place);
29}
30
31function reorderFilters(filterPanel, desiredOrder) {
32  var blocks = filterPanel.querySelectorAll('.pagefind-ui__filter-block');
33  var byKey = {};
34  blocks.forEach(function (b) {
35    var key = b.querySelector('.pagefind-ui__filter-name').textContent.trim().toLowerCase();
36    byKey[key] = b;
37  });
38  desiredOrder.forEach(function (k) {
39    if (byKey[k]) filterPanel.appendChild(byKey[k]);
40  });
41}
42
43function setupScopeFilter(scopeEl, input, ui) {
44  function getScope() { ... }
45  function apply() { ... }
46  function schedule() { ... }
47  scopeEl.addEventListener('change', schedule);
48  input.addEventListener('input', schedule);
49  new MutationObserver(schedule).observe(ui, { childList: true, subtree: true });
50}

init() 變成 orchestrator：

 1function init() {
 2  var shell = document.querySelector('.search-shell');
 3  if (!shell) return;
 4
 5  waitForElement(shell, '.pagefind-ui__drawer', function () {
 6    var els = findSearchElements(shell);
 7    syncScopeHeight(els.scope);
 8    setupFilterSlotSwap(els.filter, els.drawer, document.querySelector('.search-filter-slot'), 1400);
 9    reorderFilters(els.filter, ['type', 'tag']);
10    setupScopeFilter(els.scope, els.input, els.ui);
11  });
12}
13init();

每個拆出的函式：

• 名字描述做什麼（動詞 + 名詞）
• 接受需要的元素當參數（不依賴全局）
• 不知道其他函式的存在（解耦）

內在屬性比較：四種函式拆分粒度

優先按職責拆 — 函式名表達 intent、debug 範圍小、單獨可測。

拆函式的具體技巧

1. 函式名是動詞片語

1syncScopeHeight()           // 動詞 + 對象
2setupFilterSlotSwap()       // 動詞 + 對象
3reorderFilters()            // 動詞 + 對象
4findSearchElements()        // 動詞 + 對象

不要：

1filter()        // 動詞模糊（filter 是動詞還是名詞？）
2handle()        // 太抽象
3init()          // 只有 orchestrator 用、不要散在各處

2. 參數是該函式需要的、不傳一個 mega object

1// 好 — 函式知道它需要什麼
2function syncScopeHeight(scopeEl) { ... }
3
4// 較差 — 函式拿到一堆無關的東西、不清楚依賴
5function syncScopeHeight(allElements) {
6  var scope = allElements.scope;
7  ...
8}

明確參數 = 明確依賴 = 容易測試。

3. 副作用集中在一處

1function syncScopeHeight(scopeEl) {
2  function update() {
3    document.body.style.setProperty('--search-scope-h', scopeEl.offsetHeight + 'px');
4  }
5  update();
6  new ResizeObserver(update).observe(scopeEl);
7}

副作用（DOM 變動、event listener、observer）都在這個函式內。沒散到別處。

4. 不依賴外部變數

1// 好 — 純函式、依賴只在參數
2function reorderFilters(filterPanel, desiredOrder) { ... }
3
4// 較差 — 依賴外部全局變數
5var desiredOrder = ['type', 'tag'];
6function reorderFilters(filterPanel) {
7  // 用了 desiredOrder
8}

純函式 = 無隱式依賴 = 重用方便、測試方便。

設計取捨：大型 init function 的拆分策略

四種做法、各自機會成本不同。這個專案選 A（按職責拆 + 純函式）當預設、其他做法在特定情境合理。

A：按職責拆 + 純函式 + init 當 orchestrator（這個專案的預設）

• 機制：每職責一個函式（動詞 + 對象命名）、依賴透過參數傳入、init 組合各函式
• 選 A 的理由：debug 範圍小（職責 = 函式 = grep 範圍）、單獨可測、可重用
• 適合：> 50 行的 init function、預期長期維護
• 代價：多寫幾個函式名與簽名、檔案 LOC 略增

B：按行數機械拆（每 30 行一份）

• 機制：固定 LOC 拆檔、不考慮職責邊界
• 跟 A 的取捨：B 拆完後切片無邏輯意義、A 切片各自完整；B 更亂、debug 反而更難
• B 是反模式：「行數」不是有意義的拆分判準 — 拆完後切片無邏輯意義、debug 反而更難

C：保持 mega init function

• 機制：所有 setup 邏輯塞在一個 init 內
• 跟 A 的取捨：C 一個函式看完所有 setup、A 散在多函式；但 C 在 200+ 行時改一處要小心整體
• C 才合理的情境：< 50 行的 init、職責本來就單一

D：按職責拆 + class 包裝多實例

• 機制：把 setup 包成 class、new SearchShell(rootEl) 建立實例
• 跟 A 的取捨：D 多實例支援更乾淨（每實例自己的 state）、A 用純函式 + 起點當參數也能達成
• D 比 A 好的情境：元件有複雜的內部 state、預期會被多次實例化（library 設計）

判讀徵兆

核心原則：函式是「做一件事」的單位。一個函式越多職責、debug 與重用越難。拆 = 投資、回報是未來的維護成本下降。

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  // ... 所有 query 從參數 shell 開始
6}
7
8document.querySelectorAll('.search-shell').forEach(setupSearchShell);

元件根不在函式內 query、由呼叫者傳入。函式支援任意數量的元件實例。

這個做法存在的價值

兩件事：

1. 多實例支援免費：forEach(setup) 自動處理多個 shell
2. 純函式特性：函式行為只依賴參數、不依賴外部狀態 — 可單獨測試、可重用、副作用集中

跟元件根變數的關鍵差異：那個 pattern 假設「shell 唯一」、本 pattern 把這個假設外移到呼叫端、函式本身不假設。

適合的情境

核心特徵：把「shell 從哪來」這個責任明確交給呼叫端、函式自己不關心。

不適合的情境

設計細節

函式簽名的設計

 1// 好：shell 是必填參數
 2function setupSearchShell(shell) { ... }
 3
 4// 較差：依賴外部變數
 5var shell;  // module scope
 6function setupSearchShell() {
 7  // 用了外部 shell
 8}
 9
10// 更差：mega object
11function setupSearchShell(allElements) {
12  var shell = allElements.shell;  // 不知道實際依賴什麼
13  // ...
14}

明確參數 = 明確依賴 = 容易測試、容易讀。

內部子函式也接受 shell

 1function setupSearchShell(shell) {
 2  syncScopeHeight(shell);
 3  setupFilterSlot(shell);
 4  setupScopeFilter(shell);
 5}
 6
 7function syncScopeHeight(shell) {
 8  var scope = shell.querySelector('.search-scope');
 9  // ...
10}

每層都明確接受 shell — 不依賴外層 closure。整套函式族都是純函式。

預先抓子節點 vs 每次重 query

 1// 方式 A：函式入口抓所有子節點
 2function setupSearchShell(shell) {
 3  var els = {
 4    ui:     shell.querySelector('.pagefind-ui'),
 5    input:  shell.querySelector('.pagefind-ui__search-input'),
 6    drawer: shell.querySelector('.pagefind-ui__drawer'),
 7  };
 8  // 後續用 els.ui / els.input / els.drawer
 9}
10
11// 方式 B：各子函式自己 query
12function setupSearchShell(shell) {
13  syncScopeHeight(shell);  // 內部自己 querySelector
14  setupFilterSlot(shell);
15}

A 比較有效率（只 query 一次）、B 比較解耦（子函式自包含）。選 B 為預設、效能瓶頸時才考慮 A。

跟其他起點做法的關係

#14 Selector 精準度 的「起點」維度有四種做法：

升級階梯：document → 元件根變數 → 起點當參數 → closest。複雜度遞增、能處理的情境也遞增。

應用範例：多實例 setup

1// 頁面有 N 個 search-shell（例如多語版面切換）
2document.querySelectorAll('.search-shell').forEach(setupSearchShell);
3
4// 跑完之後：每個 shell 各自獨立 setup、互不干擾

當前頁只一個 shell、上面這行也適用 —forEach 對 1 個元素跑一次、跟 hardcode 單例沒差。做了多實例設計、未來不需要重寫。

應用範例：單元測試

純函式可以對 mock DOM 測試：

1test('setupSearchShell 把 filter 移到 sidebar', function () {
2  var shell = createMockShell();  // 建立測試用 DOM
3  setupSearchShell(shell);
4
5  expect(shell.querySelector('.search-filter-slot').children.length).toBe(1);
6});

不需要全頁面 mount、只需要 mock 一個 shell — 測試成本低。

判讀徵兆

核心原則：本 pattern 把「我從哪取得 shell」的答案從函式內搬到呼叫端 — 換到「函式可重用」+「測試容易」+「多實例免費」三個收益、代價是函式簽名多一個參數。當前情境只一個實例也適用、未來擴展不需重寫。