@qijenchen/design-system 0.1.0-beta.10

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>
+  )
+}

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

@@ -0,0 +1,364 @@
+// @benchmark-cited: 2026-05-19 — Mantine AppShell / Ant Layout / Material 3 Drawer / Atlassian Navigation System cite in app-shell.spec.md frontmatter.
+/**
+ * AppShell — web service page-level layout primitive。
+ *
+ * 組合 Sidebar + ChromeHeader + Aside + main 成完整 page shell。SSOT 邊界:本 pattern only
+ * own slot composition + layout mode + Aside responsive mode;不 own sidebar / header /
+ * sheet 視覺(各自 spec own)。
+ *
+ * 對齊 Mantine AppShell compound API + Ant Layout slot 模式 + Material 3 standard/modal
+ * drawer canonical(per spec.md frontmatter cite)。
+ *
+ * Spec SSOT:`patterns/app-shell/app-shell.spec.md`
+ */
+
+import * as React from 'react'
+import { X as XIcon } from 'lucide-react'
+import {
+  Sheet,
+  SheetContent,
+} from '@/design-system/components/Sheet/sheet'
+import { Button } from '@/design-system/components/Button/button'
+import { ScrollArea } from '@/design-system/components/ScrollArea/scroll-area'
+import { ChromeHeader } from '@/design-system/patterns/header-canonical/chrome-header'
+import { useIsNarrowViewport } from '@/design-system/hooks/use-is-narrow-viewport'
+import { cn } from '@/lib/utils'
+
+// ── Types ────────────────────────────────────────────────────────────────────
+
+type AppShellLayout = 'primary-sidebar' | 'primary-header'
+
+export interface AppShellProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** primary-sidebar (Linear/Notion 派) | primary-header (GitHub/Slack 派);預設 primary-sidebar */
+  layout?: AppShellLayout
+  /** Sidebar 元素(必傳 Sidebar primitive,per Consumer 紀律)*/
+  sidebar?: React.ReactNode
+  /**
+   * Local page header(永遠 render 在 main column 頂部,當前頁 actions / breadcrumb / page-level filter)。
+   * 兩 layout mode 都會 render 此 slot — `primary-header` mode 多了 globalHeader 在上方,
+   * **不取代** local header(per 2026-05-20 user clarification「primary-header = primary-sidebar + 一條 global header」)。
+   */
+  header?: React.ReactNode
+  /**
+   * Global header(僅 `primary-header` mode render)。橫跨整 viewport 的頂部 bar:
+   * account avatar / workspace switcher / global search / notifications。
+   * 對齊 GitHub top nav / Slack workspace bar / Gmail logo bar 慣例。
+   * `primary-sidebar` mode 傳此 prop 會被忽略。
+   */
+  globalHeader?: React.ReactNode
+  /** Aside 元素(`<AppShellAside>` sub-component);可選 */
+  aside?: React.ReactNode
+  /** Aside open state(modal mode 必須)*/
+  asideOpen?: boolean
+  onAsideOpenChange?: (open: boolean) => void
+  /** Main content;`<main>` landmark + padding=0 */
+  children: React.ReactNode
+}
+
+export interface AppShellAsideProps {
+  /** Required:modal mode 走 Sheet → aria-labelledby 強制,per sheet.spec.md:98 */
+  title: string
+  /** Width(number 或 breakpoint-keyed object);clamp min:240 max:640 */
+  width?: number | { md?: number; xl?: number }
+  /** Children content */
+  children: React.ReactNode
+  className?: string
+}
+
+// ── Context ──────────────────────────────────────────────────────────────────
+
+interface AppShellContextValue {
+  layout: AppShellLayout
+  asideOpen: boolean
+  setAsideOpen: (open: boolean) => void
+  isMobile: boolean
+}
+
+const AppShellContext = React.createContext<AppShellContextValue | null>(null)
+
+function useAppShell(): AppShellContextValue {
+  const ctx = React.useContext(AppShellContext)
+  if (!ctx) throw new Error('AppShellAside must be used within <AppShell>')
+  return ctx
+}
+
+// Mobile breakpoint:**消費既有 `useIsNarrowViewport`**(`hooks/use-is-narrow-viewport.ts` SSOT,
+// 768px,跟 Sidebar SSOT 同源)— 不發明 local hook,per codex Layer B D2/D4 verdict 避 drift。
+
+// xl breakpoint(對齊 Tailwind v4 xl = 1280px,DS-wide consensus)
+const XL_BREAKPOINT_PX = 1280
+
+function useIsXl(): boolean {
+  const [isXl, setIsXl] = React.useState<boolean>(() => {
+    if (typeof window === 'undefined') return false
+    return window.matchMedia(`(min-width: ${XL_BREAKPOINT_PX}px)`).matches
+  })
+
+  React.useEffect(() => {
+    const mq = window.matchMedia(`(min-width: ${XL_BREAKPOINT_PX}px)`)
+    const handler = (e: MediaQueryListEvent) => setIsXl(e.matches)
+    mq.addEventListener('change', handler)
+    return () => mq.removeEventListener('change', handler)
+  }, [])
+
+  return isXl
+}
+
+// ── Width resolve(consumer 自傳 + clamp 240-640)──────────────────────────────
+
+const ASIDE_WIDTH_MIN = 240
+const ASIDE_WIDTH_MAX = 640
+const ASIDE_WIDTH_DEFAULT = 320
+
+function resolveAsideWidth(width: AppShellAsideProps['width'], isXl: boolean): number {
+  if (typeof width === 'number') {
+    return Math.max(ASIDE_WIDTH_MIN, Math.min(ASIDE_WIDTH_MAX, width))
+  }
+  if (width && typeof width === 'object') {
+    // breakpoint-keyed:xl viewport(≥1280px)用 xl,否則 md
+    const v = (isXl ? width.xl ?? width.md : width.md) ?? ASIDE_WIDTH_DEFAULT
+    return Math.max(ASIDE_WIDTH_MIN, Math.min(ASIDE_WIDTH_MAX, v))
+  }
+  return ASIDE_WIDTH_DEFAULT
+}
+
+// ── Skip-to-main link(a11y WCAG 2.4.1)───────────────────────────────────────
+
+function SkipToMain() {
+  return (
+    <a
+      href="#app-shell-main"
+      className={cn(
+        'sr-only focus:not-sr-only',
+        'focus:fixed focus:top-2 focus:left-2 focus:z-50',
+        'focus:px-3 focus:py-2 focus:rounded-md',
+        'focus:bg-surface focus:text-foreground focus:shadow-[var(--elevation-200)]',
+        'focus:outline-none focus:ring-2 focus:ring-primary'
+      )}
+    >
+      Skip to main content
+    </a>
+  )
+}
+
+// ── AppShell root ────────────────────────────────────────────────────────────
+
+const AppShell = React.forwardRef<HTMLDivElement, AppShellProps>(
+  (
+    {
+      layout = 'primary-sidebar',
+      sidebar,
+      header,
+      globalHeader,
+      aside,
+      asideOpen: asideOpenProp,
+      onAsideOpenChange,
+      children,
+      className,
+      ...props
+    },
+    ref
+  ) => {
+    const [asideOpenInternal, setAsideOpenInternal] = React.useState(false)
+    const isControlled = asideOpenProp !== undefined
+    const asideOpen = isControlled ? asideOpenProp : asideOpenInternal
+
+    const setAsideOpen = React.useCallback(
+      (open: boolean) => {
+        if (!isControlled) setAsideOpenInternal(open)
+        onAsideOpenChange?.(open)
+      },
+      [isControlled, onAsideOpenChange]
+    )
+
+    const isMobile = useIsNarrowViewport()
+
+    // ── Keyboard: cmd+. toggle aside ──
+    // ⌘B sidebar toggle by Sidebar SSOT(本 component 不重覆 register)
+    React.useEffect(() => {
+      const onKey = (e: KeyboardEvent) => {
+        if (e.key === '.' && (e.metaKey || e.ctrlKey)) {
+          e.preventDefault()
+          setAsideOpen(!asideOpen)
+        }
+      }
+      window.addEventListener('keydown', onKey)
+      return () => window.removeEventListener('keydown', onKey)
+    }, [asideOpen, setAsideOpen])
+
+    const ctxValue = React.useMemo<AppShellContextValue>(
+      () => ({ layout, asideOpen, setAsideOpen, isMobile }),
+      [layout, asideOpen, setAsideOpen, isMobile]
+    )
+
+    // ── Layout grid(2 mode)──
+    // primary-sidebar:
+    //   row1: [sidebar (頂天)][main col (header + main)][aside (頂天)]
+    // primary-header:
+    //   row1: [header (橫跨整 viewport, banner role)]
+    //   row2: [sidebar][main][aside]
+
+    // AppShellAside 自決 inline vs modal mode(via AppShellContext.isMobile)。
+    // AppShell 一律只 render `{aside}` 一次,AppShellAside 內部根據 isMobile 決定 render 形式。
+
+    if (layout === 'primary-header') {
+      // primary-header layout(2026-05-21 v2 — user clarification「primary-header = primary-sidebar + 一條 global header」):
+      // 結構:row1 globalHeader(全寬 global bar)/ row2 [sidebar][main col: localHeader + main][aside]
+      // - globalHeader = 跨頁 account / workspace switcher / notifications(對齊 GitHub top nav / Slack workspace bar)
+      // - header = local page header,**仍存在**(per page actions / breadcrumb,對齊 GitHub repo header / Slack channel header / Gmail email-list toolbar 2-layer 慣例)
+      // Consumer 必傳 `<Sidebar viewportInsetTop="var(--chrome-header-height)">` 讓 sidebar 從 globalHeader 下方起算。
+      return (
+        <AppShellContext.Provider value={ctxValue}>
+          <div
+            ref={ref}
+            className={cn('flex h-svh w-full flex-col overflow-hidden bg-canvas', className)}
+            {...props}
+          >
+            <SkipToMain />
+            {/* Row 1:Global header(account / workspace switcher / notifications,橫跨整 viewport)*/}
+            {globalHeader && <div className="flex-shrink-0">{globalHeader}</div>}
+            {/* Row 2:[sidebar][main col][aside]horizontal row */}
+            <div className="flex flex-1 min-h-0 w-full">
+              {sidebar}
+              {/* Main column:local header + main content(per user model「primary-header = primary-sidebar + global header」)*/}
+              <div className="flex flex-col flex-1 min-w-0 min-h-0 overflow-hidden">
+                {header && <div className="flex-shrink-0">{header}</div>}
+                <main
+                  id="app-shell-main"
+                  tabIndex={-1}
+                  className="flex-1 min-w-0 min-h-0 overflow-y-auto focus:outline-none"
+                >
+                  {children}
+                </main>
+              </div>
+              {aside}
+            </div>
+          </div>
+        </AppShellContext.Provider>
+      )
+    }
+
+    // primary-sidebar layout
+    return (
+      <AppShellContext.Provider value={ctxValue}>
+        <div
+          ref={ref}
+          className={cn('flex h-svh w-full overflow-hidden bg-canvas', className)}
+          {...props}
+        >
+          <SkipToMain />
+          {/* Sidebar — 頂天 */}
+          {sidebar}
+          {/* Main column(header + main 垂直堆)*/}
+          <div className="flex flex-col flex-1 min-w-0 min-h-0 overflow-hidden">
+            {header && (
+              // Header 在 main column 內(main col sibling,非 main descendant)→ 跟 W3C ARIA in HTML
+              // banner rule 對照:`<header>` 在 main descendant 才不是 banner,本 ChromeHeader 是 <div>
+              // 所以本來就不會被 banner role 計算。仍包 wrap div not <header> 確保不無意觸發 banner。
+              <div className="flex-shrink-0">{header}</div>
+            )}
+            <main
+              id="app-shell-main"
+              tabIndex={-1}
+              className="flex-1 min-h-0 overflow-y-auto focus:outline-none"
+            >
+              {children}
+            </main>
+          </div>
+          {/* Aside slot — desktop inline OR mobile Sheet,內部自決 */}
+          {aside}
+        </div>
+      </AppShellContext.Provider>
+    )
+  }
+)
+AppShell.displayName = 'AppShell'
+
+// ── AppShellAside sub-component ──────────────────────────────────────────────
+
+/**
+ * AppShellAside — right panel:standard inline(desktop) vs modal overlay(mobile)。
+ *
+ * Desktop(viewport ≥ 768px):
+ *   - Render 直接放 layout grid 右側(asideOpen=true 才 mount,close hide via parent)
+ *   - 不蓋 mask / background 可操作 / 佔 layout 寬
+ *   - Vertical extent:primary-sidebar → 頂天立地 / primary-header → header 下方
+ *
+ * Mobile(viewport < 768px):
+ *   - Render 走 Sheet primitive(side="right",per sheet.spec.md)
+ *   - Mask 蓋 / background 不可操作 / 不佔 layout 寬
+ *   - title 強制(aria-labelledby per sheet.spec.md:98)
+ */
+const AppShellAside = React.forwardRef<HTMLElement, AppShellAsideProps>(
+  ({ title, width, children, className }, ref) => {
+    const { asideOpen, setAsideOpen, isMobile } = useAppShell()
+    const isXl = useIsXl()
+    const resolvedWidth = resolveAsideWidth(width, isXl)
+
+    // Shared frame:always-on header(title + close X)+ body(ScrollArea + layoutSpace 規則 1B 父層 padding)
+    // 對齊 codex Layer B 2026-05-20「container mode 可變,panel role/content 不該變」+ Notion/Figma right
+    // panel 共識(modal vs inline 結構相同,host wrapper 不同)。
+    // 2026-05-20 migrate 消費 ChromeHeader primitive(撤回自刻 + 撤回 bg-surface 疊加 — 對齊
+    // `header-canonical.spec.md`「6. Background ownership」段「Nested chrome header 透明繼承
+    // parent」:aside container 自身已 bg-surface,內 header 不該再畫 bg 避免疊加 drift)。
+    const frame = (
+      <>
+        <ChromeHeader>
+          <h2 className="text-body-lg font-medium flex-1 truncate">{title}</h2>
+          <Button
+            iconOnly
+            dismiss
+            size="sm"
+            startIcon={XIcon}
+            aria-label="關閉"
+            onClick={() => setAsideOpen(false)}
+          />
+        </ChromeHeader>
+        <ScrollArea className="flex-1 min-h-0">
+          {children}
+        </ScrollArea>
+      </>
+    )
+
+    // Modal mode(mobile)— Sheet from right
+    if (isMobile) {
+      return (
+        <Sheet open={asideOpen} onOpenChange={setAsideOpen}>
+          <SheetContent
+            side="right"
+            className="w-[min(90vw,var(--app-shell-aside-modal-width))] flex flex-col p-0 [&>button]:hidden"
+            style={{ ['--app-shell-aside-modal-width' as string]: `${resolvedWidth}px` }}
+          >
+            {frame}
+          </SheetContent>
+        </Sheet>
+      )
+    }
+
+    // Standard inline mode(desktop)
+    if (!asideOpen) return null
+
+    return (
+      <aside
+        ref={ref}
+        aria-label={title}
+        className={cn(
+          'flex flex-col h-full min-h-0 overflow-hidden',
+          'bg-surface border-l border-divider',
+          className
+        )}
+        style={{ width: resolvedWidth }}
+      >
+        {frame}
+      </aside>
+    )
+  }
+)
+AppShellAside.displayName = 'AppShellAside'
+
+// ── Exports ──────────────────────────────────────────────────────────────────
+
+// code-quality-allow: dead-export useAppShell — public compound API hook(consumer 可自拼 custom aside layout,
+// 對齊 Radix `useDialogContext` / MUI `useFormControl` 慣例)。內部 AppShellAside 已消費(L294),
+// audit script 抓「無 cross-file import」是 false positive(2026-05-21 D2 codify)。
+export { AppShell, AppShellAside, useAppShell }

