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

package/src/lib/roving-list-keyboard.ts

@@ -0,0 +1,400 @@
+/**
+ * @internal — 「列上有小按鈕的一串」鍵盤路線的**唯一**判定與執行(2026-09-26 由四份合一)。
+ *
+ * ── 規則住所 ─────────────────────────────────────────────────────────────────
+ * 規則(Tab 換區、方向鍵在區裡走、Esc 退一步)= `ds-canonical/references/keyboard-model-canonical.md`
+ * 「列上有小按鈕的一串」;本檔是那張按鍵表**唯一的程式版**,四個宿主只讀自己的 DOM、執行結果:
+ *   - `components/Sidebar/sidebar.tsx`        SidebarMenu(真焦點,roving tabindex)
+ *   - `components/FileUpload/file-upload.tsx` 內建檔案清單(真焦點,roving tabindex)
+ *   - `components/TreeView/tree-view.tsx`      樹狀表格(真焦點 + 樹的展開 / 收合 / 回上一層 + 鍵盤重排)
+ *   - `components/Command/command.tsx`         cmdk 清單(「這一項」= 反白列,焦點停在搜尋框 / 清單 = home)
+ *
+ * ── 決定來源 ─────────────────────────────────────────────────────────────────
+ * 路線乙:待辦總帳 `governance/planning/2026-09-25-interaction-and-hover-remediation.md` B9,user 逐字(附條件同意,
+ * 條件查證成立記在同列):「確定建議符合我們一致的設計語言且不違背世界級的設計就照建議」。
+ * 合併與 X1–X7 統一:同檔〇節「09-26 同意清單回覆」,user 逐字:「確保符合我們一致的設計語言且不違背世界級的設計且都有
+ * 確保整個ds 是SSOT,避免漂移就照你建議做」—— 同意的清單含「按鍵規則合併」與批次細節 X1–X35,其中
+ * X4(按鈕上 Home / End)、X6(列上選單鈕按 ↓)、X7(樹在按鈕上 Shift+Tab)三處「統一成側欄做法」。
+ * 2026-09-26 之前這張表有四份平行實作(側欄 / 檔案清單 / 樹 `tree-keyboard-route.ts` / Command),三處互相不一致:
+ *   X4 側欄與檔案清單的按鈕上 Home / End 換到頭尾項,樹不處理;
+ *   X6 側欄的選單鈕按 ↓ 換下一項,樹讓給按鈕開選單;
+ *   X7 側欄在按鈕上 Shift+Tab 一下離開,樹要兩下(先落回本列)—— 違反 B9「Tab 一下離開」。
+ *
+ * ── 本檔兩層 ─────────────────────────────────────────────────────────────────
+ *   (一) 判定(純函式,不碰 DOM):`resolveRovingKey` / `pickRovingTarget` / `pickRovingTabStop`
+ *        —— 判定表 `scripts/test-roving-list-keyboard.mjs`(含舊路線對照組)逐格驗。
+ *   (二) 宿主共用的 DOM 小工具:列裡可走到的東西、把它們收出 Tab 路、真焦點宿主的執行器 `applyRovingAction`。
+ *        Command 是虛擬游標(cmdk 自己搬反白),執行方式不同,在 command.tsx 自己對應 —— 判定仍只讀本檔。
+ */
+
+// ════════════════════════════════════════════════════════════════════════════
+// (一) 判定
+// ════════════════════════════════════════════════════════════════════════════
+
+/** 按鍵發生時,焦點在「這一項」本身,還是這一項裡的某一個東西(小按鈕 / 連結 / 名片頭像…) */
+export type RovingFocus = 'item' | 'control'
+
+/** 樹才有的三個狀態;平面清單不傳 = 沒有「先展開」「回上一層」這兩步 */
+export interface RovingTreeState {
+  hasChildren: boolean
+  expanded: boolean
+  hasParent: boolean
+}
+
+export interface RovingKeyInput {
+  /** KeyboardEvent.key */
+  key: string
+  focus: RovingFocus
+  /** 這一項可以用 → 走到的東西數(宿主以 `listRovingControls` 數出來) */
+  controlCount: number
+  /** focus === 'control' 時焦點在第幾個(0 起算);focus === 'item' 時不讀 */
+  controlIndex: number
+  /** 焦點所在的東西是文字輸入(輸入框 / 多行框 / 下拉 / 可編輯區):方向鍵、Home / End、Enter / 空白鍵都屬於它自己 */
+  controlIsTextEntry?: boolean
+  /** 「這一項」本身是文字輸入(只有 Command 的搜尋框):← / Home / End / 打字屬於插入點 */
+  itemIsTextEntry?: boolean
+  /** itemIsTextEntry 時:插入點已在字尾(且沒有選取範圍)。不在字尾時 → 要留給插入點移動 */
+  caretAtEnd?: boolean
+  /** 樹的狀態;平面清單不傳 */
+  tree?: RovingTreeState
+  /** 可以用 Cmd / Ctrl + Shift + 方向鍵重排(只有 draggable 的樹) */
+  reorderable?: boolean
+  /**
+   * 這一串有「打字跳位」(只有樹:keyboard-model-canonical.md 五條判準第 2 條「需要 tree 那一整套鍵盤模型(打字前導、…)」)。
+   * 焦點在項目上打一個可見字元 → 回 `typeahead`,由宿主找下一個名字以該字開頭的項目;平面清單(側欄 / 檔案清單)不傳 = 不處理。
+   * 出處:W3C APG Tree View 逐字 "Type a character: focus moves to the next node with a name that starts with the typed character."
+   * (<https://www.w3.org/WAI/ARIA/apg/patterns/treeview/>)。
+   */
+  typeahead?: boolean
+  /** 事件已被更外層的捕獲處理程式 preventDefault */
+  defaultPrevented: boolean
+  metaKey: boolean
+  ctrlKey: boolean
+  altKey: boolean
+  shiftKey: boolean
+}
+
+export type RovingReorderKey = 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight'
+export type RovingMove = 'item-prev' | 'item-next' | 'item-first' | 'item-last'
+
+export type RovingKeyAction =
+  /** 不處理 —— 交給瀏覽器、插入點或那個東西自己 */
+  | { type: 'none' }
+  /** 吃掉按鍵(preventDefault)但不動焦點 —— 例:已在最後一顆按鈕上再按 → */
+  | { type: 'consume' }
+  /** 換到上 / 下 / 第一 / 最後一項(焦點落在項目上;不繞回) */
+  | { type: RovingMove }
+  | { type: 'expand' }
+  | { type: 'collapse' }
+  | { type: 'parent' }
+  /** 把焦點放到這一項第 index 個東西 */
+  | { type: 'control'; index: number }
+  /** 焦點回到這一項本身 */
+  | { type: 'item' }
+  /** Tab / Shift+Tab:焦點先回到這一項(整串唯一的 Tab 停靠點),**不擋預設** —— 瀏覽器接著往下 / 往上走一站 = 一下離開這一串 */
+  | { type: 'leave' }
+  /** Enter / 空白鍵在項目上:這一項自己的預設動作(樹 = 選取;原生按鈕 = 瀏覽器自己點) */
+  | { type: 'activate-item' }
+  /** Enter / 空白鍵在項目裡的按鈕 / 連結上:那個東西自己的動作,**不是**「選這一項」 */
+  | { type: 'activate-control' }
+  /** 鍵盤重排(樹;修飾鍵層,與導覽鍵正交) */
+  | { type: 'reorder'; key: RovingReorderKey }
+  /** 打字跳位(只有 `typeahead: true` 的宿主):焦點在項目上打了一個可見字元,由宿主找下一個名字以它開頭的項目 */
+  | { type: 'typeahead'; char: string }
+
+const REORDER_KEYS: readonly string[] = ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight']
+const isReorderKey = (key: string): key is RovingReorderKey => REORDER_KEYS.includes(key)
+
+/**
+ * 按鍵表(規格 SSOT = keyboard-model-canonical.md「列上有小按鈕的一串」;每一格的來歷寫在該格旁):
+ *
+ * | 鍵 | 焦點在項目上 | 焦點在這一項的東西上 |
+ * |---|---|---|
+ * | ↑ ↓ | 上 / 下一項 | 回到上 / 下一項(X3,依 Adobe 方向鍵模式;選單鈕也一樣 —— X6 統一成側欄做法) |
+ * | Home End | 第一 / 最後一項 | 同左(X4 統一成側欄做法) |
+ * | → | 樹裡收著的資料夾先展開;否則進第一個東西;沒有就不動 | 下一個;最後一個停住 |
+ * | ← | 樹:展開的先收合、否則回上一層;平面清單:不動 | 上一個;第一個 → 回項目 |
+ * | Tab / Shift+Tab | 一下離開這一串 | 同左(X7:先回項目、再由瀏覽器往外走) |
+ * | Enter / 空白鍵 | 這一項自己的預設動作 | 那個東西自己的動作 |
+ * | 可見字元(只有 `typeahead` 宿主 = 樹)| 打字跳位:下一個名字以它開頭的項目(W3C APG Tree View) | 不處理(按鈕上打字沒有意義) |
+ */
+export function resolveRovingKey(input: RovingKeyInput): RovingKeyAction {
+  const { key } = input
+  if (input.defaultPrevented) return { type: 'none' }
+
+  // 鍵盤重排:修飾鍵層,只從項目上發動(tree-view.spec.md「鍵盤重排」,行為不變)
+  if (input.focus === 'item' && input.reorderable && (input.metaKey || input.ctrlKey) && input.shiftKey && isReorderKey(key)) {
+    return { type: 'reorder', key }
+  }
+  // 帶 Cmd / Ctrl / Alt 的組合留給瀏覽器、輔助科技與按鈕自己(例:Alt+↓)。Shift 不在內:Shift+Tab 是導覽鍵。
+  if (input.metaKey || input.ctrlKey || input.altKey) return { type: 'none' }
+
+  // Tab / Shift+Tab:不論焦點在項目或項目裡的東西上,都是一下離開這一串(B9;X7)
+  if (key === 'Tab') return { type: 'leave' }
+
+  // ── 焦點在這一項裡的東西上 ──
+  if (input.focus === 'control') {
+    // 文字輸入:方向鍵移插入點、Enter / 空白鍵是打字,全部屬於它(原樹的 isButtonLike 例外,現全宿主一致)
+    if (input.controlIsTextEntry) return { type: 'none' }
+    switch (key) {
+      case 'ArrowRight':
+        // 已是最後一個 → 不動(W3C 樹狀表格:最右一格按 → 焦點不移動)
+        return input.controlIndex < input.controlCount - 1
+          ? { type: 'control', index: input.controlIndex + 1 }
+          : { type: 'consume' }
+      case 'ArrowLeft':
+        // 已是第一個 → 回到這一項(B9「← 回項目」)
+        return input.controlIndex > 0 ? { type: 'control', index: input.controlIndex - 1 } : { type: 'item' }
+      case 'ArrowDown':
+        // X6:選單鈕(aria-haspopup)也一樣換下一項 —— 開選單用 Enter / 空白鍵(同側欄帳號列,sidebar.spec.md)
+        return { type: 'item-next' }
+      case 'ArrowUp':
+        return { type: 'item-prev' }
+      case 'Home':
+        // X4:同側欄 / 檔案清單 —— 換到第一 / 最後一項
+        return { type: 'item-first' }
+      case 'End':
+        return { type: 'item-last' }
+      case 'Enter':
+      case ' ':
+        return { type: 'activate-control' }
+      default:
+        return { type: 'none' }
+    }
+  }
+
+  // ── 焦點在項目本身(Command:焦點在 home、反白在這一列)──
+  if (input.itemIsTextEntry) {
+    // 搜尋框:插入點已在字尾、沒有按 Shift(Shift+→ 是選取文字)時,→ 才進反白列的第一個東西(AI 推導,command.spec.md「A11y」)
+    if (key === 'ArrowRight') {
+      return !input.shiftKey && input.caretAtEnd !== false && input.controlCount > 0
+        ? { type: 'control', index: 0 }
+        : { type: 'none' }
+    }
+    if (key === 'ArrowDown') return { type: 'item-next' }
+    if (key === 'ArrowUp') return { type: 'item-prev' }
+    // ← / Home / End / Enter / 空白鍵 / 打字:屬於搜尋框與清單函式庫
+    return { type: 'none' }
+  }
+  switch (key) {
+    case 'ArrowDown':
+      return { type: 'item-next' }
+    case 'ArrowUp':
+      return { type: 'item-prev' }
+    case 'Home':
+      return { type: 'item-first' }
+    case 'End':
+      return { type: 'item-last' }
+    case 'ArrowRight': {
+      // 樹裡收著的資料夾 → 先展開(B9);已展開的資料夾或葉節點、平面清單 → 進第一個東西;沒有就不動
+      const tree = input.tree
+      if (tree && tree.hasChildren && !tree.expanded) return { type: 'expand' }
+      return input.controlCount > 0 ? { type: 'control', index: 0 } : { type: 'consume' }
+    }
+    case 'ArrowLeft': {
+      // 樹:展開的資料夾 → 收合;否則 → 回上一層;最外層不動。平面清單:不動(B9「← 在列上維持樹的語意」)
+      const tree = input.tree
+      if (tree && tree.hasChildren && tree.expanded) return { type: 'collapse' }
+      return tree && tree.hasParent ? { type: 'parent' } : { type: 'consume' }
+    }
+    case 'Enter':
+    case ' ':
+      return { type: 'activate-item' }
+    default:
+      // 打字跳位(樹):單一可見字元(空白鍵已在上面 = 選取;Shift+字母 也是一個可見字元,大小寫由宿主比對時折疊)
+      if (input.typeahead && key.length === 1 && key !== ' ') return { type: 'typeahead', char: key }
+      return { type: 'none' }
+  }
+}
+
+/**
+ * 上 / 下 / 第一 / 最後一項落在哪 —— **不繞回**(同 W3C grid / tree;X2)。
+ * `items` 依畫面順序、含走不到的項目(停用、看不見);`isNavigable` 決定哪些能當落點。
+ * 目前這一項本身走不到(例:樹裡用 ← 回到停用的上一層)時,仍從它的位置往前 / 往後找。
+ */
+export function pickRovingTarget<T>(
+  move: RovingMove,
+  items: readonly T[],
+  current: T | null,
+  isNavigable: (item: T) => boolean = () => true,
+): T | null {
+  if (move === 'item-first') return items.find(isNavigable) ?? null
+  if (move === 'item-last') {
+    for (let i = items.length - 1; i >= 0; i--) if (isNavigable(items[i])) return items[i]
+    return null
+  }
+  const start = current == null ? -1 : items.indexOf(current)
+  if (start < 0) return null
+  const dir = move === 'item-next' ? 1 : -1
+  for (let i = start + dir; i >= 0 && i < items.length; i += dir) {
+    if (isNavigable(items[i])) return items[i]
+  }
+  return null
+}
+
+export interface RovingTabStopOptions<T> {
+  /** 上次焦點停過的那一項 */
+  remembered?: T | null
+  /** 「目前這一頁 / 選中」那一項(側欄 aria-current="page";樹 aria-selected) */
+  isCurrent?: (item: T) => boolean
+  /** 能不能當「目前」或「第一項」的落點(停用、看不見的不算) */
+  isNavigable?: (item: T) => boolean
+  /** 上次停過的那一項還能不能拿焦點(預設同 isNavigable;樹的停用列仍可經 ← 拿到焦點,傳 () => true) */
+  canHoldFocus?: (item: T) => boolean
+}
+
+/**
+ * 整串唯一的 Tab 停靠點(X1):上次停過的那一項 → 目前這一頁 / 選中那一項 → 第一個可用項。
+ * 出處:W3C「the element that had focus the last time the composite contained focus」+ 導覽樹範例
+ * 「focus always lands on the item representing the current page」(keyboard-model-canonical.md 同節引文)。
+ */
+export function pickRovingTabStop<T>(items: readonly T[], options: RovingTabStopOptions<T> = {}): T | null {
+  const isNavigable = options.isNavigable ?? (() => true)
+  const canHoldFocus = options.canHoldFocus ?? isNavigable
+  const { remembered, isCurrent } = options
+  if (remembered != null && items.includes(remembered) && canHoldFocus(remembered)) return remembered
+  const current = isCurrent ? items.find((item) => isNavigable(item) && isCurrent(item)) : undefined
+  return current ?? items.find(isNavigable) ?? null
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// (二) 宿主共用的 DOM 小工具
+// ════════════════════════════════════════════════════════════════════════════
+
+/**
+ * 項目裡「可以走到的東西」的候選(再經 `isRovingControlReachable` 過濾)。
+ * 2026-09-26 之前四份各寫一份、各差一點(樹多認 contenteditable、側欄只認按鈕類),合成這一份;
+ * 側欄另有自己的範圍(只認動作鈕的兩個出口),以參數傳入。
+ */
+export const ROVING_CONTROL_SELECTOR =
+  'a[href], button, input, select, textarea, [contenteditable]:not([contenteditable="false"]), [tabindex]'
+
+/** 把候選 selector 限定在某個範圍裡(`[cmdk-item] a[href], [cmdk-item] button, …`)。不用 `:is()`:舊版 jsdom 不認得。 */
+export function scopeRovingSelector(scope: string, selector: string = ROVING_CONTROL_SELECTOR): string {
+  return selector.split(',').map((part) => `${scope} ${part.trim()}`).join(', ')
+}
+
+/**
+ * 文字輸入(方向鍵、Home / End、打字屬於它自己)。沒有插入點的 input type 不算(同 React Aria `nonTextInputTypes`)。
+ * 全 DS 只有這一份:清單鍵盤(本檔)、反白來歷(hooks/use-input-modality.ts)、下拉的空白鍵(SelectMenu/select-menu-keyboard.ts)
+ * 都讀它(2026-09-26 之前各寫一份)。
+ */
+const NON_TEXT_INPUT_TYPES = new Set(['checkbox', 'radio', 'range', 'color', 'file', 'image', 'button', 'submit', 'reset', 'hidden'])
+export function isTextEntryElement(el: Element): boolean {
+  if (el.tagName === 'TEXTAREA' || el.tagName === 'SELECT') return true
+  if (el.tagName === 'INPUT') return !NON_TEXT_INPUT_TYPES.has((el as HTMLInputElement).type)
+  return (el as HTMLElement).isContentEditable === true
+}
+
+/**
+ * 此刻走得到:沒有停用、不在 inert / aria-hidden 裡(例:多選列的勾選框是 inert + aria-hidden 的純視覺)、
+ * 畫得出來(display:none 不算;opacity 0 的「滑過才出現」按鈕算 —— 鍵盤走到時它會浮出)。
+ */
+export function isRovingControlReachable(el: HTMLElement): boolean {
+  return (
+    !(el as HTMLButtonElement).disabled &&
+    !el.closest('[inert], [aria-hidden="true"]') &&
+    el.getClientRects().length > 0
+  )
+}
+
+/** 某一項裡可以走到的東西,依畫面(文件)順序。 */
+export function listRovingControls(root: Element, selector: string = ROVING_CONTROL_SELECTOR): HTMLElement[] {
+  return Array.from(root.querySelectorAll<HTMLElement>(selector)).filter(isRovingControlReachable)
+}
+
+/** 只在值不同時才寫:同值 setAttribute 也會產生 mutation record,會讓宿主的 MutationObserver 自我觸發。 */
+export function setRovingTabIndex(el: HTMLElement, value: 0 | -1): void {
+  if (el.getAttribute('tabindex') !== String(value)) el.setAttribute('tabindex', String(value))
+}
+
+/**
+ * 項目裡的東西一律不在 Tab 路上(-1,→ 才進得去;別項與本項的都一樣)。
+ * 用 DOM 設而不是逐一傳 prop:consumer 的插槽(inlineActionsSlot / description / 名片頭像)是任意 ReactNode,拿不到它們的 props。
+ */
+export function removeRovingControlsFromTabOrder(elements: Iterable<HTMLElement>): void {
+  for (const el of elements) setRovingTabIndex(el, -1)
+}
+
+/** 真焦點宿主(側欄 / 檔案清單 / 樹)執行判定結果時要的東西 */
+export interface RovingDomHost {
+  event: { preventDefault(): void }
+  /** 目前這一項(整串唯一的 Tab 停靠點就在這種元素上) */
+  item: HTMLElement
+  /** 這一項可以走到的東西(已過濾,`listRovingControls`) */
+  controls: readonly HTMLElement[]
+  /** 整串的項目,依畫面順序(含走不到的;由 isNavigable 篩) */
+  items: readonly HTMLElement[]
+  isNavigable?: (item: HTMLElement) => boolean
+  /** 樹傳 { preventScroll: true }(捲動由列自己的 scrollIntoView 以 block:nearest 處理) */
+  focusOptions?: FocusOptions
+  /** 樹才有:展開 / 收合 / 回上一層 */
+  onExpand?: () => void
+  onCollapse?: () => void
+  onParent?: () => void
+  /** 項目本身的預設動作要由宿主執行時才傳(樹 = 選取);不傳 = 項目是原生按鈕,交給瀏覽器 */
+  onActivateItem?: () => void
+  /** 打字跳位(只有 `typeahead: true` 的宿主):宿主自己累積字串、找項目、搬焦點 */
+  onTypeahead?: (char: string) => void
+}
+
+/**
+ * 真焦點宿主的執行器:判定之外只剩「焦點怎麼搬、要不要擋預設」,三個宿主完全相同,所以也只寫一份。
+ * `reorder` 不在這裡(樹自己處理:要看是否正在用滑鼠拖曳)。
+ */
+export function applyRovingAction(action: RovingKeyAction, host: RovingDomHost): void {
+  const { event, item, controls, focusOptions } = host
+  switch (action.type) {
+    case 'none':
+    case 'reorder':
+    case 'activate-control':
+      // 按鈕 / 連結的 Enter、空白鍵是瀏覽器原生行為;這裡不擋也不代點
+      return
+    case 'leave':
+      // 焦點在項目裡的東西上時先放回這一項(整串唯一那顆 0),**不擋預設**:瀏覽器接著從這一項往下 / 往上走 = 一下離開。
+      // 往前若不先放回,Shift+Tab 會先落回本項(X7 修的就是這個);往後在焦點鎖(手機抽屜 = Radix FocusScope)裡,
+      // 鎖判斷「是不是最後一顆」看的是 tabindex≥0 的元素,-1 的按鈕永遠不是它 → 不先放回就繞不回開頭
+      //(@radix-ui/react-focus-scope@1.1.7 dist/index.mjs:106-121)。焦點已在這一項上時 focus() 不做任何事。
+      item.focus(focusOptions)
+      return
+    case 'activate-item':
+      if (!host.onActivateItem) return
+      event.preventDefault()
+      host.onActivateItem()
+      return
+    case 'typeahead':
+      // 判定只在 typeahead 宿主才會回這格;擋預設是為了不讓 Firefox「輸入時搜尋」之類的瀏覽器功能吃掉字元
+      if (!host.onTypeahead) return
+      event.preventDefault()
+      host.onTypeahead(action.char)
+      return
+    default:
+      break
+  }
+  event.preventDefault()
+  switch (action.type) {
+    case 'consume':
+      return
+    case 'item-prev':
+    case 'item-next':
+    case 'item-first':
+    case 'item-last':
+      pickRovingTarget(action.type, host.items, item, host.isNavigable)?.focus(focusOptions)
+      return
+    case 'control':
+      controls[action.index]?.focus(focusOptions)
+      return
+    case 'item':
+      item.focus(focusOptions)
+      return
+    case 'expand':
+      host.onExpand?.()
+      return
+    case 'collapse':
+      host.onCollapse?.()
+      return
+    case 'parent':
+      host.onParent?.()
+      return
+  }
+}

package/src/lib/utils.ts

@@ -76,6 +76,11 @@ const twMerge = extendTailwindMerge({
       // Custom opacity utility(對應 tokens/opacity/opacity.css `@utility opacity-disabled`)。
       // 不註冊 group → tailwind-merge 用 default opacity-N heuristic,可能誤判 class 衝突。
       'opacity': ['opacity-disabled'],
+      // 「底」的滑過 / 按住疊層(對應 tokens/color/semantic.css `@utility bg-interaction-hover / -active`;
+      // color.spec.md「Hover 換色配對總則」,待辦總帳 B8)。它們寫的是 background-image,不是底色 ——
+      // 不註冊的話 tailwind-merge 把 `bg-*` 一律猜成 bg-color,`cn('bg-surface', 'bg-interaction-hover')`
+      // 會把 bg-surface 刪掉,底色整個消失(2026-09-25 以 tailwind-merge 3.5 實測)。登記在 bg-image 才對得上它真正寫的屬性。
+      'bg-image': ['bg-interaction-hover', 'bg-interaction-active', 'bg-interaction-selected', 'bg-interaction-selected-hover', 'bg-interaction-selected-active'],
     },
   },
 })

