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

package/src/patterns/element-anatomy/item-anatomy.spec.md

@@ -1,4 +1,4 @@
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline(M22(d) 顯式撤回;本檔 frontmatter 無 benchmark list,來源 URL 未補)。 -->
 
 # Item Anatomy 設計原則(Family 1 + Family 2 row 結構 SSOT)
 
@@ -47,7 +47,7 @@
 
 | 元件 | 繼承的部分 | 不繼承的部分 |
 |------|----------|-----------|
-| `Tabs`（Trigger） | gap-2 slot 間距、scanning 字體 tier、hover 行為 | 結構是**橫向 inline**（非垂直 row）, 高度系統對標 Button, 無 prefix/content/suffix column | 詳細對標分析見 `components/Tabs/tabs.spec.md`「Tabs 不完全屬於 item-layout」段 |
+| `Tabs`（Trigger） | gap-2 slot 間距、scanning 字體 tier、hover 行為 | 結構是**橫向 inline**（非垂直 row）, 高度系統對標 Button, 無 prefix/content/suffix column;詳細對標分析見 `components/Tabs/tabs.spec.md`「對標對象與故意的偏離」段 |
 
 ---
 
@@ -55,7 +55,9 @@
 
 **用途**：頁面上的閱讀式單列。使用者讀取內容、需要 description 多行、looser density。
 
-**結構**：`[larger icon/avatar 20-24px] [content: label + multi-line description OK] [suffix action/button/counter]`，reading typography（default leading），字體略大於 Family 1。
+**結構**：`[icon/avatar 16-20px(`ICON_SIZE` sm/md=16, lg=20)] [content: label + multi-line description OK] [suffix action/button/counter]`，reading typography（default leading 1.5）。
+
+> **2026-06-15 修**：本行原寫 icon「20-24px」,與 item-anatomy.tsx 的 `ICON_SIZE = {sm:16, md:16, lg:20}` 常數打架（24px 不存在於常數,md 是 16 非 20+）。已對齊**實作真值 ICON_SIZE**。Family 2 與 Family 1 的 icon **px 值相同**（皆走 ICON_SIZE）;兩 family 的差別在 **typography 行高 + density**（reading 1.5 / scanning 1.3）+ description 多行能力,**不在 icon px**。
 
 **消費者**：
 
@@ -121,7 +123,7 @@
 | `[avatar] Title\nSubtitle` / `[icon] Label` | **MenuItem / Family 2** | 語意是「一個實體 / 一筆資料」,title 是 item 識別 |
 | `Email:user@x.com` / `Created: 2026-04-22` | **DescriptionList** | 語意是「同一實體的 N 個屬性」,label 是 key,不是 item 識別 |
 | 一排 `[status dot] Project name [count]` | **MenuItem / Family 2** | 實體列表(每個 project 是獨立 item) |
-| NameCard 裡 profile 的「職稱 / 部門 / 到期日」 | **DescriptionList(horizontal)** | 同一人的多個 metadata 屬性 |
+| ProfileCard 裡 profile 的「職稱 / 部門 / 到期日」 | **DescriptionList(horizontal)** | 同一人的多個 metadata 屬性 |
 
 ### ❌ 禁止(自刻 = 繞過 anatomy canonical)
 
@@ -141,9 +143,9 @@
 
 ```bash
 # 看有沒有繞過 item-anatomy 的手刻 list item
-rg "className=\"flex.*py-[0-9].*hover:bg\" packages/design-system/src src/hooks --type tsx
+rg 'className="flex.*py-[0-9].*hover:bg' packages/design-system/src -g '*.tsx'
 # 看有沒有繞過 DescriptionList 的手刻 key-value grid
-rg "grid-cols-\[[0-9]+px_1fr\]" packages/design-system/src src/hooks --type tsx
+rg 'grid-cols-\[[0-9]+px_1fr\]' packages/design-system/src -g '*.tsx'
 ```
 
 非空 = drift,要改用 primitive。
@@ -152,7 +154,7 @@ rg "grid-cols-\[[0-9]+px_1fr\]" packages/design-system/src src/hooks --type tsx
 
 ## 任何未來的 row 元件
 
-必須先判斷屬於 Family 1 或 Family 2，然後照對應章節的規則做。**不要自己發明新規格**——發明前必先讀本 spec 全文 + CLAUDE.md「4-Family Model」。
+必須先判斷屬於 Family 1 或 Family 2，然後照對應章節的規則做。**不要自己發明新規格**——發明前必先讀本 spec 全文 + `element-anatomy.spec.md`「4 個可繼承的 Layout Family」。
 
 ---
 
@@ -161,16 +163,27 @@ rg "grid-cols-\[[0-9]+px_1fr\]" packages/design-system/src src/hooks --type tsx
 ### Row primitives 必須共用的規格
 
 - **水平 padding**: `px-[var(--layout-space-loose)]`(sidebar context) / `px-3`(menu context),由 consumer 脈絡決定
-- **垂直 padding**: `py-[calc((var(--field-height-*)-1lh)/2)]` 的 item-layout 公式
+- **垂直 padding**: `py-[calc((var(--field-height-N) N∈{sm,md,lg}-1lh)/2)]` 的 item-layout 公式
 - **字重**: `font-medium`(500),**不隨 selected 變**
 - **預設文字色**: `text-fg-secondary`(neutral-8);icon 透過 currentColor 繼承
 - **Hover**: `bg-neutral-hover` + `text-foreground`
