@qijenchen/design-system 0.1.0-beta.10

package/src/patterns/header-canonical/chrome-header.tsx

@@ -0,0 +1,175 @@
+import * as React from 'react'
+import { cn } from '@/lib/utils'
+
+/**
+ * @internal — DS-internal primitive(2026-05-23 per `.claude/rules/ui-development.md` Public vs Internal canonical)。
+ * end-user app 直接 render `<ChromeHeader />` 無 functioning UI;由 Sidebar / FileViewer / Dialog / Sheet / Popover 等 DS 元件 wrap 消費。
+ *
+ * ChromeHeader — Fixed-height chrome header primitive(Layout Family B,header-canonical.spec.md)
+ *
+ * ── 定位 ──
+ * Page chrome 級 header 共用 primitive。封裝重複 contract:
+ *   flex items-center gap-2 shrink-0 h-[var(--chrome-header-height)] border-b border-divider px-[var(--layout-space-loose)]
+ *
+ * Consumers:Sidebar / FileViewer Toolbar / FileViewer InfoPanel / 未來 page top bar / Drawer
+ * 跟 SurfaceHeader(overlay padding-based)是兩個並存家族(per header-canonical.spec.md L23-30)。
+ *
+ * ── 實作基礎 ──
+ * 消費:--chrome-header-height(48/56 density-responsive)/ --layout-space-loose / border-divider
+ * 對應 pattern:patterns/header-canonical
+ *
+ * ── 消費的 SSOT ──
+ * - tokens: [--chrome-header-height, --layout-space-loose, --divider]
+ * - patterns: [header-canonical(本 pattern), overlay-surface(姊妹 SurfaceHeader)]
+ * - spec refs: patterns/header-canonical/header-canonical.spec.md(L23-30 家族區分 / W1 border / W3 tabs size / Layer 3 ChromeHeader API)
+ *
+ * ── API(per M31 codex 比稿 Step 5 — narrow API,避免 M21 prop variant 風險)──
+ * withTabs?: boolean(預設 false)
+ *   true → 移除自身 border-b,delegate paint 給 TabsList(per W1「Header semantic owner / TabsList paint owner in withTabs state」)
+ * lockDensity?: 'inherit' | 'lg'(預設 'inherit')
+ *   'inherit' → 跟 page density(html[data-density] 自動)
+ *   'lg' → 強制 lg(viewer-fullscreen-chrome escape hatch,FileViewer 永遠 lg-equivalent design intent)
+ *
+ * 不開:density?: 'md' | 'lg' 自由 prop。M21 違反 — 任意 density 等於 cva-on-pattern。
+ */
+export interface ChromeHeaderProps
+  extends React.HTMLAttributes<HTMLElement> {
+  /**
+   * 是否內含 Tabs。
+   * true(無 tabsSlot)→ 移除自身 border-b,consumer 自畫。
+   * 若提供 tabsSlot,自動 column mode + auto suppress border。
+   * 對應 patterns/header-canonical/header-canonical.spec.md W1
+   */
+  withTabs?: boolean
+  /**
+   * Tabs row slot(2026-05-18 加 per W2/W4 真實能用 + user-mandated fix)。
+   * 提供時 ChromeHeader 自動 column 結構:
+   *   row 1 = children(h-chrome-header-height 固定,px-loose,跟 single-row 模式同)
+   *   row 2 = tabsSlot 包在 `<div px-loose border-b border-divider>`
+   *           ↑ wrapper 提供 W2 padding inheritance + W1 全寬 paint(一條線)
+   *
+   * Consumer 傳:`tabsSlot={<TabsList>...</TabsList>}`,TabsContent 放 ChromeHeader 之外。
+   * Standalone Tabs(無 chrome header)該直接用 `<TabsList>` 不需 wrapper。
+   *
+   * 提供 tabsSlot 自動 withTabs=true,不需另傳 prop。
+   */
+  tabsSlot?: React.ReactNode
+  /**
+   * 是否鎖死 lg density(viewer-fullscreen chrome 用)。
+   * 'inherit'(預設)→ 跟 page density
+   * 'lg' → 強制 chrome-header-height lg(56)
+   * 對應 patterns/header-canonical/header-canonical.spec.md Layer 3 API
+   */
+  lockDensity?: 'inherit' | 'lg'
+  /**
+   * Leading rail slot(2026-05-21 ship per AppShell primary-header globalHeader 用例,
+   * codex M31 Layer C 建議 codify into ChromeHeader API):
+   * 固定寬度 = `var(--sidebar-width-icon)` 的左邊容器,內 `justify-center` 排列。
+   *
+   * 用途:primary-header globalHeader 左側 SidebarTrigger,跟 sidebar 收合 icon 完美水平對齊
+   * (sidebar 收合 width = sidebar-width-icon,toggle container 同寬 = toggle center x = sidebar
+   * collapsed icon center x = perfect alignment)。
+   *
+   * 對齊 GitHub global nav 左側固定寬度 logo 區 / Slack thin workspace rail 慣例。
+   * 提供時自動結構:
+   *   row1: [leadingRail (width=sidebar-width-icon)] [children (px-loose flex-1)]
+   * 不提供時 fallback 預設 single-row(全 px-loose)。
+   *
+   * 與 tabsSlot 互斥(tabsSlot 啟動 column mode,本 prop 不生效)。
+   */
+  leadingRail?: React.ReactNode
+}
+
+export const ChromeHeader = React.forwardRef<HTMLElement, ChromeHeaderProps>(
+  (
+    { className, withTabs, tabsSlot, lockDensity = 'inherit', leadingRail, children, ...props },
+    ref,
+  ) => {
+    const hasTabs = tabsSlot != null || withTabs === true
+
+    // Column mode(tabsSlot 提供時)— per W2 + W4
+    // 2026-05-20:`<div>` → `<header>`(HTML5 sectional content 允許 multiple `<header>`,
+    // page-level / sectional 都 a11y safe;統一 element contract 消除「何時用 header / 何時用 div」
+    // 的 consumer drift)。 對應 header-canonical.spec.md 「Element canonical」段。
+    if (tabsSlot != null) {
+      return (
+        <header
+          ref={ref}
+          data-density={lockDensity === 'lg' ? 'lg' : undefined}
+          className={cn('flex flex-col shrink-0', className)}
+          {...props}
+        >
+          {/* Row 1:header content(固定高度,跟 single-row 模式同 visual)*/}
+          <div
+            className={cn(
+              'flex items-center gap-2',
+              'h-[var(--chrome-header-height)]',
+              'px-[var(--layout-space-loose)]',
+            )}
+          >
+            {children}
+          </div>
+          {/* Row 2:tabsSlot wrapper — TabsList 全 dialog 寬 + 內 px-loose inset triggers
+              2026-05-18 v3 fix(同 SurfaceHeader,per user verbatim「分隔線寬度應該要填滿整個
+              dialog」+「就這樣做」approval):TabsList 自己 px-loose 內 padding 而非 wrapper
+              提供,讓 TabsList border-b 延展全 dialog 寬。對齊 `tabs.spec.md:199` 既有 canonical。*/}
+          <div className="[&>[role=tablist]]:w-full [&>[role=tablist]]:px-[var(--layout-space-loose)]">
+            {tabsSlot}
+          </div>
+        </header>
+      )
+    }
+
+    // Leading rail mode(2026-05-21 ship per AppShell primary-header globalHeader):
+    // [leadingRail (width=sidebar-width-icon, justify-center)] [children (flex-1 px-loose)]
+    // 整 header 仍 fixed-height chrome-header-height + border-b。Rail 容器無 padding(內元素
+    // 透過 sidebar-width-icon 幾何自然居中,跟 sidebar 收合 icon center x 對齊)。
+    if (leadingRail != null) {
+      return (
+        <header
+          ref={ref}
+          data-density={lockDensity === 'lg' ? 'lg' : undefined}
+          className={cn(
+            'flex items-center shrink-0',
+            'h-[var(--chrome-header-height)]',
+            !hasTabs && 'border-b border-divider',
+            className,
+          )}
+          {...props}
+        >
+          {/* Rail:固定寬度 = sidebar-width-icon,內容 justify-center 居中(toggle center x
+              = rail 寬度的中點 = sidebar 收合 icon center x = 完美 vertical 對齊)
+              2026-05-21 v2 user 抓:rail 右側加 `border-r border-divider`,sidebar 收合到
+              icon mode 時 rail 右 border = sidebar 右 border 連成一線(visual continuity)。 */}
+          <div className="flex w-[var(--sidebar-width-icon)] shrink-0 items-center justify-center border-r border-divider">
+            {leadingRail}
+          </div>
+          {/* Main:flex-1 + px-loose(沿用 header 既有左右 padding canonical)+ gap-2 */}
+          <div className="flex flex-1 items-center gap-2 min-w-0 px-[var(--layout-space-loose)]">
+            {children}
+          </div>
+        </header>
+      )
+    }
+
+    // Single-row(預設 + withTabs=true 但無 tabsSlot 的 backward compat)
+    return (
+      <header
+        ref={ref}
+        data-density={lockDensity === 'lg' ? 'lg' : undefined}
+        className={cn(
+          'flex items-center gap-2 shrink-0',
+          'h-[var(--chrome-header-height)]',
+          'px-[var(--layout-space-loose)]',
+          // W1:無 tabs 自畫 border;withTabs=true(無 tabsSlot)consumer 自畫
+          !hasTabs && 'border-b border-divider',
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </header>
+    )
+  },
+)
+ChromeHeader.displayName = 'ChromeHeader'

package/src/patterns/header-canonical/header-canonical.css

@@ -0,0 +1,27 @@
+/* Header canonical pattern local tokens(per DataTable data-table.css 既有 local-token pattern):
+   ─────────────────────────────────────────────────────────
+   Token 加入 rationale(per CLAUDE.md governance principle):
+     SSOT canonical value + 多 consumer 需 sync 即可加 local token,
+     不必硬卡 Rule of 3(清既有重複 vs spec canonical 給程式表達 是兩件事)。
+
+   --chrome-header-avatar-size:
+     Chrome header brand mark avatar canonical(per `header-canonical.spec.md` 4.5
+     + 5-DS 共識:Linear / Notion / Figma / Slack / Polaris chrome header brand mark
+     皆固定 24px,不 density-scale 也不 row-size-scale)。
+
+     Chrome header **不是 row context**(per `item-anatomy.spec.md:535` scope 限定
+     段)— chrome header 內 avatar 用 raw `<Avatar size={24}>`,**不用 `<ItemAvatar>`**。
+
+     Consumers(2,需 sync):
+       1. WorkspaceBrand demo(`_demo-helpers.tsx`)hardcode `<Avatar size={24}>` + comment cite token
+       2. SidebarHeader 收合 padding 公式:
+          calc((var(--sidebar-width-icon) - var(--chrome-header-avatar-size)) / 2)
+
+     **Sync invariant**:Token 值 + WorkspaceBrand `size={24}` literal + AVATAR_SIZE.inline.md
+     (`item-anatomy.tsx:93`)三者必同 24。改 spec canonical 時 grep
+     `--chrome-header-avatar-size` + `chrome header avatar canonical` 雙向找 sync 點。
+   ───────────────────────────────────────────────────────── */
+
+:root {
+  --chrome-header-avatar-size: 1.5rem;  /* 24px */
+}

package/src/patterns/horizontal-overflow/horizontal-overflow.tsx

@@ -0,0 +1,217 @@
+/**
+ * @internal — DS-internal primitive module(2026-05-23 per `.claude/rules/ui-development.md` Public vs Internal canonical)。
+ * end-user app 直接 import 無 functioning UI;由 Tabs / ChipGroup 等 DS 元件 wrap 消費 hook + helper components。
+ */
+// @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 { ChevronDown, ChevronLeft, ChevronRight } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import { Button } from '@/design-system/components/Button/button'
+import {
+  useScrollEdges,
+  useOverflowIndices,
+} from '@/design-system/hooks/use-overflow-items'
+
+/**
+ * Horizontal Overflow — canonical primitives + helpers
+ *
+ * 詳細設計原則與消費規則見 `horizontal-overflow.spec.md`。
+ *
+ * ── 核心規則 ──
+ * 所有 horizontal overflow 的 affordance 一律是 `<Button variant="text" size="sm" iconOnly>`。
+ * 無論內容是 Tab / Chip / Step / SegmentedControl item,overflow trigger 永遠同一套。
+ * 這是工具層,跟業務層(內容)解耦,不該跟內容爭視覺重量。
+ *
+ * ── 為什麼存在 ──
+ * 過去 Tabs 和 Chip 兩邊各自 copy-paste `ScrollArrow` / `buildFadeMask` / 常數,
+ * 導致 Chip menu trigger 漂移成 chip-shape(違反 mental model)。本 module 是
+ * single source of truth,消除複製帶來的漂移空間。
+ */
+
+// ── Constants ─────────────────────────────────────────────────────────────
+
+/** Fade mask 漸變寬度(px)*/
+// code-quality-allow: dead-export — public constant — DS API surface,consumer 可引(即使當前 internal-only)
+export const FADE_WIDTH = 16
+
+/**
+ * Scroll arrow 預留的按鈕區寬度(px)。
+ * 值對齊 `field-height-sm` 在 lg density 下的最大值(32px),確保 arrow button
+ * 在任何 density 都能完整容納 Button text sm iconOnly。
+ */
+export const ARROW_BUTTON_WIDTH = 32
+
+/** 點一次 scroll arrow 滑動 80% 容器寬度 */
+// code-quality-allow: dead-export — public constant — DS API surface,consumer 可引(即使當前 internal-only)
+export const SCROLL_PAGE_RATIO = 0.8
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+interface BuildFadeMaskArgs {
+  canScroll: boolean
+  atStart: boolean
+  atEnd: boolean
+  /**
+   * 預留給 scroll arrow button 的寬度(px)。
+   * - Scroll 模式:傳 `ARROW_BUTTON_WIDTH`,fade 會延伸到 arrow 底下,
+   *   避免「透明 button icon 跟 item 文字視覺打架」(Material 3 scrim 原理)
+   * - Menu 模式:傳 0,沒有 arrow,fade 直接從容器邊緣開始
+   */
+  reserveArrowWidth?: number
+}
+
+/**
+ * 計算 fade mask 的 `linear-gradient` 字串。
+ *
+ * 回傳 `undefined` 時代表「不需要 mask」(內容沒溢出),消費者該讓 `maskImage`
+ * 等於 undefined 讓 CSS 恢復正常渲染。
+ */
+export function buildFadeMask({
+  canScroll,
+  atStart,
+  atEnd,
+  reserveArrowWidth = 0,
+}: BuildFadeMaskArgs): string | undefined {
+  if (!canScroll) return undefined
+  const stops: string[] = []
+  if (!atStart) {
+    if (reserveArrowWidth > 0) {
+      stops.push('transparent 0')
+      stops.push(`transparent ${reserveArrowWidth}px`)
+      stops.push(`black ${reserveArrowWidth + FADE_WIDTH}px`)
+    } else {
+      stops.push('transparent 0')
+      stops.push(`black ${FADE_WIDTH}px`)
+    }
+  } else {
+    stops.push('black 0')
+  }
+  if (!atEnd) {
+    if (reserveArrowWidth > 0) {
+      stops.push(`black calc(100% - ${reserveArrowWidth + FADE_WIDTH}px)`)
+      stops.push(`transparent calc(100% - ${reserveArrowWidth}px)`)
+      stops.push('transparent 100%')
+    } else {
+      stops.push(`black calc(100% - ${FADE_WIDTH}px)`)
+      stops.push('transparent 100%')
+    }
+  } else {
+    stops.push('black 100%')
+  }
+  return `linear-gradient(to right, ${stops.join(', ')})`
+}
+
+/**
+ * Scroll by page helper。接收 scrollRef 回傳一個 `scrollByPage(direction)` 函式,
+ * 呼叫後以 smooth 動畫橫向滑動 `clientWidth × SCROLL_PAGE_RATIO`。
+ *
+ * 使用 useCallback 並以 scrollRef 為 dependency,確保消費者可以安全把回傳函式
+ * 傳給 `<OverflowScrollArrow onClick>`。
+ */
+export function useScrollByPage<T extends HTMLElement>(
+  scrollRef: React.RefObject<T | null>,
+): (direction: 'left' | 'right') => void {
+  return React.useCallback(
+    (direction: 'left' | 'right') => {
+      const el = scrollRef.current
+      if (!el) return
+      el.scrollBy({
+        left: el.clientWidth * SCROLL_PAGE_RATIO * (direction === 'left' ? -1 : 1),
+        behavior: 'smooth',
+      })
+    },
+    [scrollRef],
+  )
+}
+
+// ── Primitives ────────────────────────────────────────────────────────────
+
+export interface OverflowScrollArrowProps {
+  direction: 'left' | 'right'
+  onClick: () => void
+  /**
+   * 覆寫 aria-label(預設為「向左捲動」/「向右捲動」)。
+   * 一般情況不需要傳——預設繁中 label 對所有水平捲動情境都成立。
+   */
+  'aria-label'?: string
+}
+
+/**
+ * Scroll arrow button — canonical horizontal overflow affordance。
+ *
+ * **絕對定位**在容器的 `left-0` / `right-0`,使用 `pointer-events-none` 外層 +
+ * `pointer-events-auto` 內層,讓 fade mask 下方仍可橫向滑動(arrow 只接受點
+ * 自身的 click)。
+ *
+ * Root 是 `<Button variant="text" size="sm" iconOnly>`——跟 Tabs / Chip /
+ * 未來所有消費者共用同一個按鈕視覺。
+ */
+export const OverflowScrollArrow: React.FC<OverflowScrollArrowProps> = ({
+  direction,
+  onClick,
+  'aria-label': ariaLabel,
+}) => {
+  const defaultLabel = direction === 'left' ? '向左捲動' : '向右捲動' // i18n-allow: DS default; consumer override via aria-label prop
+  return (
+    <div
+      className={cn(
+        'absolute top-0 bottom-0 flex items-center pointer-events-none z-10',
+        direction === 'left' ? 'left-0' : 'right-0',
+      )}
+    >
+      <div className="pointer-events-auto">
+        <Button
+          variant="text"
+          size="sm"
+          iconOnly
+          startIcon={direction === 'left' ? ChevronLeft : ChevronRight}
+          aria-label={ariaLabel ?? defaultLabel}
+          onClick={onClick}
+        />
+      </div>
+    </div>
+  )
+}
+
+export interface OverflowMenuTriggerButtonProps
+  extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  /**
+   * Accessible label。消費者應傳入有語境的 label,例如
+   * `"頁籤選單(共 5 個)"` 或 `"分類選單(共 8 個)"`。必填。
+   */
+  'aria-label': string
+}
+
+/**
+ * Menu trigger button — canonical overflow menu affordance。
+ *
+ * Root 是 `<Button variant="text" size="sm" iconOnly startIcon={ChevronDown}>`。
+ * **forwardRef + props spread** 讓 Radix `<DropdownMenuTrigger asChild>` 可以
+ * 接管 onClick / aria-expanded / data-state 等 attributes。
+ *
+ * ── 為什麼不包 DropdownMenu ──
+ * Menu 的內容(items)取決於消費者的資料結構(Tab 用 DropdownMenuItem + selected,
+ * Chip 用 DropdownMenuCheckboxItem),所以只提供 trigger button,消費者自己
+ * 把 `<DropdownMenu> <DropdownMenuTrigger asChild> <OverflowMenuTriggerButton /> ... </DropdownMenu>`
+ * 串起來。
+ */
+export const OverflowMenuTriggerButton = React.forwardRef<
+  HTMLButtonElement,
+  OverflowMenuTriggerButtonProps
+>(({ 'aria-label': ariaLabel, ...props }, ref) => (
+  <Button
+    ref={ref}
+    variant="text"
+    size="sm"
+    iconOnly
+    startIcon={ChevronDown}
+    aria-label={ariaLabel}
+    {...props}
+  />
+))
+OverflowMenuTriggerButton.displayName = 'OverflowMenuTriggerButton'
+
+// ── Hook re-exports ──────────────────────────────────────────────────────
+// 讓消費者只從本 module import 所有 overflow 相關的 API。
+
+export { useScrollEdges, useOverflowIndices }

package/src/patterns/overlay-surface/overlay-surface.tsx

@@ -0,0 +1,191 @@
+import * as React from 'react'
+import { cn } from '@/lib/utils'
+
+/**
+ * @internal — DS-internal primitive(2026-05-23 per `.claude/rules/ui-development.md` Public vs Internal canonical)。
+ * end-user app 直接 import 無 functioning UI;由 Dialog / Sheet / Popover / HoverCard / Coachmark 等 DS overlay 元件 wrap 消費。
+ *
+ * Overlay Surface primitives — Dialog / Popover / Sheet 共用結構化 sub-components。
+ *
+ * 抽象這層避免各自硬寫 padding / border 導致漂移。有特殊行為(Dialog Close 按鈕 /
+ * viewport-fill 高度)由 consumer 額外包裝,不污染 primitive。
+ *
+ * ── Header / Footer 高度 canonical(2026-04-22 v3 校準,user intent 精確實作)──
+ * **Padding-based sizing**:`py-[var(--layout-space-tight)]`,高度 = max(child) + 2×tight
+ * 不用 fixed `min-h`(先前誤用 min-h-chrome-header-height 會讓 bounded button 被鎖死在 48
+ * slot 失去自然高度,違反 user 意圖)。
+ *
+ * 對齊 `--chrome-header-height`(48/56)的**條件**:header 只放 unbounded 控件(close X /
+ * text variant button,**native sm + v5 unbounded trick layout 佔位 24**):
+ *   header = 24 + 2×tight = 48 md / 56 lg ✓。
+ *
+ * 若 header 塞 **bounded 控件**(primary / tertiary with bg/border):header 自然長高
+ * (sm 28 + 2×12 = 52 md),因 bounded 按鈕有視覺邊界,padding 不會顯得過大 — 這是預期的。
+ *
+ * ── Unbounded controls 在 header canonical(v5 trick,2026-04-22)──
+ * Dismiss X(always unbounded)+ text variant header action → **`size="sm"` native**
+ * + SurfaceHeader CSS 自動套負 my trick(對 `[data-unbounded]`),layout 佔位縮回 24
+ * (xs 等同)。Rationale:button native size 跟 touch target 保留 sm(a11y 最小 24+ hit
+ * target,視覺 render 仍 28/32),layout 佔位精確匹配 chrome-header-height 幾何。詳
+ * `overlay-surface.spec.md`「Chrome dismiss size canonical」。
+ *
+ * **Notification banner family**(Notice / Alert / Toast,fixed `px-4 py-3` variant,
+ * 無 padding-based header)→ dismiss 用 `size="xs"` explicit(24 固定,無 trick)。
+ *
+ * ── Token 規則 ──
+ * horizontal padding: `px-[var(--layout-space-loose)]`
+ * vertical padding: `py-[var(--layout-space-tight)]`
+ * 分隔線: `border-{b|t} border-divider`
+ *
+ * ── Body ──
+ * Body padding-based(content area),`px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]`。
+ * Dialog / Sheet body 走 ScrollArea + chrome padding(`px-loose pt-tight pb-bottom`)。
+ * List-as-region 場景(menu / Cmd+K)由 consumer 用 className override 撤 chrome padding +
+ * 自管 list outer wrapper(詳 overlay-surface.spec.md「List-as-region in overlay body」)。
+ */
+
+// Chrome-slot layout trick(2026-04-22 v5,2026-05-04 重思 parameterize):
+// **所有 unbounded control**(Button with `data-unbounded="true"` — Button 自動在 variant="text" 或 dismiss
+// 時標記)的 **native size 不變**(sm: 28 md / 32 lg),但 **layout 佔位** via 負 `my` 縮成 `--chrome-slot-h`。
+//
+// **Slot height = header title 的 line-height**(讓 button 不 dominate,title 自然撐 header)
+//   - Default `var(--field-height-xs)` = 24,匹配 Dialog/Sheet text-body-lg (16 × 1.5 = 24)
+//   - Popover/Coachmark override `--chrome-slot-h: 1.25rem` (20),匹配 text-body (14 × 1.5 ≈ 21,floor 20)
+//
+// Header 永遠 padding-based(無 min-h),但因 slot ≤ title line-height,header 高度由 title 主導:
+//   - Dialog: max(24 title, 24 slot) + py-tight(12*2)= 48 ✓ chrome-header-height
+//   - Popover: max(21 title, 20 slot) + py-tight(12*2)= 45 ✓ 自然輕量
+// Q10 穩定性:title-only / title+button / refresh in/out 全 case header 高度 = title + py(slot 不 dominate)
+//
+// 負 my 公式:(slot - native) / 2,density-aware:
+//   Dialog md: (24 - 28) / 2 = -2px;  lg: (24 - 32) / 2 = -4px
+//   Popover md: (20 - 28) / 2 = -4px
+const CHROME_UNBOUNDED_SLOT = '[&_[data-unbounded]]:my-[calc((var(--chrome-slot-h,var(--field-height-xs))-var(--field-height-sm))/2)]'
+
+export interface SurfaceHeaderProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 是否內含 Tabs。
+   * true(無 tabsSlot)→ 移除自身 border-b。
+   * 若提供 tabsSlot,自動 column mode + auto suppress border(不需手動傳 withTabs=true)。
+   * 對齊 patterns/header-canonical/header-canonical.spec.md W1
+   * 「Header semantic owner / TabsList paint owner in withTabs state」。
+   */
+  withTabs?: boolean
+  /**
+   * Tabs row slot(2026-05-18 加 per header-canonical.spec.md W2/W4 真實能用 + user-mandated fix)。
+   * 提供時 SurfaceHeader 自動 column 結構:
+   *   row 1 = children(title + actions/dismiss,px-loose py-tight)
+   *   row 2 = tabsSlot 包在 `<div px-loose border-b border-divider>`
+   *           ↑ wrapper 提供 W2 padding inheritance + 全寬 paint(W1 視覺一條線)
+   *
+   * Consumer 傳:`tabsSlot={<TabsList>...</TabsList>}`,TabsContent 仍放 DialogBody 內。
+   * `<Tabs>` root 必須 wrap 整 DialogContent(Radix TabsList ↔ TabsContent 同 root 連動)。
+   *
+   * 提供 tabsSlot 自動 withTabs=true,不需另傳 prop。
+   */
+  tabsSlot?: React.ReactNode
+}
+
+export const SurfaceHeader = React.forwardRef<
+  HTMLDivElement,
+  SurfaceHeaderProps
+>(({ className, withTabs, tabsSlot, children, ...props }, ref) => {
+  // tabsSlot 提供 → 自動 withTabs(consumer 不需手動兩個 prop)
+  const hasTabs = tabsSlot != null || withTabs === true
+
+  // Column mode(tabsSlot 提供時)— 對應 header-canonical.spec.md W2 + W4
+  if (tabsSlot != null) {
+    return (
+      <div
+        ref={ref}
+        className={cn('flex flex-col shrink-0', className)}
+        {...props}
+      >
+        {/* Row 1:header content row(原 single-row behavior 不變,但 border-b 撤掉,row 2 wrapper 接管 paint)*/}
+        <div
+          className={cn(
+            'flex items-center gap-2',
+            'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',
+            CHROME_UNBOUNDED_SLOT,
+          )}
+        >
+          {children}
+        </div>
+        {/* Row 2:tabsSlot wrapper — TabsList 全 dialog 寬 + 內 px-loose padding inset triggers
+            2026-05-18 v3 fix(user verbatim approval「你確定這樣是世界級的設計且符合我們一致的設計
+            語言和 SSOT...就這樣做」):
+            - v1: wrapper border + TabsList border = 雙線(W1 違反)
+            - v2: wrapper px-loose + TabsList w-full inside = border 只跨 dialog - 2×px-loose
+                 (不到 dialog 邊 user 抓「分隔線寬度應該要填滿整個 dialog」)
+            - v3(本):wrapper 不 inset,TabsList 自己 px-loose 內 padding inset triggers
+                  → TabsList border-b 延展全 dialog 寬,triggers 對齊 header content
+            對齊既有 `tabs.spec.md:199`「TabsList 自身 border-b border-border 延展全 header 寬,因
+            TabsList wrapper 是 block-level full-width」+ `:187-189`「selected 底線從 TabsList
+            gray border 位置長出來」+ GitHub Primer UnderlineNav / Ant Design line type / Mantine
+            default 共識(全派 TabsList 自畫 full-width underline)。*/}
+        <div className="[&>[role=tablist]]:w-full [&>[role=tablist]]:px-[var(--layout-space-loose)]">
+          {tabsSlot}
+        </div>
+      </div>
+    )
+  }
+
+  // Padding-based(預設) — Dialog/Sheet 用 body-lg title (16/24)，自然撐 max(24 title, 24 button slot) = 24
+  // → header = 24 + py-tight 12×2 = 48 chrome-header-height ✓ 穩定無需 min-h
+  // Popover 等輕量 chrome 走 PopoverHeader override(min-h-10 + py-2 = 40,內 24 匹配 button slot)
+  //
+  // withTabs=true(無 tabsSlot,backward compat):移除 border-b,consumer 自畫
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        'flex items-center gap-2 shrink-0',
+        !hasTabs && 'border-b border-divider',
+        'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',
+        CHROME_UNBOUNDED_SLOT,
+        className,
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  )
+})
+SurfaceHeader.displayName = 'SurfaceHeader'
+
+export const SurfaceBody = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  // 2026-05-04 viewport-aware scroll canonical:
+  //   parent(PopoverContent / HoverCardContent / Dialog / Sheet)是 flex flex-col + max-h + overflow-hidden
+  //   header / footer shrink-0;Body flex-1 min-h-0 overflow-y-auto → 視窗太小時 body 內 scroll
+  //   非 flex-col parent 內 flex-1/min-h-0 no-op,backward compat
+  <div
+    ref={ref}
+    className={cn(
+      'flex-1 min-h-0 overflow-y-auto',
+      'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',
+      className,
+    )}
+    {...props}
+  />
+))
+SurfaceBody.displayName = 'SurfaceBody'
+
+export const SurfaceFooter = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement>
+>(({ className, ...props }, ref) => (
+  <div
+    ref={ref}
+    className={cn(
+      'flex items-center justify-end gap-2 shrink-0 border-t border-divider',
+      'px-[var(--layout-space-loose)] py-[var(--layout-space-tight)]',
+      className,
+    )}
+    {...props}
+  />
+))
+SurfaceFooter.displayName = 'SurfaceFooter'