@qijenchen/design-system 0.1.0-beta.145 → 0.1.0-beta.147

package/src/components/Sidebar/sidebar.tsx

@@ -36,12 +36,24 @@ import {
   ItemLabel,
   ItemInlineAction,
   ItemInlineActionButton,
+  type ItemInlineActionButtonProps,
+  ItemSuffix,
   RowSizeProvider,
   getUniformPrefixSlotStyle,
   ROW_PADDING_BY_SIZE,
   type RowSize,
   type InlineActionConfig,
 } from "@/design-system/patterns/element-anatomy/item-anatomy"
+// 「列上有小按鈕的一串」鍵盤路線的唯一判定與執行(與 TreeView / FileUpload / Command 共用;見下方 SidebarMenu)
+import {
+  applyRovingAction,
+  isRovingControlReachable,
+  isTextEntryElement,
+  pickRovingTabStop,
+  removeRovingControlsFromTabOrder,
+  resolveRovingKey,
+  setRovingTabIndex,
+} from "@/design-system/lib/roving-list-keyboard"
 
 /**
  * Sidebar
@@ -613,14 +625,14 @@ const SidebarContent = React.forwardRef<
       // SidebarContent 用 ScrollArea 處理長列表 scroll——跨 OS 一致不吃寬度(macOS
       // overlay vs Windows/Linux always-visible 差異見 scroll-area.tsx 註解)。
       // 呼吸空間和分隔線由 SidebarGroup 自己處理(對齊 MenuGroup 的 py-2 + [&+&]:border-t)。
-      // ScrollArea Root 本身 overflow-hidden,icon-collapsed 時不會露出 scroll chrome。
+      // ScrollArea Root 本身 overflow-hidden,icon-collapsed 時不會露出 scroll chrome。捲動區本身不當 Tab 停靠點(viewportTabIndex={-1};待辦總帳 B9,依 `../ScrollArea/scroll-area.spec.md:103`「內容已有自帶 focusable + 鍵盤處理的元素」時傳 -1):內容是一串串自帶方向鍵的 SidebarMenu,焦點落進任何一項都會把它捲進視野;先前 Tab 第一站是這個捲動區(「混合內容」實測第 1 站),停在上面按 ↓ 焦點不動。
       className={cn(
         "flex min-h-0 flex-1 flex-col",
         className
       )}
       {...props}
     >
-      <ScrollArea className="flex-1">
+      <ScrollArea className="flex-1" viewportTabIndex={-1}>
         <div className="flex flex-col">{children}</div>
       </ScrollArea>
     </div>
@@ -785,7 +797,10 @@ const SidebarGroupLabel = React.forwardRef<
   //
   // **為什麼 chevron 是 inline action 而非整個 label 是 trigger**:
   // 1. 同 sidebar 內的 inline action 視覺必須一致(fg-muted → fg-secondary、hover bg、圓角)
-  // 2. Linear / Notion / Finder 等世界級 sidebar 都是「label 裝飾、chevron 互動」
+  // 2. Linear / Finder 等世界級 sidebar 是「label 裝飾、chevron 互動」。**Notion 不是**(2026-09-29 出處更正,待辦總帳 N46):
+  //    Notion 的側欄說明頁逐字 "Click on the name of a sidebar section — Teamspaces, Shared, or Private — to collapse it"
+  //    (https://www.notion.com/help/navigate-with-the-sidebar)—— 點區段名稱就收合;本 DS 沒有跟,理由是第 1 與第 3 點。
+  //    2026-09-29 前這裡把 Notion 列在同一邊,是憑印象寫的(M22)。
   // 3. 整個 label 當 trigger 會把 label 升格為 button,跟非 collapsible group 的 label
   //    語意不一致(一個是 div、一個是 button),無障礙與視覺焦點都會跳動
   if (group?.collapsible) {
@@ -838,25 +853,35 @@ const SidebarGroupLabel = React.forwardRef<
 })
 SidebarGroupLabel.displayName = "SidebarGroupLabel"
 
+// ⚠️ 2026-09-24:這兩顆先前是 shadcn 原樣帶進來的**手刻品**(`b7b34721` 把 DS 搬進 npm workspace
+// 時一起進來,之後從未跟著本 DS 的行內動作 canonical 遷移)。它們自己寫死
+// `aspect-square w-5 ... [&>svg]:size-4`,也就是 **16 圖示裝在 20 盒裡** —— 而
+// `patterns/element-anatomy/inline-action.spec.md` 的尺寸表只有兩種組合(16 圖示配 18 底色、
+// 20 圖示配 22 底色),**20 兩種都不是**。同一個檔案 :826 的收合箭頭早就在消費
+// `ItemInlineActionButton`,於是同一個元件裡兩套幾何並存。
+// 依 M23(DS 既有 canonical 優先)與 M30(wrapper 必須繼承 primitive,不得平行宣告)改為委派。
+// API 隨之從 children 改成 `icon` prop —— 這是 breaking change,刻意不留 children 後備:
+// M23(f)「『向後相容』不是把新裁示變成可選的理由」。
+//
+// 命中區 ≡ 懸停底色由 primitive 自己保證(hit-area-canonical「一-4 細則」:行內動作平時沒有可視邊界,
+// 判準是懸停回饋形狀,不是「可視形狀」;`item-anatomy.tsx:730` 那塊**刻意沒有**
+// `pointer-events-none` 的懸停底色 span)。先前這裡另有一圈 `after:-inset-2 after:md:hidden`,
+// 只在 <md 生效、每邊多 8px,實測上下各越出宿主 `<li>` 2px 並蓋掉緊貼的下一列列鈕,已於同日移除。
 const SidebarGroupAction = React.forwardRef<
   HTMLButtonElement,
-  React.ComponentProps<"button"> & { asChild?: boolean }
->(({ className, asChild = false, ...props }, ref) => {
-  const Comp = asChild ? Slot : "button"
-  return (
-    <Comp
-      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 hover:bg-neutral-hover hover:text-fg-secondary [&>svg]:size-4 [&>svg]:shrink-0",
-        "after:absolute after:-inset-2 after:md:hidden",
-        "group-data-[collapsible=icon]:hidden",
-        className
-      )}
-      {...props}
-    />
-  )
-})
+  Omit<ItemInlineActionButtonProps, "size">
+>(({ className, ...props }, ref) => (
+  <ItemInlineActionButton
+    ref={ref}
+    data-sidebar="group-action"
+    className={cn(
+      "absolute right-[var(--layout-space-loose)] top-2",
+      "group-data-[collapsible=icon]:hidden",
+      className
+    )}
+    {...props}
+  />
+))
 SidebarGroupAction.displayName = "SidebarGroupAction"
 
 // ── Menu ───────────────────────────────────────────────────────────────────
@@ -868,18 +893,175 @@ SidebarGroupAction.displayName = "SidebarGroupAction"
 // 固定槽,跨 menu 跨 group 對齊。要啟用,在 `<SidebarProvider uniformPrefix>` 全域 opt-in
 // (explicit > implicit,見 sidebar.spec.md「Sidebar 全域 prefix 對齊」段)。SidebarMenu 沒有
 // per-menu 覆寫——沒有真實 use case,YAGNI。
+//
+// ── 鍵盤:一串 SidebarMenu = 一個 Tab 停靠點(2026-09-25,待辦總帳 B9 乙)──
+// 決策出處 = governance/planning/2026-09-25-interaction-and-hover-remediation.md B9,user 逐字:
+// 「確定建議符合我們一致的設計語言且不違背世界級的設計就照建議」(附條件同意;條件查證成立記在同檔 B9)。
+// 規格 SSOT = sidebar.spec.md「鍵盤:一串 SidebarMenu = 一個 Tab 停靠點」;按鍵判定與執行 = lib/roving-list-keyboard.ts
+// (2026-09-26 與 TreeView / FileUpload / Command 四份合一,同檔〇節「按鍵規則合併」),此處只剩側欄自己的 DOM:誰是列、誰是動作鈕。
+//
+// 實作 = roving tabindex,**直接改 DOM 的 tabindex 屬性**,不經 React props:
+//   - 列上的動作鈕有兩個出口不歸本元件渲染 —— `ItemInlineAction`(item-anatomy.tsx,沒有 tabIndex prop)
+//     與 consumer 的 `inlineActionsSlot`,只能在 DOM 上把它們收成 -1。同一件事只用一種機制(M17),
+//     所以列鈕的 0 / -1 也在同一個函式裡寫(AI 推導的工程取捨)。
+//   - 沒有 JS(SSR 首屏、hydration 前)時什麼都不寫 → 退回瀏覽器原生:每顆都可 Tab,不會變成到不了。
+//   - ARIA 角色維持 ul / li / button,不改成 grid / tree:狀態是「你現在在這一頁」(aria-current),
+//     不是「在控件裡被挑中」(aria-selected)。
+const SIDEBAR_MENU_BUTTON = '[data-sidebar="menu-button"]'
+// 列上的動作鈕 = 宣告式 inlineActions / inlineActionsSlot(包在 menu-inline-actions 裡)+ SidebarMenuAction 本身
+const SIDEBAR_ROW_ACTIONS =
+  '[data-sidebar="menu-inline-actions"] :is(button, a[href], [role="button"]), [data-sidebar="menu-action"]'
+
+type SidebarMenuRow = { button: HTMLElement; actions: HTMLElement[] }
+
+/** 這一串的每一列(只看直接子層 li,依畫面順序)與它自己的動作鈕(依畫面順序;含此刻走不到的,收 -1 時一併收)。 */
+function getSidebarMenuRows(menu: HTMLElement): SidebarMenuRow[] {
+  const rows: SidebarMenuRow[] = []
+  for (const child of Array.from(menu.children)) {
+    if (child.tagName !== "LI") continue
+    const button = child.querySelector<HTMLElement>(SIDEBAR_MENU_BUTTON)
+    if (!button) continue
+    rows.push({ button, actions: Array.from(child.querySelectorAll<HTMLElement>(SIDEBAR_ROW_ACTIONS)) })
+  }
+  return rows
+}
+
+// 原生 disabled 本來就聚焦不了 → 跳過(sidebar.spec.md「Disabled item」)。aria-disabled 仍可聚焦,照舊。
+const isFocusableSidebarTarget = (el: HTMLElement) => !(el as HTMLButtonElement).disabled
+// 畫得出來才走得到:icon 模式的動作鈕、被收起的整組都是 display:none(opacity-0 的滑過才出現鈕不算隱藏)
+const isRenderedSidebarTarget = (el: HTMLElement) => el.getClientRects().length > 0
+
+/**
+ * 哪些列能當落點(方向鍵與 Tab 停靠點共用)。整串看得見時,略過個別被藏起來的列;整串被藏(icon 模式收起的群組)時
+ * 不看可見性,免得重新展開後整串 0 顆可 Tab(展開是祖先屬性變化,本串收不到 mutation)。
+ */
+function sidebarRowNavigability(menu: HTMLElement, rows: SidebarMenuRow[]) {
+  const checkRendered =
+    isRenderedSidebarTarget(menu) &&
+    rows.some((row) => isFocusableSidebarTarget(row.button) && isRenderedSidebarTarget(row.button))
+  return (button: HTMLElement) =>
+    isFocusableSidebarTarget(button) && (!checkRendered || isRenderedSidebarTarget(button))
+}
+
+/**
+ * 整串只留一顆 tabindex=0:上次焦點停過的那一列 → 當前頁(aria-current="page")→ 第一個可用列(X1;
+ * 判定 = lib/roving-list-keyboard.ts `pickRovingTabStop`)。動作鈕一律 -1(別項的與本項的都不在 Tab 路上;→ 才進得去)。
+ */
+function syncSidebarMenuTabStops(menu: HTMLElement, remembered: HTMLElement | null) {
+  const rows = getSidebarMenuRows(menu)
+  const stop = pickRovingTabStop(rows.map((row) => row.button), {
+    remembered,
+    isCurrent: (button) => button.getAttribute("aria-current") === "page",
+    isNavigable: sidebarRowNavigability(menu, rows),
+  })
+  for (const row of rows) {
+    setRovingTabIndex(row.button, row.button === stop ? 0 : -1)
+    removeRovingControlsFromTabOrder(row.actions)
+  }
+}
+
 const SidebarMenu = React.forwardRef<
   HTMLUListElement,
   React.ComponentProps<"ul">