-- **Active / selected**: `bg-neutral-selected` + `text-foreground`(不加字重,避免跳動)
+- **Active / selected**: `bg-neutral-selected` + `text-foreground`；字重維持不變，避免 label metrics reflow
+- **選中 × 互動疊加（2026-08-11 user 拍板；本格是全家族唯一 owner，消費者禁自行發明）**：
+
+  | 疊加 | 底色 | 理由 |
+  |---|---|---|
+  | 選中列 × 滑鼠 hover | `bg-neutral-selected`（**釘住不變**） | hover 回饋 = 誠實回答「再點會發生什麼」；選中列再點無效果，且滑鼠使用者自有游標不需底色指位。對齊 Polaris Navigation / Carbon side-nav（兩家皆明文釘住） |
+  | 選中列 × 鍵盤焦點／反白 | `bg-neutral-selected-focus`（深一階） | 鍵盤使用者螢幕上沒有游標，深一階就是游標（WCAG 2.4.7）。虛擬焦點選單（cmdk／Radix 反白）以 `not-hover:` 分流滑鼠；真焦點元件用 `focus-visible:` |
+  | 選中列 × 按壓 | 列元件不設按壓底色；`--neutral-selected-active` 為**按壓專屬**（唯一消費者 Button toggle） | active = 瞬時按壓（2026-04-10 誕生教義）。2026-07-05 D4 借 `-active` 裝反白 + 訊號漏到滑鼠，2026-08-11 糾正歸位 |
+
+  消費者：SelectMenu／DropdownMenu（含 RadioItem）／SidebarMenuButton／TreeItem(single)／TimePicker 欄項／MenuItem／FileViewer 縮放選單。歷史偏移錨：TreeItem hover 反被洗淺、sidebar 靠編譯順序運氣不變、選單滑鼠 hover 搭鍵盤規則便車深化——同題四種即興，根因即本格缺席。
 - **無 rounded**: full-width fill
 - **無 gap 在 items 之間**: items 緊貼(SidebarMenu / TreeView / DropdownMenuGroup 容器不設 flex gap)
 - **Size variants**: sm / md / lg 跟 `--field-height-*` family 一致
 - **Icon 尺寸控制**: 用 `ICON_SIZE` 常數 `{ sm: 16, md: 16, lg: 20 }` 對齊 `--field-height-*`,並**透過 `size` prop 直接傳給 Lucide icon**(不要用 CSS selector 如 `[&>svg]:size-4`——當 icon 被包在 `h-[1lh]` wrapper 裡時,`>` 直接子選擇器失效,Lucide 會 fallback 到 24px 預設)。MenuItem / TreeView / SidebarMenuButton 都這樣做,新元件照抄
 - **Row header(分組標題)**: 用 `MenuItem header={true}` 模式,`font-medium text-fg-muted pointer-events-none` + 與 items **完全相同**的 row geometry(同 px / 同 py / 同 text size)
+- **Row header 計數 suffix**(2026-07-08 WM 戰役 codify,user 拍板):分組標題帶總數時 = **標題靠左、純數字靠右**(space-between,即 suffix slot 位置 `ml-auto`)。數字規格走既有 suffix value canonical(下方 metadata 表「fg-muted、字體大小與 label 相同」)+ `font-normal` + `tabular-nums`;count = 0 不渲染。**禁**把 count 串進 label 字串相鄰放(「Unstarted (2)」— 6 家世界級無一家括號串接:Primer CounterLabel / Ant Badge / Atlassian Badge 皆結構化 slot);字串層(aria-label / 純文字匯出)可用括號形。互動導覽元素(tab / segmented / sidebar item)的計數仍走 `badge` slot(tabs.spec.md「badge 傳達計數」),不適用本條。
+- **可收合 section header 組合 canonical**(2026-07-08 R3-7 拍板 + 2026-07-10 codify 進 DS;**組合非元件** — SectionHeader 留產品客製,但 layout 全消費本 canonical):(1) chevron = **title 後的 suffix inline action**(非 prefix、非獨立按鈕群);(2) 可選 description 與 title 間距用 `--item-gap-label-desc-*` token;(3) endSlot(操作鈕)只有 title 一行時垂直置中;(4) 同構標題列 ≥ 2 份必抽共用元件(WM `SectionHeader.tsx` 錨例 — Description / Attachments / Child work items 三份同構收斂)。手刻簽名(Chevron + justify-between + 可點且無共用元件)由 consumer 防線攔(escape `@section-header-ok:`)。
 
 ### Prefix 垂直對齊:`items-start` + `h-[1lh]` wrapper(**永遠這樣**,不要做例外)
 
@@ -196,9 +209,18 @@ rg "grid-cols-\[[0-9]+px_1fr\]" packages/design-system/src src/hooks --type tsx
 
 **asChild 的 consumer 也必須遵守**:用 asChild 讓 SidebarMenuButton / TreeItem 接受自訂 children(例如塞 Avatar 而非 LucideIcon)時,consumer 必須**自己**把 prefix 包進 `h-[1lh] shrink-0 flex items-center` 容器,不能省略。
 
+### 單行截斷 → tooltip(截斷才顯;2026-07-28)
+
+Row label / description 的**單行截斷**(`truncate`,或 `line-clamp-1` 單行 clamp)必配「僅實際截斷時顯示」的 tooltip 補全——owner = `components/Tooltip/tooltip.spec.md:32`,引擎 SSOT = `patterns/element-anatomy/truncated-text.spec.md`(`useTruncated` + 永遠 wrap、`open` 控制)。`<ItemLabel>` 與 `<ItemContent>` 已內建(量測含 MenuItem 的 `line-clamp-1` className escape),Sidebar / DropdownMenu / SelectMenu / FileItem / DataTable 欄位面板等 row consumer 免自接;手刻 label span 的 consumer 要自己消費 `useTruncated`。
+
+- **Hover-only**:trigger = label/description span 本身,不可聚焦、**不加 `tabIndex`**——Family 1 menu row 的 roving focus 在宿主 row 上,label 加 tab stop 會破壞 APG menu 鍵盤導航。先例:Tag 帶內建截斷 tooltip 渲染於 SelectMenu option 內(`select.tsx` renderLabel → `tag.tsx` open-controlled),menu 內無任何抑制(Tag 的 tooltip 抑制只存在於 closed-trigger 顯示 `pointer-events-none`,非 menu context)。鍵盤/SR 無損失:row 的 accessible name 本就含完整文字。
+- **多行 clamp(≥2 行)排除**:`truncated-text.spec.md`「何時不用」(a) 明文排除多行;`descriptionClamp >= 2` / `descMaxLines >= 2` 不顯 tooltip(DS 尚無多行截斷↔補全 canonical,owner 決策前維持排除)——由「可視高度 ≈ 1 行」量測 gate 機械保證,非 prop 判斷(MenuItem clamp 走 className escape,量 DOM 才能全蓋)。
+
 ### Card header 大 prefix 對齊（avatar > text block）
 
