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

package/src/components/Alert/alert.spec.md

@@ -0,0 +1,197 @@
+---
+component: Alert
+family: 2
+traits:
+  - hasVariants
+  - hasInteractiveStates
+variants:
+  neutral:
+    when: "中性提示(系統公告、非緊急說明);無情緒色"
+    world-class: ["Ant Alert type=info(neutral)", "Polaris Banner default"]
+  info:
+    when: "資訊性提示(版本更新、流程說明);藍色 hue"
+    world-class: ["Ant Alert type=info", "Material Alert severity=info", "Carbon InlineNotification kind=info"]
+  success:
+    when: "成功狀態的持久性宣告(綁定生效、付款完成需保留確認)"
+    world-class: ["Ant Alert type=success", "Polaris Banner status=success"]
+  warning:
+    when: "警告但非阻斷(方案即將到期、需更新付款方式);最高頻使用"
+    world-class: ["Ant Alert type=warning", "Polaris Banner status=warning", "Material Alert severity=warning"]
+  error:
+    when: "錯誤但非阻斷(系統錯誤但可重試、API 失敗摘要);搭配 aria-live=assertive"
+    world-class: ["Ant Alert type=error", "Polaris Banner status=critical", "Carbon InlineNotification kind=error"]
+sizes: {}
+benchmark:
+  - Ant Design Alert: github.com/ant-design/ant-design/tree/master/components/alert
+  - MUI Alert: github.com/mui/material-ui/tree/master/packages/mui-material/src/Alert
+  - Carbon Notification: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Notification
+  - Polaris Banner: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Banner
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Alert 設計原則
+
+## 定位
+
+Alert 是**持久性通知**，嵌入在頁面中。用於系統狀態提示、警告、錯誤訊息。使用者需要主動 dismiss 或處理。
+
+**實作基礎**：消費 Notice primitive（共享 Toast 的 layout + icon + theme 策略）。
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」章節的 reading-mode 規格。Alert 透過 Notice 繼承 Family 2 結構。
+
+---
+
+## 何時用
+
+- **頁面內需要持續存在的狀態通知**：方案即將到期、帳戶驗證未完成、需要更新付款方式
+- **頂部全域警告**（`placement="fixed"`）：系統維護中、服務降級、重要公告
+- **表單 / Dialog 內的 inline 提示**：複雜動作的前置警告（刪除前的資料影響說明）
+- **需要使用者處理才會消失的訊息**：有 CTA 可以解決問題、或需明確按下 dismiss
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 操作結果短暫回饋（儲存成功、刪除失敗）| `Toast` | Toast 自動消失，不佔頁面空間 |
+| 需要阻斷背景互動 | `Dialog` | Alert 是 inline，不阻斷 |
+| 欄位級驗證錯誤 | Field error message | Alert 是頁面級，欄位錯誤靠在欄位下方 |
+| 成功訊息需要使用者確認 | `Toast`（非阻斷）/ `Dialog`（需確認）| Alert 的持久成本對成功訊息太高 |
+
+---
+
+## 與 Toast / Notice 的分界
+
+**本節是 SSOT**——Toast spec 反向引用此節，避免兩側漂移。
+
+- **Alert**：持續顯示的 on-page 通知，使用者需主動 dismiss 或永不關閉（如頂部全域警告）
+- **Toast**：短暫浮動通知，自動消失（預設 3–5 秒）
+- **Notice**：兩者共用的內部 layout primitive，consumer **不直接使用**（由 Alert / Toast 消費）
+
+**判斷法**：問「這個訊息重要到需要使用者 acknowledge 嗎？」
+
+- 是（方案到期、帳戶未驗證、系統維護中、錯誤需要處理）→ **Alert**
+- 否（儲存成功、已複製、上傳完成）→ **Toast**
+
+---
+
+## 禁止事項
+
+- ❌ **不在 Alert 內放長篇內容**：Alert 是摘要 + CTA,超過 2–3 行的內容改用 Dialog 或導向獨立頁面
+- ❌ **不把 error form validation 做成 Alert**：欄位級錯誤必須貼近發生位置（FieldError）,使用者才能快速定位；頁面級 Alert 只放非欄位的整體錯誤（如提交失敗、權限不足）
+- ❌ **Alert 不疊 Alert**：同區出現多個 Alert 視覺雜訊重,整理成一組 messages 或合併為單一 Alert with list
+- ❌ **destructive 操作確認不用 Alert**：刪除 / 離開等需要明確確認的動作用 Dialog,Alert 無法承載 confirm / cancel 雙按鈕的阻斷流程
+- ❌ **body action row 不得混入 close X**:close X 必在 chrome corner action group,不可跟 CTA 擺在同一 row(違反 same-row consistency — CTA 是 labeled Button sm tertiary,close X 是 Button iconOnly sm dismiss,box size 與視覺分量不同,同 row 會造成 gap / 對齊錯亂)。完整規則見 `patterns/element-anatomy/inline-action.spec.md`「Same-row consistency rule(防混用)」節
+- ❌ **close X 不用 Inline Action 或自刻 `<button><X /></button>`**:corner 屬 action group region,必用 `<Button iconOnly dismiss size="sm" />`(見上方 Chrome corner close X canonical)
+
+---
+
+## A11y 預設
+
+- **預設**：`role="alert"` + `aria-live="polite"`——screen reader 在空閒時讀出 Alert 內容，不中斷使用者目前動作
+- **error variant 可升級**：`aria-live="assertive"` 中斷 screen reader 目前朗讀，立即讀出 Alert（僅用於真正 critical 的錯誤，避免濫用干擾）
+- **Close X 按鈕**：必須有 `aria-label`(如「關閉通知」),實作見下方「Chrome corner close X canonical」
+- **CTA 按鈕**：放在 Alert body action row 時 size 固定為 `xs` tertiary,文字描述動作(「前往設定」「立即更新」)
+
+---
+
+## Chrome corner close X canonical
+
+Alert 右上角的 close X **必須用 `<Button iconOnly dismiss size="sm" />`**,不是 Inline Action、不是自刻 button。
+
+**為什麼是 Button(Cat 3 Action group region)而非 Inline Action**:
+- Alert 的 chrome corner 屬 **action group region**(toolbar / chrome corner / standalone 類),實務上 close 左側可並排 refresh / share / minimize 等額外 action + `<Separator orientation="vertical" />`——一旦成為 action group,所有成員必同類(same-row consistency),統一 Button iconOnly
+- Inline Action 是「embedded 在 host 內部的 tap target」(Cat 1,如 Input clear X / Tag dismiss X),不參與 action group 規則,兩者不可混用
+- `dismiss` prop 自動套 `variant="text"` + `fg-muted → hover foreground` 弱化,視覺輕量不壓過內容
+
+**只有 X close(dismiss 語意「關閉 surface」)才套 `dismiss` prop**——Trash / Delete / Clear / Remove 不屬 dismiss,不套此 prop。
+
+SSOT 詳見 `patterns/element-anatomy/inline-action.spec.md`「Predicate:Inline Action vs Button iconOnly(canonical)」+「Dismiss canonical — X close only」章節;Button 端詳見 `components/Button/button.spec.md`「Dismiss 視覺類」段。
+
+### Corner action group 佈局 canonical
+
+Alert chrome corner 可承載多個 action(close 左側並排):
+
+```
+┌─ Alert ────────────────── [⟲] │ [X] ┐   ← chrome corner action group(Button sm)
+│ [icon] Title                         │     refresh / share / minimize 等 + Separator + close X
+│ Description                          │
+│                      [CTA1] [CTA2]   │   ← body action row(Button sm tertiary)
+└──────────────────────────────────────┘
+```
+
+**規則**:
+- 同一 action group 所有 Button 同 `size="sm"`(跟 close X 對齊)
+- 多 action 之間用 `<Separator orientation="vertical" />` 分群(`refresh / share` 一群,`close` 一群)
+- 若只有 close X 則不需要 Separator(單一 action 即 group)
+
+**世界級對照**:
+- **Material Banner**(`<Banner actions={[...]}/>` 右上 close + 可加 refresh)
+- **Polaris Banner**(`onDismiss` 走 IconButton,右上 action group)
+- **VS Code editor tab** window corner(close + pin + split,全部同 size IconButton)
+- **Figma panel corner**(close + collapse 同 group,Separator 分隔)
+
+### Multi corner action 場景
+
+目前 Alert API 只透過 `dismissible` 渲染單一 close X。多 corner action 場景目前不支援;若未來 consumer 有需求,走 Checkpoint 3 決策(M8 benchmark + consumer survey),不預先投機擴 API。
+
+---
+
+## Appearance
+
+### Subtle(預設)
+
+淺底色 + 四邊 1px border(邊框採語意色的 hover tint)。99% 場景用 subtle——視覺重量適中,使用者注意但可繼續主要任務。不設 `data-theme`,元素跟隨頁面 theme。
+
+### Solid
+
+飽和底色,跟 Toast 完全相同的 theme 策略(critical severity 場景:info / success / error 走 dark theme 白字,warning 走 light theme 深字以保對比)。一個頁面最多一個 solid Alert。
+
+Subtle vs Solid 的完整 variant × theme class 對照見 anatomy `ColorMatrix` story。
+
+## Placement
+
+- **`inline`(預設)**:頁面內嵌,圓角 + 邊框,像一張 card 嵌在內容區塊裡
+- **`fixed`**:頂部全域警告,無圓角無邊框,橫跨頁面寬度
+
+**為什麼兩種 placement 的圓角不同**:inline 是 content-level card(rounded-md = 4px,對齊 Alert 的 inline 容器身份,與 Dialog / Card 一致);fixed 是 page-level bar(無 radius,橫跨畫面形成整條)。Toast 是浮層用 `rounded-lg`(8px,浮層慣例),跟 Alert 區分。
+
+完整 placement 對照見 anatomy `PlacementMatrix` story。
+
+## 為何無 Inspector / SizeMatrix
+
+- **無 Inspector**:Alert 的關鍵決策維度是 `variant`(5 色)× `appearance`(subtle / solid)× `placement`(inline / fixed),已在 `ColorMatrix` 完整呈現 variant × appearance 矩陣,再加 `PlacementMatrix` 呈現 placement——互動切換式 Inspector 不會比這兩張矩陣更能傳達 Alert 的設計規格。
+- **無 SizeMatrix**:Alert 無 `size` prop,其視覺尺寸繼承自 Notice primitive(14px body / 16px icon / fixed padding),不隨 density 變動。尺寸規格由 `Notice` spec own。改 Notice 時 Alert 自動跟進,不需要 Alert 有獨立 SizeMatrix。
+
+對應 anatomy story:保留 `Overview` + `ColorMatrix` + `StateBehavior` + 元件特有 `PlacementMatrix`。
+
+---
+
+## API
+
+```tsx
+<Alert variant="warning" title="即將到期" description="您的方案將在 3 天後到期" />
+<Alert variant="error" appearance="solid" title="系統錯誤" />
+<Alert variant="info" placement="fixed" title="系統維護中，部分功能暫停" />
+```
+
+---
+
+## 邊界案例
+
+- **Disabled(dismiss button)**:Alert 本身無 `disabled` prop(持久通知不該被禁用),但 dismiss close X 為 `<Button iconOnly dismiss size="sm" />`,自動繼承 Button disabled 視覺(`text-fg-disabled` + `cursor-not-allowed` + 無 hover bg);實務場景:後台正在執行 close action(API in-flight)時 consumer 可 disable button 防 double-click,fg token 走 Button SSOT 不在 Alert 加層。
+- **Loading**:Alert 本身不需 loading state(非 async surface);若 Alert body action row 內 CTA 在 async 動作中,該 Button 自己處理 `loading` prop。
+- **Empty / icon-only**:Alert 必有 `title`(API contract),無 empty 場景;若無 description 則僅顯示 title + icon,layout 自動收斂。
+
+## 相關
+
+- `../Notice/notice.spec.md` — Alert 消費的 layout primitive（與 Toast 共用）
+- `../Toast/toast.spec.md` — 非阻斷短暫通知（同一套視覺策略）
+- `../Dialog/dialog.spec.md` — 需要阻斷背景的警告改用 Dialog
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `empty.spec.md`
+- `skeleton.spec.md`