->(({ className, ...props }, ref) => (
-  <ul
-    ref={ref}
-    data-sidebar="menu"
-    // 無 gap:items 連續緊貼(對齊 DropdownMenu / TreeView 的視覺節奏)
-    className={cn("flex w-full min-w-0 flex-col", className)}
-    {...props}
-  />
-))
+>(({ className, onKeyDownCapture, onFocus, ...props }, ref) => {
+  const menuRef = React.useRef<HTMLUListElement | null>(null)
+  const rememberedRef = React.useRef<HTMLElement | null>(null)
+  // 收合 / 展開、手機抽屜切換時重算一次(可見性在這些時刻改變,但本串自己的 DOM 沒變)。
+  // 用 useContext 而非 useSidebar():SidebarMenu 單獨渲染(沒有 Provider)時不該丟例外。
+  const sidebarContext = React.useContext(SidebarContext)
+  const sidebarState = sidebarContext?.state
+  const sidebarIsMobile = sidebarContext?.isMobile
+
+  const setRefs = React.useCallback(
+    (el: HTMLUListElement | null) => {
+      menuRef.current = el
+      if (typeof ref === "function") ref(el)
+      else if (ref) (ref as React.MutableRefObject<HTMLUListElement | null>).current = el
+    },
+    [ref]
+  )
+
+  // 掛上時、以及收合 / 展開 / 手機切換後同步一次;本串 DOM 的其他變化交給下方 MutationObserver
+  React.useLayoutEffect(() => {
+    if (menuRef.current) syncSidebarMenuTabStops(menuRef.current, rememberedRef.current)
+  }, [sidebarState, sidebarIsMobile])
+
+  // 列新增 / 移除、disabled 改變、子層自己重繪而本串沒重繪(例:當前頁換了 → 列鈕的 aria-current 變,
+  // 但 SidebarMenu 不訂閱 activeId)
+  React.useEffect(() => {
+    const menu = menuRef.current
+    if (!menu || typeof MutationObserver === "undefined") return
+    const observer = new MutationObserver(() => syncSidebarMenuTabStops(menu, rememberedRef.current))
+    observer.observe(menu, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      attributeFilter: ["disabled", "aria-current"],
+    })
+    return () => observer.disconnect()
+  }, [])
+
+  // 焦點用任何方式進到某一列(Tab 進來 / 方向鍵 / 滑鼠點 / 選單關閉後還焦點)→ 停靠點跟過去,
+  // 下次 Tab 回來就回到這裡(同 calendar.tsx 日期鈕的 onFocus 同步)。
+  const handleFocus = (event: React.FocusEvent<HTMLUListElement>) => {
+    onFocus?.(event)
+    const menu = event.currentTarget
+    const target = event.target as HTMLElement
+    const row = getSidebarMenuRows(menu).find(
+      (r) => r.button === target || r.actions.includes(target)
+    )
+    if (!row) return
+    rememberedRef.current = row.button
+    syncSidebarMenuTabStops(menu, row.button)
+  }
+
+  // 用 capture:方向鍵整串歸清單,要搶在列鈕 / 動作鈕自己的處理之前 —— 帳號列是 `DropdownMenuTrigger asChild`、
+  // 動作鈕可能是選單觸發鈕(inlineActionsSlot),Radix 會拿 ↓ 開選單;這裡先 preventDefault,Radix 的
+  // composeEventHandlers 看到 defaultPrevented 就不執行,開選單照樣用 Enter / Space(AI 推導,見 spec;X6 以此為全宿主的做法)。
+  const handleKeyDownCapture = (event: React.KeyboardEvent<HTMLUListElement>) => {
+    onKeyDownCapture?.(event)
+    const menu = event.currentTarget
+    const target = event.target as HTMLElement
+    const rows = getSidebarMenuRows(menu)
+    const row = rows.find((r) => r.button === target || r.actions.includes(target))
+    // 焦點不在列或動作鈕上(consumer 自己放進列裡的其他控件)→ 不接管,讓它自己的鍵盤照舊
+    if (!row) return
+    const onRow = row.button === target
+    const controls = row.actions.filter(isRovingControlReachable)
+    const action = resolveRovingKey({
+      key: event.key,
+      focus: onRow ? "item" : "control",
+      controlCount: controls.length,
+      controlIndex: onRow ? -1 : controls.indexOf(target),
+      controlIsTextEntry: !onRow && isTextEntryElement(target),
+      defaultPrevented: event.defaultPrevented,
+      metaKey: event.metaKey,
+      ctrlKey: event.ctrlKey,
+      altKey: event.altKey,
+      shiftKey: event.shiftKey,
+    })
+    const isNavigable = sidebarRowNavigability(menu, rows)
+    applyRovingAction(action, {
+      event,
+      item: row.button,
+      controls,
+      items: rows.map((r) => r.button),
+      isNavigable,
+    })
+  }
+
+  return (
+    <ul
+      ref={setRefs}
+      data-sidebar="menu"
+      // 無 gap:items 連續緊貼(對齊 DropdownMenu / TreeView 的視覺節奏)
+      className={cn("flex w-full min-w-0 flex-col", className)}
+      onFocus={handleFocus}
+      onKeyDownCapture={handleKeyDownCapture}
+      {...props}
+    />
+  )
+})
 SidebarMenu.displayName = "SidebarMenu"
 
 const SidebarMenuItem = React.forwardRef<
