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

package/src/components/ScrollArea/scroll-area.principles.stories.tsx

@@ -0,0 +1,331 @@
+// @story-baseline: packages/design-system/src/components/DataTable/data-table.anatomy.stories.tsx#AlignmentRule
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
+import { createColumnHelper } from '@tanstack/react-table'
+import { ScrollArea, ScrollBar } from './scroll-area'
+import { DataTable } from '@/design-system/components/DataTable/data-table'
+import '@/design-system/components/DataTable/column-types' // ColumnMeta declaration merging
+
+const meta: Meta = {
+  title: 'Design System/Components/ScrollArea/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+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-wrap gap-6 items-start">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal mt-2 ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+// ── Sample data ───────────────────────────────────────────────────────────────
+
+const NOTION_PAGES = [
+  'Getting Started', 'Daily journal', 'Reading list', 'Recipes', 'Weekend projects',
+  'Japan 2026 trip', 'Engineering wiki', 'Design system spec', 'Meeting notes',
+  'Roadmap Q2', 'Incident retrospectives', 'Onboarding docs',
+]
+
+// Stripe 寬欄位商品表 — 消費真 DataTable(per data-table.spec.md「簡單展示場景也用 DataTable」,
+// 對齊展示頁 HorizontalProductTable 同模式)。height="auto" + min-w-max:DataTable 無高度約束、
+// 不啟內部捲軸,捲動完全由外層 ScrollArea / native overflow 容器 own。
+type StripeProduct = {
+  sku: string; name: string; category: string; stock: number
+  price: string; margin: string; channel: string; status: string
+}
+
+const STRIPE_PRODUCTS: StripeProduct[] = [
+  { sku: 'PRO-001', name: 'Stripe Atlas 新創設立方案', category: 'Incorporation', stock: 128, price: '$500.00', margin: '42%', channel: 'Direct', status: 'Active' },
+  { sku: 'PRO-002', name: 'Stripe Radar 詐欺偵測加購', category: 'Add-on', stock: 256, price: '$0.05/tx', margin: '78%', channel: 'Direct', status: 'Active' },
+  { sku: 'PRO-003', name: 'Stripe Tax 自動稅額計算', category: 'Compliance', stock: 64, price: '$0.50/tx', margin: '65%', channel: 'Partner', status: 'Active' },
+  { sku: 'PRO-004', name: 'Stripe Connect 分潤平台帳號', category: 'Platform', stock: 32, price: '$2/acct', margin: '55%', channel: 'Direct', status: 'Beta' },
+  { sku: 'PRO-005', name: 'Stripe Issuing 實體卡發行', category: 'Cards', stock: 16, price: '$3/card', margin: '38%', channel: 'Partner', status: 'Active' },
+  { sku: 'PRO-006', name: 'Stripe Climate 碳移除貢獻', category: 'Sustainability', stock: 8, price: '1% gross', margin: '—', channel: 'Direct', status: 'Active' },
+]
+
+// 取 count 列(> 6 時循環 base 資料、SKU 連號 — 對齊展示頁 PULL_REQUESTS 生成模式)
+const productRows = (count: number): StripeProduct[] =>
+  Array.from({ length: count }, (_, i) => ({
+    ...STRIPE_PRODUCTS[i % STRIPE_PRODUCTS.length],
+    sku: `PRO-${String(i + 1).padStart(3, '0')}`,
+  }))
+
+const productCol = createColumnHelper<StripeProduct>()
+
+const PRODUCT_COLUMNS = [
+  productCol.accessor('sku', { header: 'SKU', meta: { type: 'string', width: 100 } }),
+  productCol.accessor('name', { header: 'Product', meta: { type: 'string', width: 240 } }),
+  productCol.accessor('category', { header: 'Category', meta: { type: 'string', width: 130 } }),
+  productCol.accessor('stock', { header: 'Stock', meta: { type: 'number', width: 90 } }),
+  productCol.accessor('price', { header: 'Price', meta: { type: 'string', align: 'right', width: 110 } }),
+  productCol.accessor('margin', { header: 'Margin', meta: { type: 'string', align: 'right', width: 90 } }),
+  productCol.accessor('channel', { header: 'Channel', meta: { type: 'string', width: 100 } }),
+  productCol.accessor('status', { header: 'Status', meta: { type: 'string', width: 110 } }),
+]
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+// ── WhenToUse — 何時使用 ScrollArea ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / WhenNotToUse(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 ScrollArea 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/ScrollArea/展示" name="垂直捲動 — Linear 議題清單"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">垂直捲動 — Linear issue 清單</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/ScrollArea/展示" name="垂直捲動 — Notion 側欄 導覽"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">垂直捲動 — Notion sidebar 導覽</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/ScrollArea/展示" name="水平捲動 — Stripe 寬欄位商品表"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">水平捲動 — Stripe 寬欄位商品表</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/ScrollArea/展示" name="雙向捲動 — GitHub PR 大型檢閱表"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">雙向捲動 — GitHub PR 大型檢閱表</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
+    </div>
+
+      {/* vs Native scroll — 原 ScrollAreaVsNative */}
+      <div>
+      <Rule
+        title="vs Native scroll — 整頁捲動保持 native document scroll"
+        note="瀏覽器的 document 層級捲動是 OS 慣例——保留 native 讓使用者得到 reader mode / pull-to-refresh / 鍵盤快速鍵等原生能力。ScrollArea 是 sub-region 工具,不為整頁服務。"
+      >
+        <div className="w-[320px]">
+          <div className="border border-border rounded-md bg-surface p-4">
+            <div className="text-body font-medium mb-2">Stripe Dashboard</div>
+            <div className="text-caption text-fg-muted">整個頁面長內容,交給瀏覽器 document scroll</div>
+          </div>
+          <Label>✅ 整頁:不包 ScrollArea,保留 native scrollbar + 瀏覽器能力</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="子區塊捲動 + 跨 OS 視覺一致 → 用 ScrollArea"
+        note="DataTable 橫向捲動 / Sheet body 垂直捲動 / Sidebar nav——這些 sub-region 若用 native scrollbar,Windows 會吃 17px 寬度造成跑版,ScrollArea 的 overlay 捲軸跨 OS 一致不吃寬度。"
+      >
+        <div className="w-[320px]">
+          <ScrollArea className="h-[180px] border border-border rounded-md bg-surface">
+            <div className="p-2">
+              {NOTION_PAGES.map((p) => (
+                <div key={p} className="px-3 py-1.5 text-body hover:bg-neutral-hover rounded">{p}</div>
+              ))}
+            </div>
+          </ScrollArea>
+          <Label>✅ Sidebar nav(sub-region):ScrollArea 跨 OS 一致</Label>
+        </div>
+      </Rule>
+
+      {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
+      <Rule
+        title="❌ 錯誤 — 巢狀 ScrollArea,使用者分不清在捲哪一層"
+        note="當外層與內層都是 ScrollArea 時,滑鼠滾輪捲動的目標不明確(外層?內層?),焦點管理也會崩壞——使用者體驗破碎,a11y 使用者尤其混亂。"
+      >
+        <div className="w-[320px]">
+          <ScrollArea className="h-[220px] border border-error/40 rounded-md bg-surface p-3">
+            <div className="text-body font-medium mb-2">外層 ScrollArea</div>
+            <ScrollArea className="h-[120px] border border-error/40 rounded-md bg-canvas">
+              <div className="p-2">
+                {NOTION_PAGES.slice(0, 8).map((p) => (
+                  <div key={p} className="px-2 py-1 text-caption">{p}</div>
+                ))}
+              </div>
+            </ScrollArea>
+            <div className="mt-2 text-caption">外層繼續內容...</div>
+            {NOTION_PAGES.map((p) => <div key={p} className="text-caption py-1">{p}</div>)}
+          </ScrollArea>
+          <Label warn>滾輪捲動哪一層? 焦點跳到哪? 混亂</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="✅ 正確 — 需要巢狀結構時拆成 Tabs / Accordion / Sheet"
+        note="把第二層內容換成展開/收合的 Tabs 或 Accordion,或推進新的 Sheet / Dialog 呈現——同一個視覺層級只有一個捲動軸,使用者心智清晰。"
+      >
+        <div className="w-[320px]">
+          <ScrollArea className="h-[220px] border border-success/40 rounded-md bg-surface">
+            <div className="p-3">
+              <div className="text-body font-medium mb-2">單層 ScrollArea</div>
+              {NOTION_PAGES.map((p) => (
+                <div key={p} className="px-2 py-1.5 text-body hover:bg-neutral-hover rounded">{p}</div>
+              ))}
+            </div>
+          </ScrollArea>
+          <Label>單一捲動軸,心智清晰</Label>
+        </div>
+      </Rule>
+    </div>
+    </div>
+  ),
+}
+
+export const OrientationChoice: Story = {
+  name: '方向 選擇',
+  render: () => (
+    <div>
+      <Rule
+        title="vertical — 一般垂直清單、Sheet / Dialog body、Sidebar nav"
+        note="預設 orientation。長清單、文件捲動、導覽列——內容沿垂直軸延伸的最常見場景。"
+      >
+        <div className="w-[280px]">
+          <ScrollArea className="h-[180px] border border-border rounded-md bg-surface">
+            <div className="p-2">
+              {NOTION_PAGES.map((p) => (
+                <div key={p} className="px-3 py-1.5 text-body hover:bg-neutral-hover rounded">{p}</div>
+              ))}
+            </div>
+          </ScrollArea>
+          <Label>Notion sidebar — 垂直捲動 12 個頁面項目</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="horizontal — 寬表格、Tag 溢出列、水平時間軸"
+        note="內容沿水平軸延伸且容器寬度受限。須明確渲染 <ScrollBar orientation='horizontal' /> — Radix 預設只處理 vertical。"
+      >
+        <div className="w-[440px]">
+          <ScrollArea className="border border-border rounded-md bg-surface">
+            <div className="min-w-max">
+              <DataTable columns={PRODUCT_COLUMNS} data={productRows(3)} getRowId={(p) => p.sku} height="auto" bordered={false} />
+            </div>
+            <ScrollBar orientation="horizontal" />
+          </ScrollArea>
+          <Label>Stripe 商品表 — 8 欄超出 440px 容器,水平 scrollbar</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="vertical + horizontal — 大型 DataTable 雙向溢出"
+        note="資料網格同時寬且高於容器時,渲染 vertical(自動)+ horizontal ScrollBar,Radix 自動產生右下 corner。"
+      >
+        <div className="w-[440px]">
+          <ScrollArea className="h-[200px] border border-border rounded-md bg-surface">
+            <div className="min-w-max">
+              <DataTable columns={PRODUCT_COLUMNS} data={productRows(12)} getRowId={(p) => p.sku} height="auto" bordered={false} />
+            </div>
+            <ScrollBar orientation="horizontal" />
+          </ScrollArea>
+          <Label>大型商品網格 — 12 列 × 8 欄,雙向 scrollbar + corner</Label>
+        </div>
+      </Rule>
+    </div>
+  ),
+}
+
+export const SolvesDataTableBug: Story = {
+  name: '搭配 DataTable 解跑版',
+  render: () => (
+    <div>
+      <Rule
+        title="問題 — Native horizontal scroll 在 Windows 吃 17px,右側欄被裁切"
+        note="macOS 的 scrollbar 是 overlay 不吃寬度;Windows / Linux always-visible 吃 ~17px。同一份 DataTable 在 macOS 對齊、在 Windows 右側 Status 欄被 scrollbar 壓掉一角 —— 「Left pinned + Row Actions」的典型跑版。"
+      >
+        <div className="w-[560px]">
+          <div className="border border-error/40 rounded-md bg-surface overflow-x-auto">
+            <div className="min-w-max">
+              <DataTable columns={PRODUCT_COLUMNS} data={productRows(4)} getRowId={(p) => p.sku} height="auto" bordered={false} />
+            </div>
+          </div>
+          <Label warn>❌ Native overflow-x-auto — Windows 右側 Status 欄被 scrollbar 吃掉</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="解法 — ScrollArea overlay 捲軸,跨 OS 一致不吃寬度"
+        note="同一份表格,改用 ScrollArea 包起來、額外渲染 horizontal ScrollBar。macOS 與 Windows 呈現完全一致,右側 Status 欄不被裁切。此組合限外層包 height='auto' 表格的 demo 場景;DataTable 中央捲動區本體走 native overflow-x-auto(pinned column 結構需求,見 scroll-area.spec.md「何時用」例外 + data-table.spec.md「捲軸 canonical」)。"
+      >
+        <div className="w-[560px]">
+          <ScrollArea className="border border-success/40 rounded-md bg-surface">
+            <div className="min-w-max">
+              <DataTable columns={PRODUCT_COLUMNS} data={productRows(4)} getRowId={(p) => p.sku} height="auto" bordered={false} />
+            </div>
+            <ScrollBar orientation="horizontal" />
+          </ScrollArea>
+          <Label>✅ ScrollArea + horizontal ScrollBar — 跨 OS 一致</Label>
+        </div>
+      </Rule>
+    </div>
+  ),
+}
+
+export const OutOfScopeRule: Story = {
+  name: '不該用 ScrollArea 的場景',
+  render: () => (
+    <div>
+      <Rule
+        title="❌ 單行 truncate 不用 ScrollArea"
+        note="單行文字超出容器 → 用 text-overflow: ellipsis(CSS truncate),不需要讓使用者水平捲動看一行字。那是 UX 扭曲。"
+      >
+        <div className="w-[320px] flex flex-col gap-3">
+          <div className="border border-success/40 rounded-md px-3 py-2 bg-surface">
+            <div className="text-body truncate">Stripe Atlas 新創設立方案 — 一次搞定公司設立、銀行帳戶、稅務與股權</div>
+          </div>
+          <Label>✅ 用 truncate,一行顯示,超出省略號</Label>
+          <div className="border border-error/40 rounded-md bg-surface">
+            <ScrollArea className="w-full">
+              <div className="whitespace-nowrap text-body px-3 py-2">
+                Stripe Atlas 新創設立方案 — 一次搞定公司設立、銀行帳戶、稅務與股權
+              </div>
+              <ScrollBar orientation="horizontal" />
+            </ScrollArea>
+          </div>
+          <Label warn>❌ 用 ScrollArea 讓使用者水平捲動看一行字,UX 扭曲</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 全頁捲動不用 ScrollArea"
+        note="整個頁面的捲動交給瀏覽器 document scroll——保留 OS 原生體驗(pull-to-refresh / reader mode / 捲動位置記憶)。ScrollArea 只用於 sub-region。"
+      >
+        <div className="w-[320px]">
+          <Label warn>❌ 禁止:在 &lt;body&gt; 或 &lt;html&gt; 外層包 ScrollArea</Label>
+          <Label>✅ 正確:頁面內容直接放,交給瀏覽器 document scroll</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="❌ 極短不會溢出的內容不包 ScrollArea"
+        note="內容小於容器 → 永遠不會捲動 → ScrollArea 是視覺噪音 + 額外 DOM。只在「會溢出」的場景用。"
+      >
+        <div className="w-[320px] flex flex-col gap-3">
+          <div className="border border-success/40 rounded-md px-3 py-2 bg-surface">
+            <div className="text-body">✅ 三行內容,一般 div 就夠</div>
+            <div className="text-caption text-fg-muted">不會溢出,不需 wrapper</div>
+          </div>
+          <div className="border border-error/40 rounded-md bg-surface">
+            <ScrollArea className="h-[80px]">
+              <div className="p-3">
+                <div className="text-body">❌ 極短內容仍包 ScrollArea</div>
+                <div className="text-caption text-fg-muted">多餘 DOM</div>
+              </div>
+            </ScrollArea>
+          </div>
+          <Label warn>❌ 內容不會溢出還包,純視覺噪音</Label>
+        </div>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/ScrollArea/scroll-area.spec.md

@@ -3,23 +3,20 @@ component: ScrollArea
 family: self-contained
 variants: {}
 sizes: {}
-traits:
-  - hasInteractiveStates
+traits: []  # Radix wrapper 捲軸 primitive,無 trait variants(R3 trait enforce 無適用項;2026-07-04 dim 29 補宣告)
 benchmark:
   - Radix ScrollArea primitive: github.com/radix-ui/primitives/tree/main/packages/react/scroll-area
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
-
 # ScrollArea 設計原則
 
 ScrollArea 是**跨 OS 視覺一致的自訂捲動容器**——用 overlay 捲軸取代原生 scrollbar,解決 macOS / Windows / Linux 之間的跑版落差。
 
 **Layout Family**:非上述 family — self-contained primitive(純捲動容器,無 slot 結構)。
 
-**實作基礎**:基於 Radix ScrollArea primitive(shadcn passthrough 結構)——由 Radix 處理 viewport / scrollbar / thumb 的 pointer / keyboard / overflow-detection,本 DS 僅橋接 token(scrollbar 寬度、thumb bg、hover 反饋)。
+**實作基礎**:基於 Radix ScrollArea primitive(shadcn passthrough 結構)——由 Radix 處理 viewport / scrollbar / thumb 的 pointer 拖曳與 overflow-detection,本 DS 橋接 token(scrollbar 寬度、thumb bg、hover 反饋)與 a11y 行為(Viewport `tabIndex={0}` 預設 + `viewportTabIndex={-1}` 雙 tab-stop opt-out + `viewportTabIndex={null}` ARIA composite wrapper opt-out + DS focus ring;Radix 不處理 keyboard,亦不自動標 Viewport focusable)。
 
-**世界級對照**:shadcn `ScrollArea` / Radix primitive 本身。Polaris / Carbon 未提供等效元件(預設相信 native scrollbar);我們採用 shadcn / Radix 派:為了跨 OS 視覺一致、避免 DataTable / Sheet / Dialog 遇 Windows always-visible scrollbar 吃寬度跑版。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**實作取向**:本元件包裝既有 scroll-area primitive，目的是統一跨 OS 的捲軸視覺，並避免 DataTable / Sheet / Dialog 在 always-visible scrollbar 環境中被吃掉內容寬度。
 
 ---
 
@@ -32,7 +29,7 @@ Native scrollbar 跨 OS 不一致:
 | macOS | Overlay——不吃寬度,預設隱藏,捲動時浮出 |
 | Windows / Linux | Always-visible——永遠吃 ~15–17px 寬度 |
 
-**結果**:同一個 DataTable 橫向捲動、Sheet / Dialog 內容垂直捲動在 macOS 視覺對齊,在 Windows 右側被 scrollbar 吃 17px 跑版。「Left pinned + Row Actions」的 DataTable 截圖即是此類 bug。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**結果**:同一個 DataTable 橫向捲動、Sheet / Dialog 內容垂直捲動在 macOS 視覺對齊,在 Windows 右側被 scrollbar 吃 17px 跑版。「Left pinned + Row Actions」的 DataTable 截圖即是此類已觀察的跨 OS bug。
 
 ScrollArea 用 Radix 自訂 overlay 捲軸 → **跨 OS 一致、不吃寬度、捲動時浮出(hover / scroll 自動顯示)**。
 
@@ -40,7 +37,7 @@ ScrollArea 用 Radix 自訂 overlay 捲軸 → **跨 OS 一致、不吃寬度、
 
 ## 何時用
 
-- **DataTable 橫向捲動**——最明顯跑版場景,欄位多於容器寬度時
+- **寬內容橫向捲動**——內容寬於容器的一般場景(寬表格類 demo、程式碼區塊等)。**例外:DataTable 中央捲動區不用 ScrollArea**——走 native `overflow-x-auto` + JS scrollLeft 同步(pinned column 結構需求,理由與 post-v1 重構計畫見 `data-table.spec.md`「捲軸 canonical」節;2026-06-12 收斂跨 spec 張力,以已實作且有 rationale 的 DataTable 側為準)
 - **Sheet / Dialog body 垂直捲動**——內容可能超出容器高度
 - **Sidebar nav 長列表**——導覽項目多於可見高度
 - **任何「內容可能溢出容器」且「跨 OS 視覺必須一致」的 sub-region**
@@ -62,7 +59,7 @@ ScrollArea 用 Radix 自訂 overlay 捲軸 → **跨 OS 一致、不吃寬度、
 | **Document native scroll** | Native scroll 用 OS scrollbar;ScrollArea 用 Radix overlay scrollbar | sub-region container,非全頁 |
 | **AspectRatio** | AspectRatio 鎖比例不 scroll;ScrollArea 允許溢出 scroll | 內容可能 overflow 容器需 scroll |
 
-對齊 Radix ScrollArea / Polaris Scrollable / Material `<Box overflow="auto">` 共識:sub-region scroll,document 留 native。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+本 DS 只在有明確邊界的 sub-region 使用 ScrollArea，document 級捲動保留 native，避免破壞瀏覽器的頁面捲動語意與恢復位置。
 
 ---
 
@@ -70,18 +67,17 @@ ScrollArea 用 Radix 自訂 overlay 捲軸 → **跨 OS 一致、不吃寬度、
 
 - **`vertical`**(預設)——垂直捲動(長清單、Sheet body)
 - **`horizontal`**——水平捲動(寬表格、Tag 溢出列)
-- **同時垂直 + 水平**——大型 DataTable 雙向(consumer 同時渲染兩個 `<ScrollBar>` 或依賴 Radix `type="always"`)
+- **同時垂直 + 水平**——大型 DataTable 雙向(wrapper `<ScrollArea>` 已內建一個 vertical `<ScrollBar>`,consumer 只需再渲染一個 `<ScrollBar orientation="horizontal">`)
 
 ## 視覺 token
 
 | 元素 | Token | 值 |
 |------|-------|----|
 | Scrollbar 寬度 | 固定 10px(`w-2.5` / `h-2.5`) | 跨 size 不變——scrollbar 是功能性元件,不隨內容尺寸變化 |
-| Scrollbar 內距 | `p-[1px]` | 讓 thumb 與容器邊緣有 1px 視覺 inset |
-| Scrollbar 邊界 | `border-l / border-t` transparent | 保留 1px 透明邊,hover 時若需視覺反饋可替換 |
+| Thumb 邊緣 inset | 1px(實作細節見 `.tsx`) | thumb 與容器邊緣保留 1px 視覺 inset,不貼死邊界 |
 | Track | 透明(無 bg) | overlay 浮層,不搶視覺 |
-| Thumb bg | `bg-border` → hover `bg-border-hover` | 靜態時低存在感,hover 加深反饋可抓握 |
-| Thumb radius | `rounded-full` | 圓形 thumb 對齊 macOS / modern DS 慣例 | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| Thumb bg | `--scrollbar-thumb` → hover `--scrollbar-thumb-hover`(semantic alias,resolves to `--border` / `--border-hover` = neutral-5/-6) | 靜態時低存在感,hover 加深反饋可抓握。2026-05-09 抽 SSOT alias 跟 DataTable fake scrollbar 共享 token,避免 thumb 視覺未來演化時誤動 Field/Input/Checkbox border |
+| Thumb radius | `rounded-full` | 圓形 thumb 在垂直／水平方向都保持同一端點幾何 |
 | 過渡 | `transition-colors` | 色彩變化平滑,不做尺寸動畫 |
 
 **Scrollbar 寬度固定 10px 不隨 size 變**:不同 size 的元件(sm/md/lg Button、DataTable)都消費同一個 10px scrollbar;scrollbar 是「捲動機制」不是「內容尺寸」,不需要對齊 content 字級。
@@ -100,23 +96,24 @@ ScrollArea 用 Radix 自訂 overlay 捲軸 → **跨 OS 一致、不吃寬度、
 
 ## A11y 預設
 
-Radix ScrollArea 自動處理:
+Radix primitive + 本 DS a11y 橋接:
 
-- **鍵盤捲動**:Viewport 原生可 focus,支援 `ArrowUp/Down/Left/Right` / `PageUp/Down` / `Home/End`
-- **Focus 可見**:focused viewport 保留原生 focus ring
-- **Scrollbar 非 tab stop**:scrollbar thumb 不搶焦點,使用鍵盤的使用者透過 viewport 捲動
+- **鍵盤捲動**:本 DS 在 Viewport 加 `tabIndex={0}`(預設)使其可被鍵盤聚焦(Radix 不自動把 scroll container 標 focusable,Safari 尤其需要;此即 axe `scrollable-region-focusable` fix)。聚焦後 `ArrowUp/Down/Left/Right` / `PageUp/Down` / `Home/End` 捲動為瀏覽器原生行為,非 Radix 提供。**`viewportTabIndex={-1}` opt-out(2026-07-14)**:內容已有自帶 focusable + 鍵盤處理的元素(如 TimePicker `role="listbox"` `tabIndex={0}`)時傳 `-1`,消除「Viewport+內容雙 tab stop、焦點落 Viewport 時方向鍵觸發原生捲動非元件行為」;axe 由內部 focusable 內容滿足。**`viewportTabIndex={null}` composite opt-out(2026-07-31)**:ScrollArea 被 `role="menu"` 等 ARIA composite 當純結構 wrapper、鍵盤與 focus 由其 item family own 時,完全省略 viewport `tabindex`;`-1` 仍會留下 `div[tabindex]`,不能滿足 composite 的 required-children 結構
+- **Focus 可見**:聚焦的 Viewport 顯示 DS focus ring(`focus-visible:outline-ring`,inset 2px),非瀏覽器原生 focus ring
+- **Scrollbar 非 tab stop**:scrollbar thumb 不搶焦點,使用鍵盤的使用者透過 viewport 捲動(Radix 內建)
 - **Pointer 支援**:thumb 可拖曳,track 可 click-to-jump(Radix 內建)
 
-Consumer 無需額外處理 a11y。
+本元件已內建 `tabIndex`(預設 0;`viewportTabIndex={-1}` / `{null}` 依上述兩種 owner 情境 opt-out)+ focus ring(滿足 axe `scrollable-region-focusable`)。但 Viewport 預設**無 `role` / accessible name**——**若 scroll 區域有具體語意(如「留言列表」「程式碼區塊」),consumer 應提供 `aria-label`**,否則 SR 只報「可捲動區域」無內容描述;純視覺裝飾容器可省略。(2026-05-31 #31:修正原「consumer 無需額外處理 a11y」過度宣稱)
 
 ---
 
 ## 邊界案例
 
-- **Dark mode**:`bg-border` / `bg-border-hover` 自動由 semantic token 切換,無自訂 palette,詳見 `color.spec.md`
+- **Dark mode**:`--scrollbar-thumb` / `--scrollbar-thumb-hover`(resolves to `--border` / `--border-hover`)自動由 semantic token 切換,無自訂 palette,詳見 `color.spec.md`
 - **Density**:scrollbar 寬度不受 density 影響(功能性 primitive,不隨 field-height / layout-space 放大縮小)
 - **Disabled**:ScrollArea 無互動狀態——內容是否可操作由 consumer 決定,captured 容器本身不 disable
 - **Empty**:內容為空時 scrollbar 不顯示(Radix 自動偵測 overflow,無溢出 → scrollbar 隱藏)
+- **Loading**:ScrollArea 只提供捲動能力，不擁有內容 loading；Skeleton / CircularProgress 由 consumer 放在 viewport 內容內。
 
 ---
 
@@ -124,13 +121,17 @@ Consumer 無需額外處理 a11y。
 
 ScrollArea 是**捲動容器 primitive**,本身**無互動狀態**(見「邊界案例」段:無 disabled,內容捲動由瀏覽器原生處理)。唯一的 state 是「scrollbar visible / hidden」,但這由 Radix 依 overflow 自動偵測,非 consumer 或元件 prop 可控。重寫 StateBehavior 會讓 consumer 誤以為有 hover / focus / disabled prop 可切。orientation(水平 / 垂直 / 雙向)的結構變化由元件特有 `OrientationBehavior` own。
 
-對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(scrollbar track / thumb 色) + `SizeMatrix` + 元件特有 `OrientationBehavior`。
+對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(scrollbar track / thumb 色) + `SizeMatrix` + `Accessibility` + 元件特有 `OrientationBehavior`。
 
 ---
 
+## Radix Viewport `display:table` 陷阱 + `fillX`(2026-07-08 WM 戰役 codify)
+
+Radix Viewport 內建 wrapper `min-width:100%; display:table`——這是**水平捲動的 min-content 溢出機制**,但對「垂直捲動容器內的多欄 flex 佈局」是陷阱:內容以 max-content 佈局突破 100% 寬(WM 兩欄 dialog 右欄被裁 33px 實證)。垂直捲動場景 opt-in `fillX` prop 中和為 block/w-full;**水平捲動勿開**。DialogBody 已預設開啟。
+
 ## 相關
 
-- `../DataTable/data-table.spec.md` — 主要 consumer(橫向捲動跑版問題的解法來源)
+- `../DataTable/data-table.spec.md` — 歷史動機來源(橫向捲動跑版問題),**非 consumer**:DataTable 中央捲動區走 native `overflow-x-auto`(0 import,見上方「何時用」例外 +「捲軸 canonical」節)
 - `../Sheet/sheet.spec.md` — body 捲動
 - `../Dialog/dialog.spec.md` — body 捲動
 - `../Sidebar/sidebar.spec.md` — nav 長列表捲動
@@ -141,5 +142,6 @@ ScrollArea 是**捲動容器 primitive**,本身**無互動狀態**(見「邊界
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `dialog.spec.md`
 - `file-viewer.spec.md`
 - `overlay-surface.spec.md`