package/src/components/AppShell/app-shell.spec.md

@@ -0,0 +1,331 @@
+---
+pattern: app-shell
+scope: web service page-level layout primitive (sidebar + header + main + aside composition)
+benchmark:
+  - Mantine AppShell: https://mantine.dev/core/app-shell/ — 6-slot (Header/Navbar/Aside/Footer/Main) + layout="default|alt" mode
+  - Ant Design Layout: https://ant.design/components/layout — Layout/Header/Sider/Content/Footer compound API
+  - Material 3 Navigation Drawer: https://m3.material.io/components/navigation-drawer/overview — standard (persistent inline) vs modal (overlay with mask)
+  - Atlassian Navigation System (Beta): https://atlassian.design/components/navigation-system — TopNav + SideNav + Layout
+  - Linear / Notion / Figma — primary-sidebar mode reference(local toolbar header)
+  - GitHub / Slack / Gmail — primary-header mode reference(global top bar)
+---
+
+<!-- @benchmark-cited: 2026-05-19 D5 cite — all design intent claims backed by frontmatter benchmark URLs. -->
+
+# AppShell 設計原則
+
+## 定位
+
+**Web service 頁面層級的 layout primitive**——組合 `Sidebar` + `ChromeHeader` + `Aside` + main content 成完整 page shell,定義跨元件 composition + responsive + a11y landmark canonical。
+
+**實作基礎**:自建 grid/flex layout(無 Radix primitive 對應)+ 消費既有 DS canonical(`Sidebar` / `header-canonical` / `Sheet` / `layoutSpace`)。對齊 Mantine AppShell compound API + Ant Layout slot 模式。
+
+**Layout Family**:跨 family 的**整頁框架**,不屬 4-family 任一,但**所有 family 元件可塞進 main slot**。
+
+**SSOT 邊界**:
+- AppShell own:slot composition / layout mode / Aside inline-vs-modal mode / mobile breakpoint propagate
+- **不 own**:Sidebar 視覺(SSOT 在 `Sidebar.spec.md`)/ Header 視覺(SSOT 在 `header-canonical.spec.md`)/ Sheet 視覺(SSOT 在 `sheet.spec.md`)/ Main 內 layout(SSOT 在 `layoutSpace.spec.md` 6 條規則)
+
+**不是**:`Sidebar`(本 shell consumer 之一)/ `Sheet`(臨時浮層)/ `ChromeHeader`(local header)/ `Page`(語意 wrapper,不存在於本 DS)。
+
+---
+
+## 何時用
+
+- 多頁 web service 主結構(Linear / Notion / Slack / GitHub / Asana 類)
+- 需要 sidebar + main 持續共存,跨頁切換時 sidebar 不重渲染
+- 需要 right panel(info / inspector / detail pane)跟 main 並存
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|---|---|---|
+| 單頁 landing / marketing site | `<main>` 直接展開 | 沒導覽不需要 shell |
+| Auth 頁(login / signup) | 自寫 centered layout | 不該被 sidebar 佔位 |
+| Embedded widget / iframe | `<main>` only | 已被 host shell 包住 |
+| 文件 reader(全螢幕閱讀)| `<main>` only | shell chrome 干擾閱讀 |
+
+---
+
+## API skeleton(對齊 Mantine compound API)
+
+```tsx
+<AppShell
+  layout="primary-sidebar" | "primary-header"   // 預設 primary-sidebar
+  // sidebar 開合 state 走 Sidebar SSOT 既有 SidebarProvider(消費既有 ⌘B / Ctrl+B,本 AppShell 不重發明)
+  asideOpen={open}      onAsideOpenChange={setOpen}      // ⌘. / Ctrl+. toggle (本 AppShell own)
+  sidebar={<Sidebar>...</Sidebar>}              // SSOT in components/Sidebar/sidebar.spec.md
+  header={<ChromeHeader>...</ChromeHeader>}     // SSOT in patterns/header-canonical/header-canonical.spec.md
+  aside={<AppShellAside title="Detail">...</AppShellAside>}   // 本 pattern own;modal mode 必 title(Sheet a11y)
+>
+  {children}    {/* <main> landmark, padding=0,內容遵循 layoutSpace 6 條規則 */}
+</AppShell>
+```
+
+Sub-component:`<AppShellAside title={...} width={400}>`(width consumer 自決 — `number` 或 `{ md, xl }` breakpoint-keyed,clamp `min-width: 240` / `max-width: 640`;**title prop required**,modal mode 走 Sheet → `aria-labelledby` 強制,per `sheet.spec.md:98`)。
+
+### Hook export:`useAppShell()`(2026-05-21 D2 codify per Phase B codex catch)
+
+Public compound API hook,讓 consumer 自拼 custom aside / 自管 modal layout(對齊 Radix `useDialogContext` / MUI `useFormControl` / Mantine `useAppShellContext` 慣例)。
+
+```tsx
+import { useAppShell } from '@/design-system/components/AppShell/app-shell'
+
+function CustomAside() {
+  const { asideOpen, setAsideOpen, isMobile } = useAppShell()
+  // 自管 visibility / mobile sync,不必走預設 <AppShellAside>
+}
+```
+
+**Contract**:
+- 必在 `<AppShell>` 子樹內 call,否則 throw(consumer 拼 layout 必 wrap AppShell context)
+- 回傳:`{ asideOpen: boolean, setAsideOpen: (open: boolean) => void, isMobile: boolean }`
+- 設計目的:給跳出 `<AppShellAside>` 預設 sub-component 框架的 consumer 用(rare),DS 預設仍建議走 `<AppShellAside>` slot
+
+---
+
+## Layout mode(對齊 Mantine `layout` prop)
+
+| Mode | Sidebar 位置 | Header 結構 | 適用 product 派 |
+|---|---|---|---|
+| **`primary-sidebar`**(預設)| 頂天立地 full-height(viewport 左側) | 1 層 = `header`(local toolbar 在 main col 頂)| Linear / Notion / Figma |
+| **`primary-header`** | globalHeader 下方 full-height(扣 globalHeader 高)| **2 層** = `globalHeader`(頂橫跨 viewport)+ `header`(local 在 main col 頂)| GitHub / Slack / Gmail |
+
+**Header 永遠是 horizontal strip,不延伸 vertical**(per 2026-05-19 user clarification)。
+
+### primary-header = primary-sidebar + 一條 global header(2026-05-21 v2 user clarification)
+
+過去版本誤把 primary-header 描述成「header 取代 local toolbar」**錯了** — 世界級 100% 反證:
+- **GitHub**:global top nav(logo / search / account)+ **repo header**(breadcrumb / branch selector,**local**)+ sidebar + content ← **2 層 header**
+- **Slack**:global header(workspace switcher)+ **channel header**(channel name / settings,**local**)+ sidebar + main ← **2 層**
+- **Gmail**:global logo bar + **email list toolbar**(sort / filter,**local**)+ sidebar + list ← **2 層**
+
+**結論**:`primary-header` mode = `primary-sidebar` mode 的所有東西 + **額外一條 global header 在頂**。`header` slot(local toolbar)**仍然存在**,只是上面多了 `globalHeader` slot(跨頁 chrome)。
+
+**API**:
+- `header` prop:**永遠** local page header(per page actions / breadcrumb / filter),兩 mode 都 render
+- `globalHeader` prop:**僅** `primary-header` mode render(account / workspace switcher / search / notifications)
+- `primary-sidebar` mode 傳 `globalHeader` 會被**忽略**(explicit ignore,not error)
+
+### WorkspaceBrand 放置 SSOT(2026-05-21 codify per user directive「globalHeader 存在時 sidebar 內 header 該拿掉」)
+
+| Mode | WorkspaceBrand 放置 | Sidebar 內 SidebarHeader | 對齊 World-class |
+|---|---|---|---|
+| `primary-sidebar` | **Sidebar 頂部**(`<SidebarHeader>` 內)| 有 — 放 WorkspaceBrand | Linear / Notion / Figma file panel(無 global header,workspace 自然在 sidebar 頂) |
+| `primary-header` | **globalHeader 左側**(`<GlobalHeader>` 左 slot,搭配 SidebarTrigger)| **無 / 空 SidebarHeader** | GitHub(repo page sidebar 無 header,org/repo 在 global breadcrumb)/ Gmail(無 workspace brand 在 sidebar)/ Figma file editor(file name 在 global top bar,Layers 面板無 header) |
+
+**Rule:WorkspaceBrand 只能出現一次**(視覺 SSOT)。`primary-header` mode 重複放(同時在 globalHeader + SidebarHeader)= 視覺冗餘 + 跨產品識別混淆 → **禁止**。
+
+**Slack 為 mixed pattern 例外**(thin workspace rail + channels sidebar 有 workspace name)— 不採用此分類,DS 採 **GitHub / Gmail / Figma** 共識(globalHeader 存在 → sidebar 內無 header)。
+
+**Consumer 實作 pattern**:
+```tsx
+// primary-sidebar 派(Linear/Notion):
+<AppShell layout="primary-sidebar"
+  sidebar={<Sidebar><SidebarHeader><WorkspaceBrand /></SidebarHeader>...</Sidebar>}
+  header={<PageHeader title="..." />}>...
+
+// primary-header 派(GitHub/Gmail/Figma):
+<AppShell layout="primary-header"
+  globalHeader={<GlobalHeader>... <WorkspaceBrand /> ...</GlobalHeader>}  {/* brand 在這 */}
+  sidebar={<Sidebar viewportInsetTop="..."> {/* 無 SidebarHeader */} ...</Sidebar>}
+  header={<PageHeader title="..." />}>...
+```
+
+**真正的 distinguishing factor = Header scope(local toolbar vs global bar)**(2026-05-20 user clarification 撤回 single/multi-workspace mis-claim):
+
+過去版本誤把「workspace 數量」綁定到 layout mode(寫 primary-sidebar = single-workspace、primary-header = multi-workspace)。**反證(grep world-class verified)**:
+- Linear / Notion / Figma(primary-sidebar)= 全部都**支援 multi workspace / multi team**
+- GitHub / Gmail / Slack(primary-header)= 同樣是 multi workspace
+- **Workspace 多寡跟 layout 派别無相關性** — Notion 多 workspace 卻用 primary-sidebar、Gmail 多 account 用 primary-header
+
+決定派别的是「Header scope」:
+- **Local toolbar 派**(當前頁 anchor / breadcrumb / page-level actions / filter / 該頁 specific 操作)→ `primary-sidebar`
+- **Global bar 派**(account avatar / workspace switcher / notifications / 跨頁 search / 跨頁導覽)→ `primary-header`
+
+選 mode = 表態「Header 是 local 還是 global」,**不是**「workspace 是 single 還是 multi」。
+
+**Sidebar toggle 按鈕位置**(消費既有 `Sidebar.spec.md:308-360` SidebarTrigger 兩 pattern,**不發明新 toggle**):
+
+| Mode | 對應 Sidebar pattern | Toggle 位置 |
+|---|---|---|
+| `primary-sidebar` | `Sidebar.spec.md` Pattern A(無 global top bar) | 主內容 header 最左 |
+| `primary-header` | `Sidebar.spec.md` Pattern B(有 global top bar) | global top bar 最左 |
+
+**唯一 invariant**(`Sidebar.spec.md:310` 既有):trigger 必在 sidebar 任何 state(offcanvas / icon / expanded)下都可見 — 收合後 sidebar 不見了,toggle 不可能留在 sidebar 內(會跟著消失)。兩 mode 結論都落在 **Header 最左**,只是該 Header 是 local toolbar(Pattern A)還是 global bar(Pattern B)。Consumer 直接 `<SidebarTrigger />` 塞 Header 最左,AppShell 不 wrap / 不發明。
+
+**層級語意差異**:`primary-sidebar` 的 Header scope = local(當前頁);`primary-header` 的 Header scope = global(整 app)。兩者是不同 product 角色,**不互通**。Consumer 選 mode = 表態 product 是哪派。
+
+**Workspace switcher 預設位置**:
+- `primary-sidebar`:sidebar 頂部(對齊 Linear / Notion / Slack)
+- `primary-header`:header 左側(對齊 GitHub / Gmail)
+
+**Breadcrumb 預設位置**:
+- `primary-sidebar`:Header 內(當前頁 anchor,對齊 Linear local header)
+- `primary-header`:Main 頂(對齊 GitHub `<repo>/<dir>/<file>` breadcrumb)
+
+兩者都消費既有 `breadcrumb.spec.md` 視覺 canonical,只是 placement 不同。
+
+---
+
+## Aside 2-mode(對齊 Material 3 standard vs modal drawer canonical)
+
+| Mode | Trigger | Mask 蓋背景? | Background operable? | 佔 layout 寬度? |
+|---|---|---|---|---|
+| **Standard inline**(對齊 Material 3 standard drawer) | viewport ≥ `--sidebar-mobile-breakpoint`(768px) | ❌ 不蓋 | ✅ 可操作 | ✅ 佔 layout |
+| **Modal overlay**(對齊 Material 3 modal drawer = Sheet pattern) | viewport < breakpoint | ✅ 蓋 | ❌ 不可操作 | ❌ 不佔(蓋上去) |
+
+**Standard inline** 行為(layout-mode aware):
+- `primary-sidebar` mode:右側 fix viewport 頂天立地(同 Sidebar 對稱)
+- `primary-header` mode:右側 fix 在 **Header 下方**(不 underlap header,跟 sidebar 同高 — 都從 header 底邊起)
+- Width consumer 自傳 `width` prop(`number` 或 `{ md, xl }` breakpoint-keyed),DS 不發明 width token,**clamp `min-width: 240` / `max-width: 640`** 避免過窄無法閱讀 / 過寬擠 main
+- 跟 main 共享 layout space(main width = viewport - sidebar - aside)
+- **Scroll ownership**:Aside 自帶 scroll(`overflow-y: auto` + `min-h-0`,per Atlassian Layout 慣例),main 自帶 scroll,**禁止** body-level scroll
+
+**Modal overlay** 行為:
+- 消費既有 `sheet.spec.md` canonical(從右滑出 + Esc 關 + click-outside 關 + focus trap + restore focus)
+- **title prop required**(per `sheet.spec.md:98` 禁無 title — `aria-labelledby` 強制)
+- 跟 Sidebar mobile fallback 同 SSOT
+
+**Breakpoint**:消費既有 `--sidebar-mobile-breakpoint`(`sidebar.spec.md:594` SSOT,768px),**不發明新 breakpoint**。Sidebar + Aside 同步切 Sheet。
+
+---
+
+## Mobile(viewport < breakpoint)
+
+- **Sidebar**:消費既有 `sidebar.spec.md:594` canonical(自動切 Sheet,從左滑出,寬度 `--sidebar-width-mobile`)
+- **Aside**:同邏輯,切右 Sheet(複用 Sheet primitive,只方向相反)
+- **Header**:始終可見(both mode);`primary-sidebar` 仍是 local toolbar / `primary-header` 仍是 global bar
+- **AppShell 不重新發明 mobile**,沿用 Sidebar / Sheet 既有 canonical
+
+---
+
+## Main slot
+
+**`<main>` landmark + padding=0**。AppShell.Main 是空殼 layout primitive,**不發明任何內距規則**。
+
+Main 內塞什麼(table / field / card / page header / list)的 layout + spacing → **完全遵循 `layoutSpace.spec.md` 既有 6 條規則 + 親疏 3 級**:
+- 規則 1:水平 padding(3 patterns 並存 — bounded surface 自帶 / 純 layout 父層管 / list item 自帶)
+- 規則 2:頂部(Header → 第一個元素的 gap)
+- 規則 3:元素間 gap(只看親疏)
+- 規則 6:Chrome 表面水平 padding 統一 `loose`
+
+**禁止**:AppShell.Main 強制 padding(會跟內部 DataTable / naked list 衝突 + 違反規則 1B「純 layout primitive 無邊界 → 父層管」)。
+
+**Consumer examples**(per codex Layer B 建議補):
+- Page header(`<DashboardHeader>` 類自帶 `px-loose` chrome)→ 直接 mount(規則 1A)
+- Card / Panel(自帶 border + bg)→ wrap consumer 自加 `px-loose` 父層(規則 1B)
+- DataTable(naked structure)→ consumer wrap `<div className="px-[var(--layout-space-loose)]">` 父層管(規則 1B)
+- naked list(`.map()` 不包 wrapper)→ 每 item 自帶 `px-loose`(規則 1C)
+
+**Scroll ownership**(per Atlassian Layout 慣例):
+- Main 自帶 scroll(`overflow-y: auto` + `min-h-0`),Aside / Sidebar 各自帶 scroll
+- **禁止** body-level scroll(雙 scrollbar bug),AppShell root `overflow: hidden`
+
+---
+
+## Dialog / Sheet / Popover 互動(per user Q7 — 不是 AppShell scope)
+
+- 所有 modal overlay(Dialog / Sheet / Popover / HoverCard)消費既有 `overlay-surface.spec.md` SSOT
+- Mask 蓋整個 AppShell(包含 sidebar + header + aside + main)
+- Z-index:AppShell base = 100(對齊 Mantine default);overlay 走既有 **`z-50` Tailwind utility**(`Sheet.tsx:53/69` SSOT canonical,**不發明 `--z-overlay` token** — repo 內無此 token,Sheet 直接 `z-50`)
+- AppShell **不** export `modalOpen` prop,overlay 自管 open / close state
+
+---
+
+## Keyboard shortcuts(消費既有 Sidebar SSOT)
+
+| Shortcut | Action | Cite |
+|---|---|---|
+| **`⌘B`(macOS)/ `Ctrl+B`(Windows)** | Toggle sidebar | `sidebar.spec.md:348` SSOT「industry-standard,已內建,不該改」;`sidebar.tsx:62` code key `"b"` |
+| **`⌘.`(macOS)/ `Ctrl+.`(Windows)** | Toggle aside | Linear convention(新加) |
+| **Skip-to-main link** | `Tab` 第一站 focus 「Skip to content」link → `main` | A11y WCAG 2.4.1 bypass blocks;對齊 Atlassian Layout skip-link |
+
+兩者消費既有 Sidebar keyboard shortcut 機制(`useEffect` + `document.addEventListener('keydown')`),AppShell 不發明新機制。
+
+---
+
+## A11y landmark(對齊 W3C ARIA in HTML + Mantine 慣例)
+
+| Slot | HTML landmark | Auto ARIA |
+|---|---|---|
+| `header`(`primary-header` mode) | `<header>` 直接 viewport child → **`role="banner"`** implicit(global banner) | site-wide |
+| `header`(`primary-sidebar` mode) | `<header>` 在 `<main>` descendant → **不是 banner**,是 local toolbar | per W3C ARIA in HTML spec:`<header>` 只有不在 `main/nav/section` descendant 才是 banner |
+| `sidebar` | `<nav aria-label="Primary navigation">` | Sidebar own |
+| `aside` | `<aside aria-label={title}>` | title required(modal mode `aria-labelledby` 強制) |
+| `children`(main) | `<main>` | `role="main"`(implicit)+ skip-to-main 跳轉 anchor |
+
+**W3C ARIA in HTML banner rule(精準 quote)**:`<header>` element 在 `<body>` direct context = `role="banner"` implicit;若 `<header>` 是 `<main>` / `<nav>` / `<article>` / `<section>` / `<aside>` descendant,則 **NOT** banner role(W3C HTML AAM spec)。
+
+**本 AppShell 對應落實**:
+- `primary-header` mode:`<header>` 直接 `<body>` descendant(AppShell root flex-col 第一個 child)→ implicit banner role ✓
+- `primary-sidebar` mode:header 包在 `<div>`(main column 內,跟 `<main>` 是 sibling 非 descendant)→ ChromeHeader 本身是 `<div>` 元件,因此**沒有 banner role 觸發**。屬 local toolbar 語意。
+
+不發明新 ARIA,消費 HTML5 semantic + WAI-ARIA Landmark 標準 + W3C ARIA in HTML banner rule。
+
+不發明新 ARIA,消費 HTML5 semantic + WAI-ARIA Landmark 標準 + W3C ARIA in HTML banner rule。
+
+---
+
+## Future extension(目前不定義)
+
+**Multi-sidebar**(Notion / Linear 雙側欄派):API 接 `sidebar?: ReactNode | ReactNode[]` 預留 array signature,**目前 strict 取首位**,違反 dev warning。未來擴充 SSOT 在 `Sidebar.spec.md`,不在本 pattern(per user 2026-05-19「AppShell 不該 customize Sidebar」)。
+
+**Footer**:不 expose slot(per user 2026-05-19「不用 footer」)。Web service 通常不用 footer,consumer 若需要自貼 Main 底。
+
+**Banner / announcement bar**:不 expose slot,consumer 自貼 Main 頂(對齊 Notion / Linear banner consumer-managed convention)。
+
+**Multi-tab / split view**:不 codify(per user 2026-05-19「不用」)。
+
+**Print mode**:`@media print` 隱 sidebar + aside,只露 main(future)。
+
+---
+
+## Token consumption(0 新發明,全消費既有 SSOT)
+
+| 用途 | Consume token / SSOT |
+|---|---|
+| Mobile breakpoint | `--sidebar-mobile-breakpoint`(`sidebar.spec.md:594`)|
+| Sidebar width | `--sidebar-width`(`sidebar.spec.md`)|
+| Header height | `--chrome-header-height`(`tokens/uiSize/uiSize.spec.md`)|
+| Aside width | consumer 自傳 prop(無 token)|
+| Layout spacing | `layoutSpace` 全 family(`--layout-space-{tight,loose,bottom}`)|
+| Z-index | `--z-overlay`(既有)/ AppShell base z=100 |
+| Sheet fallback | `sheet.spec.md` SSOT |
+| Overlay | `overlay-surface.spec.md` SSOT |
+
+**0 新 CSS variable**,per CLAUDE.md token 4 條硬規則(不孤立發明)。
+
+---
+
+## Consumer 紀律
+
+- ❌ 禁:`<AppShell>` 內 wrap 第二個 `<AppShell>`(nested shell 違反「整頁框架」單例性)
+- ❌ 禁:`sidebar={<div>...</div>}`(必傳 `<Sidebar>` primitive,確保視覺 SSOT)
+- ❌ 禁:`header={<header>...</header>}`(必傳 `<ChromeHeader>` 或消費 `header-canonical` 派生 header)
+- ❌ 禁:AppShell.Main 自加 padding(違反 layoutSpace 規則 1B)
+- ✅ 必:`layout` mode 在 product 啟動時固定,**不在 runtime 切換**(切換 = product 角色變動 = 應該重 mount app)
+
+---
+
+## 世界級對照
+
+| DS | Slot 結構 | Layout mode | Aside 派 | Mobile |
+|---|---|---|---|---|
+| **Mantine AppShell** | Header / Navbar / Aside / Footer / Main | `default`(header 頂)/ `alt`(navbar 頂)| collapsable | breakpoint per slot |
+| **Ant Layout** | Header / Sider / Content / Footer | 拼 building blocks 兩派並存 | 無 explicit Aside slot | Sider breakpoint |
+| **Material 3** | (無 AppShell primitive)| — | Standard inline / Modal overlay drawer | Standard → desktop / Modal → mobile |
+| **Atlassian Navigation System** | TopNav + SideNav + Layout(Beta) | TopNav-above-SideNav | — | — |
+| **本 DS AppShell** | sidebar + header + aside + main(無 footer 預設)| `primary-sidebar` / `primary-header` 對齊 Mantine 2 mode | Standard inline + Modal overlay 對齊 Material 3 | 消費既有 Sidebar / Sheet SSOT |
+
+---
+
+## 相關 spec(per codex Layer B 比稿修正 path/case)
+
+- `components/Sidebar/sidebar.spec.md` — sidebar 視覺 + 鍵盤 + mobile + SidebarTrigger Pattern A/B SSOT(本 pattern 必消費)
+- `patterns/header-canonical/header-canonical.spec.md` — header 視覺契約 SSOT
+- `patterns/overlay-surface/overlay-surface.spec.md` — Aside modal mode 上層 SSOT
+- `components/Sheet/sheet.spec.md` — modal fallback SSOT(`aria-labelledby` 強制 + `z-50`)
+- `tokens/layoutSpace/layoutSpace.spec.md` — Main 內 layout 6 條規則 SSOT
+- `tokens/uiSize/uiSize.spec.md` — `--chrome-header-height` / `--sidebar-mobile-breakpoint` 等 size token
+

