@qijenchen/design-system 0.1.0-beta.3

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@qijenchen/design-system",
+  "version": "0.1.0-beta.3",
+  "private": false,
+  "description": "World-class design system — components, patterns, tokens, hooks (single source of truth for team distribution).",
+  "type": "module",
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "src/**/*.{tsx,ts,css}",
+    "!src/**/*.stories.tsx",
+    "!src/**/*.anatomy.stories.tsx",
+    "!src/**/*.principles.stories.tsx",
+    "!src/**/*.spec.md",
+    "!src/**/*.spec.ts",
+    "!src/**/*.test.ts",
+    "README.md",
+    "scripts"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./components/*": {
+      "types": "./dist/components/*/index.d.ts",
+      "import": "./dist/components/*/index.js"
+    },
+    "./patterns/*": {
+      "types": "./dist/patterns/*/index.d.ts",
+      "import": "./dist/patterns/*/index.js"
+    },
+    "./tokens/*": "./dist/tokens/*",
+    "./hooks/*": {
+      "types": "./dist/hooks/*.d.ts",
+      "import": "./dist/hooks/*.js"
+    },
+    "./styles/globals.css": "./dist/globals.css"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "build:dts": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@radix-ui/react-accordion": "^1.2.12",
+    "@radix-ui/react-aspect-ratio": "^1.1.8",
+    "@radix-ui/react-checkbox": "^1.3.3",
+    "@radix-ui/react-collapsible": "^1.1.12",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-hover-card": "^1.1.15",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-progress": "^1.1.8",
+    "@radix-ui/react-radio-group": "^1.3.8",
+    "@radix-ui/react-scroll-area": "^1.2.10",
+    "@radix-ui/react-separator": "^1.1.8",
+    "@radix-ui/react-slider": "^1.3.6",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@radix-ui/react-switch": "^1.2.6",
+    "@radix-ui/react-tabs": "^1.1.13",
+    "@radix-ui/react-toggle": "^1.1.10",
+    "@radix-ui/react-toggle-group": "^1.1.11",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@tanstack/react-table": "^8.21.3",
+    "@tanstack/react-virtual": "^3.13.23",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "date-fns": "^4.1.0",
+    "embla-carousel-react": "^8.6.0",
+    "lucide-react": "^0.577.0",
+    "react-day-picker": "^9.14.0",
+    "react-zoom-pan-pinch": "^4.0.3",
+    "recharts": "^3.8.1",
+    "sonner": "^2.0.7",
+    "tailwind-merge": "^3.5.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0",
+    "tailwindcss": ">=4.0.0"
+  }
+}

package/src/README.md