-Row primitive 的 24px 閾值規則適用於**列表行**（prefix 跟 text block 接近等高）。當 prefix 遠大於 text block 時（如 64px profile avatar 搭配 1-2 行文字），改用 **card header 模式**：
+Row primitive 的 24px 閾值規則適用於**列表行**（prefix 跟 text block 接近等高）。當 prefix 遠大於 text block 時（如 64px profile avatar 搭配 1-2 行文字），改用 **card header 模式**。
+
+**為什麼置中**：text block 遠矮於 prefix 時，若沿用列表行的 top-align（`h-[1lh]` 對第一行），文字會頂在 avatar 上緣、下方大片留白，視覺重心偏上失衡；垂直置中讓 text 與大 avatar 形成均衡的 identity pair。實作：
 
 ```tsx
 <div className="flex items-start gap-3">
@@ -217,7 +239,7 @@ Row primitive 的 24px 閾值規則適用於**列表行**（prefix 跟 text bloc
 | 短文字（< prefix 高度） | 文字垂直置中於 prefix 高度 |
 | 長文字（> prefix 高度） | 文字自然撐高，`items-start` 讓 prefix 頂部對齊 |
 
-適用場景：NameCard profile header、FileItem rich、未來的 profile page header。
+適用場景：ProfileCard profile header、FileItem rich、未來的 profile page header。
 不適用：row primitives（MenuItem / TreeItem / Sidebar）——那些走 24px 閾值。
 
 ---
@@ -241,6 +263,8 @@ Row 集合是**內容(content)**,不是區段(region)。加 py 到 row 集合會
 
 **曾經發生的 bug**:TreeView 原本硬寫 `py-2`,放進 `SidebarGroup`(也有 `py-2`)導致 label 和 first tree item 之間多出 8px 無法解釋的 gap;後來改成「只有 menu context 加 py-2」,結果 story 的 bordered wrapper 不屬於 menu context,items 貼邊。最終解法:TreeView root 一律不加 py,所有外層容器自己負責。
 
+**同源 invariant(不只 row 集合)**:「一軸單一 spacing owner」也適用元件的**單一 margin**跨 composition boundary。2026-07-01:`TabsContent` 內建 `mt-[var(--layout-space-tight)]`(tab bar 下方間距),`tabsSlot` 模式把 tab bar 抬進 chrome header 後 TabsContent 留在 `DialogBody`(自帶 `pt-tight`)內 → header→content gap 兩個 owner 疊加 = 雙重 tight(「專案名稱」上方 md 24 / lg 32)。解法同上:chrome body 已擁有 gap,TabsContent 加 `mt-0` 轉移 ownership。詳 `components/Tabs/tabs.spec.md`「出現在 Dialog」段 + hook `check_tabs_content_chrome_body_double_gap.sh`。
+
 ### 實作規則
 
 - 寫 row 集合元件(新 tree / menu / list)時,**root div 不加 py**
@@ -324,7 +348,7 @@ Consumer 不需手動插 Separator——把同類 items 包進 Group,自動分
 
 **為什麼 state 不獨立列規則**:state 視覺(hover / focus / active / selected)跟隨 permanent layer 分類,不獨立觸發。瞬時 state(hover/focus/active)單一 item 啟用不會創造相鄰衝突;selected 的連續 bg 在 permanent flush / transparent item 上是 **multi-select feature**(Finder / Gmail / Notion idiom),在 permanent standalone card 上依然必 gap(card identity 保留)。
 
-### 世界級 benchmark(2026-04-22 掃 6 家)
+### 世界級 benchmark(2026-04-22 掃 6 家) <!-- @benchmark-unverified -->
 
 | DS | menu item | file/card list | table row | settings row |
 |----|-----------|---------------|-----------|-------------|
@@ -363,6 +387,12 @@ Consumer 不需手動插 Separator——把同類 items 包進 Group,自動分
 - `file-upload.stories.tsx` rich list(standalone card)→ 改 `gap-2` + 移除 `border overflow-hidden` 外框
 - `file-item.stories.tsx` Rich / HoverSwap rich block / Clickable:同上
 
+### 邊界案例
+
+- **多行 item(文字換行)**:不改變分類 — gap 判定只看永久視覺層,與 item 高度 / 行數無關
+- **Selected 連續多 item**:見上「為什麼 state 不獨立列規則」— flush / transparent 的連續 selected bg 是 multi-select feature;standalone card 依然必 gap
+- **Dark mode**:分隔 affordance(`border-divider` / bg token)走 semantic token 自動 adapt,分類與 gap 判定不變
+
 ### 跟 Group auto-separation 的關係
 
 本規則處理**單一 group 內 item 之間**;「Group auto-separation」處理**相鄰 group 之間**(自帶 16px + border 分隔)。
@@ -386,7 +416,7 @@ Consumer 不需手動插 Separator——把同類 items 包進 Group,自動分
 | **control** | Selection 機制(Checkbox / RadioGroupItem) | 只有 SelectionItem 有 | **永遠 inline**(`h-[1lh]`) |
 | **prefix** | 視覺輔助(icon / avatar / thumbnail) | 可選,在所有 item 元件 | 24px 閾值規則 |
 | **content** | label + 可選 description | 永遠存在 | 佔滿剩餘空間,`flex-1 min-w-0` |
-| **suffix** | label 的 metadata(tag、chevron、time、count) | 可選,在所有 item 元件 | **24px 閾值規則(跟 prefix 同公式但獨立)** |
+| **suffix** | label 的 metadata(tag、chevron、time、count) | 可選,在所有 item 元件 | **永遠 `h-[1lh]` inline 對齊第一行 label(跟 prefix 解耦,見「24px 閾值對齊規則」suffix 段)** |
 
 **suffix 可以塞什麼**(支援 Switch 同時遵守 24px 閾值):
 
@@ -399,7 +429,7 @@ Consumer 不需手動插 Separator——把同類 items 包進 Group,自動分
 
 ### 互動 control 在 suffix(Switch / Checkbox / Select)
 
-Menu item / dropdown item 的 suffix 是**可以**塞 Switch / Checkbox / Select 的——世界級 dropdown menu(macOS / Windows / VS Code 的 View menu、Notion 的 page options)普遍用 menu item + trailing toggle/checkmark 呈現「此項 on/off」。**條件**:必須遵守 item-anatomy 的對齊 + 點擊語義規則。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Menu item / dropdown item 的 suffix 是**可以**塞 Switch / Checkbox / Select 的——世界級 dropdown menu(macOS / Windows / VS Code 的 View menu、Notion 的 page options)普遍用 menu item + trailing toggle/checkmark 呈現「此項 on/off」。**條件**:必須遵守 item-anatomy 的對齊 + 點擊語義規則。 <!-- @benchmark-unverified -->
 
 **視覺對齊**(跟 `Tag` / `Chevron` 共用規則):
 
@@ -414,21 +444,26 @@ MenuItem 承載 Switch 時,**整列 row 的 click = toggle 這個 control**(不
 
 ```tsx
 // ✅ Canonical:row click 與 suffix Switch 同步 toggle(row 可點擊、Switch 視覺反映狀態)
-<DropdownMenuItem
-  suffix={<Switch checked={dark} tabIndex={-1} aria-hidden />}
+// (DropdownMenuItem 無任意 suffix slot——trailing 互動 control 用 MenuItem endContent)
+// row = 唯一 ARIA owner:role="menuitemcheckbox" + aria-checked 讓 AT 感知 on/off
+//(Switch aria-hidden 後,沒有這兩個屬性 toggle 狀態對 SR 完全隱形)
+<MenuItem
+  role="menuitemcheckbox"
+  aria-checked={dark}
+  endContent={<Switch checked={dark} tabIndex={-1} aria-hidden />}
   onClick={() => setDark(!dark)}
 >
   Dark mode
