@qijenchen/design-system 0.1.0-beta.61 → 0.1.0-beta.63

package/src/components/Menu/menu-item.spec.md

@@ -44,12 +44,12 @@ prefix icon 跟 label 同色（foreground），不是 fg-muted。詳見 item-ana
 
 所有 prefix 元素（checkbox、icon、avatar）共享同一個對齊容器。容器高度決定對齊行為：
 
-| prefix 最大高度 | 容器 | 對齊目標 |
+| prefix 最大高度 | 容器高度(原則) | 對齊目標 |
 |---|---|---|
-| ≤ 24px | `h-[1lh]` | 第一行 label 的垂直中心 |
-| > 24px | `h-[calc(1lh+var(--item-gap-label-desc)+desc_1lh)]` | label + gap + description 文字塊的垂直中心 |
+| ≤ 24px | 一行 label 高(inline) | 第一行 label 的垂直中心 |
+| > 24px | label + gap + 一行 description 的文字塊高(block) | 文字塊的垂直中心 |
 
-**SSOT**:對齊公式封裝於 `patterns/element-anatomy/item-anatomy.tsx` 的 `itemPrefixAlignVariants`(2026-04-23 重構)。MenuItem 消費此 primitive,不自建對齊邏輯;改 gap token(`--item-gap-label-desc`)或 font-size token 一處 → MenuItem 自動同步。
+**SSOT**:對齊公式(CSS calc 細節)封裝於 `patterns/element-anatomy/item-anatomy.tsx` 的 `itemPrefixAlignVariants`(2026-04-23 重構),spec 不重述公式。MenuItem 消費此 primitive,不自建對齊邏輯;改 gap token(`--item-gap-label-desc-scanning[-lg]`;bare token 已不存在,4 變體見 `layoutSpace.css`)或 font-size token 一處 → MenuItem 自動同步。
 
 **24px 是物理限制**——16px icon 在 24px 圓內仍可辨識(內部 icon 下限 12px),但在更小的容器中 icon 會低於可讀閾值。
 
@@ -183,7 +183,7 @@ Menu item 的 prefix icon 跟 label 同色（foreground），不是 fg-muted。P
 
 ## Group
 
-群組由 `MenuGroup` 包裹，`py-2`（8px）上下內距。群組緊鄰群組，無額外間距。
+群組由 `MenuGroup` 包裹,`py-2`(8px)上下內距。群組緊鄰群組無額外 margin——相鄰群組由 `[&+&]:border-t border-divider` 自動分隔(上下 py-2 合計 16px 視覺間距;Pattern A,SSOT 見 `item-anatomy.spec.md`「Group auto-separation」)。
 
 ### Group Header
 
@@ -231,6 +231,20 @@ Menu item 的 prefix icon 跟 label 同色（foreground），不是 fg-muted。P
 - `../DropdownMenu/dropdown-menu.tsx` — 操作選單
 - 未來：ContextMenu、CommandPalette
 
+### 近親分界
+
+| | MenuItem(Family 1) | SelectionItem | List item(Family 2) |
+|---|---|---|---|
+| 場景 | 浮層選單 row,掃視挑一個 | form 內 Checkbox / Radio 的 label 佈局 | 內容列表 row,閱讀 |
+| Clamp 預設 | label / desc 各 1 行 | `'none'` 完整閱讀(SSOT 對照表見 `../Checkbox/checkbox.spec.md`「為什麼不像 MenuItem 強制截斷?」) | 依元件(如 FileItem) |
+| SSOT | `item-anatomy.spec.md`「Menu item layout」 | `../SelectionControl/selection-item.spec.md` | `item-anatomy.spec.md`「List item layout」 |
+
+### 常見誤解
+
+- 直接 `<MenuItem>` 進 JSX → ❌(失去外層 Radix / cmdk a11y,見上表)
+- 單選選中要加 ✓ 勾號 → ❌,DS 用 `bg-neutral-selected` 高亮(勾號影響 prefix 對齊,見「選中指示器」)
+- suffix 可塞大塊內容 → ❌,實作寫死 inline 對齊只支援 ≤24px(見「Suffix 對齊(實作限制)」)
+
 ---
 
 ## 為何無獨立 StateBehavior story
@@ -239,7 +253,7 @@ MenuItem 的狀態色(default / hover / selected / disabled)是**結構性的**
 
 獨立 StateBehavior story 會複製 ColorMatrix 內容——MenuItem 的 state 本身就是色彩表達,無額外「時序 / 動畫」可獨立呈現(不像 Accordion 有 expand/collapse 行為)。Inspector 已互動式展示 selected / disabled 單一 variant 的切換。
 
-對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(含完整狀態色矩陣) + `SizeMatrix`。
+對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(含完整狀態色矩陣)+ `SizeMatrix` + `Accessibility`。
 
 ---
 
@@ -248,6 +262,7 @@ MenuItem 的狀態色(default / hover / selected / disabled)是**結構性的**
 - **Disabled**:`disabled` prop 由 MenuItem primitive own;視覺 `text-fg-disabled`(neutral-6,M24 state>emphasis)、無 hover bg、`aria-disabled="true"`、Enter / click 不觸發 onSelect、鍵盤導覽自動 skip(由 consumer SelectMenu / DropdownMenu / cmdk 處理)。已在「選擇 / 狀態視覺規則」段 codify。
 - **Loading**:MenuItem 為單一 row primitive 非 async surface,本身不擁有 loading prop。Async option list 的 loading 由 consumer(SelectMenu / Combobox / DropdownMenu)在 list body 替換為 `<Empty icon={<CircularProgress/>}/>`(SelectMenu SSOT)。
 - **Empty(label-only / icon-only)**:label 為必傳;若無 prefix icon / avatar / checkbox,layout 自動收斂為 `[label] [suffix?]`;若無 suffix(shortcut / endAction / chevron),收斂為純 `[label]`。
