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

package/src/components/Sidebar/sidebar.spec.md

@@ -32,12 +32,10 @@ benchmark:
   - Polaris Navigation: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Navigation
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
-
 # Sidebar 設計原則
 
 > **Foundational SSOT rationale**(2026-04-24 approved,cap 800):
-> Sidebar 有獨立 `sidebarMenuButtonVariants` cva(對齊 MenuItem 但獨立實作,同步風險見 item-anatomy.spec「SidebarMenuButton 獨立實作風險」)+ 20+ Sidebar-specific features SSOT(Chrome header/footer 高度 / Collapsible / Icon 模式 / SidebarTrigger 位置 / Mobile 行為 / 持久化 / 快捷鍵 / Group 收合 / Single selection / Inline actions / Keyboard shortcuts),scope > 單一 MenuItem consumer。Long-term 考慮 refactor 消費 menuItemVariants base(詳 `.claude/planning/row-primitive-consolidation.md`)— 若 refactor 成功,本 spec 可縮到 ~300。
+> Sidebar 有獨立 `sidebarMenuButtonVariants` cva(對齊 MenuItem 但獨立實作,同步風險見 item-anatomy.spec「SidebarMenuButton 獨立實作風險」)+ 20+ Sidebar-specific features SSOT(Chrome header/footer 高度 / Collapsible / Icon 模式 / SidebarTrigger 位置 / Mobile 行為 / 持久化 / 快捷鍵 / Group 收合 / Single selection / Inline actions / Keyboard shortcuts),scope > 單一 MenuItem consumer。Full cva consume 提案經二次評估 declined(2026-04-24,詳 `.claude/planning/row-primitive-consolidation.md.rejected.20260424.md`)— ROW_PADDING_BY_SIZE token SSOT 已是 practical best。
 
 ## 定位
 
@@ -45,7 +43,7 @@ benchmark:
 
 **實作基礎**：基於 Radix Collapsible + Radix Slot（shadcn Sidebar 模式改寫）+ 橋接 DS token。
 
-**Layout Family**：CLAUDE.md 4-Family Model **Family 1（Menu item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「Menu item layout」章節的 scanning-mode 規格。
+**Layout Family**：本元件是 `patterns/element-anatomy/item-anatomy.spec.md` 所擁有的 **Family 1（Menu item layout）** 消費者。結構繼承其「Menu item layout」章節的 scanning-mode 規格。
 
 **不是**：NavigationMenu（水平導覽）、Tabs（同層切換）、Command Palette（跨頁搜尋）、Sheet / Drawer（暫時性面板）。Sidebar 是**持續存在**的主骨架。
 
@@ -74,7 +72,7 @@ benchmark:
 
 ```
 SidebarProvider              ← 全域 context（open 狀態、cookie、快捷鍵）
-  Sidebar                    ← 主容器（variant + collapsible + side）
+  Sidebar                    ← 主容器（collapsible + side + viewportInsetTop）
     SidebarHeader            ← 頂部：logo、workspace switcher
     SidebarContent           ← 中間可捲動區
       SidebarGroup           ← 分組容器（可多個，純視覺分段）
@@ -83,14 +81,13 @@ SidebarProvider              ← 全域 context（open 狀態、cookie、快捷
           │
           ├─ SidebarMenu           扁平選單（1 層、有限可列舉）
           │    SidebarMenuItem
-          │      SidebarMenuButton   ← 必須有 icon
+          │      SidebarMenuButton   ← icon 模式下 consumer 應確保每個 item 有 icon（否則 collapsed rail 出現空槽；非元件強制）
           │      SidebarMenuBadge    ← 右側 badge
           │      SidebarMenuAction   ← hover 浮出的 action
           │
           └─ TreeView              階層樹（user data、任意深度）
     SidebarFooter            ← 底部：user menu、settings 觸發器
-    SidebarRail              ← 邊緣細條，點擊切換收合（可選）
-  SidebarTrigger             ← 展開 / 收合按鈕（可放 sidebar 內或外）
+  SidebarTrigger             ← 展開 / 收合按鈕（放 sidebar 外，詳「SidebarTrigger 位置」段）
 ```
 
 **不使用 shadcn 原版的 `SidebarMenuSub` / `SidebarMenuSubItem`**——見下方內容形態規則。
@@ -129,7 +126,11 @@ SidebarProvider              ← 全域 context（open 狀態、cookie、快捷
 - **Density**（md/lg）是**全域 UI 設定**,影響所有 `--field-height-*` tokens 的實際值
 - 兩者**獨立**:size="md" 在 density="md" 下是 32px row、在 density="lg" 下自動變 36px row
 
