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

package/src/components/Sidebar/sidebar.tsx

@@ -73,9 +73,10 @@ type SidebarContextProps = {
   open: boolean
   setOpen: (open: boolean) => void
   openMobile: boolean
-  setOpenMobile: (open: boolean) => void
+  setOpenMobile: (open: boolean | ((current: boolean) => boolean), opener?: HTMLElement) => void
+  mobileOpenerRef: React.MutableRefObject<HTMLElement | null>
   isMobile: boolean
-  toggleSidebar: () => void
+  toggleSidebar: (opener?: HTMLElement) => void
   // 全 sidebar 共用的 size(sm/md/lg)——透過 SidebarProvider 一次設定,
   // 下游所有 SidebarMenuButton / SidebarGroupLabel / SidebarMenuSkeleton 自動繼承。
   size: SidebarSize
@@ -165,26 +166,39 @@ const SidebarProvider = React.forwardRef<
       [activeIdProp, onActiveChange]
     )
     const isMobile = useIsNarrowViewport()
-    const [openMobile, setOpenMobile] = React.useState(false)
+    const [openMobile, setOpenMobileState] = React.useState(false)
+    const openMobileRef = React.useRef(false)
+    const mobileOpenerRef = React.useRef<HTMLElement | null>(null)
+    const setOpenMobile = React.useCallback((value: boolean | ((current: boolean) => boolean), opener?: HTMLElement) => {
+      const current = openMobileRef.current
+      const next = typeof value === "function" ? value(current) : value
+      if (next && !current && typeof document !== "undefined") {
+        mobileOpenerRef.current = opener ?? (
+          document.activeElement instanceof HTMLElement ? document.activeElement : null
+        )
+      }
+      openMobileRef.current = next
+      setOpenMobileState(next)
+    }, [])
 
     const [_open, _setOpen] = React.useState(defaultOpen)
     const open = openProp ?? _open
     const setOpen = React.useCallback(
       (value: boolean | ((value: boolean) => boolean)) => {
         const openState = typeof value === "function" ? value(open) : value
-        if (setOpenProp) {
-          setOpenProp(openState)
-        } else {
-          _setOpen(openState)
-        }
+        // 受控/非受控分岔依「有沒有傳 open prop」判定(同上方 activeId pattern),
+        // 不依「有沒有傳 onOpenChange」——否則 uncontrolled + onOpenChange 場景
+        // internal state 永不更新,sidebar 凍結(同 SelectMenu R2 已修 bug class)。
+        if (openProp === undefined) _setOpen(openState)
+        setOpenProp?.(openState)
         document.cookie = `${SIDEBAR_COOKIE_NAME}=${openState}; path=/; max-age=${SIDEBAR_COOKIE_MAX_AGE}`
       },
-      [setOpenProp, open]
+      [openProp, setOpenProp, open]
     )
 
