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

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

@@ -68,10 +68,22 @@ export interface MenuItemProps
   children: React.ReactNode
   /** 次要說明文字，顯示在 label 下方 */
   description?: React.ReactNode
-  /** 左側 icon（LucideIcon），與 avatar 互斥 */
+  /** 左側 icon（LucideIcon），與 avatar / startContent 互斥 */
   startIcon?: LucideIcon
-  /** 左側頭像資料（AvatarData），元件內部渲染 Avatar。與 startIcon 互斥 */
+  /** startIcon 的 className 透傳(2026-07-08 WM 戰役:status 類彩色 icon 需求;disabled 色仍勝出) */
+  startIconClassName?: string
+  /** 左側頭像資料（AvatarData），元件內部渲染 Avatar。與 startIcon / startContent 互斥 */
   avatar?: AvatarData
+  /**
+   * 左側自訂內容（ReactNode），與 startIcon / avatar 互斥。與 `endContent` 對稱。
+   *
+   * **佔位與排列邏輯跟 startIcon 一模一樣**(2026-07-10 WM TypeIcon 彩色徽章需求):
+   * 渲染在同一個 prefix 對齊容器(`itemPrefixAlignVariants` SSOT)內 —— gap / 對齊 /
+   * shrink 全繼承,零平行 layout 邏輯,不可能與 startIcon 漂移。Consumer 唯一責任
+   * 是節點尺寸對齊 `ICON_SIZE[size]`(sm/md=16px、lg=20px;如 `size-4` 徽章)。
+   * 典型場景:類型徽章(彩底 + glyph)、status 圓點組合等 LucideIcon 表達不了的 leading 視覺。
+   */
+  startContent?: React.ReactNode
   /** 顯示 checkbox（多選模式由父層控制） */
   checkbox?: boolean
   /** Checkbox 選中狀態 */