@@ -937,13 +1119,28 @@ const sidebarMenuButtonVariants = cva(
     //   對齊 MUI MiniDrawer + shadcn canonical(width morph + overflow clip + row geometry 不變)。
     // hover 底色瞬間切換,不做過渡(user 2026-09-10 拍板「第三題改成全部瞬間」;SSOT = tokens/motion/motion.spec.md「hover 回饋不做過渡」)
     "hover:bg-neutral-hover hover:text-foreground",
+    // 巢狀 hover(2026-09-25,user 選「卡片保留、按鈕再亮一層」;SSOT = sidebar.spec.md「Inline actions」段「指標在動作鈕上時(巢狀 hover)」):
+    // 指標移到同一列的動作鈕(inlineActions 的 suffix span / SidebarMenuAction)上,列保留上一行的 hover,動作鈕再亮自己那層。
+    // 需要這兩行是因為動作鈕是列鈕的**同層兄弟**(避免 button 包 button,見下方 suffixNode 註解)—— 指標在兄弟上時列鈕不算 :hover。
+    // - `~` 只往後找:動作必須排在列鈕後面(兩個內建出口都是;SidebarMenuAction 的 peer-data 也早就要求這個順序)。
+    // - 外層包 `:where()` 把特異性壓回 (0,1,0),下方 `data-[active=true]` 選中色 (0,2,0) 照樣釘住;不包會是 (0,3,0),選中列指到動作鈕時選中色被 hover 色蓋掉(2026-09-25 Chromium 實測)。
+    // - 不掛在 li 的 `group-hover/menu-item`:li 收任意子元素,指到 li 裡的子項目時父列會誤亮(同日實測)。
+    // - `[@media(hover:hover)]` 對齊上一行 `hover:` 的媒體條件(Tailwind 4 的 hover: 只在能懸停的裝置生效),觸控裝置不留殘亮。
+    // 值與上一行 `hover:` 是同一對;改那一行必須同步改這兩行。
+    "[@media(hover:hover)]:[&:where(:has(~:is([data-sidebar=menu-inline-actions],[data-sidebar=menu-action]):hover))]:bg-neutral-hover",
+    "[@media(hover:hover)]:[&:where(:has(~:is([data-sidebar=menu-inline-actions],[data-sidebar=menu-action]):hover))]:text-foreground",
     // 鍵盤游標一律畫框、不上底色(focus-canonical 規則二,user 2026-09-09 拍板);選單鈕撐滿側欄寬度 → 內描邊。
     // 2026-09-09 之前非當前項的焦點用 hover 同色底(AI 推導,user 撤回);hover 的底色與文字色只屬於滑鼠。
     "focus-visible:focus-ring-inset",
     // 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",
+    // 原生 disabled 的 button 本來就不會發 click,不再 pointer-events-none:留著接指標只為了掛禁止符號
+    //(hit-area-canonical.md 滑過原則一-3「停用的用禁止符號」;2026-09-29 全站掃出:「混合內容」的「delta（已封存）」游標是箭頭,
+    // 因為 pointer-events-none 讓 cursor 由 li 決定)。上方 hover 的底色 / 字色由 disabled:hover 釘住(:disabled:hover 特異性高過 :hover)。
+    "disabled:text-fg-disabled disabled:cursor-not-allowed disabled:hover:bg-transparent disabled:hover:text-fg-disabled",
+    // aria-disabled(asChild 的 <a> 等非 button 宿主)仍靠 pointer-events-none 擋掉點擊 / 導覽 —— 那是它唯一的擋法;
+    // 代價是游標由外層決定(箭頭)。要拿掉這裡的 pointer-events-none,得先在 asChild 宿主補 click guard(另案)。
     "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 當前項釘住不變
@@ -1045,7 +1242,8 @@ const SidebarMenuButton = React.forwardRef<
     /**
      * Inline actions 的顯示模式:
      * - `false`(預設):永遠顯示
-     * - `"hover"`:row hover 時才淡入(TreeView 模式)
+     * - `"hover"`:滑過這一列、或鍵盤焦點在這一列時才出現,瞬間出現、不淡入(TreeView 模式;
+     *   待辦總帳 L9,sidebar.spec.md「Inline actions」出現時機列)
      */
     actionsReveal?: false | "hover"
   } & VariantProps<typeof sidebarMenuButtonVariants>
