@qijenchen/design-system 0.1.0-beta.67 → 0.1.0-beta.68

package/ds-canonical/hooks/tests/test_check_story_invariants.sh

@@ -294,7 +294,7 @@ expect_block "16. R9 手刻 <div px-loose border-b border-divider> overlay heade
 run_hook "PreToolUse" "Write" "$TMP_DIR/r9-correct.stories.tsx" '
 export const Panel = () => (
   <div className="max-w-md flex flex-col rounded-lg border-border bg-surface-raised shadow-[var(--elevation-200)]">
-    <SurfaceHeader className="justify-between [--chrome-slot-h:1.25rem]">
+    <SurfaceHeader className="justify-between">
       <div className="flex-1 min-w-0"><PopoverTitle>正在上傳 3 個項目</PopoverTitle></div>
     </SurfaceHeader>
   </div>

package/ds-canonical/templates/dashboard-app.tsx

@@ -20,7 +20,7 @@
 //   3. 替換 DashboardPage 為真實業務 widgets(DataTable / Chart / Card 等 DS 元件)
 //   4. 替換 PageHeader rightSlot 的 primary action(若有)
 
-import { useState } from 'react'
+import { useState, type ReactElement } from 'react'
 import {
   AppShell,
   SidebarProvider,
@@ -97,9 +97,14 @@ function AppSidebar() {
 // 繞過 header-canonical 全部機械簽名 + 違反「消費 primitive 不 hand-craft」canonical;
 // 對齊 _demo-helpers.tsx PageHeader 同款消費形)──
 // SidebarTrigger 必有(primary-sidebar mode 的 menu toggle 入口,⌘B keyboard shortcut)
-// rightSlot 用 JSX.Element(非 React.ReactNode):workspace 內 app 自帶 @types/react 副本與
-// DS 套件 .d.ts 解析的 ReactNode 版本不相容(bigint 差異)— Element 兩邊皆可指派
-function PageHeader({ title, rightSlot }: { title: string; rightSlot?: JSX.Element }) {
+// rightSlot 型別用 ReactElement<any, any>(= 舊全域 JSX.Element 的去全域等價寫法):
+//   - 不用裸 JSX.Element:React 19 @types/react 移除「全域」JSX namespace → `JSX.Element` 在 fresh React19 install
+//     下 TS2503「Cannot find namespace 'JSX'」(本機 @types/react 19.2.15 仍含全域 shim → 源端 tsc 假陰性,
+//     只在 receiver 拿到無 shim 的 19.x fresh install 才炸;2026-06-12 bde81e7e 引入,brick 下游 receiver build + audit)
+//   - 不用裸 ReactElement:@types/react@19 預設參數由 any 改 unknown,`ReactElement<unknown>` 因 ReactPortal.children
+//     分支不可指派給 ReactNode(TS2322)→ 必顯式 <any, any>(JSX.Element 本就是 ReactElement<any, any>,語意不變)
+//   - 不用 ReactNode:workspace app 自帶 @types/react 副本與 DS .d.ts 的 ReactNode 版本 bigint 差異不相容
+function PageHeader({ title, rightSlot }: { title: string; rightSlot?: ReactElement<any, any> }) {
   return (
     <ChromeHeader className="bg-surface">
       <SidebarTrigger />

package/llms-full.txt

@@ -1,6 +1,6 @@
 # @qijenchen/design-system — 完整設計參考(llms-full)
 
-> 全 component / pattern 的 variants / sizes / 禁止事項。build-time 從 spec.md frontmatter 生成,禁手改。v0.1.0-beta.67。
+> 全 component / pattern 的 variants / sizes / 禁止事項。build-time 從 spec.md frontmatter 生成,禁手改。v0.1.0-beta.68。
 
 # Components
 

package/llms.txt

@@ -1,7 +1,7 @@
 # @qijenchen/design-system
 
 > World-class React design system(Radix/shadcn + Tailwind v4 + 自訂 design token)。
-> 54 components + 4 public patterns + design tokens。v0.1.0-beta.67。
+> 54 components + 4 public patterns + design tokens。v0.1.0-beta.68。
 
 本檔由 source(spec.md frontmatter + Storybook index)build-time 自動生成,**禁手改**(CI --check drift gate 守)。
 每元件 / pattern 的完整 variants / sizes / 禁止事項 全文見 [llms-full.txt](./llms-full.txt)。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qijenchen/design-system",
-  "version": "0.1.0-beta.67",
+  "version": "0.1.0-beta.68",
   "private": false,
   "description": "World-class design system — components, patterns, tokens, hooks (single source of truth for team distribution).",
   "type": "module",

package/src/components/Alert/alert.spec.md

@@ -142,7 +142,7 @@ Alert chrome corner 可承載多個 action(close 左側並排):
 
 ### Subtle(預設)
 
-淺底色 + 四邊 1px border(邊框採語意色的 hover tint)。99% 場景用 subtle——視覺重量適中,使用者注意但可繼續主要任務。不設 `data-theme`,元素跟隨頁面 theme。
+淺底色 + 四邊 1px border(邊框採 `--{hue}-text` = icon 同色,2026-06-15 user 拍板;原借 `-hover` 狀態 token 是語意 smell 已改)。99% 場景用 subtle——視覺重量適中,使用者注意但可繼續主要任務。不設 `data-theme`,元素跟隨頁面 theme。
 
 ### Solid
 

package/src/components/Alert/alert.tsx

@@ -23,12 +23,15 @@ import { Notice, useInverseTheme, SUBTLE_ICON_COLOR, type NoticeVariant } from '
  * fixed: 無圓角,full-width,無 border
  */
 
+// border 用 `--{hue}-text`(= icon 同色,2026-06-15 user 拍板「直接共用 hue-text,不開新 token」)。
+// 原借 `--{hue}-hover`(互動狀態 token)當靜態 border 是語意 smell + 跟 icon 不同色;
+// 改共用 hue-text(SUBTLE_ICON_COLOR 用的同一顆,blue-7 等)→ 0 新 token + border/icon cohesion。
 const SUBTLE_CONTAINER: Record<NoticeVariant, string> = {
   neutral: 'bg-muted border border-border',
-  info: 'bg-info-subtle border border-[var(--info-hover)]',
-  success: 'bg-success-subtle border border-[var(--success-hover)]',
-  warning: 'bg-warning-subtle border border-[var(--warning-hover)]',
-  error: 'bg-error-subtle border border-[var(--error-hover)]',
+  info: 'bg-info-subtle border border-[var(--info-text)]',
+  success: 'bg-success-subtle border border-[var(--success-text)]',
+  warning: 'bg-warning-subtle border border-[var(--warning-text)]',
+  error: 'bg-error-subtle border border-[var(--error-text)]',
 }
 
 const SOLID_HUE_BG: Record<string, string> = {

package/src/components/Button/button.spec.md

@@ -370,9 +370,9 @@ Button 自動加 **`data-unbounded="true"`** attribute 當 **`variant === 'text'
 
 **實際應用**:`SurfaceHeader` / `SurfaceFooter` 內建 CSS rule(SSOT 在 `overlay-surface.tsx` `CHROME_UNBOUNDED_SLOT`,此處僅引述不重述完整公式):
 ```css
-[&_[data-unbounded]]:my-[calc((var(--chrome-slot-h,var(--field-height-xs))-var(--field-height-sm))/2)]
+[&_[data-unbounded]]:my-[calc((var(--chrome-slot-h,calc(var(--font-body-lg-size)*1.5))-var(--field-height-sm))/2)]
 ```
-→ slot 高度由 `--chrome-slot-h` 參數化(default `var(--field-height-xs)`=24;Popover override 20)
+→ slot 高度由 `--chrome-slot-h` 參數化(default 衍生 `calc(var(--font-body-lg-size)*1.5)`=24;Popover-tier override = `COMPACT_HEADER_SLOT` 衍生 21;皆 title 字級改自動跟)
 → default(md): my=-2px / lg: my=-4px
 → 效果:Button native size 不變(sm 28/32,touch target 亦同),**layout 佔位縮到 24**(等效 xs 幾何),header = 24 + 2×tight = 48/56 = `--chrome-header-height` ✓
 

package/src/components/Checkbox/checkbox.principles.stories.tsx

@@ -2,6 +2,7 @@ import React from 'react'
 import LinkTo from '@storybook/addon-links/react'
 import type { Meta, StoryObj } from '@storybook/react'
 import { Checkbox } from './checkbox'
+import { CheckboxGroup } from './checkbox-group'
 import { Switch } from '@/design-system/components/Switch/switch'
 import { RadioGroup, RadioGroupItem } from '@/design-system/components/RadioGroup/radio-group'
 
@@ -64,17 +65,19 @@ export const UsageGuidance: Story = {
           note="勾選不代表立刻生效——使用者按「儲存」前都可以反悔。心智模型是「選擇 / 同意」，視覺語言強調「尚未確定」"
         >
           <div className="border border-border rounded-lg p-4 space-y-3">
-            <Checkbox
-              label="我同意服務條款與隱私政策"
-              checked={agree}
-              onCheckedChange={(v) => setAgree(v === true)}
-            />
-            <Checkbox
-              label="訂閱行銷訊息"
-              description="每月最多 2 封，可隨時取消"
-              checked={notif === 'checked'}
-              onCheckedChange={(v) => setNotif(v ? 'checked' : 'unchecked')}
-            />
+            <CheckboxGroup>
+              <Checkbox
+                label="我同意服務條款與隱私政策"
+                checked={agree}
+                onCheckedChange={(v) => setAgree(v === true)}
+              />
+              <Checkbox
+                label="訂閱行銷訊息"
+                description="每月最多 2 封，可隨時取消"
+                checked={notif === 'checked'}
+                onCheckedChange={(v) => setNotif(v ? 'checked' : 'unchecked')}
+              />
+            </CheckboxGroup>
             <div className="flex gap-2 pt-2">
               <button className="h-field-md px-3 text-body rounded-md bg-primary text-inverse-fg">儲存</button>
               <button className="h-field-md px-3 text-body rounded-md border border-border">取消</button>
@@ -119,7 +122,7 @@ export const UsageGuidance: Story = {
           title="vs Radio — Checkbox 是獨立 toggle(多選 或 單一 agreement)"
           note="每個 Checkbox 是獨立 boolean——可同時勾多個。也用於單一「我同意 X」agreement"
         >
-          <div className="space-y-2">
+          <CheckboxGroup>
             <Checkbox
               label="讀取權限"
               description="可查看資料"
@@ -138,7 +141,7 @@ export const UsageGuidance: Story = {
               checked={perms.admin}
               onCheckedChange={(v) => setPerms({ ...perms, admin: v === true })}
             />
-          </div>
+          </CheckboxGroup>
           <Label>↑ 權限可以任意組合——多選用 Checkbox</Label>
         </Rule>
 
@@ -158,11 +161,11 @@ export const UsageGuidance: Story = {
           title="❌ 多選一用 Checkbox"
           note="使用者可以同時勾 3 個 → 邏輯錯誤，破壞互斥語意"
         >
-          <div className="space-y-2">
+          <CheckboxGroup>
             <Checkbox label="信用卡" />
             <Checkbox label="銀行轉帳" />
             <Checkbox label="貨到付款" />
-          </div>
+          </CheckboxGroup>
           <Label warn>↑ 付款方式只能一個，卻用 Checkbox 允許多選 → 用 RadioGroup</Label>
         </Rule>
 

package/src/components/Coachmark/coachmark.principles.stories.tsx

@@ -26,6 +26,7 @@ import {
 } from '@/design-system/components/Dialog/dialog'
 import { Button } from '@/design-system/components/Button/button'
 import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
+import { CheckboxGroup } from '@/design-system/components/Checkbox/checkbox-group'
 
 const meta: Meta = {
   title: 'Design System/Components/Coachmark/設計原則',
@@ -138,10 +139,10 @@ export const UsageGuidance: Story = {
             <PopoverContent align="start">
               <PopoverHeader><PopoverTitle>依狀態篩選</PopoverTitle></PopoverHeader>
               <PopoverBody>
-                <div className="grid">
+                <CheckboxGroup>
                   <Checkbox defaultChecked label="進行中" />
                   <Checkbox label="已完成" />
-                </div>
+                </CheckboxGroup>
               </PopoverBody>
             </PopoverContent>
           </Popover>

package/src/components/DataTable/data-table-filter-panel.tsx

@@ -13,7 +13,7 @@ import { NumberInput } from '@/design-system/components/NumberInput/number-input
 import { DatePicker, DatePickerRange } from '@/design-system/components/DatePicker/date-picker'
 import { PeoplePicker } from '@/design-system/components/PeoplePicker/people-picker'
 import type { PersonValue } from '@/design-system/components/PeoplePicker/person-display'
-import { SurfaceHeader, SurfaceBody } from '@/design-system/patterns/overlay-surface/overlay-surface'
+import { SurfaceHeader, SurfaceBody, COMPACT_HEADER_SLOT } from '@/design-system/patterns/overlay-surface/overlay-surface'
 import { PopoverTitle, PopoverClose } from '@/design-system/components/Popover/popover'
 import { ButtonDivider } from '@/design-system/components/Button/button-group'
 import { FieldControlGroup } from '@/design-system/components/FieldControlGroup/field-control-group'
@@ -551,8 +551,8 @@ function DataTableFilterPanelInner<TData>({
         : 'w-[min(640px,calc(100vw-2rem))]',
       className,
     )}>
-      {/* Popover 派輕量 chrome — slot 縮 20 匹配 PopoverTitle text-body line-height,header 自然 ~45px */}
-      <SurfaceHeader className="[--chrome-slot-h:1.25rem]">
+      {/* Popover 派輕量 chrome — slot 走 COMPACT_HEADER_SLOT(=21,衍生自 PopoverTitle text-body line-box),header 自然 ~45px */}
+      <SurfaceHeader className={COMPACT_HEADER_SLOT}>
         <PopoverTitle className="flex-1">篩選</PopoverTitle>
         {/* Refresh icon — 只在 value ≠ defaultValue 時顯示(對齊 sort modified-from-default UX)
             含 ButtonDivider 對齊「欄位顯示」+「排序」chrome corner action canonical(2026-05-04) */}

package/src/components/DataTable/data-table-sort-manager.tsx

@@ -10,7 +10,7 @@ import { cn } from '@/lib/utils'
 import { dragSourceStyle, dragHandleCursorClass } from '@/design-system/lib/drag-visual'
 import { Button } from '@/design-system/components/Button/button'
 import { Select, type SelectOption } from '@/design-system/components/Select/select'
-import { SurfaceHeader, SurfaceBody } from '@/design-system/patterns/overlay-surface/overlay-surface'
+import { SurfaceHeader, SurfaceBody, COMPACT_HEADER_SLOT } from '@/design-system/patterns/overlay-surface/overlay-surface'
 import { ButtonDivider } from '@/design-system/components/Button/button-group'
 import { PopoverTitle, PopoverClose } from '@/design-system/components/Popover/popover'
 import { ItemInlineActionButton } from '@/design-system/patterns/element-anatomy/item-anatomy'
@@ -108,8 +108,8 @@ export function DataTableSortManager<TData>({
   // 2026-05-23 Phase A.4 Decision 2: w-[480px] → token `--data-table-sort-panel-width`(SSOT in uiSize.css)
   return (
     <div className={cn('flex flex-col h-full min-h-0 w-[var(--data-table-sort-panel-width)]', className)}>
-      {/* Popover 派輕量 chrome — slot 縮 20 匹配 PopoverTitle text-body line-height,header 自然 ~45px */}
-      <SurfaceHeader className="[--chrome-slot-h:1.25rem]">
+      {/* Popover 派輕量 chrome — slot 走 COMPACT_HEADER_SLOT(=21,衍生自 PopoverTitle text-body line-box),header 自然 ~45px */}
+      <SurfaceHeader className={COMPACT_HEADER_SLOT}>
         <PopoverTitle className="flex-1">排序</PopoverTitle>
         {onReset && sorting.length > 0 && (
           <>

package/src/components/Dialog/dialog.anatomy.stories.tsx

@@ -417,7 +417,7 @@ export const ColorMatrix: Story = {
     <div className="flex flex-col gap-8">
       <div>
         <H3>Density</H3>
-        <Desc>Dialog 繼承 page `data-density`(v5 校準,跟 Sheet 對齊)— 不自設密度 attribute。先前曾設 `data-layout-space="lg"` 給 body 寬鬆呼吸,但跟 `--chrome-header-height` canonical(md=48)衝突,2026-04-22 撤回。世界級:Polaris Modal px 16(md loose)/ Material M3 24(lg loose)— 我方跟 page density 自動對齊。</Desc>
+        <Desc>Dialog 鎖 `data-layout-space="lg"`(只鎖版面間距 tier)+ ui-size 繼承 page `data-density`(控件不被撐大)。modal 值得寬鬆呼吸 padding:body px-loose 24 / header py-tight 16 → header 56(宣告 lg tier)。reinstate c3d3b736 decouple(只鎖 layout-space,非當年連 ui-size 一起鎖撐高 header 的 density)。世界級:Material M3 / Atlassian modal padding 24。</Desc>
       </div>
 
       <div>

package/src/components/Dialog/dialog.spec.md

@@ -58,17 +58,17 @@ DialogContent (fixed, centered)
 
 **Padding SSOT**：Header / Body / Footer 的 padding + 分隔線由 `patterns/overlay-surface/overlay-surface.spec.md` own——Dialog 與 Popover 共用同一套 primitive，避免 token 漂移。Dialog 特有行為:Header 的 Close 按鈕;Body 用 `<ScrollArea>` wrap(viewport-fill 專用,SSOT 見 overlay-surface.spec.md 「Body overflow canonical」節 + `components/ScrollArea/scroll-area.spec.md`)。
 
-## Density(2026-04-22 v5 校準:繼承 page density,跟 Sheet 對齊)
+## Density(2026-06-16 定論:全繼承 page,不鎖)
 
-Dialog **繼承 page `data-density`**,不自設密度 attribute。這是 overlay primitive 的 canonical(跟 `components/Sheet/sheet.tsx` 對齊 — Sheet 不自設 density,繼承 page 層級 `html[data-density]`,見 sheet.tsx line 111 canonical)。
+Dialog **不自設任何 density attribute**,layout-space + ui-size 全繼承 page。效果:md page → body `px-loose`=16 / header `py-tight`=12(header 48);lg page → 24 / 16(header 56),隨 page。
 
-**歷史備忘**:先前曾設 `data-layout-space="lg"` 給 header/body 寬鬆呼吸,但跟 `--chrome-header-height` canonical 衝突(md page dialog header 期望 48,強設 lg 會變 56)。**已於 2026-04-22 v5 撤回**,Dialog 全盤繼承 page density,header 高度 = `--chrome-header-height` 自動對齊(md=48 / lg=56)。
+**為何不鎖(撤回本 session 一度加的 `data-layout-space="lg"`)**:本 `density.spec` 第 10 行親自定義 layout-space 管「dialog body padding」—— Dialog 若鎖死 layout-space,等於 override 我們自家 dial 對它點名要管的對象失效 = **自相矛盾**。有「同類 padding-density dial」的世界級 DS(SAP Fiori cozy/compact 做 `syncStyleClass` 專門把 page density 同步進 dialog;AWS Cloudscape compact「propagate to all components, in all view types」,例外只列 informational + tiny dropdown,modal 不在內)都讓 **modal 跟 page dial 走**,沒有一家把 modal 釘固定 tier。Material/Atlassian 的固定 24 是因為它們**沒有** density dial(其 24 = 我方 lg)。
 
-**世界級對照**:
-- Polaris Modal:px 16(= md loose)
-- Material M3 Dialog:px 24(= lg loose)
-- Atlassian Dialog:px 24
-- 我方:跟隨 page density,md=16 / lg=24,兩端都在世界級 range 內。
+**「modal 要寬鬆呼吸」怎麼滿足**:lg 產品自動拿 24(Material 級);md 產品本就要緊湊(資訊密集),16 是合格 modal padding(Polaris Modal = 16,世界級下限)。**「button 不撐高 header」**由 ui-size 繼承 page 解決(button = page sm),與 layout-space 鎖不鎖無關 → 故不需鎖。
+
+**Header 高度**:padding-based = title line-box 24 + `py-tight`×2 → md 48 / lg 56,**隨 page tier**(= `--chrome-header-height` 同 tier 對齊)。
+
+**世界級對照**:Material M3 / Atlassian 24(無 dial,= 我方 lg)/ Polaris 16(= 我方 md 下限)/ SAP Fiori + Cloudscape(有 dial → modal 跟 dial = 我方繼承)。
 
 ## Layout
 
@@ -99,8 +99,8 @@ Modal 與 viewport 四邊保持 `--layout-space-bottom`（48px）最小間距。
 
 永遠存在於 DialogHeader 右側。使用 `<Button data-dismiss iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />`，不可移除——使用者永遠需要明確的關閉手段。
 
-**Size canonical(v5 chrome-unbounded)**:Button native size **sm**(28 md / 32 lg),touch target 亦同。SurfaceHeader 的 `[data-unbounded]` CSS rule 自動對 text variant / dismiss 套負 my `calc((xs-sm)/2)` → **layout 佔位 = 24**(xs 固定)。效果:
-- Header 只有 title + close X → max layout = 24 → header = 24 + 2×tight = **48 md / 56 lg = `--chrome-header-height`** ✓
+**Size canonical(v5 chrome-unbounded)**:Button native size **sm**(隨 page density:28 md / 32 lg),touch target 亦同。SurfaceHeader 的 `[data-unbounded]` CSS rule 自動對 text variant / dismiss 套負 my → **layout 佔位 = title line-box**(slot 衍生自 `--font-body-lg-size`×1.5=24,見 `overlay-surface.spec.md` slot 段)。效果:
+- Header 只有 title + close X → max layout = 24 → header = 24 + 2×`py-tight`(隨 page:md 12 / lg 16)= **48 md / 56 lg**(= `--chrome-header-height` 同 tier 對齊)✓
 - Header 塞 bounded primary(無 `data-unbounded`)→ header 自然長高
 
 **Canonical 來源**:Dialog 是 overlay chrome，corner close X 屬 action group region，必用 Button(非 Inline Action / 非自刻 button)。詳見 `patterns/element-anatomy/item-anatomy.spec.md`「Dismiss canonical」+ `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical」。
@@ -142,7 +142,7 @@ Dialog 是容器，無整體 disabled / loading / empty 狀態——這些屬於
 
 **Dark mode**：由 semantic token（`bg-surface-raised` / `border-border`）自動切換，無自訂 palette。
 
-**Density**:Dialog **繼承 page density**(v5 校準,跟 Sheet 對齊),見上「Density」段。
+**Density**:Dialog **全繼承 page**(layout-space + ui-size 皆不自鎖),見上「Density」段。
 
 ---
 

package/src/components/Dialog/dialog.tsx

@@ -95,14 +95,13 @@ const DialogContent = React.forwardRef<
       <DialogOverlay />
       <DialogPrimitive.Content
         ref={ref}
-        // Density canonical(2026-04-22 v5 校準):Dialog 繼承 page density(跟 Sheet 對齊
-        // sheet.tsx line 111 canonical),不自設 data-layout-space="lg" 或 data-density。
-        //
-        // 先前曾設 `data-layout-space="lg"` 給 header/body 寬鬆呼吸,但跟 chrome-header-height
-        // canonical 衝突(md page dialog header 期望 48,強設 lg 會變 56)。
-        // 世界級對照:Polaris Modal horizontal padding 16 / Material M3 24 / Atlassian 24 — 16 是
-        // 合理 lower bound;md page 用 16 loose body padding 可接受,lg page 自動 24。
-        // 詳 overlay-surface.spec.md「Chrome dismiss size canonical」
+        // Density:**全繼承 page**(layout-space + ui-size 都不自鎖)。2026-06-16 定論(撤回本 session 一度加的
+        // data-layout-space="lg"):density.spec 第 10 行親自定義 layout-space 管「dialog body padding」——
+        // Dialog 鎖死它 = override 自家 dial 對它點名要管的對象失效 = 自相矛盾。有同類 padding-density dial 的
+        // 世界級(SAP Fiori syncStyleClass / AWS Cloudscape「all view types」)都讓 modal 跟 page dial 走、不鎖固定 tier。
+        // 效果:md page → body px-loose 16 / header py-tight 12(header 48);lg page → 24 / 16(header 56),隨 page。
+        // 「modal 要寬鬆」需求在 lg 階自然滿足(Polaris modal 16 = 世界級下限,證明 md 16 合格);「button 不撐高
+        // header」由 ui-size 繼承 page 解決(button=page sm),與 layout-space 鎖不鎖無關 → 故不需鎖。
         onOpenAutoFocus={handleOpenAutoFocus}
         className={cn(
           "fixed left-1/2 top-1/2 z-50 w-full -translate-x-1/2 -translate-y-1/2",

package/src/components/DropdownMenu/dropdown-menu.tsx

@@ -129,7 +129,10 @@ const DropdownMenuContent = React.forwardRef<
       sideOffset={sideOffset}
       collisionPadding={collisionPadding}
       align={align}
-      data-density="md"
+      // Density:繼承 page density(2026-06-15 canonical)。menu item 高度 = field-height-{size},而
+      // field-height 隨 density 變(md 28/32/36 → lg 32/36/40)→ 鎖 data-density="md" 會把選單釘在 md-scale,
+      // lg page 上對不上 lg 觸發點。原 data-density 是 409b91da a11y 批次順手加(對齊 Popover),非設計
+      // 決策 → 移除,item 隨 page density 與觸發點一致(tier 仍由 size prop 決定)。
       // Focus return on close:不 override `onCloseAutoFocus` — 用 Radix 內建 default
       // (close 時 focus 還 trigger;outside-interaction 例外由 Radix `hasInteractedOutsideRef` 自管)。
       // W3C APG menubar「Escape: …return focus to the element…from which the menu was opened」

package/src/components/FileItem/file-item.spec.md

@@ -293,7 +293,7 @@ upload-manager 的 completed(100% bar + ✓)屬「剛完成的 upload session」
 - **它是 popover-class 浮層 surface,但不是 Radix `<Popover>`**(常駐面板:不靠 trigger 開、不 outside-click 關、用 chevron 收合非 X dismiss)→ **不包 `<Popover>`**,而是直接消費 overlay-surface 三件套 primitive。
 - **殼 + header + body 全消費 overlay-surface SSOT(禁手刻)**:
   - 殼:用 Popover 同款 chrome token `rounded-lg border border-border bg-surface-raised shadow-[var(--elevation-200)] flex flex-col`(DS 無獨立 shell primitive — `PopoverContent`/`DialogContent` 各自套這組 token;常駐面板鏡像同值)。
-  - header:`<SurfaceHeader className="justify-between [--chrome-slot-h:1.25rem]">` + `<PopoverTitle>`(輕量浮層 header SSOT,padding = px-loose py-tight + border-b + unbounded-slot 負 my trick)。
+  - header:`<SurfaceHeader className={cn("justify-between", COMPACT_HEADER_SLOT)}>` + `<PopoverTitle>`(輕量浮層 header SSOT,slot 走 `COMPACT_HEADER_SLOT`=21 衍生自 text-body title;padding = px-loose py-tight + border-b + unbounded-slot 負 my trick)。
   - body:**`<SurfaceBody>`(body SSOT,含 px-loose py-tight + flex-1 scroll 鏈)**,FileItem-specific padding 用 className override(見下)。**這不是「List-as-region」**(那專指 edge-to-edge 選單清單:item hover-bg 貼容器、px-0;Cmd+K / menu / nav)—— upload-manager list 有 px-loose、item 無 hover-bg、是 chrome-padded body,故就用 SurfaceBody。**scroll(consumer 注意)**:SurfaceBody 的 `flex-1 / overflow-y-auto` 只在 shell 有 `max-h` + `overflow-hidden` 時生效;常駐面板若檔案數可超 viewport,shell 須加 `max-h`(對齊 overlay-surface.spec.md「viewport-aware scroll」),demo 短內容不需。
   - **禁手刻**:`<div px-loose py-2 border-b>`(header)/ 手刻 `<div px-loose py-tight>`(body)= drift(2026-06-03/04 user 抓:py-2≠py-tight / 殼 token 全偏 / body 重刻 SurfaceBody)。Hook `check_story_invariants.sh R9` 機械攔手刻 header。
 

package/src/components/FileItem/file-item.stories.tsx

@@ -6,7 +6,7 @@ import { FileItem } from './file-item'
 import { Button } from '@/design-system/components/Button/button'
 import { FileViewer, type FileInfo } from '@/design-system/components/FileViewer/file-viewer'
 // upload-manager 面板消費 overlay-surface header + body SSOT(非手刻)—— 跟 Popover/Dialog 同一組 primitive
-import { SurfaceHeader, SurfaceBody } from '@/design-system/patterns/overlay-surface/overlay-surface'
+import { SurfaceHeader, SurfaceBody, COMPACT_HEADER_SLOT } from '@/design-system/patterns/overlay-surface/overlay-surface'
 import { PopoverTitle } from '@/design-system/components/Popover/popover'
 
 // 錯誤 description 範例(含 clickable "View log"):consumer 自由 ReactNode,通常用底線 link 表 clickable
@@ -217,7 +217,7 @@ export const UploadManagerSurface = {
     <div className="max-w-md flex flex-col rounded-lg border border-border bg-surface-raised shadow-[var(--elevation-200)]">
       {/* header 消費 overlay-surface SurfaceHeader + PopoverTitle(輕量浮層 chrome SSOT,非手刻):
           px-loose py-tight + border-b + chevron(variant=text → 自動 data-unbounded → 套 slot 負 my trick)*/}
-      <SurfaceHeader className="justify-between [--chrome-slot-h:1.25rem]">
+      <SurfaceHeader className={`justify-between ${COMPACT_HEADER_SLOT}`}>
         <div className="flex-1 min-w-0"><PopoverTitle>正在上傳 3 個項目</PopoverTitle></div>
         <Button iconOnly variant="text" size="sm" startIcon={ChevronDown} aria-label="收合" onClick={noop} />
       </SurfaceHeader>
@@ -243,7 +243,7 @@ export const UploadManagerCompactSurface = {
   render: () => (
     <div className="max-w-md flex flex-col rounded-lg border border-border bg-surface-raised shadow-[var(--elevation-200)]">
       {/* header 消費同一個 overlay-surface SurfaceHeader + PopoverTitle SSOT(同 rich panel)*/}
-      <SurfaceHeader className="justify-between [--chrome-slot-h:1.25rem]">
+      <SurfaceHeader className={`justify-between ${COMPACT_HEADER_SLOT}`}>
         <div className="flex-1 min-w-0"><PopoverTitle>同步 3 個檔案</PopoverTitle></div>
         <Button iconOnly variant="text" size="sm" startIcon={ChevronDown} aria-label="收合" onClick={noop} />
       </SurfaceHeader>

package/src/components/FileViewer/file-viewer.anatomy.stories.tsx

@@ -394,7 +394,7 @@ export const Inspector: Story = {
                 </tr>
                 <tr>
                   <Td>Toolbar 高度</Td>
-                  <Td mono>--chrome-header-height(lg=56px,ChromeHeader lockDensity="lg",與 InfoPanel header 等高)</Td>
+                  <Td mono>--chrome-header-height(隨 page:48 md / 56 lg,ChromeHeader 繼承 page,與 InfoPanel header 等高)</Td>
                 </tr>
                 <tr>
                   <Td>Toolbar 水平 padding</Td>
@@ -632,9 +632,9 @@ export const SizeMatrix: Story = {
               </tr>
               <tr>
                 <Td>Toolbar 高</Td>
-                <Td mono>--chrome-header-height(lg=56px)</Td>
+                <Td mono>--chrome-header-height(48 md / 56 lg)</Td>
                 <Td>Figma toolbar 48–56 / macOS Preview 56</Td>
-                <Td>ChromeHeader lockDensity="lg",token 驅動;lg 下值為 56px</Td>
+                <Td>ChromeHeader 繼承 page density,token 驅動;md=48 / lg=56(2026-06-15 移除 lockDensity)</Td>
               </tr>
               <tr>
                 <Td>InfoPanel 寬</Td>
@@ -698,7 +698,7 @@ export const SizeMatrix: Story = {
               <tr>
                 <Td>Panel header 高</Td>
                 <Td mono>--chrome-header-height</Td>
-                <Td>消費 &lt;ChromeHeader lockDensity=&quot;lg&quot;&gt;,lg = 56px;與 Toolbar 等高,視覺水平對齊</Td>
+                <Td>消費 &lt;ChromeHeader&gt;(繼承 page density);md=48 / lg=56,與 Toolbar 等高,視覺水平對齊</Td>
               </tr>
               <tr>
                 <Td>Body 水平 padding</Td>

package/src/components/FileViewer/file-viewer.spec.md

@@ -100,7 +100,7 @@ Family 的 canonical 規定的是「同用途同 layout」;FileViewer 用途(ful
 ```
 
 **分區決策**:
-- **Toolbar 高度 = `--chrome-header-height`**(md=48 / lg=56)——與 InfoPanel header 同高,視覺對齊;**code 已消費 `<ChromeHeader>` primitive**(`file-viewer.tsx:328` Toolbar + `:459` InfoPanel header,皆 `<ChromeHeader lockDensity="lg">`),高度由 primitive 內部套 `h-[var(--chrome-header-height)]`(`chrome-header.tsx`),tsx 不硬寫 height className。**跨家族 SSOT pointer**:FileViewer Toolbar + InfoPanel header 屬 **Chrome header(Fixed-h)家族**,border / padding / dismiss size / withTabs 跨家族契約 SSOT 詳 `patterns/header-canonical/header-canonical.spec.md`。viewer 需 lock lg density 走 `lockDensity="lg"` prop。
+- **Toolbar 高度 = `--chrome-header-height`**(隨 page density:md=48 / lg=56)——與 InfoPanel header 同高,視覺對齊;**code 已消費 `<ChromeHeader>` primitive**(Toolbar + InfoPanel header,皆 `<ChromeHeader>` **繼承 page density**,2026-06-15 移除 lockDensity),高度由 primitive 內部套 `h-[var(--chrome-header-height)]`(`chrome-header.tsx`),tsx 不硬寫 height className。**跨家族 SSOT pointer**:FileViewer Toolbar + InfoPanel header 屬 **Chrome header(Fixed-h)家族**,border / padding / dismiss size / withTabs 跨家族契約 SSOT 詳 `patterns/header-canonical/header-canonical.spec.md`。FileViewer **不鎖 density**(全 surface 繼承 page;原 `lockDensity="lg"` 只鎖兩個 header、沒鎖 body → header(px-loose@lg=24)與 body(px-loose@page=16)左緣不對齊 = 圖二 bug,已移除,見 `density.spec.md` 消費者清單)。
 - **Viewport `flex-1`**——填滿剩餘空間;InfoPanel 透過 `w-80 shrink-0` 從右側切出,不吃 viewport 自然寬
 - **Filmstrip 固定 h-24**——預留 thumb 64 + padding;只在 `showFilmstrip && files.length > 1` 時顯示
 - **Prev/Next arrows 絕對定位**——避免 layout shift,只在 `files.length > 1` 渲染
@@ -244,7 +244,7 @@ Shell 看到 `pageNumber` capability 時自動在 toolbar 顯示 page navigator(
 
 ### 同 flex 列幾何鐵律(CLAUDE.md 規則)
 
-`[−]` / `[%input]` / `[+]` 三個 slot **都是 h-field-sm**,統一高度確保 gap 不被 hover bg 吃掉。Toolbar 包在 `<ChromeHeader lockDensity="lg">`(`file-viewer.tsx:328`)內,subtree density = lg → h-field-sm 解析為 **32px**(對齊本 spec「Density」段 L313 + `uiSize.spec.md`:sm 在 md density = 28px / lg density = 32px)。Button iconOnly size="sm" aspect-square ≈ 32×32,Input size="sm" 32 高,視覺嚴格對齊。
+`[−]` / `[%input]` / `[+]` 三個 slot **都是 h-field-sm**,統一高度確保 gap 不被 hover bg 吃掉。Toolbar 包在 `<ChromeHeader>`(繼承 page density,2026-06-15 移除 lockDensity)內 → h-field-sm 隨 page density 解析(`uiSize.spec.md`:sm 在 md = 28px / lg = 32px)。Button iconOnly size="sm" aspect-square 與 Input size="sm" 同高,視覺嚴格對齊。
 
 ### Why inline(不抽獨立 primitive)
 
@@ -255,7 +255,7 @@ Shell 看到 `pageNumber` capability 時自動在 toolbar 顯示 page navigator(
 ## InfoPanel 規則
 
 - **寬度固定 w-80(320px)**——對齊 Figma right panel(320)的業界慣例;Google Photos 用 360 偏寬,FileViewer 走 Figma 偏窄以讓 viewport 多一些空間 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-- **Header 高度 = `--chrome-header-height`**(56px @ viewer lockDensity="lg")——與 Toolbar 等高,視覺對齊;消費 `<ChromeHeader lockDensity="lg">`(`file-viewer.tsx:459`)
+- **Header 高度 = `--chrome-header-height`**(隨 page density:48 md / 56 lg)——與 Toolbar 等高,視覺對齊;消費 `<ChromeHeader>`(繼承 page,2026-06-15 移除 lockDensity)
 - **內容分兩區**:
   - 「說明」Textarea(可編輯 / readOnly 依 `readOnly` prop)
   - 「檔案資訊」`<dl>`:檔名 / 類型 / 大小 / 自訂 metadata 條目
@@ -310,7 +310,7 @@ Shell 看到 `pageNumber` capability 時自動在 toolbar 顯示 page navigator(
 
 **Dark mode**:FileViewer chrome 鎖 dark(`data-theme="dark"` subtree);背景頁面的 theme 不影響 viewer chrome——viewer 是獨立沉浸式 context,類似 Tooltip / 全螢幕影片播放器的 convention。
 
-**Density**:FileViewer chrome 走 `<ChromeHeader lockDensity="lg">`(`file-viewer.tsx:328,459` Toolbar + InfoPanel header),強制 lg-equivalent chrome-header-height = 56px;Filmstrip `h-24`(96px)+ thumb 64×64 屬媒體展示框尺寸,**刻意不隨 density 放大**(viewer 是展示殼不是工作區)。Toolbar 內的 `<Button size="sm">` 與 `<ZoomInput h-field-sm>` 會隨 density 微調(sm 在 md density = 28px,lg density = 32px),在 viewer 這個尺度可忽略。
+**Density**:FileViewer **全 surface 繼承 page density**(2026-06-15 移除 lockDensity — 原本只鎖兩個 ChromeHeader、沒鎖 body → header(px-loose@lg=24)與 body(px-loose@page=16)左緣不對齊,圖二 bug)。chrome-header-height 隨 page(48 md / 56 lg),header 與 body 同密度 → 左緣對齊;Filmstrip `h-24`(96px)+ thumb 64×64 屬媒體展示框尺寸,**刻意不隨 density 放大**(viewer 是展示殼不是工作區)。Toolbar 內 `<Button size="sm">` 與 `<ZoomInput h-field-sm>` 隨 page density(sm 在 md = 28px / lg = 32px)。
 
 ---
 

package/src/components/FileViewer/file-viewer.tsx

@@ -338,7 +338,9 @@ const Toolbar: React.FC<ToolbarProps> = ({
 }) => {
   return (
     <ChromeHeader
-      lockDensity="lg"
+      // Density:繼承 page(2026-06-15 canonical)。原 lockDensity="lg" 只鎖在 header、沒鎖 body →
+      // InfoPanel header(px-loose@lg=24)與其 body(px-loose@page=16)左緣不對齊(圖二 bug)。移除 lock
+      // → header + body 全繼承 page density,左緣對齊;FileViewer 全 surface 同一密度(non-special)。
       className={cn(
         // Chrome layer — `bg-surface-raised` 對齊 token semantic「遮蓋型浮層必須不透明」。
         // FileViewer 整體是 overlay,chrome 屬其 raised surface(同 DropdownMenuContent line 244)。
@@ -467,8 +469,9 @@ const InfoPanel: React.FC<InfoPanelProps> = ({
       )}
       aria-label={labels.detailPanel}
     >
-      {/* Panel header — 與 Toolbar 等高(consume ChromeHeader lockDensity="lg"),視覺一致 */}
-      <ChromeHeader lockDensity="lg" className="justify-between">
+      {/* Panel header — 與 Toolbar 同 ChromeHeader,繼承 page density(2026-06-15:移除 lockDensity,
+          修 header(原 px-loose@lg=24)與 body(px-loose@page=16)左緣不對齊 = 圖二 bug;全 surface 同密度)。 */}
+      <ChromeHeader className="justify-between">
         <h3 className="text-body-lg font-medium text-foreground">{labels.detailsHeading}</h3>
         {/* InfoPanel close 走 dismiss canonical `<Button iconOnly dismiss />`,對齊 button.spec.md
             「Dismiss 視覺類」+ inline-action.spec.md「Dismiss canonical — X close only」。 */}

package/src/components/Notice/notice.anatomy.stories.tsx

@@ -53,10 +53,10 @@ const VARIANT_ICON: Record<NoticeVariant, LucideIcon | null> = {
 
 const SUBTLE_CONTAINER: Record<NoticeVariant, string> = {
   neutral: 'bg-muted border border-border',
-  info: 'bg-info-subtle border border-[var(--info-hover)]',
-  success: 'bg-success-subtle border border-[var(--success-hover)]',
-  warning: 'bg-warning-subtle border border-[var(--warning-hover)]',
-  error: 'bg-error-subtle border border-[var(--error-hover)]',
+  info: 'bg-info-subtle border border-[var(--info-text)]',
+  success: 'bg-success-subtle border border-[var(--success-text)]',
+  warning: 'bg-warning-subtle border border-[var(--warning-text)]',
+  error: 'bg-error-subtle border border-[var(--error-text)]',
 }
 
 function SubtleShell({ variant, children }: { variant: NoticeVariant; children: React.ReactNode }) {

package/src/components/Notice/notice.spec.md

@@ -154,4 +154,5 @@ Notice **不**自帶 Esc-to-dismiss 行為(`notice.tsx` 無 keydown handler);dis
 - `alert.spec.md`
 - `bulk-action-bar.spec.md`
 - `coachmark.spec.md`
+- `item-anatomy.spec.md`
 - `toast.spec.md`

package/src/components/Notice/notice.stories.tsx

@@ -26,10 +26,10 @@ type Story = StoryObj<typeof Notice>
 
 const SUBTLE_CONTAINER: Record<NoticeVariant, string> = {
   neutral: 'bg-muted border border-border',
-  info: 'bg-info-subtle border border-[var(--info-hover)]',
-  success: 'bg-success-subtle border border-[var(--success-hover)]',
-  warning: 'bg-warning-subtle border border-[var(--warning-hover)]',
-  error: 'bg-error-subtle border border-[var(--error-hover)]',
+  info: 'bg-info-subtle border border-[var(--info-text)]',
+  success: 'bg-success-subtle border border-[var(--success-text)]',
+  warning: 'bg-warning-subtle border border-[var(--warning-text)]',
+  error: 'bg-error-subtle border border-[var(--error-text)]',
 }
 
 const SOLID_BG: Record<Exclude<NoticeVariant, 'neutral'>, string> = {

package/src/components/Popover/popover.anatomy.stories.tsx

@@ -2,6 +2,8 @@
 import type { Meta, StoryObj } from '@storybook/react'
 import { Popover, PopoverTrigger, PopoverContent, PopoverHeader, PopoverBody, PopoverFooter, PopoverTitle } from './popover'
 import { Button } from '@/design-system/components/Button/button'
+import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
+import { CheckboxGroup } from '@/design-system/components/Checkbox/checkbox-group'
 import { H3, Desc, Td, Th, TokenCell } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
 
 const meta: Meta = {
@@ -26,11 +28,11 @@ export const Overview: Story = {
             <PopoverContent>
               <PopoverHeader><PopoverTitle>依類型篩選</PopoverTitle></PopoverHeader>
               <PopoverBody>
-                <div className="flex flex-col gap-1.5 text-caption text-fg-secondary">
-                  <label className="flex items-center gap-2"><input type="checkbox" defaultChecked /> 待處理</label>
-                  <label className="flex items-center gap-2"><input type="checkbox" defaultChecked /> 進行中</label>
-                  <label className="flex items-center gap-2"><input type="checkbox" /> 已完成</label>
-                </div>
+                <CheckboxGroup>
+                  <Checkbox defaultChecked label="待處理" />
+                  <Checkbox defaultChecked label="進行中" />
+                  <Checkbox label="已完成" />
+                </CheckboxGroup>
               </PopoverBody>
               <PopoverFooter>
                 <Button variant="tertiary" size="sm" className="flex-1">清除</Button>
@@ -129,11 +131,11 @@ export const Inspector: Story = {
               <PopoverHeader><PopoverTitle>依類型篩選</PopoverTitle></PopoverHeader>
             )}
             <PopoverBody>
-              <div className="flex flex-col gap-1.5 text-caption text-fg-secondary">
-                <label className="flex items-center gap-2"><input type="checkbox" defaultChecked /> 待處理</label>
-                <label className="flex items-center gap-2"><input type="checkbox" defaultChecked /> 進行中</label>
-                <label className="flex items-center gap-2"><input type="checkbox" /> 已完成</label>
-              </div>
+              <CheckboxGroup>
+                <Checkbox defaultChecked label="待處理" />
+                <Checkbox defaultChecked label="進行中" />
+                <Checkbox label="已完成" />
+              </CheckboxGroup>
             </PopoverBody>
             {showFooter && (
               <PopoverFooter>
@@ -194,7 +196,7 @@ export const ColorMatrix: Story = {
               <tr><Td>次要文字</Td><Td><TokenCell token="--fg-secondary" display="text-fg-secondary" /></Td><Td>說明 / 次要資訊</Td></tr>
               <tr><Td>圓角</Td><Td mono>rounded-lg(8px)</Td><Td>對齊 Dialog radius(浮層視覺語言一致)</Td></tr>
               <tr><Td>陰影</Td><Td mono>--elevation-200</Td><Td>浮層級 elevation(見 `elevation.spec.md`)</Td></tr>
-              <tr><Td>Density</Td><Td mono>data-density="md"</Td><Td>Popover 永遠鎖 md,不隨頁面 density 放大(lightweight)</Td></tr>
+              <tr><Td>Layout-space</Td><Td mono>data-layout-space="md"</Td><Td>只鎖版面間距(header py-tight 精簡);ui-size 跟 page → 內部控件對齊觸發點(2026-06-15 改,原 data-density master switch)</Td></tr>
               <tr><Td>Header/Body/Footer padding</Td><Td mono>px-[loose] py-[tight]</Td><Td>結構化 sub-components 採 Dialog 同一套 padding token</Td></tr>
               <tr><Td>Portal z-index</Td><Td mono>z-50</Td><Td>Radix Portal 統一層級,避開一般頁面內容</Td></tr>
             </tbody>