package/src/patterns/action-bar/action-bar.spec.md

@@ -483,6 +483,7 @@ Icon 的目的是幫助辨識，不是視覺對稱。
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `alert.spec.md`
 - `bulk-action-bar.spec.md`
 - `button.spec.md`
 - `calendar.spec.md`
@@ -490,3 +491,4 @@ Icon 的目的是幫助辨識，不是視覺對稱。
 - `file-viewer.spec.md`
 - `popover.spec.md`
 - `separator.spec.md`
+- `toast.spec.md`

package/src/patterns/element-anatomy/inline-action.spec.md

@@ -69,15 +69,19 @@ Inline action icon 色彩規則 **依 host 是否有自帶色彩分兩支**。
 
 ### 尺寸對照
 
-| 宿主 | Icon 視覺 | Hover 背景 | 圓角 | 排版佔位 |
-|---|---|---|---|---|
-| Tag sm (20px) | 16px | 18px | rounded-md | 16px |
-| Tag md/lg (24px) | 16px | 18px | rounded-md | 16px |
-| Field sm/md | 16px | 18px | rounded-md | 16px |
-| Field lg | 20px | 22px | rounded-md | 20px |
-| TreeItem sm/md | 16px | 18px | rounded-md | 16px |
-| TreeItem lg | 20px | 22px | rounded-md | 20px |
-| Panel list row(visibility / sort / filter panels)| 16px | 18px | rounded-md | 16px |
+| 宿主 | Icon 視覺 | Hover 背景 | 圓角 | 可點範圍 | 排版佔位 |
+|---|---|---|---|---|---|
+| Tag sm (20px) | 16px | 18px | rounded-md | 18px | 16px |
+| Tag md/lg (24px) | 16px | 18px | rounded-md | 18px | 16px |
+| Field sm/md | 16px | 18px | rounded-md | 18px | 16px |
+| Field lg | 20px | 22px | rounded-md | 22px | 20px |
+| TreeItem sm/md | 16px | 18px | rounded-md | 18px | 16px |
+| TreeItem lg | 20px | 22px | rounded-md | 22px | 20px |
+| Panel list row(visibility / sort / filter panels)| 16px | 18px | rounded-md | 18px | 16px |
+
+**「可點範圍」欄恆等於「Hover 背景」欄**(user 2026-09-24 逐字:「重點是要讓 inline action 的可點擊範圍跟其 hover 底色一樣吧?都是 18*18」)——
+那塊底色就是使用者看得到的形狀,看得到的每一點都要點得到。跨元件規則與唯一例外的 owner = `ds-canonical/references/hit-area-canonical.md`;
+本表只放本元件的值,不重述規則。**排版佔位不變,仍是 icon 尺寸**(16 / 20):多出來的 2px 靠溢出(absolute / negative margin)承擔,不吃版位 —— 見上方「視覺規則」3 與下方 Consumer wrapping rule。
 
 **Consumer wrapping rule**:當 consumer 包 `ItemInlineActionButton` 在 reserve slot(如 hover-reveal opacity wrapper),**reserve 寬度 = 排版佔位**(sm/md=16,lg=20),**禁止自訂為 24 / 28**(過大會在 cell 留 phantom space)。歷史:DataTable header reserve 24 → 16 修正(2026-04-29)。
 