-    const toggleSidebar = React.useCallback(() => {
+    const toggleSidebar = React.useCallback((opener?: HTMLElement) => {
       return isMobile
-        ? setOpenMobile((o) => !o)
+        ? setOpenMobile((o) => !o, opener)
         : setOpen((o) => !o)
     }, [isMobile, setOpen, setOpenMobile])
 
@@ -194,6 +208,21 @@ const SidebarProvider = React.forwardRef<
           event.key === SIDEBAR_KEYBOARD_SHORTCUT &&
           (event.metaKey || event.ctrlKey)
         ) {
+          // 2026-07-05 D4 修:全域攔截加三道 guard——
+          // (1) defaultPrevented:app 層 editor 已處理同快捷鍵時不 double-fire;
+          // (2) isComposing:IME 組字中不攔(組字期間 key 事件不代表使用者意圖);
+          // (3) 可編輯 target:input / textarea / contentEditable 內 Cmd/Ctrl+B 是
+          //     bold 等編輯語意,快捷鍵讓位(對齊 VS Code / Linear 讓位可編輯區慣例)。
+          if (event.defaultPrevented || event.isComposing) return
+          const target = event.target
+          if (
+            target instanceof HTMLElement &&
+            target.closest(
+              'input, textarea, [contenteditable]:not([contenteditable="false"])'
+            )
+          ) {
+            return
+          }
           event.preventDefault()
           toggleSidebar()
         }
@@ -213,6 +242,7 @@ const SidebarProvider = React.forwardRef<
         isMobile,
         openMobile,
         setOpenMobile,
+        mobileOpenerRef,
         toggleSidebar,
         size,
         activeId,
@@ -257,7 +287,7 @@ const SidebarProvider = React.forwardRef<
             style={wrapperStyle}
             className={cn(
               "group/sidebar-wrapper flex min-h-svh w-full",
-              // CSS :has() 偵測 — 只在 uniformPrefix=true(預設)時掛
+              // CSS :has() 偵測 — 只在 uniformPrefix=true(opt-in,預設 false;見 sidebar.spec.md「Sidebar 全域 prefix 對齊」)時掛
               // mixing detected → 同時把 --item-icon-size cascade 到 slot 寬(`!` important 蓋
               // 過 wrapperStyle inline,讓 collapsed pl 公式知道「ItemPrefix wrapper 被撐到
               // 24,effective prefix width = 24 非 16」)。
@@ -291,6 +321,10 @@ const Sidebar = React.forwardRef<
      * 從該值起算(`top: viewportInsetTop / height: calc(100svh - viewportInsetTop)`),
      * 讓 global header 不被覆蓋(AppShell primary-header mode 必傳)。
      * 對齊 Mantine `layout="default"` navbar 高度扣 header 慣例。
+     *
+     * ⚠️ 作用範圍:**僅桌機 `offcanvas` / `icon` 分支**套用 insetStyle。
+     * `collapsible="none"`(於 isMobile 前提前 return 固定 div)與 mobile Sheet
+     * 兩分支不套此 inset —— 該兩模式下 global header 仍會被覆蓋(未接線)。
      */
     viewportInsetTop?: string
   }
@@ -306,7 +340,7 @@ const Sidebar = React.forwardRef<
     },
     ref
   ) => {
-    const { isMobile, state, openMobile, setOpenMobile } = useSidebar()
+    const { isMobile, state, openMobile, setOpenMobile, mobileOpenerRef } = useSidebar()
     const insetStyle: React.CSSProperties | undefined = viewportInsetTop
       ? { top: viewportInsetTop, height: `calc(100svh - ${viewportInsetTop})` }
       : undefined
@@ -332,6 +366,12 @@ const Sidebar = React.forwardRef<
           <SheetContent
             data-sidebar="sidebar"
             data-mobile="true"
+            onCloseAutoFocus={(event) => {
+              event.preventDefault()
+              const opener = mobileOpenerRef.current
+              mobileOpenerRef.current = null
+              if (opener?.isConnected) opener.focus({ preventScroll: true })
+            }}
             className="w-[var(--sidebar-width)] bg-surface p-0 text-foreground [&>button]:hidden"
             style={
               {
@@ -426,11 +466,12 @@ const SidebarTrigger = React.forwardRef<
       size="sm"
       iconOnly
       startIcon={PanelLeft}
-      aria-label="Toggle Sidebar"
+      aria-label="切換側邊欄" /* i18n-allow: DS default;consumer 經 {...props} override */
       className={className}
       onClick={(event) => {
+        const opener = event.currentTarget
         onClick?.(event)
-        toggleSidebar()
+        toggleSidebar(opener)
       }}
       {...props}
     />
@@ -456,13 +497,15 @@ SidebarInput.displayName = "SidebarInput"
 
 // ── Shell regions ──────────────────────────────────────────────────────────
 
-// SidebarHeader / SidebarFooter:
-//   - 固定高度 `var(--chrome-header-height)`(md=48 / lg=56,density-responsive)
-//   - 跨元件 chrome header 共享同一個 token,自動跟主內容 page header 對齊
+// SidebarHeader(固定高度 chrome slot)vs SidebarFooter(content-based):
+//   - SidebarHeader:固定高度 `var(--chrome-header-height)`(md=48 / lg=56,density-responsive),
+//     跨元件 chrome header 共享同一個 token,自動跟主內容 page header 對齊
+//   - SidebarFooter:高度由內容決定(`shrink-0 py-2 border-t`,不消費 chrome-header-height、
+//     無自身固定高度),見下方 SidebarFooter 定義的 docblock + spec「Chrome 內容的約束」段
 //   - 水平 padding 用 loose token(跟 items 的 px 對齊)
 //   - 邊框是結構邊界(分隔 fixed/scroll 區),full-width 不內縮
 //
-// 為什麼 density-responsive:chrome 裡放的 button 綁定 field-height token,
+// 為什麼 Header density-responsive:chrome 裡放的 button 綁定 field-height token,
 // 會隨 density 變大。Chrome 如果不跟著放大,lg density 下 padding 會被擠壓。
 const SidebarHeader = React.forwardRef<
   HTMLDivElement,
@@ -501,10 +544,11 @@ const SidebarHeader = React.forwardRef<
         //                                JS 端透過 WorkspaceBrand RowSizeProvider value="md"
         //                                + AVATAR_SIZE.inline.md spec-coupled 共識 sync。
         //
-        // Numerical equivalence to v13 `loose-4` 公式(verified):
-        //   md density: (48-24)/2 = 12 = loose-4 = 12 ✓ identical
-        //   lg density: (64-24)/2 = 20 = loose-4 = 20 ✓ identical
-        // → v14 upgrade 純 SSOT chain robustness,0 視覺改變。
+        // Collapsed pl 幾何值(rail-centered,--sidebar-width-icon = 2*loose + menu-icon):
+        //   md density: (48-24)/2 = 12  ·  lg density: (68-24)/2 = 22
+        //   (lg width = 2×24+20 = 68,非 stale 64;avatar-size = 24 both densities)
+        // 註:已撤回的 v13 `loose-4` 近似在 lg 給 20,與新 rail-幾何精確值 22 不同 —
+        //     v14 以 SSOT chain 公式取代該近似,md 兩者恰好都是 12。
         "group-data-[collapsible=icon]:!pl-[calc((var(--sidebar-width-icon)-var(--chrome-header-avatar-size))/2)]",
         "group-data-[collapsible=icon]:!pr-0",
         "transition-[padding] duration-200 ease-linear motion-reduce:duration-0",
@@ -587,8 +631,9 @@ SidebarContent.displayName = "SidebarContent"
 // ── Group ──────────────────────────────────────────────────────────────────
 
 // SidebarGroupContext——讓 `SidebarGroupLabel` 和 `SidebarGroupContent` 知道當前
-// 所在的 group 是否 collapsible,以自動切換渲染模式(label 變 trigger,content 變
-// `Collapsible.Content`)。沒有 context 就是舊行為(非 collapsible 的 plain div)。
+// 所在的 group 是否 collapsible,以自動切換渲染模式(label 尾端 chevron button 變
+// `Collapsible.Trigger`、content 變 `Collapsible.Content`;label 本身維持
+// `role="presentation"` div,不升格為 button)。沒有 context 就是舊行為(plain div)。
 type SidebarGroupContextValue = {
   collapsible: boolean
 }
@@ -602,13 +647,14 @@ function useSidebarGroup() {
  * SidebarGroup
  *
  * 預設是非互動的 plain group(div)。當 `collapsible` = true 時自動切換成 Radix
- * Collapsible:SidebarGroupLabel 變 trigger、SidebarGroupContent 變 Content、
- * 自動渲染 chevron 於 label 尾端、chevron 依 open state 旋轉。
+ * Collapsible:SidebarGroupLabel 尾端自動渲染 chevron button 作為 `Collapsible.Trigger`
+ * (承載 aria-expanded / data-state,依 open state 旋轉),SidebarGroupContent 變 Content;
+ * label 本身維持 `role="presentation"` div,不升格為 button。
  *
  * ── API 設計決策 ──
  * 為什麼是 group 層級的 prop 而不是 label 層級?因為「group 是否可收合」是結構層
- * 的決定,影響 group 所有子 primitive 的渲染模式(label 變 button、content 變
- * animated container)。把 prop 放在 label 上會讓 content 不知道自己該不該被包,
+ * 的決定,影響 group 子 primitive 的渲染模式(label 尾端 chevron 變 trigger button、
+ * content 變 animated container)。把 prop 放在 label 上會讓 content 不知道自己該不該被包,
  * 形成跨元件的 prop drilling。放在 group 上用 context 傳遞是 React 的標準做法。
  */
 const SidebarGroup = React.forwardRef<
@@ -652,8 +698,10 @@ const SidebarGroup = React.forwardRef<
         open={open}
         onOpenChange={onOpenChange}
         className={baseClass}
-        // Collapsible 在 icon 模式下整個隱藏(跟 TreeView 一樣——icon rail 沒空間放展開的 tree)
-        // Consumer 若要在 icon 模式顯示整個 group,自行傳 className 覆寫
+        // 註:此 Collapsible.Root 本身**不**自帶 icon 模式隱藏 class(baseClass 無
+        // `group-data-[collapsible=icon]:hidden`),icon 模式下預設仍渲染。若要在 icon rail
+        // 隱藏整個可收合 group(icon rail 沒空間放展開的 tree),consumer 自行傳
+        // `className="group-data-[collapsible=icon]:hidden"` 覆寫。
         {...(props as React.ComponentProps<typeof CollapsiblePrimitive.Root>)}
       >
         {children}
@@ -705,7 +753,7 @@ const sidebarGroupLabelVariants = cva(
     "px-[var(--layout-space-loose)]",
     "font-medium text-fg-muted",
     "cursor-default select-none pointer-events-none outline-none",
-    // icon 模式:display:none 硬隱藏(跟 SidebarMenuButton label span 一致的策略)
+    // icon 模式:GroupLabel 純視覺分段 → collapsed 連 SR 一併隱藏是刻意(供名責任在各 menu button 的 sr-only label,2026-07-05 D4 修後與 MenuButton 策略分工)
     "group-data-[collapsible=icon]:hidden",
   ],
   {
@@ -731,11 +779,11 @@ const SidebarGroupLabel = React.forwardRef<
 
   // Collapsible group:label 本身仍是 plain header(保留原本語意),
   // chevron 是 suffix slot 裡的 inline action button,用 Radix Collapsible.Trigger asChild
-  // 包住 `ItemInlineActionButton`——視覺規格完全對齊 uiSize.spec.md「Inline Action」,
+  // 包住 `ItemInlineActionButton`——視覺規格完全對齊 patterns/element-anatomy/inline-action.spec.md(Inline Action SSOT),
   // 跟 SidebarMenuButton 的 suffix inline action 同一套 canonical 實作。
   //
   // **為什麼 chevron 是 inline action 而非整個 label 是 trigger**:
-  // 1. 同 sidebar 內的 inline action 視覺必須一致(fg-muted → foreground、hover bg、圓角)
+  // 1. 同 sidebar 內的 inline action 視覺必須一致(fg-muted → fg-secondary、hover bg、圓角)
   // 2. Linear / Notion / Finder 等世界級 sidebar 都是「label 裝飾、chevron 互動」
   // 3. 整個 label 當 trigger 會把 label 升格為 button,跟非 collapsible group 的 label
   //    語意不一致(一個是 div、一個是 button),無障礙與視覺焦點都會跳動
@@ -799,7 +847,7 @@ const SidebarGroupAction = React.forwardRef<
       ref={ref}
       data-sidebar="group-action"
       className={cn(
-        "absolute right-[var(--layout-space-loose)] top-2 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-fg-muted outline-none ring-ring transition-colors hover:bg-neutral-hover hover:text-foreground focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
+        "absolute right-[var(--layout-space-loose)] top-2 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-fg-muted outline-none ring-ring transition-colors hover:bg-neutral-hover hover:text-fg-secondary focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
         "after:absolute after:-inset-2 after:md:hidden",
         "group-data-[collapsible=icon]:hidden",
         className
@@ -814,9 +862,10 @@ SidebarGroupAction.displayName = "SidebarGroupAction"
 
 // SidebarMenu — items 容器
 //
-// Prefix 對齊由 `SidebarProvider` 全域 auto-detect 處理(school B,Notion/Linear 慣例):
-// 整個 sidebar 子樹同時存在 icon 和 avatar prefix 時,自動套用固定槽,跨 menu 跨 group 對齊。
-// 若要關閉,在 `<SidebarProvider uniformPrefix={false}>` 全域控制。SidebarMenu 沒有
+// Prefix 對齊由 `SidebarProvider` 的 `uniformPrefix`(opt-in,預設 false)全域處理(school B,
+// Notion/Linear 慣例):開啟後,整個 sidebar 子樹同時存在 icon 和 avatar prefix 時,自動套用
+// 固定槽,跨 menu 跨 group 對齊。要啟用,在 `<SidebarProvider uniformPrefix>` 全域 opt-in
+// (explicit > implicit,見 sidebar.spec.md「Sidebar 全域 prefix 對齊」段)。SidebarMenu 沒有
 // per-menu 覆寫——沒有真實 use case,YAGNI。
 const SidebarMenu = React.forwardRef<
   HTMLUListElement,
@@ -856,8 +905,10 @@ SidebarMenuItem.displayName = "SidebarMenuItem"
  *   - hover:      bg-neutral-hover
  *   - selected:   bg-neutral-selected(data-active=true)
  *
- * Icon 模式:button 保持 w-full 填滿 sidebar icon rail,鎖高為 field-height-{size},
- * content 用 justify-center 居中,label span 以 display:none 硬隱藏。
+ * Icon 模式:button 保持 w-full 填滿 sidebar icon rail,**無 height lock / 無 justify-center**
+ * (2026-05-21 v4 C* 撤回 `!h-[...]`——row height 永遠 stable,collapsed 只 outer clip);
+ * prefix(icon / avatar)靠 `!pl-[calc((rail - prefix-width)/2)]` 公式置中對齊 rail,
+ * label span 以 sr-only 視覺隱藏(a11y tree 保留,2026-07-05 D4——SR 仍讀得到 accessible name)。
  */
 const sidebarMenuButtonVariants = cva(
   [
@@ -876,22 +927,37 @@ const sidebarMenuButtonVariants = cva(
     //   range 內。Row geometry 永遠 stable(px-loose + items-start + gap-2 + height auto),
     //   無 discrete property switch → 無 fly / 無 flutter / 無 jitter。
     //
-    //   Label/badge/action 自然存在 DOM(a11y screen reader 仍讀到),只是 outer clip 視覺消失。
-    //   Tooltip 仍在 collapsed state 顯示(per L1043-1055 既有 hidden 條件)。
+    //   2026-07-05 D4 更新:v4「outer clip、SR 仍讀到」的宣稱在 v5 label display:none 後
+    //   已失真;現行 = label 走 sr-only(SR 讀到、供 accessible name,見下方 v5/D4 註解),
+    //   badge / action / inline-actions 仍 display:none(視覺 + SR 一併隱藏——collapsed 供名
+    //   責任在 label,badge 計數屬補充資訊)。Tooltip 仍在 collapsed state 顯示
+    //   (per buttonWithTooltip 既有 hidden 條件),僅 hover 提示、不供名。
     //
     //   對齊 MUI MiniDrawer + shadcn canonical(width morph + overflow clip + row geometry 不變)。
     "transition-[background-color,color] duration-200 ease-linear motion-reduce:duration-0",
     "hover:bg-neutral-hover hover:text-foreground",
     "focus-visible:bg-neutral-hover focus-visible:text-foreground",
-    "disabled:pointer-events-none disabled:opacity-disabled",
-    "aria-disabled:pointer-events-none aria-disabled:opacity-disabled",
+    // 2026-05-31 M24:SidebarMenuButton 主要為 icon+label(currentColor 可改寫)→ 用 semantic
+    // text-fg-disabled 對齊 MenuItem primitive(menu-item.tsx:198/221/248 + item-anatomy.tsx:374),
+    // 非 opacity-disabled(opacity 保留給圖片/avatar/Switch 等無法改寫內部色者,per color.spec.md:103/118/701)。
+    "disabled:pointer-events-none disabled:text-fg-disabled",
+    "aria-disabled:pointer-events-none aria-disabled:text-fg-disabled",
     "data-[active=true]:bg-neutral-selected data-[active=true]:text-foreground",
+    // 2026-08-11 user 拍板(SSOT = item-anatomy「選中 × 互動疊加」):滑鼠 hover 當前項釘住不變
+    //(先前無規則,靠編譯順序運氣;現寫成顯式,釘住 (0,3,0) > hover (0,2,0));
+    // 鍵盤焦點停在當前項 → -focus 深一階(游標可見;非當前項維持上方 focus-visible 的 hover 色)。
+    "data-[active=true]:hover:bg-neutral-selected data-[active=true]:focus-visible:bg-neutral-selected-focus",
     "group-has-[[data-sidebar=menu-action]]/menu-item:pr-8",
-    // 2026-05-21 v5 restore label display:none(user 抓「label 沒消失」):
+    // 2026-05-21 v5 restore label 硬隱藏(user 抓「label 沒消失」):
     // C* outer overflow-x:hidden 理論 clip,但 label.x=40 在 sidebar-width-icon=48 內 → 首字
-    // 部分可見。display:none 是 instant 切換非 main animation,跟 C* 「不用 display:none 做主
-    // 動畫」不衝突(label 不參與 width 動畫,純 final state)。對齊 shadcn canonical。
-    "group-data-[collapsible=icon]:[&_[data-sidebar=menu-label]]:hidden",
+    // 部分可見。instant 切換非 main animation,跟 C* 「不用 display:none 做主
+    // 動畫」不衝突(label 不參與 width 動畫,純 final state)。
+    // 2026-07-05 D4 修:v5 的 display:none 讓 accessible-name 計算排除 label
+    // (icon aria-hidden、badge 也 hidden)→ collapsed 時 menu button 對 SR 是無名
+    // button(WCAG 4.1.2)。改 sr-only:position:absolute + 1px + clip 視覺隱藏但保留
+    // a11y tree,button 仍有 accessible name;absolute 移出 flex flow,layout 效果同
+    // display:none(icon 置中公式不變)。
+    "group-data-[collapsible=icon]:[&_[data-sidebar=menu-label]]:sr-only",
     // 2026-05-22 Approach 9 — 收合時所有 prefix center 鎖回 rail center
     // (--sidebar-width-icon/2 = GlobalHeader toggle geometry SSOT)。
     // 公式: pl = (rail - prefix-width) / 2,prefix-width 由 SidebarProvider 注入的
@@ -955,7 +1021,7 @@ const SidebarMenuButton = React.forwardRef<
     startIcon?: LucideIcon
     tooltip?: string | React.ComponentProps<typeof TooltipContent>
     /**
-     * Suffix slot 的 inline actions(宣告式 API,對齊 uiSize.spec.md「Inline Action」)。
+     * Suffix slot 的 inline actions(宣告式 API,對齊 patterns/element-anatomy/inline-action.spec.md)。
      * Host 自動用 `<ItemInlineAction>` 渲染,consumer 只宣告 intent。
      * Icon 模式下自動隱藏。
      */
@@ -1026,8 +1092,9 @@ const SidebarMenuButton = React.forwardRef<
     // 所以 asChild 的 consumer 自行放 icon + label(記得 prefix 要包在 h-[1lh] 容器,
     // label span 要有 data-sidebar="menu-label" attribute 才能參與 icon 模式自動隱藏)。
     //
-    // Label span 在 icon 模式下透過 cva base 的 `[&_[data-sidebar=menu-label]]:hidden` display:none,
-    // 這樣 flex 只剩 icon 一個 child,justify-center 可以真正置中。
+    // Label span 在 icon 模式下透過 cva base 的 `[&_[data-sidebar=menu-label]]:sr-only`
+    // 視覺隱藏(2026-07-05 D4:sr-only 非 display:none,SR 保留 accessible name;
+    // absolute 移出 flex flow),這樣 flex 只剩 icon 一個 in-flow child,置中公式不變。
     // Sidebar 寬度 transition 200ms 是唯一持續動畫,使用者視線跟著寬度走,不會察覺 label 的瞬切。
     // 用 `<ItemIcon>` / `<ItemLabel>` helper,**不直接寫 ItemPrefix wrap StartIcon**——
     // ItemIcon 內部會自動加 `data-prefix-type="icon"`,讓 SidebarProvider 的全域
@@ -1043,7 +1110,14 @@ const SidebarMenuButton = React.forwardRef<
     )
 
     const hasSlot = !!inlineActionsSlot
-    const hasActions = hasSlot || (!!inlineActions && inlineActions.length > 0)
+    // Host disabled 時 inline actions(config + slot)整段不渲染,paddingRight 預留一併取消
+    // (inline-action.spec.md「宿主 disabled 時不渲染」+ sidebar.spec.md「Host disabled 時|不渲染」)。
+    // 必須 render 層 guard:suffix 跟 button 是 sibling(避免巢狀 button),
+    // native disabled 的 pointer-events-none 蓋不到 sibling,CSS 層無從繼承。
+    // aria-disabled 同步 guard——對齊 cva `aria-disabled:` 樣式支線(asChild 非 button host 自傳)。
+    const isDisabled =
+      !!props.disabled || props["aria-disabled"] === true || props["aria-disabled"] === "true"
+    const hasActions = !isDisabled && (hasSlot || (!!inlineActions && inlineActions.length > 0))
 
     // 計算 suffix 所佔寬度:N×icon + (N-1)×gap-2(8px),再加 gap-2 跟 label 之間的間隔
     // Slot mode 預設按 1 icon 預留(consumer 寬度自控)
@@ -1085,7 +1159,7 @@ const SidebarMenuButton = React.forwardRef<
           // mouse click 觸發,導致 click 之後 actions 永久顯示直到焦點移走;
           // focus-visible 只在鍵盤 tab 時啟動,mouse click 不會觸發,符合使用者直覺。
           actionsReveal === "hover" &&
-            "opacity-0 group-hover/menu-item:opacity-100 group-has-[:focus-visible]/menu-item:opacity-100 transition-opacity duration-150"
+            "opacity-0 group-hover/menu-item:opacity-100 group-has-[:focus-visible]/menu-item:opacity-100 transition-opacity duration-150 motion-reduce:duration-0"
         )}
       >
         {hasSlot
@@ -1142,7 +1216,7 @@ const SidebarMenuAction = React.forwardRef<
       ref={ref}
       data-sidebar="menu-action"
       className={cn(
-        "absolute right-[var(--layout-space-loose)] top-1/2 -translate-y-1/2 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-fg-muted outline-none ring-ring transition-colors hover:bg-neutral-hover hover:text-foreground focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
+        "absolute right-[var(--layout-space-loose)] top-1/2 -translate-y-1/2 flex aspect-square w-5 items-center justify-center rounded-md p-0 text-fg-muted outline-none ring-ring transition-colors hover:bg-neutral-hover hover:text-fg-secondary focus-visible:ring-2 [&>svg]:size-4 [&>svg]:shrink-0",
         "after:absolute after:-inset-2 after:md:hidden",
         "group-data-[collapsible=icon]:hidden",
         showOnHover &&
@@ -1238,7 +1312,7 @@ SidebarMenuSkeleton.displayName = "SidebarMenuSkeleton"
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const sidebarMeta = {
   component: 'Sidebar',
-  family: null, // non-family composite / overlay / layout
+  family: 1, // Family 1(Menu item layout)消費者 — 對齊 sidebar.spec.md frontmatter family: 1(SidebarMenuButton rows 消費 item-anatomy;同 tree-view.tsx 慣例)
   variants: {
     default: { when: '標準導覽 row,參與 single-selection' },
     meta: { when: 'Section 底部命令 row(Show more / 新增),不參與 selection' },
@@ -1248,9 +1322,12 @@ export const sidebarMeta = {
     md: { px: 32, when: '預設 — 應用程式主導覽' },
     lg: { px: 36, when: '重要主導覽 / icon-prominent workspace switcher' },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'selected' = nav 當前項(data-[active=true] → bg-neutral-selected 灰底家族;2026-07-07 meta 詞彙統一補列);
+  // 'active' 移除 — 全檔無 Tailwind 按壓 utility(內嵌 SidebarTrigger 的按壓屬 Button meta,同 Notice/Alert
+  // 排除內嵌 dismiss Button 慣例;2026-07-07 對抗稽核抓 doc-claim ≠ code 補修)。
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-neutral-hover', 'bg-surface', 'bg-transparent'],
+    bg: ['bg-neutral-hover', 'bg-neutral-selected', 'bg-surface', 'bg-transparent'],
     fg: ['text-fg-muted', 'text-fg-secondary', 'text-foreground'],
     ring: ['ring-ring'],
   },

package/src/components/Skeleton/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './skeleton'

package/src/components/Skeleton/skeleton.anatomy.stories.tsx

@@ -0,0 +1,145 @@
+// @anatomy-rationale:
+//   Inspector / ColorMatrix / SizeMatrix / StateBehavior N/A — Skeleton 是極簡
+//   animation primitive(單一 div + pulse animation),刻意沒有 size / color /
+//   variant prop。形狀 / 尺寸完全由 consumer 的 className 決定;色彩透過
+//   bg-muted 從 theme 繼承(2026-05-20 修 drift,實際 skeleton.tsx:10 用 bg-muted);
+//   loading 是唯一狀態(無 hover / focus / active)。
+//   本檔保留 Overview + CommonShapes + DesignPrinciple + Accessibility 四個 story。
+import type { Meta, StoryObj } from '@storybook/react'
+import { Skeleton } from './skeleton'
+import { H3, Desc } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+/**
+ * Skeleton 是極簡 animation primitive——單一 div + pulse animation,
+ * **刻意沒有 size / color / variant**。形狀 / 尺寸完全由 consumer 的 className
+ * (Tailwind utilities)決定。底色固定用 `bg-muted`,深淺模式由主題色自動切換。
+ *
+ * 因此本 spec 只有 Overview + 常見形狀 + 設計原則 + 無障礙四個 story,沒有 SizeMatrix /
+ * ColorMatrix / StateMatrix——這些概念對 Skeleton 不適用。
+ */
+
+const meta: Meta = {
+  title: 'Design System/Components/Skeleton/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>Skeleton 用帶有脈動動畫的灰色色塊,模擬真實內容的形狀與排版,讓使用者預期即將出現的佈局。底色採用系統的中性色,深淺模式會自動切換。</Desc>
+        <div className="flex flex-col gap-2 max-w-md">
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-3/4" />
+          <Skeleton className="h-4 w-1/2" />
+        </div>
+      </div>
+
+      <div>
+        <H3>Props 速查</H3>
+        <Desc>Skeleton 只是 styled div——尺寸 / 形狀完全由 className(Tailwind utilities)決定。</Desc>
+      </div>
+    </div>
+  ),
+}
+
+export const CommonShapes: Story = {
+  name: '常見形狀',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>單行文字</H3>
+        <Skeleton className="h-4 w-48" />
+      </div>
+
+      <div>
+        <H3>多行段落(寬度遞減模擬自然換行)</H3>
+        <div className="flex flex-col gap-2 max-w-md">
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-full" />
+          <Skeleton className="h-4 w-3/4" />
+        </div>
+      </div>
+
+      <div>
+        <H3>標題 + 描述</H3>
+        <div className="flex flex-col gap-2 max-w-sm">
+          <Skeleton className="h-5 w-40" />
+          <Skeleton className="h-4 w-64" />
+        </div>
+      </div>
+
+      <div>
+        <H3>Avatar(圓形)+ name</H3>
+        <div className="flex items-center gap-3 max-w-sm">
+          <Skeleton className="h-10 w-10 rounded-full" />
+          <div className="flex flex-col gap-2 flex-1">
+            <Skeleton className="h-4 w-24" />
+            <Skeleton className="h-3 w-32" />
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <H3>Card 載入</H3>
+        <div className="border border-border rounded-lg p-4 max-w-sm flex flex-col gap-3">
+          <Skeleton className="h-40 w-full rounded-md" />
+          <Skeleton className="h-5 w-3/4" />
+          <div className="flex flex-col gap-1">
+            <Skeleton className="h-3 w-full" />
+            <Skeleton className="h-3 w-full" />
+            <Skeleton className="h-3 w-2/3" />
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <H3>List 載入(多 row 同形狀)</H3>
+        <div className="flex flex-col gap-3 max-w-md">
+          {Array.from({ length: 4 }).map((_, i) => (
+            <div key={i} className="flex items-center gap-3">
+              <Skeleton className="h-10 w-10 rounded-full" />
+              <div className="flex flex-col gap-1.5 flex-1">
+                <Skeleton className="h-4 w-3/5" />
+                <Skeleton className="h-3 w-1/3" />
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const DesignPrinciple: Story = {
+  name: '設計原則',
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div>
+        <H3>形狀貼合真實內容</H3>
+        <Desc>Skeleton 的形狀應該貼近真實內容的排版——使用者看到 skeleton 後資料載入,佈局不應大幅跳動。形狀嚴重偏離真實內容會讓使用者預期被打破、體感更慢。</Desc>
+      </div>
+
+      <div>
+        <H3>長時間 loading 不適合 Skeleton</H3>
+        <Desc>Skeleton 暗示「佈局已就位,資料很快會來」——長時間(&gt; 10s)持續顯示會讓使用者懷疑是否卡住。此時改用 progress indicator 或說明文字。</Desc>
+      </div>
+    </div>
+  ),
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙與鍵盤',
+  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">{"本元件為純視覺呈現,無 keyboard / ARIA role / focus state 需求。Consumer 包 Skeleton 進互動容器(Button / Card / Link)時 a11y 由容器決定。"}</p>
+    </div>
+  ),
+}