@@ -1139,6 +1337,19 @@ const SidebarMenuButton = React.forwardRef<
         ref={ref}
         data-sidebar="menu-button"
         data-active={isActive}
+        // 2026-09-24:先前這裡**只有** data-active 這個純樣式 attribute,螢幕閱讀器讀不到
+        // 「你現在人在這一頁」—— 當前項在視覺上有底色,對 SR 卻跟其他項完全一樣。
+        // aria-current="page" 是這個狀態的世界級標準寫法,三份一手來源一致:
+        //   W3C APG Disclosure Navigation 範例(連結上帶 aria-current="page")、
+        //   GitHub repo 導覽(Code / Issues / PRs 那排)、
+        //   Primer TreeView(aria-current={isCurrentItem ? 'true' : undefined})。
+        // 它與 aria-selected 是兩件事,WAI-ARIA 1.2 aria-current 的 Note 明文說兩者可以並存:
+        //   current = 你現在人在這一頁(已發生的事實);selected = 這個控件裡被挑中的那一項。
+        // 側欄導覽要表達的是「你現在在這一頁」,不是「控件裡被挑中的那一項」,所以用 current 不用 selected。
+        // 2026-09-25 起一串 SidebarMenu 只佔一個 Tab 停靠點、方向鍵在裡面走(待辦總帳 B9,見上方 SidebarMenu),
+        // 但 ARIA 角色仍是 ul / li / button、沒有宣告 grid / tree 這類 composite 角色 → aria-selected 不適用,這條不變。
+        // 純 SR 語意,**零視覺變化**。
+        aria-current={isActive ? 'page' : undefined}
         className={cn(sidebarMenuButtonVariants({ size, variant }), className)}
         style={hasActions ? { paddingRight: buttonPaddingRight } : undefined}
         onClick={handleClick}