-</DropdownMenuItem>
+</MenuItem>
 
 // ❌ 錯:row 跟 Switch 各自獨立,兩個不同 action
-<DropdownMenuItem onClick={navigate('/settings')}>
+<MenuItem onClick={() => navigate('/settings')}>
   Dark mode
   <Switch checked={dark} onCheckedChange={setDark} />  {/* Switch 有自己的 click,搶 row click */}
-</DropdownMenuItem>
+</MenuItem>
 ```
 
-**Switch 實作細節**:放 suffix 時 Switch 應 `tabIndex={-1}` + `aria-hidden`(或去掉自己的 click handler),讓 **row 成為唯一互動靶子**、Switch 純視覺反映狀態。Radix `DropdownMenuCheckboxItem` 的 Checkbox 就是這模式(checkmark 是視覺,整列是 trigger)。Switch 類比採用同樣規則。
+**Switch 實作細節**:放 suffix 時 Switch 應 `tabIndex={-1}` + `aria-hidden`(或去掉自己的 click handler),讓 **row 成為唯一互動靶子**、Switch 純視覺反映狀態。**同時 row 必須自己宣告可感知的 checked state**——`role="menuitemcheckbox"`(或 `"switch"`)+ `aria-checked`;Switch 被 aria-hidden 後,漏宣告 = toggle 狀態對 screen reader 完全隱形。Radix `DropdownMenuCheckboxItem` 就是這模式(checkmark 純視覺,整列 row 帶 role=menuitemcheckbox + aria-checked)。Switch 類比採用同樣規則。
 
 **何時用 suffix Switch vs Field horizontal**:
 
@@ -439,7 +474,7 @@ MenuItem 承載 Switch 時,**整列 row 的 click = toggle 這個 control**(不
 
 兩者**結構一致**(label 左 / toggle 右齊),差別只在**容器層級**(menu item = overlay row / Field horizontal = page row)。
 
-**世界級對照**:macOS View menu「Show toolbar」+ ✓ / Figma View menu「Show layout grids」+ toggle / VS Code View menu「Toggle sidebar」+ ✓——都是 menu item + trailing toggle/check 的 canonical 應用。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**世界級對照**:macOS View menu「Show toolbar」+ ✓ / Figma View menu「Show layout grids」+ toggle / VS Code View menu「Toggle sidebar」+ ✓——都是 menu item + trailing toggle/check 的 canonical 應用。 <!-- @benchmark-unverified -->
 
 **外層**:`flex items-start`——多行時 control / prefix / suffix 的 Y 不隨文字下移。
 
@@ -457,18 +492,16 @@ MenuItem 承載 Switch 時,**整列 row 的 click = toggle 這個 control**(不
 
 ---
 
+## 24px 閾值對齊規則(Prefix)與 Suffix inline 對齊
 
-## 24px 閾值對齊規則(Prefix 與 Suffix 共用同一條公式)
-
+**核心原則**:Prefix 的對齊容器高度由**自己內容物的大小**決定(24px 閾值公式);**Suffix 一律 `h-[1lh]` inline 對齊第一行 label**(實作 SSOT:`ItemSuffix` primitive 與 MenuItem suffix slot 皆固定 `h-[1lh]`,見 `menu-item.spec.md`「Suffix 對齊(實作限制)」)。兩 slot 各自獨立,不互相同步。
 
-**核心原則**:每個 slot 的對齊容器高度由**自己內容物的大小**決定。Prefix 和 suffix 用的是**完全一樣**的公式,只是各自獨立判斷,不互相同步。
-
-### 公式
+### 公式(prefix slot)
 
 | 內容物高度 | 對齊容器 | 對齊目標 |
 |---|---|---|
 | ≤ 24px | `h-[1lh]` | 第一行 label 的垂直中心 |
-| > 24px(+ 有 description) | `h-[calc(1lh + 2px + desc_1lh)]` | label + gap + description 文字塊的垂直中心 |
+| > 24px(+ 有 description) | `h-[calc(1lh + var(--item-gap-label-desc-<mode>[-lg]) + desc-font-size*1.3)]` | label + gap + description 文字塊的垂直中心 |
 | > 24px(無 description) | `h-[1lh]` | 強制 inline(沒有文字塊可對齊) |
 
 ### 為什麼 prefix 和 suffix 各自獨立(不互相同步)
@@ -484,7 +517,7 @@ MenuItem 承載 Switch 時,**整列 row 的 click = toggle 這個 control**(不
 
 **2. 業界 convention 全部如此**
 
-Apple Mail / Gmail / iOS Settings / Material 3 / Atlassian DSP / Polaris ResourceItem——**全部**是「prefix 跟 suffix 各自獨立對齊」。沒有任何一個把小 suffix 強迫對齊到大 avatar 中心。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Apple Mail / Gmail / iOS Settings / Material 3 / Atlassian DSP / Polaris ResourceItem——**全部**是「prefix 跟 suffix 各自獨立對齊」。沒有任何一個把小 suffix 強迫對齊到大 avatar 中心。 <!-- @benchmark-unverified -->
 
 | 系統 | Prefix(大 avatar) | Suffix(小元素) |
 |---|---|---|
@@ -497,22 +530,20 @@ Apple Mail / Gmail / iOS Settings / Material 3 / Atlassian DSP / Polaris Resourc
 
 把小 suffix 強迫對齊大 avatar 中心,小 suffix 會「下沉」到 description 行,**視覺上跟 label 失聯**。對齊 label 第一行則讓 suffix 跟它修飾的對象在同一條基準線上,視覺重量自然分配。
 
-### 大塊 suffix 的對待方式(symmetric 規則)
+### 大塊 suffix(> 24px)不支援 block 對齊(2026-06-11 收斂對齊實作)
 
-`suffix > 24px` 的場景雖然罕見,但**完全套用同一條公式**——當 suffix 是 thumbnail、stacked badge 等大塊內容時,自己的對齊容器走 block calc,對齊文字塊中心。
+`suffix > 24px`(thumbnail / stacked badge)在 DS 內**零實作、不支援 block 對齊**:`ItemSuffix` primitive 與 MenuItem suffix slot 皆固定 `h-[1lh]` inline(SSOT:`item-anatomy.tsx` ItemSuffix、`menu-item.spec.md`「Suffix 對齊(實作限制)」),本 folder anatomy story 對齊表亦明文「Suffix 所有情況 = 一行文字高度」。世界級同向:上表 Material 3 List trailing icon top-aligned(對齊第一行,非文字塊中心)。
 
 | 場景 | Prefix | Suffix | 結果 |
 |---|---|---|---|
-| 標準選單(MenuItem 大宗) | icon 16px / avatar 24px | Tag / Chevron(≤24px) | 兩邊都 inline |
+| 標準選單(MenuItem 大宗) | icon 16px / avatar 24px | Tag / Chevron(≤24px) | Prefix inline,suffix inline |
 | 用戶選單(avatar + name + role) | avatar 32px(block) | Chevron(≤24px) | Prefix block,suffix inline ← **各自獨立** |
-| 帶縮圖列表(thumbnail + title + 縮圖) | icon 16px(inline) | thumbnail 40px(block) | Prefix inline,suffix block ← **各自獨立** |
-| 雙視覺重的卡片 | avatar 40px(block) | thumbnail 40px(block) | 兩邊都 block |
 
-**沒有「prefix 跟 suffix 必須同步」的情況。** 每個 slot 反映自己內容物的視覺重量,各自走公式。
+**沒有「prefix 跟 suffix 必須同步」的情況。** 未來若需 thumbnail 級大塊 suffix,屬 API 擴充——先回本 spec 補 canonical 再動 primitive。
 
 ### Avatar 尺寸選擇
 
-**用於 prefix slot**。Avatar 尺寸是 **consumer 依視覺重量意圖決定**的——有兩組預設可選,對齊模式跟著 size 走,**不跟著 description 的有無走**。
+**用於 prefix slot**。Avatar 尺寸是 **consumer 依視覺重量意圖決定**的——有兩組預設可選,對齊模式跟著 size 走,**不跟著 description 的有無走**(scope:裸 `<ItemAvatar>` 組合;經 `MenuItem avatar`(AvatarData)高階 API 時由 MenuItem 自動依 description 有無選 inline/block 尺寸——AvatarData 無 size 欄位,見 `menu-item.spec.md`「startIcon vs avatar」)。
 
 **兩組預設尺寸**(依 row size):
 
@@ -530,9 +561,9 @@ Apple Mail / Gmail / iOS Settings / Material 3 / Atlassian DSP / Polaris Resourc
 | > 24 | 無 | `h-[1lh]` inline | 大 avatar 但無 desc,仍對齊第一行(block 沒意義) |
 | > 24 | 有 | `h-[block calc]` block | 大 avatar 視覺重,平衡 label + desc 整個文字塊 |
 
-**關鍵**:consumer 可以自由選擇「小 avatar + description」——那是完全合法的組合,此時 avatar inline 對齊第一行 label,description 從第二行自然往下。沒有「有 desc 就必須用 block 尺寸」的規則。
+**關鍵**:consumer 可以自由選擇「小 avatar + description」——那是完全合法的組合,此時 avatar inline 對齊第一行 label,description 從第二行自然往下。沒有「有 desc 就必須用 block 尺寸」的規則。此自由度屬裸 `<ItemAvatar>` 組合;MenuItem 的 AvatarData API 不暴露此選擇(自動推導,見上 scope 註)。
 
-**程式化規則**(scope:**row context only** — Sidebar / SelectMenu / TreeView / Combobox / Menu 等 row primitive 子樹內):consumer **必須**用 `<ItemAvatar>` / `<ItemIcon>` helper 元件,**禁止** `import { AVATAR_SIZE }` 手動查表,更**禁止**硬寫 `<Avatar size={N} />`。
+**Helper 程式化封裝 + review 防線**(scope:**row context only** — Sidebar / SelectMenu / TreeView / Combobox / Menu 等 row primitive 子樹內):consumer **必須**用 `<ItemAvatar>` / `<ItemIcon>` helper 元件(helper 自動查 `RowSizeContext` 對表 = 程式化封裝),**禁止** `import { AVATAR_SIZE }` 手動查表,更**禁止**硬寫 `<Avatar size={N} />`(兩條禁令現無機械 hook 閘,靠 review 防線把關)。
 
 **Scope 例外:Chrome header 不是 row context**(per `header-canonical.spec.md` 4.5):chrome header 有自己的 spec-level avatar canonical = 24px(density-fixed / row-size-fixed),用 raw `<Avatar size={24}>` + `--chrome-header-avatar-size` CSS token。Chrome header avatar 不參與 row anatomy 對齊機制(無 sm/md/lg row size lookup 需求)。詳 `header-canonical.spec.md` 4.5「Chrome header avatar SSOT」段。
 
@@ -571,7 +602,7 @@ Canonical 對齊模式判斷:`MenuItem` 的 `isBlockAlign = avatarPx > 24 && !!d
 
 ### Token: `--item-icon-size` / `--item-avatar-size`(2026-05-22 codify)
 
