@qijenchen/design-system 0.1.0-beta.82 → 0.1.0-beta.84

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

@@ -6,7 +6,7 @@ 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_PLAIN_MS, HOVER_DELAY_CLOSE_MS } from '@/design-system/tokens/motion/motion'
+import { MOTION_DELAY_PLAIN_MS, MOTION_DELAY_CLOSE_MS } from '@/design-system/tokens/motion/motion'
 
 /**
  * OverflowIndicator — +N 觸發器 + HoverCard 顯示溢出內容
@@ -96,13 +96,16 @@ const OverflowIndicator = React.forwardRef<HTMLSpanElement, OverflowIndicatorPro
   ) {
     if (count <= 0) return null
 
+    // a11y(2026-07-14 dim-6):拆 role="button" + aria-haspopup="dialog" —— trigger 無
+    // activation 行為(無 Enter/Space handler,HoverCard 靠 hover/focus 自動開),宣告了
+    // button/haspopup 卻按 Enter 無反應 = 對 AT 空承諾。對齊 Avatar hoverCard 同款拆除
+    // (avatar.tsx 2026-07-06 + hover-card.spec.md「A11y 預設」:Radix 官方零 role/aria 定位)。
+    // trigger 有可見 "+N" 文字,無需 aria-label / role;保留 tabIndex=0 + focus ring(WCAG 2.1.1)。
     const trigger = shape === 'tag' ? (
       <span
         ref={ref}
         data-overflow-indicator=""
         tabIndex={0}
-        role="button"
-        aria-haspopup="dialog"
         className={cn(tagVariants({ color: 'neutral', size }), 'cursor-pointer focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1', className)}
         {...props}
       >
@@ -113,8 +116,6 @@ const OverflowIndicator = React.forwardRef<HTMLSpanElement, OverflowIndicatorPro
         ref={ref}
         data-overflow-indicator=""
         tabIndex={0}
-        role="button"
-        aria-haspopup="dialog"
         className={cn(
           'shrink-0 rounded-full inline-grid place-content-center',
           'bg-muted text-foreground font-medium leading-none cursor-pointer',
@@ -130,11 +131,11 @@ const OverflowIndicator = React.forwardRef<HTMLSpanElement, OverflowIndicatorPro
     )
 
     // 2026-05-18 fix(per user audit「所有 hovercard 應消費 hover delay token」+ motion.spec.md SSOT):
-    // 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
+    // plain tier(純列表展開、無 fetch)= MOTION_DELAY_PLAIN_MS,per motion.spec.md 對照表 row;
+    // close = MOTION_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_PLAIN_MS} closeDelay={HOVER_DELAY_CLOSE_MS}>
+      <HoverCard openDelay={MOTION_DELAY_PLAIN_MS} closeDelay={MOTION_DELAY_CLOSE_MS}>
         <HoverCardTrigger asChild>
           {trigger}
         </HoverCardTrigger>

package/src/components/Pagination/pagination.spec.md

@@ -64,7 +64,7 @@ Pagination 是「大量資料切成多頁後的位置導覽」——顯示當前
 ```
 
 - **格位配置**:boundary 1 + sibling 1(= MUI `boundaryCount` / `siblingCount` 預設 1/1;內部常數,v1 不開 props——未來若開放,命名必沿用 MUI)。最大格位 = 首尾各 1 + 當前頁左右各 1 + 當前頁 + 2 顆 ellipsis = **7 格**,超過即摺疊。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-- **Ellipsis 非互動**:純指示符號(`MoreHorizontal` icon + `aria-hidden`),不可點——對齊 Ant / MUI / shadcn;Breadcrumb 的可點 ellipsis 是 collapse dropdown 場景,語意不同。
+- **Ellipsis 非互動**:純指示符號(`MoreHorizontal` icon + `aria-hidden`),不可點——對齊 MUI / shadcn(非互動 ellipsis)。**Ant 為可點 jump-5 派**(rc-pagination 預設把省略格渲染成 `jump-prev` / `jump-next`:hover 顯 «/»、click 跳 5 頁,`https://github.com/react-component/pagination`);本 DS 選非互動,快速跳頁留給未來 `showQuickJumper`。Breadcrumb 的可點 ellipsis 是 collapse dropdown 場景,語意不同。
 - **上下頁按鈕**:iconOnly(`ChevronLeft` / `ChevronRight`),在第一頁 / 最後一頁時 `disabled`。
 - 頁碼格位由內部演算法產生;兩顆省略號各自身分穩定,翻頁時不互相 remount(演算法簽名與 React key 等實作細節由 `pagination.tsx` 檔內註解單一持有,spec 不重述——職責分離)。
 

package/src/components/Pagination/pagination.stories.tsx

@@ -18,9 +18,7 @@ export const Default: Story = {
     return (
       <div className="flex flex-col gap-3">
         <p className="text-caption text-fg-muted">
-          客服工單佇列:total=128 / 每頁預設 20 → 7 頁(總頁數由 total/pageSize 內部推導,
-          Ant 同款資料模型)。當前頁 `aria-current="page"`,選中 = 主色描邊+染字不染底;
-          選中之上 hover 升 hover 階、按壓 active 階。
+          客服工單佇列:共 128 筆、每頁 20 筆 → 7 頁。
         </p>
         <Pagination total={128} page={page} onPageChange={setPage} />
       </div>
@@ -36,9 +34,7 @@ export const FullBar: Story = {
     return (
       <div className="flex flex-col gap-3">
         <p className="text-caption text-fg-muted">
-          搜尋結果頁:showTotal(「第 x–y 筆,共 N 筆」range 格式,Ant/MUI/Carbon 共識)+
-          pageSizeOptions(「N 筆/頁」選單)—— 分頁完整功能 own 在本元件(SSOT),layout =
-          資訊左、操作群(頁碼+每頁筆數)右,對齊 Ant 源碼結構;換每頁筆數自動回第 1 頁。
+          搜尋結果頁:顯示總筆數 + 每頁筆數選單,左資訊右操作;換每頁筆數會自動回第 1 頁。
         </p>
         <Pagination
           total={85}

package/src/components/Pagination/pagination.tsx

@@ -172,7 +172,7 @@ const Pagination = React.forwardRef<HTMLElement, PaginationProps>(
               </Button>
             </li>
           ) : (
-            // Ellipsis 純指示不可點(Ant / MUI / shadcn 同);寬度對齊數字鈕保持節奏
+            // Ellipsis 純指示不可點(MUI / shadcn 同;Ant 為可點 jump-5 派,見 spec);寬度對齊數字鈕保持節奏
             <li
               key={slot}
               aria-hidden

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

@@ -66,7 +66,7 @@ export const Overview: Story = {
             <tbody>
               {[
                 ['mode', "'edit' | 'display' | 'readonly' | 'disabled'", "'edit'", 'Field mode'],
-                ['variant', "'default' | 'bare' | 'naked'", "'default'", 'Field chrome variant(對齊 Select / Combobox)'],
+                ['variant', "'default'", "'default'", 'Field chrome variant(對齊 Select / Combobox;naked = @internal cell-as-input,2026-07-14 型別收窄至 FieldVariantInternal)'],
                 ['size', "'sm' | 'md' | 'lg'", "'md'", '對齊 field-height tier'],
                 ['value', 'PersonValue | PersonValue[] | null', '—', '單選 / 多選(類型決定模式)'],
                 ['onChange', '(value: PersonValue[]) => void', '—', '值變更 callback(永遠 emit array)'],
@@ -78,7 +78,7 @@ export const Overview: Story = {
                 ['pillShowAvatar', 'boolean', 'true', "multiDisplay='pill' 時是否顯示 avatar prefix"],
                 ['pillWrap', 'boolean', 'true', 'pill 模式是否允許換行'],
                 ['searchIn', "'menu' | 'trigger'", "'menu'", '搜尋型態(menu 浮層內 / trigger inline;multi 才有意義)'],
-                ['showDisplayEndIcon', 'boolean', 'false', 'display 模式渲 ChevronDown + naked wrapper(DataTable cell 對齊)'],
+                ['showDisplayEndIcon', 'boolean', 'false', 'display 模式渲 ChevronDown + naked wrapper(opt-in 逃生門;2026-07-08 A 案後 DataTable 預設不傳)'],
                 ['defaultOpen', 'boolean', 'false', 'uncontrolled 初始開啟狀態'],
                 ['onOpenChange', '(open: boolean) => void', '—', 'open 狀態變更 callback'],
                 ['disabled', 'boolean', 'false', '停用'],
@@ -97,7 +97,7 @@ 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,切 `variant` 看 default / bare / naked chrome 差異。' } },
+    docs: { description: { story: '右側 Controls 切 props 即時 render,取代 Figma inspect。切 `mode` 看 edit / display / readonly / disabled 視覺差異,切 `size` 對照 field-height tier,切 `variant` 看 default / naked chrome 差異。' } },
   },
   args: {
     mode: 'edit',
@@ -112,7 +112,7 @@ export const Inspector: Story = {
   },
   argTypes: {
     mode: { control: 'radio', options: ['edit', 'display', 'readonly', 'disabled'] },
-    variant: { control: 'radio', options: ['default', 'bare', 'naked'] },
+    variant: { control: 'radio', options: ['default', 'naked'] },
     size: { control: 'radio', options: ['sm', 'md', 'lg'] },
     disabled: { control: 'boolean' },
     showDisplayEndIcon: { control: 'boolean' },

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

@@ -175,13 +175,13 @@ export const EmptyStateRule: Story = {
     <div>
       <Rule
         title="edit 模式 — 未選時顯示「請選擇人員」佔位提示"
-        note="跟 Select / Combobox 的 placeholder 行為一致。不用 em-dash,因為 edit mode 是可操作的"
+        note="跟 Select / Combobox 的 placeholder 行為一致。不用半形連字號,因為 edit mode 是可操作的"
       >
         <PeoplePicker value={null} onChange={() => {}} people={team} />
       </Rule>
 
       <Rule
-        title="readonly — 未填時顯示 em-dash（—）"
+        title="readonly — 未填時顯示半形連字號（-）"
         note="跟所有 Field readonly 空值呈現一致。table cell 場景特別常見(未指派 assignee)"
       >
         <PeoplePicker mode="readonly" value={null} />

package/src/components/PeoplePicker/people-picker.spec.md

@@ -76,7 +76,7 @@ Multi mode 公開 `multiDisplay` / `pillShowAvatar` / `pillWrap` 三個顯示 pr
 
 PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為人員清單通常規模較大且使用者記得人名關鍵字（符合 Select spec「Searchable 開啟判斷」的「label 性質」主判準：人名是獨特關鍵字）。
 
-- **搜尋 placeholder**：預設「搜尋人員…」，可透過 `searchPlaceholder` 覆寫
+- **搜尋 placeholder**：預設「搜尋人員…」，可透過 `searchPlaceholder` 覆寫。**僅 multi 模式 panel-top search（`searchIn='menu'`，default）生效**——single mode wrap `<Select searchable>` 走 inline-trigger 搜尋，提示取自 `placeholder`（Select 無 searchPlaceholder prop）；multi `searchIn='trigger'` inline 搜尋同理走 placeholder 規則（見「Trigger display SSOT canonical table」§E）
 - **空狀態**：預設「沒有符合的人員」，透過 `emptyText` 覆寫
 
 ---
@@ -96,8 +96,8 @@ PeoplePicker 永遠支援搜尋（內部使用 `Command` / cmdk）——因為
 | 型態 | 使用情境 | 元件 API |
 |---|---|---|
 | **none** | 短列表 (< 7 選項) / 自然語言 label 可用 native type-ahead | 不傳 `searchable` |
-| **inline-trigger** | 單選 + 需快速 type-and-pick;trigger 變 input | `<Select searchable />` / `<Combobox searchable searchIn='trigger' />` / `<PeoplePicker />` single / `<PeoplePicker multi searchIn='trigger' />` |
-| **panel-top** | 多選 + 連續 type-and-select(關鍵字保留在 menu 不被 chip 切走) | `<Combobox searchable searchIn='menu' />` / `<PeoplePicker multi />`(default menu) |
+| **inline-trigger** | 單選 + 需快速 type-and-pick;trigger 變 input | `<Select searchable />` / `<Combobox searchable searchIn='trigger' />` / `<PeoplePicker value={person} />`(single = value 非陣列)/ `<PeoplePicker value={[...]} searchIn='trigger' />`(multi opt-in;無 `multi` prop — 單/多選由 value 是否為陣列決定,見「單選 vs 多選」)|
+| **panel-top** | 多選 + 連續 type-and-select(關鍵字保留在 menu 不被 chip 切走) | `<Combobox searchable searchIn='menu' />` / `<PeoplePicker value={[...]} />`(multi default menu)|
 
 ### Trigger display SSOT canonical table(2026-05-15 v3 user verbatim 整理)
 
@@ -209,8 +209,8 @@ interface PersonData {
 ## readonly / disabled
 
 與其他 Field 一致：
-- **readonly**：顯示選中人員（Avatar + Name），無 dropdown trigger、無搜尋
-- **disabled**：灰化整個 field，不可互動
+- **readonly**：顯示選中人員（Avatar + Name），無 dropdown trigger、無搜尋；avatar hover ProfileCard 保留（純展示仍可查閱人員資訊）
+- **disabled**：灰化整個 field，不可互動——含 avatar dim（host-controlled opacity）+ 抑制 avatar ProfileCard hoverCard（無 HoverCard wrapper / 無 tab stop；2026-07-14 修，原 hoverCard 未抑制 falsify「不可互動」）
 
 ---
 
@@ -237,7 +237,7 @@ PeoplePicker 是 **composite Field Control**(Field shell + Avatar + SelectMenu),
 
 ## shadcn passthrough 例外說明
 
-PeoplePicker 是 **composite 元件**(內部 wrap `<Select>`(single)/ `<Combobox>`(multi)),其主 API 為 declarative(value / onChange / size / mode / options...)。**有套 `forwardRef` + HTML root props spread**(codex P2 fix 2026-05-07 v15.10,`people-picker.tsx:111` / L53 / L131 `...rest`):
+PeoplePicker 是 **composite 元件**(內部 wrap `<Select>`(single)/ `<Combobox>`(multi)),其主 API 為 declarative(value / onChange / size / mode / people...)。**有套 `forwardRef` + HTML root props spread**(codex P2 fix 2026-05-07 v15.10,`people-picker.tsx:111` / L53 / L131 `...rest`):
 
 - **forwardRef + 單一 root**:`PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'>`,ref 與 `...rest`(`id` / `data-testid` / `onBlur` / `onFocus` / `aria-*` 等 HTML root props)forward 到內部 trigger 容器(readonly/disabled root div、或 wrapped Select / Combobox 的 root),對齊 DS 既有 Combobox / Select 慣例
 - **`onChange` 走 Omit**:本元件 onChange 用 `(value: PersonValue[]) => void` custom signature,跟 HTMLAttributes onChange 衝突,故 Omit

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

@@ -4,20 +4,29 @@
 import * as React from 'react'
 import { ChevronDown } from 'lucide-react'
 import { cn } from '@/lib/utils'
-import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
-import { fieldWrapperStyles, EMPTY_DISPLAY, nakedCellRowModeAlign } from '@/design-system/components/Field/field-wrapper'
+import type { FieldMode, FieldVariant, FieldVariantInternal, FieldWidth } from '@/design-system/components/Field/field-types'
+import { fieldWrapperStyles, nakedCellRowModeAlign } from '@/design-system/components/Field/field-wrapper'
+import { useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
 import { ItemSuffix } from '@/design-system/patterns/element-anatomy/item-anatomy'
 import { useFieldSurface, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant } from '@/design-system/components/Field/field-context'
 import { Avatar } from '@/design-system/components/Avatar/avatar'
 import { Tag } from '@/design-system/components/Tag/tag'
-import { Select } from '@/design-system/components/Select/select'
-import { Combobox } from '@/design-system/components/Combobox/combobox'
+import { Select as SelectPublic } from '@/design-system/components/Select/select'
+import { Combobox as ComboboxPublic } from '@/design-system/components/Combobox/combobox'
 import { PersonDisplay, MultiPersonDisplay, PersonAvatarTag, buildPersonProfileCard, resolvePerson, type PersonValue } from './person-display'
 import {
   getAvatarStackVisibleCount,
   AVATAR_STACK_AVATAR_PX,
   AVATAR_STACK_OVERFLOW_CHIP_PX,
 } from './avatar-stack-overflow'
+import type { WithFieldVariantInternal } from '@/design-system/components/Field/field-types'
+
+// ── @internal naked variant forward 通道(2026-07-14 API 策展 E)──────────────────────────
+// naked 已從公開 FieldVariant 拆出(field-types.ts FieldVariantInternal)。PeoplePicker 是
+// Select / Combobox 的 wrapper:cell-registry 傳入的 naked 需原樣 forward 給 primitive
+// (M30 wrapper forward 全 primitive surface)。型別層 widen,純型別、零 runtime。
+const Select = SelectPublic as WithFieldVariantInternal<typeof SelectPublic>
+const Combobox = ComboboxPublic as WithFieldVariantInternal<typeof ComboboxPublic>
 // Pure helpers extracted to sibling for file-size budget(2026-05-18,P1 ≤ 500 lines)。
 // 不消費 component closure 的純 constant / 純 mapping function 全部搬走,主檔保留 SSOT-bearing
 // render logic(消費 Combobox / Select / state 等 closure 的部分)。
@@ -55,6 +64,9 @@ export interface PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElem
   mode?: FieldMode
   /** Field chrome variant(對齊 Select / Combobox)*/
   variant?: FieldVariant
