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

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

@@ -0,0 +1,109 @@
+---
+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 `role="separator"` + orientation 語意。
+
+## 定位
+
+**Separator 只用於 consumer 手動放置的分隔線。** 元件固定結構（header/footer 邊框）和裝飾性邊框不使用 Separator。
+
+## 何時用 / 何時不用（判斷法）
+
+判斷核心：**誰決定「這裡要分隔」？**
+
+### Consumer 手動放 → Separator 元件
+
+Consumer 在 JSX 裡明確放置分隔線的場景：
+- `<SidebarSeparator />` 在 sidebar 群組間
+- `<DropdownMenuSeparator />` 在操作選單項目間
+- `<ButtonDivider />` 在按鈕群組內
+
+為什麼：Consumer 控制的分隔點需要語意標記（`role="separator"`），讓輔助技術能辨識內容群組邊界。
+
+### 元件自動分隔相鄰群組 → CSS `[&+&]`
+
+元件內部自動在相鄰同類群組間產生分隔線：
+- `MenuGroup`:相鄰同類群組之間自動出現 `border-divider` 分隔(見 `menu.tsx`)
+- `SidebarGroup`:相鄰群組之間自動產生分隔線(見 `sidebar.tsx`)
+
+為什麼：Consumer 只需要思考「分組」，不需要記得放分隔線。CSS 相鄰選擇器無法用元件替代（無處插入 DOM node）。
+
+### 元件固定結構 → CSS `border-t/b border-divider`
+
+元件內部固定存在的結構性分隔：
+- Dialog Header/Footer
+- Sidebar Header/Footer
+- NameCard 各 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 放置的分隔線
+
+## 為何無 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" aria-orientation="horizontal|vertical">`,SR 讀「separator」幫助理解結構
+- **判斷**:同 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/Sheet/sheet.spec.md

