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

package/src/components/AppShell/app-shell.principles.stories.tsx

@@ -0,0 +1,140 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — 產品架構參照(Linear / Notion / Figma / GitHub / Slack / Gmail 等)為 usage 觀察,非逐句 URL-cited;視為 unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import type { Meta, StoryObj } from '@storybook/react'
+import LinkTo from '@storybook/addon-links/react'
+
+const meta: Meta = {
+  title: 'Design System/Components/AppShell/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+export const UsageGuidance: Story = {
+  name: '使用準則',
+  render: () => (
+    <div className="prose max-w-2xl space-y-6 px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]">
+      <section>
+        <h2 className="text-h4 mb-2">何時用 AppShell</h2>
+        <ul className="text-body space-y-2">
+          <li>
+            • 多頁 web service 的主結構——Linear / Notion / Slack / GitHub / Asana 這類「左側導覽 + 中央工作區」產品。完整組合見{' '}
+            <LinkTo kind="Design System/Components/AppShell/展示" name="主側欄佈局 — Linear 式議題追蹤"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">展示 → 主側欄佈局 — Linear 式議題追蹤</span></LinkTo>
+          </li>
+          <li>
+            • 需要 sidebar + main 持續共存——在議題列表、看板、報表等頁面間切換時,左側導覽不重渲染、捲動位置不丟失。見{' '}
+            <LinkTo kind="Design System/Components/AppShell/展示" name="主側欄佈局 + 頁面分頁"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">展示 → 主側欄佈局 + 頁面分頁</span></LinkTo>
+          </li>
+          <li>
+            • 需要右側詳情面板(議題詳情 / inspector / 成員資料)跟 main 並存——如 Linear 點選議題後右側展開詳情。開合行為見{' '}
+            <LinkTo kind="Design System/Components/AppShell/設計規格" name="狀態行為"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">設計規格 → 狀態行為(右側面板開合)</span></LinkTo>
+          </li>
+        </ul>
+      </section>
+
+      <section>
+        <h2 className="text-h4 mb-2">何時不用</h2>
+        <ul className="text-body space-y-1">
+          <li>• 單頁 landing / marketing site(產品官網、定價頁)→ `&lt;main&gt;` 直接展開,沒導覽不需要 shell</li>
+          <li>• Auth 頁(login / signup)→ 自寫置中 layout,不被 sidebar 佔位</li>
+          <li>• Embedded widget / iframe(嵌進別人頁面的客服小視窗類)→ 已被 host shell 包住</li>
+          <li>• 文件 reader(全螢幕閱讀)→ shell chrome 干擾閱讀</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2 className="text-h4 mb-2">Layout mode 怎麼選</h2>
+        <p className="text-body">
+          兩種佈局模式(primary-sidebar / primary-header)的選型決策樹獨立成「佈局模式怎麼選」story(含
+          WorkspaceBrand 放置規則),見本頁側欄或{' '}
+          <LinkTo kind="Design System/Components/AppShell/設計原則" name="佈局模式怎麼選"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">設計原則 → 佈局模式怎麼選</span></LinkTo>
+        </p>
+      </section>
+
+      <section>
+        <h2 className="text-h4 mb-2">vs Sidebar 規則</h2>
+        <p className="text-body">
+          AppShell 只負責整體組合、版面模式、以及右側面板的響應式開合。Sidebar 的外觀、行為、行動裝置上的
+          抽屜形式都由 Sidebar 元件自己定義,<strong>AppShell 不會去改 Sidebar 的樣式</strong>。
+          多個 sidebar 的情境要等 Sidebar 元件本身支援後才提供。
+        </p>
+      </section>
+
+      <section>
+        <h2 className="text-h4 mb-2">Consumer 紀律</h2>
+        <ul className="text-body space-y-1">
+          <li>❌ 禁:`&lt;AppShell&gt;` 內塞另一個 `&lt;AppShell&gt;`(整頁框架只能有一個)</li>
+          <li>❌ 禁:`sidebar` 傳裸 `&lt;div&gt;` → 必傳 `&lt;Sidebar&gt;`,才能維持一致的展開／收合、行動裝置抽屜、鍵盤操作與視覺;傳其他容器雖然型別過得了,卻會失去這些導覽行為</li>
+          <li>❌ 禁:`header` 傳裸 `&lt;header&gt;` → 應傳 `&lt;ChromeHeader&gt;`(或沿用同一套標準標頭結構自訂),才能得到一致的標頭高度、內距與對齊</li>
+          <li>❌ 禁:硬性撐開 Main 區域的內距 → Main 本身不加留白,由內容自己決定(自帶邊框的卡片、資料表各自帶內距)</li>
+          <li>✅ 必:Main 內容的間距沿用既有版面間距原則——頁面標頭、卡片、資料表、純列表各按對應規則處理</li>
+        </ul>
+      </section>
+    </div>
+  ),
+}
+
+// 佈局模式選型 deep-dive — 內容錨定 app-shell.spec.md 的「Layout mode 兩 mode 差異」+「WorkspaceBrand 放置 SSOT」
+// +「帳號入口(Account entry)放置 SSOT」段(均含 Responsive 精修子句;用段名錨定不寫死行號避免 drift)。
+// category-templates.md component-specific `{Topic}Rule` idiom
+export const LayoutModeRule: Story = {
+  name: '佈局模式怎麼選',
+  render: () => (
+    <div className="prose max-w-2xl space-y-6 px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]">
+      <section>
+        <h2 className="text-h4 mb-2">唯一判準:頂部標頭服務的範圍</h2>
+        <p className="text-body mb-2">
+          唯一的區分標準 = <strong>頂部標頭服務的是「目前這一頁」還是「整個產品」</strong>,
+          <em>不是</em>工作區(workspace)的數量多寡(Notion / Gmail 都支援多工作區,卻分屬不同派)。
+          問自己:頂部那條標頭列服務的是當前頁面,還是整個產品?
+        </p>
+        <ul className="text-body space-y-1">
+          <li>
+            <strong>primary-sidebar</strong>:頂部是<strong>服務當前頁的工具列</strong> —
+            放麵包屑、頁面層級操作、篩選。Sidebar 頂天立地,工作區品牌(`WorkspaceBrand`)放在 sidebar 頂。
+            參考 Linear / Notion / Figma。
+          </li>
+          <li>
+            <strong>primary-header</strong>:多一條<strong>橫跨頂部、服務整個產品的全域標頭</strong> —
+            放帳號、工作區切換、跨頁搜尋、通知;服務當前頁的工具列
+            <em>仍在</em>主欄頂部,只是上面多了這條全域標頭。工作區品牌改放全域標頭(`globalHeader`)左側。
+            參考 GitHub / Slack / Gmail。完整組合見{' '}
+            <LinkTo kind="Design System/Components/AppShell/展示" name="主標頭佈局 — 全域+本地兩層(GitHub/Gmail/Slack 派)"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">展示 → 主標頭佈局 — 全域+本地兩層</span></LinkTo>
+          </li>
+        </ul>
+        <p className="text-caption text-fg-secondary mt-2">
+          兩種模式是產品的角色定位——啟動時就固定,不該在執行期切換。視覺對照圖見{' '}
+          <LinkTo kind="Design System/Components/AppShell/設計規格" name="兩種布局模式對照圖"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">設計規格 → 兩種布局模式對照圖</span></LinkTo>
+        </p>
+      </section>
+
+      <section>
+        <h2 className="text-h4 mb-2">常見誤解:全域標頭會取代當前頁工具列</h2>
+        <p className="text-body">
+          錯。primary-header = primary-sidebar 的所有東西 + <strong>額外一條</strong>全域標頭在頂;
+          當前頁工具列(`header` slot)<strong>仍然存在</strong>。GitHub / Slack / Gmail 全部同時保有兩層,
+          不是二選一。
+        </p>
+      </section>
+
+      <section>
+        <h2 className="text-h4 mb-2">WorkspaceBrand 跟著 mode 走(只能出現一次)</h2>
+        <ul className="text-body space-y-1">
+          <li>• <strong>primary-sidebar</strong>:WorkspaceBrand 放 Sidebar 頂部(`&lt;SidebarHeader&gt;` 內)— Linear / Notion / Figma file panel</li>
+          <li>• <strong>primary-header</strong>:WorkspaceBrand 改放 globalHeader 左側(搭配 SidebarTrigger),SidebarHeader 留空 — GitHub / Gmail / Figma file editor</li>
+          <li>❌ 禁:`primary-header` mode 同時在 globalHeader + SidebarHeader 各放一份 = 視覺冗餘 + 跨產品識別混淆(WorkspaceBrand 視覺 SSOT,只能出現一次)</li>
+        </ul>
+      </section>
+
+      <section>
+        <h2 className="text-h4 mb-2">帳號入口(個人設定)跟著 mode 走(只能出現一次)</h2>
+        <ul className="text-body space-y-1">
+          <li>• <strong>primary-sidebar</strong>:帳號 / 個人設定放 Sidebar 底部(`&lt;SidebarFooter&gt;`)— Linear / Notion / Figma</li>
+          <li>• <strong>primary-header</strong>:帳號入口改放 globalHeader 右側 avatar(品牌左、帳號右,左右對稱),sidebar 不放帳號頁尾 — GitHub / Gmail / Slack 帳號一律在全域標頭右上</li>
+          <li>• 開「個人資料 / 設定 / 登出」帳號選單(`&lt;DropdownMenu&gt;`),<strong>不用 ProfileCard</strong>(ProfileCard 是看別人的人員卡,預設動作 Chat/通話用在自己身上不對)</li>
+          <li>• 帳號 avatar = 24px,跟左側品牌 avatar 同尺寸(沿用標準標頭的頭像尺寸規範);右側邊距與品牌距分割線對稱</li>
+          <li>❌ 禁:`primary-header` mode 同時在 globalHeader + sidebar footer 各放一份 = 入口混淆(帳號入口視覺 SSOT,只能出現一次)</li>
+        </ul>
+      </section>
+    </div>
+  ),
+}

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