-**Chrome header 不跟 size 變**：`SidebarHeader` / `SidebarFooter` 固定用 `var(--chrome-header-height)`,只跟 **density** 連動,不跟 `size` prop 變——因為 header 是結構槽位,不是 row。
+**Chrome header 不跟 size 變**：`SidebarHeader` 固定用 `var(--chrome-header-height)`,只跟 **density** 連動,不跟 `size` prop 變——因為 header 是結構槽位,不是 row。**SidebarFooter 修正(2026-06-12 doc-to-code)**:footer 實作自 2026-04-14 起為 content-based(`flex flex-col py-2`,sidebar.tsx SidebarFooter,行為同 SidebarGroup),**非** fixed-h——單行高度由下方內容紀律保證,非結構鎖。
+
+**SidebarFooter user 區必單行(2026-06-12 明文,fork drift 防線;2026-07-30 帳號選單修正)**:名字單行(`text-body-lg` truncate)。footer user 行 = **帳號入口**,點開**帳號選單(`DropdownMenu`)**;職稱/email/工號等身份資訊歸帳號選單頂部 `DropdownMenuLabel` 第二行(`text-caption`)。**自己的 avatar 不掛 ProfileCard hoverCard**(ProfileCard 是看「別人」的人員卡;rule owner = `../AppShell/app-shell.spec.md`「帳號入口(Account entry)放置 SSOT」的「入口開什麼」段,本處不重述)。(UserFooter canonical,sidebar.stories.tsx)。shadcn nav-user 的「name + email `text-xs` 兩行」是 demo 慣例非本 DS canonical(`text-xs` 同時違反下方 chrome typography 一律 `text-body-lg` 條);registry antiPattern `sidebar-footer-two-line` 機械攔。
+
+**SidebarHeader brand 必單行(2026-06-12 明文,fork drift anchor)**:Avatar 24 + 名稱單行,**無副標 slot**——Fixed-h chrome 結構上不可成長;plan/org 等第二行資訊歸 workspace switcher dropdown row,對齊 Slack/Notion/Linear 現行版單行。shadcn TeamSwitcher demo 的「Acme Inc + Enterprise」兩行是 demo 慣例非本 DS canonical(fork repo AI 曾以訓練先驗在 spec 沉默處回填此副標)。Registry antiPattern `sidebar-header-subtitle-second-line` 機械攔(flex-col 直接子層簽名)。
 
 ---
 
@@ -139,7 +140,7 @@ Sidebar 有兩種正交的內容形態，consumer 嚴格擇一或混用：
 
 | 形態 | 元件 | 深度 | 數量 | Icon 模式 |
 |------|------|------|------|----------|
-| **扁平導覽** | `SidebarMenu` | **嚴格 1 層** | **有限可列舉** | ✅ 顯示 icon + tooltip |
+| **扁平導覽** | `SidebarMenu` | **嚴格 1 層** | **有限可列舉** | ✅ 顯示 icon(hover tooltip 為 opt-in,需 per-button 傳 `tooltip` prop) |
 | **階層樹** | `TreeView` | 任意 | 任意 | ❌ 整區隱藏 |
 
 ### 判斷規則
@@ -188,7 +189,7 @@ Settings 不在 sidebar，從 footer 的 avatar / user menu 觸發 modal 或快
 
 ### 混用
 
-Gmail / Linear 的標準版型：上方 SidebarGroup 放扁平主導覽（SidebarMenu），下方 SidebarGroup 放 user data（TreeView）。icon 模式下，扁平區顯示 icon + tooltip，TreeView 整段隱藏。
+Gmail / Linear 的標準版型：上方 SidebarGroup 放扁平主導覽（SidebarMenu），下方 SidebarGroup 放 user data（TreeView）。icon 模式下，扁平區顯示 icon（hover tooltip 需 per-button 傳 `tooltip` prop），TreeView 整段隱藏。
 
 ---
 
@@ -204,13 +205,13 @@ Gmail / Linear 的標準版型：上方 SidebarGroup 放扁平主導覽（Sideba
 
 ## Chrome header / footer 高度：density-responsive shared token
 
-`SidebarHeader` 和 `SidebarFooter` 的高度 = `var(--chrome-header-height)`，**不是寫死**，也**不是完全 content-based**。這個 token：
+`SidebarHeader` 的高度 = `var(--chrome-header-height)`，**不是寫死**，也**不是完全 content-based**(SidebarFooter 為 content-based,見上方 2026-06-12 修正)。這個 token：
 
 > **跨家族 SSOT pointer**:本元件 SidebarHeader 屬 **Chrome header(Fixed-h)家族**;border / padding / dismiss size / withTabs(tabs 進 header 時 border auto-suppress + tabs size 對應 + flush stack)的跨家族視覺契約 SSOT 詳 `patterns/header-canonical/header-canonical.spec.md`。本節僅 codify Sidebar 特有的高度 + token rationale。
 
 - md density: `3rem`（48px）
 - lg density: `3.5rem`（56px）