+  /** 寬度軸 — `fill` 填滿容器(default)/ `hug` 依內容收縮(value 寬 + slot 寬 + gap + 內 padding);
+   *  chrome 與互動不變。SSOT → field-controls.spec.md「寬度軸(width: fill / hug)」。 */
+  width?: FieldWidth
   size?: 'sm' | 'md' | 'lg'
   /** 當前已選的人(單選 PersonValue,多選 PersonValue[])*/
   value?: PersonValue | PersonValue[] | null
@@ -65,7 +77,10 @@ export interface PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElem
   /** 2026-05-12 Stream C Issue 4 fix(codex Q3 Cluster C):trigger empty placeholder。
    *  Default '請選擇人員'。**禁** 將 `emptyText`(search-empty)當 trigger placeholder 傳。 */
   placeholder?: string
-  /** 搜尋框 placeholder */
+  /** 搜尋框 placeholder — **僅 multi 模式 panel-top search(`searchIn='menu'`,default)生效**。
+   *  single mode wrap `<Select searchable>` 走 inline-trigger 搜尋,提示取自 `placeholder`
+   *  (Select 無 searchPlaceholder prop);multi `searchIn='trigger'` inline 搜尋同理走
+   *  placeholder 規則(spec「Trigger display SSOT canonical table」)。 */
   searchPlaceholder?: string
   /** 搜尋無結果訊息(filtered menu empty)。**僅**用於 SelectMenu `emptyText`(菜單空狀態,
    *  2026-07-04 Q4 接線完成),不轉 trigger placeholder(2026-05-12 Issue 4 semantic fix)。 */