@@ -1,5 +1,9 @@
 ---
-pattern: app-shell
+component: AppShell
+family: composite  # 組合 sidebar+header+main+aside,非 Family 1-4 row element
+variants: {}  # layout 是頁面結構 mode,非視覺 variant 軸
+sizes: {}  # shell 尺寸由 slots / responsive layout 自管,無 component size 軸
+traits: []  # page-level layout composite,slots 全 ReactNode 組合,無 trait variants(R3 trait enforce 無適用項;2026-07-04 dim 29 補宣告)
 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
@@ -10,7 +14,6 @@ benchmark:
   - 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 設計原則
 
@@ -24,7 +27,8 @@ benchmark:
 
 **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 條規則)
+- **邊界狀態**:layout 殼,無自身互動狀態(disabled / loading / empty 不適用,slot 內容各自管;dark / density 隨 theme subtree);overlay open state 自管(見「Dialog / Sheet / Popover 互動」段)
+- **不 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)。
 
@@ -56,13 +60,17 @@ benchmark:
   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)
+  aside={<AppShellAside title="Detail">...</AppShellAside>}   // 本 composite 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`)。
+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`「禁止事項」(無 title → aria-labelledby 強制))。
+
+**Aside body padding(內容自帶,刻意 Pattern B)**:`<AppShellAside>` 的 body(ScrollArea 內)**不自帶 px/py**,由 consumer 塞入的 children 自行負責留白(對齊 `layoutSpace.spec.md` 規則 1B「父層/內容管 padding」的裸結構路線,同 Table / DataTable)。**理由**:aside 內容異質(清單需 hover 貼邊滿版、表格需 flush、表單才需 padding),框架統一加 padding 反而破壞清單/表格。與 Dialog / Sheet body 自帶 `px-loose py-tight` 的差異是**刻意**的(那兩者內容較單一)。consumer 放需留白的內容時,自帶 `px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]`(範例 `app-shell.stories.tsx` 即如此)。
+
+**Aside 開關控制(刻意單向,2026-07-17 user 拍板)**:`asideOpen` / `onAsideOpenChange` 提供完整 **controlled** 路徑;uncontrolled fallback 初值**刻意固定關閉**(`useState(false)`),**不提供 `defaultAsideOpen`**。理由:側邊詳情面板實務上幾乎一定由 app 的 route / 選取狀態驅動(modal mode 更明文要求 controlled),初值固定關閉是合理預設,額外加 `defaultAsideOpen` 偏 YAGNI。對齊 Dim 26 dual-mode canonical 的「刻意單一模式 → 補 rationale」例外機制。未來真有 uncontrolled 初值需求再加(additive,不破壞)。
 
 ### Hook export:`useAppShell()`(2026-05-21 D2 codify per Phase B codex catch)
 
@@ -79,7 +87,7 @@ function CustomAside() {
 
 **Contract**:
 - 必在 `<AppShell>` 子樹內 call,否則 throw(consumer 拼 layout 必 wrap AppShell context)
-- 回傳:`{ asideOpen: boolean, setAsideOpen: (open: boolean) => void, isMobile: boolean }`
+- 回傳:`{ layout: 'primary-sidebar' | 'primary-header', asideOpen: boolean, setAsideOpen: (open: boolean) => void, isMobile: boolean }`(hook 回傳整個 context,consumer 拼 custom layout 可讀當前 `layout` mode)
 - 設計目的:給跳出 `<AppShellAside>` 預設 sub-component 框架的 consumer 用(rare),DS 預設仍建議走 `<AppShellAside>` slot
 
 ---
@@ -93,14 +101,14 @@ function CustomAside() {
 
 **Header 永遠是 horizontal strip,不延伸 vertical**(per 2026-05-19 user clarification)。
 
-### primary-header = primary-sidebar + 一條 global header(2026-05-21 v2 user clarification)
+### primary-header = primary-sidebar + 一條 global header
 
-過去版本誤把 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)。世界級對照(皆為 2 層 header):
+- **GitHub**:global top nav(logo / search / account)+ **repo header**(breadcrumb / branch selector,**local**)+ sidebar + content
+- **Slack**:global header(workspace switcher)+ **channel header**(channel name / settings,**local**)+ sidebar + main
+- **Gmail**:global logo bar + **email list toolbar**(sort / filter,**local**)+ sidebar + list
 
-**結論**:`primary-header` mode = `primary-sidebar` mode 的所有東西 + **額外一條 global header 在頂**。`header` slot(local toolbar)**仍然存在**,只是上面多了 `globalHeader` slot(跨頁 chrome)。
+**常見誤解:「primary-header = header 取代 local toolbar」** — 錯;global header 是**加在 local toolbar 之上**,不是取代(上列三家全部同時保有兩層)。
 
 **API**:
 - `header` prop:**永遠** local page header(per page actions / breadcrumb / filter),兩 mode 都 render
@@ -116,6 +124,8 @@ function CustomAside() {
 
 **Rule:WorkspaceBrand 只能出現一次**(視覺 SSOT)。`primary-header` mode 重複放(同時在 globalHeader + SidebarHeader)= 視覺冗餘 + 跨產品識別混淆 → **禁止**。
 
+**Responsive 精修(mobile-Sheet 子句,2026-06-18)**:「只能出現一次」= **同一時間一次,「一次」per breakpoint 判定**。Desktop(≥768px)brand 在 globalHeader、sidebar 內無 SidebarHeader。Mobile(<768px)sidebar 收成 Sheet(`sidebar.tsx` mobile 分支,z-50)打開時**蓋住 globalHeader** → brand 看不到、drawer 變孤兒 → 此時在 Sheet 內補 `<SidebarHeader><WorkspaceBrand/>`(globalHeader 既被蓋住,仍「同一時間一次」,非重複)。機制:consumer 讀既有 `useSidebar().isMobile`,mobile 才條件渲染**同一組 primitive**(style SSOT,與 primary-sidebar 外觀一致,非手刻對齊)。Reference:`_demo-helpers.tsx` `AcmeSidebar`(`includeWorkspaceBrand || isMobile`)。**禁止**:desktop primary-header 同時 globalHeader + SidebarHeader 放 brand(那才是真重複)。對齊 Material modal navigation drawer(手機 drawer 從 top app bar 開、蓋住內容、頂放品牌)+ Gmail / GitHub mobile 選單。
+
 **Slack 為 mixed pattern 例外**(thin workspace rail + channels sidebar 有 workspace name)— 不採用此分類,DS 採 **GitHub / Gmail / Figma** 共識(globalHeader 存在 → sidebar 內無 header)。
 
 **Consumer 實作 pattern**:
@@ -132,27 +142,46 @@ function CustomAside() {
   header={<PageHeader title="..." />}>...
 ```
 