+- **極長 label / description**:預設各 clamp 1 行 truncate(見「Clamp 政策」),row 高度恆為兩種之一不被撐高。
 - **Dark mode**:走 semantic token 自動 adapt。
 - **Density**:`size` 由 consumer menu(`Menu` block-tier `compact` / `reading`)決定 row height + padding,MenuItem 自身不持 density state。
 
@@ -282,11 +297,8 @@ MenuItem 的狀態色(default / hover / selected / disabled)是**結構性的**
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
-- `opacity.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
+- `dropdown-menu.spec.md`
+- `item-anatomy.spec.md`
+- `select-menu.spec.md`
 - `selection-item.spec.md`
 - `sidebar.spec.md`

package/src/components/Menu/menu-item.tsx

@@ -1,3 +1,7 @@
+/**
+ * @internal — DS-internal 單元(per `.claude/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
+ * 不進 root barrel front-door;由 DropdownMenu / SelectMenu 等 menu 類 DS 元件 wrap 消費,end-user app 請用 wrapper 元件。
+ */
 // @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
 import * as React from 'react'
 import { cva, type VariantProps } from 'class-variance-authority'
@@ -20,7 +24,7 @@ import { ICON_SIZE, AVATAR_SIZE, ItemContent, itemPrefixAlignVariants, ROW_PADDI
  *
  * ── Prefix 對齊規則（24px 閾值）──
  *   prefix ≤ 24px  → h-[1lh]，對齊第一行 label
- *   prefix > 24px  → h-[calc(1lh+var(--item-gap-label-desc)+desc_1lh)]，對齊文字區塊
+ *   prefix > 24px  → h-[calc(1lh+var(--item-gap-label-desc-scanning)+desc_1lh)](size-aware -scanning[-lg] 變體)，對齊文字區塊
  *   無 description → prefix 上限 24px
  *
  * ── Size ──
@@ -86,7 +90,7 @@ export interface MenuItemProps
    * Label 最大行數(line-clamp 截斷,超過顯示 ellipsis)。
    *
    * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `1`(單行截斷,符合選單快速掃視需求)
-   * - 數字 → 截斷到該行數
+   * - 數字(1-6)→ 截斷到該行數;>6 超出 line-clamp utility 支援範圍 → 不截斷(同 'none',見 lineClampClass)
    * - `'none'` → **明確**不截斷,自然 wrap 任意行數
    *
    * 為什麼用 `'none'` 而不是 `undefined` 表達不截斷?React props 的 destructure default
@@ -98,7 +102,7 @@ export interface MenuItemProps
    * Description 最大行數。
    *
    * - `undefined`(預設 prop 值未傳)→ 套用元件預設 `1`(跟 label 對稱,維持掃視節奏)
-   * - 數字 → 截斷到該行數
+   * - 數字(1-6)→ 截斷到該行數;>6 超出 line-clamp utility 支援範圍 → 不截斷(同 'none',見 lineClampClass)
    * - `'none'` → 明確不截斷
    *
    * 為什麼預設 1?Menu 的設計目的是「快速掃視多個選項挑一個」,垂直空間是

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

@@ -26,19 +26,19 @@ export const UsageGuidance: Story = {
         <p>適合 Notice 的真實業務場景(點擊跳轉「展示」頁範例):</p>
         <ul className="space-y-1">
           <li>
-            <LinkTo kind="Design System/Internal/Notice/展示" name="部署成功 橫幅"><span className="text-primary hover:underline font-medium cursor-pointer">部署成功 橫幅</span></LinkTo>
+            <LinkTo kind="Design System/Internal/Notice/展示" name="部署成功 橫幅"><span className="text-primary hover:underline font-medium cursor-pointer">CI/CD 部署成功橫幅 — 附「查看部署紀錄」動作</span></LinkTo>
           </li>
           <li>
-            <LinkTo kind="Design System/Internal/Notice/展示" name="工作區付款失敗"><span className="text-primary hover:underline font-medium cursor-pointer">Workspace 付款失敗</span></LinkTo>
+            <LinkTo kind="Design System/Internal/Notice/展示" name="工作區付款失敗"><span className="text-primary hover:underline font-medium cursor-pointer">工作區付款失敗 — 附「更新付款方式」補救動作</span></LinkTo>
           </li>
           <li>
-            <LinkTo kind="Design System/Internal/Notice/展示" name="行內通知變體對照"><span className="text-primary hover:underline font-medium cursor-pointer">行內通知變體對照</span></LinkTo>
+            <LinkTo kind="Design System/Internal/Notice/展示" name="行內通知變體對照"><span className="text-primary hover:underline font-medium cursor-pointer">方案限制 / 空間不足 / 連線失敗等行內提示(五種語意變體)</span></LinkTo>
           </li>
           <li>
-            <LinkTo kind="Design System/Internal/Notice/展示" name="Toast 樣式"><span className="text-primary hover:underline font-medium cursor-pointer">Toast 樣式</span></LinkTo>
+            <LinkTo kind="Design System/Internal/Notice/展示" name="Toast 樣式"><span className="text-primary hover:underline font-medium cursor-pointer">「變更已儲存」「已複製連結」Toast 短暫提示</span></LinkTo>
           </li>
           <li>
-            <LinkTo kind="Design System/Internal/Notice/展示" name="中性 純文字"><span className="text-primary hover:underline font-medium cursor-pointer">Neutral 純文字</span></LinkTo>
+            <LinkTo kind="Design System/Internal/Notice/展示" name="中性 純文字"><span className="text-primary hover:underline font-medium cursor-pointer">成員邀請待加入提醒 — 中性純文字</span></LinkTo>
           </li>
         </ul>
         <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方 vs 近親段落)。</p>
@@ -47,7 +47,7 @@ export const UsageGuidance: Story = {
       <Section title="何時不用 + 替代">
         <p>Notice 是 internal primitive,自身有 dismiss 按鈕 + <code>onDismiss</code> callback,但不管 dismiss 後的 mount / unmount 生命週期,也無 auto-dismiss 計時——需要這些行為改用以下 consumer:</p>
         <ul>
-          <li><strong>需要管理 dismiss 後移除(永久 inline)</strong> → 用 <code>Alert</code>(內部消費 Notice + 處理 unmount + role="alert")</li>
+          <li><strong>需要管理 dismiss 後移除(永久 inline)</strong> → 用 <code>Alert</code>(內部消費 Notice + 處理 unmount + live region:error/warning role="alert"、其餘 role="status")</li>
           <li><strong>需要 auto-dismiss(短暫 toast)</strong> → 用 <code>Toast</code></li>
           <li><strong>表單欄位錯誤訊息</strong> → 用 <code>Field</code> 內建 errorText,不用 Notice</li>
         </ul>
@@ -74,7 +74,7 @@ export const CompositionRules: Story = {
     <div>
       <Section title="Pattern 1 — Alert(persistent inline announcement)">
         <div className="prose prose-sm max-w-prose">
-          <p>需要「持續顯示直到 user 主動 dismiss」→ <LinkTo kind="Design System/Components/Alert/展示" name="低調 單行"><span className="text-primary hover:underline font-medium cursor-pointer">Subtle 單行</span></LinkTo>。Alert 內部消費 Notice + 加上 dismiss button + role="alert" ARIA。</p>
+          <p>需要「持續顯示直到 user 主動 dismiss」→ <LinkTo kind="Design System/Components/Alert/展示" name="低調單行"><span className="text-primary hover:underline font-medium cursor-pointer">Alert 低調單行</span></LinkTo>。Alert 內部消費 Notice + 加上 dismiss button + live region ARIA(error/warning → role="alert" assertive;info/success/neutral → role="status" polite)。</p>
           <ul>
             <li>典型場景:付款失敗 banner / workspace 警告 / 重要通知 user 必看</li>
             <li>對齊世界級:Polaris <code>Banner</code> / Material <code>Banner</code> / Atlassian <code>InlineMessage</code> — 共識用「persistent + dismissible」</li>

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

@@ -25,7 +25,7 @@ Notice 是純視覺 primitive，不是獨立使用的元件。消費者：
 
 **Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」章節的 reading-mode 規格。Notice 語意為 notification（非 row collection），但視覺排版遵循 Family 2 確保跨元件視覺一致。
 
-**尺寸偏離（documented exception）**：Notice / Alert / Toast **單一固定 size**，**不**實作 Family 2 baseline 的 sm/md/lg。世界級共識（Material Banner/Snackbar、Polaris Banner、Atlassian InlineMessage、GitHub Flash）都是**單一 prominent size**——通知的使命是「搶注意」而非「在密度選擇裡協調」，提供 size 選項反而會讓 consumer 糾結（該用哪個 size？）而稀釋元件的目的性。同理 padding 也不隨 density 變（`px-4 py-3` 固定）——通知是跨 density 一致的訊息載體。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**尺寸偏離（documented exception）**：Notice / Alert / Toast **單一固定 size**——不實作 Family 2 baseline 的 sm/md/lg，padding 也不隨 density 變（`px-4 py-3` 固定）。通知用單一 prominent size 強化「搶注意」的目的性，對齊世界級共識（Material Banner/Snackbar、Polaris Banner、Atlassian InlineMessage、GitHub Flash）。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ## Typography
 
@@ -107,7 +107,7 @@ Notice 是 **Toast / Alert 共用的 layout primitive**,刻意不擁有尺寸與
 - **無 SizeMatrix**:Notice / Alert / Toast **單一固定 size**(見本 spec「尺寸偏離」段),不實作 Family 2 baseline 的 sm/md/lg——通知的使命是「搶注意」而非「在密度選擇裡協調」。padding 固定 `px-4 py-3`,typography 固定 md tier(14px),不隨 density 變。
 - **無 ColorMatrix**:Notice 本身**不設 bg / text color**(見本 spec「Theme 策略」段),色彩完全由 consumer(Alert / Toast)透過 `data-theme` + `text-foreground` 控制。Notice 層級的色彩矩陣沒有意義——視覺對照屬於 consumer 的職責,應查 `alert.anatomy.stories.tsx` 與 `toast.anatomy.stories.tsx` 的 ColorMatrix。
 
-對應 anatomy story:保留 `Overview` / `Inspector` / `StateBehavior`,額外追加元件特有的 `VariantIconMap`(展示 5 種 variant 對應的 status icon + 語意)。
+對應 anatomy story:保留 `Overview` / `Inspector` / `StateBehavior` / `Accessibility`,額外追加元件特有的 `VariantIconMap`(展示 5 種 variant 對應的 status icon + 語意)。
 
 ---
 
@@ -115,7 +115,7 @@ Notice 是 **Toast / Alert 共用的 layout primitive**,刻意不擁有尺寸與
 
 - **Disabled(dismiss button)**:Notice 本身不擁有 disabled state(internal primitive,無互動);內嵌的 `<Button iconOnly dismiss size="xs" />` 在 disabled context 內會自動繼承 Button disabled 視覺(`text-fg-disabled` + `cursor-not-allowed`)。Notice **不提供 disable dismiss 的 API**——`...props` 只 spread 到 root `<div>`,dismiss `<Button>` 不接收 / 不 forward 任何 consumer disabled prop,無 consumer-level prop pass-through 可停用 dismiss。對齊消費者 canonical(`../Alert/alert.spec.md`「Disabled(dismiss button)」:banner dismiss 恆可用,對齊 Polaris / Material Banner「通知關閉鈕應永遠可按」);若需防止 close action(API in-flight)被雙擊,consumer 在 `onDismiss` 內自行 debounce / 加上層鎖,不在 UI 層暴露 disabled 透傳。
 - **Loading**:Notice 非 async surface,無 loading state。Body 內若 consumer 注入 CTA Button,該 Button 自行處理 loading。
-- **Empty**:Notice 的 `title` 為必填(消費合約),`description` 選填;layout 至少 1 行 title 內容。`neutral` variant 不渲 status icon 時即為 title-only icon-less 形態(見 `NeutralTitleOnly` story),仍合法 render。
+- **Empty**:Notice 的 `title` 為必填(TypeScript required prop,消費合約),`description` 選填;layout 至少 1 行 title 內容。誤傳空字串時照常 render(無 runtime warn / throw),空 title 的內容責任在 consumer(Alert / Toast)。`neutral` variant 不渲 status icon 時即為 title-only icon-less 形態(見 `NeutralTitleOnly` story),仍合法 render。
 - **Icon-only / variant=neutral**:`neutral` variant 不渲 status icon,layout 自動收斂為 `[title + description?]  [endContent?]  [dismiss X?]` 三 slot。
 
 ---
@@ -137,9 +137,9 @@ Notice 是 **Toast / Alert 共用的 layout primitive**,刻意不擁有尺寸與
 - Tab — focus dismiss button(若 dismissible)
 - Enter / Space — 觸發 focus 中的 dismiss button(原生 button 行為,呼叫 `onDismiss`)
 
-Notice **不**自帶 Esc-to-dismiss 行為(`notice.tsx` 無 keydown handler);dismiss 純粹由 dismiss button 的 `onClick={onDismiss}` 觸發。若 consumer(Alert / Toast)需要 Esc 關閉,於 consumer 層自行掛 keydown。
+Notice **不**自帶 Esc-to-dismiss 行為(`notice.tsx` 無 keydown handler);dismiss 純粹由 dismiss button 的 `onClick={onDismiss}` 觸發。若 consumer(Alert / Toast)需要 Esc 關閉,於 consumer 層自行掛 keydown。Dismiss 後的焦點處置 Notice 同樣不管理(無 focus restoration 邏輯)——節點移除後焦點落點由 consumer(Alert / Toast host)決定。
 
-**Focus**:focus-visible ring 對齊 DS canonical(`outline: 2px solid var(--ring)`);focus management 由元件 own。
+**Focus**:唯一 focusable 元素是 dismiss `<Button>`,focus indicator 走 Button canonical(`focus-visible:ring-2 ring-ring`,box-shadow ring 非 CSS `outline`);Notice 本身無 focus management(dismiss 後焦點處置見上段,由 consumer 決定)。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -147,5 +147,7 @@ Notice **不**自帶 Esc-to-dismiss 行為(`notice.tsx` 無 keydown handler);dis
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `alert.spec.md`
 - `bulk-action-bar.spec.md`
 - `coachmark.spec.md`
+- `toast.spec.md`

package/src/components/Notice/notice.tsx

@@ -1,3 +1,7 @@
+/**
+ * @internal — DS-internal 單元(per `.claude/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
+ * 不進 root barrel front-door;由 Alert / Toast wrap 消費,end-user app 請用 wrapper 元件。
+ */
 import * as React from 'react'
 import { X as XIcon, Info, CircleCheck, TriangleAlert, XCircle, type LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
@@ -186,7 +190,7 @@ export const noticeMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  states: ['default'], // 無互動 layout primitive(spec「邊界案例」:不擁有 disabled;hover / focus 屬內嵌 dismiss Button)
   tokens: {
     bg: [],
     fg: ['text-error-text', 'text-fg-muted', 'text-fg-secondary', 'text-info-text', 'text-success-text', 'text-warning-text'],

package/src/components/NumberInput/number-input.anatomy.stories.tsx

@@ -45,7 +45,7 @@ const TOKEN_MAP: Record<ModeKey, Record<StateKey, ColorSpec>> = {
     disabled: { bg: 'transparent',    text: '--fg-disabled',  border: 'transparent' },
   },
   readonly: {
-    default:  { bg: '--bg-disabled',  text: '--foreground',   border: 'transparent' },
+    default:  { bg: '--bg-readonly',  text: '--foreground',   border: 'transparent' },
     hover:    { bg: '--bg-disabled',  text: '--foreground',   border: 'transparent' },
     focus:    { bg: '--bg-disabled',  text: '--foreground',   border: 'transparent' },
     error:    { bg: '--bg-disabled',  text: '--foreground',   border: 'transparent' },
@@ -254,8 +254,8 @@ export const Overview = {
                 ['precision', 'number', '—', '小數位數'],
                 ['locale', 'string', "'en-US'", '數字格式 locale'],
                 ['endAction', 'InlineActionConfig', '—', '右側 inline action（宣告式 API）'],
-                ['disabled', 'boolean', 'false', '原生屬性，自動覆蓋 mode 為 disabled'],
-                ['readOnly', 'boolean', 'false', '原生屬性，自動覆蓋 mode 為 readonly'],
+                ['disabled', 'boolean', 'false', '原生屬性；mode 未顯式指定時解析為 disabled（顯式 mode prop 永遠最優先，useResolvedFieldMode SSOT）'],
+                ['readOnly', 'boolean', 'false', '原生屬性；mode 未顯式指定且無 Field context mode 時解析為 readonly（優先序 mode > 有效 disabled > fieldCtx.mode > readOnly）'],
               ].map(([p, t, d, desc]) => (
                 <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
               ))}
@@ -760,7 +760,7 @@ export const StateBehavior = {
                   ['type="text" inputMode="decimal"', '用 text 而非 number，避免瀏覽器 spinner 干擾'],
                   ['空字串 / "-" → onChange(null)', '清空或只剩負號時回傳 null'],
                   ['NaN 忽略', '非數字輸入不觸發 onChange'],
-                  ['disabled / readOnly 原生屬性覆蓋 mode', 'disabled → mode="disabled", readOnly → mode="readonly"'],
+                  ['disabled / readOnly 參與 mode 推導', 'mode 未顯式指定時：有效 disabled → "disabled"；readOnly 排在 Field context mode 之後 → "readonly"（顯式 mode prop 永遠最優先，useResolvedFieldMode）'],
                 ].map(([rule, desc]) => (
                   <tr key={rule}><Td mono>{rule}</Td><Td>{desc}</Td></tr>
                 ))}

package/src/components/NumberInput/number-input.principles.stories.tsx

@@ -71,7 +71,7 @@ export const UsageGuidance: Story = {
       <Section title="vs 近親元件">
         <Rule
           title="❌ 不用 NumberInput 做電話號碼或郵遞區號 → Input"
-          note="電話不是算術數字。改用 Input + type='tel'。Stripe 的電話欄用 Input,不用 NumberInput(不該加千分位或用 step)"
+          note="電話、郵遞區號、身分證字號、產品代碼都「長得像數字」但不是算術型 value——不做加減、不做千分位、不做 step。改用 Input + type='tel' / pattern(Stripe 的電話欄用 Input)。用 NumberInput 會錯誤套用千分位、吃掉前導零,且誤導 mobile 彈出數字鍵盤"
         >
           <NumberInput mode="readonly" value={912345678} />
           <Label warn>↑ 電話 0912-345-678 被當數值,顯示時加上千分位 912,345,678 → 數字意義錯誤(前導零也被吃掉)</Label>
@@ -94,6 +94,14 @@ export const UsageGuidance: Story = {
           <NumberInput mode="readonly" value={85.5} suffix="%" precision={1} />
           <NumberInput mode="readonly" value={12500} />
         </Rule>
+
+        <Rule
+          title="❌ 不用 Input 顯示數字"
+          note="即使值看起來「就是數字字串」,缺少格式化會讓大數字不可讀(1234567 vs 1,234,567)。Edit 與 Display 分離是 Field 設計的基本前提——用 NumberInput 兩者都得到"
+        >
+          <Input defaultValue="1234567" />
+          <Label warn>↑ 1234567 難讀、無貨幣前綴、無 locale、無右對齊</Label>
+        </Rule>
       </Section>
     </div>
   ),
@@ -153,7 +161,7 @@ export const FormatOptionsRule: Story = {
     <div>
       <Rule
         title="prefix — 置於數字前的符號(貨幣是最常見場景)"
-        note="prefix 會同時出現在 edit、readonly、DataTable cell。使用者不需要自己輸入 $——打字就是純數字"
+        note="prefix 出現在 readonly / display / disabled 與 DataTable cell 的格式化值;edit 模式輸入 raw 純數字、不渲染 prefix——使用者不需要自己輸入 $"
       >
         <NumberInput mode="readonly" value={2490} prefix="$" />
         <NumberInput mode="readonly" value={12500} prefix="NT$" precision={0} />
@@ -186,36 +194,6 @@ export const FormatOptionsRule: Story = {
   ),
 }
 
-export const DataTypeMatchRule: Story = {
-  name: '數字一律用 NumberInput',
-  render: () => (
-    <div>
-      <Rule
-        title="所有數值資料都用 NumberInput——不用 Input type=number"
-        note="NumberInput 提供:千分位格式化、locale 切換、prefix/suffix、precision、edit 左 / table 右 對齊、DataTable 自動整合。原生 input type=number 這些都沒有"
-      >
-        <NumberInput mode="readonly" value={1234567} prefix="$" />
-        <NumberInput mode="readonly" value={85.5} suffix="%" precision={1} />
-        <NumberInput mode="readonly" value={12500} />
-      </Rule>
-
-      <Rule
-        title="❌ 不用 Input 顯示數字"
-        note="即使值看起來「就是數字字串」,缺少格式化會讓大數字不可讀(1234567 vs 1,234,567)。Edit 與 Display 分離是 Field 設計的基本前提——用 NumberInput 兩者都得到"
-      >
-        <Input defaultValue="1234567" />
-        <Label warn>↑ 1234567 難讀、無貨幣前綴、無 locale、無右對齊</Label>
-      </Rule>
-
-      <Rule
-        title="❌ 看起來像數字但不是算術型的資料:用 Input"
-        note="電話、郵遞區號、身分證字號、產品代碼都「長得像數字」但不是算術型 value——不做加減、不做千分位、不做 step。用 NumberInput 會錯誤套用千分位(0912-345-678 變成「912,345,678」)、誤導 mobile 彈出數字鍵盤且關閉符號輸入"
-      >
-        <NumberInput mode="readonly" value={912345678} />
-        <Label warn>↑ 電話 0912-345-678 被當數值,顯示時加上千分位 912,345,678 → 數字意義錯誤(前導零也被吃掉)</Label>
-        <Input defaultValue="0912-345-678" />
-        <Label>↑ 電話用 Input(可自訂 type=tel 或 pattern),保留 dash / 前導零</Label>
-      </Rule>
-    </div>
-  ),
-}
+// @story-trait-rationale: DataTypeMatchRule(數字一律用 NumberInput)retired 2026-06-11 per audit Dim 24/25 —
+//   與 UsageGuidance「vs 近親元件」段完整重複(✅ NumberInput-over-Input / ❌ 電話號碼非算術型);
+//   唯一未覆蓋的「❌ 不用 Input 顯示數字」與「非算術型資料」完整 note 已折入 UsageGuidance。

package/src/components/NumberInput/number-input.spec.md

@@ -19,6 +19,10 @@ NumberInput 是**數值的**輸入與顯示元件。格式化邏輯：`toLocaleS
 
 共用規則見 `../Field/field-controls.spec.md`。本文件只記錄 NumberInput 特有的原則。
 
+## Controlled-only rationale(Dim 26)
+
+本元件採 **controlled-only**:`value` + `onChange`,不支援 `defaultValue` uncontrolled fallback(value pair V1)。對齊 Field 家族 canonical(Combobox / DatePicker / TimePicker / SelectMenu 同,rationale 見各 spec 同名段);NumberInput 另因 raw 輸入 ↔ 格式化值的 parse pipeline 以 `null` 為空值 sentinel,dual-mode 會複製 parse 狀態。未來要改 dual-mode 需 `useControllableState` helper,屬 major API 擴充。
+
 **Layout Family**：CLAUDE.md 4-Family Model **Family 4（Field control layout）** 消費者。結構繼承 `components/Field/field-controls.spec.md` 的 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1（Menu item）讓 SelectMenu trigger + options 連續一致。
 
 ---
@@ -39,6 +43,8 @@ NumberInput 是**數值的**輸入與顯示元件。格式化邏輯：`toLocaleS
 | 視覺調整數值（音量、亮度、滑動調整）| `Slider` | 使用者目標是「感受」而非「輸入精確值」 |
 | 大量帶小數的科學計算 | `Input` + 自訂驗證 | 極端精度需求超出 NumberInput 格式化能力 |
 
+**常見誤解**:(1)「看起來像數字」≠ 數值——電話 / 郵遞區號 / 身分證號用 `Input`(見上表);(2)百分比 value 直接存 `85` 非 `0.85`,`suffix='%'` 純顯示;(3)NumberInput **無** step ↑↓ stepper——純值輸入,加減互動走 `endSlot`(見禁止事項)。
+
 ---
 
 ## 格式化選項
@@ -50,6 +56,8 @@ NumberInput 是**數值的**輸入與顯示元件。格式化邏輯：`toLocaleS
 | `precision` | 小數位數 | `85.50` |
 | `locale` | 數字格式 locale | 預設 `en-US` |
 
+千分位**無獨立 prop**——由 `toLocaleString(locale)` 自動產生(含負號與超大數字分組)。「何時用」列的四種格式化(千分位 / 前綴 / 後綴 / 精度)= 上表 3 個 prop + 此預設行為的映射。
+
 ## 對齊
 
 - **Edit 模式（input）**：靠左——input 內打字是左到右
@@ -99,6 +107,10 @@ col.accessor('price', {
 - **Loading**:NumberInput 不提供 loading state(`NumberInputProps` 無 `loading` prop、無 `CircularProgress` / `aria-busy` 邏輯)。數值輸入為同步操作,無 async fetch 語意;若需 async 場景(如遠端校驗)請走外層 Field validation + `endSlot` 自訂 spinner。
 - **Empty(null / undefined / 空字串)**:Display mode 渲 `—`(em dash + `text-fg-muted`);Edit mode placeholder 走 default placeholder color。
 - **Invalid input**(non-numeric):input 為 `type="text" inputMode="decimal"`,onChange 以 `Number(raw)` parse,NaN 時忽略不觸發 `onChange`(value 維持原值);搭配 Field validation 渲 error variant(`aria-invalid="true"` + `text-fg-error` border + 下方 error message)。
+- **負數 / 超大數字**:`toLocaleString(locale)` 自動處理負號與千分位分組,無特殊 prop。
+- **科學記號輸入**(`1e5`):`Number(raw)` parse 為 `100000`,非 NaN 即觸發 `onChange`(`number-input.tsx:136-138`)。
+- **精度上限**:`precision` > 6 為禁止事項(浮點精度雜訊),極端精度走 `Input` + 自驗證。
+- **RTL**:未實作方向鏡像(edit 靠左 / table cell 靠右皆以 LTR 設計);RTL 屬 DS-wide 決策,未定(與 Chip / Breadcrumb 同口徑)。
 - **Dark mode / density**:走 Field SSOT,不獨立 own。
 
 ---
@@ -123,3 +135,10 @@ col.accessor('price', {
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `date-picker.spec.md`
+- `input.spec.md`
+- `slider.spec.md`

package/src/components/OverflowIndicator/overflow-indicator.anatomy.stories.tsx

@@ -4,7 +4,8 @@
 //     ShapeMatrix(3.)已對照 shape × 色彩 token + consumer 場景。HoverCard
 //     content 走深色 tooltip,色彩繼承 tooltip token。
 //   StateBehavior N/A — Trigger pill 本身無 hover 視覺(hover 觸發 HoverCard
-//     展開即是 state 表達);無 focus / active / disabled。openDelay /
+//     展開即是 state 表達);無 active / disabled;focus-visible ring 屬 a11y
+//     focusable 修正(2026-06-01 #13,見 Accessibility story)非獨立視覺軸。openDelay /
 //     closeDelay 等行為已於 Inspector 展示。HoverCard 內容互動由消費的內容
 //     元件(Avatar / Tag)各自負責。
 import type { Meta, StoryObj } from '@storybook/react'
@@ -321,7 +322,7 @@ function OverflowInspector() {
               </tr>
               <tr>
                 <Td mono>openDelay</Td>
-                <Td mono>700ms（HOVER_DELAY_RICH_MS）</Td>
+                <Td mono>500ms（HOVER_DELAY_PLAIN_MS）</Td>
               </tr>
               <tr>
                 <Td mono>closeDelay</Td>
@@ -542,7 +543,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"摘要:\n\n  ARIA / Pattern  :對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。\n\n  互動行為  :\n\n  +N trigger 是 passive 計數 span（cursor-default，無 tabIndex / role / Enter handler）。HoverCard 在 hover 或 trigger 取得 focus 時自動展開，沒有「按 Enter 開選單」的鍵盤指令，也沒有 click 切換。\n\n  Focus  :trigger 本身不是 tab stop；HoverCard 內展開的可互動內容（人員 tag / ProfileCard）由各自內容元件負責 focus 管理。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation；HoverCard 內容透過 hover 或 focus 自動顯示（非鍵盤指令觸發）。WCAG AA contrast ≥ 4.5:1（text）/ 3:1（UI）。"}</p>
+      <p className="whitespace-pre-line">{"摘要:\n\n  ARIA / Pattern  :對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。\n\n  互動行為  :\n\n  +N trigger 是 keyboard-focusable 計數 span（tabIndex=0 + role=\"button\" + aria-haspopup=\"dialog\"；2026-06-01 #13 由純 passive 改 focusable，修 WCAG 2.1.1 違反）。HoverCard 在 hover 或 trigger 取得 focus 時自動展開，沒有「按 Enter 開選單」的鍵盤指令，也沒有 click 切換。\n\n  Focus  :trigger 是 tab stop（focus-visible ring，鍵盤使用者可 focus 開啟 HoverCard 看溢出內容）；HoverCard 內展開的可互動內容（人員 tag / ProfileCard）由各自內容元件負責 focus 管理。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation；HoverCard 內容透過 hover 或 focus 自動顯示（非鍵盤指令觸發）。WCAG AA contrast ≥ 4.5:1（text）/ 3:1（UI）。"}</p>
     </div>
   ),
 }

package/src/components/OverflowIndicator/overflow-indicator.principles.stories.tsx

@@ -27,10 +27,7 @@ export const UsageGuidance: Story = {
           <LinkTo kind="Design System/Internal/OverflowIndicator/展示" name="Combobox 標籤溢出"><span className="text-primary hover:underline font-medium cursor-pointer">Combobox 標籤溢出</span></LinkTo>
         </li>
         <li>
-          <LinkTo kind="Design System/Internal/OverflowIndicator/展示" name="人員頭像 疊合 +N"><span className="text-primary hover:underline font-medium cursor-pointer">人員頭像 疊合 +N</span></LinkTo>
-        </li>
-        <li>
-          <LinkTo kind="Design System/Internal/OverflowIndicator/展示" name="形狀對照"><span className="text-primary hover:underline font-medium cursor-pointer">形狀對照</span></LinkTo>
+          <LinkTo kind="Design System/Internal/OverflowIndicator/展示" name="人員頭像 疊合 +N"><span className="text-primary hover:underline font-medium cursor-pointer">PR reviewer 頭像疊合 +N(只顯前 3 位)</span></LinkTo>
         </li>
         <li>
           <LinkTo kind="Design System/Internal/OverflowIndicator/展示" name="Breadcrumb 中段收合"><span className="text-primary hover:underline font-medium cursor-pointer">Breadcrumb 中段收合</span></LinkTo>
@@ -39,7 +36,7 @@ export const UsageGuidance: Story = {
           <LinkTo kind="Design System/Internal/OverflowIndicator/展示" name="DataTable 人員欄位"><span className="text-primary hover:underline font-medium cursor-pointer">DataTable 人員欄位</span></LinkTo>
         </li>
       </ul>
-      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方 vs 近親段落)。</p>
     </div>
 
       {/* vs 近親 — VsScrollAreaRule — 原 VsScrollAreaRule */}

package/src/components/OverflowIndicator/overflow-indicator.spec.md

@@ -67,6 +67,15 @@ sm / md 跟 Tag 同階（20/24px），lg 對齊 md（尺寸需求一致，不需
 
 ---
 
+## 邊界案例
+
+- **count ≤ 0**:元件自行不渲染(return `null`)——「無溢出」時 consumer 不需條件渲染
+- **大數值**:`+N` 原樣顯示(無 `99+` 縮寫),trigger `min-w` 起步、隨位數自然加寬
+- **極窄容器 / 貼 viewport 邊**:浮層定位與翻邊由 HoverCard(Radix collision)處理,見 `hover-card.spec.md`
+- **已展開時項目變動**:children 變動觸發浮層寬度重新量測(shrink-wrap re-measure)
+
+---
+
 ## 禁止事項
 
 - ❌ 用 Tooltip 取代 HoverCard——溢出內容可能需要互動
@@ -116,4 +125,3 @@ OverflowIndicator 是 **composite**(HoverCard trigger + tag-styled `+N` span + H
 **Focus**:trigger 是 tab stop(keyboard 可達 + focus-visible ring,讓鍵盤使用者也能 focus 開啟 HoverCard 看溢出內容);HoverCard 內展開的可互動內容(如人員 tag / ProfileCard)由各自的內容元件負責 focus 管理。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;HoverCard 內容透過 hover 或 focus 自動顯示(非鍵盤指令觸發)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
-

package/src/components/OverflowIndicator/overflow-indicator.stories.tsx

@@ -120,49 +120,13 @@ export const AvatarStackOverflow: Story = {
   ),
 }
 
-/* ═══════════════════════════════════════════════════════════════════════════
-   Story 3:形狀對照(circle vs tag)
-   ═══════════════════════════════════════════════════════════════════════════ */
-
-export const Shapes: Story = {
-  name: '形狀對照',
-  render: () => (
-    <div className="flex flex-col gap-6">
-      <div className="flex flex-col gap-2">
-        <span className="text-caption text-fg-muted">shape="circle" — 搭配 Avatar stack 用,圓形 pill</span>
-        <div className="flex items-center gap-3">
-          <OverflowIndicator count={3} shape="circle" size="sm">
-            <div className="text-caption">sm 20px</div>
-          </OverflowIndicator>
-          <OverflowIndicator count={12} shape="circle" size="md">
-            <div className="text-caption">md 24px</div>
-          </OverflowIndicator>
-          <OverflowIndicator count={99} shape="circle" size="lg">
-            <div className="text-caption">lg 24px</div>
-          </OverflowIndicator>
-        </div>
-      </div>
-
-      <div className="flex flex-col gap-2">
-        <span className="text-caption text-fg-muted">shape="tag" — 搭配 Tag 組溢出,rounded-md rectangle</span>
-        <div className="flex items-center gap-3">
-          <OverflowIndicator count={3} shape="tag" size="sm">
-            <div className="text-caption">sm Tag 樣式</div>
-          </OverflowIndicator>
-          <OverflowIndicator count={12} shape="tag" size="md">
-            <div className="text-caption">md Tag 樣式</div>
-          </OverflowIndicator>
-          <OverflowIndicator count={99} shape="tag" size="lg">
-            <div className="text-caption">lg Tag 樣式</div>
-          </OverflowIndicator>
-        </div>
-      </div>
-    </div>
-  ),
-}
+// @story-trait-rationale: Shapes(形狀對照)retired 2026-06-11 per audit Dim 24/25 —
+//   shape × size 全矩陣已由 anatomy ShapeMatrix「Shape × Size 視覺矩陣」+ SizeMatrix
+//   (overflow-indicator.anatomy.stories.tsx)完整覆蓋,展示層只留真實業務場景;
+//   principles UsageGuidance 對應 LinkTo 已同步移除。
 
 /* ═══════════════════════════════════════════════════════════════════════════
-   Story 4:Breadcrumb 中段收合(+N 顯示隱藏路徑)
+   Story 3:Breadcrumb 中段收合(+N 顯示隱藏路徑)
    ═══════════════════════════════════════════════════════════════════════════ */
 
 export const BreadcrumbCollapse: Story = {
@@ -192,7 +156,7 @@ export const BreadcrumbCollapse: Story = {
 }
 
 /* ═══════════════════════════════════════════════════════════════════════════
-   Story 5:DataTable row 的指派人員溢出
+   Story 4:DataTable row 的指派人員溢出
    ═══════════════════════════════════════════════════════════════════════════ */
 
 const rows = [

package/src/components/OverflowIndicator/overflow-indicator.tsx

@@ -1,8 +1,12 @@
+/**
+ * @internal — DS-internal 單元(per `.claude/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
+ * 不進 root barrel front-door;由 Combobox / PeoplePicker 等 DS 元件 wrap 消費,end-user app 請用 wrapper 元件。
+ */
 import * as React from 'react'
 import { cn } from '@/lib/utils'
 import { HoverCard, HoverCardTrigger, HoverCardContent } from '@/design-system/components/HoverCard/hover-card'
 import { tagVariants } from '@/design-system/components/Tag/tag'
-import { HOVER_DELAY_RICH_MS, HOVER_DELAY_CLOSE_MS } from '@/design-system/tokens/motion/motion'
+import { HOVER_DELAY_PLAIN_MS, HOVER_DELAY_CLOSE_MS } from '@/design-system/tokens/motion/motion'
 
 /**
  * OverflowIndicator — +N 觸發器 + HoverCard 顯示溢出內容
@@ -126,9 +130,11 @@ const OverflowIndicator = React.forwardRef<HTMLSpanElement, OverflowIndicatorPro
     )
 
     // 2026-05-18 fix(per user audit「所有 hovercard 應消費 hover delay token」+ motion.spec.md SSOT):
-    // rich tier(可互動 popup,user 可移浮層上操作)= HOVER_DELAY_RICH_MS;close = HOVER_DELAY_CLOSE_MS。
+    // plain tier(純列表展開、無 fetch)= HOVER_DELAY_PLAIN_MS,per motion.spec.md 對照表 row;
+    // close = HOVER_DELAY_CLOSE_MS。2026-06-11 修:2026-05-18 token 遷移誤挑 rich(原 hardcode 200/300
+    // 兩 tier 皆非,遷移未對照 spec 表)— popup 可互動性由 close 緩衝保障,與 open tier 無關。
     return (
-      <HoverCard openDelay={HOVER_DELAY_RICH_MS} closeDelay={HOVER_DELAY_CLOSE_MS}>
+      <HoverCard openDelay={HOVER_DELAY_PLAIN_MS} closeDelay={HOVER_DELAY_CLOSE_MS}>
         <HoverCardTrigger asChild>
           {trigger}
         </HoverCardTrigger>

package/src/components/PeoplePicker/people-picker.anatomy.stories.tsx

@@ -97,12 +97,14 @@ export const Overview: Story = {
 export const Inspector: Story = {
   name: '元件檢閱器',
   parameters: {
-    docs: { description: { story: '右側 Controls 切 props 即時 render,取代 Figma inspect。切 `mode` 看 edit / display / readonly / disabled 視覺差異,切 `size` 對照 field-height tier。' } },
+    docs: { description: { story: '右側 Controls 切 props 即時 render,取代 Figma inspect。切 `mode` 看 edit / display / readonly / disabled 視覺差異,切 `size` 對照 field-height tier,切 `variant` 看 default / bare / naked chrome 差異。' } },
   },
   args: {
     mode: 'edit',
+    variant: 'default',
     size: 'md',
     disabled: false,
+    showDisplayEndIcon: false,
     value: SAMPLE_PEOPLE[0],
     people: SAMPLE_PEOPLE,
     searchPlaceholder: '搜尋指派對象…',
@@ -110,8 +112,10 @@ export const Inspector: Story = {
   },
   argTypes: {
     mode: { control: 'radio', options: ['edit', 'display', 'readonly', 'disabled'] },
+    variant: { control: 'radio', options: ['default', 'bare', 'naked'] },
     size: { control: 'radio', options: ['sm', 'md', 'lg'] },
     disabled: { control: 'boolean' },
+    showDisplayEndIcon: { control: 'boolean' },
     searchPlaceholder: { control: 'text' },
     emptyText: { control: 'text' },
   },
@@ -131,6 +135,11 @@ export const ModeMatrix: Story = {
         <Desc>Field 樣式 + 展開觸發 Popover + Command 搜尋。</Desc>
         <PeoplePicker people={SAMPLE_PEOPLE} value={SAMPLE_PEOPLE[0]} onChange={() => {}} />
       </div>
+      <div>
+        <H3>display</H3>
+        <Desc>裸 PersonDisplay(Avatar + Name),無 field chrome——DataTable cell / detail panel 純顯示。</Desc>
+        <PeoplePicker mode="display" people={SAMPLE_PEOPLE} value={SAMPLE_PEOPLE[0]} />
+      </div>
       <div>
         <H3>readonly</H3>
         <Desc>顯示選中人員(Avatar + Name),無 dropdown trigger、無搜尋。</Desc>
@@ -236,7 +245,7 @@ export const ColorMatrix: Story = {
               </tr>
               <tr>
                 <Td mono>readonly</Td>
-                <Td><TokenCell token="--bg-disabled" display="bg-disabled(鎖定底)" /></Td>
+                <Td><TokenCell token="--bg-readonly" display="bg-readonly(鎖定底)" /></Td>
                 <Td>—(no border)</Td>
                 <Td><TokenCell token="--foreground" /></Td>
               </tr>