@@ -111,6 +126,7 @@ export interface PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElem
 const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(function PeoplePicker({
   mode: modeProp,
   variant: variantProp,
+  width,
   size: sizeProp,
   value,
   onChange,
@@ -131,11 +147,12 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
   ...rest
 }, ref) {
   const surface = useFieldSurface()
+  const emptyDisplay = useFieldEmptyDisplay()
   const size = useResolvedFieldSize(sizeProp)  // B 組 cascade fix
   const disabled = useResolvedFieldDisabled(disabledProp)
   // 2026-06-08 SSOT:mode/disabled/variant 統一經 helper;修 <Field disabled> 漏 cascade(原只讀 fieldCtx.mode)
   const resolvedMode: FieldMode = useResolvedFieldMode({ mode: modeProp, disabled })
-  const resolvedVariant: FieldVariant = useResolvedFieldVariant(variantProp)
+  const resolvedVariant: FieldVariantInternal = useResolvedFieldVariant(variantProp)
   const isMulti = Array.isArray(value)
   const isEmpty = !value || (isMulti && value.length === 0)
 
@@ -195,7 +212,7 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
   // 與 edit (Select / Combobox wrapped) 同 DOM 結構消除 cell display↔edit 像素偏移。
   if (resolvedMode === 'display') {
     if (!showDisplayEndIcon) {
-      if (isEmpty) return <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+      if (isEmpty) return <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>
       return isMulti
         ? <MultiPersonDisplay value={value as PersonValue[]} size={size} measured />
         : <PersonDisplay value={value as PersonValue} size={size} />
@@ -204,12 +221,12 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
   const iconSize = ICON_SIZE[size as 'sm' | 'md' | 'lg']
     return (
       <div
-        className={cn(fieldWrapperStyles({ mode: 'display', variant: resolvedVariant, size }), className)}
+        className={cn(fieldWrapperStyles({ mode: 'display', variant: resolvedVariant, width, size }), className)}
         data-field-mode="display"
       >
         <span className={cn('flex-1 min-w-0 inline-flex items-center', nakedCellRowModeAlign)}>
           {isEmpty
-            ? <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+            ? <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>
             : isMulti
               ? <MultiPersonDisplay value={value as PersonValue[]} size={size} measured />
               : <PersonDisplay value={value as PersonValue} size={size} />}
@@ -226,18 +243,20 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
     return (
       <div
         ref={ref}
-        className={cn(fieldWrapperStyles({ mode: resolvedMode, variant: resolvedVariant, size }), className)}
+        className={cn(fieldWrapperStyles({ mode: resolvedMode, variant: resolvedVariant, width, size }), className)}
         data-field-mode={resolvedMode}
         aria-disabled={resolvedMode === 'disabled' ? true : undefined}
         aria-label={ariaLabel}
         {...rest}
       >
         <span className={cn('flex-1 min-w-0 inline-flex items-center', nakedCellRowModeAlign, resolvedMode === 'disabled' && 'text-fg-disabled')}>
+          {/* 2026-07-14 deep-audit 修:disabled 傳入 → 抑制 Avatar ProfileCard hoverCard + avatar dim
+              (spec「disabled:灰化整個 field,不可互動」原被 hoverCard falsify);readonly 保留 hoverCard(純展示仍可查閱) */}
           {isEmpty
-            ? <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+            ? <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>
             : isMulti
-              ? <MultiPersonDisplay value={value as PersonValue[]} size={size} measured />
-              : <PersonDisplay value={value as PersonValue} size={size} />}
+              ? <MultiPersonDisplay value={value as PersonValue[]} size={size} measured disabled={resolvedMode === 'disabled'} />
+              : <PersonDisplay value={value as PersonValue} size={size} disabled={resolvedMode === 'disabled'} />}
         </span>
         {/* 2026-06-26 類型身份 indicator:edit 顯示 / readonly 不顯示 / disabled 保留(fg-disabled,對齊原生 <select disabled>);naked cell 依 showDisplayEndIcon */}
         {(resolvedVariant === 'naked' ? showDisplayEndIcon : resolvedMode === 'disabled') && (
@@ -258,6 +277,9 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
     return (
       <Select
         ref={ref as React.Ref<HTMLDivElement>}
+        // 2026-07-14 deep-audit fix:width 補 forward(原漏傳 → single edit path 忽略公開 width prop;
+        // multi pill / stack 皆有傳,對齊 M30 wrapper forward 全 primitive surface)
+        width={width}
         size={size}
         variant={resolvedVariant}
         options={people.map(personToSelectOption)}
@@ -273,9 +295,11 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
         className={className}
         aria-label={ariaLabel}
         selectedItemRenderer={(opt) => <PersonDisplay value={findPerson(people, opt.value)} size={size} />}
-        // **codex P2 forward**:Select extends `SelectHTMLAttributes<HTMLSelectElement>`,
-        // event handler element 型別跟 PeoplePicker `HTMLAttributes<HTMLDivElement>` 不一致
-        // (`onCopy` / `onChange` 等)。Runtime spread 等效 — DOM 收到 attrs 不挑剔。
+        // **codex P2 forward**:Select 原生屬性走 allowlist(`Pick<SelectHTMLAttributes>`,
+        // 2026-07-14 API 策展 D,見 select.tsx SelectProps docblock),event handler element
+        // 型別跟 PeoplePicker `HTMLAttributes<HTMLDivElement>` 不一致(`onCopy` / `onChange` 等)。
+        // Runtime spread 等效 — DOM 收到 attrs 不挑剔(非 allowlist attrs 落 CustomSelect rest,
+        // 續 spread 到 trigger div,runtime 行為不變)。
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         // any-allow: rest 含 `onChange: FormEventHandler` 跟 Select onChange signature 衝突 — DOM runtime spread 安全(per codex P2 forward)
         {...(rest as any)}
@@ -290,6 +314,7 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
     }
     return (
       <Combobox
+        width={width}
         ref={ref as React.Ref<HTMLDivElement>}
         size={size}
         variant={resolvedVariant}
@@ -297,6 +322,9 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
         value={selectedNames}
         onChange={handleMultiChange}
         searchable
+        // 2026-07-14 deep-audit fix:searchIn 補 forward(原漏傳 → pill 模式永遠 Combobox default 'menu',
+        // documented multi opt-in `searchIn='trigger'` silently 無效;stack branch 已傳,對齊 M30 forward 全 surface)
+        searchIn={searchIn}
         searchPlaceholder={searchPlaceholder}
         // 2026-05-12 Stream C Issue 4(codex Q3):placeholder = trigger empty hint('請選擇人員')
         // — semantic clean separation。2026-07-04 Q4 拍板完成 1-cycle 承諾:emptyPlaceholder forward
@@ -353,6 +381,7 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
 
   return (
     <Combobox
+      width={width}
       ref={mergedStackRef}
       size={size}
       variant={resolvedVariant}
@@ -472,3 +501,14 @@ export const peoplePickerMeta = {
 } as const
 
 export { PeoplePicker }
+// 2026-07-10 C14 export 缺口修(R2 同類:定義存在但無 export 面,consumer 想守 PersonValue 鏈
+// import 不到 → 被逼手刻)。person-display 表面隨 PeoplePicker subpath + root barrel 一併公開。
+export {
+  PersonDisplay,
+  MultiPersonDisplay,
+  PersonAvatarTag,
+  buildPersonProfileCard,
+  resolvePerson,
+  type PersonValue,
+  type PersonData,
+} from './person-display'

package/src/components/PeoplePicker/person-display.tsx

@@ -1,7 +1,8 @@
 // @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 { X } from 'lucide-react'
-import { EMPTY_DISPLAY } from '@/design-system/components/Field/field-wrapper'
+import { cn } from '@/lib/utils'
+import { useFieldEmptyDisplay } from '@/design-system/components/Field/field-context'
 import { Tag } from '@/design-system/components/Tag/tag'
 import { OverflowIndicator } from '@/design-system/components/OverflowIndicator/overflow-indicator'
 import { Avatar } from '@/design-system/components/Avatar/avatar'
@@ -16,10 +17,11 @@ import {
 
 // ── Types ───────────────────────────────────────────────────────────────────
 
-// PersonData 承載 ProfileCard 所需的完整資訊。DS 全域 person avatar 的 hoverCard ProfileCard 永遠
-// 顯示同一組 sections(name + subtitle + status + 4 default fields + 自訂 fields + actions + View more)
-// — 缺資料顯 placeholder,不會 collapse。對齊 avatar.spec.md「person avatar hover → ProfileCard」
-// DS-wide canonical(2026-05-06 v11 always-render schema 升級)。
+// PersonData 承載 ProfileCard 所需的完整資訊。DS 全域 person avatar 的 hoverCard ProfileCard 顯示
+// 同一組 sections(name + subtitle + status + 2 default fields(id + employeeNumber,見下方
+// NAMECARD_DEFAULT_FIELD_KEYS 對齊註解)+ 自訂 fields + actions + View more)— 缺資料顯 placeholder;
+// **例外:status undefined 時整 status block 省略(collapse,= loading transient,見 status jsDoc)**。
+// 對齊 avatar.spec.md「person avatar hover → ProfileCard」DS-wide canonical。
 export interface PersonData {
   name: string
   avatarUrl?: string
@@ -109,23 +111,30 @@ function PersonAvatar({
   size = 'md',
   className = '',
   style,
+  disabled = false,
 }: {
   person: PersonData
   size?: 'sm' | 'md' | 'lg'
   className?: string
   style?: React.CSSProperties
+  /** disabled field context(2026-07-14 deep-audit 修):抑制 ProfileCard hoverCard(Avatar 收
+   *  undefined → 無 HoverCard wrapper / 無 tabIndex,真不可互動)+ avatar 自身 dim(host-controlled
+   *  opacity — avatar.spec.md「Avatar 在 disabled 元件內 host-controlled opacity」canonical;
+   *  PeoplePicker disabled 分支無 fieldCtx,Avatar self-dim 搆不到,host 補)。
+   *  對齊 people-picker.spec.md「disabled:灰化整個 field,不可互動」。 */
+  disabled?: boolean
 }) {
   const isTableScrolling = useTableIsScrolling()
   const nameCard = React.useMemo(
-    () => (isTableScrolling ? undefined : buildPersonProfileCard(person)),
-    [person, isTableScrolling]
+    () => (isTableScrolling || disabled ? undefined : buildPersonProfileCard(person)),
+    [person, isTableScrolling, disabled]
   )
   return (
     <Avatar
       src={person.avatarUrl}
       alt={person.name}
       size={AVATAR_PX[size]}
-      className={className}
+      className={cn(className, disabled && 'opacity-disabled')}
       style={style}
       hoverCard={nameCard}
     />
@@ -138,8 +147,9 @@ function PersonAvatar({
 // outer 改 items-start + Avatar 外包 ItemPrefix primitive consumption。單行視覺 = items-center 等效;
 // 多行(autoRowHeight cell)避免 avatar+name center 整 row 不對齊 first-line text top。M1 消費既有
 // 對齊 TreeView / MenuItem / SelectionItem 共用 ItemPrefix wrap chevron/icon/avatar canonical。
-function PersonDisplay({ value, size = 'md' }: { value?: PersonValue | null; size?: 'sm' | 'md' | 'lg' }) {
-  if (!value) return <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+function PersonDisplay({ value, size = 'md', disabled = false }: { value?: PersonValue | null; size?: 'sm' | 'md' | 'lg'; /** 見 PersonAvatar.disabled jsDoc(抑制 hoverCard + dim) */ disabled?: boolean }) {
+const emptyDisplay = useFieldEmptyDisplay()
+  if (!value) return <span className="text-foreground">{emptyDisplay}</span>
 
   const person = resolvePerson(value)
 
@@ -150,7 +160,7 @@ function PersonDisplay({ value, size = 'md' }: { value?: PersonValue | null; siz
   // 對齊 GitHub Primer ActionList / Slack users_select / Atlassian UserPicker truncation canonical。
   return (
     <span className="flex items-start gap-2 min-w-0 w-full">
-      <ItemPrefix><PersonAvatar person={person} size={size} /></ItemPrefix>
+      <ItemPrefix><PersonAvatar person={person} size={size} disabled={disabled} /></ItemPrefix>
       <span className="truncate flex-1 min-w-0">{person.name}</span>
     </span>
   )
@@ -168,6 +178,7 @@ function MultiPersonDisplay({
   max,
   measured = false,
   onRemove,
+  disabled = false,
 }: {
   value?: PersonValue[] | null
   size?: 'sm' | 'md' | 'lg'
@@ -182,7 +193,10 @@ function MultiPersonDisplay({
   measured?: boolean
   /** 傳入時啟用 dismiss(edit mode),callback 接收被移除的 person */
   onRemove?: (person: PersonValue) => void
+  /** 見 PersonAvatar.disabled jsDoc(抑制全 stack ProfileCard hoverCard + avatar dim) */
+  disabled?: boolean
 }) {
+  const emptyDisplay = useFieldEmptyDisplay()
   // 2026-07-05 D3 P1 修(React #310 家族):3 hooks 原在 empty early return 之後 — value 非空↔空
   // 切換時 hook 數 0↔3 變動必 crash(現靠 consumer 三元切換 element type 偶然避開)。hoist 到 return 前。
   // 2026-05-15 Bug 3 fix(Claude+Codex Step 5 比稿 consensus):消費 shared `avatar-stack-overflow`
@@ -211,7 +225,7 @@ function MultiPersonDisplay({
     return () => ro.disconnect()
   }, [measured, size, value])
 
-  if (!value || value.length === 0) return <span className="text-fg-muted">{EMPTY_DISPLAY}</span>
+  if (!value || value.length === 0) return <span className="text-foreground">{emptyDisplay}</span>
 
   const resolvedMax = measured && measuredCount !== null ? measuredCount : (max ?? 3)
   const people = value.map(resolvePerson)
@@ -221,7 +235,7 @@ function MultiPersonDisplay({
 
   // 單人回退到 PersonDisplay(顯示名字)
   if (people.length === 1) {
-    return <PersonDisplay value={value[0]} size={size} />
+    return <PersonDisplay value={value[0]} size={size} disabled={disabled} />
   }
 
   // 2026-05-14 item-anatomy SSOT fix(per codex+Layer A 共識):outer items-start + avatar stack
@@ -241,6 +255,7 @@ function MultiPersonDisplay({
               person={person}
               size={size}
               className="ring-2 ring-[var(--surface)]"
+              disabled={disabled}
             />
             {handleDismiss && <AvatarDismissOverlay onRemove={handleDismiss} label={person.name} />}
           </span>
@@ -266,7 +281,8 @@ function MultiPersonDisplay({
                   src={person.avatarUrl}
                   alt={person.name}
                   size={16}
-                  hoverCard={buildPersonProfileCard(person)}
+                  // disabled field:同 PersonAvatar — 抑制 ProfileCard hoverCard(不可互動)
+                  hoverCard={disabled ? undefined : buildPersonProfileCard(person)}
                 />
               }
               onRemove={onRemove ? () => onRemove(value![resolvedMax + i]) : undefined}
@@ -293,8 +309,8 @@ MultiPersonDisplay.displayName = 'MultiPersonDisplay'
 //     sm/md stroke 規格;2026-06-12 同步 checkbox 2026-05-18 簡化 3.5→3,SSOT →
 //     .claude/references/ui-dev-rules.md「小尺寸 icon stroke 補償」)
 //   - **text-on-emphasis**(白 X,確保飽和色底對比)
-//   - **位置 `absolute top-0 right-0`**(button 右上角貼齊 avatar 右上角,完全在 avatar
-//     內 — user-confirmed canonical)
+//   - **位置 `absolute -top-px -right-1`**(top -1px / right -4px,右緣凸出 avatar 外 4px —
+//     v15.15 user-confirmed asymmetric canonical,rationale 見下方 className 內註解)
 //
 // **a11y**(codex P1 fix):`opacity-0` 而非 `display:none` — element 在 DOM/tab-order,
 // keyboard tab 可達,觸控 focus-within 也顯。Hover / focus-within / focus-visible

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

@@ -19,7 +19,7 @@ export const Overview: Story = {
     <div className="flex flex-col gap-10">
       <div>
         <H3>Anatomy</H3>
-        <Desc>Popover 是 Radix passthrough——點擊觸發的浮層容器,提供定位 / 動畫 / 焦點管理 / click-outside 關閉。內容完全由 consumer 決定(可放任何 React 元素)。本 DS 橋接 elevation / radius / border token,不改 Radix API。</Desc>
+        <Desc>Popover 是點擊觸發的浮層容器,提供定位 / 動畫 / 焦點管理 / click-outside 關閉。內容完全由 consumer 決定(可放任何 React 元素)。本 DS 在 Radix Popover 上橋接 elevation / radius / border token,並覆寫兩處 a11y 行為(非全等 Radix,詳「A11y 預設」段 DS 覆寫):開啟焦點落在 body 首個互動元素(而非 Radix 預設 close X)、以及自動接線 aria-labelledby(有 PopoverTitle 時)。</Desc>
         <div className="flex items-center gap-4">
           <Popover>
             <PopoverTrigger asChild>
@@ -45,7 +45,7 @@ export const Overview: Story = {
 
       <div>
         <H3>Props 速查</H3>
-        <Desc>Popover / PopoverTrigger / PopoverContent 直接沿用 Radix Popover 的同名 API,只多接上設計系統的 token,行為與 props 與 Radix 一致。Props 依宣告元件分兩類——定位類(align / side / sideOffset / collisionPadding)寫在 {'<PopoverContent>'} 上,開關 / modal 類(open / onOpenChange / defaultOpen / modal)寫在最外層 {'<Popover>'}(Root)上;寫錯元件不會生效(見「所屬元件」欄)。完整 API 見 <a href="https://www.radix-ui.com/primitives/docs/components/popover" className="underline" target="_blank" rel="noreferrer">Radix Popover 官方文件</a>。</Desc>
+        <Desc>Popover / PopoverTrigger / PopoverContent 沿用 Radix Popover 的同名 prop（定位 / 開關 / modal 等 props 與 Radix 一致），並接上設計系統 token。**例外**:PopoverContent 覆寫兩處 a11y 行為(`onOpenAutoFocus` 讓開啟焦點落 body 首個互動元素、自動接線 `aria-labelledby`),故行為非全等 Radix，詳「A11y 預設」段。Props 依宣告元件分兩類——定位類(align / side / sideOffset / collisionPadding)寫在 {'<PopoverContent>'} 上,開關 / modal 類(open / onOpenChange / defaultOpen / modal)寫在最外層 {'<Popover>'}(Root)上;寫錯元件不會生效(見「所屬元件」欄)。完整 API 見 <a href="https://www.radix-ui.com/primitives/docs/components/popover" className="underline" target="_blank" rel="noreferrer">Radix Popover 官方文件</a>。</Desc>
         <div className="overflow-x-auto">
           {/* @anatomy-exempt-next: Props 速查表為純文件對照(prop/type/default),非元件資料展示;DataTable 過重 */}
           <table className="text-caption border-collapse">

package/src/components/Popover/popover.tsx

@@ -7,6 +7,7 @@ import { cn } from "@/lib/utils"
 import { SurfaceHeader, SurfaceBody, SurfaceFooter, COMPACT_HEADER_SLOT } from "@/design-system/patterns/overlay-surface/overlay-surface"
 import { Button } from "@/design-system/components/Button/button"
 import { OVERLAY_SIDE_OFFSET, OVERLAY_COLLISION_PADDING } from "@/design-system/tokens/elevation/overlay-geometry"
+import { overlayMotion } from "@/design-system/tokens/motion/overlay-motion"
 
 /**
  * Popover — Radix Popover + 設計系統 token
@@ -100,7 +101,8 @@ const PopoverContent = React.forwardRef<
             // 2026-05-04 viewport-aware max-h SSOT(從 ProfileCard 升 DS-wide):header/footer 永遠 in-viewport,body 壓縮 scroll
             // 2026-05-05 audit dim 35 補:加 `min-h-0` 完成 M25 chain invariant(flex item default min-h: auto 阻 shrink)
             "max-h-[var(--radix-popover-content-available-height,100vh)] flex flex-col overflow-hidden min-h-0",
-            "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 motion-reduce:animate-none",
+            overlayMotion,
+            "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95",
             "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
             "origin-[var(--radix-popover-content-transform-origin)]",
             className