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

package/src/components/TreeView/tree-view.principles.stories.tsx

@@ -0,0 +1,223 @@
+// @principles-rationale: UsageGuidance merges WhenToUse + WhenNotToUse(含近親對照)into single 使用指引 story per refactor task (2026-04-26)
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Folder, FileText, Image, Users, User } from 'lucide-react'
+import { TreeView, TreeItem } from './tree-view'
+
+const meta: Meta = {
+  title: 'Design System/Components/TreeView/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-col gap-3 max-w-md">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    {children}
+  </section>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose mb-8">
+          <p>適合 TreeView 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li><LinkTo kind="Design System/Components/TreeView/展示" name="檔案瀏覽"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">檔案瀏覽</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/TreeView/展示" name="步驟引導"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">步驟引導</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/TreeView/展示" name="多選"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">多選</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/TreeView/展示" name="長標籤"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">長標籤</span></LinkTo></li>
+            <li><LinkTo kind="Design System/Components/TreeView/展示" 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「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方 vs 近親 段)。</p>
+        </div>
+
+        <Rule
+          title="TreeView 的 sweet spot — 階層資料 + 任意多層 + 展開收合"
+          note="檔案資料夾、組織架構、專案 / 子專案 / 任務。每個 node 有 children 就可展開,沒有就是 leaf"
+        >
+          <div className="border border-border rounded-lg p-3 w-80">
+            <TreeView aria-label="文件與下載資料夾樹" defaultExpandedIds={['docs', 'photos', 'downloads']}>
+              <TreeItem id="docs" label="Documents" icon={Folder}>
+                <TreeItem id="resume" label="Resume.pdf" icon={FileText} />
+                <TreeItem id="photos" label="Photos" icon={Folder}>
+                  <TreeItem id="beach" label="beach.jpg" icon={Image} />
+                  <TreeItem id="trip" label="trip.jpg" icon={Image} />
+                </TreeItem>
+              </TreeItem>
+              <TreeItem id="downloads" label="Downloads" icon={Folder}>
+                <TreeItem id="installer" label="installer.dmg" icon={FileText} />
+              </TreeItem>
+            </TreeView>
+          </div>
+        </Rule>
+      </Section>
+
+      <Section title="何時不用 + 替代方案">
+        <Rule
+          title='❌ 互斥展開(同時只開一個):用 Accordion type="single"'
+          note='TreeView 預設允許任意多個節點同時展開。平面設定分段若需要「展開一個、其他自動收合」的互斥語意,用 Accordion type="single"(非 TreeView)'
+        >
+          <div className="border border-border rounded-lg p-3 w-80">
+            <TreeView aria-label="帳號設定分段" selectionMode="none" defaultExpandedIds={['account', 'notify', 'privacy']}>
+              <TreeItem id="account" label="帳號設定">
+                <TreeItem id="account-email" label="電子郵件" />
+                <TreeItem id="account-password" label="密碼" />
+              </TreeItem>
+              <TreeItem id="notify" label="通知偏好">
+                <TreeItem id="notify-email" label="信件通知" />
+                <TreeItem id="notify-push" label="推播通知" />
+              </TreeItem>
+              <TreeItem id="privacy" label="隱私與安全">
+                <TreeItem id="privacy-2fa" label="兩步驟驗證" />
+              </TreeItem>
+            </TreeView>
+          </div>
+          <Label warn>↑ 三個設定分段在 TreeView 裡可同時展開;要「展開一個自動收其他」的互斥手風琴,用 Accordion type="single"</Label>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親元件">
+        <Rule
+          title="❌ 平面資料(無階層):用 DataTable / list"
+          note="TreeView 為階層而設計——若資料本質是平面(使用者清單、訂單清單),用 DataTable 更自然,TreeView 的遞迴結構徒增 overhead"
+        >
+          <div className="border border-border rounded-lg p-3 w-80">
+            <TreeView aria-label="平面使用者清單反例">
+              <TreeItem id="alice" label="Alice" icon={User} />
+              <TreeItem id="bob" label="Bob" icon={User} />
+              <TreeItem id="charlie" label="Charlie" icon={User} />
+              <TreeItem id="diana" label="Diana" icon={User} />
+            </TreeView>
+          </div>
+          <Label warn>↑ 平面的使用者清單用 TreeView → TreeView 的 chevron / indent 都用不上,用 DataTable 或 list</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 純視覺分段(設計時可列舉的固定選單):用 SidebarGroup 不用 TreeView"
+          note="Sidebar 主選單只接受 1 層可列舉項目——設計時就固定死、不會 runtime 新增的分段,用 SidebarGroup 純視覺分段即可。真階層 user data(專案 / 子專案、部門樹,即使只有 2 層、未來會長)才用 TreeView(見 sidebar.spec.md「判斷規則」)"
+        >
+          <Label warn>固定分段用 SidebarGroup 就夠,不需要 TreeView 的遞迴 overhead;user data 樹則一律 TreeView</Label>
+        </Rule>
+      </Section>
+    </div>
+  ),
+}
+
+export const ExpandSelectSeparationRule: Story = {
+  name: '展開 與 Select 語意分離',
+  render: () => {
+    const [selected, setSelected] = React.useState<Set<string>>(new Set(['resume']))
+    return (
+      <div>
+        <Rule
+          title="Chevron = 展開 / 收合;Label = 選取 / 執行"
+          note="兩個獨立的互動區——點 chevron 只展開不選,點 label 只選不展開(除非 consumer 顯式 opt-in expandOnSelect)。世界級 tree 元件的共識(VS Code、macOS Finder、Linear)"
+        >
+          <div className="border border-border rounded-lg p-3 w-80">
+            <TreeView aria-label="展開與選取行為範例" selectedIds={selected} onSelectedChange={setSelected} defaultExpandedIds={['docs', 'photos']}>
+              <TreeItem id="docs" label="Documents" icon={Folder}>
+                <TreeItem id="resume" label="Resume.pdf" icon={FileText} />
+                <TreeItem id="photos" label="Photos" icon={Folder}>
+                  <TreeItem id="beach" label="beach.jpg" icon={Image} />
+                </TreeItem>
+              </TreeItem>
+            </TreeView>
+          </div>
+          <Label>↑ 點 chevron 展開資料夾,點檔名選取該檔。兩個動作獨立</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 混淆 expand 和 select 語意"
+          note="點 node 同時展開 + 選取,使用者會困惑:「我只想展開看看,不想選它」。分離讓使用者有更細的控制"
+        >
+          <Label warn>若強制合併,變成「想展開必須選」,破壞檔案瀏覽的自然 pattern(想看裡面但不選起來)</Label>
+        </Rule>
+      </div>
+    )
+  },
+}
+
+export const IndentRule: Story = {
+  name: '縮排與欄位節奏',
+  render: () => (
+    <div>
+      <Rule
+        title="Indent 必須用 gap-2(8px)和 chevronSize 對齊"
+        note="indentStep = chevronSize + gap-2,跟 item-layout 的 prefix-content gap 一致。讓 indent 視覺跟 item-layout 融為一體,而非獨立數字系統"
+      >
+        <div className="border border-border rounded-lg p-3 w-80">
+          <TreeView aria-label="工程團隊縮排範例" defaultExpandedIds={['eng', 'frontend', 'backend']}>
+            <TreeItem id="eng" label="Engineering" icon={Users}>
+              <TreeItem id="frontend" label="Frontend" icon={Users}>
+                <TreeItem id="alice" label="Alice" icon={User} />
+                <TreeItem id="bob" label="Bob" icon={User} />
+              </TreeItem>
+              <TreeItem id="backend" label="Backend" icon={Users}>
+                <TreeItem id="charlie" label="Charlie" icon={User} />
+              </TreeItem>
+            </TreeItem>
+          </TreeView>
+        </div>
+        <Label>↑ 三層縮排節奏一致——每層 indent 剛好是 chevron + gap-2</Label>
+      </Rule>
+
+      <Rule
+        title="Chevron placeholder 保留對齊"
+        note="同層 siblings 有展開 icon、有的沒有 → label 不對齊。TreeView 自動給葉節點留 chevron 位置(透明 placeholder),consumer 不需介入"
+      >
+        <div className="border border-border rounded-lg p-3 w-80">
+          <TreeView aria-label="行銷素材資料夾樹" defaultExpandedIds={['assets', 'social']}>
+            <TreeItem id="assets" label="行銷素材" icon={Folder}>
+              <TreeItem id="hero" label="活動主視覺.png" icon={Image} />
+              <TreeItem id="social" label="社群貼文" icon={Folder}>
+                <TreeItem id="story" label="限動範本.psd" icon={FileText} />
+              </TreeItem>
+            </TreeItem>
+          </TreeView>
+        </div>
+        <Label>↑ 「活動主視覺.png」是葉,「社群貼文」可展開——兩者 label 依然垂直對齊</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 混用有 icon / 無 icon 的節點"
+        note="Chevron 有自動佔位(leaf 也留等寬空白),但 icon 無自動佔位——同層有些節點傳 icon、有些沒傳,label 起點會直接錯開。要嘛全傳 icon,要嘛全不傳(見 spec「Icon 一致性原則」)"
+      >
+        <div className="border border-border rounded-lg p-3 w-80">
+          <TreeView aria-label="icon 混用反例檔案樹" defaultExpandedIds={['src', 'public']}>
+            <TreeItem id="src" label="src" icon={Folder}>
+              <TreeItem id="app" label="App.tsx" icon={FileText} />
+              <TreeItem id="readme" label="README.md" />
+            </TreeItem>
+            <TreeItem id="public" label="public">
+              <TreeItem id="favicon" label="favicon.ico" icon={Image} />
+            </TreeItem>
+          </TreeView>
+        </div>
+        <Label warn>↑ 「README.md」「public」沒傳 icon → label 起點比有 icon 的節點前移,視覺節奏錯開</Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/TreeView/tree-view.spec.md

@@ -2,7 +2,10 @@
 component: TreeView
 family: 1
 variants: {}
-sizes: {}
+sizes:
+  sm: { when: "緊湊清單(與 md 同視覺,保留供密度語意)" }
+  md: { when: "default 一般導覽樹" }   # ★ default
+  lg: { when: "touch / 大字級" }
 traits:
   - hasInteractiveStates
   - isStructural
@@ -23,7 +26,7 @@ TreeView 是**階層結構的遞迴元件**。一個 TreeItem 就是一個 node
 
 **實作基礎**：基於 Radix Collapsible 實作展開 / 收合，自建 tree 結構與 ARIA tree 鍵盤導覽（Radix 沒有 Tree primitive）。
 
-**Layout Family**：CLAUDE.md 4-Family Model **Family 1（Menu item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「Menu item layout」章節的 scanning-mode 規格。
+**Layout Family**：本元件是 `patterns/element-anatomy/item-anatomy.spec.md` 所擁有的 **Family 1（Menu item layout）** 消費者。結構繼承其「Menu item layout」章節的 scanning-mode 規格。
 
 TreeView 本身只負責三件事:
 1. **遞迴渲染** + indent
@@ -38,7 +41,7 @@ TreeView 本身只負責三件事:
 
 - **階層結構資料**：檔案管理器資料夾樹、部門組織架構、專案 / 子專案 / 任務、權限群組
 - **Sidebar 內的分層導覽**：workspace > channel > thread、product > category > item
-- **可展開收合的清單**：FAQ（但多個可同時展開,非 Accordion 互斥）、程式碼 tree、JSON viewer
+- **可展開收合的階層清單**：程式碼檔案樹、JSON viewer、DOM inspector（遞迴巢狀結構;平面章節如 FAQ / 設定分組屬 Accordion,見「何時不用」）
 - **任意多層**：從 1 層到 N 層深度都由同一個 TreeView 承載
 
 ## 何時不用
@@ -46,8 +49,8 @@ TreeView 本身只負責三件事:
 | 場景 | 改用 | 原因 |
 |------|------|------|
 | 平面資料（無階層）| `DataTable` / 自訂 list | TreeView 為階層而設計，沒 children 的平面用 list |
-| 同時只能展開一個（互斥）| `Accordion`（TBD）| TreeView 允許任意多個展開,互斥模式語意不同 |
-| 簡單 2 層 nav（主分類 + 子分類）| `Sidebar` + SidebarMenuSubButton | 輕量 2 層用 Sidebar 的內建結構,不需遞迴 |
+| 平面章節折疊（FAQ / 設定分組,無階層）| `Accordion`（`type="single"` 互斥 / `type="multiple"` 多開）| TreeView 是遞迴階層 node;平面章節不論單開或多開都屬 Accordion 範疇（accordion.spec.md「何時用」列 FAQ 為主要用途）|
+| 純視覺分段 / 設計時可列舉的 1 層固定選單 | `SidebarGroup` / `SidebarMenu` | Sidebar 主選單只接受 1 層可列舉項目;任何真階層（深度 > 1、runtime 可新增、user data）一律 TreeView（見 sidebar.spec.md「判斷規則」）|
 | 選單式展開（點完就關）| `DropdownMenu` + sub-menu | DropdownMenu 的 sub menu 是 temporary,TreeView 是 persistent |
 | 階層選擇但需要搜尋 / 快速找 | 自訂 tree + search filter（未來 TreeView 可加 search prop）| 基本 TreeView 不含 search |
 
@@ -79,19 +82,19 @@ TreeView 本身只負責三件事:
 | Slot | 說明 | 存在條件 |
 |---|---|---|
 | **indent** | `paddingLeft = depth × indentStep` | depth > 0 |
-| **chevron** | `ChevronRight`(收合)/ `ChevronDown`(展開) | 有 children |
-| **chevron placeholder** | 等寬空白,確保同層 leaf label 對齊 | 沒 children 但同層有 expandable siblings |
+| **chevron** | `ChevronRight`(展開時 `rotate-90` transition,見「動畫」)| 有 children |
+| **chevron placeholder** | 等寬空白,確保同層 leaf label 對齊 | 沒 children(每個 leaf 無條件留等寬空白,不檢查 siblings)|
 | **icon** | `LucideIcon`,跟 label 同色(內容 icon) | 可選 |
 | **label** | 主要文字 | 必有 |
 | **suffix** | badge / 計數 / inline action(⋯ menu trigger) | 可選 |
 
 ### Chevron 的特殊性
 
-Chevron 是**展開/收合控件**,不是 prefix icon:`fg-muted`(指示色,hover 時 foreground)/ 位置在 indent 之後 icon 之前 / 點擊只 toggle expand 不觸發 selection / `rotate-90` transition。
+Chevron 是**展開/收合控件**,不是 prefix icon:`fg-muted`(指示色,hover 時 `fg-secondary`,只前進一階)/ 位置在 indent 之後 icon 之前 / 點擊只 toggle expand 不觸發 selection / `rotate-90` transition。
 
 ### 佔位規則(chevron + icon)
 
-同層 node 間,**有元素的 slot 必須在沒元素的 sibling 上留等寬空白**,否則 label 不對齊。Chevron 佔位:同層有任何 expandable sibling(寬 16/16/20 @ sm/md/lg);Icon 佔位:同層有任何 sibling 帶 icon(同寬)。**判斷自動化**:TreeView render 時掃 siblings 決定 placeholder,consumer 不介入。
+同層 node 間,label 需對齊。**Chevron 佔位**:每個無 children 的 leaf **無條件**渲染等寬 chevron placeholder(寬 16/16/20 @ sm/md/lg),不檢查 siblings——故有/無 expandable sibling 結果都對齊。**Icon 佔位**:icon slot 只在該 node 傳 `icon` prop 時渲染 `<ItemIcon>`,**無自動等寬 placeholder**(無 icon 的 leaf 不補空位);若要 icon 欄整齊,consumer 自行確保同層都傳 icon。
 
 ---
 
@@ -114,9 +117,9 @@ Chevron 是**展開/收合控件**,不是 prefix icon:`fg-muted`(指示色,hover
 
 **行為**:點整行(label / icon / 空白)→ select(預設所有 node 可選);點 chevron → toggle expand,不 select;鍵盤 `→`(收合 expandable)→ expand;`←`(展開 expandable)→ collapse;`←`(leaf / 收合 node)→ 焦點到 parent。
 
-**預設 label 不 expand**——chevron 是展開唯一控件。理由:select / expand 語意獨立(sidebar「Documents」點 label 進頁面,點 chevron 才展開子列表)。Consumer `expandOnSelect` prop 可讓整行同時 select + expand(適合 stepper)。
+**預設 label 不 expand**——chevron 是展開唯一控件。理由:select / expand 語意獨立(sidebar「Documents」點 label 進頁面,點 chevron 才展開子列表)。Consumer `expandOnSelect` prop 可讓整行同時 select + expand(適合 stepper)——**此連帶展開僅限指標點擊(`handleRowClick`)**;鍵盤 `Enter` / `Space` 只觸發 select,展開 / 收合一律走 `→` / `←`(對齊 WAI-ARIA treeview「Enter 啟用、方向鍵展開收合」慣例)。
 
-**動畫**:children 用 Radix `Collapsible` height animation(0 → auto);chevron `transition-transform duration-150 rotate-0 → rotate-90`。
+**動畫**:children 用 Radix `Collapsible` height animation(0 → auto);chevron `transition-all duration-150 rotate-0 → rotate-90`(`transition-all` 同時涵蓋 hover 色彩過渡)。
 
 ---
 
@@ -129,12 +132,26 @@ Chevron 是**展開/收合控件**,不是 prefix icon:`fg-muted`(指示色,hover
 - `aria-selected="true"` 在 selected node 上
 - 視覺:selected node 用 `neutral-selected` state(跟 MenuItem 單選一致;完整 token 見 anatomy `ColorMatrix`)
 
-### 多選(file browser)
+### 多選(file browser / permission picker)
 
-- 用 checkbox 表達選取,不用背景色
-- `Shift+Click` 範圍選取
-- `Ctrl/Cmd+Click` 切換個別選取
-- `aria-multiselectable="true"` 在 TreeView 上
+- **視覺 SSOT(2026-05-26 user explicit lock)**:對齊 `SelectMenu` multi pattern,checkbox 為**唯一** visual signal —
+  - **Auto-render `<Checkbox>`**:`selectionMode="multiple"` 時 TreeItem 內建 render checkbox(reflect `selectedIds`),consumer **無需手動傳** `checkbox` prop
+  - **Row 不套 `bg-neutral-selected`**(該 token 保留給 single mode 補無 checkbox 的視覺信號)
+  - **Text 也不變 `text-foreground`**(已有 checkbox 強信號,text 變色會雙重 noise)→ 維持 `text-fg-secondary` muted
+  - 對齊 cite:`menu-item.tsx:194-195`(MenuItem selected → bg only)+ `select-menu.tsx` option render `checkbox={multiple}` / `selected={!multiple && …}`(SelectMenu multi → checkbox only)
+- API:`selectionMode="multiple"` 自動 render checkbox;consumer 傳 `checkbox={<Checkbox/>}` 可 override(parent-child cascade 等 advanced 場景)
+- 多選互動:點擊逐項 toggle(`handleRowClick` → `select(id)`;**不支援** `Shift+Click` 範圍選取 / `Ctrl/Cmd+Click` 修飾鍵切換——`handleRowClick` 不讀 `shiftKey/metaKey/ctrlKey`)/ `aria-multiselectable="true"` 在 TreeView 上
+
+### 視覺信號 SSOT 對照表(single vs multi)
+
+| Mode | Default text | Selected text | Selected bg | Checkbox |
+|---|---|---|---|---|
+| `single` | `text-fg-secondary`(muted)| `text-foreground` ✅ | `bg-neutral-selected` ✅ | N/A |
+| `multiple` | `text-fg-secondary`(muted)| 不變(維持 muted)| 不變 | auto `<Checkbox checked={isSelected} />` ✅ |
+
+設計理由:single 沒 checkbox → text+bg 雙信號補;multi 有 checkbox 強信號 → text+bg 不再變化避 noise。
+
+歷史錨例(2026-05-26):本 session 多次 revert + 對齊。User 明確「multi 已有 checkbox,text 不該再變色」→ 鎖 multi mode `text-foreground` apply 改 `selectionMode === 'single'` only。對齊 SelectMenu pattern,無偏移。
 
 ### 無選取(純展開/收合)
 
@@ -152,10 +169,12 @@ Chevron 是**展開/收合控件**,不是 prefix icon:`fg-muted`(指示色,hover
 | `←` | 收合(若展開);移到 parent(若已收合或是 leaf) |
 | `Home` | 焦點移到第一個 node |
 | `End` | 焦點移到最後一個可見 node |
-| `Enter` / `Space` | 觸發 selection(跟點擊 label 同效果) |
-| `*` | 展開同層所有 siblings |
+| `Enter` / `Space` | 觸發 selection(等同點擊 label 的 select;`expandOnSelect` 的連帶展開僅限指標點擊,鍵盤展開 / 收合用 `→` / `←`) |
+| `Cmd/Ctrl+Shift+↑` / `↓` | 重排:同層上移 / 下移(僅 `draggable` 時;詳「Drag and Drop → 鍵盤重排」) |
+| `Cmd/Ctrl+Shift+→` | 重排:移入上一個 sibling(需為 folder;收合時自動展開) |
+| `Cmd/Ctrl+Shift+←` | 重排:移出,成為 parent 的下一個 sibling |
 
-遵循 [WAI-ARIA TreeView pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/)。
+遵循 [WAI-ARIA TreeView pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/)。重排鍵位在 modifier 層,與 APG 導覽鍵完全正交(APG 無 drag-and-drop pattern,重排屬 application-level 鍵位)。
 
 ---
 
@@ -163,8 +182,8 @@ Chevron 是**展開/收合控件**,不是 prefix icon:`fg-muted`(指示色,hover
 
 | 元素 | Role | 屬性 |
 |---|---|---|
-| TreeView 容器 | `role="tree"` | `aria-label`,`aria-multiselectable`(多選時) |
-| TreeItem 外層 | `role="treeitem"` | `aria-expanded`(expandable 才有),`aria-selected`,`aria-level`,`aria-setsize`,`aria-posinset` |
+| TreeView 容器 | `role="tree"` | **`aria-label` 或 `aria-labelledby`(擇一必填 — accessible name)**,`aria-multiselectable`(多選時) |
+| TreeItem 外層 | `role="treeitem"` | `aria-expanded`(expandable 才有),`aria-selected`,`aria-level` |
 | TreeItem children 容器 | `role="group"` | — |
 
 ---
@@ -185,9 +204,9 @@ TreeItem row 有 5 種狀態:default / hover / focused(鍵盤) / selected / disa
 |---|---|---|
 | **全 icon** | node 有明確的類型差異(folder/file、page type、step status) | icon 是層級的主要視覺指引,每個 node 一眼可辨識 |
 | **全無 icon** | node 類型單一(全部是「頁面」或「步驟」),不需要類型區分 | 靠 indent + chevron 表達層級;深層考慮開 tree guide |
-| ❌ **混用** | — | 有 icon 的 node 和沒 icon 的 node label 起始位置不同(即使有 placeholder 佔位,視覺仍不一致) |
+| ❌ **混用** | — | icon 無自動佔位(見「佔位規則」),有 icon / 無 icon 的 node label 起始位置直接錯開 |
 
-混用時 placeholder 雖然保證 label 水平對齊,但「有圖 / 無圖」的視覺節奏仍然不一致。如果確實有些 node 沒有合適的 icon,寧可全部不用 icon + 開 tree guide,也不要混用。
+Chevron placeholder 只保證 chevron 欄對齊;icon 無自動佔位,混用時「有圖 / 無圖」的 label 起點與視覺節奏都不一致。如果確實有些 node 沒有合適的 icon,寧可全部不用 icon + 開 tree guide,也不要混用。
 
 ---
 
@@ -195,7 +214,7 @@ TreeItem row 有 5 種狀態:default / hover / focused(鍵盤) / selected / disa
 
 **預設關閉。** 大部分 tree 使用情境(sidebar nav + 全 icon)不需要。
 
-當 tree **沒有 icon** 且 **深度 ≥ 3** 時,建議開啟 guide 補充視覺層級線索。Consumer 可透過 `showGuides` prop 開啟。
+當 tree **沒有 icon** 且 **深度 ≥ 3** 時,建議開啟 guide 補充視覺層級線索。未來將提供 `showGuides` prop(初版不實作,目前無此 prop)。
 
 啟用時的規則:
 - 線條顏色:`border-divider`
@@ -225,7 +244,7 @@ Sidebar 是頁面級容器,padding 應該跟其他頁面區塊的間距一致(
 
 **為什麼**:tree 是任意深度的遞迴結構,沒有任何方式可以壓縮成單排 icon。Gmail / Linear / Notion 一致採取「隱藏」——使用者要看 tree 必須先展開 sidebar。詳見 `sidebar.spec.md` 的 icon 模式規則。
 
-實作上由 Sidebar 元件透過 CSS `group-data-[collapsible=icon]:hidden` 自動隱藏,TreeView 本身不需特殊處理。
+Sidebar 不會自動辨識任意 tree 容器；consumer 必須在承載 TreeView／可收合 tree group 的 wrapper 傳 `className="group-data-[collapsible=icon]:hidden"`，讓 Sidebar group state 在 icon 模式隱藏整塊 tree。TreeView 本身不改變資料或互動模式。
 
 ### 為什麼 menu 用 px-3
 
@@ -235,7 +254,7 @@ Sidebar 是頁面級容器,padding 應該跟其他頁面區塊的間距一致(
 
 ## Hover-only Inline Actions
 
-TreeItem 右側 `actions` slot 只在 hover 該列時出現(opacity 0→1 transition)。**為什麼**:(a) 視覺清潔(10+ node × 2-3 icon = 20-30 灰 icon 同屏噪音極大);(b) 業界一致(Notion / VS Code / Figma 都 hover-only);(c) 不影響操作(要操作自然會 hover)。
+TreeItem 右側 inline actions（宣告式 `inlineActions: InlineActionConfig[]` 或 escape-hatch `inlineActionsSlot`，**非** `actions` prop）預設在 hover 該列**或鍵盤 focus-visible 該列**時出現(opacity 0→1 transition)；`actionsReveal={false}` 則常駐不 hover-reveal。**為什麼**:(a) 視覺清潔(10+ node × 2-3 icon = 20-30 灰 icon 同屏噪音極大);(b) 業界一致(Notion / VS Code / Figma 都 hover-only);(c) 不影響操作(要操作自然會 hover)。
 
 **Uniform 規則**:同類型 node 的 hover action 必須完全一致,否則 discovery 失敗。
 - **⋯ (more menu)**:所有 node 統一有,menu 內容由 consumer 依 node type 動態(rename / delete / duplicate)
@@ -245,9 +264,9 @@ TreeItem 右側 `actions` slot 只在 hover 該列時出現(opacity 0→1 transi
 
 ### Inline action 視覺 + API
 
-Icon 尺寸跟 size tier(sm/md=16, lg=20);色 `fg-muted` → hover `foreground`;hover bg `neutral-hover`;action 間距 / 高度對齊規則見 `item-anatomy.spec.md`「Inline Action 設計規格」(canonical SSOT)。
+Icon 尺寸跟 size tier(sm/md=16, lg=20);色 `fg-muted` → hover `fg-secondary`;hover bg `neutral-hover`;action 間距 / 高度對齊規則見 `../../patterns/element-anatomy/inline-action.spec.md`(canonical SSOT,2026-04-24 自 item-anatomy 抽出)。
 
-**宣告式 API**(對齊 `uiSize.spec.md` + `SidebarMenuButton.inlineActions`):`inlineActions: InlineActionConfig[]` + `actionsReveal: false | "hover"`(預設 `"hover"`,鍵盤 focus-visible 也顯)。內部用 `<ItemInlineAction>` helper 渲染,consumer **不可手刻 button JSX**(canonical 在 `item-layout.tsx`,共用 size 查表 / Tooltip / hover bg / aria)。Hover-reveal 用 `group-has-[:focus-visible]/tree-item:opacity-100` 而非 `group-focus-within`(後者 mouse click 會永久顯示)。
+**宣告式 API**(對齊 `inline-action.spec.md` + `SidebarMenuButton.inlineActions`):`inlineActions: InlineActionConfig[]` + `actionsReveal: false | "hover"`(預設 `"hover"`,鍵盤 focus-visible 也顯)。內部用 `<ItemInlineAction>` helper 渲染,consumer **不可手刻 button JSX**(canonical 在 `item-anatomy.tsx`,共用 size 查表 / Tooltip / hover bg / aria)。Hover-reveal 用 `group-has-[:focus-visible]/tree-item:opacity-100` 而非 `group-focus-within`(後者 mouse click 會永久顯示)。
 
 ---
 
@@ -262,7 +281,27 @@ Icon 尺寸跟 size tier(sm/md=16, lg=20);色 `fg-muted` → hover `foreground`;
 - **Auto-expand**:拖曳停留收合 folder 500ms → 自動展開(Figma 行為);離開或結束取消計時
 - **依賴**:`@dnd-kit/core`(`useDraggable` + `useDroppable` + `DragOverlay`);state 由 consumer `onDragEnd({sourceId, targetId, position})` callback 自行更新
 
-**視覺**(2026-05-06 v14.5 SSOT 抽 `lib/drag-visual.ts`):被拖 node 原位 `opacity-30` 半透明殘影 / before-after drop indicator 為 2px primary 細線(`bg-primary` `h-0.5`,left 跟 indent 深度)/ inside drop target `bg-primary-subtle` 全行背景 / DragOverlay ghost 圓角 + icon + label + 半透明 + elevation shadow。**TreeView 是 DS 內最早 codified 的 drag canonical**,DataTable row drag + column reorder 都 inherit 此 pattern via `drag-visual.ts` SSOT module。視覺校驗見 story `DragAndDrop`。
+**視覺**(2026-05-06 v14.5 SSOT 抽 `lib/drag-visual.ts`):被拖 node 原位 `opacity-disabled`(45%)半透明殘影 / before-after drop indicator 為 2px primary 細線(`bg-primary` `h-0.5`,left 跟 indent 深度)/ inside drop target `bg-primary-subtle` 全行背景 / DragOverlay ghost 圓角 + icon + label + **不透明 `bg-surface`** + elevation shadow(跟 surface 拉開的視覺距離靠 shadow 不靠 opacity;半透明只用在上述原位殘影)。**TreeView 是 DS 內最早 codified 的 drag canonical**,DataTable row drag + column reorder 都 inherit 此 pattern via `drag-visual.ts` SSOT module。視覺校驗見 story `DragAndDrop`。
+
+**結構安全(2026-07-14 修)**:`handleDragOver` / `handleDragEnd` 有 descendant guard(`isInSubtree`)——drop target 落在被拖 node 自己的子樹內時視同無效目標(原實作只擋 `over.id === active.id` 未擋 descendants,會發出 `targetId ∈ source 子樹` 的非法事件;consumer 按 remove→insert 實作時整個子樹會靜默消失)。鍵盤重排路徑共用同一 guard。
+
+### 鍵盤重排(2026-07-14 v1)
+
+`draggable` 啟用後,鍵盤與指標同樣可重排(WCAG 2.1.1 keyboard parity——四鍵可組合出任何 pointer 可達的合法樹位置)。鍵位 `Cmd/Ctrl+Shift+方向鍵`(對齊 [Notion 移動 block 鍵位](https://www.notion.com/help/keyboard-shortcuts),WebFetch 驗證紀錄 `.claude/logs/treeview-keyboard-dnd-design.md#L25`;[Asana](https://keycombiner.com/collections/asana/) / [Todoist](https://www.todoist.com/help/articles/use-keyboard-shortcuts-in-todoist-Wyovn2) 同「modifier+方向鍵直接移動」派),對虛擬焦點(`aria-activedescendant`)節點操作,**每按一下立即 commit**——無 grab-mode、無預覽、無 cancel(反向鍵即 undo)。**不用** dnd-kit `KeyboardSensor`:其 activator 需可接收 DOM focus([dnd-kit sensors 文件](https://dndkit.com/api-documentation/sensors/keyboard)),與單一 tab stop 虛擬焦點模型(2026-07-05 D4 拍板)結構性不相容,故為容器 `handleKeyDown` 的自建分支。
+
+| 按鍵 | 行為 | 發出事件 |
+|---|---|---|
+| `Cmd/Ctrl+Shift+↑` | 同層上移(整個子樹一起動) | `{sourceId, targetId: prevSibling, position: 'before'}` |
+| `Cmd/Ctrl+Shift+↓` | 同層下移(跳過 sibling 的子樹,不會鑽進去) | `{sourceId, targetId: nextSibling, position: 'after'}` |
+| `Cmd/Ctrl+Shift+→` | 移入上一個 sibling(需為 folder;collapsed 時自動展開——pointer 500ms hover auto-expand 的鍵盤對應物) | `{sourceId, targetId: prevSibling, position: 'inside'}` |
+| `Cmd/Ctrl+Shift+←` | 移出,成為 parent 的下一個 sibling | `{sourceId, targetId: parentId, position: 'after'}` |
+
+- **契約同 pointer**:同一個 `onDragEnd` + `TreeDragEndEvent`,consumer API 零改動。**頻率差異**:pointer 一手勢一次、keyboard 每步一次——有伺服器持久化的 consumer 建議 optimistic update(不建議 debounce batch,會破壞每按即 commit 語意)。
+- **邊界 no-op**:已在最上方 / 最下方 / 最外層、無可移入的 folder → 不發事件,只 SR 播報原因。
+- **disabled**:disabled node 不可移動,也不可當 target 錨點——相鄰 sibling disabled 時錨到最近 enabled sibling 表達同一插槽(可達位置與 pointer 一致;pointer 的 `useDroppable` 同樣 disable disabled node)。
+- **視覺**:每按即 commit,節點真實移動即回饋——**不用** dropIndicator / DragOverlay(那是「預覽中」的視覺語言,用在已 commit 的操作上會說謊);保留 keyboard focus ring 跟隨(`focusedId` 是 node id,移動後 `aria-activedescendant` 自動指向新位置)+ 移動後 `scrollIntoView`。
+- **互斥**:pointer 拖曳進行中忽略鍵盤重排;`draggable` 未啟用時整組鍵位 no-op(不落入導覽)。
+- **SR 播報**:TreeView 自有 sr-only `role="status"` polite live region(消費 `select-menu.tsx` `SelectMenuLiveStatus` 先例;單一節點覆寫式更新,快速連按只播最新)。文案 zh-TW 預設(「已將『X』移到『Y』之後,第 n 項,共 m 項」/「已將『X』移入『Y』」/「已在最上方」等),`reorderAnnouncements` prop per-key 覆寫(i18n 覆寫點),含 `instructions` sr-only 操作說明(tree 容器 `aria-describedby` 指向,僅 `draggable` 渲染)。播報為 optimistic(事件發出即播,假設 consumer 依約 reorder);移入原本收合的 folder 時序數不可知,播報省略序數。
 
 ---
 
@@ -271,27 +310,27 @@ Icon 尺寸跟 size tier(sm/md=16, lg=20);色 `fg-muted` → hover `foreground`;
 多選 tree(如 file browser、permission picker)在 label 前方加 checkbox:
 
 ```
-[indent][chevron][icon?][checkbox][label][suffix?]
+[indent][chevron][checkbox?][indicator|icon?][label][suffix?]
 ```
 
-Checkbox 位於 icon 之後、label 之前。跟 MenuItem 的多選 checkbox 位置對齊。
+Checkbox 位於 chevron 之後、indicator / icon / label 之前（`tree-view.tsx` render 順序:chevron → checkbox → indicator / icon → label,見 tsx 內「Checkbox 在 icon 前」註解）。對齊 SelectMenu 多選 checkbox 慣例。
 
 單選模式不需要 checkbox——用 `bg-neutral-selected` 背景色表達選中。
 
 ---
 
-## 閱讀模式
+## Label typography(掃描模式)
 
-TreeView 同時服務**掃描**和**閱讀**兩種情境:
+Tree 本質是**掃描導覽**(快速找到目標 node),所以 TreeView label 一律走**掃描模式**——row typography 由 row primitive 的 `ROW_PADDING_BY_SIZE` SSOT 鎖定:sm/md = `text-body leading-compact`、lg = `text-body-lg leading-compact`。
 
 | 情境 | Label typography | 理由 |
 |---|---|---|
-| **Sidebar nav** | `text-body leading-compact`(掃描模式) | 選單快速掃視,label 短 |
-| **File browser** | `text-body leading-compact`(掃描模式) | 檔名快速掃視 |
-| **Stepper** | `text-body`(閱讀模式) | Step 名稱需要閱讀理解 |
-| **Page tree** | `text-body leading-compact`(掃描模式) | 頁面標題快速掃視 |
+| **Sidebar nav** | `text-body leading-compact` | 選單快速掃視,label 短 |
+| **File browser** | `text-body leading-compact` | 檔名快速掃視 |
+| **Stepper** | `text-body leading-compact` | 跟其餘 node 一致,同走 row primitive |
+| **Page tree** | `text-body leading-compact` | 頁面標題快速掃視 |
 
-大部分 tree 使用情境是**掃描模式**(快速找到目標 node),所以 TreeView 預設用 `leading-compact`。Consumer 可透過 prop 切換。
+TreeView 目前**沒有**閱讀 / 掃描模式的切換 prop——所有 node 統一 `leading-compact`(對齊 `ROW_PADDING_BY_SIZE` 既定 SSOT,跨 row 元件視覺一致)。
 
 ---
 
@@ -305,8 +344,7 @@ TreeItem props slots(consumer 決定 node 視覺):
 | `label` | `ReactNode` | 主要文字(必填) |
 | `inlineActions` | `InlineActionConfig[]` | 右側 inline actions,詳見 `item-anatomy.spec.md` |
 | `actionsReveal` | `false \| "hover"` | 預設 `"hover"`,`false` 常駐 |
-| `status` | `'default' \| 'active' \| 'completed' \| 'error'` | Stepper 狀態視覺 |
-| `indicator` | `ReactNode` | 取代 **icon** 位置(chevron 永存)。Stepper 用 status dot / checkmark |
+| `indicator` | `ReactNode` | 取代 **icon** 位置(chevron 永存)。Stepper 狀態視覺由此傳 `<StepDone/>` / `<StepActive/>` / `<StepPending/>`(非 `status` prop——TreeItemProps 無 `status` 欄位)|
 
 **情境消費範例**(Sidebar nav / File browser / Stepper)由 stories.tsx 承載,不在本 spec 重複貼 code。
 
@@ -318,19 +356,19 @@ TreeItem props slots(consumer 決定 node 視覺):
 
 - ❌ 不得在 TreeItem 內嵌套非 TreeItem 的 children——children slot 只接受 TreeItem(遞迴結構)
 - ❌ 不得把展開/收合和選取的語意混在一起——chevron 負責 expand,label 負責 select,兩者獨立(除非 consumer 顯式 opt-in `expandOnSelect`)
-- ❌ 不得用 Accordion 取代 TreeView——Accordion 是「同時只開一個」的互斥模式,tree 是「任意多個都可以開」
-- ❌ 不得省略 chevron / icon placeholder——同層 siblings 有元素差異時必須佔位,否則 label 不對齊(佔位由 TreeView 自動處理,consumer 不需介入)
+- ❌ 不得用 Accordion 取代 TreeView——Accordion 是平面 section 折疊(`type="single"` 互斥 / `type="multiple"` 多開,見 accordion.spec.md),tree 是階層 node 結構
+- ❌ 不得省略 chevron placeholder——leaf 無條件佔位,由 TreeView 自動處理,consumer 不需介入;icon 無自動佔位,同層要嘛全傳 icon 要嘛全不傳(見「佔位規則」)
 - ❌ 不得用非 gap-2(8px)的值作為 indent 內部 gap——indentStep 必須等於 `chevronSize + gap-2`,跟 item-layout 的 prefix-content gap 一致
 
 ---
 
-## 為何無 Inspector
+## Anatomy story 涵蓋
 
-TreeView 是**階層樹元件**,關鍵決策維度是 selection × expanded × indent × size × context(sidebar / panel / dialog),已由 `SizeMatrix` / `ColorMatrix` / 元件特有 `IndentMatrix`(縮排規則) / `StateBehavior`(selected vs expanded 語意分離) / `KeyboardMatrix` 五張 story 完整覆蓋。
+TreeView 是**階層樹元件**,關鍵決策維度是 selection × expanded × indent × size × context(`'sidebar'` / `'menu'`——`tree-view.tsx` `TreeContext` 僅此兩值)。`Inspector` 提供互動式 Controls(size / context / selectionMode / expandOnSelect)即時切換,搭配 `SizeMatrix` / `ColorMatrix` / 元件特有 `IndentMatrix`(縮排規則) / `StateBehavior`(selected vs expanded 語意分離) / `KeyboardMatrix` / `Accessibility` 完整覆蓋。
 
-TreeView 真實展示需要**多層巢狀結構**才有意義(單節點無法體現樹形設計),互動 Inspector 切換單一 prop 無法呈現 `IndentMatrix`(縮排與 guide line 規則)、`StateBehavior`(selected + expanded 正交語意)這類需要完整樹形視覺才能傳達的設計。改以 `Overview` 的完整樹範例 + 各結構矩陣覆蓋。
+TreeView 真實展示需要**多層巢狀結構**才有意義(單節點無法體現樹形設計),故 `Inspector` 以真實的 Engineering 團隊檔案樹為 render 對象;`IndentMatrix`(縮排與 guide line 規則)、`StateBehavior`(selected + expanded 正交語意)這類需要完整樹形視覺才能傳達的設計則另以靜態矩陣呈現。
 
-對應 anatomy story:保留 `Overview` + `SizeMatrix` + `ColorMatrix` + 元件特有 `IndentMatrix` + `StateBehavior` + `KeyboardMatrix`。
+對應 anatomy story:`Overview` + `Inspector` + `SizeMatrix` + `ColorMatrix` + 元件特有 `IndentMatrix` + `StateBehavior` + `KeyboardMatrix` + `Accessibility`。
 
 ---
 
@@ -353,18 +391,27 @@ TreeView 真實展示需要**多層巢狀結構**才有意義(單節點無法體
 
 ## A11y 預設
 
-**ARIA / Pattern**:繼承 Radix `collapsible` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/collapsible#accessibility)。
+**ARIA / Pattern**:自建 ARIA tree(非沿用 Radix 預設)。容器 `role="tree"`(多選時加 `aria-multiselectable`),每個 node `role="treeitem"` + `aria-expanded`(expandable 才有)/ `aria-selected` / `aria-level`,皆由元件手動設定(`tree-view.tsx` TreeItem render)。Radix `collapsible` 僅用於 children 展開 / 收合的高度動畫,**不提供** tree 的 role / aria / 鍵盤導覽(Radix 沒有 Tree primitive,見「定位」段)。對齊 [WAI-ARIA TreeView pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/)。`aria-setsize` / `aria-posinset` **刻意省略**:APG 規定只有當節點未全數 render 進 DOM(lazy load)或 DOM 序 ≠ 閱讀序時才必需;本元件全可見節點皆在 DOM(`querySelectorAll('[role="treeitem"]:not([hidden])')`)且 DOM 序 = 閱讀序,故非必需。
+
+**Accessible name(必填契約)**:`role="tree"` 的名稱無法從子節點內容推導,consumer **必須**提供 `aria-label`(直接字串)或 `aria-labelledby`(指向可見標題的 id)其中之一——有可見標題時優先 `aria-labelledby`,無則用 `aria-label`。兩者皆缺 → 螢幕閱讀器只讀出「tree」無法辨識用途(WAI-ARIA APG 要求 `role="tree"` 具 accessible name)。`tree-view.tsx` 於 `process.env.NODE_ENV !== 'production'` 時 `console.warn` 提示,避免上線後才發現無名稱樹(對齊 Button / Tag 的 dev-only 誤用警告 idiom)。
+
+**Keyboard 行為**(自建 handler,`tree-view.tsx` handleKeyDown):
+
+- Tab — 焦點進入整棵 tree(單一 tab stop)
+- ↑/↓ — 在可見 node 之間移動
+- → — 展開 node,已展開則移到第一個 child
+- ← — 收合 node,leaf 則跳回 parent
+- Home / End — 跳到第一個 / 最後一個可見 node
+- Enter / Space — 選取目前 node
+- Cmd/Ctrl+Shift+↑/↓/→/← — 重排目前 node(僅 `draggable` 時;上下 = 同層移動、→ = 移入 folder、← = 移出到上層,詳「鍵盤重排」段)
 
-**Keyboard 行為**:
+**Focus**:焦點由元件自管(`aria-activedescendant` virtual focus,非 roving tabindex)——DOM focus 固定停在 tree 容器(單一 tab stop,root `tabIndex={0}`),鍵盤移動時 `aria-activedescendant` 指向目前 node,並用內描邊高亮標示(`ring-2 ring-ring ring-inset`,非 `outline`)。**無** focus trap、**無** focus restoration(tree 不是浮層,不需要)。
 
-- Tab — 進入 tree
-- ↑/↓ — 導覽 items
-- ←/→ — collapse/expand
-- Enter — activate
+**「單一 tab stop」範圍限樹的 node 導覽**:auto-render checkbox 與 consumer 傳入的 `checkbox` element 都由 TreeItem 正規化為 `aria-hidden` + `tabIndex={-1}`，只鏡像 treeitem 的 `aria-selected`、不佔 tab 序；但公開 `inlineActions` / `inlineActionsSlot` 經 `ItemInlineAction` 渲染的原生 `<button>` 是各自獨立的 tab stop(對齊 GitHub / VS Code 檔案樹「row action 可 Tab」慣例)。故當某列有 inline actions 時,整頁 Tab 序會依序停在這些按鈕上——「單一 tab stop」指的是**樹形節點導覽**進出點,非「整棵樹含 action 只有一個 tab 停靠」。
 
-**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+**SR 播報(重排)**:鍵盤重排結果經 TreeView 自有 sr-only `role="status"` polite live region 播報,tree 容器 `aria-describedby` 指向 sr-only 操作說明(兩者僅 `draggable` 時渲染、皆在 `role="tree"` 之外——tree 的合法 children 只有 treeitem / group);文案可經 `reorderAnnouncements` prop 覆寫,詳「鍵盤重排」段。
 
-**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作導覽 / 選取 / 展開收合 / **拖曳重排**(無需滑鼠;2026-07-14 v1 補齊——重排走容器 handleKeyDown 的 `Cmd/Ctrl+Shift+方向鍵` 分支,非 dnd-kit `KeyboardSensor`,sensors 仍僅 `PointerSensor`,見「鍵盤重排」段)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 
@@ -372,3 +419,5 @@ TreeView 真實展示需要**多層巢狀結構**才有意義(單節點無法體
 
 - `accordion.spec.md`
 - `combobox.spec.md`
+- `data-table.spec.md`
+- `sidebar.spec.md`