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

package/src/tokens/color/color.stories.tsx

@@ -0,0 +1,363 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import React from 'react'
+
+const meta: Meta = {
+  title: 'Design System/Tokens/Color',
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component: `
+色彩 token 系統。元件只使用語義 token，不直接引用原始色票。
+
+完整規則：\`packages/design-system/src/tokens/color/color.spec.md\`
+        `,
+      },
+    },
+  },
+}
+
+export default meta
+type Story = StoryObj
+
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function SwatchBg({
+  bg,
+  label,
+  desc,
+  bordered = false,
+}: {
+  bg: string
+  label: string
+  desc: string
+  bordered?: boolean
+}) {
+  return (
+    <div className="space-y-1.5">
+      <div
+        className={`h-14 w-full rounded-md ${bordered ? 'border border-border' : ''}`}
+        style={{ background: bg }}
+      />
+      <code className="block text-caption font-medium">{label}</code>
+      <span className="block text-caption text-fg-muted">{desc}</span>
+    </div>
+  )
+}
+
+function SwatchText({
+  className,
+  label,
+  desc,
+}: {
+  className: string
+  label: string
+  desc: string
+}) {
+  return (
+    <div className="border-b border-border py-3 last:border-0">
+      <p className={`text-body mb-1 ${className}`}>
+        此操作將永久刪除該筆資料，確認後無法復原。
+      </p>
+      <div className="flex gap-3">
+        <code className="text-caption font-medium">{label}</code>
+        <span className="text-caption text-fg-muted">{desc}</span>
+      </div>
+    </div>
+  )
+}
+
+function SectionLabel({ children }: { children: React.ReactNode }) {
+  return (
+    <p className="text-caption font-medium uppercase tracking-wider text-fg-muted">
+      {children}
+    </p>
+  )
+}
+
+
+// ── 1. Primitives ────────────────────────────────────────────────────────────
+
+export const Primitives: Story = {
+  name: '原始色票',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '原始色票（Layer 1）。元件**不得直接使用**，一律透過語義 token。\n\n' +
+          '**已映射為語義 token 的色相：** blue → primary、deep-orange → error + notification、green → success、yellow → warning\n\n' +
+          '**其餘色相（orange、amber、lime、turquoise、indigo、purple、magenta）** 保留給 data visualization、categorization tag、avatar 等需要多色區分的場景。',
+      },
+    },
+  },
+  render: () => {
+    const SEMANTIC_MAP: Record<string, string> = {
+      blue: 'primary',
+      'deep-orange': 'error + notification',
+      green: 'success',
+      yellow: 'warning',
+    }
+    const HUES: Array<{ name: string; suffix?: string }> = [
+      { name: 'neutral', suffix: '-opaque' },
+      { name: 'blue' },
+      { name: 'deep-orange' },
+      { name: 'orange' },
+      { name: 'amber' },
+      { name: 'yellow' },
+      { name: 'lime' },
+      { name: 'green' },
+      { name: 'turquoise' },
+      { name: 'indigo' },
+      { name: 'purple' },
+      { name: 'magenta' },
+      { name: 'red' },
+    ]
+    return (
+      <div className="space-y-1 max-w-2xl">
+        <div className="grid pb-2 border-b border-border mb-2" style={{ gridTemplateColumns: '160px repeat(9, 1fr)' }}>
+          <span className="text-caption text-fg-muted">hue</span>
+          {[1,2,3,4,5,6,7,8,9].map(n => (
+            <span key={n} className="text-caption text-fg-muted text-center">{n}</span>
+          ))}
+        </div>
+        {HUES.map(({ name, suffix = '' }) => {
+          const semantic = SEMANTIC_MAP[name]
+          return (
+            <div key={name} className="grid items-center gap-x-1 py-0.5" style={{ gridTemplateColumns: '160px repeat(9, 1fr)' }}>
+              <div className="flex items-center gap-1.5 truncate">
+                <span className="text-caption text-fg-muted">{name}</span>
+                {semantic && <span className="text-footnote text-[var(--primary)] font-medium">→ {semantic}</span>}
+              </div>
+              {[1,2,3,4,5,6,7,8,9].map(n => (
+                <div
+                  key={n}
+                  className="h-6 rounded-md border border-[var(--black-a06)]"
+                  style={{ background: `var(--color-${name}-${n}${suffix})` }}
+                  title={`--color-${name}-${n}${suffix}`}
+                />
+              ))}
+            </div>
+          )
+        })}
+        <p className="pt-3 text-caption text-fg-muted">
+          neutral 顯示 opaque 版本。-6 為基底色，其餘由相對色語法推導。無 → 標記的色相保留給 data visualization / categorization。
+        </p>
+      </div>
+    )
+  },
+}
+
+
+// ── 2. Surface ───────────────────────────────────────────────────────────────
+
+export const Surface: Story = {
+  name: '表面層',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Surface = 空間容器（內容坐在上面的背景），不帶語義。' +
+          'canvas → surface → surface-raised 三層由底到高疊加。overlay / tooltip 也屬於 surface（空間用途）。',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-xl space-y-4">
+      <div className="grid grid-cols-3 gap-4">
+        <SwatchBg bg="var(--canvas)"         bordered label="bg-canvas"         desc="頁面最底層背景" />
+        <SwatchBg bg="var(--surface)"        bordered label="bg-surface"        desc="card、sidebar、table" />
+        <SwatchBg bg="var(--surface-raised)" bordered label="bg-surface-raised" desc="modal、popover、dropdown" />
+      </div>
+      <div className="grid grid-cols-2 gap-4 max-w-sm">
+        <div className="space-y-1.5">
+          <div className="h-14 w-full rounded-md border border-border" style={{ background: 'var(--overlay)' }} />
+          <code className="block text-caption font-medium">bg-overlay</code>
+          <span className="block text-caption text-fg-muted">dialog backdrop 遮罩</span>
+        </div>
+        <div className="space-y-1.5">
+          <div className="h-14 w-full rounded-md flex items-center justify-center" style={{ background: 'var(--tooltip)' }}>
+            <span className="text-caption text-white">tooltip</span>
+          </div>
+          <code className="block text-caption font-medium">bg-tooltip</code>
+          <span className="block text-caption text-fg-muted">tooltip 深色底（不透明）</span>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+
+// ── 3. Text ──────────────────────────────────────────────────────────────────
+
+export const Text: Story = {
+  name: '文字色',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '文字從主要資訊到 disabled 的四個層級。一律使用 neutral alpha token，疊加在任何背景都能維持對比。',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-xl">
+      <SwatchText className="text-foreground"   label="text-foreground"   desc="主要文字、一般資訊" />
+      <SwatchText className="text-fg-secondary" label="text-fg-secondary" desc="次要資訊、helper text" />
+      <SwatchText className="text-fg-muted"     label="text-fg-muted"     desc="placeholder、caption、弱化 icon" />
+      <SwatchText className="text-fg-disabled"  label="text-fg-disabled"  desc="disabled 文字" />
+      <div className="mt-4 flex items-center gap-3 px-3 py-2 rounded-md" style={{ backgroundColor: 'var(--primary)' }}>
+        <span style={{ color: 'var(--on-emphasis)' }} className="text-body font-medium">text-on-emphasis</span>
+        <span style={{ color: 'var(--on-emphasis)' }} className="text-caption opacity-80">Avatar color variant / Steps filled indicator 等飽和色底的對比文字</span>
+      </div>
+    </div>
+  ),
+}
+
+
+// ── 4. Semantic ──────────────────────────────────────────────────────────────
+
+export const Semantic: Story = {
+  name: '語義色',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Primary = 互動入口（按鈕、連結）。Info = 系統狀態（in-progress、active）。subtle 為淡底填充，用於 tag、banner、checked 背景。',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-2xl space-y-8">
+
+      {/* Action */}
+      <div>
+        <SectionLabel>Action — Primary</SectionLabel>
+        <div className="mt-3 grid grid-cols-2 gap-3 max-w-xs">
+          <SwatchBg bg="var(--primary)"        label="bg-primary"        desc="按鈕、連結、focus ring" />
+          <SwatchBg bg="var(--primary-subtle)" bordered label="bg-primary-subtle" desc="淡底 / checked 底" />
+        </div>
+      </div>
+
+      {/* Status */}
+      <div>
+        <SectionLabel>Status</SectionLabel>
+        <div className="mt-3" style={{ display: 'grid', gridTemplateColumns: '44px 1fr 1fr 1fr 1fr', gap: '8px', alignItems: 'start' }}>
+          <div />
+          {['Info', 'Error', 'Success', 'Warning'].map(n => (
+            <span key={n} className="text-caption text-fg-muted text-center block">{n}</span>
+          ))}
+          <span className="text-caption text-fg-muted self-center">Base</span>
+          <SwatchBg bg="var(--info)"    label="bg-info"    desc="資訊 / 進行中 / active" />
+          <SwatchBg bg="var(--error)"   label="bg-error"   desc="錯誤 / 危險" />
+          <SwatchBg bg="var(--success)" label="bg-success" desc="成功" />
+          <SwatchBg bg="var(--warning)" label="bg-warning" desc="警告" />
+          <span className="text-caption text-fg-muted self-center">Subtle</span>
+          <SwatchBg bg="var(--info-subtle)"    bordered label="bg-info-subtle"    desc="淡底" />
+          <SwatchBg bg="var(--error-subtle)"   bordered label="bg-error-subtle"   desc="淡底" />
+          <SwatchBg bg="var(--success-subtle)" bordered label="bg-success-subtle" desc="淡底" />
+          <SwatchBg bg="var(--warning-subtle)" bordered label="bg-warning-subtle" desc="淡底" />
+        </div>
+      </div>
+
+      {/* Other */}
+      <div>
+        <SectionLabel>Other</SectionLabel>
+        <div className="mt-3 grid grid-cols-2 gap-3 max-w-xs">
+          <SwatchBg bg="var(--notification)" label="bg-notification" desc="未讀計數 / 通知紅點" />
+          <SwatchBg bg="var(--brand)"        label="bg-brand"        desc="品牌色，固定色" />
+        </div>
+      </div>
+
+      {/* Border */}
+      <div>
+        <SectionLabel>Border</SectionLabel>
+        <div className="mt-3 space-y-2.5">
+          {[
+            { label: 'border-border',  desc: '元件標準邊框',   style: { border: '2px solid var(--border)' } },
+            { label: 'border-divider', desc: '分隔線（比 border 更淡）', style: { borderBottom: '2px solid var(--divider)' } },
+          ].map(({ label, desc, style }) => (
+            <div key={label} className="flex items-center gap-4">
+              <div className="h-10 w-24 rounded-md bg-surface" style={style} />
+              <div>
+                <code className="text-caption font-medium">{label}</code>
+                <span className="ml-2 text-caption text-fg-muted">{desc}</span>
+              </div>
+            </div>
+          ))}
+        </div>
+      </div>
+
+    </div>
+  ),
+}
+
+
+// ── 5. Interactive ───────────────────────────────────────────────────────────
+
+export const Interactive: Story = {
+  name: '互動色',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '互動色的三種狀態。使用語義 token（`bg-primary-hover`），不直接引用 primitive step。\n\n' +
+          '```tsx\n' +
+          '<a className="text-primary hover:text-primary-hover">連結</a>\n' +
+          '<button className="bg-primary hover:bg-primary-hover active:bg-primary-active" />\n' +
+          '```\n\n' +
+          '> 色盤對應（內部實作）：-1 = subtle、-5 = hover、-6 = base、-7 = active。\n\n' +
+          '---\n\n' +
+          '#### Neutral Interaction\n\n' +
+          '低調互動背景，用於 list row、tree node。',
+      },
+    },
+  },
+  render: () => (
+    <div className="max-w-lg space-y-8">
+      {/* Colored interactive states */}
+      {[
+        { name: 'Primary', prefix: 'primary', hover: '--primary-hover', base: '--primary', active: '--primary-active' },
+        { name: 'Info',    prefix: 'info',    hover: '--info-hover',    base: '--info',    active: '--info-active' },
+        { name: 'Error',   prefix: 'error',   hover: '--error-hover',   base: '--error',   active: '--error-active' },
+        { name: 'Success', prefix: 'success', hover: '--success-hover', base: '--success', active: '--success-active' },
+        { name: 'Warning', prefix: 'warning', hover: '--warning-hover', base: '--warning', active: '--warning-active' },
+      ].map(({ name, prefix, hover, base, active }) => (
+        <div key={name}>
+          <span className="text-caption text-fg-muted mb-1.5 block">{name}</span>
+          <div className="grid grid-cols-3 gap-2">
+            <SwatchBg bg={`var(${hover})`}  label="hover"  desc={`bg-${prefix}-hover`} />
+            <SwatchBg bg={`var(${base})`}   label="base"   desc={`bg-${prefix}`} />
+            <SwatchBg bg={`var(${active})`} label="active" desc={`bg-${prefix}-active`} />
+          </div>
+        </div>
+      ))}
+
+      {/* Ghost */}
+      <div>
+        <SectionLabel>Neutral Interaction — Default family（hover/active）+ Selected family（持續選中）</SectionLabel>
+        <div className="mt-3 space-y-1">
+          {[
+            { label: '正常狀態（無背景）', bg: 'transparent',                    token: '' },
+            { label: 'Hover 回饋',         bg: 'var(--neutral-hover)',        token: 'bg-neutral-hover' },
+            { label: 'Active 回饋（:active click）', bg: 'var(--neutral-active)', token: 'bg-neutral-active' },
+            { label: 'Selected 持續選中',   bg: 'var(--neutral-selected)',     token: 'bg-neutral-selected' },
+            { label: 'Selected + Hover',    bg: 'var(--neutral-selected-hover)', token: 'bg-neutral-selected-hover' },
+            { label: 'Selected + Active',   bg: 'var(--neutral-selected-active)', token: 'bg-neutral-selected-active' },
+            { label: 'Disabled 狀態',      bg: 'var(--bg-disabled)',          token: 'bg-disabled' },
+          ].map(({ label, bg, token }) => (
+            <div
+              key={label}
+              className="flex items-center gap-3 rounded-md px-3 py-2 text-body"
+              style={{ background: bg }}
+            >
+              <span className="h-4 w-4 shrink-0 rounded-md bg-[var(--fg-disabled)]" />
+              <span className="flex-1 text-fg-disabled">{label}</span>
+              {token && <code className="text-caption text-fg-muted">{token}</code>}
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  ),
+}

package/src/tokens/color/primitives.css

@@ -245,6 +245,13 @@
 
 }
 
+/* Tailwind bridge for absolute anchors.
+   Keep the bridge in the primitive color SSOT so text-white/bg-white ship to consumers. */
+@theme inline {
+  --color-white: oklch(1 0 0);
+  --color-black: oklch(0 0 0);
+}
+
 
 /* ── Layer 1 — Dark Mode Overrides ── */
 [data-theme="dark"] {

package/src/tokens/color/semantic.css

@@ -122,7 +122,7 @@
    │   (subtle)   bg-{primary|info|error|success|warning}-subtle         │
    │   (text)     text-{info|error|success|warning}-text                  │
    │                  ↑ 用於 subtle bg 上的文字（資訊呈現）                │
-   │  Special     text-warning-foreground（yellow solid 例外）            │
+   │  On-fill     --on-emphasis（白）/ --on-emphasis-dark（深,亮底用）   │
    │  Neutral     bg-neutral-hover / bg-neutral-active / bg-disabled     │
    │              bg-neutral-selected / bg-neutral-selected-hover /       │
    │              bg-neutral-selected-active                              │
@@ -171,24 +171,33 @@
 
   /* 文字 / Icon */
   --foreground:           var(--color-neutral-9);
-  --warning-foreground:   var(--black-a85);
   --fg-secondary:         var(--color-neutral-8);
   --fg-muted:             var(--color-neutral-7);
   --fg-disabled:          var(--color-neutral-6);
 
-  /* On-emphasis:飽和色底的對比文字(white on filled surface)
-     消費者:Avatar color variants(blue/red/green/... fill + on-emphasis text)
-           Steps filled indicator(completed/active 的 icon 色)
-     為什麼獨立 token:foreground 是 neutral 文字色,warning-foreground 是 warning
-     子場景 amber 底的對比,都不是「任何飽和色底的通用對比」。Polaris 叫 text-onEmphasis,
-     Material 叫 on-primary/on-secondary family。我們用 on-emphasis 保持通用。
-     Dark mode 不反轉(白字在飽和色底永遠白)
-     2026-05-20 fix:raw oklch → primitive --color-white */
+  /* ── On-emphasis 配對:飽和 / 填色底上的對比文字 ──────────────────────────────
+     世界級對照:Material on-primary/on-secondary family、Radix --accent-contrast、
+     Polaris text-{x}-on-bg-fill —— 「填色底的文字色」依底色明暗成對提供,不是單一固定白。
+     本 DS 採「2-bucket」(白 + 深)而非 per-hue(12 個 token = 過度設計;深底白字已是最大對比,
+     per-hue 救不了暗色邊緣):
+       --on-emphasis       = 白字,用於「夠深」的飽和色底(WCAG ≥3:1 大粗字達標的 hue)
+       --on-emphasis-dark  = 深字(= black-a85),用於「太亮」的色底(白字連 3:1 都不及格:yellow/amber/orange/lime)
+     命名:配對白↔深;不用「inverse」(已保留給 --inverse-* 反相 surface 命名空間),不用 mode 字眼
+     (token 名一律不編碼 light/dark mode,mode 靠 redefinition)。
+     合規門檻(2026-06-04 user 拍板「以最低為原則」)= WCAG large/bold 3:1(solid chip/avatar 視大粗字)。
+     消費者:Avatar / Tag solid color variants、Steps filled indicator、Calendar today、Tooltip、
+     warning solid surface(黃底深字)等 —— 「亮底深字」一律消費 --on-emphasis-dark(不再有 warning 專屬 token)。
+     兩者都「Dark mode 不反轉」(白 / 深字在飽和底永遠同極性,底色明暗跨 mode 不變)。
+     ⚠️ green 例外:green-6 白字實測 2.47(連 3:1 都不過),但 user 拍板維持白字(沿用世界級慣見的
+        「綠底白字」按鈕觀感)→ documented exception(知情違反),待日後評估是否調 green-6。
+     2026-06-04 改名:原 --warning-foreground 被 categorical yellow/amber 借用 = 誤名(它跟 warning 無關,
+        本質是「亮底深字」通用概念)→ 改名 --on-emphasis-dark + 移除 warning 專屬 alias(user「以乾淨為主」)。 */
   --on-emphasis:          var(--color-white);
+  --on-emphasis-dark:     var(--black-a85);
 
   /* Brand / Action — 品牌主操作色
      --primary-text 為 SOP 規定的 5 件套之一，目前無消費者
-     （Button 直接用 text-white, Tag 用 primitive --color-blue-7） */
+     （Button 直接用 text-on-emphasis, Tag 用 primitive --color-blue-7） */
   --primary:              var(--color-blue-6);
   --primary-hover:        var(--color-blue-5);
   --primary-active:       var(--color-blue-7);
@@ -197,7 +206,11 @@
 
   /* Status: Info — 資訊狀態色
      目前指向 blue（與 primary 同源），但語義獨立——如未來 brand 改色，
-     primary 跟著改，info 仍維持「資訊=藍」的通用慣例 */
+     primary 跟著改，info 仍維持「資訊=藍」的通用慣例。
+     ⚠️ 選取控件(Checkbox/Switch/Radio/Calendar selected)的 checked 藍 = --primary 非 --info:
+     選取是「互動操作的 selected state」隨 brand 走(Material 3 CheckboxTokens
+     SelectedContainerColor=Primary / shadcn bg-primary / Ant colorPrimary 同款);
+     --info 只給資訊呈報(Alert/Badge/Toast info)。2026-06-12 codify per user 提問 */
   --info:                 var(--color-blue-6);
   --info-hover:           var(--color-blue-5);
   --info-active:          var(--color-blue-7);
@@ -319,6 +332,7 @@
   --neutral-hover:        var(--color-neutral-1);
   --neutral-active:       var(--color-neutral-2);
   --bg-disabled:          var(--color-neutral-2);
+  --bg-readonly:          var(--color-neutral-2);  /* readonly 鎖定欄位 chrome — 同值但獨立 owner(≠ disabled:可聚焦/選取/提交,僅不可改值);詳 color.spec.md Static Subtle 邊界 */
 
   /* Neutral Interactive — Selected state family
      ─────────────────────────────────────────────────────────────
@@ -450,6 +464,7 @@
   /* Foreground */
   --color-foreground:            var(--foreground);
   --color-on-emphasis:           var(--on-emphasis);
+  --color-on-emphasis-dark:      var(--on-emphasis-dark);
 
   /* Primary */
   --color-primary:               var(--primary);
@@ -463,7 +478,6 @@
   --color-error:                 var(--error);
   --color-success:               var(--success);
   --color-warning:               var(--warning);
-  --color-warning-foreground:    var(--warning-foreground);
   --color-notification:          var(--notification);
 
   /* Presence Status(Avatar badge) */
@@ -506,6 +520,7 @@
   --color-neutral-hover:             var(--neutral-hover);
   --color-neutral-active:            var(--neutral-active);
   --color-disabled:                  var(--bg-disabled);
+  --color-readonly:                  var(--bg-readonly);
 
   /* Neutral Interaction — Selected state family */
   --color-neutral-selected:          var(--neutral-selected);

package/src/tokens/density/density.spec.md

@@ -0,0 +1,128 @@
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — verified 0 world-class DS claim in body; blanket retract removed. -->
+
+# Density 設計原則
+
+Density 由**兩個獨立維度**構成,並配合一個 convenience attribute 同時控制兩者:
+
+| 維度 | 管的是 | attribute | 範例 |
+|------|--------|-----------|------|
+| **UI Size** | 元件**高度 / 內距**(Button / Input / SelectionItem / field-height / table-row) | `data-ui-size` | `md`(32px field-height-md)/ `lg`(36px field-height-md) |
+| **Layout Space** | 版面**間距 / 外框 padding**(section gutter / dialog body padding / form gap) | `data-layout-space` | `md`(tight gap)/ `lg`(loose gap) |
+| **Density**(convenience)| 一鍵同時切兩者 | `data-density` | `md` / `lg` |
+
+## 兩維度為何解耦(世界級對照)
+
+**Carbon Design System**:spacing scale 獨立於 component size([carbondesignsystem.com/elements/spacing](https://carbondesignsystem.com/elements/spacing/overview/))
+**GitHub Primer**:8px base unit scale 獨立於 control size([styleguide.github.com/primer](https://styleguide.github.com/primer/support/spacing/))
+**Atlassian**:spacing tokens 可單獨消費(partial decouple)
+
+**反例**(耦合):Material M3 / Polaris density 模式綁 control size + spacing — 無法「寬版面 + 標準 control」的場景。
+
+**我們走 decouple 流派**:解決 Dialog / overlay chrome 的痛點 — header 想要版面間距寬鬆(layout-space=lg),但不要被 button chrome 撐高(ui-size 跟 page 走 md)。
+
+## 預設同步(density convenience)
+
+日常使用:不管兩個維度,直接 `data-density` 一次切兩者:
+
+```html
+<html data-theme="light" data-density="md">
+```
+
+- **md**(預設):資訊密集的桌面 UI / form-heavy 頁面
+- **lg**:觸控裝置 / 需要更大點擊目標的情境
+
+`data-density` 內部等同同時設 `data-ui-size` + `data-layout-space` 相同 tier。CSS selectors 同時監聽 `[data-density="lg"], [data-ui-size="lg"]` 等(見 `uiSize.css` + `layoutSpace.css`)。
+
+## 解耦用法(canonical 情境)
+
+當需要「版面間距寬鬆(layout-space)+ 控件高度標準(ui-size)」時,**顯式設兩個 attribute**:
+
+### Canonical 情境 1 — Overlay 的 layout-space tier(2026-06-15 重訂)
+
+**核心原則**:浮層(Portal overlay)**預設全繼承 page density**;只鎖「**有設計理由 + 該元件真的消費到**」的那個 dial,**禁用 `data-density` master switch 鎖浮層**(它連 ui-size 一起鎖 → 內部控件 / 選單 item 對不上觸發點)。**ui-size 永遠跟 page** —— 浮層只決定「版面間距 tier」(layout-space),控件大小交給 page。
+
+| 浮層 | 鎖 | 理由 |
+|------|----|------|
+| Dialog | **不鎖(繼承 page)** | layout-space 本 spec 第 10 行定義即管「dialog body padding」,鎖死 = override 自家 dial 自相矛盾;modal 寬鬆需求在 lg 階自然滿足(md 16 = Polaris 下限合格);button 不撐高由 ui-size 繼承解決。有同類 dial 的 SAP/Cloudscape modal 跟 dial、不鎖 |
+| Popover / Coachmark | `data-layout-space="md"` | 輕量浮層 → header py-tight 保持精簡;ui-size 跟 page 讓內部 field 控件對齊觸發點。Coachmark 建在 Popover 上自動繼承 |
+| Tooltip / DropdownMenu | 不鎖(繼承 page) | 不消費任何 layout-space token(Tooltip padding 寫死 px-3 py-2;Dropdown 是 RowSize + py-2);鎖 ui-size 會把選單 item(field-height-{size})釘在 md-scale → 對不上 lg 觸發點 |
+| Sheet | 不鎖(繼承 page) | 側板,螢幕變小時常駐側板會 responsive 變 Sheet;若 Sheet 鎖 tier 而側板繼承 page → 切換瞬間跳 mode,不一致 |
+| FileViewer | 不鎖(繼承 page) | 全螢幕 chrome 殼。原 `lockDensity="lg"` 只鎖在兩個 ChromeHeader、沒鎖 body → header(px-loose@lg=24)與 body(px-loose@page=16)左緣不對齊;移除 → 全 surface 同密度 |
+
+**Tier alignment**:每個 overlay 宣告自己的 layout-space tier → header 高度隨之(Dialog lg → title 24 + py-tight 16×2 = 56;Popover md → 45)。「對齊 `--chrome-header-height`」是**同 tier 內**成立(Popover 45 ≠ Dialog 56 ≠ chrome 48 本就允許,各宣告各 tier),非跨 page 強制。詳 `patterns/header-canonical/header-canonical.spec.md` A 家族。
+
+**為何不鎖 ui-size**:field-height token 隨 density 變(md 28/32/36 → lg 32/36/40);鎖 ui-size=md 會把浮層內控件 / 選單 item 釘死 md-scale,lg page 上對不上 lg 觸發點。decouple = 只鎖版面間距、控件跟 page。對標 Carbon spacing scale 獨立於 control size / GitHub Primer 8px scale 獨立。
+
+### Canonical 情境 2 — 單獨切 ui-size
+
+Product demo / stakeholder 觀感測試:
+
+```ts
+document.documentElement.setAttribute('data-ui-size', 'lg')
+// layout-space 仍 md — 看大 control 在密集 layout 裡是否合用
+```
+
+### Canonical 情境 3 — 局部覆蓋
+
+某 region 需要不同密度:
+
+```tsx
+<div data-layout-space="lg">
+  {/* 這個 region layout 寬鬆,control 跟外層 page 走 */}
+</div>
+```
+
+## 動態切換
+
+```ts
+// 一鍵(兩維度同步)
+document.documentElement.setAttribute('data-density', 'lg')
+
+// 解耦(獨立控制)
+document.documentElement.setAttribute('data-ui-size', 'lg')
+document.documentElement.setAttribute('data-layout-space', 'md')
+```
+
+## 判斷流程(寫新元件時)
+
+1. **元件是否有自己特定 density**?
+   - 否(繼承 page) → 不設任何 `data-*-size` attribute,所有 token 由 `html[data-density]` 繼承
+   - 是 → 看 Q2
+
+2. **需要 layout 跟 control 同步 density 嗎**?
+   - 是 → 用 `data-density="X"`(convenience)
+   - 否(想解耦) → 明示 `data-layout-space="X"` + / 或 `data-ui-size="Y"`
+
+3. **Portal 逃逸 subtree?**(Dialog / Popover / Sheet / DropdownMenu / Tooltip)
+   - density 設在 `html` root 時,CSS cascade 會傳到 portal 出去的內容(portal 掛 body,仍在 html 底下)→ **浮層繼承 page density 正常,不需自設**。
+   - 只有 density 設在「中層 div」時 portal 才逃逸該 subtree(M3 邊界)。
+   - **鎖浮層 density/layout-space = 刻意覆蓋成某 tier,需設計理由(見情境 1 表)**,非 Portal 必要;且只鎖該元件真正消費的 dial。
+
+## 消費者清單
+
+| 元件 | attribute 設置 | 用法理由 |
+|------|---------------|---------|
+| Dialog | **無(繼承 page,2026-06-16)** | layout-space 定義即管 dialog body padding → 鎖 = override 自家 dial 自相矛盾;header 隨 page md=48 / lg=56;有同類 dial 的 SAP/Cloudscape modal 跟 dial |
+| Sheet | 無(繼承 page) | 側板;responsive 會跟常駐側板互換,不能跳 mode |
+| Popover / Coachmark | `data-layout-space="md"`(2026-06-15) | 輕量;header py-tight 精簡;ui-size 繼承 page → 內部控件對齊觸發點。Coachmark 建在 Popover 上自動繼承 |
+| DropdownMenu | 無(繼承 page,2026-06-15) | 不消費 layout-space token;鎖 ui-size 會讓 menu item(field-height-{size})對不上觸發點 |
+| Tooltip | 無(繼承 page,2026-06-15) | 不消費任何 density/layout-space token,鎖 = inert |
+| FileViewer | 無(繼承 page,2026-06-15) | 全螢幕 chrome 殼;原 lockDensity 只鎖 header 造成左緣不對齊 → 移除 |
+| Sidebar | 無(繼承 page) | inline chrome(非 Portal 逃逸),跟隨 page density;size="md" 在 density="lg" 下自動變 36px row(見 sidebar.spec.md)|
+
+**邊界:page density=lg 下的 Portal overlay**——Tooltip / DropdownMenu 繼承 page → lg page 上隨 page 放大,選單 item 對齊 lg 觸發點。Popover / Coachmark 鎖 layout-space=md(header 精簡)但 ui-size 仍繼承 lg(內部控件放大)。Dialog 繼承 page(不鎖)→ md 16 / lg 24 padding 隨 page。皆透過 `[data-layout-space="md|lg"]` reset selector(layoutSpace.css L21/L31)在任意 page density 上正確解析。
+
+## Anti-patterns(禁止)
+
+- ❌ 元件同時設 `data-density` + `data-ui-size`(重複,以後者為準但混亂)
+- ❌ **用 `data-density` master switch 鎖浮層**(連 ui-size 一起鎖 → 內部控件 / 選單 item 對不上觸發點)。只鎖該元件真正消費的 dial(見情境 1 表)
+- ❌ **把 density/layout-space lock 設在 header primitive(ChromeHeader / SurfaceHeader)而非 surface 根**——header 鎖、body 沒鎖 → 左緣不對齊(FileViewer 圖二 bug)。lock 一律放 surface 根容器
+- ❌ 為了追求表面一致性硬把 Dialog button 綁 lg ui-size(犧牲 header 高度 / strapline 彈性)
+- ❌ **鎖 Dialog 的 layout-space**(2026-06-16 定論)—— 本 spec 第 10 行定義 layout-space 就管「dialog body padding」,鎖 Dialog = 令自家 dial 對它點名要管的對象失效 = 自相矛盾;有同類 dial 的 SAP/Cloudscape 都讓 modal 跟 page dial。modal 寬鬆需求在 lg 階自然滿足(md 16 = Polaris 下限),不靠鎖。Popover/Coachmark 鎖 md 是另一回事(空間效率、消費 layout-space token、且為非阻斷錨定浮層)
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `file-viewer.spec.md`
+- `header-canonical.spec.md`