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

為什麼對齊需要單一來源

商業邏輯

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

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

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

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

這次任務的實際應用

觀察

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

判讀

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}

對齊問題的兩種失敗模式

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

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

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

核心定義：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 後在邊界情境暴露

判讀徵兆

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

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

為什麼缺一個值整個壞

商業邏輯

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

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

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

跳過第 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。

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

執行

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

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

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

不要把「估算 / 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 變數、會在邊界情境爆掉

判讀徵兆

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

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

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

為什麼排擠式做法行不通

商業邏輯

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

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

兩種共存模式比較

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

這次任務的實際做法

觀察

搜尋頁 desktop layout：

• <main> 寬度 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 的物理空間預算〉。

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

選擇順序：先確認中央欄的位置要求。要嚴格置中 → 疊層式；可隨 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 內

判讀徵兆

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

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

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

商業邏輯

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

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

三層拆解 debug 法

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

這次任務的實際情境

觀察

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

判讀

第一輪猜測：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 的直接子節點 — 它在 <form> 內。

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

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 顯示「實際巢狀關係」。兩者一起看才知道規則為什麼沒生效。

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

當一個元件需要在多種狀態下保持固定位置 — 優先 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）

判讀徵兆

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