-- **跨元件共享**：sidebar header、sidebar footer、主內容 page header 都用同一個 token
+- **跨元件共享**：sidebar header、主內容 page header 都用同一個 token(sidebar footer 為 content-based,見上方 2026-06-12 修正)
 - **隨 density 同步變**
 
 ### 為什麼是這個設計（不是 h-12 寫死 或 py-3 純 padding）
@@ -238,9 +239,9 @@ Gmail / Linear 的標準版型：上方 SidebarGroup 放扁平主導覽（Sideba
 
 ### Chrome 內容的約束
 
-放在 SidebarHeader / SidebarFooter 裡的元件必須能容納在這個高度內：
+放在 SidebarHeader（固定高度 `--chrome-header-height`）裡的元件必須能容納在這個高度內（**SidebarFooter 為 content-based，高度隨內容 flex、不受此固定高度約束**）：
 
-- Avatar: `size={24}` —— **chrome header avatar canonical（density-fixed / row-size-fixed）**。consumer 用 **raw `<Avatar size={24}>`**（chrome header 不是 row context → 不該用 `<ItemAvatar>`）。對應 CSS local token `--chrome-header-avatar-size: 1.5rem`（`header-canonical.css`），sidebar 收合對齊公式消費此 token。詳 `header-canonical.spec.md`「4.5 Chrome header avatar SSOT」段 + `item-anatomy.spec.md:535` scope 限定段。
+- Avatar: `size={24}` —— **chrome header avatar canonical（density-fixed / row-size-fixed）**。consumer 用 **raw `<Avatar size={24}>`**（chrome header 不是 row context → 不該用 `<ItemAvatar>`）。對應 CSS local token `--chrome-header-avatar-size: 1.5rem`（`header-canonical.css`），sidebar 收合對齊公式消費此 token。詳 `header-canonical.spec.md`「4.5 Chrome header avatar SSOT」段 + `item-anatomy.spec.md`「Scope 例外:Chrome header 不是 row context」段。
 - Button: `size="sm"` 或 `size="md"`
 - 單排 title 文字 + icon button
 
@@ -262,16 +263,9 @@ Modal header 用 **padding-based**（`py-3` + content），因為 modal 是 ephe
 - 不同 weight → 會造成「哪個比較重要」的語意混淆
 - **「當前位置」的訊號由 sidebar active item(`bg-neutral-selected`)負責**,不靠 page title 的字重搶戲
 
-### 對照 Linear / Slack / Discord / Figma <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+### Chrome typography 選擇
 
-| 產品 | Chrome text size | 做法 |
-|---|---|---|
-| Linear | 14-15px medium | 同 size 同 weight |
-| Slack | 15-18px bold | 同 weight,稍有 size 差異 |
-| Discord | 16px semibold | 同 size 同 weight |
-| Figma | 13px regular | 同 size 同 weight |
-
-我們選 **`text-body-lg font-medium` 統一**,是世界級 chrome typography 的中庸做法——比 Linear（14-15px medium）字級大 1px / weight 一致，比 Slack（15-18px bold）字級略小且 weight 較輕避免 navigation 過度搶 attention，對齊 Discord（16px semibold）。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+本 DS 選 **`text-body-lg font-medium` 統一**：16px 保留 chrome 中的可讀性，medium 足以標示結構但不會壓過頁面內容。workspace brand、page title 與 user name 共用同 size / weight，層級改由 slot 位置與 active state 表達，不在固定高度的 chrome 裡製造假主從。
 
 ---
 
@@ -472,7 +466,7 @@ variant=meta 把這三件事做成結構性保證:樣式自動退、selection
 </SidebarMenuButton>
 ```
 
-**世界級對照**:Linear「Show N more」、Notion「Show N more」、Slack「Show more」、Gmail Labels「More」——全部是「section 底部的 muted 命令 row」,行為與視覺一致。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**命令 row 語意**:meta item 固定放在 section 底部，以 muted 視覺表明它會展開更多資料，而不是另一個可被選中的導覽項目。
 
 **禁止**:
 
@@ -484,9 +478,9 @@ variant=meta 把這三件事做成結構性保證:樣式自動退、selection
 
 ## Single selection（整個 sidebar 同時只有一個 active item）
 
-**規則**:不論 MainNav / TreeView / Favorites / 任何 group,**同一時間只有一個 item 被選中**。選任何 item 都會自動 deselect 其他。沒有例外——sidebar 的核心語意是「當下在哪頁」,多個 active 就失去意義。
+**規則(UX 語意)**:不論 MainNav / TreeView / Favorites / 任何 group,**同一時間只有一個 item 被選中**——sidebar 的核心語意是「當下在哪頁」,多個 active 就失去意義。
 
-**結構性保證**:`SidebarProvider` 內建 single-selection state,`SidebarMenuButton` 接 `id` prop 自動從 context 讀 `isActive`、自動在 `onClick` 呼叫 `setActiveId`。
+**結構性保證(範圍 = `SidebarMenuButton`)**:`SidebarProvider` 內建 single-selection state,`SidebarMenuButton` 接 `id` prop 自動從 context 讀 `isActive`、自動在 `onClick` 呼叫 `setActiveId`。**此結構保證僅涵蓋 `SidebarMenuButton`**:`TreeView` 用自己獨立的 `selectedIds` state、不接 `SidebarContext`,**沒有元件層級的 cross-family auto-deselect**——跨 TreeView 的單選需 consumer 用同一份 `activeId` state 手動橋接(SidebarMenu 與 TreeView 都讀寫同一個 state,見 principles『啟用狀態跨群組單一』story)。
 
 ```tsx
 // Controlled(router-driven,typical production 用法)