@@ -132,7 +144,9 @@ const MenuItem = React.forwardRef<HTMLDivElement, MenuItemProps>(
       children,
       description,
       startIcon: StartIcon,
+      startIconClassName,
       avatar,
+      startContent,
       checkbox,
       checked,
       selected,
@@ -165,7 +179,7 @@ const MenuItem = React.forwardRef<HTMLDivElement, MenuItemProps>(
       ? (`block-${sizeKey}` as const)
       : 'inline'
 
-    const hasPrefix = !!StartIcon || !!avatar || checkbox
+    const hasPrefix = !!StartIcon || !!avatar || !!startContent || checkbox
 
     // ── Header variant ──
     if (header) {
@@ -221,11 +235,21 @@ const MenuItem = React.forwardRef<HTMLDivElement, MenuItemProps>(
         {hasPrefix && (
           <div className={cn(itemPrefixAlignVariants({ align: prefixAlign }))}>
             {checkbox && (
+              // 2026-07-14 a11y(axe nested-interactive):此 checkbox 是純視覺 indicator —— checked
+              // ARIA state 由外層 row 單一 owner 宣告(Radix menuitemcheckbox / cmdk option /
+              // select-all row role="checkbox",見上方「ARIA 單一 owner gate」)。Radix Checkbox 渲
+              // focusable <button role="checkbox">,巢狀在互動 row 內 = axe nested-interactive
+              // violation;tabIndex=-1 不夠(axe-core no-focusable-content 對 tabindex<0 仍回
+              // violation,僅 messageKey 換 notHidden)。aria-hidden 移出 AT tree(消 SR 內外雙重
+              // checkbox 宣告)+ inert 移除 focusability(axe focusDisabled 認 inert → clean pass)。
+              // inert:React 18 無 typing(React 19 才內建),以 spread cast 傳字串 attr。
               <Checkbox
                 size={CHECKBOX_SIZE[sizeKey]}
                 checked={checked === true ? true : checked === 'indeterminate' ? 'indeterminate' : false}
                 disabled={disabled}
                 tabIndex={-1}
+                aria-hidden
+                {...({ inert: '' } as object)}
                 className="pointer-events-none"
               />
             )}
@@ -233,7 +257,7 @@ const MenuItem = React.forwardRef<HTMLDivElement, MenuItemProps>(
               <StartIcon
                 data-prefix-type="icon"
                 size={iconPx}
-                className={cn('shrink-0', disabled && 'text-fg-disabled')}
+                className={cn('shrink-0', startIconClassName, disabled && 'text-fg-disabled')}
                 aria-hidden
               />
             )}
@@ -247,6 +271,16 @@ const MenuItem = React.forwardRef<HTMLDivElement, MenuItemProps>(
                 size={avatarPx}
               />
             )}
+            {startContent && (
+              // 自訂 leading 節點:同容器 = 佔位/排列與 startIcon 一模一樣(見 props JSDoc)。
+              // disabled 用 opacity-disabled(對齊本元件 suffix slot 對自訂 ReactNode 的同款處理)。
+              <span
+                data-prefix-type="content"
+                className={cn('flex shrink-0 items-center', disabled && 'opacity-disabled')}
+              >
+                {startContent}
+              </span>
+            )}
           </div>
         )}
 

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

@@ -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 + live region:error/warning role="alert"、其餘 role="status")</li>
+          <li><strong>需要 dismiss 後移除(永久 inline)</strong> → 用 <code>Alert</code>(內部消費 Notice + live region:error/warning role="alert"、其餘 role="status")。Alert 是 controlled-only:提供 <code>onDismiss</code> callback,consumer 在 callback 中更新狀態並自行 unmount,Alert 不會自行移除</li>
           <li><strong>需要 auto-dismiss(短暫 toast)</strong> → 用 <code>Toast</code></li>
           <li><strong>表單欄位錯誤訊息</strong> → 用 <code>Field</code> 內建 errorText,不用 Notice</li>
         </ul>

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

@@ -1,7 +1,18 @@
 ---
 component: Notice
 family: 2
-variants: {}
+# variant 語意 = status icon 選擇(見本文「Variant」表);world-class 對照見 frontmatter benchmark 清單
+variants:
+  neutral:
+    when: "一般訊息、系統公告;無情緒色、不掛 status icon"
+  info:
+    when: "資訊提示(版本更新、流程說明);Info icon"
+  success:
+    when: "操作成功確認;CircleCheck icon"
+  warning:
+    when: "可恢復警告(未儲存變更、連線不穩);TriangleAlert icon"
+  error:
+    when: "錯誤(操作失敗、權限不足);XCircle icon"
 sizes: {}
 traits:
   - isInternal
@@ -25,7 +36,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，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 -->
+**尺寸偏離（documented exception）**：Notice / Alert / Toast **單一固定 size**——不實作 Family 2 baseline 的 sm/md/lg，padding 預設不隨 density 變（`px-4 py-3` 固定；唯一例外：Alert `placement="fixed"` 水平 px 改 density-aware，詳「Padding」段）。通知用單一 prominent size 強化「搶注意」的目的性，對齊世界級共識（Material Banner/Snackbar、Polaris Banner、Atlassian InlineMessage、GitHub Flash）。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
 
 ## Typography
 
@@ -49,6 +60,8 @@ Notice 是純視覺 primitive，不是獨立使用的元件。消費者：
 
 不隨 density 變——Toast/Alert 是通知，不是工作區域元件。
 
+**例外——Alert `placement="fixed"` 水平 px density-aware**:Alert 的 fixed placement 傳 `className='px-[var(--layout-space-loose)]'`(`alert.tsx` fixed 分支)覆寫 Notice 的 `px-4`，改用 density-aware 水平 padding（md=16 / lg=24px），讓 fixed alert 嵌在更大佈局時跟周圍 loose-padding 元素（Toolbar / BulkActionBar / DataTable）左右對齊。垂直 `py-3` 仍固定（notification banner family 垂直不隨 density）。故上方「px 固定」限 Notice 預設 / Toast / Alert inline placement；Alert fixed placement 是唯一 documented 例外。
+
 ## Layout
 
 item-layout 4-slot：
@@ -89,7 +102,7 @@ CSS `color` 從 body 繼承的是**已解析的計算值**，不是 `var(--foreg
 
 ## 何時用 / 何時不用
 
-**Notice 是 internal primitive**——不直接使用，透過 `Alert` / `Toast` 等外層通知元件消費。
+**Notice 是 internal primitive**——不進 root barrel front-door、不裸用；透過 `Alert` / `Toast` 等外層通知元件消費；consumer 需要時可經 per-component subpath 包裝並自行確認後使用（`.claude/rules/ui-development.md`「Root barrel front-door 排除」SSOT，internal ≠ 禁用）。
 
 | 場景 | 正確做法 |
 |------|---------|

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

@@ -231,7 +231,7 @@ export const Overview = {
                 <NumberInput mode="readonly" value={value} {...props} className="max-w-[200px]" />
               </div>
               <span className="text-caption font-mono text-fg-secondary">{label}</span>
-              {value === null && <span className="text-[11px] text-fg-muted">em dash + text-fg-muted</span>}
+              {value === null && <span className="text-[11px] text-fg-muted">hyphen + text-foreground</span>}
             </div>
           ))}
         </div>
@@ -722,7 +722,7 @@ export const StateBehavior = {
                 {[
                   ['value = 2490, prefix="$"', '2490（raw 數值）', '$2,490（格式化）'],
                   ['value = 85.5, suffix="%", precision=1', '85.5（raw 數值）', '85.5%（格式化）'],
-                  ['value = null', '空白', '— (em dash, fg-muted)'],
+                  ['value = null', '空白', '- (hyphen, foreground)'],
                   ['value = 12500, prefix="NT$"', '12500（raw 數值）', 'NT$12,500（格式化）'],
                 ].map(([ctx, edit, display]) => (
                   <tr key={ctx}>
@@ -745,7 +745,7 @@ export const StateBehavior = {
               <div key={m} className="flex flex-col gap-1 items-start">
                 <span className="text-[11px] text-fg-muted font-mono">{m}</span>
                 <div className="w-[160px]"><NumberInput mode={m} value={null} prefix="$" /></div>
-                <span className="text-[10px] text-fg-muted">{m === 'edit' ? '空白 input' : m === 'disabled' ? 'em dash — + fg-disabled（M24 state > emphasis）' : 'em dash — + fg-muted'}</span>
+                <span className="text-[10px] text-fg-muted">{m === 'edit' ? '空白 input' : m === 'disabled' ? 'hyphen - + fg-disabled（M24 state > emphasis）' : 'hyphen - + foreground'}</span>
               </div>
             ))}
           </div>

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

@@ -1,5 +1,5 @@
 // @principles-rationale: UsageGuidance merges WhenToUse + WhenNotToUse into single 使用指引 story per refactor task (2026-04-26)
-// @story-baseline: packages/design-system/src/components/DataTable/data-table.stories.tsx#NumberAlignment
+// @story-baseline: packages/design-system/src/components/DataTable/data-table.anatomy.stories.tsx#AlignmentRule
 import React from 'react'
 import LinkTo from '@storybook/addon-links/react'
 import type { Meta, StoryObj } from '@storybook/react'

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

@@ -68,7 +68,7 @@ NumberInput 是**數值的**輸入與顯示元件。格式化邏輯：`toLocaleS
 `<NumberInput mode="display">` 在 table cell 和 Form readonly 共用 `formatNumber()` 格式化函式。
 
 - 有值：格式化輸出（prefix + localized number + suffix）
-- null / undefined：`—`（em dash），`text-fg-muted`
+- null / undefined：半形 `-`（hyphen），`text-foreground`（disabled → fg-disabled）
 
 ## DataTable 整合
 
@@ -105,11 +105,11 @@ col.accessor('price', {
 
 - **Disabled**:由 Field SSOT own(`Field/field-controls.spec.md` State machine 段)。視覺:wrapper bg → `bg-disabled`(neutral-2,`semantic.css` `--bg-disabled`)、formatted text → `text-fg-disabled`(M24 state>emphasis)。Display mode + disabled 維持格式化輸出但 token 切 disabled。
 - **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。
+- **Empty(null / undefined / 空字串)**:Display / readonly mode 渲半形 `-`(hyphen + `text-foreground`,disabled → fg-disabled);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"` + wrapper `border-error`(hover 時 `border-error-hover`)+ 下方 error message)。
-- **輸入中間態**(`-`、`1.`、`0.0` 等 parse 後 lossy 的 raw 字串,2026-07-05 D4 codify):edit mode 以 internal draft string 承載——輸入期間 DOM 顯示 draft 原字串(負號、尾點不被 controlled 回寫吃掉),parse 成功即時同步 `onChange(parsed)`;blur / Enter commit(清 draft、顯示回 committed value,不合法殘字自然還原)、Escape 棄 draft(對齊 form-validation 規則 4)。value 面語意不變:`''` / `'-'` 視為 `null`。對齊 Ant InputNumber / Adobe Spectrum NumberField internal draft canonical。 <!-- @benchmark-unverified -->
+- **輸入中間態**(`-`、`1.`、`0.0` 等 parse 後 lossy 的 raw 字串,2026-07-05 D4 codify):edit mode 以 internal draft string 承載——輸入期間 DOM 顯示 draft 原字串(負號、尾點不被 controlled 回寫吃掉),parse 成功即時同步 `onChange(parsed)`;blur / Enter commit(清 draft、顯示回 committed value,不合法殘字自然還原)、Escape 棄未提交 draft 字串、顯示回 committed value(NumberInput 為 live-commit,每次合法 parse 即 onChange,故非回復 pre-edit 原值;真 revert 需另存 snapshot,屬 API 擴充)。value 面語意不變:`''` / `'-'` 視為 `null`。對齊 Ant InputNumber / Adobe Spectrum NumberField internal draft canonical。 <!-- @benchmark-unverified -->
 - **負數 / 超大數字**:`toLocaleString(locale)` 自動處理負號與千分位分組,無特殊 prop。
-- **科學記號輸入**(`1e5`):`Number(raw)` parse 為 `100000`,非 NaN 即觸發 `onChange`(`number-input.tsx:136-138`)。
+- **科學記號輸入**(`1e5`):`Number(raw)` parse 為 `100000`,非 NaN 即觸發 `onChange`(`number-input.tsx:150-152`)。
 - **精度上限**:`precision` > 6 為禁止事項(浮點精度雜訊),極端精度走 `Input` + 自驗證。
 - **RTL**:未實作方向鏡像(edit 靠左 / table cell 靠右皆以 LTR 設計);RTL 屬 DS-wide 決策,未定(與 Chip / Breadcrumb 同口徑)。
 - **Dark mode / density**:走 Field SSOT,不獨立 own。

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

@@ -1,9 +1,10 @@
 import * as React from 'react'
 import { type VariantProps } from 'class-variance-authority'
 import { cn } from '@/lib/utils'
-import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
+import type { FieldMode, FieldVariant, FieldVariantInternal } from '@/design-system/components/Field/field-types'
 import type { InlineActionConfig } from '@/design-system/patterns/element-anatomy/item-anatomy'
-import { fieldWrapperStyles, bareInputStyles, EMPTY_DISPLAY } from '@/design-system/components/Field/field-wrapper'
+import { fieldWrapperStyles, bareInputStyles } from '@/design-system/components/Field/field-wrapper'
+import { useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
 import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid } from '@/design-system/components/Field/field-context'
 import { ItemInlineAction } from '@/design-system/patterns/element-anatomy/item-anatomy'
 
@@ -38,17 +39,20 @@ function formatNumber(
 // ── Types ───────────────────────────────────────────────────────────────────
 
 export interface NumberInputProps
-  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'value' | 'onChange' | 'type'>,
-    Omit<VariantProps<typeof fieldWrapperStyles>, 'mode' | 'variant'>,
+  // `defaultValue` 一併 Omit(2026-07-14 dim-26):number-input.spec.md「controlled-only,不支援
+  // defaultValue」宣稱的型別面機械封鎖 — 原本仍在型別 surface 且經 {...props} spread 到已
+  // controlled 的 input(React value/defaultValue dev warning)。與 LinkInput(link-input.tsx)同款。
+  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size' | 'value' | 'defaultValue' | 'onChange' | 'type'>,
+    Omit<VariantProps<typeof fieldWrapperStyles>, 'mode' | 'variant' | 'width'>,
     NumberFormatOptions {
   /** Field display mode */
   mode?: FieldMode
   /**
    * Visual chrome(正交於 mode);Phase B1(2026-05-05)新增。
    * - `'default'`(預設)— 完整 Field wrapper chrome。
-   * - `'bare'` — 透明 variant,hover/focus 才 reveal(Toolbar inline / DataTable cell)。
+   * (2026-07-09 `bare` variant 退役;naked = cell-as-input substrate,@internal)
    *
-   * 透傳:在 `<Field variant="bare">` 內自動繼承 context.variant;per-prop override context。
+   * 透傳:在 `<Field variant="default">` 內自動繼承 context.variant;per-prop override context。
    */
   variant?: FieldVariant
   /** Error 狀態（正交於 mode）。 */
@@ -102,16 +106,19 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
     const size = useResolvedFieldSize(sizeProp)
     const disabled = useResolvedFieldDisabled(disabledProp)
     // chrome 透傳:per-prop override context;context 沒值則 'default'
-    const variant: FieldVariant = useResolvedFieldVariant(variantProp)
+    const variant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
     // 2026-06-08 SSOT:mode 經 useResolvedFieldMode 統一解析(prop > 有效 disabled > fieldCtx.mode > readOnly > 'edit')
     const resolvedMode: FieldMode = useResolvedFieldMode({ mode: modeProp, disabled, readOnly })
+    const emptyDisplay = useFieldEmptyDisplay()
 
     // 2026-07-05 D4 draft state:controlled value 回寫會吃掉輸入中間態('-'、'1.'、'0.0' 等
     // parse 後 lossy 的 raw 字串)— 例:已有值 5 全選打「-」→ onChange(null) 回寫把 DOM 重設
     // 為空,負號被吃、無法打出 -5。修法對齊 Ant InputNumber / Adobe Spectrum NumberField 的
     // internal draft string canonical:輸入期間 DOM 顯示以 local draft 優先,parse 成功即時同步
-    // onChange(parsed);blur / Enter commit 清 draft 回 value 顯示;Escape 一併棄 draft(對齊
-    // form-validation 規則 4 回復原值)。宣告於 non-edit early return 之前(Rules-of-Hooks,
+    // onChange(parsed);blur / Enter commit 清 draft、顯示回 committed value;Escape 棄未提交
+    // raw draft 字串、顯示回 committed value(NumberInput 為 live-commit:每次合法 parse 即
+    // onChange,故非回復 pre-edit 原值 — 真 revert 需另存 pre-edit snapshot,屬 API 擴充)。
+    // 宣告於 non-edit early return 之前(Rules-of-Hooks,
     // 同 LinkInput 2026-07-04 修法)。
     const [draft, setDraft] = React.useState<string | null>(null)
 
@@ -126,11 +133,11 @@ const NumberInput = React.forwardRef<HTMLInputElement, NumberInputProps>(
             className={cn(
               'flex-1 min-w-0',
               resolvedMode === 'disabled' && 'text-fg-disabled cursor-not-allowed',
-              // 2026-05-31 M24:disabled > muted。disabled 時不可再套 muted(否則 neutral-7 蓋過 disabled neutral-6)
-              value == null && resolvedMode !== 'disabled' && 'text-fg-muted',
+              // 2026-07-09 空值符號前景 + M24:fieldEmptyColorClass = disabled→fg-disabled / else→foreground(同 readonly value 色)
+              value == null && fieldEmptyColorClass(resolvedMode),
             )}
           >
-            {value == null ? EMPTY_DISPLAY : formatNumber(value, { precision, prefix, suffix, locale })}
+            {value == null ? emptyDisplay : formatNumber(value, { precision, prefix, suffix, locale })}
           </span>
         </div>
       )

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

@@ -15,11 +15,11 @@ import { Tag } from '@/design-system/components/Tag/tag'
 import { Avatar } from '@/design-system/components/Avatar/avatar'
 import { ProfileCard, ProfileCardDefaultActions } from '@/design-system/components/ProfileCard/profile-card'
 
-const personHover = (name: string) => (
+const personHover = (name: string, src?: string) => (
   <ProfileCard
     name={name}
     subtitle="Design｜D-0042｜EMP-1001"
-    avatar={{ alt: name }}
+    avatar={{ src, alt: name }}
     status="online"
     statusMessage="Out of Office: Back on Monday."
     actions={<ProfileCardDefaultActions />}
@@ -31,6 +31,8 @@ const personHover = (name: string) => (
   />
 )
 const P = { A: 'Alan Chen', B: 'Betty Wu', C: 'Charlie Lee' } as const
+// 真實人像(2026-07-08 sweep):u=EMP-100x 對齊 dialog.stories.tsx MEMBERS 同名人物(跨 story 同人同照)
+const P_SRC = { A: 'https://i.pravatar.cc/48?u=EMP-1001', B: 'https://i.pravatar.cc/48?u=EMP-1002', C: 'https://i.pravatar.cc/48?u=EMP-1003' } as const
 import { H3, Desc, Td, Th, Swatch } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
 
 const meta: Meta = {
@@ -322,11 +324,11 @@ function OverflowInspector() {
               </tr>
               <tr>
                 <Td mono>openDelay</Td>
-                <Td mono>500ms（HOVER_DELAY_PLAIN_MS）</Td>
+                <Td mono>500ms（MOTION_DELAY_PLAIN_MS）</Td>
               </tr>
               <tr>
                 <Td mono>closeDelay</Td>
-                <Td mono>200ms（HOVER_DELAY_CLOSE_MS）</Td>
+                <Td mono>200ms（MOTION_DELAY_CLOSE_MS）</Td>
               </tr>
             </tbody>
           </table>
@@ -489,9 +491,9 @@ export const SizeMatrix: Story = {
                 <Td mono>sm</Td>
                 <Td>
                   <div className="flex items-center">
-                    <Avatar alt={P.A} color="indigo" size={20} hoverCard={personHover(P.A)} />
+                    <Avatar src={P_SRC.A} alt={P.A} color="indigo" size={20} hoverCard={personHover(P.A, P_SRC.A)} />
                     <span className="-ml-1.5">
-                      <Avatar alt={P.B} color="magenta" size={20} hoverCard={personHover(P.B)} />
+                      <Avatar src={P_SRC.B} alt={P.B} color="magenta" size={20} hoverCard={personHover(P.B, P_SRC.B)} />
                     </span>
                     <span className="-ml-1.5">
                       <OverflowIndicator count={3} shape="circle" size="sm">
@@ -519,7 +521,7 @@ export const SizeMatrix: Story = {
                 <Td mono>md</Td>
                 <Td>
                   <div className="flex items-center">
-                    <Avatar alt={P.A} color="indigo" size={24} hoverCard={personHover(P.A)} />
+                    <Avatar src={P_SRC.A} alt={P.A} color="indigo" size={24} hoverCard={personHover(P.A, P_SRC.A)} />
                     <span className="-ml-1.5">
                       <OverflowIndicator count={4} shape="circle" size="md">
                         <div className="p-1 text-caption">…</div>
@@ -543,7 +545,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 是 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>
+      <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/aria-haspopup——無 activation 行為的宣告是對 AT 空承諾，2026-07-14 對齊 Avatar hoverCard canonical 拆除；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

@@ -43,10 +43,10 @@ export const UsageGuidance: Story = {
       <div className="prose prose-sm max-w-prose">
       <p>處理超出空間的 2 種策略:</p>
       <ul>
-        <li><strong>OverflowIndicator(本元件)</strong>—展示已知數量的 collapse;「我有 N 個 item,看不下去」+1 visual,點開展開或 expand</li>
-        <li><strong>ScrollArea</strong>—未知數量或極多 item 時 scroll;讓使用者捲動瀏覽全部</li>
+        <li><strong>OverflowIndicator(本元件)</strong>—項目數量已知且不多時,顯示前幾個、其餘折成 <code>+N</code>,點開看完整清單</li>
+        <li><strong>ScrollArea</strong>—項目數量未知或極多時,讓使用者捲動瀏覽全部</li>
       </ul>
-      <p className="text-fg-muted">判斷:item 數可數且少(≤ 100)→ OverflowIndicator;太多或不知數 → ScrollArea。</p>
+      <p className="text-fg-muted">判斷:項目數可數且少(≤ 100)→ OverflowIndicator;太多或未知數量 → ScrollArea。</p>
     </div>
     </div>
   ),

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

@@ -23,7 +23,7 @@ OverflowIndicator 是 **`+N` 溢出指示器 + HoverCard 顯示隱藏內容**—
 
 ## 何時用 / 何時不用
 
-**OverflowIndicator 是 internal primitive**——由需要處理「溢出 +N」的元件消費，不直接使用。
+**OverflowIndicator 是 internal primitive**——不進 root barrel front-door、不裸用；由需要處理「溢出 +N」的元件消費；consumer 需要時可經 per-component subpath 包裝並自行確認後使用（`.claude/rules/ui-development.md`「Root barrel front-door 排除」SSOT，internal ≠ 禁用）。
 
 | 場景 | 正確做法 |
 |------|---------|
@@ -45,6 +45,8 @@ OverflowIndicator 是 **`+N` 溢出指示器 + HoverCard 顯示隱藏內容**—
 
 Tooltip 純文字、不可互動、滑鼠離開 trigger 即消失——不適合承載這些需求。
 
+**注意**:浮層內互動(tag dismiss / nested ProfileCard)為**滑鼠增強**——Radix HoverCard content 鍵盤不可達(見「A11y 預設」鍵盤限制),鍵盤等效操作由主列可見項承擔,勿把唯一操作入口放在浮層內。
+
 ### trigger 不用 Tag 元件
 
 Tag 內建 truncation Tooltip 會跟 OverflowIndicator 的 HoverCard 衝突。改用 `tagVariants` 直接套樣式，保持視覺一致但不含 Tag 的額外行為。
@@ -120,7 +122,7 @@ OverflowIndicator 是 **composite**(HoverCard trigger + tag-styled `+N` span + H
 
 **ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。
 
-**互動行為**:trigger 為 `+N` 計數 span,**keyboard-focusable**(`tabIndex=0` + `role="button"` + `aria-haspopup="dialog"`,對齊 Avatar hoverCard canonical),HoverCard 在 hover 或 trigger 取得 focus 時自動展開——無「按 Enter 開選單」的鍵盤指令,也沒有 click 切換。(2026-06-01 #13:原設計純 passive 不可聚焦 → 鍵盤使用者無法開啟 HoverCard 看溢出內容,違 WCAG 2.1.1;改 focusable)
+**互動行為**:trigger 為 `+N` 計數 span,**keyboard-focusable**(`tabIndex=0`;**不掛 `role="button"` / `aria-haspopup`**——2026-07-14 對齊 Avatar hoverCard canonical 2026-07-06 拆除:trigger 無 activation 行為,宣告 button/haspopup 卻按 Enter 無反應 = 對 AT 空承諾),HoverCard 在 hover 或 trigger 取得 focus 時自動展開——無「按 Enter 開選單」的鍵盤指令,也沒有 click 切換。(2026-06-01 #13:原設計純 passive 不可聚焦 → 鍵盤使用者無法開啟 HoverCard 看溢出內容,違 WCAG 2.1.1;改 focusable)。**鍵盤限制**:HoverCard 內容(tag dismiss / nested ProfileCard)僅滑鼠可互動——Radix 把 content 內 tabbable node 設 `tabindex="-1"`(hover-card.spec.md「A11y 預設」),鍵盤等效操作由主列可見項承擔。
 
 **Focus**:trigger 是 tab stop(keyboard 可達 + focus-visible ring,讓鍵盤使用者也能 focus 開啟 HoverCard 看溢出內容);HoverCard 內展開的可互動內容(如人員 tag / ProfileCard)由各自的內容元件負責 focus 管理。
 

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

@@ -1,17 +1,19 @@
 import type { Meta, StoryObj } from '@storybook/react'
+import type { ColumnDef } from '@tanstack/react-table'
 import { OverflowIndicator } from './overflow-indicator'
 import { Tag } from '@/design-system/components/Tag/tag'
 import { Avatar } from '@/design-system/components/Avatar/avatar'
+import { DataTable } from '@/design-system/components/DataTable/data-table'
 import { ProfileCard, ProfileCardDefaultActions } from '@/design-system/components/ProfileCard/profile-card'
 
 /** Person avatar hover canonical helper — 對齊 avatar.spec.md DS-wide rule:
  *  person avatar 必 hover → ProfileCard,必含 status / statusMessage / fields / actions / onViewMore
  *  (profile-card.spec.md 重要資訊 canonical;consumer 的 person 資料全備則全 render) */
-const personHoverCard = (p: { name: string; role?: string; empId?: string }) => (
+const personHoverCard = (p: { name: string; role?: string; empId?: string; avatarUrl?: string }) => (
   <ProfileCard
     name={p.name}
     subtitle={p.role ? `${p.role}｜${p.empId ?? 'EMP-0000'}` : 'Design｜D-0042｜EMP-1001'}
-    avatar={{ alt: p.name }}
+    avatar={{ src: p.avatarUrl, alt: p.name }}
     status="online"
     statusMessage="Out of Office: Back on Monday! For urgent matters please contact @Wei-Lun Cheng in the meantime."
     actions={<ProfileCardDefaultActions />}
@@ -81,13 +83,15 @@ export const ComboboxTagOverflow: Story = {
    Story 2:Avatar 人員 stack +N(shape="circle")
    ═══════════════════════════════════════════════════════════════════════════ */
 
+// 真實人像(2026-07-08 sweep):固定 u= key 保 determinism;中文名用拼音 key,跨 story 同人同照
+// (對齊 hover-card.stories / selection-item.stories 同名人物)
 const reviewers = [
-  { name: 'Ada Chen', color: 'indigo' as const },
-  { name: '張美真', color: 'magenta' as const },
-  { name: '林伯彥', color: 'green' as const },
-  { name: '黃怡君', color: 'turquoise' as const },
-  { name: '王文彬', color: 'purple' as const },
-  { name: '李思妤', color: 'yellow' as const },
+  { name: 'Ada Chen', color: 'indigo' as const, avatarUrl: 'https://i.pravatar.cc/48?u=ada-chen' },
+  { name: '張美真', color: 'magenta' as const, avatarUrl: 'https://i.pravatar.cc/48?u=zhang-meizhen' },
+  { name: '林伯彥', color: 'green' as const, avatarUrl: 'https://i.pravatar.cc/48?u=lin-boyan' },
+  { name: '黃怡君', color: 'turquoise' as const, avatarUrl: 'https://i.pravatar.cc/48?u=huang-yijun' },
+  { name: '王文彬', color: 'purple' as const, avatarUrl: 'https://i.pravatar.cc/48?u=wang-wenbin' },
+  { name: '李思妤', color: 'yellow' as const, avatarUrl: 'https://i.pravatar.cc/48?u=li-siyu' },
 ]
 
 export const AvatarStackOverflow: Story = {
@@ -100,7 +104,7 @@ export const AvatarStackOverflow: Story = {
       <div className="flex items-center">
         {reviewers.slice(0, 3).map((p, i) => (
           <span key={p.name} className={i > 0 ? '-ml-1.5' : ''}>
-            <Avatar alt={p.name} color={p.color} size={24} hoverCard={personHoverCard(p)} />
+            <Avatar src={p.avatarUrl} alt={p.name} color={p.color} size={24} hoverCard={personHoverCard(p)} />
           </span>
         ))}
         <span className="-ml-1.5">
@@ -108,7 +112,7 @@ export const AvatarStackOverflow: Story = {
             <div className="flex flex-col gap-1 min-w-[160px] text-caption">
               {reviewers.slice(3).map((p) => (
                 <div key={p.name} className="flex items-center gap-2">
-                  <Avatar alt={p.name} color={p.color} size={20} hoverCard={personHoverCard(p)} />
+                  <Avatar src={p.avatarUrl} alt={p.name} color={p.color} size={20} hoverCard={personHoverCard(p)} />
                   <span>{p.name}</span>
                 </div>
               ))}
@@ -163,76 +167,80 @@ const rows = [
   {
     title: '登入頁改版',
     assignees: [
-      { name: 'Ada Chen', color: 'indigo' as const },
-      { name: '張美真', color: 'magenta' as const },
+      { name: 'Ada Chen', color: 'indigo' as const, avatarUrl: 'https://i.pravatar.cc/48?u=ada-chen' },
+      { name: '張美真', color: 'magenta' as const, avatarUrl: 'https://i.pravatar.cc/48?u=zhang-meizhen' },
     ],
   },
   {
     title: 'Stripe 金流串接',
     assignees: [
-      { name: '林伯彥', color: 'green' as const },
-      { name: '黃怡君', color: 'turquoise' as const },
-      { name: '王文彬', color: 'purple' as const },
-      { name: '李思妤', color: 'yellow' as const },
-      { name: '吳冠霆', color: 'red' as const },
+      { name: '林伯彥', color: 'green' as const, avatarUrl: 'https://i.pravatar.cc/48?u=lin-boyan' },
+      { name: '黃怡君', color: 'turquoise' as const, avatarUrl: 'https://i.pravatar.cc/48?u=huang-yijun' },
+      { name: '王文彬', color: 'purple' as const, avatarUrl: 'https://i.pravatar.cc/48?u=wang-wenbin' },
+      { name: '李思妤', color: 'yellow' as const, avatarUrl: 'https://i.pravatar.cc/48?u=li-siyu' },
+      { name: '吳冠霆', color: 'red' as const, avatarUrl: 'https://i.pravatar.cc/48?u=wu-guanting' },
     ],
   },
   {
     title: '行銷活動著陸頁',
     assignees: [
-      { name: '蔡佳芸', color: 'blue' as const },
-      { name: '陳俊宇', color: 'purple' as const },
-      { name: '周思涵', color: 'magenta' as const },
+      { name: '蔡佳芸', color: 'blue' as const, avatarUrl: 'https://i.pravatar.cc/48?u=tsai-chiayun' },
+      { name: '陳俊宇', color: 'purple' as const, avatarUrl: 'https://i.pravatar.cc/48?u=chen-chunyu' },
+      { name: '周思涵', color: 'magenta' as const, avatarUrl: 'https://i.pravatar.cc/48?u=chou-szuhan' },
     ],
   },
 ]
 
+// 2026-07-14 audit(R1 A.2):手刻 table markup → 消費真 <DataTable>(對齊 ProgressBar
+// InlineTableCell 同款 consumer-自訂-cell 模式;columns 不設 meta.type 走自訂 cell)。
+
+type AssigneeRow = (typeof rows)[number]
+
+const assigneeColumns: ColumnDef<AssigneeRow>[] = [
+  {
+    id: 'title',
+    header: '任務',
+    cell: ({ row }) => row.original.title,
+  },
+  {
+    id: 'assignees',
+    header: '負責人',
+    meta: { width: 180 },
+    cell: ({ row }) => {
+      const visible = row.original.assignees.slice(0, 2)
+      const hidden = row.original.assignees.slice(2)
+      return (
+        <div className="flex items-center">
+          {visible.map((p, i) => (
+            <span key={p.name} className={i > 0 ? '-ml-1.5' : ''}>
+              <Avatar src={p.avatarUrl} alt={p.name} color={p.color} size={20} hoverCard={personHoverCard(p)} />
+            </span>
+          ))}
+          {hidden.length > 0 && (
+            <span className="-ml-1.5">
+              <OverflowIndicator count={hidden.length} shape="circle" size="sm">
+                <div className="flex flex-col gap-1 min-w-[140px]">
+                  {hidden.map((p) => (
+                    <div key={p.name} className="flex items-center gap-2">
+                      <Avatar src={p.avatarUrl} alt={p.name} color={p.color} size={20} hoverCard={personHoverCard(p)} />
+                      <span>{p.name}</span>
+                    </div>
+                  ))}
+                </div>
+              </OverflowIndicator>
+            </span>
+          )}
+        </div>
+      )
+    },
+  },
+]
+
 export const TableRowAssignees: Story = {
   name: 'DataTable 人員欄位',
   render: () => (
-    <div className="border border-border rounded-md max-w-2xl overflow-hidden">
-      <table className="w-full text-caption">
-        <thead className="bg-muted text-fg-secondary">
-          <tr>
-            <th className="text-left px-3 py-2 font-medium">任務</th>
-            <th className="text-left px-3 py-2 font-medium">負責人</th>
-          </tr>
-        </thead>
-        <tbody>
-          {rows.map((r) => {
-            const visible = r.assignees.slice(0, 2)
-            const hidden = r.assignees.slice(2)
-            return (
-              <tr key={r.title} className="border-t border-divider">
-                <td className="px-3 py-2">{r.title}</td>
-                <td className="px-3 py-2">
-                  <div className="flex items-center">
-                    {visible.map((p, i) => (
-                      <span key={p.name} className={i > 0 ? '-ml-1.5' : ''}>
-                        <Avatar alt={p.name} color={p.color} size={20} hoverCard={personHoverCard(p)} />
-                      </span>
-                    ))}
-                    {hidden.length > 0 && (
-                      <span className="-ml-1.5">
-                        <OverflowIndicator count={hidden.length} shape="circle" size="sm">
-                          <div className="flex flex-col gap-1 min-w-[140px]">
-                            {hidden.map((p) => (
-                              <div key={p.name} className="flex items-center gap-2">
-                                <Avatar alt={p.name} color={p.color} size={20} hoverCard={personHoverCard(p)} />
-                                <span>{p.name}</span>
-                              </div>
-                            ))}
-                          </div>
-                        </OverflowIndicator>
-                      </span>
-                    )}
-                  </div>
-                </td>
-              </tr>
-            )
-          })}
-        </tbody>
-      </table>
+    <div className="max-w-2xl">
+      <DataTable columns={assigneeColumns} data={rows} getRowId={(r) => r.title} height="auto" />
     </div>
   ),
 }