@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.81

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

@@ -0,0 +1,243 @@
+// @story-baseline: packages/design-system/src/components/DataTable/data-table.stories.tsx#NumberAlignment
+import type { Meta, StoryObj } from '@storybook/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
+
+// ── Data ──────────────────────────────────────────────────────────────────────
+
+// Linear-style issue list
+const LINEAR_ISSUES: Array<{ id: string; title: string; status: string; assignee: string }> = [
+  { id: 'ENG-1204', title: 'DataTable 水平捲動在 Windows 跑版 17px', status: 'In Progress', assignee: 'Alice Chen' },
+  { id: 'ENG-1203', title: 'Sheet body 長內容捲動時標題浮動行為不一致', status: 'In Review', assignee: 'Bob Liu' },
+  { id: 'DES-872', title: 'Sidebar 深色模式 hover 色與 active 色太接近', status: 'Todo', assignee: 'Carol Wang' },
+  { id: 'ENG-1199', title: 'PeoplePicker 選中多人後換行邏輯錯誤', status: 'In Progress', assignee: 'David Kuo' },
+  { id: 'ENG-1198', title: 'Combobox 鍵盤 arrow 導覽跳過 disabled option', status: 'Done', assignee: 'Eve Lin' },
+  { id: 'DES-870', title: 'Toast 在 dark mode 與 Dialog 疊層時色階不夠', status: 'Todo', assignee: 'Frank Ho' },
+  { id: 'ENG-1195', title: 'DatePicker 時區 UTC+0 下一日顯示錯誤', status: 'Backlog', assignee: 'Grace Tsai' },
+  { id: 'ENG-1192', title: 'Tabs 在小螢幕水平溢出時箭頭 hit area 太窄', status: 'In Progress', assignee: 'Henry Wu' },
+  { id: 'DES-865', title: 'Typography scale 在 1.2x 密度下 body-lg 與 h3 過近', status: 'In Review', assignee: 'Ivy Chang' },
+  { id: 'ENG-1188', title: 'Tooltip delay 全站預設值從 0ms 調回 300ms', status: 'Done', assignee: 'Jack Lee' },
+  { id: 'ENG-1185', title: 'DropdownMenu nested submenu 在 RTL 定位錯誤', status: 'Todo', assignee: 'Kate Lin' },
+  { id: 'ENG-1183', title: 'Slider 拖曳時 thumb 偏移半個像素(視覺毛邊)', status: 'In Progress', assignee: 'Leo Hsu' },
+]
+
+// Notion-style sidebar nav
+const NOTION_NAV = [
+  { section: 'Private', items: ['Getting Started', 'Daily journal', 'Reading list', 'Recipes', 'Weekend projects', 'Japan 2026 trip'] },
+  { section: 'Workspace', items: ['Engineering wiki', 'Design system spec', 'Meeting notes', 'Roadmap Q2', 'Incident retrospectives', 'Onboarding docs'] },
+  { section: 'Shared', items: ['Product handbook', 'Brand guidelines', 'Customer interviews', 'Competitive analysis', 'Press & media kit'] },
+]
+
+// Stripe-style wide product table (triggers horizontal scroll)
+const STRIPE_PRODUCTS: Array<{ sku: string; name: string; category: string; stock: number; price: string; margin: string; channel: string; status: string }> = [
+  { 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' },
+]
+
+const STATUS_COLORS: Record<string, string> = {
+  'In Progress': 'var(--info)',
+  'In Review':   'var(--warning)',
+  'Todo':        'var(--fg-muted)',
+  'Done':        'var(--success)',
+  'Backlog':     'var(--fg-muted)',
+  'Active':      'var(--success)',
+  'Beta':        'var(--info)',
+}
+
+// ── DataTable columns ─────────────────────────────────────────────────────────
+// 消費真 <DataTable>(per data-table.spec.md「簡單展示場景也用 DataTable,不另外維護靜態 Table」)。
+// ScrollArea 包 height="auto" DataTable = scroll-area.spec.md「Orientation」段 canonical 組合:
+// 捲動完全由 ScrollArea own(DataTable 無高度約束 + min-w-max 不啟內部捲軸)。
+
+type StripeProduct = (typeof STRIPE_PRODUCTS)[number]
+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: { width: 110 },
+    cell: (info) => (
+      <span className="inline-flex items-center gap-1.5">
+        <span className="w-1.5 h-1.5 rounded-full" style={{ backgroundColor: STATUS_COLORS[info.getValue()] }} />
+        {info.getValue()}
+      </span>
+    ),
+  }),
+]
+
+interface PullRequest {
+  id: string
+  title: string
+  author: string
+  reviewer: string
+  base: string
+  compare: string
+  checks: string
+  additions: number
+  deletions: number
+}
+
+const PR_TITLES = [
+  'feat: ScrollArea overlay scrollbar for cross-OS consistency',
+  'fix: DataTable pinned column shadow on horizontal scroll',
+  'refactor: extract drag-visual SSOT for row + column reorder',
+  'docs: clarify density vs size boundary in tokens README',
+  'fix: Sheet body scroll chain forwards flex-col h-full',
+  'feat: Combobox keyboard navigation skips disabled options',
+]
+
+const PR_AUTHORS = ['@alice-chen', '@bob-liu', '@carol-wang', '@david-kuo', '@eve-lin', '@frank-ho']
+
+const PULL_REQUESTS: PullRequest[] = Array.from({ length: 18 }, (_, i) => ({
+  id: `#${4210 - i}`,
+  title: PR_TITLES[i % PR_TITLES.length],
+  author: PR_AUTHORS[i % PR_AUTHORS.length],
+  reviewer: `${PR_AUTHORS[(i + 1) % PR_AUTHORS.length]}, ${PR_AUTHORS[(i + 2) % PR_AUTHORS.length]}`,
+  base: 'main',
+  compare: 'feat/scroll-area',
+  checks: '12 / 12 passing',
+  additions: 128 + i * 7,
+  deletions: 24 + i * 3,
+}))
+
+const prCol = createColumnHelper<PullRequest>()
+
+const PR_COLUMNS = [
+  prCol.accessor('id', { header: '#', meta: { type: 'string', width: 90 } }),
+  prCol.accessor('title', { header: 'Title', meta: { type: 'string', width: 360 } }),
+  prCol.accessor('author', { header: 'Author', meta: { type: 'string', width: 130 } }),
+  prCol.accessor('reviewer', { header: 'Reviewer', meta: { type: 'string', width: 190 } }),
+  prCol.accessor('base', { header: 'Base', meta: { type: 'string', width: 90 } }),
+  prCol.accessor('compare', { header: 'Compare', meta: { type: 'string', width: 150 } }),
+  prCol.accessor('checks', {
+    header: 'Checks',
+    meta: { width: 140 },
+    cell: (info) => (
+      <span className="inline-flex items-center gap-1.5">
+        <span className="w-1.5 h-1.5 rounded-full bg-[var(--success)]" />
+        {info.getValue()}
+      </span>
+    ),
+  }),
+  prCol.accessor('additions', {
+    header: 'Additions',
+    meta: { width: 110, align: 'right' },
+    cell: (info) => <span className="text-success">+{info.getValue()}</span>,
+  }),
+  prCol.accessor('deletions', {
+    header: 'Deletions',
+    meta: { width: 110, align: 'right' },
+    cell: (info) => <span className="text-error">-{info.getValue()}</span>,
+  }),
+]
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const VerticalIssueList: Story = {
+  name: '垂直捲動 — Linear 議題清單',
+  render: () => (
+    <div className="max-w-xl">
+      <p className="text-caption text-fg-muted mb-3">
+        長 issue 清單(12 筆),容器固定 320px 高。macOS / Windows 呈現一致,不吃寬度。
+      </p>
+      <ScrollArea className="h-[320px] border border-border rounded-lg">
+        <div className="p-2">
+          {LINEAR_ISSUES.map((issue) => (
+            <div key={issue.id} className="flex items-center gap-3 px-3 py-2 rounded-md hover:bg-neutral-hover cursor-pointer">
+              <span className="text-caption font-mono text-fg-muted shrink-0 w-20">{issue.id}</span>
+              <span className="text-body flex-1 truncate">{issue.title}</span>
+              <span className="inline-flex items-center gap-1.5 text-footnote shrink-0">
+                <span className="w-1.5 h-1.5 rounded-full" style={{ backgroundColor: STATUS_COLORS[issue.status] }} />
+                <span className="text-fg-secondary">{issue.status}</span>
+              </span>
+            </div>
+          ))}
+        </div>
+      </ScrollArea>
+    </div>
+  ),
+}
+
+export const SidebarNav: Story = {
+  name: '垂直捲動 — Notion 側欄 導覽',
+  render: () => (
+    <div className="w-[260px]">
+      <p className="text-caption text-fg-muted mb-3">
+        Sidebar 導覽區,多個群組項目超過可見高度。
+      </p>
+      <ScrollArea className="h-[400px] border border-border rounded-lg bg-canvas">
+        <div className="p-3">
+          {NOTION_NAV.map((group) => (
+            <div key={group.section} className="mb-4">
+              <div className="px-2 py-1 text-footnote text-fg-muted font-medium">{group.section}</div>
+              {group.items.map((item) => (
+                <div key={item} className="px-2 py-1.5 rounded-md text-body hover:bg-neutral-hover cursor-pointer truncate">
+                  {item}
+                </div>
+              ))}
+            </div>
+          ))}
+        </div>
+      </ScrollArea>
+    </div>
+  ),
+}
+
+export const HorizontalProductTable: Story = {
+  name: '水平捲動 — Stripe 寬欄位商品表',
+  render: () => (
+    <div className="max-w-[640px]">
+      <p className="text-caption text-fg-muted mb-3">
+        8 欄商品表(SKU / Name / Category / Stock / Price / Margin / Channel / Status)欄寬總和超出
+        640px 容器 → 用 <code className="font-mono text-footnote bg-muted px-1 rounded">orientation=&quot;horizontal&quot;</code> scrollbar。
+        比 native 的優勢:Windows 不吃 17px,右邊 Status 欄不被裁切。
+        表格本體消費真 DataTable(height=&quot;auto&quot; 無高度約束,捲動由 ScrollArea own)。
+      </p>
+      <ScrollArea className="border border-border rounded-lg">
+        <div className="min-w-max">
+          <DataTable columns={PRODUCT_COLUMNS} data={STRIPE_PRODUCTS} getRowId={(p) => p.sku} height="auto" bordered={false} />
+        </div>
+        <ScrollBar orientation="horizontal" />
+      </ScrollArea>
+    </div>
+  ),
+}
+
+export const BothDirections: Story = {
+  name: '雙向捲動 — GitHub PR 大型檢閱表',
+  render: () => (
+    <div className="max-w-[560px]">
+      <p className="text-caption text-fg-muted mb-3">
+        容器 560×280px、內容寬 &gt; 560、高 &gt; 280,同時渲染 vertical + horizontal scrollbar
+        (wrapper 已內建 vertical,consumer 只需再渲染一個 horizontal,見 scroll-area.spec.md「Orientation」)。
+        表格本體消費真 DataTable(height=&quot;auto&quot;,雙向捲動完全由 ScrollArea own)。
+      </p>
+      <ScrollArea className="h-[280px] border border-border rounded-lg">
+        <div className="min-w-max">
+          <DataTable columns={PR_COLUMNS} data={PULL_REQUESTS} getRowId={(pr) => pr.id} height="auto" bordered={false} />
+        </div>
+        <ScrollBar orientation="horizontal" />
+      </ScrollArea>
+    </div>
+  ),
+}

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