package/src/components/AspectRatio/aspect-ratio.tsx

@@ -0,0 +1,58 @@
+// @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 * as AspectRatioPrimitive from '@radix-ui/react-aspect-ratio'
+
+/**
+ * AspectRatio — 固定長寬比容器(Radix AspectRatio primitive 薄包裝)
+ *
+ * 世界級對照:shadcn `AspectRatio` / Ant 無獨立元件(CSS 方案)/ Material 無
+ *
+ * ── 為什麼需要 ──
+ * CSS `aspect-ratio` 屬性雖然現代瀏覽器都支援,但 Radix primitive 提供 SSR-safe
+ * padding-bottom 方案 + consistent API,避免邊緣 bug(image 未載入時容器坍塌 /
+ * content-fit 差異)。保 safe + 一致視覺。
+ *
+ * ── 標準 ratio(DS 慣例) ──
+ * 16/9  — 寬螢幕影片、onboarding feature tour 截圖(Coachmark media 預設)
+ * 4/3   — 老電視 / 照片基本 ratio、產品 thumbnail
+ * 1/1   — Avatar / 方形貼文預覽 / icon preview
+ * 3/4   — 直式照片(人物 portrait)
+ * 21/9  — Ultra-wide banner(hero section)
+ *
+ * Consumer 傳 `ratio={n/m}` 數字計算(如 16/9 = 1.7777)。
+ *
+ * ── 常見消費者 ──
+ * Coachmark media / Carousel item image / Card thumbnail(未來)/ Chart preview
+ */
+
+export type AspectRatioProps = React.ComponentPropsWithoutRef<typeof AspectRatioPrimitive.Root>
+
+// shadcn canonical:顯式 forwardRef + displayName(雖 Radix primitive 已 forwardRef,
+// 此 wrapper 確保本 DS 每個 named export 在 Inspector 顯示正確 displayName,
+// 且 props passthrough + ref 行為在 code 層面明確可見)
+const AspectRatio = React.forwardRef<
+  React.ElementRef<typeof AspectRatioPrimitive.Root>,
+  AspectRatioProps
+>((props, ref) => <AspectRatioPrimitive.Root ref={ref} {...props} />)
+AspectRatio.displayName = 'AspectRatio'
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const aspectRatioMeta = {
+  component: 'AspectRatio',
+  family: null, // non-family composite / overlay / layout
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: [],
+    fg: [],
+    ring: [],
+  },
+} as const
+
+export { AspectRatio }