@@ -0,0 +1,32 @@
+# Design System Home
+
+本資料夾是 design system 的原始碼 + 設計規格 SSOT。
+
+## 子資料夾 charter(建立新檔案前必讀對應子 dir 的 README)
+
+| 子 dir | 收什麼 | 不收什麼 | Charter |
+|--------|-------|---------|---------|
+| `tokens/` | CSS 變數定義 + token spec + token stories | 元件 code、文件撰寫指南 | `tokens/README.md` |
+| `components/` | 每個元件一個 PascalCase folder(內含 tsx / spec / stories) | 平坦 `.md` 檔、cross-cutting rule | `components/README.md` |
+| `patterns/` | runtime UI 佈局 / 互動 primitive(.tsx + .spec.md),多元件 consume | 文件撰寫指南、governance meta rule、taxonomy | `patterns/README.md` |
+| `hooks/` | React hooks(跨 DS 元件共用的 `use-*.ts`) | Claude Code hooks(那屬 `.claude/hooks/`) | N/A |
+| `stories-helpers/` | Storybook 共用 helper(非 runtime,僅 `.stories.tsx` / `.anatomy.stories.tsx` 消費的 anatomy 排版 util 等) | 任何 runtime consume(應用 / 元件 / pattern code 不得 import);runtime primitive 應住 `patterns/` | N/A |
+
+## 本層級(`packages/design-system/src/` 根)只收 `README.md`
+
+所有 DS 內容必屬於某個子 dir(tokens / components / patterns / hooks / stories-helpers)。即使跨 pattern 的 taxonomy(如 4-Family Model)也住在最相關的 pattern topic 資料夾內(`patterns/element-anatomy/element-anatomy.spec.md`)—— 這樣 folder = topic home,不需要頂層 flat 檔案。
+
+若未來真有 scope 橫跨 3+ 子 dir 且不屬任一 topic 的純 meta doc,才重新評估是否加頂層檔(屆時更新本 charter)。
+
+## 不屬於本資料夾的 DS 相關內容
+
+| 內容類型 | 實際位置 |
+|---------|---------|
+| AI 工作流 / workflow guide(寫 story / 做 prototype / audit) | `.claude/skills/<skill>/` |
+| AI 每 session 需要的 signal rule | `CLAUDE.md` |
+| AI session 狀態(audit progress / tech debt) | `~/.claude/projects/.../memory/` |
+| Tool-level 機械檢查 | `.claude/hooks/` |
+
+## 建立新檔案決策
+
+不確定檔案放這裡還是別處 → **先 Read 該目標 dir 的 README.md 再 Write**。這是 CLAUDE.md 的硬規則。

package/src/components/Accordion/accordion.tsx

@@ -0,0 +1,104 @@
+import * as React from 'react'
+import * as AccordionPrimitive from '@radix-ui/react-accordion'
+import { ChevronDown } from 'lucide-react'
+import { cn } from '@/lib/utils'
+
+/**
+ * Accordion — Radix Accordion + 本 DS token
+ *
+ * 結構對齊 shadcn/ui accordion(Accordion / AccordionItem / AccordionTrigger /
+ * AccordionContent),但視覺全改本 DS token。
+ *
+ * ── 視覺差異 vs shadcn 預設 ──
+ * Shadcn 預設 hover 加底線(web 早期 link style),本 DS 改為文字色 tint
+ * (`hover:text-fg-secondary`)——維持現代 SaaS 質感(Notion / Linear / Stripe 皆不用
+ * 底線),但保留 hover 顏色變化作為可點擊提示(user 決策 2026-04-20)。
+ * Chevron 用 Lucide + 本 DS icon size(16px),rotate 動畫 200ms。
+ *
+ * ── 使用情境 ──
+ * FAQ / settings section 收合 / 多區塊表單分組 / 進階選項可隱藏。
+ * 不用於「單純顯示 / 隱藏單一區塊」(那是 Collapsible,本 DS 尚未建立;用 details 或
+ * 自組 toggle),Accordion 是「多個 item 可互斥或獨立收合」的 pattern。
+ */
+
+const Accordion = AccordionPrimitive.Root
+
+const AccordionItem = React.forwardRef<
+  React.ElementRef<typeof AccordionPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Item>
+>(({ className, ...props }, ref) => (
+  <AccordionPrimitive.Item
+    ref={ref}
+    className={cn('border-b border-divider', className)}
+    {...props}
+  />
+))
+AccordionItem.displayName = 'AccordionItem'
+
+const AccordionTrigger = React.forwardRef<
+  React.ElementRef<typeof AccordionPrimitive.Trigger>,
+  React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Trigger>
+>(({ className, children, ...props }, ref) => (
+  <AccordionPrimitive.Header className="flex">
+    <AccordionPrimitive.Trigger
+      ref={ref}
+      className={cn(
+        'flex flex-1 items-center justify-between gap-2',
+        'py-4 text-body font-medium text-foreground text-left',
+        'transition-colors hover:text-fg-secondary',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+        // AccordionTrigger 單一 text-style 列 → semantic `text-fg-disabled`(非 opacity);Button canonical 對齊
+        'disabled:text-fg-disabled disabled:pointer-events-none',
+        "[&[data-state=open]>svg]:rotate-180",
+        className,
+      )}
+      {...props}
+    >
+      {children}
+      <ChevronDown
+        size={16}
+        className="shrink-0 text-fg-muted transition-transform duration-200"
+        aria-hidden
+      />
+    </AccordionPrimitive.Trigger>
+  </AccordionPrimitive.Header>
+))
+AccordionTrigger.displayName = 'AccordionTrigger'
+
+const AccordionContent = React.forwardRef<
+  React.ElementRef<typeof AccordionPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Content>
+>(({ className, children, ...props }, ref) => (
+  <AccordionPrimitive.Content
+    ref={ref}
+    className={cn(
+      'overflow-hidden text-body text-fg-secondary',
+      'data-[state=closed]:animate-accordion-up data-[state=open]:animate-accordion-down',
+    )}
+    {...props}
+  >
+    <div className={cn('pb-4', className)}>{children}</div>
+  </AccordionPrimitive.Content>
+))
+AccordionContent.displayName = 'AccordionContent'
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const accordionMeta = {
+  component: 'Accordion',
+  family: null, // non-family composite / overlay / layout
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: [],
+    fg: ['text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],
+    ring: ['ring-ring'],
+  },
+} as const
+
+export { Accordion, AccordionItem, AccordionTrigger, AccordionContent }