@@ -87,7 +91,7 @@ Inline action icon 色彩規則 **依 host 是否有自帶色彩分兩支**。
 
 - **間距**:`gap-2`(8px)——跟 fieldWrapperStyles 的元素間距一致(Select 的 clear X 和 ChevronDown 就是 gap-2)
 - **對齊**:全部垂直置中在同一行(`flex items-center`)
-- **出現時機**:全部一起出現(TreeItem 的 hover-reveal 是同時淡入所有 action,不逐個)
+- **出現時機**:全部一起出現(TreeItem 的 hover-reveal 是同時出現所有 action,不逐個);**瞬間出現、不淡入**(owner = `tokens/motion/motion.spec.md`「hover 回饋不做過渡」,2026-09-26 延伸到滑過才出現的按鈕;實作 = `item-anatomy.tsx` 的 `SUFFIX_HOVER_REVEAL_BY_GROUP`)
 
 ### API 設計
 
@@ -191,7 +195,7 @@ Row action 的 affordance 是「次要功能」,不是 primary CTA。Button chro
 ```
 
 **chrome corner action group(Alert / Toast / Dialog / Popover header corner)** 屬 **Button family**(action group region,不是 inline action)。Canonical 不在本 spec — 詳:
-- 尺寸:`patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」(overlay sm + v5 trick / banner xs explicit)
+- 尺寸:`patterns/overlay-surface/overlay-chrome-sizing.spec.md`「Chrome dismiss size canonical」(overlay sm + v5 trick / banner xs explicit)
 - variant / divider:`patterns/action-bar/action-bar.spec.md`(corner action group)
 
 ### 邊界案例