-**Local token family(per `--item-*` prefix 既有 family,e.g., `--item-prefix-slot` / `--item-gap-label-desc`)**。
+**Local token family(per `--item-*` prefix 既有 family,e.g., `--item-prefix-slot` / `--item-gap-label-desc-<mode>[-lg]`)**。
 
 由 row primitive(目前 SidebarProvider)透過 inline style 注入,**JS const → CSS var mirror**:
 
@@ -630,13 +661,13 @@ Label x 位置受 prefix 尺寸影響(icon 16 vs avatar 24,差 8px)。**對齊
 
 | 情境 | 對齊要求 | 理由 |
 |---|---|---|
-| **同 group 多 items** | Prefix 類型必須一致(全 icon 或全 avatar) | 多個 label 需要齊左掃視,prefix 類型混用會讓 label x 跳動,破壞 row rhythm |
+| **同 group 多 items** | Prefix 類型必須一致(全 icon 或全 avatar) | 多個 label 需要共享 scan alignment；混用 prefix 類型會產生不一致的 label 起點 |
 | **同 group 單一 item** | **無對齊負擔**,用 prefix 自然尺寸 | 沒有相鄰 label 可參照,縮小 prefix 只是為了對齊一個不存在的東西 |
 | **跨 group** | **永不強求對齊** | 不同 group 的語意本來就不同(主導覽 icon / user identity avatar / thumbnail list),各自反映視覺重量 |
 
 **範例**:Sidebar footer 只有一個 user row(Alan Chen)→ 用 inline avatar 24px 的自然預設,不需要縮成 16px 去對齊上方 main nav 的 icon。Main nav 和 footer 是不同 group,本來就該各自獨立。
 
