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

package/src/components/Separator/separator.spec.md

@@ -0,0 +1,115 @@
+---
+component: Separator
+family: self-contained
+traits: []
+variants: {}
+sizes: {}
+benchmark:
+  - Radix Separator primitive: github.com/radix-ui/primitives/tree/main/packages/react/separator
+  - Ant Design Divider: github.com/ant-design/ant-design/tree/master/components/divider
+  - MUI Divider: github.com/mui/material-ui/tree/master/packages/mui-material/src/Divider
+---
+
+# Separator 設計原則
+
+Separator 是語意分隔元件，用於標示內容群組之間的邊界。
+
+**Layout Family**：非上述 family — self-contained primitive（獨立視覺，無 slot 結構）。
+
+**實作基礎**：基於 Radix Separator（shadcn passthrough）——提供正確的 ARIA 語意：預設 `decorative=true` 時 render `role="none"`（SR 跳過），`decorative={false}` 時 render `role="separator"` + orientation 語意。詳 A11y 段。
+
+## 定位
+
+**Separator 只用於 consumer 手動放置的分隔線。** 元件固定結構（header/footer 邊框）和裝飾性邊框不使用 Separator。
+
+## 何時用 / 何時不用（判斷法）
+
+判斷核心：**誰決定「這裡要分隔」？**
+
+### Consumer 手動放 → Separator 元件
+
+Consumer 在 JSX 裡明確放置分隔線的場景：
+- `<SidebarSeparator />` 在 sidebar 群組間（消費 DS Separator）
+- `<DropdownMenuSeparator />` 在操作選單項目間（Radix Menu 自有 separator primitive，非 DS Separator）
+- `<ButtonDivider />` 在按鈕群組內（raw div + `role="separator"`，非 DS Separator）
+
+為什麼：Consumer 控制的分隔點由放置者宣告語意——DS Separator 預設 decorative（`role="none"`，SR 靜默），真實切分內容區段時 `decorative={false}` 才輸出 `role="separator"`（詳「A11y 預設」段）。
+
+### 元件自動分隔相鄰群組 → CSS `[&+&]`
+
+元件內部自動在相鄰同類群組間產生分隔線：
+- `MenuGroup`:相鄰同類群組之間自動出現 `border-divider` 分隔(見 `menu-item.tsx`)
+- `SidebarGroup`:相鄰群組之間自動產生分隔線(見 `sidebar.tsx`)
+
+為什麼：Consumer 只需要思考「分組」，不需要記得放分隔線。CSS 相鄰選擇器無法用元件替代（無處插入 DOM node）。
+
+### 元件固定結構 → CSS `border-t/b border-divider`
+
+元件內部固定存在的結構性分隔：
+- Dialog Header/Footer
+- Sidebar Header/Footer
+- ProfileCard 各 section
+- SelectMenu 搜尋框下方
+
+為什麼：這些分隔線是元件自身結構的一部分（如視窗標題列底線），不由 consumer 控制，不需要語意標記。
+
+### 控件外框 / 容器輪廓 → CSS `border border-border`
+
+視覺裝飾性邊框，不分隔內容：
+- Input / Checkbox / Radio 外框
+- Card / Dialog / Sheet 容器邊線
+- DataTable 格線
+- Tabs 底線基準
+
+## Token 規則
+
+| 用途 | Token | 值 |
+|------|-------|----|
+| 分隔線（content separation） | `--divider`（neutral-4） | 較淡 |
+| 控件邊框（container/control edge） | `--border`（neutral-5） | 較深 |
+
+**分隔線一律用 `--divider`，不用 `--border`。** 兩者視覺上接近但語意不同：`--divider` 是「這裡有群組邊界」，`--border` 是「這是元件的邊緣」。
+
+## 禁止事項
+
+- ❌ 用 Separator 元件做元件固定結構的分隔（那是 CSS border 的工作）
+- ❌ 用 `--border` token 做分隔線（應該用 `--divider`）
+- ❌ 用 `bg-border` 做 ButtonDivider 等 consumer 放置的分隔線
+
+## 邊界案例
+
+- **Vertical 方向**：`h-full` 取父容器高度——父容器無確定高度（auto）時 separator 高度為 0、不可見；需父容器有確定高度或 flex row 的 stretch 對齊
+- **空容器 / 0 寬**：horizontal `w-full` 隨父寬，父寬為 0 時無可見線；Separator 不自帶 min-width / min-height
+- **厚度固定 1px**（`h-px` / `w-px`）、非互動無 hover / focus——無 size / state 變體（見下「為何無 …」段）
+
+## 為何無 Inspector / ColorMatrix / SizeMatrix / StateBehavior
+
+Separator 是**視覺分隔 primitive**(一條 1px 線),結構極薄:
+
+- **無 Inspector**:Separator 唯一變因是 `orientation`(horizontal / vertical),已在 `TokenMatrix` 對照呈現。互動 Inspector 無進一步可調 prop。
+- **無 ColorMatrix**:Separator 固定用 `--divider` token(比 border 更淡的語意分隔色),dark mode 由 semantic token 自動切換。無變體。加 color variant 會誤用成「狀態訊號」(分隔應是中性的)。
+- **無 SizeMatrix**:Separator 固定 1px 厚度(線應該是線),長度由 container 決定(`w-full` / `h-full`)。無 sm/md/lg tier。
+- **無 StateBehavior**:非互動元件,無 hover / focus / active / selected / disabled。
+
+對應 anatomy story:保留 `Overview` + `TokenMatrix`(horizontal × vertical + `--divider` vs `--border` 用法對照)。
+
+---
+
+## A11y 預設
+
+Separator 是**純視覺 divider**,預設 ARIA 行為(對齊 Radix Separator primitive):
+
+- **預設 `role="none"`(decorative)**:純視覺分隔,SR 不朗讀(避免「separator」/「horizontal rule」雜訊干擾 list 朗讀)
+- **語意分隔場景(`decorative=false`)**:當 Separator 真實切分內容區段(`<nav>` 內分 navigation group / Menu 分群),Radix 自動 render `<div role="separator">`,SR 讀「separator」幫助理解結構。`aria-orientation` 僅在 `orientation="vertical"` 時輸出(`aria-orientation="vertical"`);`horizontal`(WAI-ARIA separator 預設方向)時 Radix 刻意省略冗餘屬性,故 DOM 不出現 `aria-orientation="horizontal"`
+- **判斷**:同 list 內 item 之間的視覺隔線 = decorative(預設);跨 region 的結構分隔(sidebar group / menu group)= semantic(`decorative={false}`)
+- **不取得 focus**:Separator 永遠 non-interactive,無鍵盤行為
+- **驗證**:Storybook a11y addon panel 0 critical violation;對齊 [Radix Separator a11y](https://www.radix-ui.com/primitives/docs/components/separator#accessibility)
+
+## 相關
+
+- `../../tokens/color/color.spec.md` — `--divider` / `--border` token 定義（「邊框 / 分隔」節）
+- `../Button/button-group.tsx` — ButtonDivider 實作
+- `../Sidebar/sidebar.tsx` — SidebarSeparator（Radix Separator 消費者）
+- `../DropdownMenu/dropdown-menu.tsx` — DropdownMenuSeparator（Radix Menu Separator）
+- `../Menu/menu-item.tsx` — MenuGroup 自動分隔 CSS pattern（`[&+&]:border-t`）
+- `../Sidebar/sidebar.tsx` — SidebarGroup 自動分隔 pseudo-element pattern

package/src/components/Separator/separator.stories.tsx

@@ -0,0 +1,127 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { MoreVertical, Pencil, Copy, Trash2, User, Bell, Shield } from 'lucide-react'
+import { Separator } from './separator'
+import { DescriptionList, DescriptionItem } from '@/design-system/components/DescriptionList/description-list'
+import { Button } from '@/design-system/components/Button/button'
+import { MenuItem } from '@/design-system/components/Menu/menu-item'
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+} from '@/design-system/components/DropdownMenu/dropdown-menu'
+
+const meta: Meta<typeof Separator> = {
+  title: 'Design System/Components/Separator/展示',
+  component: Separator,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '語意分隔元件（Radix Separator passthrough）——只用於 consumer 手動放置的分隔線。色彩固定為 `--divider` token，無 size / variant。',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof Separator>
+
+/* ── Horizontal(預設)──────────────────────────────────────────────── */
+// Settings page / overview panel 的分段 rows。**每個 row 消費 MenuItem**(Family 1 item-anatomy
+// 正式消費者),有 icon prefix + label + description;Separator 切出 row group 之間的視覺分段。
+// 對應 iOS Settings / Notion Workspace settings / Linear user settings canonical。
+export const Horizontal: Story = {
+  name: '水平',
+  render: () => (
+    <div role="listbox" aria-label="settings sections demo" className="border border-border rounded-lg max-w-md overflow-hidden">
+      <MenuItem
+        startIcon={User}
+        description="Email、時區、顯示語言"
+      >
+        帳號設定
+      </MenuItem>
+      <Separator />
+      <MenuItem
+        startIcon={Bell}
+        description="Email / 推播通知規則"
+      >
+        通知
+      </MenuItem>
+      <Separator />
+      <MenuItem
+        startIcon={Shield}
+        description="資料分享範圍、權限層級"
+      >
+        隱私
+      </MenuItem>
+    </div>
+  ),
+}
+
+/* ── Vertical（垂直分隔，toolbar 間隔）──────────────────────────────────── */
+export const Vertical: Story = {
+  name: '垂直',
+  render: () => (
+    <div className="flex items-center gap-2 border border-border rounded-lg px-3 py-2 w-fit">
+      <Button variant="text" size="sm">編輯</Button>
+      <Button variant="text" size="sm">複製</Button>
+      <Separator orientation="vertical" className="h-5" />
+      <Button variant="text" size="sm">分享</Button>
+      <Button variant="text" size="sm">下載</Button>
+      <Separator orientation="vertical" className="h-5" />
+      <Button variant="text" size="sm" danger>刪除</Button>
+    </div>
+  ),
+}
+
+/* ── 在 DropdownMenu 內 ─────────────────────────────────────────────── */
+export const InDropdownMenu: Story = {
+  name: '在 DropdownMenu 內',
+  render: () => (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <Button variant="tertiary" size="sm" startIcon={MoreVertical}>
+          更多操作
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="start">
+        <DropdownMenuItem startIcon={Pencil}>重新命名</DropdownMenuItem>
+        <DropdownMenuItem startIcon={Copy}>複製連結</DropdownMenuItem>
+        <DropdownMenuSeparator />
+        <DropdownMenuItem startIcon={Trash2}>刪除</DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  ),
+}
+
+/* ── 在 DescriptionList 之間 ────────────────────────────────────────── */
+export const BetweenSections: Story = {
+  name: '在 DescriptionList 區塊之間',
+  render: () => (
+    <div className="border border-border rounded-lg p-4 max-w-md flex flex-col gap-4">
+      {/*
+       * heading → first-item gap 對齊 item → item gap(都是 layout-space-tight):
+       * Gestalt proximity canonical —— 相同距離代表 heading 擁有下方 items;
+       * 若拉大 gap 反而讓 heading 看似「分離」,與 items 的歸屬關係變弱。世界級 idiom:
+       * iOS Settings / Notion properties / Ant Descriptions 皆採相等 gap。
+       */}
+      <div>
+        <div className="text-body font-medium mb-[var(--layout-space-tight)]">基本資料</div>
+        <DescriptionList cols={1}>
+          <DescriptionItem label="姓名">Ada Chen</DescriptionItem>
+          <DescriptionItem label="Email">ada.chen@example.com</DescriptionItem>
+        </DescriptionList>
+      </div>
+      <Separator />
+      <div>
+        <div className="text-body font-medium mb-[var(--layout-space-tight)]">團隊資訊</div>
+        <DescriptionList cols={1}>
+          <DescriptionItem label="團隊">Design Systems</DescriptionItem>
+          <DescriptionItem label="職稱">Design Engineer</DescriptionItem>
+        </DescriptionList>
+      </div>
+    </div>
+  ),
+}

package/src/components/Separator/separator.tsx

@@ -30,14 +30,14 @@ Separator.displayName = "Separator"
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const separatorMeta = {
   component: 'Separator',
-  family: null, // non-family composite / overlay / layout
+  family: 'self-contained', // 純視覺 divider,獨立視覺無 slot 結構(對齊 spec frontmatter L3 family: self-contained)
   variants: {
 
   },
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['default'], // 純 Radix Separator.Root,非互動,無 hover/active/focus/disabled(對齊 spec「無 StateBehavior」bullet + A11y 段;段名指法免行號漂移)
   tokens: {
     bg: [],
     fg: [],

package/src/components/Sheet/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 './sheet'

package/src/components/Sheet/sheet.anatomy.stories.tsx

@@ -0,0 +1,269 @@
+// @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 {
+  Sheet,
+  SheetTrigger,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  SheetDescription,
+  SheetBody,
+  SheetFooter,
+} from './sheet'
+import { Button } from '@/design-system/components/Button/button'
+import { H3, Desc, Td, Th, TokenCell } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+const meta: Meta = {
+  title: 'Design System/Components/Sheet/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>Sheet 基於 Radix Dialog 的 side variant——從畫面邊緣滑入的浮層面板。結構跟 Dialog 同（Header + Content + Footer），差異在位置與動畫。消費者 API 僅 side=&quot;right&quot;（detail panel、filter drawer）；top / bottom / left 為 DS 內部基建變體（見下方 Side 方向表）。</Desc>
+        <div className="flex items-center gap-3 flex-wrap">
+          <Sheet>
+            <SheetTrigger asChild>
+              <Button variant="tertiary">開啟任務詳情</Button>
+            </SheetTrigger>
+            <SheetContent side="right">
+              <SheetHeader>
+                <SheetTitle>修復付款流程 bug</SheetTitle>
+                <SheetDescription>#PROJ-1234 · 指派給陳大明</SheetDescription>
+              </SheetHeader>
+              <SheetBody className="text-body">
+                <p className="mb-3 text-fg-secondary">使用者於結帳最後一步點選「完成付款」後,頁面卡在轉圈動畫超過 30 秒,最終回到購物車且訂單未成立。重現率約 1/5,僅出現在 Safari 17。</p>
+                <p className="text-caption text-fg-muted">優先級 P1 · 影響 230 筆訂單 · 截止 2026-04-25</p>
+              </SheetBody>
+              <SheetFooter>
+                <Button variant="tertiary">標記為已解決</Button>
+                <Button variant="primary">儲存變更</Button>
+              </SheetFooter>
+            </SheetContent>
+          </Sheet>
+        </div>
+      </div>
+
+      <div>
+        <H3>Props 速查</H3>
+        <Desc>Sheet / SheetTrigger / SheetClose / SheetPortal 是 Radix Dialog 的薄 re-export;SheetHeader / SheetBody / SheetFooter 不是 re-export——它們各自組合了關閉 X 按鈕、捲動區域與底部分隔，並消費共用的浮層 padding；SheetTitle / SheetDescription 則在 Radix 基底上再加上字級與間距樣式。</Desc>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Prop (SheetContent)</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>side</Td><Td mono>'top' | 'right' | 'bottom' | 'left'</Td><Td mono>'right'</Td><Td>滑入方向,決定浮層位置 + 動畫</Td></tr>
+              <tr><Td mono>open / onOpenChange</Td><Td mono>boolean / (o) =&gt; void</Td><Td mono>—</Td><Td>controlled 開關(選用)——掛在 root <code>Sheet</code> 非 SheetContent</Td></tr>
+              <tr><Td mono>onEscapeKeyDown</Td><Td mono>(e) =&gt; void</Td><Td mono>—</Td><Td>Esc 鍵 callback,preventDefault 阻止關閉</Td></tr>
+              <tr><Td mono>onPointerDownOutside</Td><Td mono>(e) =&gt; void</Td><Td mono>—</Td><Td>點擊外部 callback,preventDefault 阻止關閉</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+// ── Inspector ─────────────────────────────────────────────────────────────
+
+interface InspectorArgs {
+  side: 'top' | 'right' | 'bottom' | 'left'
+  width: 'default' | 'sm' | 'lg'
+  showFooter: boolean
+}
+
+export const Inspector: Story = {
+  name: '元件檢閱器',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '右側 Controls 切 SheetContent props 即時 render,取代 Figma inspect。切 `side` 看四個方向的滑入動畫 + 位置;切 `width` 看自訂寬度覆寫。點 trigger 觸發 Sheet,Esc 或點遮罩關閉。',
+      },
+    },
+  },
+  args: {
+    side: 'right',
+    width: 'default',
+    showFooter: true,
+  },
+  argTypes: {
+    side: {
+      control: 'radio',
+      options: ['top', 'right', 'bottom', 'left'],
+      description: 'right★default(detail drawer)/ left(mobile nav)/ top(notification)/ bottom(action sheet)',
+    },
+    width: {
+      control: 'radio',
+      options: ['default', 'sm', 'lg'],
+      description: 'default=w-3/4 + sm:max-w-md / sm=max-w-sm / lg=max-w-lg',
+    },
+    showFooter: { control: 'boolean', description: '顯示 SheetFooter(含「取消 / 儲存」CTA)' },
+  },
+  render: (args) => {
+    const { side, width, showFooter } = args as InspectorArgs
+    const widthClass =
+      width === 'sm' ? 'sm:max-w-sm' : width === 'lg' ? 'sm:max-w-lg' : ''
+    return (
+      <Sheet>
+        <SheetTrigger asChild>
+          <Button variant="tertiary">開啟任務詳情</Button>
+        </SheetTrigger>
+        <SheetContent side={side} className={widthClass}>
+          <SheetHeader>
+            <SheetTitle>修復付款流程 bug</SheetTitle>
+            <SheetDescription>#PROJ-1234 · 指派給陳大明</SheetDescription>
+          </SheetHeader>
+          <SheetBody className="text-body">
+            <p className="mb-3 text-fg-secondary">使用者於結帳最後一步點選「完成付款」後,頁面卡在轉圈動畫超過 30 秒,最終回到購物車且訂單未成立。重現率約 1/5,僅出現在 Safari 17。</p>
+            <p className="text-caption text-fg-muted">優先級 P1 · 影響 230 筆訂單 · 截止 2026-04-25</p>
+          </SheetBody>
+          {showFooter && (
+            <SheetFooter>
+              <Button variant="tertiary">標記為已解決</Button>
+              <Button variant="primary">儲存變更</Button>
+            </SheetFooter>
+          )}
+        </SheetContent>
+      </Sheet>
+    )
+  },
+}
+
+export const SideMatrix: Story = {
+  name: 'Side 方向 × 用途',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>Side 方向（消費者 API = right；其餘為 DS 內部基建）</H3>
+        <Desc>消費者 code 只能用 side=&quot;right&quot;。top / bottom / left 變體保留 DS 內部基建用（例：Sidebar 小視口 left-slide），消費者禁止直接傳、需授權（canonical 見 sheet.tsx L23-27 + showcase AR35）。下表後三列為內部能力 + 世界級對照，供 DS contributor 參考。</Desc>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Side</Th><Th>滑入方向</Th><Th>典型用途</Th><Th>世界級對照</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>right ★消費者 default</Td><Td>從右邊</Td><Td>消費者 API：Detail panel（Jira task drawer、Linear issue detail、GitHub PR file diff drawer）、filter panel</Td><Td>Jira / Linear / Notion side panel</Td></tr>
+              <tr><Td mono>left（內部）</Td><Td>從左邊</Td><Td>DS 內部基建：Sidebar 小視口 left-slide（非消費者 API）</Td><Td>Material mobile drawer、Slack mobile nav</Td></tr>
+              <tr><Td mono>top（內部）</Td><Td>從上方</Td><Td>DS 內部基建保留（非消費者 API，notification center 類）</Td><Td>iOS Control Center top pull-down</Td></tr>
+              <tr><Td mono>bottom（內部）</Td><Td>從下方</Td><Td>DS 內部基建保留（非消費者 API；mobile bottom sheet 另用專屬元件）</Td><Td>iOS Bottom Sheet、Material Bottom Sheet</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div>
+        <H3>實際範例（右側 detail drawer）</H3>
+        <Desc>最常見用法：列表項點擊後從右側滑入 detail panel，使用者可在 panel 內編輯同時看到背景列表。</Desc>
+        <Sheet>
+          <SheetTrigger asChild>
+            <Button variant="tertiary">開啟 detail panel</Button>
+          </SheetTrigger>
+          <SheetContent side="right">
+            <SheetHeader>
+              <SheetTitle>Q1 財報</SheetTitle>
+              <SheetDescription>最後編輯：2026-04-18 17:32</SheetDescription>
+            </SheetHeader>
+            <SheetBody>
+              <p className="text-body text-fg-secondary">本季營收 NT$4,820 萬,較上季成長 12%;毛利率 38.5%。下方附完整損益表與部門別明細,可直接在此面板註記後送交財務複核。</p>
+            </SheetBody>
+            <SheetFooter>
+              <Button variant="primary">儲存</Button>
+            </SheetFooter>
+          </SheetContent>
+        </Sheet>
+      </div>
+    </div>
+  ),
+}
+
+export const ColorMatrix: Story = {
+  name: '色彩對照表',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>Sheet 視覺 token（與 Dialog 共用基底）</H3>
+        <Desc>Sheet 和 Dialog 共用 `bg-surface-raised` + elevation-200——改其中一個必須連動另一個,不讓 modal 家族視覺漂移。容器邊框各自不同:Sheet 用較淡的 `border-divider`,Dialog 用 `border-border`。</Desc>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>層</Th><Th>Token</Th><Th>說明</Th></tr></thead>
+            <tbody>
+              <tr><Td>Overlay</Td><Td><TokenCell token="--overlay" display="bg-overlay" /></Td><Td>背景遮罩 semi-transparent</Td></tr>
+              <tr><Td>Sheet 背景</Td><Td><TokenCell token="--surface-raised" display="bg-surface-raised" /></Td><Td>比 surface 高一階</Td></tr>
+              <tr><Td>容器邊框</Td><Td><TokenCell token="--divider" display="border-divider" /></Td><Td>側緣描邊,較 Dialog 的 border-border 淡一階</Td></tr>
+              <tr><Td>分隔線（header / footer）</Td><Td><TokenCell token="--divider" display="border-divider" /></Td><Td>區隔 section</Td></tr>
+              <tr><Td>主要文字</Td><Td><TokenCell token="--foreground" display="text-foreground" /></Td><Td>Title</Td></tr>
+              <tr><Td>次要文字</Td><Td><TokenCell token="--fg-secondary" display="text-fg-secondary" /></Td><Td>Description</Td></tr>
+              <tr><Td>Shadow</Td><Td mono>--elevation-200</Td><Td>浮層 elevation</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const SizeMatrix: Story = {
+  name: '尺寸對照表',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>預設尺寸</H3>
+        <Desc>Sheet 大小依 `side` 變化：左/右 sheet 有預設寬度（響應式限制 max-w），上/下 sheet 有預設高度。consumer 可透過 className 自訂。</Desc>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Side</Th><Th>預設尺寸</Th><Th>響應式</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>right / left</Td><Td mono>w-3/4（手機佔 75% 寬）</Td><Td>sm:max-w-md（桌機 448px）</Td></tr>
+              <tr><Td mono>top / bottom</Td><Td>auto（依內容）</Td><Td>—</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div>
+        <H3>覆寫寬度 / 高度</H3>
+        <Desc>{'consumer 透過 className 覆寫。例:`<SheetContent className="w-full sm:max-w-lg">` 桌機用更寬。'}</Desc>
+      </div>
+    </div>
+  ),
+}
+
+export const StateBehavior: Story = {
+  name: '狀態行為',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>開啟 / 關閉</H3>
+        <Desc>Radix 提供 data-state 切換 + DS Tailwind animate 驅動進離場動畫（slide-in-from-側邊 + fade-in overlay，300ms；sheet.tsx L69-78），離場鏡像。Modal 狀態鎖 body scroll。</Desc>
+        <ul className="text-caption text-fg-muted list-disc pl-5 space-y-1">
+          <li>點擊 trigger → 開啟（slide-in from `side`）</li>
+          <li>點擊 overlay → 關閉（default；可用 onPointerDownOutside preventDefault 阻止）</li>
+          <li>按 Esc → 關閉（default；可用 onEscapeKeyDown preventDefault 阻止）</li>
+          <li>點擊 X close button → 關閉</li>
+          <li>Focus trap 限制 Tab 循環在 Sheet 內</li>
+        </ul>
+      </div>
+
+      <div>
+        <H3>Disabled / loading / empty / error 的職責邊界</H3>
+        <Desc>Sheet 是容器,無整體狀態——內容層負責。trigger 的 disabled 由 trigger 自己管;內容的 loading / empty / error 由 consumer 在 `SheetContent` 內渲染對應 primitive（Skeleton / Empty / Alert）。</Desc>
+      </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">{"Sheet 沿用 Radix 對話框的無障礙預設,開啟後會自動標記為對話框、把標題念給螢幕報讀器聽,並把鍵盤焦點鎖在面板內。\n\n鍵盤操作:\n\n- Tab — 焦點只在面板內循環,不會跑到背景頁面\n- Shift + Tab — 反向循環焦點\n- Esc — 關閉面板\n\n焦點:開啟時自動把焦點移進面板,關閉後還回原本的觸發按鈕;鍵盤聚焦的元素會顯示清楚的外框。\n\n驗證標準:Storybook 無障礙檢查面板不應出現嚴重問題,且全程僅用鍵盤即可操作,不需滑鼠。文字對比至少 4.5:1、介面元素對比至少 3:1(WCAG AA)。"}</p>
+    </div>
+  ),
+}