@@ -51,7 +51,7 @@ const ScrollArea = React.forwardRef<
         visible:outline 用 DS focus ring,不破壞視覺。 */}
     <ScrollAreaPrimitive.Viewport
       tabIndex={0}
-      className="flex-1 min-h-0 w-full rounded-[inherit] focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-primary"
+      className="flex-1 min-h-0 w-full rounded-[inherit] focus-visible:outline-2 focus-visible:outline-offset-[-2px] focus-visible:outline-ring"
     >
       {children}
     </ScrollAreaPrimitive.Viewport>
@@ -92,14 +92,14 @@ ScrollBar.displayName = ScrollAreaPrimitive.ScrollAreaScrollbar.displayName
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const scrollAreaMeta = {
   component: 'ScrollArea',
-  family: null, // non-family composite / overlay / layout
+  family: 'self-contained', // 對齊 scroll-area.spec.md frontmatter(SSOT;同 Separator/OverflowIndicator meta 寫法)
   variants: {
 
   },
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['default'],
   tokens: {
     bg: [],
     fg: [],

package/src/components/SegmentedControl/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './segmented-control'

package/src/components/SegmentedControl/segmented-control.anatomy.stories.tsx

@@ -0,0 +1,295 @@
+// @anatomy-rationale:
+//   ColorMatrix represented as StateBehavior「視覺狀態對照」段 — SegmentedControl
+//     不分 variant 色彩(全 DS 統一 surface / fg-secondary unselected,primary
+//     selected),色彩變化僅由 state 驅動。State 色彩矩陣(unselected / hover /
+//     selected / disabled × bg / text / border / z-index)已由 StateBehavior(5.)
+//     完整對照,獨立 ColorMatrix 會與 StateBehavior 重複。
+import * as React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { AlignLeft, AlignCenter, AlignRight, List, LayoutGrid, Calendar } from 'lucide-react'
+import { SegmentedControl, SegmentedControlItem } from './segmented-control'
+import { Badge } from '@/design-system/components/Badge/badge'
+import { H3, Desc, Td, Th, TokenCell } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+const meta: Meta<React.ComponentProps<typeof SegmentedControl> & { iconOnly?: boolean }> = {
+  title: 'Design System/Components/SegmentedControl/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>SegmentedControl(role="group")+ N 個 Item(role="radio",N = 2-5)。Items 連體展示,基於 Radix ToggleGroup(type="single")。內部結構 mirror Button(gap-1、label px-1、badge gap-1)。</Desc>
+        <div className="border border-border rounded-lg p-4 max-w-md">
+          <SegmentedControl defaultValue="week">
+            <SegmentedControlItem value="day">日</SegmentedControlItem>
+            <SegmentedControlItem value="week">週</SegmentedControlItem>
+            <SegmentedControlItem value="month">月</SegmentedControlItem>
+          </SegmentedControl>
+        </div>
+        <p className="text-footnote text-fg-muted mt-3">Items 之間 `-ml-px`(除第一個)讓相鄰 border 重疊成單一視覺線;第一個 `rounded-l-md`,最後一個 `rounded-r-md`,中間 `rounded-none`</p>
+      </div>
+
+      <div>
+        <H3>Item 內部結構</H3>
+        <Desc>[startIcon?] [label span px-1] [suffix gap-1:badge?]——跟 Button size sm/md/lg 的 `gap-1` 和 `px-1` label 完全對齊,視覺肌肉記憶直接複用。</Desc>
+        <div className="flex flex-col gap-3 border border-border rounded-lg p-4 max-w-md">
+          <SegmentedControl defaultValue="all">
+            <SegmentedControlItem value="all" badge={<Badge count={12} variant="low" />}>全部</SegmentedControlItem>
+            <SegmentedControlItem value="active" badge={<Badge count={3} variant="high" />}>進行中</SegmentedControlItem>
+            <SegmentedControlItem value="done">已完成</SegmentedControlItem>
+          </SegmentedControl>
+        </div>
+      </div>
+
+      <div>
+        <H3>Props 速查</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
+            <tbody>
+              {[
+                ['SegmentedControl', '', '', ''],
+                ['  value / defaultValue', 'string', '必填', '當前 value(Radix ToggleGroup type="single"),必須落在可選 item 上'],
+                ['  onValueChange', '(value: string) => void', '—', '切換 callback'],
+                ['  size', "'xs' | 'sm' | 'md' | 'lg'", "'md'", '對齊 --field-height-*(跟 Button / Input 同,field-height family 共享 default md)'],
+                ['  fullWidth', 'boolean', 'false', 'hug content(false)vs 撐滿父容器並等分(true)'],
+                ['  iconOnly', 'boolean', 'false', 'group-level:全部 icon-only(必須整組一致,不可混搭)'],
+                ['  disabled', 'boolean', 'false', '整個 SegmentedControl 停用'],
+                ['SegmentedControlItem', '', '', ''],
+                ['  value', 'string', '必填', '唯一識別碼'],
+                ['  startIcon', 'LucideIcon', '—', 'label 左側 icon'],
+                ['  badge', 'ReactNode', '—', 'label 右側 badge(計數指示器,如「全部 12」)'],
+                ['  aria-label', 'string', '(iconOnly 必填)', 'iconOnly 時必填(dev-mode runtime warn,非 TS 強制),自動渲染 tooltip'],
+                ['  disabled', 'boolean', 'false', '單獨 item 停用(不得是當前 value)'],
+              ].map(([p, t, d, desc]) => (
+                <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const Inspector: Story = {
+  name: '元件檢閱器',
+  parameters: {
+    docs: { description: { story: '右側 Controls 切 SegmentedControl props 即時 render,取代 Figma inspect。改 `value` 看選中狀態、切 `size` 對照 field-height tier、切 `fullWidth` 看 hug vs 等分。' } },
+  },
+  args: {
+    size: 'md',
+    value: 'week',
+    fullWidth: false,
+    iconOnly: false,
+    disabled: false,
+  },
+  argTypes: {
+    size: { control: 'radio', options: ['xs', 'sm', 'md', 'lg'] },
+    value: {
+      control: 'radio',
+      options: ['day', 'week', 'month'],
+      description: '當前選中的 item value',
+    },
+    fullWidth: { control: 'boolean', description: 'false=hug content / true=撐滿父容器等分' },
+    iconOnly: { control: 'boolean', description: 'group-level:全部 icon-only(必須整組一致)' },
+    disabled: { control: 'boolean' },
+  },
+  render: (args) => (
+    <div className="max-w-md">
+      <SegmentedControl {...args}>
+        {args.iconOnly ? (
+          <>
+            <SegmentedControlItem value="day" startIcon={AlignLeft} aria-label="日" />
+            <SegmentedControlItem value="week" startIcon={AlignCenter} aria-label="週" />
+            <SegmentedControlItem value="month" startIcon={AlignRight} aria-label="月" />
+          </>
+        ) : (
+          <>
+            <SegmentedControlItem value="day">日</SegmentedControlItem>
+            <SegmentedControlItem value="week">週</SegmentedControlItem>
+            <SegmentedControlItem value="month">月</SegmentedControlItem>
+          </>
+        )}
+      </SegmentedControl>
+    </div>
+  ),
+}
+
+export const SizeMatrix: Story = {
+  name: '尺寸對照表',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>四種 Size — 對齊 field-height / button 系統</H3>
+        <div className="overflow-x-auto mb-4">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Size</Th><Th>Token</Th><Th>Padding</Th><Th>字體</Th><Th>Icon</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>xs</Td><Td mono>--field-height-xs(固定)</Td><Td mono>px-2</Td><Td>text-caption</Td><Td mono>16</Td></tr>
+              <tr><Td mono>sm</Td><Td mono>--field-height-sm</Td><Td mono>px-3</Td><Td>text-body</Td><Td mono>16</Td></tr>
+              <tr><Td mono>md ★default</Td><Td mono>--field-height-md</Td><Td mono>px-3</Td><Td>text-body</Td><Td mono>16</Td></tr>
+              <tr><Td mono>lg</Td><Td mono>--field-height-lg</Td><Td mono>px-3</Td><Td>text-body-lg</Td><Td mono>20</Td></tr>
+            </tbody>
+          </table>
+        </div>
+        <div className="flex flex-col gap-4">
+          {(['xs', 'sm', 'md', 'lg'] as const).map(size => (
+            <div key={size} className="flex items-center gap-4">
+              <span className="text-caption text-fg-muted font-mono w-14">{size}</span>
+              <SegmentedControl size={size} defaultValue="a">
+                <SegmentedControlItem value="a">日</SegmentedControlItem>
+                <SegmentedControlItem value="b">週</SegmentedControlItem>
+                <SegmentedControlItem value="c">月</SegmentedControlItem>
+              </SegmentedControl>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const StateBehavior: Story = {
+  name: '狀態行為',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>視覺狀態對照</H3>
+        <div className="overflow-x-auto mb-4">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>State</Th><Th>Bg</Th><Th>Text</Th><Th>Border</Th><Th>Z-index</Th></tr></thead>
+            <tbody>
+              <tr><Td>Unselected</Td><Td><TokenCell token="--surface" display="bg-surface" /></Td><Td><TokenCell token="--fg-secondary" display="text-fg-secondary" /></Td><Td><TokenCell token="--border" display="border-border" /></Td><Td>—</Td></tr>
+              <tr><Td>Hover unselected</Td><Td><TokenCell token="--surface" display="bg-surface(不變)" /></Td><Td><TokenCell token="--foreground" display="text-foreground" /></Td><Td><TokenCell token="--border-hover" display="border-border-hover" /></Td><Td mono>z-[5](hover 邊框浮上)</Td></tr>
+              <tr><Td>Selected</Td><Td><TokenCell token="--surface" display="bg-surface" /></Td><Td><TokenCell token="--primary-hover" display="text-primary-hover" /></Td><Td><TokenCell token="--primary-hover" display="border-primary-hover" /></Td><Td mono>z-10(浮在相鄰 item border 上)</Td></tr>
+              <tr><Td>Disabled</Td><Td>bg-surface(不變)</Td><Td>text-fg-disabled</Td><Td>border-border(不變,hover 鎖定)</Td><Td>—</Td></tr>
+            </tbody>
+          </table>
+        </div>
+        <div className="flex flex-col gap-4">
+          <div className="flex items-center gap-4">
+            <span className="text-caption text-fg-muted w-32">Normal(hover 測試)</span>
+            <SegmentedControl defaultValue="b">
+              <SegmentedControlItem value="a">日</SegmentedControlItem>
+              <SegmentedControlItem value="b">週</SegmentedControlItem>
+              <SegmentedControlItem value="c">月</SegmentedControlItem>
+            </SegmentedControl>
+          </div>
+          <div className="flex items-center gap-4">
+            <span className="text-caption text-fg-muted w-32">整組 disabled</span>
+            <SegmentedControl defaultValue="b" disabled>
+              <SegmentedControlItem value="a">日</SegmentedControlItem>
+              <SegmentedControlItem value="b">週</SegmentedControlItem>
+              <SegmentedControlItem value="c">月</SegmentedControlItem>
+            </SegmentedControl>
+          </div>
+          <div className="flex items-center gap-4">
+            <span className="text-caption text-fg-muted w-32">單獨 item disabled</span>
+            <SegmentedControl defaultValue="a">
+              <SegmentedControlItem value="a">日</SegmentedControlItem>
+              <SegmentedControlItem value="b">週</SegmentedControlItem>
+              <SegmentedControlItem value="c" disabled>月(beta)</SegmentedControlItem>
+            </SegmentedControl>
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <H3>Item 連體手法</H3>
+        <Desc>Items 之間 `-ml-px`(除第一個)讓相鄰 border 重疊、視覺上只有一條線。Selected item 的 `z-10` 讓它的 border 浮在相鄰 item 之上,避免被重疊 border 切掉。第一個 item `rounded-l-md`,最後一個 `rounded-r-md`,中間 `rounded-none`。</Desc>
+      </div>
+    </div>
+  ),
+}
+
+export const FullWidthMatrix: Story = {
+  name: 'fullWidth 行為',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>fullWidth = false(預設,hug content)</H3>
+        <Desc>寬度由 item 總寬決定,items 各自照內容寬度排列。Toolbar 場景 / 跟 Button 並排時使用。</Desc>
+        <div className="flex items-center gap-4 border border-dashed border-divider rounded-md p-4">
+          <SegmentedControl defaultValue="list">
+            <SegmentedControlItem value="list" startIcon={List} aria-label="清單" />
+            <SegmentedControlItem value="grid" startIcon={LayoutGrid} aria-label="格狀" />
+            <SegmentedControlItem value="calendar" startIcon={Calendar} aria-label="行事曆" />
+          </SegmentedControl>
+          <span className="text-caption text-fg-muted">← 寬度 hug content</span>
+        </div>
+      </div>
+
+      <div>
+        <H3>fullWidth = true(撐滿父容器 + 等分)</H3>
+        <Desc>所有 item 等分父容器寬度。小容器 / 狹窄上下文(mobile、Dialog、Sheet、Field row)使用。</Desc>
+        <div className="flex flex-col gap-3 max-w-md">
+          <div className="border border-dashed border-divider rounded-md p-4">
+            <SegmentedControl defaultValue="day" fullWidth>
+              <SegmentedControlItem value="day">日</SegmentedControlItem>
+              <SegmentedControlItem value="week">週</SegmentedControlItem>
+              <SegmentedControlItem value="month">月</SegmentedControlItem>
+            </SegmentedControl>
+          </div>
+          <div className="w-[280px] border border-dashed border-divider rounded-md p-4">
+            <SegmentedControl defaultValue="day" fullWidth>
+              <SegmentedControlItem value="day">日</SegmentedControlItem>
+              <SegmentedControlItem value="week">週</SegmentedControlItem>
+              <SegmentedControlItem value="month">月</SegmentedControlItem>
+            </SegmentedControl>
+            <span className="text-footnote text-fg-muted mt-2 block">↑ 固定 280px 容器:items 等分寬度</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const IconOnlyMatrix: Story = {
+  name: '純圖示（群組層）',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>iconOnly 是 group-level,不是 item-level</H3>
+        <Desc>**必須整組一致**:要嘛全部 icon-only,要嘛全部帶 label。混搭會讓使用者無法預測哪個 item 有 tooltip、哪個沒有,也破壞 segmented 的對稱感。iconOnly 時每個 item 變正方形(`aspect-square p-0`),必須設 aria-label(dev-mode runtime warn,非 TS 強制),自動渲染 tooltip。</Desc>
+        <div className="flex flex-col gap-4">
+          <div className="flex items-center gap-4">
+            <span className="text-caption text-fg-muted w-24">對齊選擇</span>
+            <SegmentedControl iconOnly defaultValue="left">
+              <SegmentedControlItem value="left" startIcon={AlignLeft} aria-label="靠左" />
+              <SegmentedControlItem value="center" startIcon={AlignCenter} aria-label="置中" />
+              <SegmentedControlItem value="right" startIcon={AlignRight} aria-label="靠右" />
+            </SegmentedControl>
+          </div>
+          <div className="flex items-center gap-4">
+            <span className="text-caption text-fg-muted w-24">檢視模式</span>
+            <SegmentedControl iconOnly defaultValue="list">
+              <SegmentedControlItem value="list" startIcon={List} aria-label="清單" />
+              <SegmentedControlItem value="grid" startIcon={LayoutGrid} aria-label="格狀" />
+              <SegmentedControlItem value="calendar" startIcon={Calendar} aria-label="行事曆" />
+            </SegmentedControl>
+          </div>
+        </div>
+        <p className="text-footnote text-error font-medium mt-3">❌ 禁止:iconOnly 和帶 label 的 item 混搭——必須全組一致</p>
+      </div>
+    </div>
+  ),
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙',
+  render: () => (
+    <div className="max-w-3xl text-body text-fg-secondary">
+      <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
+      <p className="whitespace-pre-line">{"  ARIA / Pattern  :繼承 Radix toggle-group primitive 的無障礙預設——整組 role=\"group\",每個 item role=\"radio\"(type=\"single\" 互斥選一),鍵盤導覽由 primitive 處理。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/toggle-group#accessibility)。\n\n  Keyboard 行為  :\n\n- Tab — 進入整組(只有一個 tab 停留點,落在選中項;沒選就落在上次 focus 過的 item,初次進入才是第一項)\n- ←/→ — 在 item 之間移動 roving focus(只移焦點,不切換選取)。WAI-ARIA APG 對水平 segmented/radio group 的主要導覽鍵\n- ↑/↓ — 同 ←/→,也會在 item 間移動 roving focus。Radix toggle-group 未鎖 orientation(沿用 default 雙軸 roving),APG 接受 group 同時支援兩軸方向鍵\n- Enter / Space — 選取目前 focus 的 item\n\n  Focus  :採 roving tabindex——整組共用一個 tab 停留點,方向鍵在 item 間移動焦點(選取仍需 Enter/Space/click);不是 Dialog 那種把焦點關在裡面的 focus trap。Focus ring 對齊 Button:focus-visible:ring-2 ring-ring ring-offset-1(box-shadow ring,非 CSS outline)。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。"}</p>
+    </div>
+  ),
+}