-**業界 convention**:Apple HIG list section、Material 3 list、Atlassian DSP 全部採用「section-scoped consistency」——同一 section 內 leading element 類型一致,跨 section 變化是正常的。沒有任何世界級系統要求整個 sidebar / menu 所有 prefix 強迫同尺寸。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**業界 convention**:Apple HIG list section、Material 3 list、Atlassian DSP 全部採用「section-scoped consistency」——同一 section 內 leading element 類型一致,跨 section 變化是正常的。沒有任何世界級系統要求整個 sidebar / menu 所有 prefix 強迫同尺寸。 <!-- @benchmark-unverified -->
 
 ❌ **錯誤示範**:為了讓 footer avatar 跟 main nav icon 齊左,把 avatar 從 24 改成 16——這是用錯誤方向修了一個根本不存在的問題,且違反 Avatar 尺寸公式。
 
@@ -649,7 +680,7 @@ Label x 位置受 prefix 尺寸影響(icon 16 vs avatar 24,差 8px)。**對齊
 | School | 代表 | 行為 | 我們的預設? |
 |---|---|---|---|
 | A | Slack / VS Code Explorer / Discord | Per-section 獨立 prefix 寬度 | **✅ 預設** |
-| B | Notion / Linear / Atlassian Confluence | 全域對齊 | 🟡 Opt-in via `uniformPrefix` | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| B | Notion / Linear / Atlassian Confluence | 全域對齊 | 🟡 Opt-in via `uniformPrefix` | <!-- @benchmark-unverified -->
 
 兩派都是世界級慣例,沒有絕對對錯。**選 A 作為預設的理由**:
 
@@ -663,27 +694,19 @@ Label x 位置受 prefix 尺寸影響(icon 16 vs avatar 24,差 8px)。**對齊
 
 - `<ItemIcon>` 渲染的 `<ItemPrefix>` 自動帶 `data-prefix-type="icon"`
 - `<ItemAvatar>` 渲染的 `<ItemPrefix>` 自動帶 `data-prefix-type="avatar"`
-- Row-primitive 頂層容器(`SidebarProvider` 的 wrapper div)在 inline style 預設一個 `--mixed-prefix-slot` 候選值(= `AVATAR_SIZE.inline[size]`,20/24/24 @ sm/md/lg)
+- Row-primitive 頂層容器(`SidebarProvider` 的 wrapper div)**只在 `uniformPrefix={true}`(opt-in,預設 `false`)時**於 inline style 注入 `--mixed-prefix-slot` 候選值(= `AVATAR_SIZE.inline[size]`,20/24/24 @ sm/md/lg;`sidebar.tsx` wrapperStyle 三元式,不 opt-in 完全不注入)
 - 同一個 wrapper 用 Tailwind variant `has-[[data-prefix-type=icon]]:has-[[data-prefix-type=avatar]]:[--item-prefix-slot:var(--mixed-prefix-slot)]` 條件化把候選值賦給 `--item-prefix-slot`
 - `<ItemPrefix>` 讀取 `--item-prefix-slot`(預設 `auto`,有值則套槽 + center),自動套用
 
 **單一類型時**:沒有任何一個後代有 `data-prefix-type=avatar`(或反過來),`:has()` 不命中,`--item-prefix-slot` 維持 `auto`,prefix 縮到自然寬度。**完全沒有 ghost spacing**。
 
-### Per-row-primitive override(罕見 escape hatch)
-
-`SidebarMenu` 的 `uniformPrefix` prop:
+### Per-row-primitive override(不提供,YAGNI)
 
-| 值 | 行為 |
-|---|---|
-| 不傳(預設) | 繼承 SidebarProvider 的全域 auto |
-| `true` | 強制這個 menu 套槽,即使單一類型 |
-| `false` | 強制關閉這個 menu 的對齊,即使全域偵測到混用 |
-
-`uniformPrefix={false}` 用法極罕見——為「我刻意要這個 menu 跟其他 menu 視覺上不同步」的場景保留。
+`uniformPrefix` 只存在於 `<SidebarProvider>`(全域 opt-in,預設 `false`);`SidebarMenu` **沒有** per-menu 覆寫 prop——曾設計過三層級組合,但零真實 caller,依 YAGNI 撤除(見 `sidebar.tsx` SidebarMenu 註解 + `sidebar.spec.md`「Sidebar 全域 prefix 對齊」段)。未來若出現「全域對齊但單一 menu 不對齊」的具體 use case,再由該 use case 推導正確 API,不預先猜想。
 
 ### 其他 row primitive 怎麼接
 