@@ -517,8 +511,8 @@ variant=meta 把這三件事做成結構性保證:樣式自動退、selection
 
 `<SidebarGroup collapsible>` 把整個 group 升級成可點擊收合。內部用 Radix Collapsible 實作,**三件事自動發生**:
 
-1. `SidebarGroupLabel` 從純裝飾 header 變成 trigger(button),加 hover 狀態、`cursor-pointer`
-2. Label 尾端自動渲染 `ChevronRight` icon,open 時旋轉 90°
+1. `SidebarGroupLabel` 本身仍是純裝飾 header(`div` `role="presentation"`),**只有尾端的 chevron** 是 trigger（`Collapsible.Trigger asChild` 包住 `ItemInlineActionButton`，帶 hover bg / `cursor-pointer`）——刻意不把整個 label 升格為 button，理由見下方 rationale
+2. Label 尾端自動渲染 `ChevronDown` icon(accordion 慣例),open 時旋轉 180°
 3. `SidebarGroupContent` 被 `Collapsible.Content` 包起來,data-state 可驅動動畫
 
 Consumer 不需要任何額外 code——只要加一個 prop:
@@ -536,7 +530,7 @@ Consumer 不需要任何額外 code——只要加一個 prop:
 - ❌ 主導覽 group(永遠要看見)
 - ❌ 只有 1-2 個 item 的 group(收合徒增互動成本)
 
-**為什麼 prop 放在 `SidebarGroup` 而非 `SidebarGroupLabel`**:「是否可收合」是結構層決定,影響 label(是否 trigger)+ content(是否 animated container)兩個 primitive。放在 label 上會讓 content 不知道該不該被 `Collapsible.Content` 包,形成 prop drilling。group 層用 React context 傳遞是標準做法。
+**為什麼 prop 放在 `SidebarGroup` 而非 `SidebarGroupLabel`**:「是否可收合」是結構層決定,影響 label 尾端 chevron button(是否為 `Collapsible.Trigger`)+ content(是否被 `Collapsible.Content` 包)兩個 primitive(label 本身維持 `role="presentation"` div,不升格為 button)。放在 label 上會讓 content 不知道該不該被 `Collapsible.Content` 包,形成 prop drilling。group 層用 React context 傳遞是標準做法。
 
 ---
 
@@ -544,7 +538,7 @@ Consumer 不需要任何額外 code——只要加一個 prop:
 
 `<SidebarMenuButton inlineActions={[...]}>` 支援 suffix 放置 inline action button,搭配 `actionsReveal="hover"` 做 TreeView 風格的 hover-reveal。
 