@@ -1150,20 +1361,26 @@ const SidebarMenuButton = React.forwardRef<
 
     // Suffix inline actions——絕對定位在 menu-item 右邊,
     // 跟 button 同層(不是 button 的 child,避免巢狀 button)。
+    // 容器消費 `ItemSuffix`(item-anatomy.tsx):滑過才出現(`hoverReveal`)的規則只住那一份 ——
+    // 2026-09-26 之前這裡另抄了一份同字串,出現方式要跟著 SSOT 改時會漏(M17);它也是「滑過造成的變化一律瞬間」
+    //(待辦總帳 L9 / N4(3),motion.spec.md「hover 回饋不做過渡」)的唯一落點。group 用 `menu-item`(上方 SidebarMenuItem 的 group/menu-item)。
+    // `:has(:focus-visible)` 而非 `:focus-within`:滑鼠點動作鈕不該讓它常駐,只有鍵盤走到時才顯示(ItemSuffix 同註解)。
     const suffixNode = hasActions ? (
-      <span
+      <ItemSuffix
         data-sidebar="menu-inline-actions"
+        hoverReveal={actionsReveal === "hover"}
+        hoverGroup="menu-item"
         className={cn(
-          "absolute top-1/2 -translate-y-1/2 flex items-center gap-2",
+          "absolute top-1/2 -translate-y-1/2",
           "right-[var(--layout-space-loose)]",
           // Icon 模式隱藏(跟 SidebarMenuBadge / SidebarMenuAction 一致)
           "group-data-[collapsible=icon]:hidden",
-          // hover-reveal:滑鼠 hover 或鍵盤 focus(但不是 mouse click 的 focus)時顯示。
-          // 用 `:has(:focus-visible)` 而非 `:focus-within`——focus-within 會被
-          // 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 motion-reduce:duration-0"
+          // 兩顆動作鈕之間的空隙歸列(2026-09-26,待辦總帳 N53 ①,user:「這些看起來幾乎都是bug」;修法 = R20「讓亮著的地方點得到」):
+          // 空隙在滑過時讓列亮著(sidebar.spec.md「Inline actions」段「兩顆動作鈕之間的空隙也算在內」),
+          // 點下去卻落在這個容器、列不導覽 —— 看得到亮卻點不到(hit-area-canonical.md「看到亮起來卻點不到」)。
+          // 容器本身不接指標,只有裡面可以按的東西接;空隙、以及插槽裡不能按的裝飾都穿到底下的列鈕(列鈕 paddingRight 已讓出這一段)。
+          // 指到按鈕上時容器仍是 :hover 的祖先,列的巢狀滑過(上方 cva 的 `~` 選擇器)照舊。
+          "pointer-events-none [&_:is(button,a[href],[role=button],[tabindex])]:pointer-events-auto",
         )}
       >
         {hasSlot
@@ -1171,7 +1388,7 @@ const SidebarMenuButton = React.forwardRef<
           : inlineActions!.map((action, i) => (
               <ItemInlineAction key={action.label + i} action={action} />
             ))}
-      </span>
+      </ItemSuffix>
     ) : null
 
     // code-quality-allow: long-function — helper fn 結構緊密,拆 sub-fn 會跨 fn 傳 state 反而複雜
@@ -1206,31 +1423,31 @@ const SidebarMenuButton = React.forwardRef<
 )
 SidebarMenuButton.displayName = "SidebarMenuButton"
 
+// 同上(見 SidebarGroupAction 上方的遷移說明)。
 const SidebarMenuAction = React.forwardRef<
   HTMLButtonElement,
