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

package/src/components/Tabs/tabs.principles.stories.tsx

@@ -0,0 +1,291 @@
+// @principles-rationale: Merged WhenToUse + WhenNotToUse + TabsVsSegmentedControl
+// into a single `UsageGuidance` story (3 sections — 何時用 / 何時不用 + 替代 / vs 近親)
+// per 2026-04-26 user mandate. SizeSelection + TriggerSlots kept as separate principles.
+import type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
+import { Users, Settings, Bell } from 'lucide-react'
+import { Tabs, TabsList, TabsTrigger, TabsContent } from './tabs'
+import { SegmentedControl, SegmentedControlItem } from '@/design-system/components/SegmentedControl/segmented-control'
+import { Badge } from '@/design-system/components/Badge/badge'
+
+const meta: Meta = {
+  title: 'Design System/Components/Tabs/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-body-lg font-semibold text-foreground mb-3 pb-1 border-b border-divider">{title}</h2>
+    <div>{children}</div>
+  </section>
+)
+
+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-4">{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>
+)
+
+// ── UsageGuidance ────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose">
+          <p>適合 Tabs 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li>
+              <LinkTo kind="Design System/Components/Tabs/展示" name="帶後綴"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">帶後綴</span></LinkTo>
+            </li>
+            <li>
+              <LinkTo kind="Design System/Components/Tabs/展示" name="溢出處理 — 水平捲動"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">溢出處理 — 水平捲動</span></LinkTo>
+            </li>
+            <li>
+              <LinkTo kind="Design System/Components/Tabs/展示" 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>
+      </Section>
+
+      <Section title="何時不用 + 替代">
+        <Rule
+          title="❌ 單一 tab 的 Tabs"
+          note="只有一個 trigger 沒有切換語意——應該直接顯示內容,不需要 tabs"
+        >
+          <Tabs defaultValue="a">
+            <TabsList>
+              <TabsTrigger value="a">唯一選項</TabsTrigger>
+            </TabsList>
+            <TabsContent value="a" className="text-body text-fg-primary">唯一內容區沒有切換價值,應直接顯示。</TabsContent>
+          </Tabs>
+          <Label warn>↑ 這個 Tabs 沒有意義,直接顯示內容</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 等分 / fullWidth 的 Tabs"
+          note="Tabs label 長度天然不均(「總覽」2 字 vs「成員管理與權限設定」8 字),強制等分會視覺失衡。需要等分選項改用 SegmentedControl"
+        >
+          <div className="w-full">
+            <SegmentedControl defaultValue="day" fullWidth>
+              <SegmentedControlItem value="day">日</SegmentedControlItem>
+              <SegmentedControlItem value="week">週</SegmentedControlItem>
+              <SegmentedControlItem value="month">月</SegmentedControlItem>
+            </SegmentedControl>
+            <Label>↑ 需要等分?改用 SegmentedControl</Label>
+          </div>
+        </Rule>
+
+        <Rule
+          title="❌ 用 Tabs 做頁面層級路由切換"
+          note="Tabs 是「同一上下文底下切換 view」,不是頁面導覽。路由層級切換應該用 navigation / breadcrumb,URL 要跟著變"
+        >
+          <Tabs defaultValue="home">
+            <TabsList>
+              <TabsTrigger value="home">首頁</TabsTrigger>
+              <TabsTrigger value="products">產品列表</TabsTrigger>
+              <TabsTrigger value="about">關於我們</TabsTrigger>
+            </TabsList>
+            <TabsContent value="home" className="text-body text-fg-primary">首頁是獨立路由,不應由 Tabs 承載。</TabsContent>
+            <TabsContent value="products" className="text-body text-fg-primary">產品列表是獨立路由,不應由 Tabs 承載。</TabsContent>
+            <TabsContent value="about" className="text-body text-fg-primary">關於我們是獨立路由,不應由 Tabs 承載。</TabsContent>
+          </Tabs>
+          <Label warn>↑ 這些是獨立頁面,不該用 Tabs</Label>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親 — Tabs vs SegmentedControl">
+        <Rule
+          title="規模:一整塊 container vs 局部變體"
+          note="Tabs 切換的是一整塊 container(可能有自己的 header / toolbar / 多個 section),每個 view 是獨立的子頁規模。SegmentedControl 切換的是局部內容的變體——單一 chart 的維度、單一 list 的排序、單一 form section 的條件欄位。兩者都能『切換下方內容』,但前者是結構、後者是 control"
+        >
+          <div>
+            <Label>✅ Tabs:電商後台,每個 view 是獨立子頁(各自有 filters / table / actions)</Label>
+            <Tabs defaultValue="orders">
+              <TabsList>
+                {/* 2026-07-04:同組 startIcon 全有或全無(spec 禁止事項)— 原 顧客/設定 混用 icon 已移除 */}
+                <TabsTrigger value="orders">訂單</TabsTrigger>
+                <TabsTrigger value="customers">顧客</TabsTrigger>
+                <TabsTrigger value="products">產品</TabsTrigger>
+                <TabsTrigger value="settings">設定</TabsTrigger>
+              </TabsList>
+              <TabsContent value="orders" className="text-body text-fg-muted">1,284 筆訂單 · 篩選「待出貨」· 批次列印出貨單</TabsContent>
+              <TabsContent value="customers" className="text-body text-fg-muted">顧客名單、分群標籤與生命週期價值</TabsContent>
+              <TabsContent value="products" className="text-body text-fg-muted">商品目錄、庫存與上下架狀態</TabsContent>
+              <TabsContent value="settings" className="text-body text-fg-muted">商店設定：金流、物流、稅率</TabsContent>
+            </Tabs>
+          </div>
+          <div>
+            <Label>✅ SegmentedControl:Dashboard chart 的時間維度切換(局部變體,不是結構)</Label>
+            <SegmentedControl defaultValue="week">
+              <SegmentedControlItem value="day">日</SegmentedControlItem>
+              <SegmentedControlItem value="week">週</SegmentedControlItem>
+              <SegmentedControlItem value="month">月</SegmentedControlItem>
+              <SegmentedControlItem value="quarter">季</SegmentedControlItem>
+            </SegmentedControl>
+            <Label>↑ 切換會讓下方 chart 重新載入,但切的是 chart 的一個維度,不是整個 container</Label>
+          </div>
+        </Rule>
+
+        <Rule
+          title="視覺角色:container 結構 vs compact control"
+          note="Tabs 佔整行、與父容器 header border 對齊,是 section 的 anchor。SegmentedControl 是 pill 尺寸,能跟 Button / Input 並排而不違和。判斷 fallback:放進 toolbar 或 Field 感覺自然 → SegmentedControl;必須自己獨佔一行 → Tabs"
+        >
+          <div>
+            <Label>✅ SegmentedControl 在 toolbar 裡跟 Button / Input 並排</Label>
+            <div className="flex items-center gap-3 p-2 border border-border rounded-md w-fit">
+              <SegmentedControl defaultValue="list" size="sm">
+                <SegmentedControlItem value="list">清單</SegmentedControlItem>
+                <SegmentedControlItem value="board">看板</SegmentedControlItem>
+              </SegmentedControl>
+              <div className="h-5 w-px bg-divider" />
+              <span className="text-body text-fg-muted">工具列其他控制項…</span>
+            </div>
+            <Label>↑ 同 toolbar 尺度,跟其他 control 並排。換成 Tabs 在這個位置會違和</Label>
+          </div>
+        </Rule>
+
+        <Rule
+          title="❌ 不能用 Tabs 做 form field"
+          note="付款方式 / 配送方式這類「選一個、下方欄位跟著變」的 form section 看起來像 Tabs(切換內容),但它是表單內的一個 field(值會送出、跟其他 form field 同行文化),應該用 SegmentedControl。Tabs 不能塞進 Field、也不參與表單狀態"
+        >
+          <div>
+            <Label>✅ 付款方式(SegmentedControl + 下方條件欄位)</Label>
+            <div className="flex flex-col gap-2 w-[400px]">
+              <span className="text-caption text-fg-muted">付款方式</span>
+              <SegmentedControl defaultValue="card">
+                <SegmentedControlItem value="card">信用卡</SegmentedControlItem>
+                <SegmentedControlItem value="bank">銀行轉帳</SegmentedControlItem>
+                <SegmentedControlItem value="cash">貨到付款</SegmentedControlItem>
+              </SegmentedControl>
+              <div className="mt-2 text-caption text-fg-muted">(下方依選擇顯示卡號 / 銀行帳號 / 收件資訊欄位)</div>
+            </div>
+          </div>
+        </Rule>
+      </Section>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const { expect, userEvent, waitFor, within } = await import('@storybook/test')
+    const canvas = within(canvasElement)
+    const assertControlledPanelExists = async (name: string) => {
+      const tab = canvas.getByRole('tab', { name })
+      await userEvent.click(tab)
+      await waitFor(() => {
+        expect(tab).toHaveAttribute('aria-selected', 'true')
+        const panelId = tab.getAttribute('aria-controls')
+        expect(panelId).toBeTruthy()
+        expect(document.getElementById(panelId as string)).not.toBeNull()
+      })
+    }
+
+    await assertControlledPanelExists('唯一選項')
+    await assertControlledPanelExists('首頁')
+    await assertControlledPanelExists('產品列表')
+    await assertControlledPanelExists('關於我們')
+    await assertControlledPanelExists('首頁')
+  },
+}
+
+// ── Size ─────────────────────────────────────────────────────────────────────
+
+export const SizeSelection: Story = {
+  name: '尺寸選擇',
+  render: () => (
+    <div>
+      <Rule
+        title="sm — ★ 預設,overlay / chrome / dense toolbar"
+        note="h-tab-sm(32/40)。所有 header 內 tabs 預設用 sm(對齊 Ant Design verbatim「small size could be used in Modal」)"
+      >
+        <Tabs defaultValue="a">
+          <TabsList size="sm">
+            <TabsTrigger value="a">一般</TabsTrigger>
+            <TabsTrigger value="b">進階</TabsTrigger>
+          </TabsList>
+          <TabsContent value="a" className="text-body text-fg-secondary mt-2">名稱、描述與可見範圍等一般設定</TabsContent>
+        </Tabs>
+      </Rule>
+
+      <Rule
+        title="md — future tier(目前無 recommended use case)"
+        note="h-tab-md(40/48)。中間階梯保留 token,新 consumer 必先諮詢 DS owner(多家世界級 DS 只有 1 個 default size,無中間階梯)"
+      >
+        <Tabs defaultValue="a">
+          <TabsList size="md">
+            {/* 2026-07-04:同組 icon 全有或全無(spec 禁止事項)— 原 成員 單獨帶 icon 已移除 */}
+            <TabsTrigger value="a">總覽</TabsTrigger>
+            <TabsTrigger value="b">成員</TabsTrigger>
+            <TabsTrigger value="c" badge={<Badge count={3} />}>通知</TabsTrigger>
+          </TabsList>
+          <TabsContent value="a" className="text-body text-fg-secondary mt-2">專案的總覽資訊（KPI、最近活動）</TabsContent>
+        </Tabs>
+      </Rule>
+
+      <Rule
+        title="lg — 獨立 tabs 取代 chrome header(罕見 page-level hero)"
+        note="h-tab-lg(48/56)= --chrome-header-height 像素相等。整個頁面的主結構切換,tabs 本身取代 chrome header 位置(對齊 Ant verbatim「Large size tabs are usually used in page header」)"
+      >
+        <Tabs defaultValue="a">
+          <TabsList size="lg">
+            <TabsTrigger value="a">產品</TabsTrigger>
+            <TabsTrigger value="b">服務</TabsTrigger>
+          </TabsList>
+          <TabsContent value="a" className="text-body text-fg-secondary mt-2">產品功能、方案與定價總覽</TabsContent>
+        </Tabs>
+      </Rule>
+    </div>
+  ),
+}
+
+// ── Trigger 結構 ──────────────────────────────────────────────────────────────
+
+export const TriggerSlots: Story = {
+  name: '觸發位置插槽使用',
+  render: () => (
+    <div>
+      <Rule
+        title="startIcon 描述 tab 的內容性質"
+        note="使用名詞性 icon(人像配「成員」、齒輪配「設定」、鈴鐺配「通知」)。不放動詞性 icon(Download、Trash2),tab 是視圖切換不是動作觸發。同一組 tabs 內 startIcon 全有或全無、不混用(spec 禁止事項),下方三個 trigger 皆帶 icon 即為「全有」的 uniform 示範"
+      >
+        <Tabs defaultValue="a">
+          <TabsList>
+            <TabsTrigger value="a" startIcon={Users}>成員</TabsTrigger>
+            <TabsTrigger value="b" startIcon={Settings}>設定</TabsTrigger>
+            <TabsTrigger value="c" startIcon={Bell}>通知</TabsTrigger>
+          </TabsList>
+          <TabsContent value="a" className="text-body text-fg-secondary mt-2">成員名單與角色權限管理</TabsContent>
+        </Tabs>
+      </Rule>
+
+      <Rule
+        title="badge 傳達該 view 底下的待處理計數"
+        note="「通知 3」「成員 12」。未選中時也應顯示 badge——否則使用者不知道該切過去"
+      >
+        <Tabs defaultValue="inbox">
+          <TabsList>
+            <TabsTrigger value="inbox">收件匣</TabsTrigger>
+            <TabsTrigger value="unread" badge={<Badge count={12} />}>未讀</TabsTrigger>
+            <TabsTrigger value="starred" badge={<Badge count={3} />}>星標</TabsTrigger>
+          </TabsList>
+          <TabsContent value="inbox" className="text-body text-fg-secondary mt-2">收件匣的所有訊息（依時間排序）</TabsContent>
+        </Tabs>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/Tabs/tabs.spec.md

@@ -4,11 +4,11 @@ family: composite
 variants: {}
 sizes:
   sm:
-    when: "form field-height 28 / compact chrome / dialog / panel context"
+    when: "★ cva default — 所有 header 內 tabs(overlay / chrome header / Dialog / Sidebar / dense toolbar)"
   md:
-    when: "default general UI"
+    when: "future tier — 目前無 recommended use case,新 consumer 須先諮詢 DS owner"
   lg:
-    when: "touch / prominent CTA / stakeholder-facing surface"
+    when: "獨立 tabs 直接取代 chrome header — page-level workspace 主導覽(tab 高度 = chrome-header-height)"
 traits:
   - hasSizes
   - hasInteractiveStates
@@ -20,8 +20,6 @@ benchmark:
   - Polaris Tabs: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Tabs
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
-
 # Tabs 設計原則
 
 ## 定位
@@ -82,29 +80,24 @@ TabsList ─┬─ TabsTrigger  [startIcon?] [label] [suffix?: badge? + endIcon?
 TabsContent ← 對應被選中的 trigger
 ```
 
-**單個 Trigger 內部**：
+**Trigger ↔ panel IDREF 鐵律**:composition 必須為每個 `TabsTrigger value="x"` 提供同 value 的 `<TabsContent value="x">`;該 trigger 成為 active 時,Radix 的 `aria-controls` 必解析到已掛載 panel。Inactive panel 的同時掛載生命週期由 Radix 管理,本 DS 不另要求 `forceMount`。即使某個反例 story 刻意展示「不該用 Tabs」的產品語意,也不得省略 panel 而讓 active trigger 產生懸空 IDREF。內容為空時仍渲 `TabsContent` + `<Empty>`,不以缺 DOM panel 表達空值。
 
-```
-[startIcon?]  [label]  [suffix?]
-  ↑            ↑         ↑
-  16/20px      plain     span(gap-1): [badge?] [endIcon?]
-               span
-  │─── gap-2 ────│─── gap-2 ──│
-```
-
-- **Trigger 三層 slot 間 gap-2**（8px），對標 **item-layout pattern** 的橫向 inline 變體
-- **suffix 內 gap-1**（4px），對標 **Button** suffix wrapper（`button.tsx:288`）
+**單個 Trigger 內部**：`[startIcon 16/20px] ─gap-2─ [label] ─gap-2─ [suffix span(gap-1): badge? endIcon?]`——slot 間 **gap-2**（8px）對標 **item-layout pattern** 橫向 inline 變體；suffix 內 **gap-1**（4px）對標 **Button** suffix wrapper（`button.tsx` 的 `<span className="inline-flex items-center gap-1">`）
 - `startIcon` 描述 tab 的內容性質（人像 icon 配「成員」、齒輪 icon 配「設定」）
 - `badge` 傳達該 tab 底下的待處理計數（「通知 3」「成員 12」）
 - `endIcon` **純視覺 indicator only**（方向 / 狀態 — ChevronDown 暗示「展開後看到子內容」、Pin / Star 狀態徽記）。**不拼 click 行為** — 點到 endIcon 跟點到 tab body 同效果（切 tab）
-- `inlineAction`（2026-05-21 加）拆分 click target：點到 inlineAction 走它自己的 handler 不切 tab；典型如「『更多 ▾』tab 後綴點開 overflow dropdown 不切 tab」（split-click pattern,對齊 GitHub「Code ▾」/ Linear "Triage..." menu / Atlassian split-tab 共識）
+- `inlineAction`（2026-05-21 加）拆分 click target：點到 inlineAction 走它自己的 handler 不切 tab；典型如「『更多 ▾』tab 後綴點開 overflow dropdown 不切 tab」。**DOM 結構(2026-07-18 決策1 axe 正規修)**:inlineAction **portal 到 `TabsList` 的 overlay 層(`role=tablist` 之外的 sibling div)**,以 trigger 的量測座標(viewport-relative,涵蓋 none/scroll/menu)定位在 trigger 右緣預留的 paddingRight 區。**為什麼不放 tablist 內**:`role=tablist` 只能擁有 `role=tab`(ARIA required-children);inlineAction(`button[aria-haspopup]`)DOM-在 tablist 內會觸發 axe critical,故 portal 出去。trigger 本身仍在 tablist 內(底層 primitive 的 roving focus 要求 trigger 為 List React 子代)。**演進史**:2026-07-05 先修 button-巢-button(nested-interactive serious,改 sibling 佈局);2026-07-18 再修 button-在-tablist(required-children critical,改 portal overlay)。**代價(user 2026-07-18 拍板接受)**:鍵盤 Tab 序 = 全部 tab 之後才到 action(action 現為 overlay 內獨立 tab stop)。click 天然分流(action portal 出 trigger 子樹,不冒泡)。
+
+  **可視 viewport 契約(2026-08-02 regression fix)**:實際 viewport = overlay 與 trigger 所有 overflow-clipping ancestors 的交集。trigger 完全不相交時不 render action；部分相交時僅在 canonical trailing action slot 完整可見才 render。**禁 clamp** action 到 viewport 內，否則會侵入 label/suffix 並破壞 canonical 8px content→action gap。consumer `style` 可合併其他 key，但不可覆寫該 padding reservation。
+
+  **⚠️ ARIA required-children 鐵律(泛化,防同類 regression)**:任何 composite widget 容器(`role=tablist` / `listbox` / `menu` / `radiogroup` / `tree`)只能擁有其 required child role;要在容器「格子」旁塞獨立互動 element(action / dropdown trigger)時,**必 portal 出容器 DOM 子樹 + 量測定位**(aria-owns 不可行:axe required-children 計 DOM-owned 子代,不因 aria-owns 排除)。對齊 W3C ARIA APG composite-widget owned-elements 規範。
 
 ### 對標對象與故意的偏離
 
 Tabs trigger = **item-layout 橫向變體 + Button 高度系統**。對標 item-layout 的:slot gap-2 / startIcon-label-suffix 三格固定 / suffix 可組合容器。對標 Button 的:固定高度 token(`--tab-height-*`)/ icon size 查表 / suffix wrapper gap-1。
 
 三處刻意偏離 item-layout:
-- **固定高度** `h-[var(--tab-height-*)]` + `items-center`(非 `h-[1lh]`)— Tabs 是 Button 樣的固定容器,非內容撐高 row
+- **固定高度** `h-[var(--tab-height-N) N∈{sm,md,lg}]` + `items-center`(非 `h-[1lh]`)— Tabs 是 Button 樣的固定容器,非內容撐高 row
 - **無 `<ItemIcon>` / `<ItemLabel>` helper**,直接吃 `LucideIcon` prop + 裸 `<span>` label — slot 固定三格,無複雜 prefix mixing
 - **label 不包 `<span>` padding wrapper**(對比 Button 設計) — selected underline 必須 fit content,label 有橫向 padding 會讓 underline 多 8px 鬆散
 
@@ -116,7 +109,7 @@ Tabs trigger = **item-layout 橫向變體 + Button 高度系統**。對標 item-
 
 **Tabs 目前只有一種視覺**：底線標示型（underline indicator）。
 
-選中 trigger 底部有 2px 的 `bg-primary` 底線，未選 trigger 僅文字色變化。未來若需要「填色型」或「pill 型」tabs，應先評估是否真的是 Tabs 的語意（通常是 SegmentedControl 或 Button group 的偽裝）再考慮擴充。
+選中 trigger 底部有 2px 的 `bg-primary` 底線（2026-07-06 拍板：持續選中站 base），未選 trigger 僅文字色變化。未來若需要「填色型」或「pill 型」tabs，應先評估是否真的是 Tabs 的語意（通常是 SegmentedControl 或 Button group 的偽裝）再考慮擴充。
 
 ---
 
@@ -127,14 +120,14 @@ Tabs 有三種尺寸,**高度由 `--tab-height-*` token 控制**,隨 `data-densi
 | Size | md density | lg density | 字體 | 何時用 | 世界級對照 |
 |------|-----------|-----------|------|--------|-----------|
 | `sm` ★ cva default(2026-05-17 從 md 改 sm)| 32 | 40 | `text-body` (14) | **預設 use case**:所有 header 內 tabs(overlay header / chrome header / Dialog / Sidebar / dense toolbar)| Ant Design verbatim:「**small size could be used in Modal**」(`ant.design/components/tabs`)|
-| `md` | 40 | 48 | `text-body` (14) | **Future tier — 目前無 recommended use case**;新 consumer 必先諮詢 DS owner | 多家世界級 DS(Material / MUI / Primer / Polaris)只有 1 個 default size,無中間階梯 | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| `md` | 40 | 48 | `text-body` (14) | **Future tier — 目前無 recommended use case**;新 consumer 必先諮詢 DS owner | 保留相容階梯，不作新用例預設 |
 | `lg` | 48 | 56 | `text-body-lg` (16) | **獨立 tabs 直接取代 chrome header 用**(tab 高度 = `--chrome-header-height` 像素相等,48/56)— page-level workspace 主導覽 | Ant verbatim:「**Large size tabs are usually used in page header**」(`ant.design/components/tabs`)|
 
 **Token alignment + size 階梯 rationale SSOT**:`--tab-height-lg` (48/56) = `--chrome-header-height` (48/56) 像素相等 + md future tier + sm default 遷移 — **完整 cross-family canonical 詳** `patterns/header-canonical/header-canonical.spec.md` W3/W5/W6(per Rule-of-3 SSOT 集中此處,本元件 spec.md 不重複論述,只列上表 size table)。
 
 ### 為什麼 Tabs 不複用 `--field-height-*`
 
-Tabs 是 navigation container，不是 form control。field-height 的 scale（24–36）是為 input / button 設計，套在 tabs 上高度 < 32px 時底線距 baseline < 8px，違反 navigation breathing 最小值。世界級設計系統（Atlassian 32 / Polaris 44 / Material 48）的 tabs 高度都在 32 起跳。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Tabs 是 navigation container，不是 form control。field-height 的 scale（24–36）是為 input / button 設計；套在 tabs 上高度 < 32px 時，底線距 baseline < 8px，低於本 DS navigation breathing 最小值，因此使用獨立的 `--tab-height-*` 階梯。
 
 ### 為什麼獨立於 `--table-row-*`
 
@@ -150,23 +143,23 @@ Tabs 支援三種 overflow 策略，透過 `TabsList` 的 `overflow` prop 選擇
 |---|---|---|
 | `none` ★default | 不處理，triggers 溢出父容器 | Tabs 數量可控、一定塞得下 |
 | `scroll` | 單行橫向滾動 + 邊緣 fade mask 指示 | 動態 tabs 但不希望中斷視覺順序 |
-| `menu` | 塞不下收進 `⋯` dropdown，所有 triggers 仍在 DOM | 工具列 tabs、需要完整選項可見 |
+| `menu` | scroll + ⌄ quick-jump dropdown（列全部 tab，點選跳轉），所有 triggers 一直可見 | 工具列 tabs、需要快速跳轉到任一 tab |
 
 ### scroll 模式
 
 外層 overflow-x scroll(scrollbar 隱藏)+ 邊緣 mask-image gradient 依滾動位置動態 fade(不可滾無 mask / 可右→右 fade / 可左→左 fade / 雙向→兩側)。`useScrollEdges()` hook 追蹤狀態。**Mask 不用 gradient overlay**:mask 淡化內容本身 alpha,自動融合任何背景(dark / card / surface);overlay 需寫死背景色會漂移。
 
-**Scroll arrow buttons**(`atStart/atEnd === false` 時顯示 `<ChevronLeft/Right>`,點擊捲 80% 容器寬,smooth scroll):三輸入方式都要顧——鍵盤(Radix 原生方向鍵 + scroll-into-view) / trackpad(兩指橫滑) / 滑鼠滾輪(需 `Shift+wheel`,一般使用者不知道,**必須補 arrow buttons**)。Arrow 容器 `pointer-events-none` + 內層 Button `pointer-events-auto`,不阻擋下方 trigger hit test。對齊 Material 3 / Ant / Carbon / Mantine。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**Scroll arrow buttons**(`atStart/atEnd === false` 時顯示 `<ChevronLeft/Right>`,點擊捲 80% 容器寬,smooth scroll):三輸入方式都要顧——鍵盤(底層 primitive 方向鍵 + scroll-into-view) / trackpad(兩指橫滑) / 滑鼠滾輪(需 `Shift+wheel`,不易發現,因此**必須補 arrow buttons**)。Arrow 容器 `pointer-events-none` + 內層 Button `pointer-events-auto`,不阻擋下方 trigger hit test。
 
 ### menu 模式
 
-所有 TabsTrigger 仍在 DOM(保 Radix roving tabindex),溢出者套 `invisible`(visibility hidden,不接 hit test 但保 layout)。`useOverflowIndices()` 偵測溢出。右側 `<Button variant="text" iconOnly startIcon={MoreVertical} />`(overflow canonical icon)開 DropdownMenu 顯示對應 labels;點 menu item 經 Tabs context `onValueChange` 觸發,Radix 自然更新 `data-state`。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+menu = **scroll 模式 + 額外的 ⌄ quick-jump navigator**(show-all navigator pattern)。全部 TabsTrigger 一直可見、留在底層 `overflow-x-auto` 捲動容器內(**不套 `invisible`、不隱藏溢出**)。右側 `OverflowMenuTriggerButton`(`ChevronDown` ⌄ icon)在有溢出空間時(`canScroll`)出現,點開 DropdownMenu **列出全部 tab**(非只溢出者);當前選中的 tab 用 DropdownMenuItem 的 `selected` 標記(`bg-neutral-selected`,跟 SelectMenu 單選同一套視覺)。點 menu item 經 Tabs context `onValueChange` 觸發切換(底層 primitive 自然更新 `data-state`),同時 `scrollIntoView`(`inline: center`)把該 tab 捲到視圖中央。底層仍是真實捲動容器(非 `overflow-hidden`)的理由:`scrollIntoView` 與鍵盤 focus 的 auto scroll-into-view 都需要真實 scroll 容器;捲軸用 CSS 隱藏。
 
-**a11y**:溢出 trigger 只視覺隱藏仍可 focus;鍵盤使用者方向鍵導覽 / Tab 到 ⋯ 用 dropdown,兩路徑並存。對齊 Ant `moreIcon` / Atlassian Navigation Tabs。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**a11y**:全部 trigger 一直在 DOM 且可見(保留 roving tabindex);鍵盤使用者可用方向鍵導覽全部 tab,或 Tab 到 ⌄ 用 dropdown 快速跳轉,兩路徑並存。
 
 ### 跨元件共用
 
-`useOverflowIndices` / `useScrollEdges` 在 `packages/design-system/src/hooks/use-overflow-items.ts`,`ChipGroup` 的 `layout="scroll" | "menu"` 消費同一組 hook,確保 Tabs / Chip overflow 行為一致。
+`useScrollEdges`(及 `OverflowScrollArrow` / `OverflowMenuTriggerButton`)在 `patterns/horizontal-overflow/horizontal-overflow.tsx`(re-export 自 `hooks/use-overflow-items.ts`),`ChipGroup` 的 `layout="scroll" | "menu"` 消費同一組 primitive,確保 Tabs / Chip overflow 行為一致。注意 Tabs / Chip 的 menu 模式都是 show-all navigator(用 `useScrollEdges` 偵測捲動邊界),**不用** `useOverflowIndices`(那是「動態算溢出 index」用,menu 永遠顯示全部所以不需要)。
 
 ---
 
@@ -176,26 +169,26 @@ Tabs 支援三種 overflow 策略，透過 `TabsList` 的 `overflow` prop 選擇
 
 Tabs 是 **navigation anchor**，不是 compact control：
 - 它在視覺階層上是 section header 等級，用「文字流」的節奏左對齊排列，trigger 間以 `--layout-space-loose` 分隔，接近閱讀動線
-- 「各 segment 同寬」是 SegmentedControl 的身份特徵（對齊 Apple HIG / Material 3 等定義），Tabs 沒有這層視覺契約 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- 「各 segment 同寬」是本 DS SegmentedControl 的身份特徵，Tabs 沒有這層視覺契約
 - 需要 compact 的等寬互斥切換器 → 用 `SegmentedControl`；需要 section-level 的視圖導覽 → 用 Tabs
 
 **Triggers 之間 gap**：使用 `--layout-space-loose`（md density 16px / lg density 24px），與其他「pattern 層級的鬆散留白」共用同一 token。Tabs 的 gap 不是裝飾性空白，而是告訴使用者「每個 tab 是獨立的視圖入口」的視覺分隔。
 
+**TabsList 容器寬度(2026-06-12 user 拍板,解 L58 spec≠code)**:**跨滿父容器**(none 模式 `w-full`;scroll/menu 模式 inner list `min-w-full` 保留溢出成長)——底線連成整條、右端達內容區邊緣,與「跨父容器寬度、與 header border 對齊」的角色定義一致(對齊 Ant nav `left:0;right:0` 底線 / Primer UnderlineNav;shadcn 為 pill 式不同型不適用)。Trigger 本身仍 hug content(上段不變)。**左右邊距 ownership**:TabsList **不自加水平 padding**——邊距由容器的 `--layout-space-loose` gutter 提供(standalone = 父容器 padding;withTabs = 繼承 header padding,W2 lockstep),故 tab 左緣永遠對齊兄弟內容左緣。
+
+**TabsContent 與 TabsList 間距(2026-06-12 user 拍板)**:`--layout-space-tight`(md 12px,density 連動),**內建於 TabsContent**(`mt-[var(--layout-space-tight)]`,className 可覆寫;full-height 佈局用 `mt-0`)。依 `layoutSpace.spec`「親疏 3 級」第一級(同 bundle,元件 spec own)+ 規則 3「直接功能依賴 = tight」精神;**不**取 Ant 的固定 16px(M23 自家 token 優先)。內容本身的排版歸 item-anatomy / 各內容元件管,本條只管 list↔content gap。
+
+> ⚠️ **此預設只在 TabsContent 緊接 tab bar 當直接 sibling 時成立**(standalone 頁面 tabs、ChromeHeader-as-sibling)。當 `tabsSlot` composition 把 tab bar 抬進 chrome header、TabsContent 留在 `DialogBody`/`SheetBody`/`SurfaceBody`(chrome scroll body,已自帶 `pt-/py-[var(--layout-space-tight)]`)內時,body 已擁有 header→content gap,TabsContent 的預設 `mt-tight` 會**雙重疊加**(md 24 / lg 32)。此時 TabsContent **必 `className="mt-0"`** 把 ownership 轉移給 body — 詳見下方「出現在 Dialog」段。一軸單一 spacing owner,per `item-anatomy.spec.md`「垂直 padding 歸屬 / 禁雙重 padding」。Hook `check_tabs_content_chrome_body_double_gap.sh` 機械強制。
+
 ---
 
 ## Underline 與 TabsList border 的視覺關係
 
-TabsList 底部有 1px gray border（`border-divider`，neutral-4），selected trigger 有 2px primary-hover 底線。**這兩條線視覺上必須是同一條**——selected 底線從 TabsList 的 gray border 位置「長出來」，不得出現雙線。
+TabsList 底部有 1px gray border（`border-divider`，neutral-4），selected trigger 有 2px primary 底線。**這兩條線視覺上必須是同一條**——selected 底線從 TabsList 的 gray border 位置「長出來」，不得出現雙線。
 
 **原則**：selected 底線必須覆蓋並延伸 TabsList 的 gray border，避免疊線。實作手法（pseudo-element 定位）見 `.tsx`。
 
-**色 token = `--divider`(neutral-4)而非 `--border`(neutral-5)**(2026-05-18 改 per user verbatim「我認為應該把 tabs 的下底線統一改成是 divider 色吧?」+「做」approval):
-- 跟 Dialog / Sheet / Popover / Sidebar header `border-b border-divider` 同色 — chrome separator 一致
-- withTabs scenario 下 tabs underline = chrome separator,色不同會視覺斷裂
-- Selected trigger 2px primary indicator overlay underlying 1px divider 對比仍清楚(primary 比 neutral-4 強得多)
-- 對齊 `color.spec.md:706-708` outer-vs-divider 判準的「T-junction seamless」直覺(tabs underline 跟 header separator T 字交接)
-
-在 Dialog / Sidebar header 內特別重要——header 的 `border-b` 和 Tabs 的 `border-b` 必須感知為同一條水平線。
+**色 token = `--divider`(neutral-4)而非 `--border`(neutral-5)**(2026-05-18 改 per user verbatim「我認為應該把 tabs 的下底線統一改成是 divider 色吧?」+「做」approval):跟 Dialog / Sheet / Popover / Sidebar header `border-b border-divider` 同色——chrome separator 一致,withTabs scenario 下 underline = chrome separator,色不同會視覺斷裂;selected trigger 2px primary indicator overlay 1px divider 對比仍清楚;對齊 `color.spec.md`「T-junction connectivity 原則」(tabs underline 跟 header separator T 字交接)。在 Dialog / Sidebar header 內特別重要——header 的 `border-b` 和 Tabs 的 `border-b` 必須感知為同一條水平線。
 
 ---
 
@@ -203,43 +196,28 @@ TabsList 底部有 1px gray border（`border-divider`，neutral-4），selected
 
 Tabs 常與容器 header 的底邊 border 合併——**視覺上只有一條線**,不是 header border + tabs border 疊兩條。
 
-**做法**:Tabs 的 `TabsList` 底部 border 與 header 的 `border-b` 實際上是**同一條線**(設計上重疊、實作上不重複渲染)。**Header 退讓**(移除自己 `border-b`),**Tabs 接管**(自身 `border-b border-divider` per `TABS_LIST_BASE`,2026-05-18 fd843c25 統一 chrome separator 色)。none overflow mode → TabsList block-level full-width 延展;scroll / menu overflow mode → TabsList `inline-flex w-fit`(2026-05-19 c359c711 border owner 升 list 內部 + `overflow-y-hidden` 阻 y auto-promote)。
+**做法**:Tabs 的 `TabsList` 底部 border 與 header 的 `border-b` 實際上是**同一條線**(設計上重疊、實作上不重複渲染)。**Header 退讓**(移除自己 `border-b`),**Tabs 接管**(自身 `border-b border-divider` per `TABS_LIST_BASE`,2026-05-18 fd843c25 統一 chrome separator 色)。三種 overflow mode 的 TabsList 一律跨滿父容器(none 模式 `w-full`;scroll / menu 模式 inner list `min-w-full` 保留溢出成長,見「寬度行為」段;`TABS_LIST_BASE` + `overflow-y-hidden` 阻 y auto-promote,2026-05-19 c359c711 border owner 升 list 內部);chrome header 內的 W2 px-loose inset 由 `ChromeHeader` tabsSlot wrapper 以 `[&_[data-slot=tabs-list]]:px-[var(--layout-space-loose)]` 注入(attribute contract:TabsList 三種 overflow 模式皆自標 `data-slot="tabs-list"`,2026-07-30 v4;全寬 paint 由 TabsList 自帶 w-full / min-w-full,wrapper 不注入寬度,見 `header-canonical.spec.md` W2 v4)。
 
-**世界級對照(verbatim cite)**:
-- **GitHub Primer PageHeader**:「`hasBorder` defaults true,**but border NOT rendered if Navigation child contains UnderlineNav**;UnderlineNav itself provides bottom border」(`primer.style/components/page-header/react`)
-- **Ant Design Tabs**:line type 自帶 bottom border(`ant.design/components/tabs`)
-- **Mantine Tabs**:default variant 自包 bottom border(`mantine.dev/core/tabs/`)
-- **Counter-pattern(reject)**:Material UI 走「container 畫 border + tabs 不畫」(`<Box sx={{ borderBottom: 1 }}><Tabs>...</Tabs></Box>` 從 `mui.com/material-ui/react-tabs/`)— 本 DS reject,理由:tabs underline 需 1px gray base line(`tabs.spec.md:185-187`),tabs 不畫 border 會讓 2px primary indicator 浮空失去 base
+**世界級對照**:GitHub Primer、Ant Tabs 與 Mantine Tabs 都讓 tabs family 擁有自身 separator；Material UI 的替代模式由 parent 擁有 separator。此 DS 採前者，因為 separator 與 active indicator 是同一個 TabsList 狀態邊界；`ChromeHeader` 因此在含 Tabs 時讓出該邊界，避免雙 owner。外部對照只作輔證，內部 authority 見 `header-canonical.spec.md` W1。
 
 **Auto-suppress 機制(Phase 2 production code 提案)**:header primitive 加 `withTabs?: boolean` prop → true 時自動移除自身 `border-b`,免 consumer 手動忘記。對齊 GitHub Primer 的 auto-suppress 模式(免 consumer 手動 prop)。完整 cross-header canonical 詳 `patterns/header-canonical/header-canonical.spec.md` W1。
 
 Size 建議:overlay / chrome header 內用 `sm`(32/40)— 對應 close X 也是 sm,視覺一致;**獨立取代 chrome header** 的 page-level workspace tabs 用 `lg`(48/56,= chrome-header-height)。
 
+**間距 ownership**:tabsSlot 模式下 `TabsContent` 放 `DialogBody`/`SheetBody`/`SurfaceBody`(自帶 `pt-/py-tight`)內時**必 `className="mt-0"`** — body 已擁有 header→content gap,TabsContent 預設 `mt-tight` 會雙重(md 24 / lg 32,2026-07-01 user 抓)。詳「TabsContent 與 TabsList 間距」段;hook `check_tabs_content_chrome_body_double_gap.sh` 強制。
+
 ---
 
 ## 狀態
 
-### active
-
-選中的 trigger：
-- 文字色 `text-foreground`、`font-medium`
-- 底部 2px 底線 `bg-primary-hover`（對齊 semantic.css：選中狀態的邊框/文字統一用 `--primary-hover`）
-
-未選的 trigger：
-- 文字色 `text-fg-secondary`、一般 weight
-- 無底線
-- hover 時文字色轉 `text-foreground`
+DS 詞彙 **selected**（持續選中）；Radix DOM attr 為 `data-state="active"`（primitive 命名，不改寫）。
 
-### disabled
-
-- 文字色 `text-fg-disabled`
-- 無 hover 色變化、無底線
-- Cursor 變為 `not-allowed`（滑鼠移過明確告知不可點）
-- 不接受鍵盤 focus
-
-### focus-visible
-
-`ring-2 ring-ring ring-offset-1`，與 Button 一致。鍵盤導覽（Radix Tabs 原生支援左右箭頭）由 Radix 處理。
+| State | 視覺 |
+|---|---|
+| selected | `text-foreground` + `font-medium` + 底部 2px `bg-primary` 底線（semantic.css 選中規則；2026-07-06 拍板持續選中站 base，Ant inkBarColor = colorPrimary 同款）|
+| 未選 | `text-fg-secondary` + `font-medium`（與 selected 同 weight，差異僅文字色 + 有無底線，非 weight）、無底線；hover 時文字色轉 `text-foreground` |
+| disabled | `text-fg-disabled`；無 hover 色變化、無底線；`cursor-not-allowed`；不接受鍵盤 focus |
+| focus-visible | `ring-2 ring-ring ring-offset-1`，與 Button 一致；鍵盤導覽（左右箭頭）由 Radix 原生處理 |
 
 ---
 
@@ -254,6 +232,8 @@ Size 建議:overlay / chrome header 內用 `sm`(32/40)— 對應 close X 也是
 - **Empty(no tabs)**:單 tab 已禁用(見「禁止事項」),0 tab 同理 — consumer 應條件性不渲 `<Tabs>`,不渲空 TabsList。
 - **Empty content panel**:tab 切到沒內容的 view 時,content panel 應渲 `<Empty>` 引導 user(對齊 empty 元件的 page-empty pattern)— 由 consumer 決定,Tabs primitive 不獨立處理。
 - **Disabled tab 鍵盤行為**:Radix Tabs 自動 skip disabled tab(`←/→` 不停留),focus 跳到下一個可用 tab。
+- **極長 label**:trigger `whitespace-nowrap` 不換行、不 truncate(hug content);整列放不下屬 TabsList 溢出問題,走「Overflow 模式」(scroll / menu),非單 trigger 截斷。
+- **RTL**:不支援；全域 LTR-only compatibility contract 見 `packages/design-system/README.md#compatibility-matrix`。scroll edge / arrow 的 LTR 實作細節不另立 owner。
 - **Dark mode / density**:走 chrome-header / Field 對應 token 自動 adapt;`size` × `variant` matrix 已在 anatomy 完整呈現,density 由 size prop 表達不獨立 own 維度。
 
 ---
@@ -264,7 +244,7 @@ Size 建議:overlay / chrome header 內用 `sm`(32/40)— 對應 close X 也是
 - ❌ 不得用 Tabs 做表單單選（選 view ≠ 選 value）——改用 SegmentedControl
 - ❌ 不得用 Tabs 做頁面層級導覽（切路由）——改用 navigation
 - ❌ Trigger `startIcon` 不得超過一個
-- ❌ **同一組 Tabs 內 `startIcon` 全有或全無**(2026-05-18 加 per user 抓「圖一 tabs 圖示混用」)——禁止「總覽無 icon / 成員 + 通知 + 設定 有 icon」這種視覺重心散亂的混用。對齊 Material UI Tabs「Tab labels may be either all icons or all text」+ Carbon「Do not mix dismissible tabs without icons with dismissible tabs with icons」。Scope **限縮 `startIcon`** — `endIcon`(badge / chevron-down 等狀態 indicator)可獨立判斷,因屬狀態 affordance 非語意 label icon <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- ❌ **同一組 Tabs 內 `startIcon` 全有或全無**(2026-05-18 加 per user 抓「圖一 tabs 圖示混用」)——禁止「總覽無 icon / 成員 + 通知 + 設定 有 icon」這種視覺重心散亂的混用。Scope **限縮 `startIcon`** — `endIcon`(badge / chevron-down 等狀態 indicator)可獨立判斷,因屬狀態 affordance 非語意 label icon
 - ❌ `endIcon` 不得放動詞性 icon（Download、Trash2）——tab 是視圖切換，不是觸發動作
 - ❌ Dialog / Sidebar header 內不得同時有 header `border-b` 和 TabsList `border-b`——會出現雙線
 - ❌ 不得把 trigger 改成等分 / fullWidth——等寬互斥切換是 SegmentedControl 的身份特徵，Tabs 是 navigation anchor，兩者不同層級。需要等寬改用 SegmentedControl
@@ -273,13 +253,16 @@ Size 建議:overlay / chrome header 內用 `sm`(32/40)— 對應 close X 也是
 
 ---
 
-## 為何無 Inspector
-
-Tabs 決策維度是 `size` × `variant` × overflow 模式 × 寬度行為——已由 `SizeMatrix` / `ColorMatrix` / `StateBehavior`(selected / hover / disabled) / 元件特有 `OverflowMatrix`(scroll / menu / fade 三模式) / `SpacingTokens` 五張結構 story 完整覆蓋。
+## Anatomy story 結構
 
-互動 Inspector 切單一 tab 不如 `OverflowMatrix` 的三種 overflow 模式 side-by-side 比較有效——「tabs 放不下時怎麼處理」是設計決策題,需要同時看三個方案。同樣 `SizeMatrix` / `StateBehavior` 是結構性對照,單 tab 互動無法呈現 underline / selected border 與 TabsList border 的視覺關係(見「Underline 與 TabsList border 的視覺關係」段)。
+Tabs anatomy 採 DS 標準結構 + 元件特有矩陣:
 
-對應 anatomy story:保留 `Overview` + `SizeMatrix` + `ColorMatrix` + `StateBehavior` + 元件特有 `OverflowMatrix` + `SpacingTokens`。
+- `Overview` —— 預設視覺概覽
+- `Inspector`(`元件檢閱器`)—— 互動式 prop 試玩(`size` × `overflow` × `value` 即時切換),對齊全部同類元件「單組合即時試玩 prop」的 DS 慣例
+- 標準 `SizeMatrix` / `ColorMatrix` / `StateBehavior`(selected / hover / disabled)—— 結構性對照,呈現 underline / selected border 與 TabsList border 的視覺關係(見「Underline 與 TabsList border 的視覺關係」段),單組合 Inspector 無法並列呈現
+- 元件特有 `OverflowMatrix`(scroll / menu / fade 三模式)—— 「tabs 放不下時怎麼處理」是設計決策題,需三方案 side-by-side 同時比較,Inspector 單組合無法呈現
+- `SpacingTokens` —— 間距 token 對照
+- `Accessibility`(`無障礙`)—— Radix tabs a11y 預設摘要 + Keyboard 行為對照(詳「A11y 預設」段)
 
 ---
 
@@ -301,14 +284,20 @@ Tabs 決策維度是 `size` × `variant` × overflow 模式 × 寬度行為—
 - Home/End — 第一 / 最後 tab
 - Enter / Space — activate
 
-**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+**Focus**:Tabs 為內嵌導覽,不困住焦點(無 focus trap);Radix `tabs` primitive 以 roving tabindex 管理 tab 之間的鍵盤移動(整組 tabs 為單一 tab stop)。選中 tab 與 TabsContent 各有 focus-visible 焦點框(`ring-2 ring-ring` per design-system focus-visible canonical)。
 
-**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+**驗證**:Tabs 元件**自身結構** axe 0 critical(nested-interactive + aria-required-children 皆已修,2026-07-18 實測 `.claude/logs/a11y-audit.json`);逐一 activate 每個 trigger 後,其 `aria-controls` 必解析到同 value 的已掛載 `TabsContent` panel;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+**非-Tabs-結構例外**:story 內 demo 內容的 color-contrast / DataTable 巢狀(appshell story)非 Tabs 元件 own,屬各自 owner;trigger ↔ panel 的 IDREF 完整性則是 Tabs composition contract,不得列為外部例外。
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `accordion.spec.md`
+- `button.spec.md`
 - `carousel.spec.md`
+- `header-canonical.spec.md`
+- `horizontal-overflow.spec.md`
+- `segmented-control.spec.md`
 - `sidebar.spec.md`
 - `steps.spec.md`