@@ -0,0 +1,148 @@
+---
+component: Sheet
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - isOverlay
+benchmark:
+  - Radix Dialog primitive (shadcn Sheet base): github.com/radix-ui/primitives/tree/main/packages/react/dialog
+  - MUI Drawer: github.com/mui/material-ui/tree/master/packages/mui-material/src/Drawer
+  - Ant Design Drawer: github.com/ant-design/ant-design/tree/master/components/drawer
+  - Polaris Sheet: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Sheet
+---
+
+# Sheet 設計原則
+
+## 定位
+
+Sheet 是**從畫面邊緣滑入的浮層面板**——上 / 下 / 左 / 右四個方向，用於側邊操作、暫時性 panel、mobile fullscreen 編輯。
+
+**實作基礎**：shadcn passthrough——基於 Radix Dialog（`side` variant，非居中 modal）。本 DS 保留 shadcn 原結構 + 橋接 DS token。
+
+**Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
+
+---
+
+## 何時用
+
+- **側邊操作面板**：filter panel、detail pane、task 編輯 side sheet
+- **暫時性內容展示**：notification drawer、cart summary、activity history
+- **Mobile fullscreen 編輯**：桌機用 Dialog 的場景在手機改用 Sheet bottom / fullscreen
+- **跟主頁面平行的工作流程**：使用者在主頁看清單，sheet 編輯某一項，不離開清單 context
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 需要集中注意力的確認 / 破壞性動作 | `Dialog` | Dialog 是居中 modal，視覺更聚焦；Sheet 靠邊較輕 |
+| 短暫的回饋訊息（成功 / 失敗）| `Toast` | Toast 自動消失，Sheet 需使用者明確關閉 |
+| 持久性頁面通知 | `Alert` | Alert 是 inline，Sheet 是浮層 |
+| 主導覽外殼 | `Sidebar` | Sidebar 持續存在，Sheet 是暫時浮層 |
+| Hover 補充資訊 | `HoverCard` / `Tooltip` | Sheet 觸發是點擊、體積大 |
+| 選值 / 選單 | `Select` / `DropdownMenu` | Sheet 太重，選單用專用元件 |
+
+---
+
+## Sheet vs Dialog 的分界
+
+| | Sheet | Dialog |
+|---|---|---|
+| 位置 | 畫面邊緣滑入（上/下/左/右） | 畫面居中 |
+| 視覺重量 | 較輕（單邊） | 較重（四周 overlay） |
+| 典型用途 | 側邊工作流程、detail panel | 確認流程、複雜表單 |
+| 阻斷感 | 較弱（使用者視線可繼續掃主頁） | 強（完全聚焦 modal） |
+| 手機體驗 | 自然（從底部 / 全螢幕滑入符合 mobile pattern） | 桌機導向（中央 modal 不符 mobile sheet pattern，浮層遮住主流向） |
+
+**判準**：
+- **需要聚焦決策（刪除、確認、複雜表單）→ Dialog**
+- **主頁面平行的側邊工作 / mobile 編輯 → Sheet**
+
+---
+
+## 為何無 Inspector
+
+Sheet 是**側邊滑入 modal 容器**,關鍵決策維度是 `side`(top / right / bottom / left)× size(響應式)× open/close——已由元件特有 `SideMatrix`(4 個方向結構對照) + `SizeMatrix` + `StateBehavior`(open/close/ESC) + `ColorMatrix` 四張矩陣覆蓋。互動 Inspector 切換 side 不如 side-by-side 4 方向對照直觀——需要視覺比較各方向滑入結構。內容完全由 consumer 決定,Sheet 本身無 variant/disabled 等可試玩 prop。
+
+對應 anatomy story:保留 `Overview` + 元件特有 `SideMatrix`(4 方向 × 用途) + `ColorMatrix` + `SizeMatrix` + `StateBehavior`。
+
+---
+
+## Padding SSOT
+
+Sheet 的 `SheetHeader` / `SheetBody` / `SheetFooter` 對應 `SurfaceHeader` / `SurfaceBody` / `SurfaceFooter` primitive——padding + 分隔線由 `patterns/overlay-surface/overlay-surface.spec.md` own,Sheet 與 Dialog / Popover 共用同一套 primitive,避免 token 漂移。Sheet 特有行為:side variant(`top` / `right` / `bottom` / `left`)決定滑入方向 + height/width 響應式策略,padding 本身對齊 overlay-surface canonical。
+
+---
+
+## 關閉按鈕
+
+> **跨家族 SSOT pointer**:SheetHeader 屬 **Padding-based overlay header 家族**;border / padding / dismiss size / withTabs 的跨家族視覺契約 SSOT 詳 `patterns/header-canonical/header-canonical.spec.md`。本節僅 codify Sheet 特有 close X canonical。
+
+永遠存在於 SheetHeader 右側(對齊 DialogHeader canonical)。使用 `<Button iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />`,不可移除——使用者永遠需要明確的關閉手段。
+
+**Canonical 來源**:Sheet 是 overlay chrome,corner close X 屬 action group region,必用 Button(非 Inline Action / 非自刻 button)。詳見 `patterns/element-anatomy/inline-action.spec.md`「Dismiss canonical — X close only」+ `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」。
+
+---
+
+## 空值 / 驗證 / a11y
+
+Sheet 為容器,內容由 consumer 決定;focus trap + Escape close + `aria-labelledby` 由 Radix Dialog primitive 提供。
+
+---
+
+## 禁止事項
+
+- ❌ Sheet 內塞滿全頁複雜流程 — Sheet 是 side surface 不是 page 替代;若內容超過 3-4 個 section / 多步表單,改 navigate 到獨立 route page
+- ❌ Sheet 內再開 Sheet(nested side surface)— 視覺空間衝突,user 找不到 escape;改用 Dialog 或 page transition
+- ❌ Sheet trigger 用 inline link(非 Button)— Sheet 是 substantive action 不是 navigation,affordance 必須是 Button(可 tertiary / icon-only)
+- ❌ Sheet content 無 title — `aria-labelledby` 必須對應可見 title,SR 否則讀「unnamed dialog」
+- ❌ Sheet 用作 Toast / 短暫通知 — Sheet 阻斷 chrome interaction,不適合 ephemeral 訊息;短暫 → Toast / 持久 → Alert / 阻斷 confirm → Dialog
+- ❌ 跳過 Radix Dialog primitive 自建 Sheet — focus trap / Esc close / Portal escape 邏輯複雜,自建必漏
+
+---
+
+## 邊界案例
+
+- **Disabled**:Sheet 本身無 disabled state(非互動 control,是 surface container);trigger Button 由 consumer 控 disabled。
+- **Loading(panel content loading)**:Sheet 為純容器,不獨立 own loading state。Async body 場景由 consumer 在 body slot 渲 `<Empty icon={<CircularProgress size={48}/>}/>`(對齊 `empty.spec.md:182` 全頁 loading SSOT)或 `<Skeleton>` line-stack 取代 content,不開 / 不關 Sheet 即可。
+- **Empty(no content)**:Sheet 必含 title(`aria-labelledby` 強制要求);body 為空時 consumer 應渲 `<Empty>` placeholder,不渲空白 panel。
+- **Dark mode**:overlay-surface SSOT 自動 adapt(`overlay-surface.spec.md`);Sheet 不獨立 own dark token。
+- **Density**:Sheet body density 由 consumer 控(若內含 form / DataTable / Menu 各自有 density 規則);Sheet container 自身不持 density。
+
+---
+
+## 相關
+
+- `../Dialog/dialog.spec.md` — 居中 modal 的對應元件（共用 Radix Dialog base）
+- `../Sidebar/sidebar.spec.md` — 持久性導覽（非暫時浮層）
+- `../Toast/toast.spec.md` — 短暫自動消失的浮動通知
+- `../DropdownMenu/dropdown-menu.spec.md` — 選單類浮層
+- Radix Dialog primitive — `@radix-ui/react-dialog`（Sheet 是 side variant）
+
+## A11y 預設
+
+**ARIA / Pattern**:繼承 Radix `dialog` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/dialog#accessibility)。
+
+**Keyboard 行為**:
+
+- Tab — focus trap 在 sheet 內
+- Esc — 關閉
+- Shift+Tab — 反向 focus 循環
+
+**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `accordion.spec.md`
+- `scroll-area.spec.md`
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `app-shell.spec.md`
+- `density.spec.md`