-  React.ComponentProps<"button"> & {
-    asChild?: boolean
-    showOnHover?: boolean
-  }
->(({ className, asChild = false, showOnHover = false, ...props }, ref) => {
-  const Comp = asChild ? Slot : "button"
-
-  return (
-    <Comp
-      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 hover:bg-neutral-hover hover:text-fg-secondary [&>svg]:size-4 [&>svg]:shrink-0",
-        "after:absolute after:-inset-2 after:md:hidden",
-        "group-data-[collapsible=icon]:hidden",
-        showOnHover &&
-          "group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-[state=open]:opacity-100 peer-data-[active=true]/menu-button:text-foreground md:opacity-0",
-        className
-      )}
-      {...props}
-    />
-  )
-})
+  Omit<ItemInlineActionButtonProps, "size"> & { showOnHover?: boolean }
+>(({ className, showOnHover = false, ...props }, ref) => (
+  <ItemInlineActionButton
+    ref={ref}
+    data-sidebar="menu-action"
+    className={cn(
+      "absolute right-[var(--layout-space-loose)] top-1/2 -translate-y-1/2",
+      "group-data-[collapsible=icon]:hidden",
+      showOnHover &&
+        "group-focus-within/menu-item:opacity-100 group-hover/menu-item:opacity-100 data-[state=open]:opacity-100 peer-data-[active=true]/menu-button:text-foreground md:opacity-0",
+      // 當前項旁的動作鈕:靜止已是 foreground(上一行),滑過 / 按下**釘住 foreground**,不讓 ItemInlineActionButton 的
+      // `hover:/active:text-fg-secondary` (0,2,0) 把它降回一階(2026-09-25 合成情境量測:淺 #252525→#545454、深 #FFFFFF→#E1E1E1;目前 DS 內無 showOnHover 消費者)。
+      // 依據:inline-action.spec.md「Icon 色彩」的階梯 root invariant `fg-muted → fg-secondary → foreground`,滑過只准往前一階;
+      // 這顆的靜止已站在最高一階 foreground,沒有下一階可升就留在原地,不得往回掉 ——
+      // 同列鈕「選中 × 滑過釘住」的寫法(上方 cva 的 `data-[active=true]:hover:…`)。特異性 (0,3,0) > hover:/active: 的 (0,2,0)。
+      showOnHover &&
+        "peer-data-[active=true]/menu-button:hover:text-foreground peer-data-[active=true]/menu-button:active:text-foreground",
+      className
+    )}
+    {...props}
+  />
+))
 SidebarMenuAction.displayName = "SidebarMenuAction"
 
 // SidebarMenuBadge — 重用專案的 Badge 元件,絕對定位在 menu item 右側
@@ -1333,7 +1550,7 @@ export const sidebarMeta = {
   tokens: {
     bg: ['bg-neutral-hover', 'bg-neutral-selected', 'bg-surface', 'bg-transparent'],
     fg: ['text-fg-muted', 'text-fg-secondary', 'text-foreground'],
-    ring: ['ring-ring'],
+    ring: ['focus-ring-inset'],
   },
   defaultSize: 'md',
 } as const

package/src/components/Skeleton/skeleton.spec.md

@@ -86,7 +86,7 @@ Skeleton 是**純視覺 loading placeholder**,預設 ARIA 行為:
 - **無內建 ARIA**:Skeleton 實作只是一個套用 pulse 動畫的 div(`{...props}` 原樣傳遞),不會自動設任何 ARIA 屬性。SR 不該朗讀 N 條 placeholder shape,因此 consumer 若需要對 SR 隱藏這些佔位塊,應自行在容器設 `aria-hidden="true"`
 - **`aria-busy="true"` 由 consumer 容器 own**:loading region 的容器(如 DataTable / Card / Sidebar group)應設 `aria-busy="true"`,告知 SR「該區域 loading 中」;data ready 後 consumer 移除 `aria-busy` 同時 unmount Skeleton
 - **不取得 focus**:Skeleton 永遠 non-interactive,無鍵盤行為
-- **動畫**:`prefers-reduced-motion: reduce` 用戶自動 stop pulse 動畫(`skeleton.tsx:10` 的 `motion-reduce:animate-none`)。**例外(2026-09-09)**:一次數百格、只活幾十到幾百毫秒的佔位(DataTable 快速捲動的列殼,`data-table.spec.md`「快速捲動的列殼」)傳 `className="animate-none"` 關掉脈動 —— 幾百個透明度動畫會讓光柵每幀重畫、合成器追不上(真實呈現幀消融實測空白幀 42 → 20);形狀、底色、元件都仍是本 Skeleton,只關動畫。pulse 是自動播放的循環動畫,歸 WCAG 2.2.2 Pause, Stop, Hide(Level A);honor `prefers-reduced-motion` 即滿足。注意非 2.3.3 Animation from Interactions(該 SC 是 Level AAA,僅涵蓋由互動 / 捲動觸發的位移動畫,不適用 auto-play loop)
+- **動畫**:`prefers-reduced-motion: reduce` 用戶自動 stop pulse 動畫(`skeleton.tsx:10` 的 `motion-reduce:animate-none`)。**例外(2026-09-09)**:一次數百格、只活幾十到幾百毫秒的佔位(DataTable 快速捲動的列殼,`../DataTable/data-table-scroll-performance.spec.md`「快速捲動的列殼」)傳 `className="animate-none"` 關掉脈動 —— 幾百個透明度動畫會讓光柵每幀重畫、合成器追不上(真實呈現幀消融實測空白幀 42 → 20);形狀、底色、元件都仍是本 Skeleton,只關動畫。pulse 是自動播放的循環動畫,歸 WCAG 2.2.2 Pause, Stop, Hide(Level A);honor `prefers-reduced-motion` 即滿足。注意非 2.3.3 Animation from Interactions(該 SC 是 Level AAA,僅涵蓋由互動 / 捲動觸發的位移動畫,不適用 auto-play loop)
 - **替代文字**:長時間 loading(>3s)consumer 應 fallback 為 `<Empty icon={<CircularProgress/>} description="載入中..." />`(SR-friendly text)— Skeleton 適合 < 3s 短暫 placeholder(3s 為建議換手值;> 10s 仍用 Skeleton 屬「禁止事項」硬性違規)
 - **驗證**:Storybook a11y addon panel 0 critical violation。Skeleton 本身無文字內容、無互動角色,axe 不會要求 label;若 consumer 把 Skeleton 包進有語意的容器,label 由該容器負責
 

package/src/components/Slider/slider.anatomy.stories.tsx