-**宣告式 API**,完全對齊 `uiSize.spec.md`「Inline Action」節:
+**宣告式 API**,完全對齊 `patterns/element-anatomy/inline-action.spec.md`(Inline Action SSOT):
 
 ```tsx
 <SidebarMenuButton
@@ -566,20 +560,20 @@ Consumer 不需要任何額外 code——只要加一個 prop:
 - 處理 Tooltip / `aria-label` / `cursor-pointer`(宣告式 config 自動帶)
 - 計算 button 的 `paddingRight`(host 用 `N×icon + (N-1)×gap + loose + gap` 公式自動算)
 
-**規格**(完全繼承 uiSize.spec.md):
+**規格**(完全繼承 `inline-action.spec.md`):
 
 | 項目 | 值 |
 |---|---|
 | Icon 尺寸 | `ICON_SIZE[size]`(16/16/20) |
 | Hover bg 尺寸 | icon + 2(18/18/22) |
-| Hover bg 圓角 | `rounded-md` (sm/md) / `rounded-md` (lg) |
-| Icon 顏色 | `fg-muted` → `foreground` on hover/active |
+| Hover bg 圓角 | `rounded-md`(全尺寸一致) |
+| Icon 顏色 | `fg-muted` → `fg-secondary` on hover/active |
 | 多個 action 間距 | `gap-2`(8px) |
 | 出現時機 | 預設永遠顯示;`actionsReveal="hover"` → row hover/focus 才淡入 |
 | Icon 模式 | 整個 suffix 隱藏 |
 | Host disabled 時 | 不渲染(遵守宿主 disabled 規則) |
 
-**Canonical 實作**:`ItemInlineAction` + `ItemSuffix`(`item-layout.tsx`)。未來 DropdownMenuItem / TreeItem / Field / Tag 都應逐步遷移到這個共用元件,消除「每個 host 各自複製 18 行 JSX」的技術債——見 `item-anatomy.spec.md` 底部「Inline action 共用元件」節。
+**Canonical 實作**:`ItemInlineAction` + `ItemSuffix`(`item-anatomy.tsx`)。未來 DropdownMenuItem / TreeItem / Field / Tag 都應逐步遷移到這個共用元件,消除「每個 host 各自複製 18 行 JSX」的技術債——見 `inline-action.spec.md`(Inline Action SSOT)。
 
 **何時用**:
 - ✅ Favorites / Bookmarks 類 user data item 的 hover-reveal 「⋯」/「×」
@@ -591,10 +585,14 @@ Consumer 不需要任何額外 code——只要加一個 prop:
 
 ## Mobile 行為
 
-`md` breakpoint（768px）以下自動切 **Sheet 抽屜**——從側邊滑入、覆蓋主內容、點外部或 Esc 關閉。Sheet 寬度用 `--sidebar-width-mobile`，**mobile 沒有 icon 模式**（細列在手機上既占空間又難點）。
+`md` breakpoint（768px）以下,`collapsible="offcanvas"`（預設）/ `"icon"` 自動切 **Sheet 抽屜**——從側邊滑入、覆蓋主內容、點外部或 Esc 關閉。Sheet 寬度用 `--sidebar-width-mobile`，**mobile 沒有 icon 模式**（細列在手機上既占空間又難點）。
+
+**例外 — `collapsible="none"`**:`none` 分支在 tsx 於 `isMobile` 判斷**之前**提前 return 固定寬度 `--sidebar-width` div,**不進 Sheet**。故 mobile + `collapsible="none"` 會維持固定 240px 側欄(第三種狀態),非「一律 Sheet」。需 mobile Sheet 行為請用 `offcanvas` 或 `icon`。
 
 Sheet 開啟狀態**不持久化**。
 
+**Sheet 蓋住 global top bar → primary-header consumer 須在 Sheet 內補品牌/帳號**:Sheet（z-50）打開時覆蓋整個左側含 global top bar。若你是 `AppShell` `primary-header` 派(品牌 logo + 帳號入口放在 globalHeader、sidebar 平常無 header/footer),小螢幕 Sheet 打開後 globalHeader 被蓋住 → 使用者看不到品牌也按不到帳號。解法:consumer 讀 `useSidebar().isMobile` + `useAppShell().layout`,**mobile 時才**在 `<SidebarHeader>` 內放 `<WorkspaceBrand/>`(左)+ `flex-1` + `<AccountMenu/>`(右)= 把整條 globalHeader 鏡像進 Sheet 頂排(SidebarHeader 即 ChromeHeader 基底,結構 SSOT);**不放 `<SidebarFooter>`**(primary-header 帳號家在 header 區,footer 是 primary-sidebar 慣例)。**rule owner = `../AppShell/app-shell.spec.md`「帳號入口(Account entry)放置 SSOT」的 Responsive 精修子句**(本處不重述,Rule-of-3)。reference:`AppShell/_demo-helpers.tsx` `AcmeSidebar`。
+
 ---
 
 ## 持久化與快捷鍵
@@ -610,12 +608,20 @@ Sheet 開啟狀態**不持久化**。
 
 | Token | 預設值 | 用途 |
 |-------|--------|------|
-| `--sidebar-width` | `17rem` | 展開寬度 |
-| `--sidebar-width-icon` | `calc(2 * var(--layout-space-loose) + var(--sidebar-menu-icon-size))` | icon 模式寬度(2026-05-21 v3 撤回 `3rem` hardcode,改 geometry formula 保證 icon center x = loose + icon/2 在展開/收合一致;md=48 / lg=64,跟 chrome-header-height 解耦)|
+| `--sidebar-width` | `15rem` (240px) | 展開寬度(2026-05-21 v11 user 拍板 240px;對齊 Linear/Notion/Figma/Polaris/Material Drawer 主流 240–256,5/8 家 = 240。也是 `--sidebar-width-min` AppShell Aside floor 共識值)|
+| `--sidebar-width-icon` | `calc(2 * var(--layout-space-loose) + var(--sidebar-menu-icon-size))` | icon 模式寬度(2026-05-21 v3 撤回 `3rem` hardcode,改 geometry formula 保證 icon center x = loose + icon/2 在展開/收合一致;**md = 2×16+16 = 48 / lg = 2×24+20 = 68**,跟 chrome-header-height 解耦)|
 | `--sidebar-menu-icon-size` | `1rem` (16px) | sidebar menu icon 大小(per ICON_SIZE.sm/md=16);size=lg 罕見 case override `1.25rem` |
 | `--sidebar-width-mobile` | `18rem` | Mobile sheet 寬度 |
 
-**用 rem**：跟隨 root font-size，支援 accessibility 等比例縮放。**不用 layoutSpace / uiSize 推導**：sidebar width 是容器維度，不是間距或元件內高度，語意不同；耦合會讓寬度跟間距連動。**16rem / 3rem / 18rem** 是 shadcn + 多數 SaaS 的事實標準，不要為獨特而改。
+**用 rem**：跟隨 root font-size，支援 accessibility 等比例縮放。**不用 layoutSpace / uiSize 推導**：sidebar width 是容器維度，不是間距或元件內高度，語意不同；耦合會讓寬度跟間距連動。**15rem / 18rem** 對齊 Linear/Notion/Figma/Polaris/Material Drawer 240–288 主流寬度,`--sidebar-width-icon` 用 geometry formula(2026-05-21 v3)`calc(2*loose + icon-size)` 保證 collapse/expand icon center x 一致。
+
+---
+
+## 常見誤解
+
+- 「SidebarMenuSub 可做第 2 層選單」——本 DS 不 export;深度 > 1 一律 TreeView(見「內容形態選擇」)
+- 「Settings 子頁要佔 sidebar 位置」——走 in-page secondary nav / user menu modal(見「Settings 這類有子頁的頁面」)
+- 「點 icon 可順便展開 sidebar」——行為不可預測;重新看階層資料的唯一路徑 = 展開 sidebar(見「Icon 模式的行為規則」)
 
 ---
 
@@ -634,7 +640,7 @@ Sheet 開啟狀態**不持久化**。
 
 ## 與其他元件的關係
 
-- **TreeView**：放在 SidebarContent 內；icon 模式由 Sidebar 透過 CSS 自動隱藏；`context="sidebar"` 讓 TreeView 用 sidebar 的 padding token
+- **TreeView**：放在 SidebarContent 內；icon 模式不會自動隱藏，TreeView／可收合 tree group 的承載 group 必須傳 `className="group-data-[collapsible=icon]:hidden"`；`context="sidebar"` 讓 TreeView 使用 sidebar padding token
 - **Command（Cmd+K）**：icon 模式下深層頁面跳轉的逃生艙
 - **Tabs**：Settings 等頁面的 in-page secondary nav
 - **DropdownMenu**：SidebarHeader 的 workspace switcher、SidebarFooter 的 user menu
@@ -645,7 +651,7 @@ Sheet 開啟狀態**不持久化**。
 ## 判斷決策樹
 
 ```