-要對齊 Notion 模式,在 row primitive 的頂層 wrapper(例如 `<TreeView>` 的 root)加: <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+要對齊 Notion 模式,在 row primitive 的頂層 wrapper(例如 `<TreeView>` 的 root)加: <!-- @benchmark-unverified -->
 
 ```tsx
 const slotStyle = getUniformPrefixSlotStyle(size)
@@ -702,12 +725,12 @@ const slotStyle = getUniformPrefixSlotStyle(size)
 - ❌ 拿 escape hatch `uniformPrefix={false}` 配合 mixed prefix 沒有設計理由——這違反使用者視覺直覺,只在「刻意製造視覺斷層」時才該用
 - ❌ 在 row primitive 的某個中層元件再做一次 `:has()` 偵測——應該由頂層容器一次處理,中層不該重複 logic
 
-
-
 ## SelectionItem:Control 跟 Prefix 同高度(不歪斜)
 
 `SelectionItem` 永遠有 **control** slot(checkbox / radio)。當 prefix(icon / avatar)也存在時,**兩者必須在同一條 baseline**——否則視覺歪斜。
 
+> **何時用 SelectionItem(vs 裸 RadioGroup / Checkbox group)**:SSOT → `components/SelectionControl/selection-item.spec.md`「何時用」;本節只 own control + prefix 對齊規則。
+
 ### 規則:control 跟著 prefix 的對齊走
 
 | prefix 模式 | Control 對齊 | Prefix 對齊 | 結果 |
@@ -767,19 +790,20 @@ Block 模式時 checkbox 不在 label 第一行——它跟 avatar 在同一高
 
 | | 掃描模式 | 閱讀模式 |
 |---|---|---|
+| **判斷標準** | 使用者快速掃描選擇 | 使用者停留閱讀 |
 | **場景** | 浮層 / overlay（一掃而過） | 頁面 / 表單（仔細閱讀） |
 | **Label 行高** | `leading-compact` (1.3) | 預設 (1.5) |
 | **Description 字體** | 降一級（14→12px, 16→14px） | 最小 14px（14→14px, 16→14px） |
 | **Description 顏色** | `fg-secondary` | `fg-secondary` |
-| **Label ↔ Desc 間距** | 2px via `--item-gap-label-desc` token(SSOT)| 同左 |
+| **Label ↔ Desc 間距** | 2px via `--item-gap-label-desc-<mode>[-lg]` token 4 變體(SSOT,見下)| 同左 |
 
-**SSOT 架構(2026-04-23 更新)**:
-- **Token**:`--item-gap-label-desc`(值 2px,定義於 `tokens/layoutSpace/layoutSpace.css`)
-- **Primitive**:`<ItemContent label description descriptionTone>`(from `item-anatomy.tsx`,封裝 flex-col + token gap)
+**SSOT 架構(2026-04-23;2026-05-31 infra-audit 修:bare token 已重構成 4 個 mode×size 變體)**:
+- **Token**:**4 變體**(皆 2px,定義於 `tokens/layoutSpace/layoutSpace.css`)——`--item-gap-label-desc-reading` / `--item-gap-label-desc-reading-lg` / `--item-gap-label-desc-scanning` / `--item-gap-label-desc-scanning-lg`(依 layout family reading/scanning × size 選)。bare `--item-gap-label-desc` 已不存在。
+- **Primitive**:`<ItemContent label description descriptionTone>`(from `item-anatomy.tsx`,封裝 flex-col + 依 mode/size 選對應 token gap)
 - **Consumer 消費 2 擇 1**:
-  - 直接 token:`mt-[var(--item-gap-label-desc)]` / `gap-[var(--item-gap-label-desc)]`
-  - 或 primitive:`<ItemContent label=... description=... descriptionTone=...>`
-- **改值一處(token)→ 全 DS 同步**,不用 grep 手改 13+ 檔
+  - 直接 token:`gap-[var(--item-gap-label-desc-<mode>[-lg])]`(選 reading/scanning × size 變體)
+  - 或 primitive:`<ItemContent label=... description=... descriptionTone=...>`(primitive 自動選變體)
+- **改值(4 變體)→ 全 DS 同步**,不用 grep 手改 13+ 檔
 
 **偏離 canonical 規則**:Consumer 若有明確合理理由不用 primitive / 自訂 label-desc typography,**必在該元件 `spec.md` 明文 rationale**。
 
@@ -787,10 +811,10 @@ Block 模式時 checkbox 不在 label 第一行——它跟 avatar 在同一高
 
 | Consumer | Primitive 消費 | Rationale |
 |----------|--------------|-----------|
-| **FileItem**(rich + compact) | ✅ ItemContent + ItemPrefix + ItemInlineActionButton | 純 row-item layout,完美 fit |
-| **Notice / Alert / Toast** | ✅ ItemContent + ItemPrefix | title+desc 標準 row-item 結構 |
-| **NameCard** | ✅ ItemContent(+ `labelTruncate=false` + `labelClassName` escape hatch) | 偏離 rationale:card context 用 `text-body-lg font-medium`,非一般 body label |
-| **MenuItem** | ✅ ItemContent(`mode="scanning"\|"scanning-lg"`)+ `itemPrefixAlignVariants` cva SSOT | Content 用 ItemContent 配合 size-aware scanning mode(sm/md = caption / lg = body-compact);label+desc clamp 透過 className escape hatch(MenuItem 特化 labelMaxLines / descMaxLines 語意) |
+| **FileItem**(rich + compact) | ✅ ItemContent + ItemPrefix(hover action 為 Button xs iconOnly,非 ItemInlineActionButton——2026-04-23 user 統一,見 file-item.tsx)| 純 row-item layout,完美 fit |
+| **Notice / Alert / Toast** | ✅ ItemContent + ItemPrefix + ItemSuffix | 乾淨 reading-md consumer（2026-06-15 收斂:原 root `leading-compact` off-grid 偏移已移除、suffix 改消費 ItemSuffix;詳 notice.spec.md Typography 段）|
+| **ProfileCard** | ✅ ItemContent(+ `labelTruncate=false` + `labelClassName` escape hatch) | 偏離 rationale:card context 用 `text-body-lg font-medium`,非一般 body label |
+| **MenuItem** | ✅ ItemContent(`mode="scanning"` + `size="md"\|"lg"` 正交)+ `itemPrefixAlignVariants` cva SSOT | Content 用 ItemContent 配合 size-aware scanning mode(sm/md = caption / lg = body-compact);label+desc clamp 透過 className escape hatch(MenuItem 特化 labelMaxLines / descMaxLines 語意) |
 | **Sidebar / TreeView** | ✅ ItemPrefix(+ 其他 primitives) | Label-only(無 description),不需 ItemContent |
 | **Empty** | ❌ token-direct only | **結構限制**:centered stack pattern(icon → title → desc → action 垂直居中),非 row-item 佈局。保持手刻 |
 | **Dialog**(DialogTitle / DialogDescription) | ❌ token-direct only | **結構限制**:title 跟 desc 是獨立 Radix `<DialogTitle>` / `<DialogDescription>` component(aria-labelledby / aria-describedby 語義),非同層 span 配對 |
@@ -799,7 +823,7 @@ Block 模式時 checkbox 不在 label 第一行——它跟 avatar 在同一高
 | **Switch**(standalone mode with label+desc) | ❌ token-direct only | **a11y 限制(同 SelectionItem)**:standalone mode 用 `<label htmlFor={inputId}>` 包 label+desc+switch,form control 關聯必要。Control-only mode(放 MenuItem suffix 等)不涉及 label+desc,不在 ItemContent scope |
 | **Steps**(`StepDescription`) | ❌ token-direct only | **API 限制**:StepLabel 跟 StepDescription 是獨立 public forwardRef subcomponent,consumer 分開寫;遷 ItemContent(single-component API)= breaking API |
 
-**共 5 consumer 消費 primitive(FileItem / Notice / NameCard / MenuItem / TreeView・Sidebar),5 consumer 保 token-direct 各有 a11y / semantic / API 結構限制**。Token 層 SSOT 100% 覆蓋(改 `--item-gap-label-desc` 全 DS 同步);primitive 層覆蓋結構能 fit 的 consumer。
+**共 5 consumer 消費 primitive(FileItem / Notice / ProfileCard / MenuItem / TreeView・Sidebar),6 consumer 保 token-direct(Empty / Dialog / DescriptionList / SelectionItem / Switch / Steps)各有 a11y / semantic / API 結構限制**。Token 層 SSOT 100% 覆蓋(改 `--item-gap-label-desc-<mode>[-lg]` 4 變體 → 全 DS 同步);primitive 層覆蓋結構能 fit 的 consumer。
 
 **Switch 跟 SelectionItem 同 blocker**(2026-04-23 user 糾正):兩者都是 `<label htmlFor>` 表單 control 關聯結構,ItemContent 用 `<span>` 渲染 label 會破壞 form a11y。這類結構**只能 token-level SSOT**(實際已做)。
 
@@ -819,20 +843,19 @@ World-class benchmark(6 家 DS):
 - Polaris / Atlassian / Apple HIG:typography token 手選(無 density prop)
 - 6 家共識:14/20 vs 16/24 兩擋 body 表達 scanning vs reading
 
-本 DS 採 density-prop 派(A 派),跟 Material / Carbon / Ant 對齊。`mode` 比 `dense` 更 self-documenting。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+本 DS 採 density-prop 派(A 派),跟 Material / Carbon / Ant 對齊。`mode` 比 `dense` 更 self-documenting。 <!-- @benchmark-unverified -->
 
 **未來改 scanning typography(e.g. 從 caption 12 改到 caption 13)**:只改 `--font-caption-size` token 一處 → 所有 `mode="scanning"` 的 consumer 同步動。
 
 ### Suffix block formula 的 `2px` 也 tokenize(2026-04-23)
 
 `h-[calc(1lh+2px+desc_1lh)]` 中的 `2px` 原 hard-code(item-anatomy.stories / MenuItem cva / SelectionItem cva),
-2026-04-23 全改為 `var(--item-gap-label-desc)` — 同 token 傳播到 block 公式。改 gap 值一處,
-inline 跟 block 兩層 formula 同步動。
+2026-04-23 全改為 gap token — 同 token 傳播到 block 公式。改 gap 值一處,inline 跟 block 兩層 formula 同步動。
+(2026-05-31 重構後依 mode/size 選對應後綴變體 `--item-gap-label-desc-<reading|scanning>[-lg]`,bare token 已不存在;見上方「兩種閱讀模式」SSOT 段。)
 
 **Enforcement**:
-- Hook `check_item_content_primitive.sh`(2026-04-23)P1 warn:component .tsx 出現硬寫 `mt-0.5` / `gap-0.5` 提示改 token / primitive
-- Consumer 刻意 hard-code 加 `// @item-gap-exempt: <reason>` 豁免 + rationale 在 spec
-| **判斷標準** | 使用者快速掃描選擇 | 使用者停留閱讀 |
+- Hook `check_item_content_primitive.sh`(2026-04-23 加)已 retired(→ `.claude/hooks/retired/`,無現役 write-time 機械閘);硬寫 `mt-0.5` / `gap-0.5` 現靠 audit-time 掃描 + mindset #2(優先消費既有 token / primitive)把關
+- Consumer 刻意 hard-code 加 `// @item-gap-exempt: <reason>` 豁免 + rationale 在 spec(marker 現無 hook 消費者,保留作 review 註記)
 
 **兩種模式的唯一差異是行高。** Description 在所有模式都降一級字體——label 是要辨識的目標，description 是補充，尺寸差有助快速區分。
 
