@qijenchen/design-system 0.1.0-beta.83 → 0.1.0-beta.85

package/src/components/SelectionControl/selection-item.principles.stories.tsx

@@ -62,10 +62,10 @@ export const CompositionRules: Story = {
         <p>SelectionItem 是 Family 2 reading-mode row layout primitive,由 Checkbox / RadioGroup 兩個 consumer 在「list-as-page settings」場景消費,**不直接放在 app code**:</p>
 
         <h4>Pattern 1 — Checkbox + SelectionItem(多選 settings list)</h4>
-        <p>多選 + 每個 row 大塊 description / icon → <LinkTo kind="Design System/Components/Checkbox/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Checkbox</span></LinkTo> 內部消費 SelectionItem(prefix 放 Checkbox indicator / content 放 label + description)。對齊 Notion 通知設定 / Slack notification preferences idiom。</p>
+        <p>多選 + 每個 row 大塊 description / icon → <LinkTo kind="Design System/Components/Checkbox/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Checkbox</span></LinkTo> 內部消費 SelectionItem(control 放 Checkbox indicator / prefix 可選放 icon 或 avatar / content 放 label + description)。對齊 Notion 通知設定 / Slack notification preferences idiom。</p>
 
         <h4>Pattern 2 — RadioGroup + SelectionItem(單選 plan picker)</h4>
-        <p>單選 + 每個 row 大塊描述(plan tier / tier features)→ <LinkTo kind="Design System/Components/RadioGroup/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">RadioGroup</span></LinkTo> 內部消費 SelectionItem(prefix 放 Radio indicator / content 多行)。對齊 Stripe plan picker / Linear pricing tier idiom。</p>
+        <p>單選 + 每個 row 大塊描述(plan tier / tier features)→ <LinkTo kind="Design System/Components/RadioGroup/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">RadioGroup</span></LinkTo> 內部消費 SelectionItem(control 放 Radio indicator / prefix 可選放 icon 或 avatar / content 多行)。對齊 Stripe plan picker / Linear pricing tier idiom。</p>
 
         <h4>Field 包覆規則</h4>
         <p>Checkbox / RadioGroup 在 form context 內 → 外層用 <LinkTo kind="Design System/Components/Field/展示" name="垂直"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Field</span></LinkTo> 統一 label + helper + error(對齊 Field 4-Family Layout 慣例)。Field 處理 wrapper level 的 ARIA + error,SelectionItem 處理 row level 的 layout。</p>

package/src/components/SelectionControl/selection-item.spec.md

@@ -26,13 +26,13 @@ SelectionItem 是 **Checkbox 和 RadioGroup 共用的 item 佈局 primitive**—
 
 **實作基礎**：自建 internal primitive——純視覺佈局 + padding 公式，無 external primitive base。
 
-**Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」章節的 reading-mode 規格。SelectionItem 是 Family 2 的 SelectionItem variant：prefix 放 Checkbox/Radio indicator 而非 icon/avatar。
+**Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」章節的 reading-mode 規格。SelectionItem 是 Family 2 的 SelectionItem variant：`control` slot 放 Checkbox/Radio indicator，`prefix` slot 專供 icon/avatar——兩者是獨立 slot、可並存（如 `<Checkbox icon>` 同時有 indicator + icon，見「結構」段的 3-slot 圖）。
 
 ---
 
 ## 何時用 / 何時不用
 
-**SelectionControl 是 internal primitive**——不直接使用，透過 Checkbox / RadioGroup 消費。
+**SelectionItem 是 internal primitive**——不直接使用，透過 Checkbox / RadioGroup 消費。**裸用禁止；內部由 Checkbox / RadioGroup 組合消費允許**——consumer 與展示範例一律走公開 `<Checkbox label>` / `<RadioGroupItem label>` 路徑（自動 wire id/htmlFor）；primitive 自家 stories 展示自身 API 為唯一裸用豁免。
 
 **icon / avatar prefix 消費路徑(2026-06-12 M30 修)**:`<Checkbox icon={...}>` / `<RadioGroupItem avatar={...}>` 直接轉發本 primitive 的既有槽(本檔「3-slot 結構」+ selection-item.tsx jsDoc 為對齊規則 SSOT)——不需也不准裸用 `<SelectionItem>`。
 
@@ -85,7 +85,7 @@ Checkbox 和 Radio 視覺幾乎完全一致（差異只在形狀 `rounded-md` vs
 ## 禁止事項
 
 - ❌ 直接在 JSX 用 `<SelectionItem>`——透過 Checkbox / Radio 消費
-- ❌ 在 Checkbox / Radio 之外複製 SelectionItem 邏輯——共用源頭一定是 SelectionControl
+- ❌ 在 Checkbox / Radio 之外複製 SelectionItem 邏輯——共用源頭一定是 SelectionItem（`SelectionControl/` 僅為概念群組資料夾名，見「關於資料夾命名」note）
 - ❌ 改動 `py` padding 公式只針對某一 variant——Checkbox 和 Radio 必須同步
 
 ---

package/src/components/SelectionControl/selection-item.stories.tsx

@@ -114,19 +114,19 @@ export const WithPrefixAvatarBlock: Story = {
       </p>
       <SelectionItem
         control={<Checkbox defaultChecked />}
-        avatar={{ alt: 'Ada Chen', color: 'indigo' }}
+        avatar={{ src: 'https://i.pravatar.cc/64?u=ada-chen', alt: 'Ada Chen', color: 'indigo' }}
         label="Ada Chen"
         description="Design Engineer · Frontend team"
       />
       <SelectionItem
         control={<Checkbox />}
-        avatar={{ alt: '張美真', color: 'magenta' }}
+        avatar={{ src: 'https://i.pravatar.cc/64?u=zhang-meizhen', alt: '張美真', color: 'magenta' }}
         label="張美真"
         description="Product Designer · Platform team"
       />
       <SelectionItem
         control={<Checkbox defaultChecked />}
-        avatar={{ alt: '林伯彥', color: 'green' }}
+        avatar={{ src: 'https://i.pravatar.cc/64?u=lin-boyan', alt: '林伯彥', color: 'green' }}
         label="林伯彥"
         description="Staff Engineer · Infra team"
       />

package/src/components/Separator/separator.spec.md

@@ -78,7 +78,7 @@ Consumer 在 JSX 裡明確放置分隔線的場景：
 
 ## 邊界案例
 
-- **Vertical 方向**：`h-full` 取父容器高度——父容器無確定高度（auto）時 separator 高度為 0、不可見；需父容器有確定高度或 flex row 的 stretch 對齊
+- **Vertical 方向**：`h-full` 取父容器高度——父容器無確定高度（auto）時 separator 高度為 0、不可見；需父容器有確定高度或 flex row 的 stretch 對齊。**例外(toolbar / action region 群組分隔)**:實務上一律**縮短高度**(`h-6 mx-1` 等),不 full-height — 幾何 SSOT → `patterns/action-bar/action-bar.spec.md`「分隔線幾何」段(2026-07-08 codify;版面切分 divider 不適用、零 gap)
 - **空容器 / 0 寬**：horizontal `w-full` 隨父寬，父寬為 0 時無可見線；Separator 不自帶 min-width / min-height
 - **厚度固定 1px**（`h-px` / `w-px`）、非互動無 hover / focus——無 size / state 變體（見下「為何無 …」段）
 
@@ -88,7 +88,7 @@ Separator 是**視覺分隔 primitive**(一條 1px 線),結構極薄:
 
 - **無 Inspector**:Separator 唯一變因是 `orientation`(horizontal / vertical),已在 `TokenMatrix` 對照呈現。互動 Inspector 無進一步可調 prop。
 - **無 ColorMatrix**:Separator 固定用 `--divider` token(比 border 更淡的語意分隔色),dark mode 由 semantic token 自動切換。無變體。加 color variant 會誤用成「狀態訊號」(分隔應是中性的)。
-- **無 SizeMatrix**:Separator 固定 1px 厚度(線應該是線),長度由 container 決定(`w-full` / `h-full`)。無 sm/md/lg tier。
+- **無 SizeMatrix**:Separator 固定 1px 厚度(線應該是線),長度由 container 決定(`w-full` / `h-full`;toolbar 群組分隔例外縮短,見「邊界案例」+ action-bar.spec.md「分隔線幾何」)。無 sm/md/lg tier。
 - **無 StateBehavior**:非互動元件,無 hover / focus / active / selected / disabled。
 
 對應 anatomy story:保留 `Overview` + `TokenMatrix`(horizontal × vertical + `--divider` vs `--border` 用法對照)。

package/src/components/Separator/separator.stories.tsx

@@ -1,16 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react'
-import { MoreVertical, Pencil, Copy, Trash2, User, Bell, Shield } from 'lucide-react'
+import { User, Bell, Shield } from 'lucide-react'
 import { Separator } from './separator'
 import { DescriptionList, DescriptionItem } from '@/design-system/components/DescriptionList/description-list'
 import { Button } from '@/design-system/components/Button/button'
 import { MenuItem } from '@/design-system/components/Menu/menu-item'
-import {
-  DropdownMenu,
-  DropdownMenuTrigger,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuSeparator,
-} from '@/design-system/components/DropdownMenu/dropdown-menu'
 
 const meta: Meta<typeof Separator> = {
   title: 'Design System/Components/Separator/展示',
@@ -76,25 +69,11 @@ export const Vertical: Story = {
   ),
 }
 
-/* ── 在 DropdownMenu 內 ─────────────────────────────────────────────── */
-export const InDropdownMenu: Story = {
-  name: '在 DropdownMenu 內',
-  render: () => (
-    <DropdownMenu>
-      <DropdownMenuTrigger asChild>
-        <Button variant="tertiary" size="sm" startIcon={MoreVertical}>
-          更多操作
-        </Button>
-      </DropdownMenuTrigger>
-      <DropdownMenuContent align="start">
-        <DropdownMenuItem startIcon={Pencil}>重新命名</DropdownMenuItem>
-        <DropdownMenuItem startIcon={Copy}>複製連結</DropdownMenuItem>
-        <DropdownMenuSeparator />
-        <DropdownMenuItem startIcon={Trash2}>刪除</DropdownMenuItem>
-      </DropdownMenuContent>
-    </DropdownMenu>
-  ),
-}
+// @story-trait-rationale: InDropdownMenu retired 2026-07-14 per audit Dim 24 —
+//   同一「重新命名/複製連結/分隔/刪除」選單完整重複 principles DecorativeSemanticRule
+//   (separator.principles.stories.tsx)首例;且 menu 內分隔屬 DropdownMenuSeparator
+//   (DropdownMenu owns 該 primitive,見 separator.spec.md 近親分界),非 consumer
+//   手動放置 Separator 的場景 — canonical 範例由 DropdownMenu 展示層 owns。
 
 /* ── 在 DescriptionList 之間 ────────────────────────────────────────── */
 export const BetweenSections: Story = {

package/src/components/Sheet/sheet.anatomy.stories.tsx

@@ -238,7 +238,7 @@ export const StateBehavior: Story = {
     <div className="flex flex-col gap-8">
       <div>
         <H3>開啟 / 關閉</H3>
-        <Desc>Radix 提供 data-state 切換 + DS Tailwind animate 驅動進離場動畫（slide-in-from-側邊 + fade-in overlay，300ms；sheet.tsx L69-78），離場鏡像。Modal 狀態鎖 body scroll。</Desc>
+        <Desc>Radix 提供 data-state 切換 + DS Tailwind animate 驅動進離場動畫（panel slide-in-from-側邊 250ms，consume surfaceMotion / --motion-duration-surface；overlay fade 沿用 tw-animate-css 預設 約 150ms；sheet.tsx sheetVariants），離場鏡像。Modal 狀態鎖 body scroll。</Desc>
         <ul className="text-caption text-fg-muted list-disc pl-5 space-y-1">
           <li>點擊 trigger → 開啟（slide-in from `side`）</li>
           <li>點擊 overlay → 關閉（default；可用 onPointerDownOutside preventDefault 阻止）</li>

package/src/components/Sheet/sheet.principles.stories.tsx

@@ -82,7 +82,7 @@ export const UsageGuidance: Story = {
           <LinkTo kind="Design System/Components/Sheet/展示" name="編輯成員詳情（右側滑入）"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">編輯成員詳情（右側滑入）</span></LinkTo>
         </li>
       </ul>
-      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見本頁下方「vs 近親」對照段)。</p>
     </div>
 
       {/* vs 近親 — VsDialogRule — 原 VsDialogRule */}

package/src/components/Sheet/sheet.spec.md

@@ -104,7 +104,7 @@ Sheet 為容器,內容由 consumer 決定;focus trap + Escape close + `aria-labe
 ## 邊界案例
 
 - **Disabled**:Sheet 本身無 disabled state(非互動 control,是 surface container);trigger Button 由 consumer 控 disabled。
-- **Loading(panel content loading)**:Sheet 為純容器,不獨立 own loading state。Async body 場景由 consumer 在 body slot 渲 `<Empty icon={<CircularProgress size={48}/>}/>`(對齊 `empty.spec.md:167` loading compose SSOT)或 `<Skeleton>` line-stack 取代 content,不開 / 不關 Sheet 即可。
+- **Loading(panel content loading)**:Sheet 為純容器,不獨立 own loading state。Async body 場景由 consumer 在 body slot 渲 `<Empty icon={<CircularProgress size={48}/>}/>`(對齊 `empty.spec.md:168` loading compose SSOT)或 `<Skeleton>` line-stack 取代 content,不開 / 不關 Sheet 即可。
 - **Empty(no content)**:Sheet 必含 title(`aria-labelledby` 強制要求);body 為空時 consumer 應渲 `<Empty>` placeholder,不渲空白 panel。
 - **Scroll(body 內容超過視口高度)**:`SheetBody` = `<ScrollArea>`(`flex-1 min-h-0`),超高內容在 body 內部捲動,header / footer 固定不動;consumer 不需自寫 `overflow-y-auto`。
 - **誤嵌套降級(nested Sheet)**:禁止事項已禁 nested;若 consumer 不慎嵌套,Radix 的 Esc 與 focus trap 只作用於**最上層** layer(DismissableLayer 只 dismiss highest layer;FocusScope stack 最新 scope active),關閉由上而下逐層。
@@ -132,7 +132,7 @@ Sheet 為容器,內容由 consumer 決定;focus trap + Escape close + `aria-labe
 - Esc — 關閉
 - Shift+Tab — 反向 focus 循環
 
-**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+**Focus**:Radix primitive 自管 focus trap / visible ring(per design-system focus-visible canonical)。**Restoration 例外(2026-07-14)**:Radix 內建「關閉回焦 trigger」依賴 `SheetTrigger` 的 triggerRef;**controlled-without-trigger**(如 AppShellAside 手機模式)triggerRef=null + 內建 preventDefault 會讓焦點掉 `<body>` — 必自建 `onCloseAutoFocus` snapshot 還原(先例:AppShellAside app-shell.tsx / DatePicker Range date-picker.tsx:1061;WCAG 2.4.3)。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 

package/src/components/Sheet/sheet.tsx

@@ -12,6 +12,7 @@ import {
 } from "@/design-system/patterns/overlay-surface/overlay-surface"
 import { Button } from "@/design-system/components/Button/button"
 import { ScrollArea } from "@/design-system/components/ScrollArea/scroll-area"
+import { surfaceMotion } from "@/design-system/tokens/motion/overlay-motion"
 
 /**
  * Sheet — **右側 Dialog primitive**(給消費者的 canonical)。
@@ -67,8 +68,9 @@ SheetOverlay.displayName = SheetPrimitive.Overlay.displayName
 const sheetVariants = cva(
   // 核心容器 — 無 padding(由 SheetBody / SheetHeader / SheetFooter 自理 padding,
   // 對齊 overlay-surface pattern + Dialog canonical)
-  // Animation canonical:300ms 雙向一致(D4 audit:500ms 太久 sluggish)+ motion-reduce 豁免
-  "fixed z-50 flex flex-col bg-surface-raised shadow-[var(--elevation-200)] transition ease-in-out data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:duration-300 data-[state=open]:duration-300 motion-reduce:transition-none motion-reduce:data-[state=open]:duration-0 motion-reduce:data-[state=closed]:duration-0",
+  // Animation canonical:panel = surfaceMotion 250ms(--motion-duration-surface)雙向一致
+  // (D4 audit:500ms 太久 sluggish)+ motion-reduce 豁免
+  `fixed z-50 flex flex-col bg-surface-raised shadow-[var(--elevation-200)] transition ease-in-out data-[state=open]:animate-in data-[state=closed]:animate-out ${surfaceMotion}`,
   {
     variants: {
       side: {
@@ -91,7 +93,9 @@ interface SheetContentProps
     VariantProps<typeof sheetVariants> {}
 
 // AutoFocus canonical(對齊 Dialog / Material / Polaris)— 見 dialog.tsx handleOpenAutoFocus 註解
-const handleSheetOpenAutoFocus = (e: Event) => {
+/** @internal DS 預設 open-focus(首個 body 互動元素)。consumer 傳自訂 onOpenAutoFocus 會覆寫
+ *  本預設({...props} 在後),需自訂前置行為(如 AppShellAside opener snapshot)時 import 接力呼叫。 */
+export const handleSheetOpenAutoFocus = (e: Event) => {
   e.preventDefault()
   const content = e.currentTarget as HTMLElement
   const firstBodyTarget = content.querySelector<HTMLElement>(
@@ -123,7 +127,7 @@ const SheetContent = React.forwardRef<
 SheetContent.displayName = SheetPrimitive.Content.displayName
 
 // ── SheetHeader:SurfaceHeader + Close X(對齊 DialogHeader canonical)──────────
-// 2026-05-18 audit gap fix:type 對齊 SurfaceHeaderProps,withTabs / lockDensity expose
+// 2026-05-18 audit gap fix:type 對齊 SurfaceHeaderProps,withTabs / tabsSlot expose
 // 給 consumer(per header-canonical.spec.md W1 跨 6 consumer 同契約)。Spread 早 forward
 // 過去,只是 TS type 沒 expose 導致 consumer 不能 type-safe 用 `<SheetHeader withTabs>`。
 const SheetHeader = React.forwardRef<
@@ -152,7 +156,7 @@ SheetHeader.displayName = "SheetHeader"
 //
 // ── List-as-region 場景(menu / nav / settings list)──
 // 不再提供 `flush` variant(2026-05-01 移除)。canonical = consumer 用 className override:
-// `<SheetBody className="!px-0 !pt-0 !pb-0"><div className="py-2">{items}</div></SheetBody>`
+// `<SheetBody className="!px-0 !pt-0 !pb-0"><div className="py-2">{items}</div></SheetBody>`  ← @tabs-content-gap-ok: JSDoc 文件範例(list-as-region canonical,非 tabs !pt-0 hack;對齊 dialog.tsx 同款 marker)
 // 詳 DialogBody comment + `tokens/layoutSpace/layoutSpace.spec.md`「List-as-region in overlay body」
 // `className` forward 到 **inner content div**(非外層 ScrollArea wrapper)——
 // consumer `<SheetBody className="flex flex-col gap-X">` 期望作用於 children 排列;

package/src/components/Sidebar/sidebar.anatomy.stories.tsx

@@ -17,6 +17,7 @@ import {
 } from './sidebar'
 import { ItemAvatar } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { Avatar } from '@/design-system/components/Avatar/avatar'
+import { ChromeHeader } from '@/design-system/patterns/header-canonical/chrome-header'
 
 const meta: Meta = {
   title: 'Design System/Components/Sidebar/設計規格',
@@ -115,7 +116,7 @@ const SidebarPreview = ({
               <SidebarMenuItem>
                 <SidebarMenuButton asChild>
                   <button type="button">
-                    <ItemAvatar alt="Alan Chen" color="blue" />
+                    <ItemAvatar src="https://i.pravatar.cc/48?u=EMP-1001" alt="Alan Chen" color="blue" />
                     <span data-sidebar="menu-label" className="min-w-0 flex-1 truncate">Alan Chen</span>
                   </button>
                 </SidebarMenuButton>
@@ -139,7 +140,7 @@ export const Overview: Story = {
       <div className="flex flex-col gap-2">
         <H3>結構（Anatomy）</H3>
         <Desc>
-          Sidebar 是三段式結構——SidebarHeader（固定高）、SidebarContent（可捲動）、SidebarFooter（固定高）。
+          Sidebar 是三段式結構——SidebarHeader（固定高 `--chrome-header-height`）、SidebarContent（可捲動）、SidebarFooter（高度由內容決定，shrink-0 靠底 + border-t）。
           Content 內放一或多個 SidebarGroup，每個 group 有 py-2 呼吸空間 + 自動內縮分隔線。
           Group 內放 SidebarMenu（扁平 row）或 TreeView（階層 row），兩者共用 item-layout row geometry。
         </Desc>
@@ -651,10 +652,13 @@ export const StateBehavior: Story = {
                 </SidebarContent>
               </Sidebar>
               <div className="flex-1 flex flex-col">
-                <div className="h-10 border-b border-divider flex items-center px-3 gap-2">
+                {/* 2026-07-14 audit Dim 68:主內容 header 消費 ChromeHeader(原手刻 h-10=40px 破壞
+                    與 SidebarHeader 共用 --chrome-header-height 的兩側 chrome 對齊 — sidebar.spec.md
+                    「Chrome header 不跟 size 變」段;對齊 sidebar.stories.tsx PageContent baseline)*/}
+                <ChromeHeader className="bg-surface">
                   <SidebarTrigger />
-                  <span className="text-caption text-fg-muted">Dashboard</span>
-                </div>
+                  <span className="text-body-lg font-medium">Dashboard</span>
+                </ChromeHeader>
                 <div className="flex-1 px-4 py-3 text-caption text-fg-muted">
                   點 SidebarTrigger 或按 Cmd/Ctrl+B,觀察 sidebar 縮到 48px(icon mode)。再按一次展開。
                 </div>
@@ -668,7 +672,7 @@ export const StateBehavior: Story = {
       <div className="flex flex-col gap-3">
         <span className="text-caption font-medium text-fg-secondary">行為 3:Icon mode 時 label 隱藏 → Tooltip 代償</span>
         <Desc>
-          collapse 到 icon mode 時 label 文字隱藏,滑鼠 hover menu button 自動出現 Tooltip(顯示 label)補償 — 對齊 Linear / GitHub 慣例,避免 icon-only 狀態讓使用者忘記每個 icon 的含義。SidebarMenuButton 內建此行為(`tooltip` prop)。
+          collapse 到 icon mode 時 label 文字隱藏,滑鼠 hover menu button(**需 per-button 傳 `tooltip` prop**,opt-in)才出現 Tooltip(顯示 label)補償 — 對齊 Linear / GitHub 慣例,避免 icon-only 狀態讓使用者忘記每個 icon 的含義。SidebarMenuButton 內建此行為(`tooltip` prop)。
         </Desc>
       </div>
 
@@ -678,9 +682,9 @@ export const StateBehavior: Story = {
         <ul className="text-caption text-fg-secondary space-y-1.5 ml-4 list-disc">
           <li>`collapsible="offcanvas"` 用於主內容為主的 app(sidebar 是啟動器,使用者常關);`collapsible="icon"` 用於深度導覽 app(sidebar 是常駐工作區)。</li>
           <li>open state 寫 cookie `sidebar_state`(7 天 max-age);Provider 只寫不讀,還原由 consumer 讀 cookie 傳 `defaultOpen`(避免 SSR hydration flash)。</li>
-          <li>Mobile(&lt;768px)一律走 Sheet overlay,不受 `collapsible` prop 影響——小螢幕 sidebar 永遠不佔固定空間。</li>
+          <li>Mobile(&lt;768px)時 `offcanvas`(預設)/ `icon` 走 Sheet overlay,小螢幕不佔固定空間;**`collapsible="none"` 例外**——`none` 在 `isMobile` 判斷前提前 return,mobile 下仍是固定寬度側欄,不進 Sheet。</li>
           <li>Icon mode 下 active item 的 `bg-neutral-selected` 仍然顯示,但 label 不可見——提供最小視覺指引讓使用者知道「當前在哪」。</li>
-          <li>Cmd+B / Ctrl+B 全域快捷鍵由 SidebarProvider 監聽,任何 focus 位置都可觸發——目前未排除文字輸入框,在 input / textarea 內按下仍會 toggle 並攔掉預設行為(無 disableShortcut opt-out)。</li>
+          <li>Cmd+B / Ctrl+B 全域快捷鍵由 SidebarProvider 監聽,但有三道 guard(2026-07-05 D4 修):`defaultPrevented`(app editor 已處理同鍵時不 double-fire)/ `isComposing`(IME 組字中不攔)/ 可編輯 target(`input` / `textarea` / `contentEditable` 內按 Cmd/Ctrl+B **不 toggle**,讓位給 bold 等編輯語意)。仍無 `disableShortcut` opt-out。</li>
         </ul>
       </div>
     </div>
@@ -719,7 +723,7 @@ export const ChromeTokens: Story = {
             <tr>
               <Td><TkVal token="--sidebar-width-icon" value="calc(2 × loose + icon)" /></Td>
               <Td mono>calc()</Td>
-              <Td>icon 收合模式寬度(2026-05-21 v3 改 geometry formula;md=48 / lg=64,保證 icon center x 展開/收合一致)</Td>
+              <Td>icon 收合模式寬度(2026-05-21 v3 改 geometry formula;md = 2×16+16 = 48 / lg = 2×24+20 = 68,保證 icon center x 展開/收合一致)</Td>
             </tr>
             <tr>
               <Td><TkVal token="--sidebar-menu-icon-size" value="1rem (16px)" /></Td>
@@ -738,7 +742,7 @@ export const ChromeTokens: Story = {
       <div className="flex flex-col gap-2">
         <H3>Chrome header token(共享)</H3>
         <Desc>
-          SidebarHeader / SidebarFooter / 主內容 page header 都用這個 token,確保跨元件同高對齊。Density-responsive。
+          SidebarHeader / 主內容 page header 都用這個 token,確保跨元件同高對齊。Density-responsive。（SidebarFooter 為 content-based，高度由內容決定，不消費此 token。）
         </Desc>
         <table className="min-w-full text-left border-collapse">
           <thead>
@@ -750,7 +754,7 @@ export const ChromeTokens: Story = {
           <tbody>
             <tr>
               <Td mono>--chrome-header-height</Td>
-              <Td>Sidebar header / footer 固定高度；density 解析值見 uiSize.spec.md</Td>
+              <Td>Sidebar header 固定高度（footer 為 content-based，不消費此 token）；density 解析值見 uiSize.spec.md</Td>
             </tr>
           </tbody>
         </table>
@@ -766,7 +770,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"-   收合切換鍵：Cmd+B(Mac)/ Ctrl+B(Windows)是業界慣例(VS Code / Linear / shadcn 都用),Sidebar 內建並會攔下這組鍵,避免穿透到瀏覽器書籤列。任何焦點位置都能觸發;目前未排除文字輸入框——在 input / textarea 內按下仍會 toggle(無 disableShortcut opt-out)。\n\n-   收合按鈕:SidebarTrigger 內建 aria-label「切換側邊欄」,讓螢幕報讀使用者知道按鈕用途;consumer 可傳 aria-label 覆寫(i18n)。SidebarGroupLabel 的收合 chevron 另有 toggleAriaLabel prop(預設「展開或收合」)。\n\n-   當前項目:選中的 menu item 帶 data-active,呈現選取底色(bg-neutral-selected)作為視覺指引;即使收合成 icon-only 模式,選取底色仍然保留,使用者一眼知道現在在哪一頁。\n\n-   手機尺寸:768px 以下自動切換成從旁滑出的抽屜(Sheet),內建焦點鎖定、Esc 關閉、關閉後焦點回到觸發按鈕。"}</p>
+      <p className="whitespace-pre-line">{"-   收合切換鍵：Cmd+B(Mac)/ Ctrl+B(Windows)是業界慣例(VS Code / Linear / shadcn 都用),Sidebar 內建並會攔下這組鍵,避免穿透到瀏覽器書籤列。任何焦點位置都能觸發;任何焦點位置都能觸發,但有三道 guard(2026-07-05 D4):app 已處理同鍵(defaultPrevented)/ IME 組字中(isComposing)/ 可編輯 target(input / textarea / contentEditable 內讓位給 bold 等編輯語意)時不 toggle。仍無 disableShortcut opt-out。\n\n-   收合按鈕:SidebarTrigger 內建 aria-label「切換側邊欄」,讓螢幕報讀使用者知道按鈕用途;consumer 可傳 aria-label 覆寫(i18n)。SidebarGroupLabel 的收合 chevron 另有 toggleAriaLabel prop(預設「展開或收合」)。\n\n-   當前項目:選中的 menu item 帶 data-active,呈現選取底色(bg-neutral-selected)作為視覺指引;即使收合成 icon-only 模式,選取底色仍然保留,使用者一眼知道現在在哪一頁。\n\n-   手機尺寸:768px 以下自動切換成從旁滑出的抽屜(Sheet),內建焦點鎖定、Esc 關閉;關閉後焦點還原走 Radix FocusScope 預設(還原到開啟前聚焦元素),因 mobile Sheet 無顯式 SheetTrigger,不保證回到觸發按鈕。"}</p>
     </div>
   ),
 }

package/src/components/Sidebar/sidebar.principles.stories.tsx

@@ -324,10 +324,10 @@ export const GroupHeaderRules: Story = {
                   <SidebarGroupContent>
                     <SidebarMenu>
                       <SidebarMenuItem>
-                        <SidebarMenuButton startIcon={Folder}>Project A</SidebarMenuButton>
+                        <SidebarMenuButton id="web-app" startIcon={Folder}>Web App</SidebarMenuButton>
                       </SidebarMenuItem>
                       <SidebarMenuItem>
-                        <SidebarMenuButton startIcon={Folder}>Project B</SidebarMenuButton>
+                        <SidebarMenuButton id="mobile-app" startIcon={Folder}>Mobile App</SidebarMenuButton>
                       </SidebarMenuItem>
                     </SidebarMenu>
                   </SidebarGroupContent>
@@ -373,13 +373,15 @@ export const SettingsScenario: Story = {
               若子頁等重要且需一鍵直達,用 SidebarGroupLabel 當純視覺分段標題,子項全部是獨立頂層 SidebarMenuItem。
               少見,只在子項確實高頻使用時才用。
             </Desc>
-            <MiniSidebar>
+            {/* 導覽項必帶穩定 id(sidebar.spec.md「禁止:SidebarMenuButton 不傳 id」)—
+                id 進 SidebarProvider 單一 activeId selection 模型,漏 id = 啞 item 無法 active。 */}
+            <MiniSidebar activeId="settings-general">
               <SidebarContent>
                 <SidebarGroup>
                   <SidebarGroupContent>
                     <SidebarMenu>
-                      <SidebarMenuItem><SidebarMenuButton startIcon={Inbox}>Inbox</SidebarMenuButton></SidebarMenuItem>
-                      <SidebarMenuItem><SidebarMenuButton startIcon={Folder}>Projects</SidebarMenuButton></SidebarMenuItem>
+                      <SidebarMenuItem><SidebarMenuButton id="inbox" startIcon={Inbox}>Inbox</SidebarMenuButton></SidebarMenuItem>
+                      <SidebarMenuItem><SidebarMenuButton id="projects" startIcon={Folder}>Projects</SidebarMenuButton></SidebarMenuItem>
                     </SidebarMenu>
                   </SidebarGroupContent>
                 </SidebarGroup>
@@ -387,9 +389,9 @@ export const SettingsScenario: Story = {
                   <SidebarGroupLabel>Settings</SidebarGroupLabel>
                   <SidebarGroupContent>
                     <SidebarMenu>
-                      <SidebarMenuItem><SidebarMenuButton startIcon={Settings}>General</SidebarMenuButton></SidebarMenuItem>
-                      <SidebarMenuItem><SidebarMenuButton startIcon={Users}>Team</SidebarMenuButton></SidebarMenuItem>
-                      <SidebarMenuItem><SidebarMenuButton startIcon={FileText}>Billing</SidebarMenuButton></SidebarMenuItem>
+                      <SidebarMenuItem><SidebarMenuButton id="settings-general" startIcon={Settings}>General</SidebarMenuButton></SidebarMenuItem>
+                      <SidebarMenuItem><SidebarMenuButton id="settings-team" startIcon={Users}>Team</SidebarMenuButton></SidebarMenuItem>
+                      <SidebarMenuItem><SidebarMenuButton id="settings-billing" startIcon={FileText}>Billing</SidebarMenuButton></SidebarMenuItem>
                     </SidebarMenu>
                   </SidebarGroupContent>
                 </SidebarGroup>

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

@@ -142,7 +142,7 @@ Sidebar 有兩種正交的內容形態，consumer 嚴格擇一或混用：
 
 | 形態 | 元件 | 深度 | 數量 | Icon 模式 |
 |------|------|------|------|----------|
-| **扁平導覽** | `SidebarMenu` | **嚴格 1 層** | **有限可列舉** | ✅ 顯示 icon + tooltip |
+| **扁平導覽** | `SidebarMenu` | **嚴格 1 層** | **有限可列舉** | ✅ 顯示 icon(hover tooltip 為 opt-in,需 per-button 傳 `tooltip` prop) |
 | **階層樹** | `TreeView` | 任意 | 任意 | ❌ 整區隱藏 |
 
 ### 判斷規則
@@ -191,7 +191,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 整段隱藏。
 
 ---
 
@@ -241,7 +241,7 @@ 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`「Scope 例外:Chrome header 不是 row context」段。
 - Button: `size="sm"` 或 `size="md"`
@@ -487,9 +487,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 用法)
@@ -539,7 +539,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 傳遞是標準做法。
 
 ---
 
@@ -594,7 +594,9 @@ 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 開啟狀態**不持久化**。
 
@@ -616,7 +618,7 @@ Sheet 開啟狀態**不持久化**。
 | Token | 預設值 | 用途 |
 |-------|--------|------|
 | `--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=48 / lg=64,跟 chrome-header-height 解耦)|
+| `--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 寬度 |
 
@@ -671,10 +673,6 @@ 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 / 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。
@@ -687,8 +685,8 @@ Item-level default / hover / selected / disabled **色彩**完全共用 item-ana
 - **Active item**:`SidebarMenuButton` 帶 `id` + 命中 `activeId` 時自動加 `data-active="true"`,呈現選取底色（`bg-neutral-selected`)。**目前僅視覺 + `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 + restore focus to trigger(詳 sheet.spec.md)。
-- **Collapsible group**:`<SidebarGroup collapsible>` 的 label trigger 帶 `aria-expanded` + `aria-controls` 指向 GroupContent id,SR 可朗讀展開狀態。
+- **Mobile sheet focus trap**:`md` breakpoint 以下切 Sheet 模式時,Radix Dialog 自帶 focus trap + Esc dismiss(詳 sheet.spec.md)。**關閉焦點還原**:mobile Sheet **無顯式 `<SheetTrigger>`**(open state 由外部 `SidebarTrigger` → `setOpenMobile` 控制,非 Radix DialogTrigger),故關閉後焦點還原走 Radix FocusScope 預設(還原到開啟前的聚焦元素),**不保證**回到 `SidebarTrigger`;若需確定性還原,consumer 應把觸發 button 與 Sheet 綁成 `SheetTrigger`。
+- **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`)。
 
@@ -700,7 +698,7 @@ Item-level default / hover / selected / disabled **色彩**完全共用 item-ana
 - **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 -->
 - **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)**:label / inline actions suffix 隱藏,只留 icon + tooltip;TreeView 整區隱藏,重新看階層資料的唯一路徑 = 展開 sidebar(完整規則見「Icon 模式的行為規則」段)。
+- **Collapsed mode(icon-only)**:label / inline actions suffix 隱藏,只留 icon(hover tooltip 為 opt-in — 未傳 `tooltip` prop 的 collapsed button 無 hover 提示,collapsed 導覽 button 建議都傳 `tooltip`);TreeView 整區隱藏,重新看階層資料的唯一路徑 = 展開 sidebar(完整規則見「Icon 模式的行為規則」段)。
 
 ---
 

package/src/components/Sidebar/sidebar.stories.tsx

@@ -87,13 +87,14 @@ const UserFooter = () => (
       <SidebarMenuButton asChild>
         <div role="group" aria-label="當前使用者">
           <ItemAvatar
+            src="https://i.pravatar.cc/48?u=EMP-1001"
             alt="Alan Chen"
             color="blue"
             hoverCard={
               <ProfileCard
                 name="Alan Chen"
                 subtitle="Design｜D-0042｜EMP-1001"
-                avatar={{ alt: 'Alan Chen', color: 'blue' }}
+                avatar={{ src: 'https://i.pravatar.cc/80?u=EMP-1001', alt: 'Alan Chen', color: 'blue' }}
                 status="online"
                 statusMessage="Out of Office: Back on Monday!"
                 actions={<ProfileCardDefaultActions />}
@@ -258,8 +259,9 @@ export const MixedContent: Story = {
               </SidebarGroupContent>
             </SidebarGroup>
 
-            {/* User data:TreeView,icon 模式整區隱藏。
-                `collapsible` 讓整個 group 可收合——label 變 trigger + 自動 chevron,
+            {/* User data:TreeView,icon 模式整區隱藏(下方 group 手動加 group-data-[collapsible=icon]:hidden)。
+                `collapsible` 讓整個 group 可收合——label 尾端自動加 chevron button 作為
+                Collapsible.Trigger(label 本身維持 presentation div,不升格為 button),
                 content 用 Radix Collapsible 包起來。
                 群組之間的分隔線由 SidebarGroup 的 [&+&]:before 自動處理。 */}
             <SidebarGroup collapsible className="group-data-[collapsible=icon]:hidden">
@@ -486,10 +488,9 @@ export const IntegrationSidebar: Story = {
           }
           description={
             <>
-              <code className="text-caption px-1 bg-neutral-hover rounded">SidebarProvider uniformPrefix</code>
-              {' '}opt-in 後,CSS :has() 偵測整個 sidebar 子樹的混用 prefix,nav icon(16px)
-              和 brand logo(24px)在 24px 固定槽內共同對齊,兩種 label x 完全一致。Notion /
-              Raycast / Linear integrations 的混用模式。預設關閉(school A,explicit 立場)。
+              開啟 <code className="text-caption px-1 bg-neutral-hover rounded">uniformPrefix</code>
+              {' '}後,icon 導覽項與帶 logo 的整合項會對齊到同一條左緣,讓文字起點一致
+              (如 Notion / Raycast / Linear 的整合區)。預設關閉。
             </>
           }
         />