@@ -101,7 +101,7 @@ export const ColorMatrix: Story = {
             <tbody>
               <tr><Td>Track 厚度</Td><Td mono>4px(h-1)</Td><Td>—</Td></tr>
               <tr><Td>Track 底色 default</Td><Td><TokenCell token="--secondary" display="bg-secondary" /></Td><Td><TokenCell token="--secondary" display="--secondary(neutral-3)" /></Td></tr>
-              <tr><Td>Track 底色 disabled</Td><Td><TokenCell token="--muted" display="bg-muted" /></Td><Td><TokenCell token="--muted" display="--muted(neutral-2)" /></Td></tr>
+              <tr><Td>Track 底色 disabled</Td><Td><TokenCell token="--bg-disabled" display="bg-disabled" /></Td><Td><TokenCell token="--bg-disabled" display="--bg-disabled(neutral-2,元件停用狀態色)" /></Td></tr>
               <tr><Td>Range 填滿色 default</Td><Td><TokenCell token="--primary" display="bg-primary" /></Td><Td><TokenCell token="--primary" /></Td></tr>
               <tr><Td>Range 填滿色 disabled</Td><Td><TokenCell token="--border" display="bg-border" /></Td><Td><TokenCell token="--border" display="--border(neutral-5)" /></Td></tr>
               <tr><Td>Thumb 直徑</Td><Td mono>16px(h-4 w-4)</Td><Td>—</Td></tr>

package/src/components/Slider/slider.spec.md

@@ -76,7 +76,7 @@ benchmark:
 |---|---|---|
 | **Track** 厚度 | 4px | — |
 | **Track** 底色 rest | `bg-secondary` | `--secondary`(neutral-3,跟 Tag neutral / Badge low 同級「微淡可辨」)|
-| **Track** 底色 disabled | `bg-muted` | `--muted`(neutral-2,disabled-like 退化)|
+| **Track** 底色 disabled | `bg-disabled` | `--bg-disabled`(neutral-2,元件停用狀態色;2026-09-25 由 `bg-muted` 改,理由見下方「為什麼 Track 底色維持灰色凹槽身分」段)|
 | **Range** 填滿色 rest | `bg-primary` | `--primary` |
 | **Range** 填滿色 disabled | `bg-border`(neutral-5)| `--border` |
 | **Thumb** 直徑 | 16px | — |
@@ -95,7 +95,7 @@ benchmark:
 
 ### 為什麼 Track 底色維持「灰色凹槽」身分,不跟 enabled state 變動
 
-Track 的視覺角色是「可滑動範圍的凹槽底線」,語意不因 enabled / disabled 改變——rest `bg-secondary`(neutral-3)、disabled 退一階 `bg-muted`(neutral-2),都在最淡 subtle bg 層級、凹槽身分不變(disable 時 Range / Thumb border 同步降級 primary → border)。semantic token 優先、不直接引 primitive;**若覺得 track 在 white canvas 上太淡**,那是 `--secondary` / `--muted` 的系統級議題(Badge / Skeleton 一起調),不是在 Slider 裡用 primitive 繞過的理由。
+Track 的視覺角色是「可滑動範圍的凹槽底線」,語意不因 enabled / disabled 改變——rest `bg-secondary`(neutral-3)、disabled 退一階 `bg-disabled`(neutral-2),都在最淡 subtle bg 層級、凹槽身分不變(disable 時 Range / Thumb border 同步降級 primary → border)。**停用底用 `--bg-disabled` 不用 `--muted`(2026-09-25,待辦總帳 C2 / R12 W3)**:這層底只在元件停用時出現,是元件的停用狀態色;owner 取 `../../tokens/color/color.spec.md`「Static Subtle Background」段的邊界句「component disabled bg 不走 muted」(`--muted` 是靜態非互動 surface 的 token,例如 Skeleton)。兩者同值 neutral-2,畫面零變化。semantic token 優先、不直接引 primitive;**若覺得 track 在 white canvas 上太淡**,那是 `--secondary` / `--bg-disabled` 的系統級議題,不是在 Slider 裡用 primitive 繞過的理由。
 
 ### Range 色 ↔ Thumb border 色的綁定規則
 
@@ -176,7 +176,7 @@ Slider 不是 button——它是「當前位置指示器」,底色不該動(動
 
 ### Disabled 視覺階層(三階,不是四階)
 
-`track(muted, n-2)< range = thumb border(border, n-5)< text(n-7+)`——Range 與 Thumb border 刻意同 token 不拆階(見綁定規則);thumb fill(rest 白 / disabled canvas)與 range fill 對比、位置由 range 長度段決定;text 永遠最上層。
+`track(bg-disabled, n-2)< range = thumb border(border, n-5)< text(n-7+)`——Range 與 Thumb border 刻意同 token 不拆階(見綁定規則);thumb fill(rest 白 / disabled canvas)與 range fill 對比、位置由 range 長度段決定;text 永遠最上層。
 
 ### 為什麼 range disabled 用 `--border` 不用 `--fg-disabled`
 
@@ -207,7 +207,7 @@ Opacity 會同時削弱 track、range、thumb 與邊框，讓元件所有層級
 
 ### 常見錯誤(避免)
 
-**不要把 thumb 的 disabled bg 改成 `bg-muted`**——`--muted` 和 `--bg-disabled` 在這個系統都等於 `var(--color-neutral-2)`,同一個顏色。Thumb `bg-muted` 會跟 track `bg-muted` 完全融色,只剩 border 可見,失去 thumb 形狀辨識(真實踩過的 bug)。Disabled 用 **`bg-canvas`**(不透明頁面背景色,與 track 的 muted 不同值且隔 n-5 邊框,不融色)。2026-06-12 補:rest 態原為 `bg-surface`,但 `--surface` 深色 = 8% 白半透明 → thumb 在深色變破洞且 track 穿透,故改 `bg-on-emphasis`(固定白不反轉)。
+**不要把 thumb 的 disabled bg 改成 `bg-muted` 或 `bg-disabled`**——`--muted` 和 `--bg-disabled` 在這個系統都等於 `var(--color-neutral-2)`,同一個顏色,也就是 track 停用底的顏色。Thumb 用它會跟 track 完全融色,只剩 border 可見,失去 thumb 形狀辨識(真實踩過的 bug)。Disabled 用 **`bg-canvas`**(不透明頁面背景色,與 track 停用底不同值且隔 n-5 邊框,不融色)。2026-06-12 補:rest 態原為 `bg-surface`,但 `--surface` 深色 = 8% 白半透明 → thumb 在深色變破洞且 track 穿透,故改 `bg-on-emphasis`(固定白不反轉)。
 
 **不要同時套 opacity + 灰階 swap**——兩個策略互斥,同時用會導致「灰階 swap 後再打 opacity 一層」,視覺雙重降級,整個 slider 褪色過度。選一條路走到底。
 
@@ -275,7 +275,7 @@ Inspector 提供 `min` / `max` / `step` / `defaultValue` × `size` 即時調整(
 - `../SegmentedControl/segmented-control.spec.md` — 離散少量選項的對應元件
 - `../../tokens/uiSize/uiSize.spec.md` — `field-height-*` token family
 - `../../tokens/elevation/elevation.spec.md` — Elevation hover / active 語意
-- `../../tokens/color/color.spec.md` — Primary / muted / fg-disabled token
+- `../../tokens/color/color.spec.md` — Primary / bg-disabled / fg-disabled token
 - `../Field/field.spec.md` — Field 容器整合規則
 - Radix Slider primitive API — `@radix-ui/react-slider`
 
@@ -300,4 +300,5 @@ Inspector 提供 `min` / `max` / `step` / `defaultValue` × `size` 即時調整(
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `number-input.spec.md`
+- `rating.spec.md`
 - `switch.spec.md`

package/src/components/Slider/slider.tsx

@@ -99,14 +99,16 @@ const Slider = React.forwardRef<
       data-readonly={fieldReadonly || undefined}
     >
       {/*
-        Track — rest 用 bg-secondary(n-3,「微淡可辨」),disabled 用 bg-muted(n-2,退化)。
-        跟 Tag neutral / Badge low 同家族。
+        Track — rest 用 bg-secondary(n-3,「微淡可辨」),disabled 用 bg-disabled(n-2,元件停用狀態色)。
+        rest 跟 Tag neutral / Badge low 同家族。
       */}
       <SliderPrimitive.Track className={cn(
         'relative grow overflow-hidden rounded-full h-1',
         // Rest:bg-secondary(n-3,「微淡可辨」的 subtle fill,跟 Tag neutral / Badge low 同級)
-        // Disabled:bg-muted(n-2,「disabled-like 退化」底色)
-        'bg-secondary data-[disabled]:bg-muted',
+        // Disabled:bg-disabled(n-2)。2026-09-25 由 bg-muted 改(待辦總帳 C2 / R12 W3):這層底只在元件停用時出現,
+        // 是元件的停用狀態色,依 color.spec.md「Static Subtle Background」段邊界句「component disabled bg 不走 muted」
+        // 走 --bg-disabled;--muted 是靜態非互動 surface 的 token。兩者同值 neutral-2,畫面零變化。
+        'bg-secondary data-[disabled]:bg-disabled',
       )}>
         {/*
           Range — 填滿段。
@@ -145,8 +147,8 @@ const Slider = React.forwardRef<
             = 8% 白半透明 → thumb 變深色破洞且 track 穿透。
           - Disabled:`bg-canvas`(不透明頁面背景色)— 沉回背景表達「不可動」,
             = Radix disabled thumb 用 gray-1(app background)同款;不透明故 track
-            不穿透。不可用 bg-muted(曾踩 thumb 跟 track 同色融合 bug;canvas 與
-            track 的 muted 隔 n-5 邊框 + 不同值,不融)。
+            不穿透。不可用 bg-muted / bg-disabled(兩者與 track 停用底同值 n-2,曾踩 thumb 跟 track
+            同色融合 bug;canvas 與 track 的停用底隔 n-5 邊框 + 不同值,不融)。
       */}
       {Array.from({ length: thumbCount }).map((_, i) => (
         <SliderPrimitive.Thumb
@@ -163,7 +165,10 @@ const Slider = React.forwardRef<
           className={cn(
             'block h-4 w-4 shrink-0 rounded-full cursor-grab',
             'bg-on-emphasis border-2 border-primary',
-            'transition-all duration-150 motion-reduce:duration-0',
+            // 只過渡陰影(hover / 按壓時的高度),不再過渡外框色:hover 外框一律瞬間(tokens/motion/motion.spec.md「hover 回饋不做過渡」;
+            // 2026-09-26 由底色延伸到外框,待辦總帳 L9 / N4(3));按壓的外框是同一組屬性,一併瞬間(同 Button 按壓,button.tsx 無過渡)。
+            // 原 transition-all 連外框與停用底色一起過渡。陰影升級不在 2026-09-26 同意範圍(motion.spec.md「不在本規則」),維持 150ms。
+            'transition-shadow duration-150 motion-reduce:duration-0',
             // Hover:border 升 hover 階(light mode 淺一階 lift,= Button primary hover 變色邏輯)
             // + elevation 陰影。2026-07-06 修語:原註解寫「加深」但 primary-hover 比 base 淺,
             // 措辭與 token 相反 — token 不遷就錯註解,註解修正。
@@ -224,7 +229,7 @@ export const sliderMeta = {
   },
   states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-muted', 'bg-primary', 'bg-secondary', 'bg-on-emphasis', 'bg-canvas'],
+    bg: ['bg-disabled', 'bg-primary', 'bg-secondary', 'bg-on-emphasis', 'bg-canvas'],
     fg: [],
     ring: [],
   },