package/src/components/Alert/alert.tsx

@@ -0,0 +1,188 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import * as React from 'react'
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from '@/lib/utils'
+import { Notice, useInverseTheme, SUBTLE_ICON_COLOR, type NoticeVariant } from '@/design-system/components/Notice/notice'
+
+/**
+ * Alert — inline / fixed 通知
+ *
+ * ── data-theme 必須搭配 text-foreground ──
+ * CSS color 從 body 繼承已解析值,data-theme 只改 --foreground 不改 color。
+ * 在 theme boundary 設 text-foreground 強制 re-resolve。
+ *
+ * ── Appearance ──
+ * subtle: 淺底色 + 四邊 1px border(色相 hover 色)。不設 data-theme,跟隨頁面。
+ * solid: 跟 Toast 對齊:
+ *   neutral → data-theme={inverse} + bg-surface-raised（同層翻轉）
+ *   info/success/error → bg on outer, data-theme="dark" on inner
+ *   warning → bg on outer, data-theme="light" on inner
+ *
+ * ── Placement ──
+ * inline: rounded-md(card-level 圓角,非 overlay — 因 Alert 在頁面流內,非 floating)
+ * fixed: 無圓角,full-width,無 border
+ */
+
+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)]',
+}
+
+const SOLID_HUE_BG: Record<string, string> = {
+  info: 'bg-info',
+  success: 'bg-success',
+  warning: 'bg-warning',
+  error: 'bg-error',
+}
+
+const SOLID_HUE_THEME: Record<string, string> = {
+  info: 'dark',
+  success: 'dark',
+  warning: 'light',
+  error: 'dark',
+}
+
+const alertVariants = cva('w-full overflow-hidden', {
+  variants: {
+    placement: {
+      inline: 'rounded-md',
+      fixed: 'rounded-none border-none',
+    },
+  },
+  defaultVariants: { placement: 'inline' },
+})
+
+export interface AlertProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'>,
+    VariantProps<typeof alertVariants> {
+  variant?: NoticeVariant
+  appearance?: 'subtle' | 'solid'
+  title: React.ReactNode
+  description?: React.ReactNode
+  endContent?: React.ReactNode
+  dismissible?: boolean
+  onDismiss?: () => void
+}
+
+// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
+const Alert = React.forwardRef<HTMLDivElement, AlertProps>(
+  (
+    {
+      variant = 'neutral',
+      appearance = 'subtle',
+      placement,
+      title,
+      description,
+      endContent,
+      dismissible = true,
+      onDismiss,
+      className,
+      ...props
+    },
+    ref,
+  ) => {
+    const inverseTheme = useInverseTheme()
+    const isSolid = appearance === 'solid'
+    const iconClassName = !isSolid ? SUBTLE_ICON_COLOR[variant] : undefined
+
+    // ── Live region 由 wrapping consumer 擁有(WAI-ARIA + Atlassian / Polaris / Material 共識) ──
+    // Alert 是 outer host —— 自己擁有 role + aria-live;Notice(inner layout)不再帶 role,
+    // 避免 nested live region 造成 screen reader 重複朗讀。
+    // - error / warning → role="alert" + aria-live="assertive"(中斷,使用者必須立刻知道)
+    // - info / success / neutral → role="status" + aria-live="polite"(空閒朗讀,不打斷)
+    const isCritical = variant === 'error' || variant === 'warning'
+    const liveRole = isCritical ? 'alert' : 'status'
+    const liveLevel = isCritical ? 'assertive' : 'polite'
+
+    // placement="fixed" 用 loose px(density-aware)讓 Alert 嵌在更大佈局內時跟周圍
+   // loose-padding 元素(Toolbar / BulkActionBar / DataTable 等)左右對齊。
+    // py 維持 py-3 fixed(notification banner family canonical,垂直不隨 density)。
+    const noticeEl = (
+      <Notice
+        variant={variant}
+        title={title}
+        description={description}
+        endContent={endContent}
+        dismissible={dismissible}
+        onDismiss={onDismiss}
+        iconClassName={iconClassName}
+        className={placement === 'fixed' ? 'px-[var(--layout-space-loose)]' : undefined}
+      />
+    )
+
+    // ── Subtle ──
+    if (!isSolid) {
+      return (
+        <div
+          ref={ref}
+          role={liveRole}
+          aria-live={liveLevel}
+          className={cn(alertVariants({ placement }), SUBTLE_CONTAINER[variant], className)}
+          {...props}
+        >
+          {noticeEl}
+        </div>
+      )
+    }
+
+    // ── Solid neutral (inverse: bg + theme 同層) ──
+    if (variant === 'neutral') {
+      return (
+        <div
+          ref={ref}
+          role={liveRole}
+          aria-live={liveLevel}
+          data-theme={inverseTheme}
+          className={cn(alertVariants({ placement }), 'bg-surface-raised text-foreground', className)}
+          {...props}
+        >
+          {noticeEl}
+        </div>
+      )
+    }
+
+    // ── Solid 有色相: bg outer + data-theme inner ──
+    return (
+      <div
+        ref={ref}
+        role={liveRole}
+        aria-live={liveLevel}
+        className={cn(alertVariants({ placement }), SOLID_HUE_BG[variant], className)}
+        {...props}
+      >
+        <div data-theme={SOLID_HUE_THEME[variant]} className="text-foreground">
+          {noticeEl}
+        </div>
+      </div>
+    )
+  },
+)
+Alert.displayName = 'Alert'
+
+// Story auto-compile metadata — Phase 2 fill(2026-05-15)
+// Variants = NoticeVariant 5 hues(prop name `variant`,cva 內僅 placement,色相由 SUBTLE_CONTAINER / SOLID_HUE_BG map 控)
+// Sizes = none(Alert 視覺尺寸繼承 Notice primitive,不隨 size 變;見 spec「為何無 SizeMatrix」)
+export const alertMeta = {
+  component: 'Alert',
+  family: null, // non-family composite / overlay / layout
+  variants: {
+    neutral: { purpose: '中性提示(系統公告、非緊急說明);無情緒色' },
+    info: { purpose: '資訊性提示(版本更新、流程說明);藍色 hue' },
+    success: { purpose: '成功狀態的持久性宣告(綁定生效、付款完成需保留確認)' },
+    warning: { purpose: '警告但非阻斷(方案到期、需更新付款方式);最高頻' },
+    error: { purpose: '錯誤但非阻斷(系統錯誤可重試、API 失敗摘要);aria-live=assertive' },
+  },
+  sizes: {},
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  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'],
+    ring: [],
+  },
+  defaultVariant: 'neutral',
+} as const
+
+export { Alert, alertVariants }

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

