@qijenchen/design-system 0.1.0-beta.85 → 0.1.0-beta.87

package/src/components/TreeView/tree-view.spec.md

@@ -3,9 +3,9 @@ component: TreeView
 family: 1
 variants: {}
 sizes:
-  sm: { when: "緊湊清單(與 md 同視覺:text-body、indent 24;保留供密度語意)" }
+  sm: { when: "緊湊清單(與 md 同視覺,保留供密度語意)" }
   md: { when: "default 一般導覽樹" }   # ★ default
-  lg: { when: "touch / 大字級(text-body-lg、px-4 py-2、indent 28)" }
+  lg: { when: "touch / 大字級" }
 traits:
   - hasInteractiveStates
   - isStructural
@@ -41,7 +41,7 @@ TreeView 本身只負責三件事:
 
 - **階層結構資料**：檔案管理器資料夾樹、部門組織架構、專案 / 子專案 / 任務、權限群組
 - **Sidebar 內的分層導覽**：workspace > channel > thread、product > category > item
-- **可展開收合的清單**：FAQ（但多個可同時展開,非 Accordion 互斥）、程式碼 tree、JSON viewer
+- **可展開收合的階層清單**：程式碼檔案樹、JSON viewer、DOM inspector（遞迴巢狀結構;平面章節如 FAQ / 設定分組屬 Accordion,見「何時不用」）
 - **任意多層**：從 1 層到 N 層深度都由同一個 TreeView 承載
 
 ## 何時不用
@@ -49,8 +49,8 @@ TreeView 本身只負責三件事:
 | 場景 | 改用 | 原因 |
 |------|------|------|
 | 平面資料（無階層）| `DataTable` / 自訂 list | TreeView 為階層而設計，沒 children 的平面用 list |
-| 同時只能展開一個（互斥）| `Accordion type="single"` | TreeView 允許任意多個展開,互斥模式語意不同 |
-| 簡單 2 層 nav（主分類 + 子分類）| `Sidebar` + SidebarMenuSubButton | 輕量 2 層用 Sidebar 的內建結構,不需遞迴 |
+| 平面章節折疊（FAQ / 設定分組,無階層）| `Accordion`（`type="single"` 互斥 / `type="multiple"` 多開）| TreeView 是遞迴階層 node;平面章節不論單開或多開都屬 Accordion 範疇（accordion.spec.md「何時用」列 FAQ 為主要用途）|
+| 純視覺分段 / 設計時可列舉的 1 層固定選單 | `SidebarGroup` / `SidebarMenu` | Sidebar 主選單只接受 1 層可列舉項目;任何真階層（深度 > 1、runtime 可新增、user data）一律 TreeView（見 sidebar.spec.md「判斷規則」）|
 | 選單式展開（點完就關）| `DropdownMenu` + sub-menu | DropdownMenu 的 sub menu 是 temporary,TreeView 是 persistent |
 | 階層選擇但需要搜尋 / 快速找 | 自訂 tree + search filter（未來 TreeView 可加 search prop）| 基本 TreeView 不含 search |
 