@@ -317,7 +321,7 @@ hook `check_story_invariants.sh` R1(原 `check_story_anatomy.sh` 規則 B,已 fo
 - `data-table.spec.md`
 - `field-controls.spec.md`
 - `item-anatomy.spec.md`
-- `overlay-surface.spec.md`
+- `overlay-chrome-sizing.spec.md`
 - `popover.spec.md`
 - `sheet.spec.md`
 - `sidebar.spec.md`

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

@@ -190,6 +190,96 @@ rg 'grid-cols-\[[0-9]+px_1fr\]' packages/design-system/src -g '*.tsx'
 - **Row message(訊息列,2026-09-08 user 拍板)**: 用 `MenuItem message={true}` 模式——選單裡「不是選項的列」(沒有結果 / 沒有選項 / 載入中)。與 Row header 同族:`text-fg-muted pointer-events-none` + 與 items **完全相同**的 row geometry;差別是**一般字重**、內容**置中**、可帶前綴槽(列圖示尺寸的 `CircularProgress` 等)。必住在 group 裡(見「Group auto-separation」);一列訊息與一列選項等高,不撐最小高度。owner `components/SelectMenu/select-menu.spec.md`「Empty state」;樣式 `components/Menu/menu-item.spec.md`「Message row(訊息列)」
 - **可收合 section header 組合 canonical**(2026-07-08 R3-7 拍板 + 2026-07-10 codify 進 DS;**組合非元件** — SectionHeader 留產品客製,但 layout 全消費本 canonical):(1) chevron = **title 後的 suffix inline action**(非 prefix、非獨立按鈕群);(2) 可選 description 與 title 間距用 `--item-gap-label-desc-*` token;(3) endSlot(操作鈕)只有 title 一行時垂直置中;(4) 同構標題列 ≥ 2 份必抽共用元件(WM `SectionHeader.tsx` 錨例 — Description / Attachments / Child work items 三份同構收斂)。手刻簽名(Chevron + justify-between + 可點且無共用元件)由 consumer 防線攔(escape `@section-header-ok:`)。
 
+### 整列可點時,誰當那顆控件(2026-09-24 立;本節是全家族唯一 owner,消費者禁自行發明)
+
+### 這一節在回答什麼(先講目的)
+
+**目的只有一個:拿到一份「列」的設計需求時,不必看任何既有元件,就能推出它該長什麼樣、怎麼操作。**
+
+它要防的失敗是具體的:DS 裡已經有 `SidebarMenuButton`(列自己是一顆按鈕)與 `FileItem`(列不是按鈕、鍵盤由一顆隱形控件承接)兩種做法。沒有這一節,下一個人建新列元件時**只能挑一個看起來像的來抄**,而抄錯的那一半會在無障礙與鍵盤上靜默壞掉。
+
+### ⛔ 2026-09-24 重寫:先前這一節是從實作切入的
+
+原本的四題,第二題是「動作鈕排到外面後,剩下的內容裝不裝得進一顆 `<button>`?」——**那不是設計問題,那是 HTML 的限制。** user 逐字:「我要的是從設計面去定義這些,而不是導果為因,我他媽今天講了一百次了」(commit `c8821266` 訊息第 3 行;2026-09-27 補回先前被截掉的後半句)。把 markup 的限制寫成判準,等於用「能怎麼蓋」回答「這是什麼」。下面改成先問設計,實作是後果。
+
+---
+
+### 第一層(設計):這一串是**一組去處**,還是**一組東西**?
+
+這是最根本的一刀,而且**不是本檔歸納的,是世界級各家自己的分類**:
+
+| 出處 | 逐字 |
+|---|---|
+| **Ant Design** 原始碼 frontmatter(釘 6.6.5) | [`components/menu/index.en-US.md#L3-L5`](https://github.com/ant-design/ant-design/blob/6.6.5/components/menu/index.en-US.md#L3-L5):`group: Navigation`,描述 "A versatile menu for **navigation**"<br>[`components/tree/index.en-US.md#L3-L5`](https://github.com/ant-design/ant-design/blob/6.6.5/components/tree/index.en-US.md#L3-L5):`group: **Data Display**",描述 "Multiple-level structure list" |
+| **Primer** `content/ui-patterns/navigation.mdx`(釘 2026-09-27 抓到的 main HEAD) | "A tree view **isn't semantically a form of navigation**: it's for **activating an option from a hierarchical list**."([`navigation.mdx#L150`](https://github.com/primer/design/blob/87f799f202ec95df15c99f473c9c0c803da8e6b3/content/ui-patterns/navigation.mdx#L150)) |
+| **Carbon** tree-view usage「When not to use」(釘 carbon-website `d8783ad2`) | "**As the primary navigation in a product's UI.** Instead, use the UI Shell left panel for product navigation."([`tree-view/usage.mdx#L92`](https://github.com/carbon-design-system/carbon-website/blob/d8783ad2ae3b5e59c58f58311491f8a2c4e62631/src/pages/components/tree-view/usage.mdx#L92))<br>⚠️ **這句的範圍是「主導覽」,不是「側邊欄」** —— 跟 Primer 那句 "global sidebar navigation" 同一層級。它支持的是「樹不是導覽」這個分類,**不是「側邊欄不能有樹」**。Notion 的側邊欄下半就是樹。2026-09-24 我先前就是把 Primer 同類的句子裸引而讀成禁令,user 逐字戳破;這裡同樣不得裸引 —— 判準住在 `ds-canonical/rules/meta-patterns.md` M22 的子規則「引用『不要拿 X 當 Y』必須帶 Y 的範圍」,本檔不重述。 |
+
+**兩類東西,不是同一類的兩種做法:**
+
+- **一組去處(導覽)**:使用者對它做的唯一的事是**去那裡**。項目本身沒有被操作的價值,只有被抵達的價值。它由產品定義,使用者不能改動它。
+- **一組東西(資料)**:項目本身就是**被操作的對象**。使用者會挑它、對它做事、看它的狀態。它通常由使用者產生,而且能被改動。
+
+**判斷句**:問「使用者對這一項**做**什麼?」——答「去某個地方」= 去處;答「挑它、然後對它做某件事」= 東西。
+
+### 第二層(只對「一組東西」問):使用者會不會把這一整串當成**一個東西**來操作?
+
+- **會** —— 會一次挑好幾個一起處理、會在裡面搬移、項目多到需要快速跳。→ 它在使用者心中就是**一個東西**,所以鍵盤上也該是一個東西:整串一個停靠點,進去之後用方向鍵。
+- **不會** —— 每一筆各自處理,彼此沒有「一起」的概念。→ 每一筆各自獨立,預設各自一個停靠點;但**列上帶小按鈕的一串**(側欄、FileUpload 內建檔案清單…)因停靠點太多另收成一站 —— 那是第二個理由,規則與適用範圍只住 `keyboard-model-canonical.md`「列上有小按鈕的一串」(2026-09-25 待辦總帳 B9)。
+
+**這一層的完整判準(五條)與一手依據住在 `ds-canonical/references/keyboard-model-canonical.md`**,本節不重述。那五條講的是同一件事的可操作版本:節點會不會被選取並施加動作、需不需要那一整套鍵盤、深度有沒有上界、內容是不是使用者產生且可改動、啟動會不會換 URL。
+
+### 第三層(對每一列問):這一列除了主要動作,還有沒有別的動作?
+
+- **沒有** —— 整列就是一個目標。
+- **有** —— 那些動作**各自是獨立的目標**,不能被主要動作吞掉。
+  這就是為什麼「按刪除不該連帶把檔案打開」不是體貼,是必須。
+
+---
+
+### 實作是**後果**,不是判準
+
+上面三層一旦答完,markup 只剩一種寫法 —— 因為 HTML 與 ARIA 把其餘的路堵死了。
+**這一段列的是後果,不要拿它來做設計決定。**
+
+| 設計面的事實 | 被規範堵死的後果 | 規範依據 |
+|---|---|---|
+| 這一列裡有**必須被唸出來的狀態**(進度、頭像、多段說明) | 列**不能**是一顆按鈕 —— 按鈕裡的東西會被輔助科技當成裝飾唸掉,進度百分比會消失 | ARIA `button` 的 Children Presentational:"The DOM descendants are presentational. User agents SHOULD NOT expose descendants of this element through the platform accessibility API." |
+| 這一列裡有**可以聚焦的子元素** | 列**不能**是一顆按鈕 —— 直接踩 content model 明文 | WHATWG HTML `<button>`:"Phrasing content, but there must be no interactive content descendant and **no descendant with the `tabindex` attribute specified**." |
+| 這一列是「一個東西的一部分」(第二層答「會」) | 列拿 `treeitem` / `row` / `option` / `gridcell`,**整組只有一個鍵盤停靠點**,由容器管理焦點(列上 roving tabindex,或容器 `aria-activedescendant`) | WAI-ARIA §4.3.1:"Authors MUST manage focus on the following container roles";`composite`:"SHOULD ensure that a composite widget exists as a single navigation stop" |
+| 列不是按鈕、又必須可鍵盤操作 | 列內鋪一顆**覆蓋整列的原生控件**;它不可見,所以焦點框改畫在列上 | 焦點框畫在別的元素上的規則 → `ds-canonical/references/focus-canonical.md` |
+
+**先前那一版把上表第一、二列寫成「第 2 題」,等於用 HTML 的限制當設計判準。** 已撤回。
+
+### 走一遍:當初引發這一連串問題的兩個元件
+
+user 2026-09-24 原始提問:「所有可以被點擊且其中提供按鈕的 list item 都會有一樣問題?」
+「就結果是一樣的,但為何設計方式是不一樣的?是否是合理的?未來遇到這種有多 action 且自身可以點擊的
+list item 元件都是要用類似的處理方式?」
+
+| | `SidebarMenuButton` | `FileItem` | `TreeItem` |
+|---|---|---|---|
+| **第一層:去處還是東西?** | **一組去處** —— 每條通往不同頁面,使用者對它做的唯一的事是「去那裡」 | **一組東西**,但不是一個整體 —— 每個檔案是被操作的對象(有狀態、有動作),但使用者不會把它們當成一個東西一起處理 | **一組東西,而且是一個整體** —— 使用者會一次挑好幾個、在裡面搬移、項目多到需要快速跳 |
+| **列裡有沒有必須被念出來的狀態 / 可聚焦子元素?**(實作後果) | **沒有** —— 只有圖示與文字,所以列可以是一顆按鈕 | **有** —— 進度條(自帶 `role="progressbar"`)、頭像、可聚焦的 hover 按鈕,所以列**不能**是按鈕 | 不適用 —— 第一層已經決定它是一個整體,列拿 `row`(樹狀表格;2026-09-25 前是 `treeitem`) |
+| **誰承接鍵盤?**(實作後果) | **列本身**(它就是那顆 `<button>`)| **列內一顆覆蓋整列的透明控件**,焦點框畫在列上 | **列本身**(整棵樹同一時間只有一列 `tabIndex=0`;2026-09-25 前是容器 + `aria-activedescendant`,待辦總帳 B9) |
+| **一串幾個 Tab 停靠點?**(不歸本節,住 `ds-canonical/references/keyboard-model-canonical.md`「列上有小按鈕的一串」) | 一串一站 + 方向鍵(B9) | 單獨成串:每列一站、每顆動作鈕各一站;在 FileUpload 內建清單(有 `onRemove`):一串一站 + 方向鍵(B9) | 一棵樹一站 + 方向鍵 |
+
+**所以對原始問題的答案是:`SidebarMenuButton` 與 `FileItem` 設計上不一樣的只有「焦點停在哪個元素上」,而那不是選擇,是 HTML content model 逼出來的**:FileItem 的列裡有進度條與可聚焦按鈕,包進 `<button>` 會讓輔助科技讀不到(children-presentational),還直接踩 content model 明文禁止的 `tabindex` 那一句。與 `TreeItem` 的差別在第一層(樹是一個整體),不是「列裡裝了什麼」。
+
+**一串有幾個 Tab 停靠點是另一件事,不由本節決定**:2026-09-24 從頁首連按 Tab 實測時,FileItem 與側欄都是「每列一站 + 每顆動作鈕各一站」、樹整棵一站(量測原文見本檔 git 歷史 `16c8e2f5` 版);2026-09-25 user 選路線乙之後,側欄與 FileUpload 內建檔案清單改成一串一站 + 方向鍵,規則與適用範圍只住 `keyboard-model-canonical.md`「列上有小按鈕的一串」(待辦總帳 B9)。
+
+### 這條程序涵蓋所有情況嗎(逐枝窮舉)
+
+| 第一層 | 第二層 | 列裡有沒有必須被念出來的狀態 / 可聚焦子元素 | 結果 | 本 DS 實例 |
+|---|---|---|---|---|
+| **一組去處** | 不適用 | 沒有 | 列 = `<button>` / `<a>`,動作鈕是絕對定位的同層兄弟 | `SidebarMenuButton`、`MenuItem` |
+| **一組去處** | 不適用 | 有 | 列 = 非互動容器 + 覆蓋整列的透明控件,焦點框畫在列上 | DS 內目前無實例(去處很少帶狀態) |
+| **一組東西**,不是整體 | — | 沒有 | 列 = `<button>` | `MenuItem`(當它裝的是選項而非去處)|
+| **一組東西**,不是整體 | — | 有 | 列 = 非互動容器 + 覆蓋控件,焦點框畫在列上 | **`FileItem`** |
+| **一組東西,而且是整體** | — | — | 列拿 `treeitem` / `row` / `option` / `gridcell`,整組一個停靠點 + 方向鍵(列上 roving tabindex 或容器 `aria-activedescendant`) | `TreeItem`(`row`,2026-09-25 起)、`TimePicker` 的欄、`DataTable` 的格、`Calendar` 的格 |
+
+**窮盡**:第一層三分(去處 / 東西不成整體 / 東西成整體)× 列內容二分,而「成整體」那一枝的列內容不影響結論(角色已由第一層決定)。其餘枝「一串幾站」照 `keyboard-model-canonical.md`(預設每列一站;列名在「列上有小按鈕的一串」的清單收成一站,B9)。
+**新元件若覺得自己不屬於任何一枝,那是第一層沒答清楚,不是需要新增分枝。**第一層答不出來時的正解是回去問「使用者對這一項**做**什麼」,不是去看別的元件怎麼寫。
+
 ### Prefix 垂直對齊:`items-start` + `h-[1lh]` wrapper(**永遠這樣**,不要做例外)
 
 所有 row primitives 的 outer flex 用 **`items-start`** + prefix(icon / avatar / checkbox / indicator)包在 **`h-[1lh] shrink-0 flex items-center`** 容器。這是**底層規則,不可跳過**。
@@ -373,8 +463,8 @@ Consumer 不需手動插 Separator——把同類 items 包進 Group,自動分
 | **MenuItem / Select / DropdownMenuItem / SidebarMenuButton / TreeItem** | permanent transparent(radius 只在 state 可見) | **0 gap 合法** | state 稀疏不創造永久相連 |
 | **SelectionItem**(Radio / Checkbox row) | permanent transparent(code 驗證 `flex items-start gap-2`,無 bg/border/radius) | **0 gap 合法** | 選中靠 control 視覺非 row bg |
 | **DataTable row** | flush + border-b 分隔線 | **0 gap 合法** | border-b 分隔線型 affordance |
-| **FileItem compact + progress bar**(Type A upload manager) | flush + 底部 progress bar 分隔線 | **0 gap 合法** | 同 DataTable;progress bar 分隔線型 affordance(user 2026-04-22 確認) |
-| **FileItem rich**(永遠 card) | `border + bg-surface + rounded-md + inset` → **standalone card** | **必 gap ≥ 8px** | Card 邊框融合失去 identity |
+| **FileItem `surface=upload-manager`**(rich + compact;Type A upload manager) | flush 透明列(compact 另有底部 progress bar 分隔線);可點的列滑過時整列鋪到面板邊 | **0 gap 合法** | 同 DataTable;progress bar 分隔線型 affordance(user 2026-04-22 確認);列間 ink 距由兩列各自上下 `tight/2` 相加(`components/FileItem/file-item.spec.md`「List wrapper canonical」,2026-09-25 B12) |
+| **FileItem rich `surface=form`**(card) | `border + bg-surface + rounded-md + inset` → **standalone card** | **必 gap ≥ 8px** | Card 邊框融合失去 identity |
 | **FileItem compact + bg-secondary**(Type B form attachment 靜態) | `bg-secondary + rounded-md + inset` → **standalone pill** | **必 gap ≥ 4px** | bg 塊融合消失 item 邊界 |
 | **StepItem / Timeline item** | permanent transparent item + connector line | **0 gap 合法** | connector 提供連接(分隔線型 affordance 的連接版) |
 
@@ -936,7 +1026,7 @@ World-class benchmark(6 家 DS):
 
 | 屬性 | 值 | 原因 |
 |---|---|---|
-| padding-y | 12px (`py-3`) | 舒適的列表行高，觸控友好 |
+| padding-y | 12px (`py-3`) | 頁面級列表的寬鬆行高——同表的閱讀模式（頁面內停留閱讀）與較大的 avatar / thumbnail 要對應的呼吸量（2026-09-24 撤回原文的「觸控友好」：本 DS 以滑鼠指標的精度為前提，尺寸不以觸控門檻推導，見 `ds-canonical/references/hit-area-canonical.md`）|
 | padding-x | 16px (`px-4`) | 頁面內容的標準水平間距 |
 | prefix ↔ content gap | 12px (`gap-3`) | 較寬鬆，適合較大的 avatar / thumbnail |
 | 閱讀模式 | 閱讀模式 | 頁面內停留閱讀 |
@@ -1066,9 +1156,9 @@ Selection control(Dropdown / Menu / List / SegmentedControl / Chip)的 item 視
 
 ---
 
-## Recipe + 自我檢查 → `.claude/references/item-anatomy-recipe.md`
+## Recipe + 自我檢查 → `ds-canonical/references/item-anatomy-recipe.md`
 
-建立新 row primitive 的 7 步 workflow + audit grep guard + SidebarMenuButton 獨立實作風險,搬到 `.claude/references/item-anatomy-recipe.md`(spec 2026-04-24 prune 瘦身 — Recipe 是 workflow 類,搬 reference 減 spec 體積)。
+建立新 row primitive 的 7 步 workflow + audit grep guard + SidebarMenuButton 獨立實作風險,搬到 `ds-canonical/references/item-anatomy-recipe.md`(canonical owner,不指產生檢視;spec 2026-04-24 prune 瘦身 — Recipe 是 workflow 類,搬 reference 減 spec 體積)。
 
 本節僅保留 pointer。建 row primitive → 讀 reference + 本 spec 的結構 / padding / 24px 閾值 / slot 規範 / 選擇狀態視覺 / Inline Action spec 等 canonical。
 
@@ -1077,9 +1167,9 @@ Selection control(Dropdown / Menu / List / SegmentedControl / Chip)的 item 視
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `alert.spec.md`
+- `button.spec.md`
 - `checkbox.spec.md`
 - `color.spec.md`
-- `command.spec.md`
 - `dropdown-menu.spec.md`
 - `element-anatomy.spec.md`
 - `empty.spec.md`
@@ -1091,10 +1181,12 @@ Selection control(Dropdown / Menu / List / SegmentedControl / Chip)的 item 視
 - `layoutSpace.spec.md`
 - `menu-item.spec.md`
 - `notice.spec.md`
+- `overlay-surface.spec.md`
 - `select-menu.spec.md`
 - `select.spec.md`
 - `selection-item.spec.md`
 - `sidebar.spec.md`
+- `steps-state-visuals.spec.md`
 - `steps.spec.md`
 - `tabs.spec.md`
 - `time-picker.spec.md`