package/src/components/AspectRatio/aspect-ratio.spec.md

@@ -0,0 +1,134 @@
+---
+component: AspectRatio
+family: self-contained
+variants: {}
+sizes: {}
+traits:
+  - isMatrixHeavy
+benchmark:
+  - Radix AspectRatio primitive: github.com/radix-ui/primitives/tree/main/packages/react/aspect-ratio
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# AspectRatio 設計原則
+
+## 定位
+
+AspectRatio 是**固定長寬比容器** primitive——確保內部 children(通常是 image / video / illustration)永遠保持指定 ratio,避免未載入時容器坍塌或 content-fit 造成的位移。
+
+**實作基礎**:`@radix-ui/react-aspect-ratio` 薄包裝。Radix 用 SSR-safe padding-bottom 方案實作,consistent 跨瀏覽器。
+
+**Layout Family**:非上述 family — self-contained primitive(container 型 layout,無 slot 結構,只暴露 `ratio` 數值 + children)。
+
+**世界級對照**:
+- shadcn `AspectRatio`(本元件主要參考)— 同 Radix 薄包裝 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- Ant Design 無獨立元件(用 CSS aspect-ratio 或自訂 padding-bottom)
+- Material 無獨立元件(image/Card 元件內建 props)
+
+---
+
+## 何時用
+
+- **圖片容器未載入前防坍塌**:圖片 src 還沒 ready 時,容器高度若為 0 → 頁面 layout 跳動(CLS 問題)。AspectRatio 鎖死比例
+- **Coachmark / Tour media 區**:onboarding 截圖 / illustration 統一 ratio
+- **Carousel item 圖像**:輪播各張圖保持一致高度
+- **Card thumbnail**(未來):product card / blog post cover
+- **Chart / 圖表 preview**:dashboard 卡片內 chart 容器
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| content 高度需隨內容變 | 不包 AspectRatio | AspectRatio 鎖死,無法 hug content |
+| 圖片已固定 width + height 屬性 | 直接 `<img>` 即可 | AspectRatio 是給 responsive(width 100%)場景 |
+| Flex/Grid 子元素高度由父層控 | 不包 | 父層已規定高度,包 AspectRatio 多餘 |
+
+## 近親元件分界
+
+| vs | 差異軸 | 何時用 AspectRatio |
+|---|---|---|
+| **Card / 自訂 wrapper** | AspectRatio 鎖比例(寬→高);Card 一般 hug content | 需要保證 width:height 固定比 |
+| **Skeleton** | Skeleton 是 loading placeholder + 預設尺寸;AspectRatio 是 ratio container | 內含 image / chart 等需保 ratio 的 ready content |
+| **Empty(image slot)** | Empty 是 page-state 元件;AspectRatio 是 layout primitive | 結構性 ratio 鎖,跟 content state 無關 |
+
+對齊 Radix AspectRatio / Material `<Box sx={{aspectRatio}}>` / Polaris MediaCard primitive 慣例:純結構 layout 元件。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## DS 標準 ratio(慣例)
+
+| Ratio | 用途 |
+|-------|------|
+| `16/9`(寬螢幕) | onboarding / tour 截圖(Coachmark 預設)、video embed、hero banner |
+| `4/3`(傳統) | 產品照片、screenshot |
+| `1/1`(方形) | Avatar、icon preview、Instagram-style 貼文 |
+| `3/4`(直式) | 人物 portrait 照、手機截圖 |
+| `21/9`(ultrawide) | hero section banner、movie poster |
+
+**數值計算**:consumer 傳 `ratio={16/9}`(= 1.7777...),Radix 內部自動 padding-bottom `56.25%`。
+
+---
+
+## Consumer 範例
+
+```tsx
+import { AspectRatio } from '@/design-system/components/AspectRatio/aspect-ratio'
+
+<AspectRatio ratio={16 / 9} className="bg-muted rounded-lg overflow-hidden">
+  <img src={url} alt="..." className="w-full h-full object-cover" />
+</AspectRatio>
+```
+
+children 通常要 `className="w-full h-full object-cover"` 讓圖填滿容器;否則留空間。
+
+---
+
+## 禁止事項
+
+- ❌ **不用 AspectRatio 做 flex/grid layout**(它是 container 鎖比例,不是佈局)
+- ❌ **不在 AspectRatio 內放不該鎖比例的 content**(文字 / form / button — 這些應隨內容高)
+- ❌ **不重疊多層 AspectRatio**(意義不明,比例衝突)
+
+---
+
+## 為何無 ColorMatrix / SizeMatrix / StateBehavior
+
+AspectRatio 是 pure layout primitive(container 鎖比例),本身:
+
+- **無 color token**:自身不帶任何色彩,背景色由 consumer 透過 className 決定(慣例 `bg-muted` 作 image placeholder)。故不建立 `ColorMatrix`——色彩決策屬 consumer。
+- **無 size prop**:寬度由 parent / className 控制,高度由 `ratio` 公式自動推導(`height = width / ratio`)。因此不提供 sm/md/lg size variant,不同尺寸透過外層容器寬度達成。故不建立 `SizeMatrix`——元件特有視覺對照改為 `StandardRatios`(DS 慣用 5 種 ratio)。
+- **無互動狀態**:無 hover / focus / active / selected / disabled(非互動元件,純 structural container)。故不建立 `StateBehavior`。
+
+對應 anatomy story:保留 `Overview` + `Inspector`(ratio 切換互動)+ 元件特有 `StandardRatios`。
+
+---
+
+## A11y 預設
+
+元件本身不引入 a11y 干預,consumer 對 children(如 img)負責 `alt` / `aria-label`。
+
+---
+
+## shadcn passthrough 例外說明
+
+AspectRatio export 為 `const AspectRatio = AspectRatioPrimitive.Root`(**直接 re-export Radix primitive,無額外 wrapper**),不套 `React.forwardRef` / `displayName` / `...props` spread / `asChild` 的 shadcn canonical 五件套。
+
+**為什麼豁免**:Radix `AspectRatioPrimitive.Root` 本身已實作這五件套(forwardRef-ed / displayName 為 `"AspectRatio"` / `...props` 內部 spread 至 inner `<div>` / asChild 透過 Slot 支援)。在我們自己 wrap 一層只會 indirection 不加值,且會 **break** Radix 內建的 displayName / Slot 支援。這是 shadcn-official 模式(shadcn 元件庫的 AspectRatio 也是直接 re-export),非 drift。
+
+**何時需要自己 wrap**:若未來要加預設 className / 自訂 ratio 常數 / 內建 consumer 視覺 guard(如強制 border-radius),再 wrap。目前無此需求。
+
+---
+
+## 相關
+
+- `../Coachmark/coachmark.spec.md` — **本元件 consumer**:media 區預設 `mediaRatio=16/9`
+- `../Carousel/carousel.spec.md` — 未來 consumer(item image 統一 ratio)
+- Radix AspectRatio — `@radix-ui/react-aspect-ratio`
+- shadcn AspectRatio — 參考實作 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `file-viewer.spec.md`