@@ -182,7 +182,7 @@ Chevron 是**展開/收合控件**,不是 prefix icon:`fg-muted`(指示色,hover
 
 | 元素 | Role | 屬性 |
 |---|---|---|
-| TreeView 容器 | `role="tree"` | `aria-label`,`aria-multiselectable`(多選時) |
+| TreeView 容器 | `role="tree"` | **`aria-label` 或 `aria-labelledby`(擇一必填 — accessible name)**,`aria-multiselectable`(多選時) |
 | TreeItem 外層 | `role="treeitem"` | `aria-expanded`(expandable 才有),`aria-selected`,`aria-level` |
 | TreeItem children 容器 | `role="group"` | — |
 
@@ -393,6 +393,8 @@ TreeView 真實展示需要**多層巢狀結構**才有意義(單節點無法體
 
 **ARIA / Pattern**:自建 ARIA tree(非沿用 Radix 預設)。容器 `role="tree"`(多選時加 `aria-multiselectable`),每個 node `role="treeitem"` + `aria-expanded`(expandable 才有)/ `aria-selected` / `aria-level`,皆由元件手動設定(`tree-view.tsx` TreeItem render)。Radix `collapsible` 僅用於 children 展開 / 收合的高度動畫,**不提供** tree 的 role / aria / 鍵盤導覽(Radix 沒有 Tree primitive,見「定位」段)。對齊 [WAI-ARIA TreeView pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/)。`aria-setsize` / `aria-posinset` **刻意省略**:APG 規定只有當節點未全數 render 進 DOM(lazy load)或 DOM 序 ≠ 閱讀序時才必需;本元件全可見節點皆在 DOM(`querySelectorAll('[role="treeitem"]:not([hidden])')`)且 DOM 序 = 閱讀序,故非必需。
 
+**Accessible name(必填契約)**:`role="tree"` 的名稱無法從子節點內容推導,consumer **必須**提供 `aria-label`(直接字串)或 `aria-labelledby`(指向可見標題的 id)其中之一——有可見標題時優先 `aria-labelledby`,無則用 `aria-label`。兩者皆缺 → 螢幕閱讀器只讀出「tree」無法辨識用途(WAI-ARIA APG 要求 `role="tree"` 具 accessible name)。`tree-view.tsx` 於 `process.env.NODE_ENV !== 'production'` 時 `console.warn` 提示,避免上線後才發現無名稱樹(對齊 Button / Tag 的 dev-only 誤用警告 idiom)。
+
 **Keyboard 行為**(自建 handler,`tree-view.tsx` handleKeyDown):
 
 - Tab — 焦點進入整棵 tree(單一 tab stop)

package/src/components/TreeView/tree-view.stories.tsx

@@ -137,10 +137,10 @@ export const LongLabel: Story = {
       <div className="flex flex-col gap-2">
         <span className="text-caption font-medium text-fg-muted">預設 truncate</span>
         <div className="w-[220px] border border-divider rounded-lg bg-surface overflow-hidden py-2">
-          <TreeView aria-label="truncate test" defaultExpandedIds={['proj']}>
-            <TreeItem id="proj" icon={Folder} label="這是一個很長的專案名稱會被截斷">
-              <TreeItem id="f1" icon={FileText} label="這是一個很長的檔案名稱也會被截斷.tsx" />
-              <TreeItem id="f2" icon={FileText} label="短檔名.ts" />
+          <TreeView aria-label="產品設計檔案樹（截斷）" defaultExpandedIds={['proj']}>
+            <TreeItem id="proj" icon={Folder} label="2026 產品品牌識別設計提案">
+              <TreeItem id="f1" icon={FileText} label="首頁主視覺設計稿-桌面版-v3.fig" />
+              <TreeItem id="f2" icon={FileText} label="logo.svg" />
             </TreeItem>
           </TreeView>
         </div>
@@ -148,10 +148,10 @@ export const LongLabel: Story = {
       <div className="flex flex-col gap-2">
         <span className="text-caption font-medium text-fg-muted">label 換行（移除 truncate）</span>
         <div className="w-[220px] border border-divider rounded-lg bg-surface overflow-hidden py-2">
-          <TreeView aria-label="wrap test" defaultExpandedIds={['proj2']}>
-            <TreeItem id="proj2" icon={Folder} label={<span className="break-words whitespace-normal">這是一個很長的專案名稱會自然換行到下一行</span>}>
-              <TreeItem id="f3" icon={FileText} label={<span className="break-words whitespace-normal">這是一個很長的檔案名稱也會自然換行到下一行顯示完整內容.tsx</span>} />
-              <TreeItem id="f4" icon={FileText} label="短檔名.ts" />
+          <TreeView aria-label="產品設計檔案樹（換行）" defaultExpandedIds={['proj2']}>
+            <TreeItem id="proj2" icon={Folder} label={<span className="break-words whitespace-normal">2026 產品品牌識別設計提案完整版</span>}>
+              <TreeItem id="f3" icon={FileText} label={<span className="break-words whitespace-normal">首頁主視覺設計稿-桌面版與行動版對照-v3-最終定稿.fig</span>} />
+              <TreeItem id="f4" icon={FileText} label="logo.svg" />
             </TreeItem>
           </TreeView>
         </div>
@@ -263,38 +263,4 @@ export const DragAndDrop: Story = {
 }
 
 // @story-trait-rationale: AllSizes retired per F migration(2026-05-15)— anatomy.stories.tsx SizeMatrix auto-compile owns size showcase。
-// ── Indent 結構對齊驗證 ─────────────────────────────────────────────────
-
-export const IndentAlignment: Story = {
-  name: '縮排結構對齊驗證',
-  render: () => (
-    <div className="flex flex-col gap-4">
-      <div className="flex flex-col gap-1">
-        <h3 className="text-h6 font-semibold">indentStep = chevronSize + gap-2</h3>
-        <p className="text-caption text-fg-muted max-w-xl">
-          子 chevron 應對齊父 icon 的起始位置,子 icon 應對齊父 label 的起始位置。
-          這裡混合有 / 無 children 的 node 驗證 chevron placeholder 佔位(leaf 無條件留等寬空白);
-          icon 無自動佔位——無 icon 的 node(README.md / public)label 起點前移,屬「Icon 使用策略」
-          的混用反例,此處僅作 indent 結構驗證。
-        </p>
-      </div>
-      <div className="w-[300px] border border-divider rounded-lg bg-surface overflow-hidden py-2">
-        <TreeView aria-label="專案檔案樹" defaultExpandedIds={['src', 'components', 'public']}>
-          <TreeItem id="src" icon={Folder} label="src">
-            <TreeItem id="app" icon={FileCode} label="App.tsx" />
-            <TreeItem id="readme" label="README.md" />
-          </TreeItem>
-          <TreeItem id="public" label="public">
-            <TreeItem id="favicon" icon={Image} label="favicon.ico" />
-          </TreeItem>
-          <TreeItem id="components" icon={Folder} label="components">
-            <TreeItem id="button" icon={Folder} label="Button">
-              <TreeItem id="button-tsx" icon={FileCode} label="Button.tsx" />
-              <TreeItem id="button-test" label="Button.test.tsx" />
-            </TreeItem>
-          </TreeItem>
-        </TreeView>
-      </div>
-    </div>
-  ),
-}
+// @story-trait-rationale: IndentAlignment retired per Dim 24 dedup(2026-07-17)— indentStep=chevronSize+gap-2 幾何三重重複(showcase / anatomy IndentMatrix / principles IndentRule)。geometry 歸 anatomy.stories.tsx IndentMatrix、縮排原則 + icon 混用反例(唯一在此的內容)已遷入 principles.stories.tsx IndentRule;showcase 層不重複教 geometry(同 AllSizes / States 退役先例)。

package/src/components/TreeView/tree-view.tsx

@@ -293,6 +293,25 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
     },
     ref
   ) => {
+    // ── Accessible name dev-warn(2026-07-18:兌現 spec「Accessible name 必填契約」段承諾 —
+    //    原 spec 宣稱有此 console.warn 但 code 缺,spec-code drift;補上使兩者一致)──
+    //    role="tree" 名稱無法從子節點推導,缺 aria-label / aria-labelledby → SR 只讀「tree」。
+    //    對齊 Button / Tag 的 dev-only 誤用警告 idiom;production 不觸發。
+    const ariaLabel = props['aria-label']
+    const ariaLabelledby = props['aria-labelledby']
+    React.useEffect(() => {
+      if (
+        process.env.NODE_ENV !== 'production' &&
+        ariaLabel == null &&
+        ariaLabelledby == null
+      ) {
+        console.warn(
+          '[DS] TreeView:role="tree" 缺 accessible name — 請傳 aria-label(直接字串)或 aria-labelledby(指向可見標題 id)其一。' +
+            '兩者皆缺時螢幕閱讀器只讀出「tree」無法辨識用途(WAI-ARIA APG 要求 role="tree" 具 accessible name)。',
+        )
+      }
+    }, [ariaLabel, ariaLabelledby])
+
     // ── Expand state(受控 / 非受控) ──
     const [internalExpanded, setInternalExpanded] = React.useState(
       () => new Set(defaultExpandedIds)
@@ -776,6 +795,23 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
         isKeyboardRef.current = true
         if (!treeRef.current) return
 
+        // ── 互動 descendant 自理鍵盤(先於導覽 / 重排分支)──
+        // 公開 inlineActions / inlineActionsSlot 經 <ItemInlineAction> 渲染的原生 <button>
+        // (及 consumer slot 內的 link / field / role=button)是各自獨立的 tab stop(spec
+        // A11y「單一 tab stop」段)。其 Enter/Space/方向鍵應由該控件自理——若冒泡到容器
+        // handleKeyDown,下方 Enter/Space 分支的 e.preventDefault()+select() 會吃掉 button
+        // 原生啟動並誤選 tree node。虛擬焦點模型下 tree 導覽/重排只在事件來自容器本身時處理
+        // (DOM focus 停在 tree 容器;treeitem row / chevron / checkbox 皆 tabIndex=-1)。
+        const keyTarget = e.target as HTMLElement | null
+        if (keyTarget && keyTarget !== e.currentTarget) {
+          const interactive = keyTarget.closest<HTMLElement>(
+            'a[href], button, input, select, textarea, [contenteditable="true"], [tabindex]:not([tabindex="-1"])'
+          )
+          // interactive === e.currentTarget:唯一可聚焦祖先是 tree 容器(tabIndex=0 單一 tab
+          // stop 進出點)→ 屬非互動 descendant,照常走 tree 導覽。
+          if (interactive && interactive !== e.currentTarget) return
+        }
+
         // ── 鍵盤重排:Cmd/Ctrl+Shift+方向鍵(2026-07-14 v1,詳 spec「鍵盤重排」)──
         // 必排在下方「無焦點時方向鍵先聚焦第一項」分支之前(該分支不分 modifier 攔 Arrow*);
         // 非 modifier 導覽路徑(下方 switch)完全不變。

package/src/index.ts

@@ -76,7 +76,6 @@ export {
   Button,
   ButtonDivider,
   ButtonGroup,
-  ButtonGroupContext,
   buttonVariants,
 } from './components/Button/index'
 export type {
@@ -192,8 +191,8 @@ export {
   DescriptionList,
 } from './components/DescriptionList/index'
 export type {
-  DescriptionDirection,
   DescriptionItemProps,
+  DescriptionListOrientation,
   DescriptionListProps,
 } from './components/DescriptionList/index'
 export {
@@ -228,7 +227,6 @@ export {
   DropdownMenuSubContent,
   DropdownMenuSubTrigger,
   DropdownMenuTrigger,
-  floatingLayerClass,
 } from './components/DropdownMenu/index'
 export type {
   DropdownMenuItemProps,
@@ -246,7 +244,6 @@ export {
   FieldError,
   FieldGroup,
   FieldLabel,
-  getMenuListMinHeight,
   useFormValidation,
 } from './components/Field/index'
 export type {
@@ -417,7 +414,6 @@ export {
   SheetPortal,
   SheetTitle,
   SheetTrigger,
-  handleSheetOpenAutoFocus,
   sheetVariants,
 } from './components/Sheet/index'
 export {
@@ -548,13 +544,10 @@ export {
   ItemAvatar,
   ItemContent,
   ItemIcon,
-  ItemInlineAction,
-  ItemInlineActionButton,
   ItemLabel,
   ItemPrefix,
   ItemSuffix,
   ROW_PADDING_BY_SIZE,
-  RowSizeProvider,
   getUniformPrefixSlotStyle,
   itemPrefixAlignVariants,
   useRowSize,
@@ -564,8 +557,6 @@ export type {
   ItemAvatarProps,
   ItemContentProps,
   ItemIconProps,
-  ItemInlineActionButtonProps,
-  ItemInlineActionProps,
   ItemSuffixHoverGroup,
   ItemSuffixProps,
   RowSize,
@@ -598,6 +589,18 @@ export type {
 //   - components/SelectionControl
 //   - patterns/horizontal-overflow
 //   - patterns/overlay-surface
+// 另有 public 元件內個別標 @internal jsDoc 的符號亦排除 front-door(2026-07-18 決策3;subpath 仍有):
+//   - components/Button:ButtonGroupContext
+//   - components/DropdownMenu:floatingLayerClass
+//   - components/Field:FieldVariantInternal
+//   - components/Field:WithFieldVariantInternal
+//   - components/Field:getMenuListMinHeight
+//   - components/Sheet:handleSheetOpenAutoFocus
+//   - patterns/element-anatomy:ItemInlineAction
+//   - patterns/element-anatomy:ItemInlineActionButton
+//   - patterns/element-anatomy:ItemInlineActionButtonProps
+//   - patterns/element-anatomy:ItemInlineActionProps
+//   - patterns/element-anatomy:RowSizeProvider
 
 // ─── Tokens(JS mirrors — token SSOT 程式面)──────────────────────────────
 export * from './tokens/categorical-color'

package/src/lib/drag-visual.ts

@@ -6,7 +6,7 @@
  *
  * ## Pattern
  *
- * - **Source element**(被拖中的 row/column):`opacity-30`(半透,user 仍看得到原位)
+ * - **Source element**(被拖中的 row/column):`opacity-disabled`(= var(--opacity-disabled) 0.45 半透,user 仍看得到原位;2026-05-06 v14.5.2 由 opacity-30 改)
  *   — 不是 `opacity:0` 全隱形,因 user 拖太遠看不到「源頭」會迷失方向。對齊 TreeView 最早 v1 + Notion / Atlassian / Linear。
  * - **Ghost preview**(浮動 follow cursor):透過 dnd-kit `<DragOverlay>` portal,clone source 的 outerHTML
  *   strip transform/transition/opacity → render 在 portal 層,visually 跟 cursor 走。
@@ -26,7 +26,7 @@
  * - `bg-primary`:semantic state token(`--primary`)— 跟 focus state ring color 同 source(M23 一致)
  * - `bg-primary-subtle`:semantic primary subtle(`--primary-subtle`)— inside-drop dim background
  * - `h-0.5` / `w-0.5`:Tailwind size token = 2px(對齊 hairline divider thickness 概念)
- * - `opacity-30`:Tailwind 30% opacity(半透但仍清楚看到 outline)
+ * - `opacity-disabled`:DS token var(--opacity-disabled)= 0.45(半透但仍清楚看到 outline;見下方 v14.5.2 note)
  */
 
 import type * as React from 'react'

package/src/lib/utils.ts

@@ -92,3 +92,22 @@ const twMerge = extendTailwindMerge({
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs))
 }
+
+// ── line-clamp 安全對照(2026-07-18 決策4)────────────────────────────────────
+// 動態 `line-clamp-${n}` / `line-clamp-[${n}]` = Tailwind 掃不到具體值 → silent 失效(失敗記憶索引:
+//   「Tailwind v4 動態 class」陷阱)。此 map 全靜態字串 → Tailwind 可掃。canonical 上限 1-6(spec maxLines/
+//   descriptionClamp ≤6);超界值 dev-warn + clamp 回 6(不 crash、不靜默失效)。null/0/undefined → 不 clamp。
+const LINE_CLAMP: Record<number, string> = {
+  1: 'line-clamp-1', 2: 'line-clamp-2', 3: 'line-clamp-3',
+  4: 'line-clamp-4', 5: 'line-clamp-5', 6: 'line-clamp-6',
+}
+export function lineClampClass(n: number | undefined | null): string | undefined {
+  if (n == null || n <= 0) return undefined
+  const rounded = Math.round(n)
+  if (rounded !== n || n > 6) {
+    if (typeof process !== 'undefined' && process.env?.NODE_ENV !== 'production') {
+      console.warn(`[DS] line-clamp 值 ${n} 超出 canonical 範圍 1-6(或非整數)→ clamp 回 6。請傳 1-6 整數。`)
+    }
+  }
+  return LINE_CLAMP[Math.min(6, Math.max(1, rounded))]
+}

package/src/patterns/action-bar/action-bar.spec.md

@@ -472,3 +472,4 @@ Icon 的目的是幫助辨識，不是視覺對稱。
 - `data-table.spec.md`
 - `file-viewer.spec.md`
 - `popover.spec.md`
+- `separator.spec.md`

package/src/patterns/element-anatomy/inline-action.spec.md

@@ -168,7 +168,7 @@ Q3. Row 多大?
 #### Content-role vs action-role 分層(附補充原理)
 
 Row 內元件分兩類,**size 規則不同**:
-- **Content-role**(display 資料):`<Input mode="display">` / Badge / Avatar / Tag → size 對應 row tier(sm row → sm)
+- **Content-role**(display 資料):`<Input mode="view">` / Badge / Avatar / Tag → size 對應 row tier(sm row → sm)
 - **Action-role**(互動觸發):row action icon → **固定 ≤ 24**,不參與 content size-pair
 
 Row action 的 affordance 是「次要功能」,不是 primary CTA。Button chrome 過度強調;用 **Button xs 24 固定** 提供 command affordance 但不侵蝕 content hierarchy。

package/src/patterns/element-anatomy/item-anatomy.spec.md

@@ -1028,15 +1028,18 @@ Selection control(Dropdown / Menu / List / SegmentedControl / Chip)的 item 視
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `alert.spec.md`
+- `checkbox.spec.md`
 - `color.spec.md`
 - `command.spec.md`
 - `dropdown-menu.spec.md`
 - `element-anatomy.spec.md`
 - `empty.spec.md`
+- `field-controls.spec.md`
 - `field.spec.md`
 - `file-item.spec.md`
 - `header-canonical.spec.md`
 - `inline-action.spec.md`
+- `layoutSpace.spec.md`
 - `menu-item.spec.md`
 - `notice.spec.md`
 - `select-menu.spec.md`
@@ -1047,5 +1050,6 @@ Selection control(Dropdown / Menu / List / SegmentedControl / Chip)的 item 視
 - `tabs.spec.md`
 - `time-picker.spec.md`
 - `toast.spec.md`
+- `token-system.spec.md`
 - `tree-view.spec.md`
 - `typography.spec.md`

package/src/patterns/element-anatomy/item-anatomy.tsx

@@ -3,7 +3,7 @@
 import * as React from "react"
 import type { LucideIcon } from "lucide-react"
 import { cva } from "class-variance-authority"
-import { cn } from "@/lib/utils"
+import { cn, lineClampClass } from "@/lib/utils"
 import { Avatar, type AvatarProps } from "@/design-system/components/Avatar/avatar"
 import {
   Tooltip,
@@ -392,7 +392,7 @@ export const ItemContent = React.forwardRef<HTMLDivElement, ItemContentProps>(
           ? "text-[length:var(--font-body-size)]"
           : ""
 
-    const clampClass = descriptionClamp ? `line-clamp-${descriptionClamp}` : ""
+    const clampClass = lineClampClass(descriptionClamp) ?? ""
 
     return (
       <div
@@ -558,6 +558,7 @@ ItemAvatar.displayName = "ItemAvatar"
 //
 // 接受任何 button props 並 spread(讓 Radix Slot 可以 merge onClick / data-state 等)
 
+/** @internal — internal ItemInlineActionButton 的 props;隨其元件同走 subpath,不進 root barrel front-door。 */
 export interface ItemInlineActionButtonProps
   extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "children"> {
   /** Lucide icon 元件 */
@@ -662,6 +663,7 @@ ItemInlineActionButton.displayName = "ItemInlineActionButton"
 // 需要接 Radix asChild(例如 collapsible trigger)時改用 `ItemInlineActionButton`,
 // 那層沒有 Tooltip 包裝,Root 就是 button,可直接塞進 Radix Slot。
 
+/** @internal — internal ItemInlineAction 的 props;隨其元件同走 subpath,不進 root barrel front-door。 */
 export interface ItemInlineActionProps {
   action: InlineActionConfig
   /** Size 覆寫(見 `ItemInlineActionButtonProps.size`)——Field Controls / Tag 必傳 */

package/src/patterns/header-canonical/header-canonical.spec.md

@@ -270,6 +270,15 @@ ChromeHeader / SurfaceHeader 新增 `tabsSlot?: ReactNode` prop。提供時自
 
 **不開**:`density?: 'md'|'lg'` 自由 prop(M21 違反 — 任意 density 等於 cva-on-pattern,該由 density context 決定)。`lockDensity="lg"` 原為 fullscreen viewer escape hatch,但 **2026-06-15 起無 consumer 使用** — FileViewer 改為全 surface 繼承 page density(原本只鎖兩個 header、沒鎖 body → 左緣不對齊,圖二 bug)。density lock 一律設在 **surface 根**而非 header primitive(見 `density.spec.md` anti-pattern)。其餘 consumer 走 `inherit`(跟 page density)。**Grep evidence**(historical 錨,migration 已完成):migration 前 `Sidebar` + `FileViewer Toolbar/InfoPanel` 各自手刻同一 signature `flex items-center gap-2 shrink-0 h-[var(--chrome-header-height)] border-b border-divider px-[var(--layout-space-loose)]`(production 重複 contract,非 premature abstraction)→ 過 M21 prop variant test 3 條(`<Sidebar>` 等近親 grep / 3 家世界級 page-header primitive / value 結構不同)→ 抽成本 primitive。**現況**:全部已消費 `<ChromeHeader>`(`sidebar.tsx:479` / `file-viewer.tsx:340` Toolbar + `:474` InfoPanel),grep 全 repo 已無此手刻 signature(除 `chrome-header.tsx` primitive 本身)。
 
+### 空 children / action state 契約(rendering contract)
+
+**空 children**:`ChromeHeaderProps extends React.HTMLAttributes<HTMLElement>`,故 `children` 型別上 optional;但**實作恆渲染固定高度 row**(single-row `h-[var(--chrome-header-height)]` + `border-b`,`chrome-header.tsx:167-183`;`tabsSlot` 模式 row 1 亦恆渲染,`:113-122`)。因此:
+
+- **沒有 title / actions 時不要渲染 ChromeHeader**——空 children 只會留一條固定高度 + border 的空白 chrome row(`tabsSlot` 模式更明顯:tabs 上方多整行空白標題列)。consumer 條件渲染,有內容才掛 header,而非傳空殼。
+- **只有 tabs、無獨立標題列**的場景 → 用 standalone `<Tabs size="lg">`(tab 高 = chrome-header-height,見「選哪個 header」表 C 列),**不要**空 children + `tabsSlot` 硬撐。
+
+**Action loading / disabled 歸屬**:ChromeHeader 只負責 slot 排版,**不擁有**注入 action 的非同步狀態。header 內 Button / 控件的 `loading` / `disabled` 由 consumer 注入的元件自帶(如 `<Button loading>` 自畫 spinner),ChromeHeader 層**無** loading / disabled prop。故本 primitive 的 **Loading 驗證 = N/A**(排版 primitive,無自身 async state)。
+
 ### Layer 4 — Hook mechanical
 
 `chrome_header_dispatcher.sh` 依序 dispatch **4 個 lib helper**(完整清單 SSOT = dispatcher 本身,避免 spec drift):

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

@@ -68,9 +68,13 @@ export const SingleRow = () => (
       <Separator orientation="vertical" className="h-6 mx-1" />
       <Button iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />
     </ChromeHeader>
-    <div className="p-6 text-body text-fg-secondary">文件預覽內容區…</div>
+    <div className="flex flex-col gap-2 p-6 text-body text-fg-secondary">
+      <p className="text-caption text-fg-muted">陳雅婷 更新於 2026/04/18 · 12 頁 · 2.4 MB</p>
+      <p>本季合併營收 NT$4.82 億,較上季成長 8.2%;毛利率維持 41%。附錄含各區域損益與現金流量表。</p>
+    </div>
   </Panel>
 )
+SingleRow.storyName = '單列(標題 + 動作列)'
 
 /** 2. withTabs — header 含分頁列(對標 FileViewer InfoPanel / 設定頁 header)。
  *  傳 tabsSlot 自動進 column 結構:row1 = 標題列、row2 = TabsList 全寬畫線。 */
@@ -92,17 +96,29 @@ export const WithTabs = () => (
         <Button iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />
       </ChromeHeader>
       <TabsContent value="overview">
-        <div className="p-6 text-body text-fg-secondary">「概覽」分頁內容…</div>
+        <div className="flex flex-col gap-1 p-6 text-body text-fg-secondary">
+          <p>負責人:林思妤 · 期程:2026/03–2026/06 · 狀態:設計中</p>
+          <p>將既有品牌識別全面翻新——logo、配色與元件庫,預計 Q2 上線。</p>
+        </div>
       </TabsContent>
       <TabsContent value="activity">
-        <div className="p-6 text-body text-fg-secondary">「活動」分頁內容…</div>
+        <div className="flex flex-col gap-1 p-6 text-body text-fg-secondary">
+          <p>陳柏宇 上傳了「新版 logo 提案 v3」· 2 小時前</p>
+          <p>林思妤 將狀態改為「設計中」· 昨天</p>
+          <p>Aisha Khan 留言:配色再往暖色調微調 · 3 天前</p>
+        </div>
       </TabsContent>
       <TabsContent value="files">
-        <div className="p-6 text-body text-fg-secondary">「檔案」分頁內容…</div>
+        <div className="flex flex-col gap-1 p-6 text-body text-fg-secondary">
+          <p>品牌識別規範_v3.pdf · 8.1 MB</p>
+          <p>logo 原始檔.ai · 24 MB</p>
+          <p>配色對照表.xlsx · 320 KB</p>
+        </div>
       </TabsContent>
     </Tabs>
   </Panel>
 )
+WithTabs.storyName = '含分頁列'
 
 /** Overview — header anatomy 兩型疊起來一次看完,每型上方標清「何時用 + 對標既有元件」。
  *  注:ChromeHeader 另有 `leadingRail` slot,但它專為「跟 sidebar 收合 icon 對齊」而生(寬 = sidebar 收合寬),
@@ -136,7 +152,16 @@ export const Overview = () => (
           <h2 className="flex-1 truncate text-body-lg font-medium text-foreground">編輯專案設定</h2>
           <Button iconOnly dismiss size="sm" startIcon={X} aria-label="關閉" />
         </SurfaceHeader>
-        <div className="p-6 text-body text-fg-secondary">浮層內容區…(Dialog / Sheet / Popover body)</div>
+        <div className="flex flex-col gap-3 p-6 text-body text-fg-secondary">
+          <div className="flex flex-col gap-0.5">
+            <span className="text-caption text-fg-muted">專案名稱</span>
+            <span className="text-foreground">Acme 品牌改版專案</span>
+          </div>
+          <div className="flex flex-col gap-0.5">
+            <span className="text-caption text-fg-muted">可見範圍</span>
+            <span className="text-foreground">團隊成員(12 人)</span>
+          </div>
+        </div>
       </div>
     </section>
     <section className="flex flex-col gap-2">
@@ -148,3 +173,4 @@ export const Overview = () => (
     </section>
   </div>
 )
+Overview.storyName = '總覽'

package/src/tokens/categorical-color.ts

@@ -24,7 +24,7 @@
  * **機械防線**:`scripts/categorical-color-invariants.mjs` I1(release:preflight 已 chain)強制 map 的 key X 的值含 `--color-X-`(名實一致,禁 offset;原引 hook 名不存在,2026-07-04 修)。
  */
 
-/** 12 個 categorical 色相(順序對齊 primitives.css / Storybook color token 列)。 */
+/** 12 個 categorical 色相。⚠️ 順序 = **categorical 指派序**(圖表系列鄰色最大區辨:blue→green→deep-orange→yellow→red…),**非** primitives.css 檔內宣告序 — 兩者本就不同,map 以名為 key 故功能無涉;**禁**為「對齊」重排(重排 = 圖表系列換色 = 視覺 breaking)。 */
 export const CATEGORICAL_HUES = [
   'blue',
   'green',
@@ -64,8 +64,8 @@ export const CAT_SUBTLE: Record<CategoricalHue, string> = {
 /**
  * solid 模式 class:step-6 底 + on-emphasis 配對文字。
  * 文字色依「step-6 底亮度」分桶(WCAG ≥3:1 大粗字門檻,2026-06-04 user「以最低為原則」):
- *   - 夠深的色底 → `text-on-emphasis`(白):blue / deep-orange / red / turquoise / indigo / purple / magenta
- *   - 太亮的色底 → `text-on-emphasis-dark`(深):yellow / amber / orange / lime(白字連 3:1 都不過)
+ *   - 夠深的色底 → `text-on-emphasis`(白):blue / deep-orange / red / indigo / purple / magenta
+ *   - 太亮的色底 → `text-on-emphasis-dark`(深):yellow / amber / orange / lime / turquoise(白字連 3:1 都不過;turquoise 2026-07-16 dark 色相修正後 L=0.68 白字 2.77 → 切深字,兩 mode 5.65/6.47 全過)
  *   - ★ green 例外:白字 2.47 連 3:1 都不過,但 user 拍板維持白字(綠底白字慣見觀感)= documented exception。
  * 對比為 oklch→相對亮度實測(scripts/categorical-color-invariants.mjs 機械驗,green 列 exempt)。
  */
@@ -78,7 +78,7 @@ export const CAT_SOLID: Record<CategoricalHue, string> = {
   orange: 'bg-[var(--color-orange-6)] text-on-emphasis-dark',
   amber: 'bg-[var(--color-amber-6)] text-on-emphasis-dark',
   lime: 'bg-[var(--color-lime-6)] text-on-emphasis-dark',
-  turquoise: 'bg-[var(--color-turquoise-6)] text-on-emphasis',
+  turquoise: 'bg-[var(--color-turquoise-6)] text-on-emphasis-dark',
   indigo: 'bg-[var(--color-indigo-6)] text-on-emphasis',
   purple: 'bg-[var(--color-purple-6)] text-on-emphasis',
   magenta: 'bg-[var(--color-magenta-6)] text-on-emphasis',
@@ -125,7 +125,7 @@ export const CAT_SOLID_TOKENS: Record<CategoricalHue, { bg: string; text: string
   orange: { bg: 'var(--color-orange-6)', text: 'var(--on-emphasis-dark)' },
   amber: { bg: 'var(--color-amber-6)', text: 'var(--on-emphasis-dark)' },
   lime: { bg: 'var(--color-lime-6)', text: 'var(--on-emphasis-dark)' },
-  turquoise: { bg: 'var(--color-turquoise-6)', text: 'var(--on-emphasis)' },
+  turquoise: { bg: 'var(--color-turquoise-6)', text: 'var(--on-emphasis-dark)' },
   indigo: { bg: 'var(--color-indigo-6)', text: 'var(--on-emphasis)' },
   purple: { bg: 'var(--color-purple-6)', text: 'var(--on-emphasis)' },
   magenta: { bg: 'var(--color-magenta-6)', text: 'var(--on-emphasis)' },

package/src/tokens/color/color.spec.md

@@ -272,8 +272,8 @@ Tag、Avatar 等需要多色區分的場景（專案標籤、團隊分類等）
 
 填色底上的文字色**依底色明暗成對**提供(世界級共識:Material `on-primary` family、Radix `--accent-contrast`、Polaris `text-{x}-on-bg-fill` —— 都是「成對 on-color token」,不是單一固定白):
 
-- `--on-emphasis = oklch(1 0 0)`(純白,dark mode 不反轉)—— 用於**夠深的飽和色底**(白字達 WCAG 門檻):primitive 6 階深色 / `--primary` / `--error` 等,及 categorical blue/deep-orange/red/turquoise/indigo/purple/magenta。
-- `--on-emphasis-dark = var(--black-a85)`(深字,dark mode 不反轉)—— 用於**太亮的色底**(白字對比不足):categorical **yellow / amber / orange / lime**。
+- `--on-emphasis = oklch(1 0 0)`(純白,dark mode 不反轉)—— 用於**夠深的飽和色底**(白字達 WCAG 門檻):primitive 6 階深色 / `--primary` / `--error` 等,及 categorical blue/deep-orange/red/indigo/purple/magenta(turquoise 2026-07-16 移入深字組)。
+- `--on-emphasis-dark = var(--black-a85)`(深字,dark mode 不反轉)—— 用於**太亮的色底**(白字對比不足):categorical **yellow / amber / orange / lime / turquoise**(turquoise 2026-07-16 dark 色相修正後加入)。
 
 **合規門檻(2026-06-04 user 拍板「以最低為原則」)= WCAG large/bold 3:1**(solid chip / avatar 的字視為大粗字)。底色 step-6 白字達 3:1 → 用 `--on-emphasis`;不達 → 用 `--on-emphasis-dark`。
 
@@ -367,7 +367,7 @@ Badge 使用語義色的 text token（`--info-text`、`--error-text`），不直
 
 **step-7 vs semantic active 的區別**：兩者在 light mode 都指向 step-7，但 dark mode 行為不同。semantic active（如 `--primary-active`）在 dark mode 反轉為 step-5（壓暗模擬按壓感），而 primitive step-7 在 dark mode 仍維持高對比方向。簡言之：active 服務於互動回饋，step-7 服務於閱讀對比，兩者目的不同，dark mode 方向相反。
 
-**例外：step-6 滿版底色上的「亮色 hue」文字用 `--on-emphasis-dark`（`black-a85`,深色)**——yellow / amber / orange / lime 亮度極高,白字（`--on-emphasis`）連 WCAG 3:1 都不過,必須深色文字（見上「`--on-emphasis` 配對」段)。此例外只在底色是 step-6 時觸發,step-1 subtle 底色上仍用 step-7。（green-6 白字亦不過 3:1,但列 documented exception 維持白字。)
+**例外：step-6 滿版底色上的「亮色 hue」文字用 `--on-emphasis-dark`（`black-a85`,深色)**——yellow / amber / orange / lime / turquoise 亮度極高,白字（`--on-emphasis`）連 WCAG 3:1 都不過,必須深色文字（見上「`--on-emphasis` 配對」段)。此例外只在底色是 step-6 時觸發,step-1 subtle 底色上仍用 step-7。（green-6 白字亦不過 3:1,但列 documented exception 維持白字。)
 
 ### Subtle 背景（淡色填充）
 
@@ -501,7 +501,7 @@ Dark mode 覆寫：hover/active 方向反轉（hover → step-7，active → ste
 在 `primitives.css` 定義 base-6 值（只需指定 L、C、H），相對公式自動推導 1-10 階。如已存在則跳過。
 
 ```css
---color-turquoise-6: oklch(0.57 0.10 225);
+--color-turquoise-6: oklch(0.64 0.09 196);  /* light 真值(primitives.css:183);dark 另於 dark 區塊定義 */
 /* 1-5 / 7-10 自動由公式推導 */
 ```
 

package/src/tokens/color/primitives.css

@@ -285,7 +285,10 @@
   --color-neutral-9-opaque: color-mix(in srgb, white var(--_na9), black);
 
   /* Blue */
-  --color-blue-6:  oklch(0.60 0.22 258);
+  /* 2026-07-16 user 拍板:dark 主色對比升級 — 0.60→0.63(≈#2C84FF,對齊 Apple dark systemBlue)。
+     card/table/浮層 surface 上互動文字 4.07-4.10:1(AA ✗)→ 4.63-4.67:1(AA ✓);canvas 5.53:1。
+     其餘 1-10 階不手動指定,由本基準經下方既有相對公式自動推導(單一基準,設計語言不變)。 */
+  --color-blue-6:  oklch(0.63 0.22 258);
   --color-blue-1:  oklch(from var(--color-blue-6) l c h / calc(0.12 / l));
   --color-blue-2:  oklch(from var(--color-blue-6) calc(l * 0.28) calc(c * 0.65) h);
   --color-blue-3:  oklch(from var(--color-blue-6) calc(l * 0.44) calc(c * 0.82) h);
@@ -369,7 +372,11 @@
   --color-green-10: oklch(from var(--color-green-6) calc(l + (1 - l) * 0.75) calc(c * 0.14) h);
 
   /* Turquoise */
-  --color-turquoise-6:  oklch(0.57 0.10 225);
+  /* 2026-07-16 user 拍板修正:原 oklch(0.57 0.10 225)為複製 spec 假想範例的錯值 — 全 12 色相唯一
+     dark 改色相(196→225 = 偏藍)、唯一 L 降(其餘全升)、唯一 C 升,三重違反設計語言。
+     修回 H=196(同 light,Apple systemBlue/Teal dark 同樣色相恆定);L 照 11 色相經驗律內插
+     (L≤0.58 → +0.05 / L≥0.70 → +0.03;0.64 居中 → +0.04)= 0.68;C 照 ×0.95 2dp 慣例 = 0.09。 */
+  --color-turquoise-6:  oklch(0.68 0.09 196);
   --color-turquoise-1:  oklch(from var(--color-turquoise-6) l c h / calc(0.12 / l));
   --color-turquoise-2:  oklch(from var(--color-turquoise-6) calc(l * 0.28) calc(c * 0.65) h);
   --color-turquoise-3:  oklch(from var(--color-turquoise-6) calc(l * 0.44) calc(c * 0.82) h);

package/src/tokens/motion/motion.spec.md

@@ -97,13 +97,6 @@ Hover delay token 是「hover 觸發 → 延遲 N ms → overlay 顯示」的延
 - `../../components/Tooltip/tooltip.spec.md`(consumer)
 - `../../components/HoverCard/hover-card.spec.md`(consumer)
 - `../../components/Avatar/avatar.spec.md`(consumer)
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `hover-card.spec.md`
-
 ## 進出場動畫 token(2026-07-11 加,user 拍板)
 
 Overlay(Tooltip/Popover/HoverCard/DropdownMenu/Dialog/Sheet/FileViewer)的 fade/zoom/slide 進出場動畫,值統一 token 化(原各元件硬寫 zoom-95/slide-2/duration-300 = M17 假 SSOT)。由 tw-animate-css(Tailwind v4,= shadcn 官方機制)的 `--tw-duration`/`--tw-ease` 變數綁定;共用 SSOT = `overlay-motion.ts`(overlayMotion/surfaceMotion)。
@@ -120,3 +113,9 @@ Overlay(Tooltip/Popover/HoverCard/DropdownMenu/Dialog/Sheet/FileViewer)的 fade/
 **幾何原型分層(正當差異,不強行抹平)**:輕量 popup = fade+zoom+slide-side(8px);模態置中 = fade+zoom+slide-center(Dialog/FileViewer);邊緣抽屜 = slide-edge 100%、正當無 zoom(Sheet)。統一的是**時長/曲線/reduced-motion 守衛**(motion-reduce:animate-none 全 7 浮層),非幾何原型(對齊 Material standard-vs-emphasized / Carbon productive-vs-expressive tier 分層)。
 
 **a11y**:prefers-reduced-motion 下 `motion-reduce:animate-none` 全 7 浮層統一關進出場動畫(overlay-motion SSOT 保證,無漏)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `hover-card.spec.md`

package/src/tokens/opacity/opacity.spec.md

@@ -64,7 +64,7 @@ Tailwind 提供 `opacity-{5/10/20/30/40/50/60/70/80/90/95}` 百分比 ladder,但
 
 ## 消費者
 
-直接套用 `opacity-disabled` 的元件（grep 驗證 2026-07-05;Textarea 已全面 token-swap 化移除）：Avatar（Field disabled context self-dim）、Button（`aria-disabled` 分支）、MenuItem、Rating（disabled / loading 整塊）、Steps、Switch、DataTable（drag source 半透 + 整表 refresh loading reuse，經 `lib/drag-visual.ts`）。
+直接套用 `opacity-disabled` 的元件（grep 驗證 2026-07-16;Textarea 已全面 token-swap 化移除）：Avatar（Field disabled context self-dim）、Button（`aria-disabled` 分支）、MenuItem、Rating（disabled / loading 整塊）、Steps、Switch、DataTable（drag source 半透 + 整表 refresh loading reuse，經 `lib/drag-visual.ts`）、PersonDisplay（disabled 整塊,`person-display.tsx:137`）。
 
 非消費者（曾誤列）：Slider / Sidebar 走灰階 token swap；Chip 無 opacity 用例；Field wrapper blanket 已移除（Avatar self-dim 取代，見 field-wrapper.tsx 註解）。
 

package/src/tokens/orphan-tokens.spec.md

@@ -44,7 +44,7 @@ benchmark:
 
 **Why**:Material 3「Key Colors & Tones」+ Atlassian「Full color spectrum」共識 — palette 是設計師調色盤 SSOT,缺中間階就斷層,新元件需消費中間色時不該 hot-add。**全色階是 capability,不是 cost**。
 
-**Regex**:`^--color-(amber|blue|brown|red|green|deep-orange|grey|indigo|lime|orange|pink|purple|teal|yellow|cyan)-\d+$`
+**Regex**:`^--color-(amber|blue|red|green|deep-orange|indigo|lime|orange|purple|yellow)-\d+$`
 
 ### 2. Magenta / Turquoise 專用 palette(14 token,structural)
 

package/src/tokens/typography/typography.spec.md

@@ -40,6 +40,8 @@ Typography 由三個獨立維度組成，分開疊加：
 | `text-caption` | 12px      | 1.3         | 圖表附註、標籤文字、元件內次要說明 |
 | `text-footnote`| 10px      | 1.3         | 法律文字、來源標注（極少用）|
 
+> **10px a11y 用途限制**（2026-07-17）：`text-footnote` 僅限**非必要的附帶資訊**（法律細字、來源標注、storybook 註解）——目前全庫零正式元件消費，只用於 stories `<p>` 註解。**使用者需理解才能操作的資訊禁止只靠 10px**；任何 ≤12px 用途上線前須驗 200% 放大（WCAG 1.4.4）不裁切。視覺標題 ≠ 語義標題（一律用 `h1–h6`，WCAG 1.3.1）。
+
 **h5（16px）vs body-lg（16px）/ h6（14px）vs body（14px）**：同尺寸配對的統一判別法——line-height 區分角色（標題 1.3 / 段落 1.5），使用端再疊 font-weight / color 強化標題層級，需有意識地選擇（詳「同尺寸但不同角色的選法」）。