@qijenchen/design-system 0.1.0-beta.10 → 0.1.0-beta.13

package/src/components/PeoplePicker/people-picker.spec.md

@@ -0,0 +1,263 @@
+---
+component: PeoplePicker
+family: 4
+variants: {}
+sizes: {}
+traits:
+  - isInputLike
+benchmark:
+  - Ant Design Mentions: github.com/ant-design/ant-design/tree/master/components/mentions
+  - MUI Autocomplete: github.com/mui/material-ui/tree/master/packages/mui-material/src/Autocomplete
+  - Polaris Combobox: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Combobox
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# PeoplePicker 設計原則
+
+## 定位
+
+PeoplePicker 是**人員選擇器**——專為「從人員清單中選一個或多個」設計的複合元件。外觀對齊 Select / Combobox，差異在選項前綴有 Avatar 視覺。
+
+**實作基礎**：組合元件——Popover + Command（cmdk）搜尋 + SelectMenu 浮層 + PersonDisplay render。無直接 external primitive base（底層靠 shadcn passthrough 的 Popover / Command）。
+
+共用規則見 `../Field/field-controls.spec.md`。本文件只記錄 PeoplePicker 特有的原則。
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 4（Field control layout）** 消費者。結構繼承 `components/Field/field-controls.spec.md` 的 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1（Menu item）讓 SelectMenu trigger + options 連續一致。
+
+---
+
+## 何時用
+
+- **指派人員**：指派 task、assignee、reviewer 選擇
+- **加入成員**：team / channel / project 加人
+- **@提及選擇器**：文章 / 留言 / chat 內插入 @user
+- **多人協作選擇**：訂單協作人員、共同擁有者
+- **需要 avatar 視覺識別**：人員清單視覺辨識高於純文字 label
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 一般分類選擇（非人員）| `Select` / `Combobox` | PeoplePicker 專為人員設計，有 Avatar prefix |
+| 單選純文字選項（狀態 / 類別）| `Select` | PeoplePicker 開銷較大，靠 Avatar 識別；非人員用 Select |
+| 多選非人員 tag | `Combobox` | Combobox 是通用多選，無 Avatar 假設 |
+| 只顯示單一人員（不需選擇）| `NameCard` + `Avatar` | PeoplePicker 是選擇器，純展示用 NameCard |
+| 顯示整個 team 成員列表 | `Avatar.Group` / 自訂 list | PeoplePicker 是「選人」介面，不是「展示 team」 |
+
+---
+
+## 單選 vs 多選
+
+透過 `value` prop 的類型決定：
+
+| 模式 | value 類型 | 視覺 |
+|------|-----------|------|
+| 單選 | `PersonValue \| null` | Field 顯示單一 Avatar + Name |
+| 多選 | `PersonValue[]` | Field 顯示 Avatar 陣列（與 Combobox 多選同模式）|
+
+**判斷**：
+- 「這個 task 指派給誰」→ 單選（assignee 通常一個）
+- 「選擇 reviewers」→ 多選（reviewer 可多人）
+- 「加入 channel 的成員」→ 多選
+- 「文章作者」→ 單選
+
+---
+
+## 搜尋
+
+PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為人員清單通常規模較大且使用者記得人名關鍵字（符合 Select spec「Searchable 開啟判斷」的「label 性質」主判準：人名是獨特關鍵字）。
+
+- **搜尋 placeholder**：預設「搜尋人員…」，可透過 `searchPlaceholder` 覆寫
+- **空狀態**：預設「沒有符合的人員」，透過 `emptyText` 覆寫
+
+---
+
+## 與 Select / Combobox 的分界
+
+| | PeoplePicker | Select | Combobox |
+|---|---|---|---|
+| 資料類型 | **人員**（含 Avatar） | 任意（純文字）| 任意（純文字）|
+| 單選 / 多選 | 兩者皆支援（value 類型決定）| 單選 | 多選 |
+| 視覺 prefix | Avatar（必備） | 可選 startIcon | 無 |
+| 底層實作 | Popover + Command + SelectMenu | native `<select>` | native `<select>` + Tag overlay |
+| 搜尋 | 永遠啟用（人名本質）— 走 inline-trigger | 可選 `searchable`（單選短列表 → inline-trigger only）| 可選 `searchable` + `searchIn='menu' \| 'trigger'`（多選 → 兩種模式）|
+
+**搜尋型態 SSOT canonical**（A1-A5 spec,2026-05-11;2026-05-12 補 PeoplePicker multi `searchIn` opt-in）：
+
+| 型態 | 使用情境 | 元件 API |
+|---|---|---|
+| **none** | 短列表 (< 7 選項) / 自然語言 label 可用 native type-ahead | 不傳 `searchable` |
+| **inline-trigger** | 單選 + 需快速 type-and-pick;trigger 變 input | `<Select searchable />` / `<Combobox searchable searchIn='trigger' />` / `<PeoplePicker />` single / `<PeoplePicker multi searchIn='trigger' />` |
+| **panel-top** | 多選 + 連續 type-and-select(關鍵字保留在 menu 不被 chip 切走) | `<Combobox searchable searchIn='menu' />` / `<PeoplePicker multi />`(default menu) |
+
+### Trigger display SSOT canonical table(2026-05-15 v3 user verbatim 整理)
+
+**PeoplePicker 是獨立元件,有自己的另一層 SSOT,並非完全繼承 Select / Combobox**。下表標出哪些繼承、哪些 PeoplePicker 自己定義 — **改一處先看本表,違反該層 SSOT = 漂移**。
+
+#### A. 元件本質繼承表
+
+| 面向 | 來源 SSOT |
+|---|---|
+| 單人互動邏輯(open/close/keyboard/搜尋)| **繼承 Select**(只多套一層 Avatar 視覺包裝)|
+| 多人互動邏輯(N tag / overflow / inline-search)| **繼承 Combobox**(但 tag 和溢出**換成圓形 avatar 視覺**)|
+| Avatar 在 field 內 padding(12px 固定)| **PeoplePicker 自己**(不繼承 Combobox density-dependent 公式)|
+| +N 溢出 chip 形狀(**圓形**)| **PeoplePicker 自己**(不繼承 Combobox 矩形 tag) |
+| 多人 tag 視覺(**圓形 avatar overlap `-ml-0.5`**) | **PeoplePicker 自己**(不繼承 Combobox 矩形 Tag chip)|
+| 多人 length=1 視覺(降階為 avatar+人名,跟單人視覺一致)| **PeoplePicker 自己**(Combobox 無此特殊)|
+
+#### B. 單人完整 trigger SSOT
+
+| state | trigger 顯示 |
+|---|---|
+| 空、closed | placeholder「請選擇人員」+ 按空間 ellipsis |
+| 選 1 人、closed | avatar + 人名 + 按空間 ellipsis(`PersonDisplay`,`person-display.tsx:131-147`)|
+| open + inline-search、未選 | input cursor + placeholder「請選擇人員」(trigger empty placeholder,**不**用「搜尋…」)|
+| open + inline-search、選 1 人 | input cursor + placeholder = **該人名**(本人名字當搜尋預設值,按空間 ellipsis;`select.tsx:185` `selectedLabel \|\| placeholder` empty-state fallback canonical)|
+| open + panel-search、選 1 人 | avatar + 人名 + ellipsis(搜尋框在 panel 內,trigger 視覺不變)|
+
+#### C. 多人 length=1 trigger SSOT(降階為單人視覺)
+
+| state | trigger 顯示 |
+|---|---|
+| closed | avatar + 人名 + ellipsis(= 單人 closed,共享 `PersonDisplay`)|
+| open + panel-search | avatar + 人名 + ellipsis(panel 內搜尋,trigger 視覺不變)|
+| open + inline-search | avatar + **input cursor**(原本人名位置被輸入區取代;**因 avatar 仍可見,placeholder 永遠空,只剩 cursor** — 對齊 §E 「avatar 存在 → placeholder 空」rule,避免視覺重複造成混亂)|
+
+#### D. 多人 length≥2 trigger SSOT(avatar stack 視覺)
+
+| state | trigger 顯示 |
+|---|---|
+| closed | **圓形 avatar stack overlap `-ml-0.5` + 圓形 +N 溢出 chip**(本來放人名的地方不放人名)|
+| open + inline-search、**未選**(length=0)| input cursor + placeholder「請選擇人員」(trigger empty placeholder,**不**用「搜尋…」)|
+| open + inline-search、**已選**(length≥2)| **avatar stack + 圓形 +N + input cursor 在 +N 的右側**(stack 跟 +N 不動;cursor 接在 +N 後;empty search 不顯 placeholder,純 cursor。對齊 Combobox `trailing` slot placement)|
+| open + panel-search、已選 | avatar stack + 圓形 +N(searchbox 在 panel 內,trigger 視覺不變)|
+
+#### E. 共享 SSOT(單人 ↔ 多人 length=1 必對齊)
+
+| 共享項 | SSOT owner |
+|---|---|
+| Avatar 左 inset 距 trigger.left = 12px 固定(不隨 size/density 漂移)| 本 spec L94 + `people-picker.tsx:316` `!px-3` inject(form context)/ `!px-[var(--table-cell-px)]`(naked variant table cell)|
+| Avatar+人名視覺 | `person-display.tsx:131-147` `PersonDisplay`(共享 renderer)|
+| 人名按空間 ellipsis | `person-display.tsx:144` `truncate flex-1 min-w-0` |
+| Placeholder ellipsis(inline-search active 時)| `field-wrapper.tsx:244` `bareInputStyles` 含 `truncate` |
+| Empty-state inline-search placeholder(未選時 → trigger empty placeholder) | `select.tsx:185` `selectedLabel \|\| placeholder` / `combobox.tsx:554` `items.length === 0 ? placeholder : ''`(2026-05-15 Drift A fix 對齊 PeoplePicker SSOT)|
+
+**Avatar-presence → placeholder 規則(2026-05-15 user verbatim「只要有 avatar 存在,placeholder 都是空的,只會出現 cursor,這樣才不會造成混亂」)**:
+
+| 場景 | avatar 是否可見 | placeholder 行為 |
+|---|---|---|
+| 單人 inline-search、已選、open | ❌(input **取代** avatar/name,avatar 消失)| placeholder = **selectedLabel(該人名,memory aid)** — `select.tsx:185` |
+| 單人 inline-search、未選、open | ❌(從來沒 avatar)| placeholder = **trigger empty placeholder「請選擇人員」** |
+| 多人 inline-search、length≥1、open | ✅(avatar/stack 仍在,input 在 trailing)| **placeholder = '' 純 cursor**(避免跟 avatar 重複)|
+| 多人 inline-search、length=0、open | ❌(empty)| placeholder = **trigger empty placeholder「請選擇人員」** — `combobox.tsx:554`(Drift A fix)|
+
+**規則一句話**:`placeholder = (visible_avatar_exists) ? '' : (selectedLabel ?? triggerEmptyPlaceholder)`。
+
+**搜尋預設模式(2026-05-15 user 拍板)**:多選系列 default `searchIn='menu'`(panel-top search)。`searchIn='trigger'` 為 opt-in。Single mode 永遠 inline-search(Select 慣例)。
+
+#### F. Cell-edit ↔ Field-edit 一致性 invariant
+
+`MultiPersonCell` / `PersonCell`(`cell-registry.tsx:381-391` cell-as-input)+ form context PeoplePicker **包同一個元件**,所以 §B/§C/§D 規則對兩 surface 都成立。差別只在 padding 機制(共 §E)— 兩 surface 都產出 12px inset,**禁分歧**。
+
+**改 PeoplePicker 視覺前必查本表,動 trigger render / placeholder / overflowShape / tagWrapperClassName 前先 cite 對應 row。** Hook `check_peoplepicker_ssot_drift.sh` 機械強制。
+
+**Avatar 左 inset SSOT(2026-05-13 v2 — user 拍 Path a + density-drift root-cause,GitHub people picker idiom)**:single trigger / multi stack 第一個 avatar 距 trigger.left = **12px 固定**(不隨 size / density 漂移)。實作:PeoplePicker form context + 有 tag → `cn(className, '!px-3')` inject 12px override 到 Combobox Field wrapper,**覆蓋** Combobox `tagPadding[size]` density-dependent calc 公式;`tagAreaPaddingLeftPx={undefined}` 不再 +8 magic。Cell context naked variant `!px-[var(--table-cell-px)]` 已是 12px 不 inject。**為何 v1「4+8=12」公式報廢**(per 2026-05-13 codex V2 verdict correction):`tagPadding[size]` 是 `(field-height - icon-size) / 2`,真值表:default sm/md=4px → 4+8=12 ✓;default lg=6px → 14px ✗;comfortable sm/md=6px → 14px ✗;comfortable lg=8px → 16px ✗。**default sm + default md 兩個 size 也 = 12px**(我前 too narrow claim「只 md」 codex 修正);**真正漂的 = default lg + 全 comfortable 共 4 個組合**。整體 stale 結論不變(4 個漂 / 2 個對),故 `!px-3` 固定 12px 是正解。對齊 GitHub picker / Material Autocomplete renderTags / Ant Select tagRender 共享 fixed-inset canonical(不 scale with size)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**判準**：
+- **選人 → PeoplePicker**（不用 Select / Combobox 代替，失去 Avatar 視覺）
+- **非人員單選 → Select**
+- **非人員多選 → Combobox**
+
+---
+
+## PersonValue 型別
+
+```tsx
+type PersonValue = string | { name: string; avatarUrl?: string; description?: string }
+```
+
+- **簡單用 string**：只有名字（fallback 顯示 initials）
+- **完整物件**：包含 avatar URL 和 description（顯示 Avatar + 次要資訊如 role / email）
+
+---
+
+## readonly / disabled
+
+與其他 Field 一致：
+- **readonly**：顯示選中人員（Avatar + Name），無 dropdown trigger、無搜尋
+- **disabled**：灰化整個 field，不可互動
+
+---
+
+## 禁止事項
+
+- ❌ 用 PeoplePicker 選非人員（部門 / 專案 / 類別）——那些用 Select / Combobox
+- ❌ 在 readonly 模式顯示搜尋或 dropdown——readonly 是純展示
+- ❌ 多選情境強制單選（限制 value.length === 1）——改用 Select（如果真的單選）
+- ❌ 把 PeoplePicker 當 Team Member 展示元件用（不選人、只看名單）——用 Avatar.Group 或自訂 list
+- ❌ 不搭配 Avatar 視覺（純文字名字）——失去 PeoplePicker 存在的理由，直接用 Select / Combobox
+
+---
+
+## 為何無 Inspector
+
+PeoplePicker 是 **composite Field Control**(Field shell + Avatar + SelectMenu),關鍵決策維度是 `mode`(single / multi)× `size` × search behavior × value type——已由 `ModeMatrix` / `SizeMatrix` / `ColorMatrix` / `StateBehavior` / `PersonValueType` 五張矩陣完整覆蓋。互動 Inspector 對 composite 元件較弱:「傳 PersonValue 陣列」需要真實資料 fixture 展示,單組合試玩無法呈現——改以 `StateBehavior` 的真實 Assignee picker 場景取代。
+
+對應 anatomy story:保留 `Overview` + 元件特有 `ModeMatrix` / `PersonValueType` + `SizeMatrix` + `ColorMatrix` + `StateBehavior`。
+
+---
+
+## shadcn passthrough 例外說明
+
+PeoplePicker 是 **composite 元件**(Popover + Command + SelectMenu + Avatar 內部組裝),其 API 為完全 declarative(value / onChange / size / mode / options...)。**不套 `forwardRef` / `...props` spread**:
+
+- **沒有單一 DOM root 可 ref**:consumer「對誰 forward」含糊——指 Popover trigger?Command search input?SelectMenu content?任一選擇都會誤導 consumer
+- **`...props` spread 會撒到何處?** composite 元件無 identity DOM,spread 若到 root wrapper 多半無意義(wrapper 只是 flex container);到 trigger 則語義不清
+- **API 邊界明確才是 composite 價值**:PeoplePicker 暴露的是「選人」語意,不是「彈出選單 + 搜尋 + 渲染頭像」的 DOM 細節。若 consumer 需要 DOM-level 控制,該用底層 Popover + Combobox 自組,不該透過 PeoplePicker
+
+`displayName = 'PeoplePicker'` 保留,無 `asChild`(composite 不是 Slot-compat)。
+
+---
+
+## 邊界案例
+
+- **Disabled**:Field SSOT own;trigger / dismiss / inline-search input 全 disable,已選 avatar tag dismiss X 自動隱藏(對齊 Combobox readonly/disabled tag 規則)。token 走 M24 state precedence。
+- **Loading(async people fetch)**:`loading?: boolean` forward 給 SelectMenu(SelectMenu 端「Loading」段 SSOT);dropdown body 替換為 `<Empty icon={<CircularProgress size={48}/>}/>` + `aria-busy`。trigger 不變,user 隨時可開。
+- **Empty(no search results)**:`emptyText` 預設「沒有符合的人員」(本 spec L72 已 codify);無 creatable mode(人員不可建立)。
+- **Empty(no value selected)**:single mode → trigger 顯 placeholder「請選擇人員」;multi mode `value=[]` → trigger 同 placeholder(無 avatar stack 渲);詳「Trigger display SSOT canonical table」B-D 段。
+- **Dark mode / density**:Avatar 12px inset 固定不隨 density 漂移(PeoplePicker own,本 spec L94 + L140 codify);其他走 Field + SelectMenu SSOT。
+
+---
+
+## 相關
+
+- `./person-display.tsx` — PersonValue 的顯示元件（Avatar + Name，readonly / DataTable cell 用）
+- `../Select/select.spec.md` — 非人員單選的對應元件
+- `../Combobox/combobox.spec.md` — 非人員多選的對應元件
+- `../SelectMenu/select-menu.tsx` — PeoplePicker edit mode 的浮層選單（內部消費）
+- `../Avatar/avatar.spec.md` — 選項與已選值的 Avatar 視覺
+- `../NameCard/name-card.spec.md` — 純顯示人員資訊的對應元件（非選擇器）
+- `../Field/field-controls.spec.md` — Field Control 共用規則
+
+## A11y 預設
+
+**ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。
+
+**Keyboard 行為**:
+
+- Tab — focus trigger
+- Enter / Space — 開啟 picker
+- 字母鍵 — type-ahead 搜尋
+- ↑/↓ — 導覽 people
+- Enter — 選擇 / 取消選擇
+
+**Focus**:focus-visible ring 對齊 DS canonical(`outline: 2px solid var(--ring)`);focus management 由元件 own。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `select-menu.spec.md`