-Variant：傳統工具型 → sidebar；現代 SaaS 卡片化 → inset；浮動面板 → floating
+Variant：目前僅 sidebar（floating 刻意不做 / inset 規劃中未實作，見「Variant」段）
 
 Collapsible：內容優先低頻導覽 → offcanvas；扁平高頻切換 → icon；超簡單 → none
 
@@ -658,23 +664,21 @@ Collapsible：內容優先低頻導覽 → offcanvas；扁平高頻切換 → ic
 
 ---
 
-## 為何無 Inspector
-
-Sidebar 的決策維度是「結構配置」(variant / collapsible / uniformPrefix / density)不是單一 prop——已由 `Overview`(結構樹)+ `SizeMatrix` + `ColorMatrix` + `StateBehavior` + `ChromeTokens` 五 story 完整覆蓋。互動 Inspector 切單一 prop 不如結構對照,且 Sidebar 外觀需要足夠的 nav 量才能展示——真實展示是 `Overview` 的 SidebarPreview 完整結構。
-
 ## StateBehavior(Sidebar 層級特有)
 
-Item-level default / hover / active / selected / disabled **色彩**完全共用 item-anatomy row primitive(`patterns/element-anatomy/item-anatomy.spec.md`),由 `ColorMatrix` 用 5 個 state 的完整 token 對照表承載(state-driven 色彩表)。Sidebar 的 `StateBehavior` story 則展示 **container 層級的結構狀態切換**:三種 `collapsible` 模式(offcanvas / icon / none)、Cmd+B / SidebarTrigger toggle、icon mode 下 label 隱藏 + Tooltip 代償、跨 session cookie 還原——這些是 shell 層級特有的行為,不存在於 row item primitive。
+Item-level default / hover / selected / disabled **色彩**完全共用 item-anatomy row primitive(`patterns/element-anatomy/item-anatomy.spec.md`),由 `ColorMatrix` 用 4 個 state 的完整 token 對照表承載(state-driven 色彩表)。SidebarMenuButton(獨立 cva)無 `:active` press state——對齊 MenuItem / TreeItem 同族 row-button,`--neutral-active` 僅由 inline-action 子按鈕消費(item-anatomy.tsx group-active/action),menu button 本體不套用。Sidebar 的 `StateBehavior` story 則展示 **container 層級的結構狀態切換**:三種 `collapsible` 模式(offcanvas / icon / none)、Cmd+B / SidebarTrigger toggle、icon mode 下 label 隱藏 + Tooltip 代償、跨 session cookie 還原——這些是 shell 層級特有的行為,不存在於 row item primitive。
 
 ---
 
 ## A11y 預設
 
