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

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

@@ -48,6 +48,9 @@ type ShapeKey = 'circle' | 'tag'
 const SIZES: SizeKey[] = ['sm', 'md', 'lg']
 const SHAPES: ShapeKey[] = ['circle', 'tag']
 
+// 真實隱藏項目池(reviewer / assignee 溢出情境;count 可調,超出池長度時循環)— 取代編號 placeholder
+const HIDDEN_REVIEWERS = ['林思妤', '陳柏宇', 'Aisha Khan', '黃冠霖', 'Diego Santos', '王品澄', 'Nadia Petrova', '張哲瑋']
+
 // font-size 依 shape 分流(re-verified 2026-07-04):circle shape 走元件內建 triggerText
 // map(overflow-indicator.tsx:28-32),tag shape 走 tagVariants({ size })(tag.tsx:40-44)。
 // circleText / tagText 兩欄分別對應,避免把 circle-only 字級當成兩 shape 通用。
@@ -209,9 +212,9 @@ function OverflowInspector() {
             <OverflowIndicator count={count} shape={shape} size={size}>
               <div className="flex flex-col gap-1 text-caption min-w-[140px]">
                 {Array.from({ length: Math.min(count, 8) }).map((_, i) => (
-                  <span key={i}>隱藏項目 {i + 1}</span>
+                  <span key={i}>{HIDDEN_REVIEWERS[i % HIDDEN_REVIEWERS.length]}</span>
                 ))}
-                {count > 8 && <span className="text-fg-muted">…及其他 {count - 8} 項</span>}
+                {count > 8 && <span className="text-fg-muted">…及其他 {count - 8} 位</span>}
               </div>
             </OverflowIndicator>
           </div>
@@ -291,6 +294,7 @@ function OverflowInspector() {
             value={count}
             onChange={(e) => setCount(parseInt(e.target.value, 10))}
             className="w-full"
+            aria-label="調整隱藏項目數量"
           />
           <div className="text-caption font-mono text-fg-secondary">count = {count}</div>
         </div>
@@ -381,7 +385,7 @@ export const ShapeMatrix: Story = {
                   </OverflowIndicator>
                 </Td>
                 <Td mono>tagVariants neutral · rounded-md · 同 Tag 視覺</Td>
-                <Td>Combobox multi-select tag 溢出 / Breadcrumb 收合</Td>
+                <Td>Combobox multi-select tag 溢出(Breadcrumb 收合走 BreadcrumbEllipsis canonical,非本元件)</Td>
               </tr>
             </tbody>
           </table>
@@ -545,7 +549,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/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>
+      <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 內展開的內容不接受鍵盤 focus——Radix 強制 content 內 tabbable node 為 tabindex=-1，鍵盤等效操作由主列可見項承擔，需鍵盤可操作的互動浮層改用 Popover（click 觸發）。\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

@@ -29,9 +29,6 @@ export const UsageGuidance: Story = {
         <li>
           <LinkTo kind="Design System/Internal/OverflowIndicator/展示" name="人員頭像 疊合 +N"><span className="text-primary hover:text-primary-hover 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:text-primary-hover font-medium cursor-pointer">Breadcrumb 中段收合</span></LinkTo>
-        </li>
         <li>
           <LinkTo kind="Design System/Internal/OverflowIndicator/展示" name="DataTable 人員欄位"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">DataTable 人員欄位</span></LinkTo>
         </li>
@@ -43,10 +40,10 @@ export const UsageGuidance: Story = {
       <div className="prose prose-sm max-w-prose">
       <p>處理超出空間的 2 種策略:</p>
       <ul>
-        <li><strong>OverflowIndicator(本元件)</strong>—項目數量已知且不多時,顯示前幾個、其餘折成 <code>+N</code>,點開看完整清單</li>
+        <li><strong>OverflowIndicator(本元件)</strong>—項目數量已知且不多時,顯示前幾個、其餘折成 <code>+N</code>,hover 展開看完整清單</li>
         <li><strong>ScrollArea</strong>—項目數量未知或極多時,讓使用者捲動瀏覽全部</li>
       </ul>
-      <p className="text-fg-muted">判斷:項目數可數且少(≤ 100)→ OverflowIndicator;太多或未知數量 → ScrollArea。</p>
+      <p className="text-fg-muted">判斷:項目少量、已知、適合一次預覽 → OverflowIndicator;數量大、未知或需連續瀏覽 → ScrollArea。</p>
     </div>
     </div>
   ),
@@ -67,8 +64,10 @@ export const CompositionRules: Story = {
         <h4>Pattern 2 — 人員頭像疊合 +N</h4>
         <p>一群人只顯示前幾位、其餘折成 `+M`。目前由列表元件自行把頭像疊合再放上 OverflowIndicator(形狀用圓形對齊頭像);未來規劃中的 Avatar 群組元件會把這段組合收進去。對齊 Slack 工作區成員預覽 / Linear 團隊成員的做法。</p>
 
-        <h4>Pattern 3 — Tabs / Breadcrumb 水平溢出</h4>
-        <p>水平容器(Tabs / Breadcrumb)寬度不夠 → 搭配水平溢出處理 + OverflowIndicator,把中段或末端收合成 `…` 或 `+N`。對齊 Material 可捲動 Tabs + 自動溢出選單 / GitHub Breadcrumb 收合的做法。</p>
+        <h4>Pattern 3 — PeoplePicker 人員選擇欄位 +N</h4>
+        <p>人員選擇欄位選了多位、單行放不下 → PeoplePicker(<code>PersonDisplay</code>)內部使用 OverflowIndicator(圓形對齊頭像),hover `+N` 展開完整名單。對齊 Linear 多指派人 / Jira watchers 的做法。</p>
+
+        <p className="text-fg-muted">水平容器(Tabs / 單行 chip 列)寬度不夠時<strong className="font-medium">不用本元件</strong>——DS canonical 是 <code>horizontal-overflow</code> 的 <code>OverflowMenuTriggerButton</code> + DropdownMenu(click 開選單,見 horizontal-overflow.spec.md);Breadcrumb 中段收合走 BreadcrumbEllipsis + DropdownMenu(見 breadcrumb.spec.md)。兩者皆 click 開選單,與本元件 hover 展開語義不同。</p>
 
         <p className="text-fg-muted">禁止:在頁面程式碼裡自己手刻 `+N` <code>&lt;span&gt;</code>(會失去 hover 展開浮層與一致的形狀樣式)— 一律使用 OverflowIndicator。</p>
       </div>

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

@@ -124,6 +124,6 @@ OverflowIndicator 是 **composite**(HoverCard trigger + tag-styled `+N` span + H
 
 **互動行為**: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 管理。
+**Focus**:trigger 是 tab stop(keyboard 可達 + focus-visible ring,讓鍵盤使用者也能 focus 開啟 HoverCard 看溢出內容);HoverCard 內展開的內容**不接受鍵盤 focus**——Radix 強制 content 內 tabbable node 為 `tabindex="-1"`(見上方「互動行為」鍵盤限制 + `hover-card.spec.md`「A11y 預設」),鍵盤等效操作由主列可見項承擔;需鍵盤可操作的互動浮層改用 Popover(click 觸發)。
 
 **驗證**: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

@@ -129,38 +129,14 @@ export const AvatarStackOverflow: Story = {
 //   (overflow-indicator.anatomy.stories.tsx)完整覆蓋,展示層只留真實業務場景;
 //   principles UsageGuidance 對應 LinkTo 已同步移除。
 
-/* ═══════════════════════════════════════════════════════════════════════════
-   Story 3:Breadcrumb 中段收合(+N 顯示隱藏路徑)
-   ═══════════════════════════════════════════════════════════════════════════ */
-
-export const BreadcrumbCollapse: Story = {
-  name: 'Breadcrumb 中段收合',
-  render: () => (
-    <div className="flex flex-col gap-3 max-w-lg">
-      <p className="text-caption text-fg-muted">
-        深層路徑過長時,中段收合為 +N,hover 看完整路徑。
-      </p>
-      <nav className="flex items-center gap-1 text-caption">
-        <span className="text-fg-muted hover:text-foreground cursor-pointer">Projects</span>
-        <span className="text-fg-muted">/</span>
-        <OverflowIndicator count={3} shape="tag" size="sm">
-          <div className="flex flex-col gap-1 text-caption">
-            <span>Platform</span>
-            <span>Infrastructure</span>
-            <span>Monitoring</span>
-          </div>
-        </OverflowIndicator>
-        <span className="text-fg-muted">/</span>
-        <span className="text-fg-muted hover:text-foreground cursor-pointer">Dashboards</span>
-        <span className="text-fg-muted">/</span>
-        <span className="text-foreground font-medium">API latency</span>
-      </nav>
-    </div>
-  ),
-}
+// @story-trait-rationale: BreadcrumbCollapse(Breadcrumb 中段收合)retired 2026-07-16 per
+//   deep-audit A.1b — DS Breadcrumb 收合 canonical = BreadcrumbEllipsis + DropdownMenu(click 開選單,
+//   breadcrumb.spec.md「BreadcrumbEllipsis」段),Breadcrumb 全庫零 OverflowIndicator 消費;
+//   本 story 示範與 canonical 相左的 hover +N 收合 = 誤導 consumer,故 retire;
+//   principles UsageGuidance 對應 LinkTo 已同步移除。
 
 /* ═══════════════════════════════════════════════════════════════════════════
-   Story 4:DataTable row 的指派人員溢出
+   Story 3:DataTable row 的指派人員溢出
    ═══════════════════════════════════════════════════════════════════════════ */
 
 const rows = [

package/src/components/PeoplePicker/avatar-stack-overflow.ts

@@ -10,7 +10,7 @@
  *   4. **架構違反**:`MultiPersonDisplay` display path 用 canvas-based 算 / Combobox edit path 用 DOM offsetWidth
  *      → 同 cell width 兩 path 不同結果 → user verbatim「同寬 cell overflow 時間不一樣」SSOT 根本被違反
  *
- * **Fix**(per codex Q3 consensus):抽 pure formula + React hook,display + edit 兩 path **共用**。
+ * **Fix**(per codex Q3 consensus):抽 pure formula + React hook,view + edit 兩 path **共用**。
  *
  * **Deterministic formula**:
  * ```

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

@@ -31,6 +31,7 @@ export const Overview: Story = {
             people={SAMPLE_PEOPLE}
             value={SAMPLE_PEOPLE[0]}
             onChange={() => {}}
+            aria-label="負責人"
           />
         </div>
       </div>
@@ -45,6 +46,7 @@ export const Overview: Story = {
               people={SAMPLE_PEOPLE}
               value={SAMPLE_PEOPLE[0]}
               onChange={() => {}}
+              aria-label="指派對象(單選 assignee 範例)"
             />
           </div>
           <div>
@@ -53,6 +55,7 @@ export const Overview: Story = {
               people={SAMPLE_PEOPLE}
               value={[SAMPLE_PEOPLE[0], SAMPLE_PEOPLE[1]]}
               onChange={() => {}}
+              aria-label="專案協作者(多選 reviewers 範例)"
             />
           </div>
         </div>
@@ -65,7 +68,7 @@ export const Overview: Story = {
             <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
             <tbody>
               {[
-                ['mode', "'edit' | 'display' | 'readonly' | 'disabled'", "'edit'", 'Field mode'],
+                ['mode', "'edit' | 'view' | 'readonly' | 'disabled'", "'edit'", 'Field mode'],
                 ['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', '—', '單選 / 多選(類型決定模式)'],
@@ -78,7 +81,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(opt-in 逃生門;2026-07-08 A 案後 DataTable 預設不傳)'],
+                ['showDisplayEndIcon', 'boolean', 'false', 'view 模式渲 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 +100,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 / naked chrome 差異。' } },
+    docs: { description: { story: '右側 Controls 切 props 即時 render,取代 Figma inspect。切 `mode` 看 edit / view / readonly / disabled 視覺差異,切 `size` 對照 field-height tier,切 `variant` 看 default / naked chrome 差異。' } },
   },
   args: {
     mode: 'edit',
@@ -111,7 +114,7 @@ export const Inspector: Story = {
     emptyText: '沒有符合的人員',
   },
   argTypes: {
-    mode: { control: 'radio', options: ['edit', 'display', 'readonly', 'disabled'] },
+    mode: { control: 'radio', options: ['edit', 'view', 'readonly', 'disabled'] },
     variant: { control: 'radio', options: ['default', 'naked'] },
     size: { control: 'radio', options: ['sm', 'md', 'lg'] },
     disabled: { control: 'boolean' },
@@ -121,7 +124,7 @@ export const Inspector: Story = {
   },
   render: (args) => (
     <div className="max-w-md">
-      <PeoplePicker {...args} onChange={() => {}} />
+      <PeoplePicker {...args} onChange={() => {}} aria-label="負責人(Inspector 範例)" />
     </div>
   ),
 }
@@ -133,12 +136,12 @@ export const ModeMatrix: Story = {
       <div>
         <H3>edit(預設)</H3>
         <Desc>Field 樣式 + 展開觸發 Popover + Command 搜尋。</Desc>
-        <PeoplePicker people={SAMPLE_PEOPLE} value={SAMPLE_PEOPLE[0]} onChange={() => {}} />
+        <PeoplePicker people={SAMPLE_PEOPLE} value={SAMPLE_PEOPLE[0]} onChange={() => {}} aria-label="負責人(edit 模式範例)" />
       </div>
       <div>
-        <H3>display</H3>
+        <H3>view</H3>
         <Desc>裸 PersonDisplay(Avatar + Name),無 field chrome——DataTable cell / detail panel 純顯示。</Desc>
-        <PeoplePicker mode="display" people={SAMPLE_PEOPLE} value={SAMPLE_PEOPLE[0]} />
+        <PeoplePicker mode="view" people={SAMPLE_PEOPLE} value={SAMPLE_PEOPLE[0]} />
       </div>
       <div>
         <H3>readonly</H3>
@@ -341,8 +344,8 @@ export const StateBehavior: Story = {
           people={SAMPLE_PEOPLE}
           value={null}
           onChange={() => {}}
-          searchPlaceholder="試試搜尋 xyz"
-          emptyText="找不到符合的組員 — 試試輸入 email 邀請外部"
+          searchPlaceholder="搜尋團隊成員…"
+          emptyText="找不到符合的組員"
         />
       </div>
 

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

@@ -79,6 +79,7 @@ export const UsageGuidance: Story = {
               value={assignee}
               onChange={(v) => setAssignee(Array.isArray(v) ? v[0] : v)}
               people={team}
+              aria-label="task 負責人"
             />
           </div>
         </Rule>
@@ -115,6 +116,7 @@ export const UsageGuidance: Story = {
             ]}
             value={tags}
             onChange={setTags}
+            aria-label="技術 stack(多選 Combobox)"
           />
           <Label>↑ 技術 stack 是分類多選,不是人員,用 Combobox</Label>
         </Rule>
@@ -140,6 +142,7 @@ export const SingleVsMultiRule: Story = {
             value={assignee}
             onChange={(v) => setAssignee(Array.isArray(v) ? v[0] : v)}
             people={team}
+            aria-label="task 負責人(單選)"
           />
           <Label>↑ 指派 task：assignee 通常一人</Label>
         </Rule>
@@ -152,6 +155,7 @@ export const SingleVsMultiRule: Story = {
             value={reviewers}
             onChange={(v) => setReviewers(Array.isArray(v) ? v : [v])}
             people={team}
+            aria-label="PR reviewers(多選)"
           />
           <Label>↑ PR reviewers：可選多人,已選 {reviewers.length} 人</Label>
         </Rule>
@@ -177,7 +181,7 @@ export const EmptyStateRule: Story = {
         title="edit 模式 — 未選時顯示「請選擇人員」佔位提示"
         note="跟 Select / Combobox 的 placeholder 行為一致。不用半形連字號,因為 edit mode 是可操作的"
       >
-        <PeoplePicker value={null} onChange={() => {}} people={team} />
+        <PeoplePicker value={null} onChange={() => {}} people={team} aria-label="指派人員(空值 placeholder demo)" />
       </Rule>
 
       <Rule

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

@@ -60,7 +60,7 @@ const samplePeople = [
   },
 ]
 
-// @story-trait-rationale: pre-existing trait gaps (Default/WithError) tracked separately; this PR scope = add display mode card to mode showcase only.
+// @story-trait-rationale: pre-existing trait gaps (Default/WithError) tracked separately; this PR scope = add view mode card to mode showcase only.
 /* ── 單人（互動） ── */
 const SinglePicker = () => {
   const [val, setVal] = React.useState<PersonValue | null>(samplePeople[0])
@@ -72,8 +72,8 @@ const SinglePicker = () => {
       </div>
       {/* @story-trait-rationale: pre-existing trait gaps tracked separately */}
       <div>
-        <h3 className="text-body font-bold text-foreground mb-2">display</h3>
-        <PeoplePicker mode="display" value={samplePeople[0]} />
+        <h3 className="text-body font-bold text-foreground mb-2">view</h3>
+        <PeoplePicker mode="view" value={samplePeople[0]} />
       </div>
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
@@ -100,7 +100,7 @@ const MultiPicker = () => {
     <div className="flex flex-col gap-6 max-w-xs">
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">edit（可互動,多選）</h3>
-        <PeoplePicker value={val} people={samplePeople} onChange={setVal} />
+        <PeoplePicker value={val} people={samplePeople} onChange={setVal} aria-label="專案協作者(edit multi demo)" />
       </div>
       <div>
         <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
@@ -120,7 +120,7 @@ const SizePicker = ({ size }: { size: 'sm' | 'md' | 'lg' }) => {
   const [val, setVal] = React.useState<PersonValue | null>(samplePeople[0])
   return (
     <div className="flex items-center gap-3">
-      <PeoplePicker size={size} value={val} people={samplePeople} onChange={(v) => setVal(v[0] ?? null)} className="max-w-xs" />
+      <PeoplePicker size={size} value={val} people={samplePeople} onChange={(v) => setVal(v[0] ?? null)} className="max-w-xs" aria-label={`負責人(size=${size})`} />
       <Button variant="primary" size={size}>送出</Button>
       <span className="text-caption text-fg-muted">size="{size}"</span>
     </div>

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

@@ -48,7 +48,7 @@ export { PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS, getPeoplePickerTagWrapperClass }
 //     差別在 tagRenderer 視覺):
 //       - **'stack'**(default,baseline 既有視覺)— Avatar 疊合 + `+N` overflow indicator,
 //         不可 wrap。tagRenderer 渲染 avatar stack(visible count 走 shared `avatar-stack-overflow`
-//         primitive deterministic formula,2026-05-15 Bug 3 fix;display 路徑 `<MultiPersonDisplay>` 同 primitive)。
+//         primitive deterministic formula,2026-05-15 Bug 3 fix;view 路徑 `<MultiPersonDisplay>` 同 primitive)。
 //         對齊 Notion / Linear / Atlassian / Slack 多人 quick-glance idiom。
 //       - **'pill'**(opt-in)— 每人 Tag pill,可 wrap。Wrap `<Combobox tagRenderer>`,
 //         tagRenderer 用 Tag 元件 `avatar` prop SSOT(不塞 children)。
@@ -59,8 +59,12 @@ export { PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS, getPeoplePickerTagWrapperClass }
 // 讓 consumer 可傳 `id` / `data-testid` / `onBlur` / `onFocus` / `aria-*` 等 HTML root props,
 // component 內部 `...rest` forward 到 trigger 容器(對齊 DS 既有 Combobox / Select 慣例)。
 // `onChange` 衝突走 Omit(本 component 用 PersonValue[] custom signature)。
-export interface PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
-  /** Field mode(edit / display / readonly / disabled),默認 inherit Field context 或 'edit' */
+// 2026-07-17 Dim 26 修:`defaultValue` 一併 Omit — 本元件 controlled-only(spec「Controlled-only
+// rationale」),React.HTMLAttributes 內建的 `defaultValue` 若不 Omit 會讓 consumer 傳入假
+// uncontrolled API,runtime 經 `...rest` 靜默轉送 trigger div 後無效。Omit 本身即 type-level
+// regression(consumer 傳 defaultValue 直接 TS 編譯錯)。DS 先例 steps.tsx:166 同款 Omit。
+export interface PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
+  /** Field mode(edit / view / readonly / disabled),默認 inherit Field context 或 'edit' */
   mode?: FieldMode
   /** Field chrome variant(對齊 Select / Combobox)*/
   variant?: FieldVariant
@@ -113,9 +117,9 @@ export interface PeoplePickerProps extends Omit<React.HTMLAttributes<HTMLDivElem
    */
   searchIn?: 'menu' | 'trigger'
   /**
-   * Display 是否渲 ChevronDown + Field naked wrapper(D-path opt-in,2026-05-08)
-   * — DataTable cell display↔edit 像素級對齊用。預設 false(裸 PersonDisplay,backward compat)。
-   * 設 true 時 display 走 fieldWrapperStyles(naked variant)+ ItemSuffix ChevronDown,
+   * View 態是否渲 ChevronDown + Field naked wrapper(D-path opt-in,2026-05-08)
+   * — DataTable cell view↔edit 像素級對齊用。預設 false(裸 PersonDisplay,backward compat)。
+   * 設 true 時 view 走 fieldWrapperStyles(naked variant)+ ItemSuffix ChevronDown,
    * 與 edit (Select / Combobox wrapped) 同 DOM 結構,消除 Layer-B padding mismatch。
    */
   showDisplayEndIcon?: boolean
@@ -156,8 +160,8 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
   const isMulti = Array.isArray(value)
   const isEmpty = !value || (isMulti && value.length === 0)
 
-  // 2026-07-05 D3 P0 修:以下派生 + 4 hooks 原宣告在 display/readonly/single/pill 四個 early return
-  // 之後 — 同一 mounted instance 的 resolvedMode 於 edit↔display/disabled 切換(<Field mode>/<Field
+  // 2026-07-05 D3 P0 修:以下派生 + 4 hooks 原宣告在 view/readonly/single/pill 四個 early return
+  // 之後 — 同一 mounted instance 的 resolvedMode 於 edit↔view/disabled 切換(<Field mode>/<Field
   // disabled> cascade 正是 runtime 翻轉機制)時 hook 數 7→11 變動 → React #310 crash(與 Combobox
   // beta.76 / LinkInput 2026-07-04 同家族)。全部 hoist 到任何 early return 之前(對齊 select.tsx
   // 「所有 hooks 必在 early return 前 call」canonical);effect 加 mode/stack guard,邏輯不變。
@@ -206,23 +210,38 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
     else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = el
   }, [ref])
 
-  // ── mode='display' ────────────────────────────────────────────────────────
+  // ── mode='view' ────────────────────────────────────────────────────────
   // Default(showDisplayEndIcon=false):裸 PersonDisplay / MultiPersonDisplay — backward compat。
   // Opt-in(showDisplayEndIcon=true,2026-05-08 D-path):Field naked wrapper + ItemSuffix ChevronDown,
-  // 與 edit (Select / Combobox wrapped) 同 DOM 結構消除 cell display↔edit 像素偏移。
-  if (resolvedMode === 'display') {
+  // 與 edit (Select / Combobox wrapped) 同 DOM 結構消除 cell view↔edit 像素偏移。
+  if (resolvedMode === 'view') {
     if (!showDisplayEndIcon) {
-      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} />
+      // 2026-07-17 Dim 9 修:裸顯示分支原直接 return PersonDisplay/MultiPersonDisplay/span,
+      // 遺失 ref / className / DOM-safe rest props(違 spec「forwardRef + 單一 root」root props 契約,
+      // 與 readonly/disabled 分支不對稱)。補穩定 forwarding root:`w-full min-w-0` 保留
+      // PersonDisplay 既有 w-full truncate 寬度約束鏈(單人 fill + 多人 stack 左靠不變),
+      // 對齊 switch.tsx:209 view 分支轉發先例。
+      return (
+        <div ref={ref} className={cn('w-full min-w-0', className)} aria-label={ariaLabel} {...rest}>
+          {isEmpty
+            ? <span className={fieldEmptyColorClass(resolvedMode)}>{emptyDisplay}</span>
+            : isMulti
+              ? <MultiPersonDisplay value={value as PersonValue[]} size={size} measured />
+              : <PersonDisplay value={value as PersonValue} size={size} />}
+        </div>
+      )
     }
     // 2026-05-18 改 import ICON_SIZE SSOT(per user『做完』approval,消除 M17 違反 7+ 重複 ternary)
   const iconSize = ICON_SIZE[size as 'sm' | 'md' | 'lg']
     return (
       <div
-        className={cn(fieldWrapperStyles({ mode: 'display', variant: resolvedVariant, width, size }), className)}
-        data-field-mode="display"
+        // 2026-07-17 Dim 9 修:D-path view root 補 ref / aria-label / {...rest} 轉發(原只套 className,
+        // 遺失 root props;對齊 readonly/disabled 分支與 spec root props 契約)。
+        ref={ref}
+        className={cn(fieldWrapperStyles({ mode: 'view', variant: resolvedVariant, width, size }), className)}
+        data-field-mode="view"
+        aria-label={ariaLabel}
+        {...rest}
       >
         <span className={cn('flex-1 min-w-0 inline-flex items-center', nakedCellRowModeAlign)}>
           {isEmpty
@@ -371,7 +390,7 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
   // **2026-05-15 Bug 3 fix(Claude+Codex Step 5 比稿 consensus)**:visible count 走 shared
   // `avatar-stack-overflow` primitive deterministic formula(取代 Combobox DOM offsetWidth-based
   // useOverflowCount + 60px fallback 不 deterministic),pass override 給 Combobox bypass internal
-  // measurement。`MultiPersonDisplay`(display path)同 primitive,display + edit 結果一致。
+  // measurement。`MultiPersonDisplay`(view path)同 primitive,view + edit 結果一致。
   // 對齊 user verbatim SSOT「同 cell width 同 overflow 判斷」+ codex Q3 consensus shared primitive。
   const handleMultiChange = (next: string[]) => {
     onChange?.(next.map(name => findPerson(people, name)))
@@ -430,10 +449,10 @@ const PeoplePicker = React.forwardRef<HTMLDivElement, PeoplePickerProps>(functio
       // 既有 OverflowIndicator default 'circle' SSOT。
       overflowShape="circle"
       // 2026-05-15 Bug 3 fix:formula-based visible count override(避免 Combobox DOM measurement +
-      // 60px fallback 不 deterministic)。SSOT in `./avatar-stack-overflow.ts`,display + edit 共用。
+      // 60px fallback 不 deterministic)。SSOT in `./avatar-stack-overflow.ts`,view + edit 共用。
       visibleCountOverride={stackVisibleCount}
       // 2026-05-14 I4 fix(per codex+Layer A 共識):hidden items 在 `+N` overflow popover 顯
-      // Tag with avatar(對齊 display MultiPersonDisplay popover SSOT,user 抓 display vs edit
+      // Tag with avatar(對齊 view path MultiPersonDisplay popover SSOT,user 抓 display vs edit
       // overflow 視覺不一致)。
       renderHiddenTag={(item) => {
         const p = resolvePerson(findPerson(people, item.value))

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

@@ -186,7 +186,7 @@ function MultiPersonDisplay({
   max?: number
   /**
    * 2026-05-15 codex Round 5 C+ SSOT fix:`measured=true` 啟動 container-width 量測(取代 hardcode `max ?? 3`)
-   * → display + edit stack 同 algorithm(同 cell width → 同 overflow 判斷),不再 display 用固定 3 vs edit
+   * → view + edit stack 同 algorithm(同 cell width → 同 overflow 判斷),不再 view 用固定 3 vs edit
    * 用 useOverflowCount。對齊 field-controls.spec.md:286 「4-mode 共享 renderer」contract + user round 3
    * verbatim「同空間兩判斷點」SSOT directive。Default false 保 backward compat(non-cell context 仍 max ?? 3)。
    */
@@ -201,8 +201,8 @@ function MultiPersonDisplay({
   // 切換時 hook 數 0↔3 變動必 crash(現靠 consumer 三元切換 element type 偶然避開)。hoist 到 return 前。
   // 2026-05-15 Bug 3 fix(Claude+Codex Step 5 比稿 consensus):消費 shared `avatar-stack-overflow`
   // primitive。原 inline canvas-based formula 是 dual-implementation 違反 user SSOT「同 cell width 同
-  // overflow 判斷」(edit path 用 Combobox useOverflowCount DOM offsetWidth / display path 用 inline
-  // canvas)。**抽 primitive 統一**:display + edit 共用 `getAvatarStackVisibleCount` formula。
+  // overflow 判斷」(edit path 用 Combobox useOverflowCount DOM offsetWidth / view path 用 inline
+  // canvas)。**抽 primitive 統一**:view + edit 共用 `getAvatarStackVisibleCount` formula。
   // SSOT in `./avatar-stack-overflow.ts`,M14 mechanical guard 防 future drift。
   const containerRef = React.useRef<HTMLSpanElement>(null)
   const [measuredCount, setMeasuredCount] = React.useState<number | null>(null)

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

@@ -161,14 +161,17 @@ export const PlacementMatrix: Story = {
           {(['top', 'right', 'bottom', 'left'] as const).flatMap(side =>
             (['start', 'center', 'end'] as const).map(align => (
               <div key={`${side}-${align}`} className="flex items-center gap-3 border border-dashed border-divider rounded-md p-3">
+                {/* side/align 屬定位參數,標在格外 caption(非浮層可見內容);浮層本體用真實使用情境 */}
+                <span className="text-caption font-mono text-fg-muted shrink-0 whitespace-nowrap">{side} / {align}</span>
+                {/* @overlay-open-skip:12-cell 定位矩陣示範 side×align 落點,全部 defaultOpen 會讓 12 個浮層互相重疊;點擊逐格開啟即可觀察定位,開啟態視覺覆蓋於 Inspector(defaultOpen) */}
                 <Popover>
                   <PopoverTrigger asChild>
-                    <Button variant="tertiary" size="sm" className="font-mono">{side}/{align}</Button>
+                    <Button variant="tertiary" size="sm">使用說明</Button>
                   </PopoverTrigger>
-                  <PopoverContent side={side} align={align}>
-                    <PopoverBody><div className="text-caption">side=<span className="font-mono">{side}</span>, align=<span className="font-mono">{align}</span></div></PopoverBody>
+                  {/* naked popover(無 PopoverTitle)→ 自傳 aria-label 讓 role="dialog" 有 accessible name */}
+                  <PopoverContent side={side} align={align} aria-label="使用說明">
+                    <PopoverBody><div className="text-caption text-fg-secondary">拖曳卡片可調整優先順序,變更會即時同步給協作者。</div></PopoverBody>
                   </PopoverContent>
-                  {/* each placement variant already wrapped in PopoverBody for consistent padding */}
                 </Popover>
               </div>
             ))
@@ -218,13 +221,13 @@ export const SizeMatrix: Story = {
           <div className="flex items-center gap-3 border border-dashed border-divider rounded-md p-3">
             <span className="text-caption font-mono w-20">w-72(預設)</span>
             <Popover><PopoverTrigger asChild><Button variant="tertiary" size="sm">開啟</Button></PopoverTrigger>
-              <PopoverContent><PopoverBody><div className="text-caption">預設寬度 w-72</div></PopoverBody></PopoverContent>
+              <PopoverContent aria-label="預設寬度示範"><PopoverBody><div className="text-caption">預設寬度 w-72</div></PopoverBody></PopoverContent>
             </Popover>
           </div>
           <div className="flex items-center gap-3 border border-dashed border-divider rounded-md p-3">
             <span className="text-caption font-mono w-20">w-96</span>
             <Popover><PopoverTrigger asChild><Button variant="tertiary" size="sm">開啟</Button></PopoverTrigger>
-              <PopoverContent className="w-96"><PopoverBody><div className="text-caption">自訂 w-96</div></PopoverBody></PopoverContent>
+              <PopoverContent className="w-96" aria-label="自訂寬度示範"><PopoverBody><div className="text-caption">自訂 w-96</div></PopoverBody></PopoverContent>
             </Popover>
           </div>
         </div>
@@ -244,7 +247,7 @@ export const StateBehavior: Story = {
     <div className="flex flex-col gap-8">
       <div>
         <H3>開啟 / 關閉</H3>
-        <Desc>Radix 提供 data-state 切換 + DS Tailwind animate 驅動(popover.tsx L70-71):進場 `fade-in + zoom-in-95 + slide-from-side`,離場鏡像。所有方向都使用 side-aware slide 動畫,浮層看起來從 trigger 「長出來」。</Desc>
+        <Desc>Radix 提供 data-state 切換 + DS Tailwind animate 驅動(popover.tsx L105-106):進場 `fade-in + zoom-in-95 + slide-from-side`,離場 `fade-out + zoom-out`(無 slide-out,對齊 shadcn 慣例)。進場方向 side-aware slide,浮層看起來從 trigger 「長出來」。</Desc>
         <ul className="text-caption text-fg-muted list-disc pl-5 space-y-1">
           <li>點擊 trigger → 開啟</li>
           <li>點 Popover 外部 → 關閉(click outside)</li>