package/src/components/Popover/popover.spec.md

@@ -0,0 +1,198 @@
+---
+component: Popover
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - isOverlay
+benchmark:
+  - Radix Popover primitive: github.com/radix-ui/primitives/tree/main/packages/react/popover
+  - MUI Popover: github.com/mui/material-ui/tree/master/packages/mui-material/src/Popover
+  - Polaris Popover: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Popover
+  - Ant Design Popover: github.com/ant-design/ant-design/tree/master/components/popover
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Popover 設計原則
+
+## 定位
+
+Popover 是**點擊觸發的浮層容器**——提供定位、動畫、焦點管理，內容由 consumer 決定。
+
+**實作基礎**：shadcn passthrough——基於 Radix Popover。本 DS 保留 shadcn 原結構 + 橋接 DS token（elevation / radius / border）。
+
+**Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
+
+**視覺對齊 Dialog**：外殼 token 與 Dialog 完全一致（`bg-surface-raised` / `border-border` / `rounded-lg` / `elevation-200`）。差別僅兩點：(1) Popover 是 non-modal 輕量浮層不阻斷背景，(2) **density 永遠鎖 `md`** — Popover 不隨頁面 density 放大（lightweight 浮層保持緊湊）。
+
+**Content size canonical（2026-04-29）**:density lock md → **fields(Input / Select / Checkbox)預設 `size="md"`**(field-height-md 32px,對齊 density)。其餘細節走 SSOT pointer:
+- Chrome corner buttons(close X / refresh / dismiss)→ `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」(sm native + v5 trick)
+- Row inline action(panel list row 內 Eye / drag / suffix toggle)→ `patterns/element-anatomy/inline-action.spec.md`「尺寸對照」table(md = 16+18 hover bg)
+- Footer action button → `action-bar.spec.md`(輕量 chrome,sm canonical)
+
+**觸發距離 canonical**：`sideOffset = 8`（px）—— trigger 到 Popover 邊緣的垂直/水平間距。8px 是世界級浮層 idiom（Notion / Linear / Figma / Stripe 皆約 6-8px）;< 4px 會讓浮層貼死 trigger 失去「另一層」感,> 12px 會拉斷 trigger ↔ content 的視覺關聯。Radix/shadcn 預設 4px 太緊,本 DS 改為 8 對齊 overlay primitive 的呼吸感。Dialog 不適用(居中或 full-screen)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**Viewport 邊距 canonical**:`collisionPadding = 8`(px)——浮層與 viewport 邊緣的最小間距。當 popover 原本要貼近 viewport 邊(trigger 在頁面最右側、或視窗很窄),Radix 會自動推開 8px 讓浮層不貼死邊界。世界級對照:macOS / iOS / Notion / Figma 的 overflow 選單永遠留視覺呼吸距。`sideOffset` 管 trigger↔popover,`collisionPadding` 管 popover↔viewport,兩者互補。Consumer 不需傳 — 預設值是 canonical。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**Align 對齊 canonical(跨浮層 SSOT)**:`align` 必須跟隨 trigger 在容器中的位置,**不是自由選擇**:
+
+| Trigger 在容器 | `align` | 對齊行為 |
+|---------------|---------|----------|
+| **左側 / 左上**(page header left、sidebar filter button) | `"start"` | Popover 與 trigger 左邊緣對齊,向右展開 |
+| **置中**(toolbar 中央、modal 內置中按鈕) | `"center"`(default)| Popover 與 trigger 中心對齊 |
+| **右側 / 右上**(page header right、設定按鈕、overflow menu) | `"end"` | Popover 與 trigger 右邊緣對齊,向左展開 |
+
+**為什麼**:Popover 通常比 trigger 寬。align 錯方向會 (1)溢出容器邊緣 / 被 viewport 裁切、(2)視覺上 popover「沒黏在 trigger 那一側」產生 disconnect,使用者以為兩者無關。世界級對照:Figma / Notion / Linear / Stripe / Material / Ant Design 一律遵循(trigger 靠哪邊、浮層跟著靠哪邊)。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**SSOT 適用範圍(2026-04-20 精緻化)**:本規則是**「結構化浮層」的 canonical** —— Popover / DropdownMenu / Coachmark / SelectMenu 嚴格遵守(這些浮層寬度通常比 trigger 寬、且有結構化內容,錯方向必視覺 disconnect)。
+
+**輕量浮層例外**:Tooltip / HoverCard 不適用此 canonical —— 兩者 predominantly hover 觸發、純展示(不互動或極少互動)、寬度隨內容自適應,Radix 預設 `align="center"` 即可涵蓋絕大多數情境。強行套 trigger-position alignment 反而破壞 Tooltip「貼合指標」的輕量感。這兩個 primitive 走自己的 spec canonical(通常 center + 小 sideOffset)。
+
+**SelectMenu 特例**:SelectMenu 是 input-triggered,width 在 min/max 範圍內自動跟 input 同寬 → `align="start"`(對齊 input 左邊緣)在視覺上與「popover 跟 input 同寬」重疊,consumer 感知不到 alignment 差異。仍採用 canonical 以保 code 一致性,但視覺上是透明的。
+
+其他結構化浮層 spec 若討論 align 應 pointer 指回本節。
+
+**結構化組合（可選）**：PopoverContent 外殼無內距，consumer 可選擇：
+- **單一 body**：包 `<PopoverBody>` 取得 Dialog body 同 padding (`px-loose py-tight`)
+- **含標題**：組合 `<PopoverHeader>` + `<PopoverBody>`（下分隔線由 Header 提供）
+- **含操作按鈕列**：再加 `<PopoverFooter>`（上分隔線由 Footer 提供）
+
+**Dismiss 預設**(與 Dialog 一致):Popover **預設 dismissible** —— 點擊 trigger 外 / 按 Esc / focus 離開 content 樹,三者任一皆關閉。由 Radix 內建 `onPointerDownOutside` / `onEscapeKeyDown` 行為提供,consumer 無需額外 wire。如需強制 modal(必須按 Close 才能關),傳 `modal={true}` 並在 Header 放 Close 按鈕;但這是例外,不是預設——Popover 的本質是「使用者可以忽略、繼續主流程」。
+
+> **跨家族 SSOT pointer**:PopoverHeader 屬 **Padding-based overlay header 家族**;border / padding / dismiss size / withTabs(tabs 進 PopoverHeader 時 border auto-suppress + tabs size sm)的跨家族視覺契約 SSOT 詳 `patterns/header-canonical/header-canonical.spec.md`。本節僅 codify Popover 特有 close X v5 unbounded canonical。
+
+**Close X 按鈕(2026-04-22 v5 unbounded canonical)**:所有 `PopoverHeader` 內建右上 X 按鈕,`<Button data-dismiss iconOnly dismiss size="sm" />` native sm(28 md / 32 lg)。透過 SurfaceHeader 的 v5 CSS rule 自動套負 margin 讓 layout 佔位 = 24(chrome-header-height 幾何)。`hideClose` prop 可讓 composition 元件(如 Coachmark)選擇隱藏。詳 `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」。
+
+**Header / Footer 高度 canonical**:padding-based(繼承 SurfaceHeader / SurfaceFooter),高度 = max(child layout) + 2×tight。unbounded 透過 v5 trick layout 佔位 24 → header 48 / footer 48(若只有 unbounded)或自然長(若有 bounded)。詳 `tokens/uiSize/uiSize.spec.md`「Chrome header 選型 canonical」。
+
+---
+
+## Title typography canonical(non-modal 特化,2026-04-22 v4)
+
+**PopoverTitle 用 `text-body font-medium`(14px),不是 Dialog / Sheet 的 `text-body-lg`(16px)**。這是針對 **non-modal 輕量浮層** 的視覺考量,跟 density 鎖 md 同源的輕量 rationale。
+
+**重量分級(world-class 共通 pattern)**:
+
+| Overlay 類型 | Title typography | Rationale |
+|------------|------------------|-----------|
+| **Modal**(Dialog / Sheet)| `text-body-lg`(16px)| 重量級決策 surface,title 是決策 anchor,需視覺重量 |
+| **Non-modal**(Popover / Coachmark / Tooltip / HoverCard)| `text-body`(14px)| 輕量浮層,可忽略、非阻斷,title 是輔助標籤不搶視覺重心 |
+
+**世界級對照**(7 家 DS 同 split):
+| DS | Modal title | Non-modal popover title |
+|----|-------------|------------------------|
+| Material M3 | Headline(24px large / 16px body 分 variant)| Smaller(usually 14-16px) |
+| Polaris | Modal title 大號 | Popover 較小 |
+| Atlassian | Modal 大 | InlineDialog 小 |
+| Notion | Modal 16px+ | Popover 14px |
+| Linear | Modal 16px | Popover / HoverCard 14px |
+| Figma | Modal 16px | Inline panel / popover 13-14px |
+| GitHub Primer | Dialog 16px | Overlay 14px |
+
+**共通原則**:non-modal overlay 的 title 比 modal 小一級。我方採 16 → 14 分級,在 world-class 範圍內。
+
+**Coachmark 的 PopoverTitle 消費**:Coachmark 的 header 小標籤(如 "新功能介紹" / "Tip 1 of 3")繼承 PopoverTitle 14px。Coachmark **body 內容的主 title**(長敘述型 "建立你的第一個 Workspace")另走 `text-body-lg`(見 `coachmark.tsx:L178`)— 那是 body content 不是 chrome title,分離 concerns。
+
+**禁止**:consumer 自己在 PopoverContent 裡手刻 `<h2 className="text-body-lg">` 當 title(繞 PopoverTitle 的 canonical)。若需要大 title,視為該用 Dialog 而非 Popover(選對元件)。
+
+---
+
+## 何時用
+
+- **點擊觸發的輕量浮層**：filter panel、date picker 展開、設定 mini panel
+- **需要放互動元素的浮層**：按鈕、輸入框、checkbox 群組
+- **非 modal 的補充 UI**：使用者可以忽略並繼續主流程，不阻斷背景互動
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| hover 觸發（非點擊）| `HoverCard` | HoverCard 觸發是 hover，Popover 是點擊 |
+| 純文字提示 | `Tooltip` | Tooltip 更輕量，適合純文字 |
+| 需要阻斷背景的流程 | `Dialog` | Dialog 是 modal，Popover 非 modal |
+| 操作選單（複製 / 刪除）| `DropdownMenu` | DropdownMenu 有 menu 語意 + 鍵盤導覽 |
+| 選值下拉 | `Select` / `Combobox` | 下拉選單用專用元件，不自組 Popover + list |
+
+---
+
+## 與 Dialog 的分界
+
+- **Popover**：non-modal 輕量浮層（filter / settings panel / mini 操作面板）——背景仍可互動
+- **Dialog**：modal 阻斷互動（confirmation / form wizard / 需要完成才能繼續的流程）
+
+**判斷法**：問「使用者可以 ignore 這個浮層、繼續使用主介面嗎？」可以 → Popover；不可以、必須處理才能繼續 → Dialog。
+
+## 與 DropdownMenu 的分界
+
+- **DropdownMenu**：有預設 item 結構（MenuItem list），語意是「從清單中選一個動作」— click 單一 item 即觸發 action,無 save CTA
+- **Popover**：內容自由（任意 React 元素），可放按鈕、輸入框、圖表、form;支援「暫存選中狀態 + 明確 save CTA」
+
+選單類(click 單項即動作,無 save)用 DropdownMenu;自由組合 UI 面板(多欄表單、filter 控制群、「選完按套用」的多選工作流)用 Popover。
+
+### 合法但少見:Popover 內含可選 item 列 + footer save CTA
+
+Popover 可以在 body 放 checkbox / radio 列表 / 可選 chip / 可選 menu-item-like elements,**但必在 footer 有 CTA 按鈕(套用 / 儲存 / 完成)觸發狀態提交**。這個 pattern 跟 DropdownMenu 的差別是:**DropdownMenu 一 click 即觸發動作,Popover 這類是「暫存選擇 → 按 CTA 才 commit」**。典型情境:
+
+- **多選 filter panel**:checkbox 列表 + 底部 `清除 / 套用`(見 `FilterPanel` story)
+- **Bulk edit**:選多個 menu-item-like options + 底部 `儲存變更`
+- **Custom toolbar 設定**:可選 toggle 列 + 底部 `套用偏好`
+
+canonical 判斷:「使用者 click 單項是否立即改變系統狀態?」是 → DropdownMenu;否(要按 footer CTA 才 commit)→ Popover。
+
+---
+
+## 禁止事項
+
+- ❌ **不把 Popover 當 Tooltip**：Tooltip 是 hover 觸發的純文字輔助，Popover 是 click 觸發的互動面板，語意與觸發模型不同
+- ❌ **不用 Popover 做 confirmation dialog**：確認框必須阻斷背景互動,使用者不能忽略——那是 Dialog 的職責
+- ❌ **不在 Popover 內放 nested Popover**：嵌套層級混亂、焦點管理崩壞，複雜互動改用 Dialog 或拆成多步驟
+
+---
+
+## A11y 預設
+
+Radix Popover 自動處理：
+
+- **焦點管理**：開啟時移動焦點進入 content；關閉時 focus return to trigger
+- **Esc 關閉**：按 Esc 自動關閉並返回焦點
+- **Focus trap**：`modal={true}` 時焦點鎖在 content 內；預設 non-modal 下焦點離開 content 樹會自動關閉
+- **ARIA**：trigger 自動 `aria-expanded` / `aria-controls`，content `role="dialog"`
+
+Consumer 無需額外處理 a11y，保留 Radix `data-state` 屬性即可。
+
+---
+
+## 為何無 Inspector
+
+Popover 是**浮層容器 primitive**——關鍵決策是 `side` × `align` × `sideOffset`,以及內部 Header / Body / Footer 結構。`PlacementMatrix` 是完整的 side × align 12-cell 矩陣,比互動 Inspector(切單一 side/align)更能呈現所有定位組合。Header / Body / Footer padding 屬 `overlay-surface` SSOT,已由 `ColorMatrix` 的 token 表 + 該 pattern spec 覆蓋。
+
+Popover 內容完全由 consumer 決定,無自己的 variant/size/disabled 等可試玩 prop——Inspector 對 container 類元件價值低。
+
+對應 anatomy story:保留 `Overview` + 元件特有 `PlacementMatrix`(12-cell side × align 矩陣) + `ColorMatrix` + `SizeMatrix` + `StateBehavior`(open / close / animation)。
+
+---
+
+## 相關
+
+- `../HoverCard/hover-card.spec.md` — hover 觸發的對應浮層
+- `../Tooltip/tooltip.spec.md` — 純文字提示
+- `../Dialog/dialog.spec.md` — 需要阻斷的 modal
+- `../DropdownMenu/dropdown-menu.spec.md` — 有 menu 語意的操作選單
+- `../SelectMenu/select-menu.spec.md` — SelectMenu 消費 Popover 作為浮層容器
+- `../Coachmark/coachmark.spec.md` — Coachmark 為 Popover 的 composition pattern(無 header / 有 media / footer justify-between),共用所有 overlay-surface SSOT
+- Radix Popover primitive — `@radix-ui/react-popover`
+- `../../patterns/overlay-surface/overlay-surface.spec.md` — Header / Body / Footer padding SSOT（Dialog + Popover 共用）
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `command.spec.md`
+- `file-viewer.spec.md`
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `density.spec.md`