-**真正的 distinguishing factor = Header scope(local toolbar vs global bar)**(2026-05-20 user clarification 撤回 single/multi-workspace mis-claim):
+### 帳號入口(Account entry)放置 SSOT(2026-06-17 codify per user directive「primary-header 不該把個人設定放 sidebar footer,該放主標頭右側 avatar」)
+
+「帳號 / 個人設定入口」(目前使用者的 avatar,點開 = 帳號選單)放置同樣 **mode-dependent**,鏡像上方 WorkspaceBrand 規則:
+
+| Mode | 帳號入口放置 | Sidebar footer | 對齊 World-class |
+|---|---|---|---|
+| `primary-sidebar` | **Sidebar 底部**(`<SidebarFooter>` 內,當前使用者)| 有 — 放使用者 | Linear / Notion / Figma(無 global header,帳號自然在 sidebar 底)|
+| `primary-header` | **globalHeader 右側**(trailing slot,品牌在左、帳號在右)| **無 / 空** | GitHub / Gmail / Slack(帳號 avatar 一律在 global top bar 右上)|
+
+**Rule:帳號入口只能出現一次**(視覺 SSOT,同 WorkspaceBrand)。`primary-header` mode 同時放(globalHeader 右 + sidebar footer)= 視覺冗餘 + 入口混淆 → **禁止**;`primary-header` 的 sidebar **不放** user footer(與上方「globalHeader 存在 → sidebar 不重複 chrome 角色」同源邏輯)。
+
+**機械強制(2026-07-30 codify per WM F9 layer 3「無機械攔」)**:consumer 層 `packages/design-system/ds-canonical/hooks/check_consumer_code_quality.sh`(GOV-CONSUMER-QUALITY-001,fork corpus 隨附)兩段互補 — (a) 既有 primary-header 段:檔內宣告 `layout="primary-header"` + `<SidebarFooter>` → BLOCK;(b) 帳號入口 duplicate 段:mode 字面不在檔內時,SidebarHeader block 帳號選單簽名(AccountMenu / DropdownMenuTrigger+Avatar+account 語彙)與 SidebarFooter user 區同檔並存 → BLOCK(escape `@account-entry-allow: <rationale>`)。story 層 early-warn = `story-baseline-registry.json#sidebar-handbuilt-account-trigger`。跨檔組合(layout 宣告與 sidebar 分檔)機械不可及 → 歸 `/product-ui-audit` judgment。
 