-- **Landmark**:`<Sidebar>` 渲染 `<nav aria-label="Main">`(或 consumer 傳入更精確的 label,例「Workspace navigation」),作為 page-level navigation landmark,讓 SR user 直接跳轉。
-- **Active item**:`SidebarMenuButton` 帶 `id` + 命中 `activeId` 時自動加 `aria-current="page"`,SR 朗讀「current page」。`variant="meta"` 不參與 selection 不加此 attribute。
-- **快捷鍵不衝突**:`Cmd+B` / `Ctrl+B` 是 industry-standard(VS Code / Linear / shadcn),DS 內建並 `preventDefault` 避免穿透到 browser bookmark bar(`Cmd+B` 在 Safari 是 favorites);若 consumer 已有同鍵其他語意需 opt-out 透過 `SidebarProvider` `disableShortcut` prop。
-- **Mobile sheet focus trap**:`md` breakpoint 以下切 Sheet 模式時,Radix Dialog 自帶 focus trap + Esc dismiss + restore focus to trigger(詳 sheet.spec.md)。
-- **Collapsible group**:`<SidebarGroup collapsible>` 的 label trigger 帶 `aria-expanded` + `aria-controls` 指向 GroupContent id,SR 可朗讀展開狀態。
+- **Landmark**:`<Sidebar>` 目前渲染 `<div>`(三種 collapsible 分支皆然),**不自帶** `<nav>` 元素或 `role="navigation"`、`aria-label`。consumer 若要 page-level navigation landmark,需自行用 `<nav aria-label="Main">` 包住 `<Sidebar>`(或對導覽區塊 `<SidebarGroup>` 加 `role="navigation"`)。
+- **Active item**:`SidebarMenuButton` 帶 `id` + 命中 `activeId` 時自動加 `data-active="true"`,呈現選取底色（`bg-neutral-selected`)。**選中 × 互動疊加(2026-08-11,owner = `item-anatomy.spec.md` 同名格)**:滑鼠 hover 當前項**釘住不變**(先前無規則、靠編譯順序,現為顯式 class);鍵盤焦點停在當前項深一階 `bg-neutral-selected-focus`(游標可見)。**目前僅視覺 + `data-active` attribute,不設 `aria-current="page"`**——SR 讀不到「current page」語意。`variant="meta"` 永不參與 selection（`data-active` 永遠 false）。
+- **快捷鍵不衝突**:`Cmd+B` / `Ctrl+B` 是 industry-standard(VS Code / Linear / shadcn),DS 內建在 `SidebarProvider` 的 `window` keydown handler,判斷 `key==="b" && (metaKey||ctrlKey)` 後 `preventDefault` + toggle,避免穿透到 browser bookmark bar(`Cmd+B` 在 Safari 是 favorites)。**三道 guard(2026-07-05 D4 修)**:(1) `defaultPrevented`——app 層 editor 已處理同快捷鍵時不 double-fire;(2) `isComposing`——IME 組字中不攔;(3) 可編輯 target——`<input>` / `<textarea>` / `contentEditable` 內按 `Cmd/Ctrl+B` 不 toggle(bold 等編輯語意優先,對齊 VS Code / Linear 快捷鍵讓位可編輯區慣例)。**目前無 opt-out prop**(無 `disableShortcut`)。
+- **Collapsed accessible name(2026-07-05 D4 修)**:icon 模式 label 以 `sr-only` 視覺隱藏(非 display:none),SidebarMenuButton 對 SR 保留 accessible name(WCAG 4.1.2);Tooltip 僅 hover 提示、不供名;badge / inline actions 仍 display:none(補充資訊,供名責任在 label)。
+- **Mobile sheet focus trap**:`md` breakpoint 以下切 Sheet 模式時,Radix Dialog 自帶 focus trap + Esc dismiss(詳 sheet.spec.md)。**關閉焦點還原**:mobile Sheet 無顯式 `<SheetTrigger>`，SidebarTrigger 會直接傳入自身作為 opener；快捷鍵路徑則在 `setOpenMobile(true)` 前記錄當下聚焦元素。Sheet 關閉時透過 `onCloseAutoFocus` 還原仍連線的 opener；若 opener 已卸載則不強搶焦。
+- **Provider cardinality**:每個 document／app shell 只掛一個 SidebarProvider。多 Provider 的 local trigger 仍各自隔離，但 document-level Cmd/Ctrl+B shortcut 沒有 active-provider arbitration，不屬支援拓撲。
+- **Collapsible group**:`<SidebarGroup collapsible>` 的**尾端 chevron button**(`Collapsible.Trigger asChild` 包 `ItemInlineActionButton`)帶 `aria-expanded` + `aria-controls` 指向 GroupContent id,SR 可朗讀展開狀態(label 本身維持 `role="presentation"`,不承載 aria-expanded)。
 - **Sticky header / footer focus order**:Tab 順序按 DOM 順序 — Header → Content → Footer,SidebarTrigger 在 Pattern A/B 都位於 page top-left,Tab 第一站即可達。
 - **不使用 `SidebarMenuSub`**:避免 nested menu aria-tree 複雜度,階層交給 TreeView(`role="tree"` + `aria-level`)。
 
