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

package/src/components/AppShell/_demo-helpers.tsx

@@ -12,6 +12,8 @@ import {
   Users,
   BarChart3,
   LayoutDashboard,
+  User,
+  LogOut,
 } from 'lucide-react'
 import {
   Sidebar,
@@ -24,16 +26,26 @@ import {
   SidebarMenuButton,
   SidebarFooter,
   SidebarTrigger,
+  useSidebar,
 } from '@/design-system/components/Sidebar/sidebar'
+import { useAppShell } from '@/design-system/components/AppShell/app-shell'
 import { ChromeHeader } from '@/design-system/patterns/header-canonical/chrome-header'
 import {
   ItemAvatar,
 } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { Avatar } from '@/design-system/components/Avatar/avatar'
 import {
-  NameCard,
-  NameCardDefaultActions,
-} from '@/design-system/components/NameCard/name-card'
+  ProfileCard,
+  ProfileCardDefaultActions,
+} from '@/design-system/components/ProfileCard/profile-card'
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuGroup,
+} from '@/design-system/components/DropdownMenu/dropdown-menu'
 
 // ── MAIN_NAV(對齊 sidebar.stories.tsx baseline)────────────────────────
 
@@ -84,12 +96,12 @@ export const UserFooter = () => (
             alt="Alan Chen"
             color="blue"
             hoverCard={
-              <NameCard
+              <ProfileCard
                 name="Alan Chen"
                 subtitle="Design｜D-0042"
                 avatar={{ alt: 'Alan Chen', color: 'blue' }}
                 status="online"
-                actions={<NameCardDefaultActions />}
+                actions={<ProfileCardDefaultActions />}
               />
             }
           />
@@ -103,19 +115,43 @@ export const UserFooter = () => (
 // ── AcmeSidebar(完整 production-grade,對齊 sidebar IconCollapse story)──
 // `includeWorkspaceBrand` default true(primary-sidebar 派 Linear/Notion 慣例:workspace brand 在 sidebar 頂)。
 // `false` 用於 primary-header mode:workspace brand 移到 globalHeader 左側(GitHub logo / Slack workspace bar 慣例)。
+// `includeUserFooter` default true(primary-sidebar:帳號在 sidebar 底)。`false` 用於 primary-header:
+// 帳號入口移到 globalHeader 右側 AccountMenu(GitHub/Gmail/Slack 慣例;見 app-shell.spec.md 帳號入口放置 SSOT)。
 
 export function AcmeSidebar({
   viewportInsetTop,
   includeWorkspaceBrand = true,
+  includeUserFooter = true,
 }: {
   viewportInsetTop?: string
   includeWorkspaceBrand?: boolean
+  includeUserFooter?: boolean
 } = {}) {
+  // Responsive 品牌/帳號(2026-06-18 v2):小螢幕 sidebar 收成 Sheet(z-50)打開時會「蓋住」globalHeader →
+  // primary-header 把品牌+帳號放 globalHeader,Sheet 內就看不到、drawer 變孤兒。故 mobile 時在 sidebar 內補回。
+  // **每 mode 鏡像自己桌面的帳號家**(per app-shell.spec.md「帳號入口(Account entry)放置 SSOT」Responsive 精修):
+  //   - primary-header:桌面帳號在 globalHeader 右(brand 左 / account 右)→ Sheet 內把整條 globalHeader 搬進
+  //     SidebarHeader(brand + flex-1 + AccountMenu;**SidebarHeader 即 ChromeHeader 基底,與 GlobalHeader 同
+  //     primitive** = 結構 SSOT,非手刻對齊),**不放 SidebarFooter**(footer 是 primary-sidebar 慣例;
+  //     對齊 Material modal navigation drawer「帳號 switcher 放 drawer header,非 footer」)。
+  //   - primary-sidebar:桌面帳號在 sidebar 底(SidebarFooter)→ Sheet 維持 header=brand / footer=UserFooter(不變)。
+  // desktop(globalHeader 可見)維持 headerless/footerless,不重複。「只能出現一次」= 同一時間一次,per breakpoint 判定。
+  const { isMobile } = useSidebar()
+  const { layout } = useAppShell()
+  // primary-header 收成 Sheet:帳號入口鏡像 globalHeader 放 SidebarHeader 右(SidebarHeader = ChromeHeader 基底,
+  // 與 GlobalHeader「brand 左 + flex-1 + account 右」完全同結構 → avatar 24px + 右緣距 px-loose 由 construction 保證)。
+  const headerHasAccount = layout === 'primary-header' && isMobile
   return (
     <Sidebar collapsible="icon" viewportInsetTop={viewportInsetTop}>
-      {includeWorkspaceBrand && (
+      {(includeWorkspaceBrand || isMobile) && (
         <SidebarHeader>
           <WorkspaceBrand />
+          {headerHasAccount && (
+            <>
+              <div className="flex-1" />
+              <AccountMenu />
+            </>
+          )}
         </SidebarHeader>
       )}
       <SidebarContent>
@@ -137,14 +173,54 @@ export function AcmeSidebar({
           </SidebarGroupContent>
         </SidebarGroup>
       </SidebarContent>
-      <SidebarFooter>
-        <UserFooter />
-      </SidebarFooter>
+      {/* Footer 只 primary-sidebar(帳號在 sidebar 底);primary-header 帳號改放 SidebarHeader 右(見上),
+          mobile 也不放 footer(誤用他 mode 慣例)。 */}
+      {includeUserFooter && (
+        <SidebarFooter>
+          <UserFooter />
+        </SidebarFooter>
+      )}
     </Sidebar>
   )
 }
 
-// ── GlobalHeader(primary-header mode 用,跨頁 chrome:WorkspaceBrand 左 + 跨頁 actions 右)──
+// ── AccountMenu(primary-header mode 用,主標頭右側「個人設定入口」)──────────────
+// 2026-06-17 加 per user directive「primary-header 不該把個人設定放 sidebar footer,該放主標頭右側 avatar」。
+// 對齊 GitHub / Gmail / Slack / Atlassian:自己的帳號入口在 global top bar 右上 + 點開帳號選單
+// (非 ProfileCard——ProfileCard 是看「別人」的人員卡,預設動作 Chat/通話用在自己身上不對)。
+// 消費 SSOT:
+//   - <Avatar size={24}>(header-canonical.spec.md 4.5 chrome header avatar:brand + account 同 24px;
+//     sync with --chrome-header-avatar-size)。互動感由 focus ring + hover 提供,不放大到 field height。
+//   - <DropdownMenu>(個人資料 / 設定 / 登出;baseline = dropdown-menu.stories.tsx Groups)
+//   - 放置 / 邊距對稱 canonical → app-shell.spec.md「帳號入口(Account entry)放置 SSOT」段
+export function AccountMenu() {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger asChild>
+        <button
+          type="button"
+          aria-label="帳號與設定"
+          className="flex items-center justify-center rounded-full focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1"
+        >
+          {/* 24 per header-canonical.spec.md 4.5 chrome header avatar canonical(brand + account 同尺寸); sync with --chrome-header-avatar-size */}
+          <Avatar size={24} alt="Alan Chen" color="blue" />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end">
+        <DropdownMenuGroup>
+          <DropdownMenuLabel>Alan Chen</DropdownMenuLabel>
+          <DropdownMenuItem startIcon={User}>個人資料</DropdownMenuItem>
+          <DropdownMenuItem startIcon={Settings}>設定</DropdownMenuItem>
+        </DropdownMenuGroup>
+        <DropdownMenuGroup>
+          <DropdownMenuItem startIcon={LogOut}>登出</DropdownMenuItem>
+        </DropdownMenuGroup>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  )
+}
+
+// ── GlobalHeader(primary-header mode 用,跨頁 chrome:WorkspaceBrand 左 + 帳號入口右)──
 // 2026-05-21 加 per user clarification「primary-header = primary-sidebar + 一條 global header」。
 // 對齊 GitHub top nav(logo 左 / search 中 / account 右)+ Slack workspace bar 慣例。
 // 消費 ChromeHeader(per `header-canonical.spec.md` Element + Background ownership 段:
@@ -159,7 +235,7 @@ export function GlobalHeader({ rightSlot }: { rightSlot?: React.ReactNode } = {}
     <ChromeHeader className="bg-surface" leadingRail={<SidebarTrigger />}>
       <WorkspaceBrand />
       <div className="flex-1" />
-      {rightSlot}
+      {rightSlot ?? <AccountMenu />}
     </ChromeHeader>
   )
 }

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

@@ -0,0 +1,176 @@
+// @benchmark-cited: anatomy 6-canonical 對齊 Polaris / Material anatomy spec
+// @story-baseline: packages/design-system/src/components/Sidebar/sidebar.stories.tsx#IconCollapse
+// (透過 ./_demo-helpers AcmeSidebar / PageHeader / WorkspaceBrand / UserFooter 共用 baseline,
+//  避免 anatomy stories 跟 showcase + Sidebar 既有完整佈局 範例視覺偏移)
+import type { Meta, StoryObj } from '@storybook/react'
+import * as React from 'react'
+import { AppShell, AppShellAside } from './app-shell'
+import { AcmeSidebar, PageHeader } from './_demo-helpers'
+import { ChromeHeader } from '@/design-system/patterns/header-canonical/chrome-header'
+import { SidebarProvider, SidebarTrigger } from '@/design-system/components/Sidebar/sidebar'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta<typeof AppShell> = {
+  title: 'Design System/Components/AppShell/設計規格',
+  component: AppShell,
+  parameters: { layout: 'fullscreen' },
+}
+export default meta
+type Story = StoryObj<typeof AppShell>
+
+/** Slot 結構 + landmark role 對照(使用 baseline AcmeSidebar / PageHeader 完整 production-grade)。 */
+export const Overview: Story = {
+  name: '槽位結構總覽',
+  render: () => {
+    const [activeId, setActiveId] = React.useState<string>('dashboard')
+    const [asideOpen, setAsideOpen] = React.useState(true)
+    return (
+      <SidebarProvider activeId={activeId} onActiveChange={setActiveId}>
+        <AppShell
+          layout="primary-sidebar"
+          sidebar={<AcmeSidebar />}
+          header={<PageHeader title="Dashboard" />}
+          aside={
+            <AppShellAside title="Detail panel" width={320}>
+              <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]">
+                <p className="text-body">Aside 內容(留白由使用此面板的內容自行管理)</p>
+              </div>
+            </AppShellAside>
+          }
+          asideOpen={asideOpen}
+          onAsideOpenChange={setAsideOpen}
+        >
+          <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]">
+            <h2 className="text-h4 mb-3">Main &lt;main&gt; landmark + padding=0</h2>
+            <p className="text-body text-fg-secondary">
+              主內容區自身不加任何留白,留白由內容決定:自帶邊框的卡片或表格自己帶內距、
+              純排版容器由外層父層統一管理、有 hover 效果的列表則每一列各自帶內距。三種情況並存。
+            </p>
+          </div>
+        </AppShell>
+      </SidebarProvider>
+    )
+  },
+}
+
+/** Layout mode diagram:純文字 2 mode 對照(非 nested live demo,避 Sidebar fixed inset 衝突)。 */
+export const LayoutModeDiagram: Story = {
+  name: '兩種布局模式對照圖',
+  render: () => (
+    <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)] space-y-6 text-body">
+      <h2 className="text-h4">兩 mode 對照</h2>
+      <section className="space-y-2">
+        <h3 className="text-h5">primary-sidebar(Linear / Notion / Figma 派)</h3>
+        <div className="flex gap-px bg-divider border border-divider rounded overflow-hidden text-caption">
+          <div className="w-32 bg-surface-strong px-2 py-8 text-center">Sidebar<br/>頂天立地</div>
+          <div className="flex-1 flex flex-col">
+            <div className="bg-surface-strong px-2 py-1">Header(在 main col 內,當前頁 toolbar)</div>
+            <div className="bg-canvas flex-1 px-2 py-6 text-fg-muted">Main content</div>
+          </div>
+          <div className="w-24 bg-surface-strong px-2 py-8 text-center text-fg-muted">Aside<br/>頂天</div>
+        </div>
+        <p className="text-fg-muted">Header scope = <strong>local toolbar</strong>(當前頁 actions / breadcrumb / page-level filter)。Workspace 多寡無關,Notion / Linear 多 workspace 也用 primary-sidebar。</p>
+      </section>
+      <section className="space-y-2">
+        <h3 className="text-h5">primary-header(GitHub / Slack / Gmail 派)</h3>
+        <div className="flex flex-col gap-px bg-divider border border-divider rounded overflow-hidden text-caption">
+          <div className="bg-surface-strong px-2 py-1 text-center">Header(global bar,橫跨整 viewport)</div>
+          <div className="flex">
+            <div className="w-32 bg-surface-strong px-2 py-8 text-center">Sidebar<br/>(在 header 下)</div>
+            <div className="flex-1 bg-canvas px-2 py-6 text-fg-muted">Main content</div>
+            <div className="w-24 bg-surface-strong px-2 py-8 text-center text-fg-muted">Aside</div>
+          </div>
+        </div>
+        <p className="text-fg-muted">
+          Header scope = <strong>global bar</strong>(account / workspace switcher / notifications / 跨頁導覽)。
+          Workspace 多寡無關 — GitHub / Gmail multi account 也用此 layout,真正的 distinguisher 是 header 是「local 還是 global」。
+        </p>
+      </section>
+    </div>
+  ),
+}
+
+/** Aside 2-mode state behavior(toggle + breakpoint 切換)— 用完整 baseline。 */
+export const StateBehavior: Story = {
+  name: '右側面板開合行為(兩種模式)',
+  render: () => {
+    const [activeId, setActiveId] = React.useState<string>('dashboard')
+    const [open, setOpen] = React.useState(false)
+    return (
+      <SidebarProvider activeId={activeId} onActiveChange={setActiveId}>
+        <AppShell
+          layout="primary-sidebar"
+          sidebar={<AcmeSidebar />}
+          header={
+            <ChromeHeader className="bg-surface">
+              <SidebarTrigger />
+              <h1 className="text-body-lg font-medium flex-1 truncate">Toggle Aside demo</h1>
+              <Button size="sm" variant="primary" onClick={() => setOpen(!open)}>
+                {open ? 'Close' : 'Open'} Aside (cmd+.)
+              </Button>
+            </ChromeHeader>
+          }
+          aside={
+            <AppShellAside title="Detail panel" width={320}>
+              <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]">
+                <p className="text-body">Aside 內容</p>
+              </div>
+            </AppShellAside>
+          }
+          asideOpen={open}
+          onAsideOpenChange={setOpen}
+        >
+          <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)] text-body">
+            <p>Aside open:{String(open)}</p>
+            <p>Desktop ≥ 768px → inline standard mode(右側 panel,不蓋 mask)</p>
+            <p>Mobile &lt; 768px → modal mode(Sheet from right,蓋 mask)</p>
+          </div>
+        </AppShell>
+      </SidebarProvider>
+    )
+  },
+}
+
+/** A11y landmark 文字說明(非 live render,避無謂 nested shell)。 */
+export const Accessibility: Story = {
+  name: '無障礙(地標標記 + 跳轉連結 + 鍵盤導覽)',
+  render: () => (
+    <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]">
+      <h2 className="text-h4 mb-3">A11y 機制</h2>
+      <ul className="text-body space-y-2 list-disc pl-5">
+        <li>
+          <strong>Landmark</strong>:`&lt;header&gt;` / `&lt;aside&gt;` / `&lt;main&gt;` 各自有對應的無障礙地標角色。
+          `&lt;header&gt;`(ChromeHeader)在兩種模式下都只被 `&lt;div&gt;` 包覆
+          (body-scoped、與 `&lt;main&gt;` 並排而非子層),依 W3C HTML-AAM 都得到 implicit `role=banner`
+          (整站層級標頭)——`&lt;div&gt;` 外層不會 scope out banner,只有 `main/article/aside/nav/section` 才會。
+        </li>
+        <li>
+          <strong>Sidebar 導覽地標</strong>:`&lt;Sidebar&gt;` 自身渲染 `&lt;div&gt;`(不自帶 `&lt;nav&gt;` / `role=navigation`),
+          navigation landmark 責任 delegate 給 consumer——需自行用 `&lt;nav aria-label="Main"&gt;` 包住 `&lt;Sidebar&gt;`(per `sidebar.spec.md` A11y 預設)。
+        </li>
+        <li><strong>Skip to main</strong>:`Tab` 第一站 focus skip-link → jump 到 `#app-shell-main`(WCAG 2.4.1)</li>
+        <li><strong>Keyboard shortcuts</strong>:`⌘B` / `Ctrl+B` toggle sidebar(消費 Sidebar SSOT)/ `⌘.` / `Ctrl+.` toggle aside</li>
+        <li><strong>Modal Aside title</strong>:title 是必填 prop → 行動裝置上以 Sheet 形式開啟時,自動連結 `aria-labelledby`,讓螢幕報讀器讀得到面板名稱</li>
+        <li><strong>Focus trap</strong>:Sheet open 時 focus 在 Aside 內,Esc 關回 trigger(Radix Dialog 內建)</li>
+      </ul>
+    </div>
+  ),
+}
+
+/** Size matrix:Aside width clamp 文字對照(非 rendered case,因 width 是 number prop)。 */
+export const SizeMatrix: Story = {
+  name: '右側面板寬度範圍(240-640)',
+  render: () => (
+    <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)] space-y-3 text-body">
+      <h2 className="text-h4">Aside width clamp</h2>
+      <ul className="space-y-2 list-disc pl-5">
+        <li>不傳 width → 320px(default)</li>
+        <li>width={'{'}200{'}'} → 240px(clamp 下限,避免過窄無法閱讀)</li>
+        <li>width={'{'}400{'}'} → 400px(自訂值落在 [240, 640] 內)</li>
+        <li>width={'{'}800{'}'} → 640px(clamp 上限,避免過寬擠 main)</li>
+        <li>width={'{{'} md: 320, xl: 480 {'}}'} → desktop=320 / xl(≥1280px)=480 breakpoint-keyed</li>
+      </ul>
+      <p className="text-caption text-fg-muted">DS 不發明 width token,consumer 自決 + clamp 保護。</p>
+    </div>
+  ),
+}

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