-過去版本誤把「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
+**Responsive 精修(mobile-Sheet 子句,per breakpoint;2026-06-18 修正為「鏡像自己桌面的帳號家」)**:mobile(<768px)sidebar 收成 Sheet 蓋住 globalHeader(桌面帳號入口也在 globalHeader 右)→ **帳號入口鏡像桌面位置搬進 Sheet header 右**:在 `<SidebarHeader>` 內放 `<WorkspaceBrand/>`(左)+ `flex-1` + `<AccountMenu/>`(右)= 把整條 globalHeader 原封搬進 Sheet 頂排(SidebarHeader 即 ChromeHeader 基底,與 GlobalHeader 同 primitive → 帳號 avatar 24px + 右緣距 `--layout-space-loose` 由 construction 保證,**非手刻對齊**)。**不在 Sheet 底放 `<SidebarFooter>`**(footer 是 primary-sidebar 的帳號家慣例;primary-header 任何 breakpoint 帳號家都在 header 區)。Consumer 讀 `useSidebar().isMobile` + `useAppShell().layout`(`headerHasAccount = layout === 'primary-header' && isMobile`),desktop 維持無 header/footer。對齊 Material modal navigation drawer 官方「account switcher 放 drawer header 區(與 logo 同區、pinned、最高優先),footer 區放 settings/support 次要項」(<https://m3.material.io/components/navigation-drawer>)+ Gmail / GitHub mobile 選單頂部帳號慣例。**為何不放 footer**:使用者開 Sheet 看到的頂排 = 原本被蓋住的 top bar(brand 左 / 帳號右),空間記憶不斷;把帳號丟到 footer = 誤套 primary-sidebar 慣例(那 mode 桌面帳號本就在底)。Reference:`_demo-helpers.tsx` `AcmeSidebar`。
 
-決定派别的是「Header scope」:
+**為什麼 primary-header 帳號入口在「右上」**:GitHub / Gmail / Slack / Atlassian 的全域標頭一律把「自己的帳號」放右上(品牌在左、帳號在右,左右對稱)= global chrome 標準位置,不是 sidebar footer。
+
+**入口開什麼 = 帳號選單(`<DropdownMenu>`),不是 ProfileCard**:
+- 開「個人資料 / 設定 / 登出」navigation 選單(對齊 GitHub / Gmail / Slack / Atlassian「自己的帳號入口」慣例)。
+- **不用 `ProfileCard`**:ProfileCard 的預設動作(Chat / 通話)語義是「聯絡某人」,用在**自己**身上不對 — ProfileCard 是看**別人**的人員卡。自己的帳號入口 = 選單。
+- 消費既有 `components/DropdownMenu`(`DropdownMenuTrigger asChild` 包 avatar 作 focusable 觸發點)。
+
+**Avatar 尺寸 + 邊距**:帳號 avatar = `<Avatar size={24}>`(density-fixed,跟左側品牌 avatar 同尺寸),走 `../../patterns/header-canonical/header-canonical.spec.md` 4.5 chrome header avatar SSOT(brand + account 皆 24px raw Avatar、非 ItemAvatar)。右側邊距 = 作為 ChromeHeader 主內容區最後一個 child 自然繼承 `--layout-space-loose`(16px@md / 24px@lg),**與左側品牌 avatar 距 leadingRail 分割線的距離對稱**(ChromeHeader px-loose canonical 結構性保證,**禁 hardcode margin**)。
+
+**Reference implementation**:`../AccountMenu/account-menu.tsx`(公開元件;2026-07-30 F9 自 `_demo-helpers.tsx` 升 public,demo `AccountMenu` 為綁示範資料的薄 wrapper 消費之)+ `_demo-helpers.tsx` `GlobalHeader`(右 slot 預設放 `<AccountMenu />`)。
+
+**真正的 distinguishing factor = Header scope(local toolbar vs global bar)**:
 - **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」。
+**常見誤解:「multi-workspace 就必須 primary-header 派」** — workspace 多寡跟 layout 派别無相關性(world-class 反證:Linear / Notion / Figma 皆 multi-workspace 卻用 primary-sidebar;Gmail 多 account 用 primary-header)。選 mode = 表態「Header 是 local 還是 global」,**不是**「workspace 是 single 還是 multi」。
 
-**Sidebar toggle 按鈕位置**(消費既有 `Sidebar.spec.md:308-360` SidebarTrigger 兩 pattern,**不發明新 toggle**):
+**Sidebar toggle 按鈕位置**(消費既有 `sidebar.spec.md`「SidebarTrigger 位置(兩種 canonical 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 最左 |
+| `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 / 不發明。
+**唯一 invariant**(`sidebar.spec.md`「SidebarTrigger 位置」段既有):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 是哪派。
 
@@ -172,7 +201,7 @@ function CustomAside() {
 
 | Mode | Trigger | Mask 蓋背景? | Background operable? | 佔 layout 寬度? |
 |---|---|---|---|---|
-| **Standard inline**(對齊 Material 3 standard drawer) | viewport ≥ `--sidebar-mobile-breakpoint`(768px) | ❌ 不蓋 | ✅ 可操作 | ✅ 佔 layout |
+| **Standard inline**(對齊 Material 3 standard drawer) | viewport ≥ 768px(`useIsNarrowViewport()`,同 Sidebar mobile 切換) | ❌ 不蓋 | ✅ 可操作 | ✅ 佔 layout |
 | **Modal overlay**(對齊 Material 3 modal drawer = Sheet pattern) | viewport < breakpoint | ✅ 蓋 | ❌ 不可操作 | ❌ 不佔(蓋上去) |
 
 **Standard inline** 行為(layout-mode aware):
@@ -180,20 +209,20 @@ function CustomAside() {
 - `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
+- **Scroll ownership**:Aside 自帶 scroll(body 包 `<ScrollArea>` primitive + `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` 強制)
+- 消費既有 `sheet.spec.md` canonical(從右滑出 + Esc 關 + click-outside 關 + focus trap);**restore focus 由 AppShellAside 自建**(controlled Sheet 無 SheetTrigger → Radix 內建回焦失效;開啟時 snapshot opener、關閉還原、opener 已卸載 fallback `#app-shell-main`,WCAG 2.4.3,2026-07-14)
+- **title prop required**(per `sheet.spec.md`「禁止事項」禁無 title — `aria-labelledby` 強制)
 - 跟 Sidebar mobile fallback 同 SSOT
 
-**Breakpoint**:消費既有 `--sidebar-mobile-breakpoint`(`sidebar.spec.md:594` SSOT,768px),**不發明新 breakpoint**。Sidebar + Aside 同步切 Sheet。
+**Breakpoint**:消費既有 `useIsNarrowViewport()` hook(`hooks/use-is-narrow-viewport.ts`,`MOBILE_BREAKPOINT = 768`;與 `sidebar.spec.md`「Mobile 行為」段 768px 同值),**不發明新 breakpoint**(非 CSS token — repo 無 `--sidebar-mobile-breakpoint`)。Sidebar + Aside 同步切 Sheet。
 
 ---
 
 ## Mobile(viewport < breakpoint)
 
-- **Sidebar**:消費既有 `sidebar.spec.md:594` canonical(自動切 Sheet,從左滑出,寬度 `--sidebar-width-mobile`)
+- **Sidebar**:消費既有 `sidebar.spec.md`「Mobile 行為」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
@@ -228,7 +257,7 @@ Main 內塞什麼(table / field / card / page header / list)的 layout + spacing
 
 - 所有 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`)
+- Z-index:AppShell shell root **不設 z-index**(`app-shell.tsx` root `<div>` 走正常 flow / stacking context,唯一 z-* 是 SkipToMain `focus:z-50`);overlay 走既有 **`z-50` Tailwind utility**(`sheet.tsx` SheetOverlay / SheetContent `z-50` SSOT canonical,**不發明 `--z-overlay` token** — repo 內無此 token,Sheet 直接 `z-50`)
 - AppShell **不** export `modalOpen` prop,overlay 自管 open / close state
 
 ---
@@ -237,11 +266,11 @@ Main 內塞什麼(table / field / card / page header / list)的 layout + spacing
 
 | Shortcut | Action | Cite |
 |---|---|---|
-| **`⌘B`(macOS)/ `Ctrl+B`(Windows)** | Toggle sidebar | `sidebar.spec.md:348` SSOT「industry-standard,已內建,不該改」;`sidebar.tsx:62` code key `"b"` |
+| **`⌘B`(macOS)/ `Ctrl+B`(Windows)** | Toggle sidebar | `sidebar.spec.md`「持久化與快捷鍵」SSOT(⌘B / Ctrl+B industry-standard,已內建,不該改);`sidebar.tsx` 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 不發明新機制。
+**`⌘B`** 消費既有 Sidebar SSOT 機制(Sidebar 內建 `useEffect` + `window.addEventListener('keydown')`,AppShell **不重複 register**)。**`⌘.`** 為 AppShell **自有** `window` keydown listener(`app-shell.tsx:179-188`,沿用相同 pattern 形態,但屬**新註冊**、非消費 Sidebar — 對齊上表「新加」標記)。此 AppShell 自有 listener 目前**未含** Sidebar handler 的 IME composition / input-textarea guard(打字時 `⌘.` 仍會觸發 — 已知 gap)。
 
 ---
 
@@ -249,19 +278,18 @@ Main 內塞什麼(table / field / card / page header / list)的 layout + spacing
 
 | 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 |
+| `header`(`primary-header` mode) | `<header>` 只被 `<div>` 包覆(body-scoped)→ **`role="banner"`** implicit(global banner) | site-wide |
+| `header`(`primary-sidebar` mode) | `<header>` 只被 `<div>` 包覆、與 `<main>` 是 sibling(非 main descendant)→ 同樣 body-scoped → **`role="banner"`** implicit | per W3C HTML-AAM:只有 `main/article/aside/nav/section` descendant 的 `<header>` 才 scope out banner;`<div>` ancestor 不會 |
+| `sidebar` | **無自帶 landmark** — `<Sidebar>` 渲染 `<div>`(三 collapsible 分支皆然,per `sidebar.spec.md`「A11y 預設」)| consumer 需自行用 `<nav aria-label="Main">` 包住 `<Sidebar>` 才有 navigation landmark;AppShell / Sidebar 皆**不**自帶 `<nav>` / `role="navigation"` |
 | `aside` | `<aside aria-label={title}>` | title required(modal mode `aria-labelledby` 強制) |
 | `children`(main) | `<main>` | `role="main"`(implicit)+ skip-to-main 跳轉 anchor |
+| skip link | `<nav aria-label="Skip links">` 包 skip-to-main `<a>`(2026-07-30 WM patch 收編:裸 `<a>` 落在所有 landmark 之外 → axe region violation)| `role="navigation"`(implicit;WebAIM skip-navigation idiom)|
 
 **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。
+**本 AppShell 對應落實**(ChromeHeader 三個分支皆 render `<header>`,per `chrome-header.tsx` 2026-05-20「`<div>` → `<header>`」註解):
+- `primary-header` mode:`<header>` 被 `flex-shrink-0 <div>` 包覆(AppShell root flex-col 第一個 child,body-scoped)→ implicit banner role ✓
+- `primary-sidebar` mode:`<header>` 被 `flex-shrink-0 <div>` 包覆、與 `<main>` 是 sibling(非 main descendant,body-scoped)→ **同樣得到 implicit banner role**。`<div>` wrapper 依 W3C HTML-AAM **不** scope out banner(只有 `main/article/aside/nav/section` 能)。
 
 不發明新 ARIA,消費 HTML5 semantic + WAI-ARIA Landmark 標準 + W3C ARIA in HTML banner rule。
 
@@ -269,7 +297,7 @@ Main 內塞什麼(table / field / card / page header / list)的 layout + spacing
 
 ## 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」)。
+**Multi-sidebar**(Notion / Linear 雙側欄派):**尚未實作**。目前 `sidebar` prop 僅 `React.ReactNode`(單一 slot,無 array signature、無取首位邏輯、無 dev warning)。未來若支援會擴充為 array,SSOT 放 `sidebar.spec.md`,不在本 composite(per user 2026-05-19「AppShell 不該 customize Sidebar」)。
 
 **Footer**:不 expose slot(per user 2026-05-19「不用 footer」)。Web service 通常不用 footer,consumer 若需要自貼 Main 底。
 
@@ -285,25 +313,26 @@ Main 內塞什麼(table / field / card / page header / list)的 layout + spacing
 
 | 用途 | Consume token / SSOT |
 |---|---|
-| Mobile breakpoint | `--sidebar-mobile-breakpoint`(`sidebar.spec.md:594`)|
+| Mobile breakpoint | `useIsNarrowViewport()` JS hook,768px(非 CSS token;`sidebar.spec.md`「Mobile 行為」段同值)|
 | 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 |
+| Z-index | shell root 不設 z-index;overlay 走 Sheet `z-50` Tailwind utility(`sheet.tsx` SheetOverlay / SheetContent,無 `--z-overlay` token)|
 | Sheet fallback | `sheet.spec.md` SSOT |
 | Overlay | `overlay-surface.spec.md` SSOT |
 
-**0 新 CSS variable**,per CLAUDE.md token 4 條硬規則(不孤立發明)。
+**0 新 CSS variable**,per `packages/design-system/ds-canonical/rules/ui-development.md`「Token 命名 4 條硬規則」(不孤立發明)。
 
 ---
 
 ## Consumer 紀律
 
 - ❌ 禁:`<AppShell>` 內 wrap 第二個 `<AppShell>`(nested shell 違反「整頁框架」單例性)
-- ❌ 禁:`sidebar={<div>...</div>}`(必傳 `<Sidebar>` primitive,確保視覺 SSOT)
-- ❌ 禁:`header={<header>...</header>}`(必傳 `<ChromeHeader>` 或消費 `header-canonical` 派生 header)
+- ❌ 禁:`sidebar={<div>...</div>}`(應傳 `<Sidebar>` primitive,確保視覺 SSOT。raw-element slot 簽名(`sidebar={<div>}` / `header={<header>}` 等)由 `check_consumer_app_invariants.sh` Pattern 9 機械攔(P0,2026-06-12 加);TS 型別層仍收 ReactNode 不強制 — React 型別強制易被 wrapper 包一層繞過,世界級 shell 元件皆收 ReactNode;wrapper 包一層繞過的殘餘 case 靠 story 示範 + audit 把關。2026-06-10 user 拍板 2a:措辭「必」→「應」對齊 code 真實)
+- ❌ 禁:`header={<header>...</header>}`(應傳 `<ChromeHeader>` 或消費 `header-canonical` 派生 header;同上 — Pattern 9 同攔 header raw-element,TS 型別層不強制)
 - ❌ 禁:AppShell.Main 自加 padding(違反 layoutSpace 規則 1B)
+- ❌ 禁:AppShellAside header 加第二行 / actions(header = 單行 title + close X,API typed `title: string` 結構鎖;說明文字歸 aside body — 2026-06-12 fork-drift 防線)
 - ✅ 必:`layout` mode 在 product 啟動時固定,**不在 runtime 切換**(切換 = product 角色變動 = 應該重 mount app)
 
 ---
@@ -322,10 +351,17 @@ Main 內塞什麼(table / field / card / page header / list)的 layout + spacing
 
 ## 相關 spec(per codex Layer B 比稿修正 path/case)
 
-- `components/Sidebar/sidebar.spec.md` — sidebar 視覺 + 鍵盤 + mobile + SidebarTrigger Pattern A/B SSOT(本 pattern 必消費)
+- `components/Sidebar/sidebar.spec.md` — sidebar 視覺 + 鍵盤 + mobile + SidebarTrigger Pattern A/B SSOT(本 composite 必消費)
 - `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
+- `tokens/uiSize/uiSize.spec.md` — `--chrome-header-height` 等 size token
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `account-menu.spec.md`
+- `header-canonical.spec.md`
+- `sidebar.spec.md`