@@ -921,7 +944,6 @@ inline 跟 block 兩層 formula 同步動。
 
 ---
 
-
 ## Inline Action 設計規格 → `inline-action.spec.md`(2026-04-24 抽出,獨立 SSOT)
 
 嵌入 Tag dismiss / Field endAction / Row suffix action 的 icon primitive。完整 265 行視覺規格 / API / predicate / Icon 色 / same-row consistency → 見 `patterns/element-anatomy/inline-action.spec.md`。
@@ -935,7 +957,7 @@ inline 跟 block 兩層 formula 同步動。
 **任何元件既有的狀態 prop(`selected` / `checked` / `disabled` / `pressed` / `active` / `invalid` / `loading` 等),消費端必須用 prop,禁止用 `className` 疊加自創樣式表達同一個狀態**。
 
 理由:
-- 既有 prop 背後綁定 **canonical token**(`bg-neutral-selected` / `border-primary-hover` 等),一改全系統同步
+- 既有 prop 背後綁定 **canonical token**(`bg-neutral-selected` / `border-primary` 選中等),一改全系統同步
 - `className` 自創樣式繞過 canonical,導致「同一狀態在不同元件產生視覺分歧」的跨元件漂移
 - 既有 prop 通常也綁 ARIA attributes(`aria-selected` / `aria-checked` 等),自創樣式會丟失 a11y 語意
 
@@ -1003,7 +1025,7 @@ Selection control(Dropdown / Menu / List / SegmentedControl / Chip)的 item 視
 6. ✅ 外層 `flex items-start`,prefix / suffix 各自包 `h-[1lh]`(或 block calc)wrapper
 7. ✅ Prefix 用 `<ItemIcon>` / `<ItemAvatar>` helper,**禁止**硬寫 `<Avatar size={N} />` 或 `<Icon size={N} />`
 8. ✅ Icon 尺寸用 `ICON_SIZE` 常數 + `size` prop 直接傳給 Lucide,不用 CSS `[&>svg]:size-*` selector
-9. ✅ Label span 有 `min-w-0 flex-1 truncate`(或用 `<ItemLabel>` helper)
+9. ✅ Label span 有 `min-w-0 flex-1 truncate`(或用 `<ItemLabel>` helper);截斷必配「截斷才顯」tooltip(tooltip.spec.md:32)—— `<ItemLabel>` / `<ItemContent>` 已內建,手刻 span 要自己消費 `useTruncated`(見「單行截斷 → tooltip」節)
 10. ✅ Suffix inline action 用 `<ItemInlineAction>` / `<ItemInlineActionButton>`,**禁止**複製 hover-bg 絕對定位 JSX
 11. ✅ Row primitive 容器用 `<RowSizeProvider value={size}>` 包住所有 children,讓 helper 元件能讀到 size
 12. ✅ icon 色彩遵循「代表內容 = label 同色,指示方向 = fg-muted」
@@ -1022,21 +1044,28 @@ Selection control(Dropdown / Menu / List / SegmentedControl / Chip)的 item 視
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `alert.spec.md`
+- `checkbox.spec.md`
+- `color.spec.md`
 - `command.spec.md`
-- `data-table.spec.md`
 - `dropdown-menu.spec.md`
+- `element-anatomy.spec.md`
 - `empty.spec.md`
+- `field-controls.spec.md`
 - `field.spec.md`
 - `file-item.spec.md`
+- `header-canonical.spec.md`
+- `inline-action.spec.md`
+- `layoutSpace.spec.md`
 - `menu-item.spec.md`
 - `notice.spec.md`
-- `overlay-surface.spec.md`
 - `select-menu.spec.md`
 - `select.spec.md`
 - `selection-item.spec.md`
 - `sidebar.spec.md`
-- `tag.spec.md`
+- `steps.spec.md`
+- `tabs.spec.md`
 - `time-picker.spec.md`
 - `toast.spec.md`
+- `token-system.spec.md`
 - `tree-view.spec.md`
 - `typography.spec.md`