@@ -0,0 +1,140 @@
+// @benchmark-cited: Polaris / Material / Ant 共識 principles canonical(UsageGuidance integrated)
+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;/div&gt;{'}'}` → 應傳 `&lt;Sidebar&gt;` primitive(型別收 ReactNode 不機械強制,2026-06-10 拍板)</li>
+          <li>❌ 禁:`header={'{'}&lt;header&gt;raw&lt;/header&gt;{'}'}` → 應傳 `&lt;ChromeHeader&gt;` 或 header-canonical 派生(同上,不機械強制)</li>
+          <li>❌ 禁:`&lt;AppShell.Main&gt;` 強制 padding(違 layoutSpace 規則 1B)</li>
+          <li>✅ 必:Main 內容遵循既有 `layoutSpace.spec.md` 6 條規則(Page header / Card / DataTable / naked list 各按規則)</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">唯一判準:Header scope</h2>
+        <p className="text-body mb-2">
+          唯一 distinguisher = <strong>Header scope 是 local 還是 global</strong>,
+          <em>不是</em> workspace 多寡(Notion / Gmail 都支援 multi-workspace,卻分屬不同派)。
+          問自己:頂部那條 bar 服務的是「當前這一頁」還是「整個 app」?
+        </p>
+        <ul className="text-body space-y-1">
+          <li>
+            <strong>primary-sidebar</strong>:頂部是 <strong>local toolbar</strong> —
+            服務當前頁(breadcrumb / page-level actions / filter)。Sidebar 頂天立地,WorkspaceBrand 在 sidebar 頂。
+            參考 Linear / Notion / Figma。
+          </li>
+          <li>
+            <strong>primary-header</strong>:多一條 <strong>global bar</strong> 橫跨頂部 —
+            服務整個 app(account / workspace switcher / 跨頁 search / notifications);local toolbar
+            <em>仍在</em> main col 頂,只是上面多了 global header。WorkspaceBrand 改放 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">
+          兩 mode 是 product 角色表態——啟動時固定,不該在 runtime 切換。視覺對照圖見{' '}
+          <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">常見誤解:global header 取代 local toolbar</h2>
+        <p className="text-body">
+          錯。primary-header = primary-sidebar 的所有東西 + <strong>額外一條</strong> global header 在頂;
+          `header` slot(local toolbar)<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 不放 user footer — GitHub / Gmail / Slack 帳號一律在 global bar 右上</li>
+          <li>• 開「個人資料 / 設定 / 登出」帳號選單(`&lt;DropdownMenu&gt;`),<strong>不用 ProfileCard</strong>(ProfileCard 是看別人的人員卡,預設動作 Chat/通話用在自己身上不對)</li>
+          <li>• 帳號 avatar = 24px,跟左側品牌 avatar 同尺寸(header-canonical 4.5 chrome header avatar);右側邊距與品牌距分割線對稱</li>
+          <li>❌ 禁:`primary-header` mode 同時在 globalHeader + sidebar footer 各放一份 = 入口混淆(帳號入口視覺 SSOT,只能出現一次)</li>
+        </ul>
+      </section>
+    </div>
+  ),
+}