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

package/src/components/Alert/alert.stories.tsx

@@ -0,0 +1,136 @@
+// @story-history: hasVariants/hasInteractiveStates 的 canonical core stories(AllVariants / States)
+//   集中在 anatomy.stories.tsx 的 ColorMatrix + StateBehavior(Inspector 互動);本 showcase
+//   提供真實業務 scenario(部署 / 系統警示)而非 trait grid 重複展示。
+import type { Meta } from '@storybook/react'
+import { RefreshCw, Share2 } from 'lucide-react'
+import { Alert } from './alert'
+import { Button } from '@/design-system/components/Button/button'
+import type { NoticeVariant } from '@/design-system/components/Notice/notice'
+
+const meta: Meta = {
+  title: 'Design System/Components/Alert/展示',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { description: { component: '在頁面內容中持續呈現重要狀態、警告、錯誤或成功訊息，並可附帶操作。訊息需要留在閱讀脈絡供使用者處理時用 Alert；短暫回饋改用 Toast。' } },
+  },
+}
+export default meta
+
+const ALL: NoticeVariant[] = ['neutral', 'info', 'warning', 'error', 'success']
+// 真實情境的 title(「人」test:遮 variant 標籤也看得懂)
+const L: Record<string, string> = {
+  neutral: '已切換至離線模式',
+  info: 'v2.4 已發佈',
+  warning: '免費額度剩 3 天',
+  error: '付款失敗',
+  success: '部署完成',
+}
+// description 用簡潔的輔助資訊(非 variant 名稱)
+const D: Record<string, string> = {
+  neutral: '變更會在重新連線後同步',
+  info: '查看更新日誌了解新功能',
+  warning: '升級方案以避免服務中斷',
+  error: '請檢查卡號或改用其他付款方式',
+  success: 'v2.4.1 已上線到 production',
+}
+
+const actionBtn = <Button variant="tertiary" size="xs">查看詳情</Button>
+
+// 2026-07-14 audit Dim 28(story 拆分原則):原 Subtle/Solid × SingleLine/WithDescription
+// 四 story 依 appearance variant 拆細 = 「≥2 variants 拆細」反 pattern(該合對照 grid);
+// 合併為單行 / 含說明兩 story,各以 subtle vs solid 並排對照(appearance trait grid 本體
+// 由 anatomy ColorMatrix owns)。
+export const SingleLine = {
+  name: '單行（低調 vs 實心對照）',
+  render: () => (
+    <div className="grid grid-cols-2 gap-6 max-w-5xl">
+      {(['subtle', 'solid'] as const).map((appearance) => (
+        <div key={appearance} className="flex flex-col gap-3">
+          <span className="text-caption text-fg-muted font-medium">
+            {appearance === 'subtle' ? 'Subtle — 頁面內嵌預設(淺底 + 邊框)' : 'Solid — 高強調(飽和底色)'}
+          </span>
+          {ALL.map((v) => <Alert key={v} variant={v} appearance={appearance} title={L[v]} endContent={actionBtn} />)}
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+export const WithDescription = {
+  name: '含說明文字（低調 vs 實心對照）',
+  render: () => (
+    <div className="grid grid-cols-2 gap-6 max-w-5xl">
+      {(['subtle', 'solid'] as const).map((appearance) => (
+        <div key={appearance} className="flex flex-col gap-3">
+          <span className="text-caption text-fg-muted font-medium">
+            {appearance === 'subtle' ? 'Subtle — 頁面內嵌預設(淺底 + 邊框)' : 'Solid — 高強調(飽和底色)'}
+          </span>
+          {ALL.map((v) => <Alert key={v} variant={v} appearance={appearance} title={L[v]} description={D[v]} endContent={actionBtn} />)}
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+export const CornerActionGroup = {
+  name: '右上角操作群組',
+  render: () => (
+    <div className="flex flex-col gap-4 max-w-lg">
+      <span className="text-caption text-fg-muted">
+        Alert 右上角是操作按鈕群組。關閉鈕左側可以並排重新整理、分享等額外按鈕,全部用同一種最小尺寸的純圖示按鈕。
+        關閉鈕左邊有其他操作時,分隔線由 DS 自動放(誤觸保護,見 action-bar.spec.md 第五節),使用端只要傳 endContent。
+      </span>
+
+      <Alert
+        variant="warning"
+        appearance="subtle"
+        title="部署管線偵測到新的 commit"
+        description="點「重新整理」同步最新狀態,或忽略此訊息繼續目前作業。"
+        onDismiss={() => {}}
+        endContent={
+          <>
+            <Button iconOnly size="xs" variant="text" startIcon={RefreshCw} aria-label="重新整理" />
+            <Button iconOnly size="xs" variant="text" startIcon={Share2} aria-label="分享連結" />
+          </>
+        }
+      />
+
+      <span className="text-caption text-fg-muted">
+        ✅ 右上角這排(重新整理、分享、關閉)全用同一種最小尺寸的純圖示按鈕,並用分隔線分成兩群,保持同一列視覺一致。
+        ❌ 不要一群用純圖示按鈕、另一群用列內動作,會不整齊。
+      </span>
+    </div>
+  ),
+}
+
+export const Fixed = {
+  name: '固定顯示',
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <span className="text-caption text-fg-muted">固定在 header 底下,無圓角,full-width。</span>
+
+      <div className="flex flex-col gap-1">
+        <span className="text-caption text-fg-muted font-medium">Subtle Fixed</span>
+        <div className="border border-divider rounded-lg overflow-hidden">
+          <div className="px-4 py-2 bg-surface border-b border-divider">
+            <span className="text-body font-medium">專案設定</span>
+          </div>
+          {ALL.map((v) => <Alert key={v} variant={v} appearance="subtle" placement="fixed" title={L[v]} />)}
+          <div className="p-4 text-fg-muted text-caption">調整此專案的權限與通知偏好。變更會立刻套用到所有成員。</div>
+        </div>
+      </div>
+
+      <div className="flex flex-col gap-1">
+        <span className="text-caption text-fg-muted font-medium">Solid Fixed</span>
+        <div className="border border-divider rounded-lg overflow-hidden">
+          <div className="px-4 py-2 bg-surface border-b border-divider">
+            <span className="text-body font-medium">專案設定</span>
+          </div>
+          {ALL.map((v) => <Alert key={v} variant={v} appearance="solid" placement="fixed" title={L[v]} />)}
+          <div className="p-4 text-fg-muted text-caption">調整此專案的權限與通知偏好。變更會立刻套用到所有成員。</div>
+        </div>
+      </div>
+    </div>
+  ),
+}

package/src/components/Alert/alert.tsx

@@ -12,7 +12,7 @@ import { Notice, useInverseTheme, SUBTLE_ICON_COLOR, type NoticeVariant } from '
  * 在 theme boundary 設 text-foreground 強制 re-resolve。
  *
  * ── Appearance ──
- * subtle: 淺底色 + 四邊 1px border(色相 hover 色)。不設 data-theme,跟隨頁面。
+ * subtle: 淺底色 + 四邊 1px border(色相 text 色 = icon 同色,見下方 SUBTLE_CONTAINER 註)。不設 data-theme,跟隨頁面。
  * solid: 跟 Toast 對齊:
  *   neutral → data-theme={inverse} + bg-surface-raised（同層翻轉）
  *   info/success/error → bg on outer, data-theme="dark" on inner
@@ -23,12 +23,15 @@ import { Notice, useInverseTheme, SUBTLE_ICON_COLOR, type NoticeVariant } from '
  * fixed: 無圓角,full-width,無 border
  */
 
+// border 用 `--{hue}-text`(= icon 同色,2026-06-15 user 拍板「直接共用 hue-text,不開新 token」)。
+// 原借 `--{hue}-hover`(互動狀態 token)當靜態 border 是語意 smell + 跟 icon 不同色;
+// 改共用 hue-text(SUBTLE_ICON_COLOR 用的同一顆,blue-7 等)→ 0 新 token + border/icon cohesion。
 const SUBTLE_CONTAINER: Record<NoticeVariant, string> = {
   neutral: 'bg-muted border border-border',
-  info: 'bg-info-subtle border border-[var(--info-hover)]',
-  success: 'bg-success-subtle border border-[var(--success-hover)]',
-  warning: 'bg-warning-subtle border border-[var(--warning-hover)]',
-  error: 'bg-error-subtle border border-[var(--error-hover)]',
+  info: 'bg-info-subtle border border-[var(--info-text)]',
+  success: 'bg-success-subtle border border-[var(--success-text)]',
+  warning: 'bg-warning-subtle border border-[var(--warning-text)]',
+  error: 'bg-error-subtle border border-[var(--error-text)]',
 }
 
 const SOLID_HUE_BG: Record<string, string> = {
@@ -63,6 +66,11 @@ export interface AlertProps
   title: React.ReactNode
   description?: React.ReactNode
   endContent?: React.ReactNode
+  /**
+   * 顯示關閉鈕(預設 true)。**需同時傳 `onDismiss` 才會渲染 X** — Alert 是 controlled-only
+   * (不自我移除),無 handler 的 X 是死按鈕(2026-07-05 D4;對齊 Polaris Banner / Ant Alert)。
+   * 條件判斷 SSOT 在 Notice(notice.tsx `showDismiss`),Alert 原樣 forward。
+   */
   dismissible?: boolean
   onDismiss?: () => void
 }
@@ -77,7 +85,10 @@ const Alert = React.forwardRef<HTMLDivElement, AlertProps>(
       title,
       description,
       endContent,
-      dismissible = true,
+      // 2026-07-05 D4:不 destructure-default(原 `= true` 會把「consumer 沒傳」materialize 成顯式
+      // true,讓 Notice 的 dev-warn 無法分辨消費端矛盾)。等效預設 true 由 Notice showDismiss
+      // `!== false` 承擔,行為不變;X 僅在同時傳 onDismiss 時渲染(SSOT 在 notice.tsx)。
+      dismissible,
       onDismiss,
       className,
       ...props
@@ -167,7 +178,7 @@ Alert.displayName = 'Alert'
 // Sizes = none(Alert 視覺尺寸繼承 Notice primitive,不隨 size 變;見 spec「為何無 SizeMatrix」)
 export const alertMeta = {
   component: 'Alert',
-  family: null, // non-family composite / overlay / layout
+  family: 2, // List item(對齊 alert.spec.md frontmatter family: 2)
   variants: {
     neutral: { purpose: '中性提示(系統公告、非緊急說明);無情緒色' },
     info: { purpose: '資訊性提示(版本更新、流程說明);藍色 hue' },
@@ -176,7 +187,7 @@ export const alertMeta = {
     error: { purpose: '錯誤但非阻斷(系統錯誤可重試、API 失敗摘要);aria-live=assertive' },
   },
   sizes: {},
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['default'], // 2026-06-11 R2:Alert 本體無互動 state(spec L183 明文無 disabled;dismiss 互動屬內部 Button),
   tokens: {
     bg: ['bg-error', 'bg-error-subtle', 'bg-info', 'bg-info-subtle', 'bg-muted', 'bg-success', 'bg-success-subtle', 'bg-surface-raised', 'bg-warning', 'bg-warning-subtle'],
     fg: ['text-foreground'],

package/src/components/Alert/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './alert'

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,25 @@ 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 { AccountMenu as AccountMenuPrimitive } from '@/design-system/components/AccountMenu/account-menu'
+// 帳號選單內容(AccountMenuItems)在本檔以 DropdownMenu primitives 直接組,
+// 供 header AccountMenu demo wrapper 與 footer UserFooter 共用(M17 單一 SSOT)。
 import {
-  NameCard,
-  NameCardDefaultActions,
-} from '@/design-system/components/NameCard/name-card'
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuGroup,
+} from '@/design-system/components/DropdownMenu/dropdown-menu'
 
 // ── MAIN_NAV(對齊 sidebar.stories.tsx baseline)────────────────────────
 
@@ -68,34 +79,34 @@ export const MAIN_NAV = [
 export const WorkspaceBrand = () => (
   <div className="flex items-center gap-2 min-w-0">
     {/* 24 per header-canonical.spec.md 4.5 chrome header avatar canonical; sync with `--chrome-header-avatar-size` */}
+    {/* Workspace brand = 組織識別(非人)→ 首字 letter mark;2026-07-08 人像真實化 sweep 刻意保留,
+        真實人像僅套用於 person avatar(組織用人臉照片會誤導身份) */}
     <Avatar size={24} shape="square" color="blue" solid alt="Acme Inc" />
     <span className="text-body-lg font-medium truncate group-data-[collapsible=icon]:hidden">Acme Inc</span>
   </div>
 )
 
-// ── UserFooter(對齊 sidebar.stories.tsx)────────────────────────────────
+// ── UserFooter(對齊 sidebar.stories.tsx;primary-sidebar 帳號入口 = footer 行開帳號選單)──
+// per app-shell.spec.md「帳號入口(Account entry)放置 SSOT」「入口開什麼」段:入口開
+// DropdownMenu 帳號選單,不掛 ProfileCard(看「別人」的人員卡)。選單內容與 AccountMenu
+// 共用 AccountMenuItems(同檔單一 SSOT,M17)。
 
 export const UserFooter = () => (
   <SidebarMenu>
     <SidebarMenuItem>
-      <SidebarMenuButton asChild>
-        <div role="group" aria-label="當前使用者">
-          <ItemAvatar
-            alt="Alan Chen"
-            color="blue"
-            hoverCard={
-              <NameCard
-                name="Alan Chen"
-                subtitle="Design｜D-0042"
-                avatar={{ alt: 'Alan Chen', color: 'blue' }}
-                status="online"
-                actions={<NameCardDefaultActions />}
-              />
-            }
-          />
-          <span data-sidebar="menu-label" className="min-w-0 flex-1 truncate">Alan Chen</span>
-        </div>
-      </SidebarMenuButton>
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <SidebarMenuButton asChild tooltip="Alan Chen">
+            <button type="button" aria-label="帳號與設定">
+              <ItemAvatar src="https://i.pravatar.cc/48?u=EMP-1001" alt="Alan Chen" color="blue" />
+              <span data-sidebar="menu-label" className="min-w-0 flex-1 truncate">Alan Chen</span>
+            </button>
+          </SidebarMenuButton>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="start" minWidth={280}>
+          <AccountMenuItems />
+        </DropdownMenuContent>
+      </DropdownMenu>
     </SidebarMenuItem>
   </SidebarMenu>
 )
@@ -103,19 +114,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 +172,58 @@ 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 右)──
+// ── AccountMenuItems(帳號選單內容;header AccountMenu + footer UserFooter 共用,M17 SSOT)──
+// DropdownMenuLabel 兩行 = 名字 + 身份資訊(text-caption)——per sidebar.spec.md
+// 「SidebarFooter user 區必單行」:身份資訊歸帳號選單頂部,不佔 footer 行第二行。
+function AccountMenuItems() {
+  return (
+    <>
+      <DropdownMenuGroup>
+        <DropdownMenuLabel>
+          <span className="block truncate">Alan Chen</span>
+          <span className="block truncate text-caption font-normal text-fg-secondary">Design｜D-0042｜EMP-1001</span>
+        </DropdownMenuLabel>
+        <DropdownMenuItem startIcon={User}>個人資料</DropdownMenuItem>
+        <DropdownMenuItem startIcon={Settings}>設定</DropdownMenuItem>
+      </DropdownMenuGroup>
+      <DropdownMenuGroup>
+        <DropdownMenuItem startIcon={LogOut}>登出</DropdownMenuItem>
+      </DropdownMenuGroup>
+    </>
+  )
+}
+
+// ── AccountMenu(primary-header mode 用,主標頭右側「個人設定入口」)──────────────
+// 2026-06-17 加 per user directive「primary-header 不該把個人設定放 sidebar footer,該放主標頭右側 avatar」。
+// 2026-07-30 F9 升 public:元件本體升級至 `components/AccountMenu/account-menu.tsx`(SSOT),
+// demo 只留綁 Alan Chen 示範資料的薄 wrapper 消費之,不再重複實作(視覺 / 行為 / 放置 canonical 不變;
+// 放置 SSOT 仍在 app-shell.spec.md「帳號入口(Account entry)放置 SSOT」段)。
+export function AccountMenu() {
+  return (
+    <AccountMenuPrimitive
+      user={{
+        name: 'Alan Chen',
+        avatar: { src: 'https://i.pravatar.cc/48?u=EMP-1001', color: 'blue' },
+      }}
+      onViewProfile={() => {}}
+      onOpenSettings={() => {}}
+      onSignOut={() => {}}
+    />
+  )
+}
+
+// ── 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 +238,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,185 @@
+// @anatomy-rationale: Inspector + ColorMatrix N/A — AppShell 是 page-level layout composite
+// (sidebar+header+main+aside 組合),無 cva color variant → ColorMatrix N/A;
+// 無 interactive prop control(slots 全 ReactNode 組合)→ Inspector N/A(Dim 13 例外 marker)。
+// @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="訂單詳情" width={320}>
+              {/* 面板內容自帶留白(px/py),示範 aside slot 不強制內距、由內容自管 */}
+              <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)] space-y-3 text-body">
+                <div className="flex justify-between"><span className="text-fg-muted">訂單編號</span><span className="font-medium">#SO-20481</span></div>
+                <div className="flex justify-between"><span className="text-fg-muted">客戶</span><span className="font-medium">陳怡君</span></div>
+                <div className="flex justify-between"><span className="text-fg-muted">付款狀態</span><span className="font-medium">已付款</span></div>
+                <div className="flex justify-between"><span className="text-fg-muted">金額</span><span className="font-medium">NT$ 12,800</span></div>
+              </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">訂單 #SO-20481</h1>
+              <Button size="sm" variant="primary" onClick={() => setOpen(!open)}>
+                {open ? '隱藏訂單詳情' : '顯示訂單詳情'}
+              </Button>
+            </ChromeHeader>
+          }
+          aside={
+            <AppShellAside title="訂單詳情" width={320}>
+              <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)] space-y-3 text-body">
+                <div className="flex justify-between"><span className="text-fg-muted">訂單編號</span><span className="font-medium">#SO-20481</span></div>
+                <div className="flex justify-between"><span className="text-fg-muted">客戶</span><span className="font-medium">陳怡君</span></div>
+                <div className="flex justify-between"><span className="text-fg-muted">付款狀態</span><span className="font-medium">已付款</span></div>
+              </div>
+            </AppShellAside>
+          }
+          asideOpen={open}
+          onAsideOpenChange={setOpen}
+        >
+          <div className="px-[var(--layout-space-loose)] py-[var(--layout-space-tight)] text-body space-y-1">
+            <p>訂單詳情面板目前:{open ? '已展開' : '已收合'}(⌘. / Ctrl+. 可切換)</p>
+            <p className="text-fg-secondary">桌面 ≥ 768px:面板從右側並排展開,不蓋遮罩</p>
+            <p className="text-fg-secondary">行動裝置 &lt; 768px:面板以 Sheet 從右側滑出,蓋半透明遮罩</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 關閉後回焦 opener——controlled Sheet 無 SheetTrigger,Radix 內建回焦失效,由 AppShellAside 自建 opener snapshot + onCloseAutoFocus 手動還原(app-shell.tsx,2026-07-14)</li>
+      </ul>
+    </div>
+  ),
+}
+
+/** Size matrix:Aside width clamp 文字對照(非 rendered case,因 width 是 number prop)。 */
+export const SizeMatrix: Story = {
+  name: '尺寸對照表',
+  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>
+  ),
+}