@@ -682,11 +686,11 @@ Item-level default / hover / active / selected / disabled **色彩**完全共用
 
 ## 邊界案例
 
-- **Disabled item**:SidebarMenuButton 走 MenuItem primitive SSOT(`disabled` prop → `text-fg-disabled` + `aria-disabled=true` + 不觸發 onClick + 鍵盤導覽自動 skip)。
-- **Loading(nav data-fetch)**:async nav tree fetch 時 consumer 應在對應 group 內渲 `<Skeleton>` line-stack(常見 3-5 條 sidebar nav skeleton 行)而非 Empty + spinner — Sidebar 是 chrome 不是 panel,loading 用 skeleton 更符合 chrome 持續存在的 affordance。對齊 Atlassian Sidebar / VS Code activity-bar idiom。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **Disabled item**:SidebarMenuButton `disabled` prop 走 native button disabled(`text-fg-disabled` + 不觸發 onClick + 不可聚焦,鍵盤導覽自動 skip);**不自動設 `aria-disabled`**——cva 另備 `aria-disabled:` 樣式,consumer 自傳 `aria-disabled`(如 asChild 非 button host)時同樣式生效。
+- **Loading(nav data-fetch)**:async nav tree fetch 時 consumer 應在對應 group 內渲 `<Skeleton>` line-stack(常見 3-5 條 sidebar nav skeleton 行)而非 Empty + spinner — Sidebar 是持續存在的 chrome 不是 panel，skeleton 能保留導覽列的空間與節奏，不讓內容載入時整個 shell 改形。
 - **Empty(no nav items)**:罕見場景(用戶無權限 / 全空 workspace)。若整個 group 無 item,consumer 應 conditional 不渲該 group(不渲空 group label);若整個 sidebar 無 item,可能該 hide sidebar(走 layout context 不渲)。不渲空白 sidebar。
 - **Dark mode / density**:Sidebar 為 chrome surface,走 chrome-header token 自動 adapt;density 預設 lock 跟隨 app density chrome token,不獨立 own。
-- **Collapsed mode(icon-only)**:已 codify(見 Sidebar collapsed mode 段);此時 label / endAction 隱藏,只留 icon + tooltip。
+- **Collapsed mode(icon-only)**:label / inline actions suffix 隱藏,只留 icon(hover tooltip 為 opt-in — 未傳 `tooltip` prop 的 collapsed button 無 hover 提示,collapsed 導覽 button 建議都傳 `tooltip`);TreeView 整區隱藏,重新看階層資料的唯一路徑 = 展開 sidebar(完整規則見「Icon 模式的行為規則」段)。
 
 ---
 
@@ -696,18 +700,17 @@ Item-level default / hover / active / selected / disabled **色彩**完全共用
 - `../DropdownMenu/dropdown-menu.spec.md` — Header / Footer 常用的下拉選單
 - `../Tabs/tabs.spec.md` — in-page secondary nav（不塞 sidebar 的子頁切換）
 - `../Menu/menu-item.spec.md` — SidebarMenuButton 的 item-layout 共用規則
-- Command palette（`components/Command/`，shadcn passthrough 無 spec）— icon 模式下的跳轉逃生艙
-- Sheet（`components/Sheet/`，shadcn passthrough 無 spec）— 暫時性側邊面板的替代
+- `../Command/command.spec.md` — Command palette，icon 模式下的跳轉逃生艙
+- `../Sheet/sheet.spec.md` — Sheet，暫時性側邊面板的替代（mobile 模式實作基礎，詳「A11y 預設」）
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `account-menu.spec.md`
+- `app-shell.spec.md`
+- `density.spec.md`
+- `header-canonical.spec.md`
 - `scroll-area.spec.md`
 - `sheet.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `app-shell.spec.md`
+- `tree-view.spec.md`