@@ -0,0 +1,198 @@
+// AppShell stories 共用 helper(對齊 sidebar.stories.tsx IconCollapse baseline)
+// @story-baseline: packages/design-system/src/components/Sidebar/sidebar.stories.tsx#IconCollapse
+//
+// **嚴格**對齊既有 production-grade Sidebar story baseline,避免 AppShell stories 跟
+// Sidebar 既有範例視覺偏移(2026-05-20 user 抓 anti-drift)。
+// Showcase + Anatomy stories 全部 consume 此 file 不重發明 simplified mock。
+
+import {
+  Inbox,
+  Calendar,
+  Settings,
+  Users,
+  BarChart3,
+  LayoutDashboard,
+} from 'lucide-react'
+import {
+  Sidebar,
+  SidebarHeader,
+  SidebarContent,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarMenu,
+  SidebarMenuItem,
+  SidebarMenuButton,
+  SidebarFooter,
+  SidebarTrigger,
+} from '@/design-system/components/Sidebar/sidebar'
+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'
+
+// ── MAIN_NAV(對齊 sidebar.stories.tsx baseline)────────────────────────
+
+export const MAIN_NAV = [
+  { id: 'dashboard', label: 'Dashboard', icon: LayoutDashboard },
+  { id: 'inbox', label: 'Inbox', icon: Inbox },
+  { id: 'team', label: 'Team', icon: Users },
+  { id: 'insights', label: 'Insights', icon: BarChart3 },
+  { id: 'calendar', label: 'Calendar', icon: Calendar },
+  { id: 'settings', label: 'Settings', icon: Settings },
+] as const
+
+// ── WorkspaceBrand(對齊 sidebar.stories.tsx)────────────────────────────
+
+// 2026-05-21 v15 — Chrome header avatar SSOT, semantic-correct revise(per user 抓 v14
+// RowSizeProvider hijack 是 semantic 漂移 + 「想辦法在語言正確下修到正確」directive):
+//
+// Chrome header **不是 row context**(per `item-anatomy.spec.md:550` 規則 scope 是 row primitive
+// consumer + `header-canonical.spec.md` 4.5 chrome header avatar SSOT)。Chrome header avatar
+// 是 spec-level canonical 24px、density-fixed、row-size-fixed,跟 row-anatomy 的 sm/md/lg
+// lookup 邏輯無關。
+//
+// 因此 chrome header 內 avatar **用 raw `<Avatar size={24}>`,不用 `<ItemAvatar>`**:
+//   - ItemAvatar 透過 RowSizeContext lookup 是 row primitive(Sidebar / SelectMenu / TreeView 等)
+//     的 anatomy helper,目的避免 asChild consumer 寫死跨 row size 漂移
+//   - Chrome header 沒有 sm/md/lg row size 概念,無 lookup 需求,用 raw Avatar 才語義正確
+//   - 父 `<div flex items-center>` 已 provide 縱向對齊,ItemPrefix wrapper(`h-[1lh]`)冗餘
+//
+// SSOT 鎖定:`<Avatar size={24}>` 對應 `--chrome-header-avatar-size: 1.5rem` token
+// (`header-canonical.css`)+ `header-canonical.spec.md` 4.5 canonical「24px raw Avatar」。
+// 公式端透過 var() 連動;JS 端透過 spec authority + comment cite 連動。改 24 → 同步 token + 此 hardcode。
+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` */}
+    <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)────────────────────────────────
+
+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>
+    </SidebarMenuItem>
+  </SidebarMenu>
+)
+
+// ── 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 慣例)。
+
+export function AcmeSidebar({
+  viewportInsetTop,
+  includeWorkspaceBrand = true,
+}: {
+  viewportInsetTop?: string
+  includeWorkspaceBrand?: boolean
+} = {}) {
+  return (
+    <Sidebar collapsible="icon" viewportInsetTop={viewportInsetTop}>
+      {includeWorkspaceBrand && (
+        <SidebarHeader>
+          <WorkspaceBrand />
+        </SidebarHeader>
+      )}
+      <SidebarContent>
+        <SidebarGroup>
+          <SidebarGroupContent>
+            <SidebarMenu>
+              {MAIN_NAV.map((item) => (
+                <SidebarMenuItem key={item.id}>
+                  <SidebarMenuButton
+                    id={item.id}
+                    startIcon={item.icon}
+                    tooltip={item.label}
+                  >
+                    {item.label}
+                  </SidebarMenuButton>
+                </SidebarMenuItem>
+              ))}
+            </SidebarMenu>
+          </SidebarGroupContent>
+        </SidebarGroup>
+      </SidebarContent>
+      <SidebarFooter>
+        <UserFooter />
+      </SidebarFooter>
+    </Sidebar>
+  )
+}
+
+// ── GlobalHeader(primary-header mode 用,跨頁 chrome:WorkspaceBrand 左 + 跨頁 actions 右)──
+// 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 段:
+// top-level chrome → 自畫 bg-surface)。
+
+export function GlobalHeader({ rightSlot }: { rightSlot?: React.ReactNode } = {}) {
+  // 2026-05-21 v2 ship Option B(per user「primary header toggle 為了與 sidebar menu item
+  // startIcon 水平對齊...container 寬度 = sidebar-width-icon」+ Issue 2 geometry formula 落地):
+  // 用 ChromeHeader `leadingRail` slot(width = `--sidebar-width-icon` = 2*loose + icon-size)。
+  // Toggle center x = rail 寬度中點 = sidebar collapsed icon center x = 完美 vertical 對齊。
+  return (
+    <ChromeHeader className="bg-surface" leadingRail={<SidebarTrigger />}>
+      <WorkspaceBrand />
+      <div className="flex-1" />
+      {rightSlot}
+    </ChromeHeader>
+  )
+}
+
+// ── PageHeader(top-level chrome header,消費 ChromeHeader primitive)──
+// 2026-05-20 migrate 消費 ChromeHeader,撤回自刻 `<header>` + 重複 className
+// (per header-canonical.spec.md「6. Background ownership」段「Top-level chrome
+// header 自畫 bg-surface」+「Element canonical」段「ChromeHeader 內部用 `<header>`」)。
+// global header aside toggle 已撤回(2026-05-20 user「圖二 global header 不該有」)— 由
+// DataTable rowActions Info icon 主入口(row-driven)取代,page header 純 title。
+
+export function PageHeader({
+  title,
+  tabsSlot,
+  includeSidebarTrigger = true,
+}: {
+  title: string
+  /**
+   * Optional tabs row(per header-canonical.spec.md W1-W6 + Background ownership 段)。
+   * 提供時 ChromeHeader 自動 column mode + suppress border + delegate paint 給 TabsList。
+   */
+  tabsSlot?: React.ReactNode
+  /**
+   * 是否含 SidebarTrigger(2026-05-21 加 per user「primary-header mode 的 sidebar toggle 應該只放在 primary header 才對」)。
+   * - `primary-sidebar` mode = true(預設):PageHeader 是 chrome 第一層,trigger 自然在這
+   * - `primary-header` mode = false:SidebarTrigger 已在 GlobalHeader,PageHeader 不該重複
+   */
+  includeSidebarTrigger?: boolean
+}) {
+  return (
+    <ChromeHeader className="bg-surface" tabsSlot={tabsSlot}>
+      {includeSidebarTrigger && <SidebarTrigger />}
+      <h1 className="text-body-lg font-medium flex-1 truncate">{title}</h1>
+    </ChromeHeader>
+  )
+}