@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

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

@@ -0,0 +1,127 @@
+---
+component: OverflowIndicator
+family: self-contained
+variants: {}
+sizes: {}
+traits:
+  - isInternal
+benchmark:
+  - Radix HoverCard primitive: github.com/radix-ui/primitives/tree/main/packages/react/hover-card
+---
+
+# OverflowIndicator 設計原則
+
+## 定位
+
+OverflowIndicator 是 **`+N` 溢出指示器 + HoverCard 顯示隱藏內容**——當 row / container 中的項目無法全部顯示時,剩餘項目以 `+N` 形式提示,hover 展開完整清單。
+
+**實作基礎**:自建 internal primitive——消費 HoverCard + tagVariants,無直接 external primitive base。
+
+**Layout Family**:非上述 family — self-contained Tag-like primitive(自帶 `+N` 計數、單一 trigger pill + hover 展開 popover,無 prefix / content / suffix 的 slot 結構;視覺尺寸對齊 Tag family 但不屬 Family 1-4 的任何 row 結構)。
+
+---
+
+## 何時用 / 何時不用
+
+**OverflowIndicator 是 internal primitive**——由需要處理「溢出 +N」的元件消費，不直接使用。
+
+| 場景 | 正確做法 |
+|------|---------|
+| Combobox 多選 tag 溢出 | `Combobox` 單行模式內部消費 OverflowIndicator |
+| 人員選擇器 +N | `PeoplePicker`（`PersonDisplay`）內部消費 OverflowIndicator |
+| Avatar stack 溢出（「+3 more」）| Avatar.Group（未來）內部消費 |
+| Tabs / 水平 chip 列溢出 | 走 `horizontal-overflow` pattern 的 `OverflowMenuTriggerButton`（DropdownMenu affordance），**非** OverflowIndicator（規劃中：未來若需 hover 展開可改消費 OverflowIndicator）|
+| 直接在 JSX 用 `<OverflowIndicator>` | 僅當消費者是自訂 list / custom overflow pattern 時 |
+
+---
+
+## 為什麼用 HoverCard 而非 Tooltip
+
+溢出內容**可能需要互動**——而非純文字提示：
+
+- **人員 +N**：hover 清單中每個人可能需要 tag dismiss 或 hover 該人再看 ProfileCard（nested HoverCard）
+- **Tag +N**：hover 清單中每個 tag 可能需要個別 dismiss
+- **一般 +N**：穩定顯示、使用者可把滑鼠移到浮層上閱讀
+
+Tooltip 純文字、不可互動、滑鼠離開 trigger 即消失——不適合承載這些需求。
+
+### trigger 不用 Tag 元件
+
+Tag 內建 truncation Tooltip 會跟 OverflowIndicator 的 HoverCard 衝突。改用 `tagVariants` 直接套樣式，保持視覺一致但不含 Tag 的額外行為。
+
+---
+
+## 尺寸
+
+| Size | Trigger 高度 | 文字（circle shape）| 文字（tag shape）|
+|------|------------|------|------|
+| sm | `h-5 min-w-5`（20px）| `text-[10px]`（10px）| `text-caption`（12px）|
+| md | `h-6 min-w-6`（24px）| `text-caption`（12px）| `text-body`（14px）|
+| lg | `h-6 min-w-6`（24px）| `text-caption`（12px）| `text-body`（14px）|
+
+sm / md 跟 Tag 同階（20/24px），lg 對齊 md（尺寸需求一致，不需要再大）。
+
+**字級依 shape 分流**：`circle` shape 走元件內建的 `triggerText` map（sm 10px / md·lg 12px）；`tag` shape 直接套 `tagVariants({ size })`（sm 12px / md·lg 14px，見 `tag.spec.md`），刻意對齊 Tag 視覺一致（見上方「trigger 不用 Tag 元件」段）。下方「sm 用 `text-[10px]`」的理由僅適用於 circle shape。
+
+**sm 用 `text-[10px]` 的理由**：sub-footnote 特殊例外,與 Badge 共享「micro-indicator typography」tier——trigger 數字是次要輔助 indicator（非主訊息）,在 20px 小容器內 12px 會擠。完整理由與 pattern-family 說明詳見 `badge.spec.md`「字體例外：`text-[10px]`」。若未來 OverflowIndicator / Badge 以外的元件也需要 sub-footnote 尺寸,應在 typography system 加 `--font-micro` token,再改用 token 而非 arbitrary value。
+
+---
+
+## 邊界案例
+
+- **count ≤ 0**:元件自行不渲染(return `null`)——「無溢出」時 consumer 不需條件渲染
+- **大數值**:`+N` 原樣顯示(無 `99+` 縮寫),trigger `min-w` 起步、隨位數自然加寬
+- **極窄容器 / 貼 viewport 邊**:浮層定位與翻邊由 HoverCard(Radix collision)處理,見 `hover-card.spec.md`
+- **已展開時項目變動**:children 變動觸發浮層寬度重新量測(shrink-wrap re-measure)
+
+---
+
+## 禁止事項
+
+- ❌ 用 Tooltip 取代 HoverCard——溢出內容可能需要互動
+- ❌ trigger 用 Tag 元件——Tag 內建 Tooltip 會跟 HoverCard 衝突
+- ❌ 省略 `+N` 指示器（直接截斷隱藏）——使用者無法知道「還有多少被隱藏」
+- ❌ 在 HoverCard 內再嵌 Tooltip——tooltip 是資訊終點，不可巢狀
+
+---
+
+## 為何無 ColorMatrix / StateBehavior
+
+OverflowIndicator 是**承載 count + HoverCard 的 trigger primitive**,無獨立色彩與互動狀態變體:
+
+- **無 ColorMatrix**:trigger 只有 neutral 一種色彩(`circle` 用 `bg-muted` / `tag` 用 `tagVariants` 的 neutral),無 variant 色彩選項——OverflowIndicator 是結構 primitive,色彩屬於 consumer 決策(若需要色相,trigger 的外框 / 內容由 consumer 包)。
+- **無 StateBehavior**:trigger 為 HoverCard 觸發點(keyboard-focusable,有 focus-visible ring),hover / focus 只觸發 HoverCard 開啟,本身無 hover / active / disabled / selected 變化——互動狀態屬於 HoverCard trigger 行為(見 `hover-card.spec.md`),不屬 OverflowIndicator 層級。
+
+對應 anatomy story:保留 `Overview` / `Inspector` / `SizeMatrix`,額外追加元件特有的 `ShapeMatrix`(取代 ColorMatrix 展示 circle vs tag 兩種形狀變體)。
+
+---
+
+## shadcn passthrough 說明
+
+OverflowIndicator 是 **composite**(HoverCard trigger + tag-styled `+N` span + HoverCard content + rendered children list),API 為 `count`(數字)+ `children`(已 render 好的隱藏內容)+ `shape` / `size`。**套 `forwardRef` / `...props` spread**——目標皆為 **`+N` trigger pill span**(circle 或 tag 分支皆 `ref={ref}` + `{...props}`,並標 `data-overflow-indicator`):
+
+- **identity root = trigger pill span**:ref 指向 hover 前即顯示的 `+N` 計數 pill(非 portal 內的 HoverCard content);consumer 取得 ref 可量測 / 定位 trigger
+- **`...props` spread 到 trigger pill**:`Omit<React.HTMLAttributes<HTMLSpanElement>, 'children'>` 的 DOM attribute(如 `aria-*` / `data-*` / event handler)落在 trigger span 上
+- **HoverCard content 不暴露 ref**:浮層內容在 portal(DOM 離散),由底層 HoverCard 管理,不透過 OverflowIndicator 控制
+
+若 consumer 需要程式化控制 HoverCard content(custom Portal / content ref),應改用 HoverCard + Tag 自組。`displayName = 'OverflowIndicator'` 保留。
+
+---
+
+## 相關
+
+- `../HoverCard/hover-card.spec.md` — 浮層容器（OverflowIndicator 消費）
+- `../Tag/tag.spec.md` — trigger 的 `tagVariants` 樣式來源
+- `../Combobox/combobox.spec.md` — 主要消費者（多選溢出）
+- `../../patterns/horizontal-overflow/horizontal-overflow.spec.md` — 水平溢出 pattern（其 menu 模式 trigger 為 `OverflowMenuTriggerButton`，DropdownMenu affordance；與 OverflowIndicator 目前無直接消費關係，兩者語義不同：前者 click 開選單、後者 hover 展開）
+- `../Avatar/avatar.spec.md` — Avatar stack 溢出場景（未來消費者）
+
+## A11y 預設
+
+**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)
+
+**Focus**:trigger 是 tab stop(keyboard 可達 + focus-visible ring,讓鍵盤使用者也能 focus 開啟 HoverCard 看溢出內容);HoverCard 內展開的可互動內容(如人員 tag / ProfileCard)由各自的內容元件負責 focus 管理。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;HoverCard 內容透過 hover 或 focus 自動顯示(非鍵盤指令觸發)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。

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

@@ -0,0 +1,238 @@
+import type { Meta, StoryObj } from '@storybook/react'
+import { OverflowIndicator } from './overflow-indicator'
+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'
+
+/** 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 }) => (
+  <ProfileCard
+    name={p.name}
+    subtitle={p.role ? `${p.role}｜${p.empId ?? 'EMP-0000'}` : 'Design｜D-0042｜EMP-1001'}
+    avatar={{ 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 />}
+    fields={[
+      { label: 'ID', value: 'YHANAX' },
+      { label: 'Employee number', value: '1234567' },
+    ]}
+    onViewMore={() => {}}
+  />
+)
+
+const meta: Meta<typeof OverflowIndicator> = {
+  title: 'Design System/Internal/OverflowIndicator/展示',
+  component: OverflowIndicator,
+  tags: ['!dev'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'OverflowIndicator 是 `+N` 溢出指示器——當容器無法顯示全部項目時,以 `+N` 形式提示,hover 展開完整清單(HoverCard 承載,可互動)。由 Combobox / PeoplePicker / Avatar Group 等元件消費,App 不直接使用。',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof OverflowIndicator>
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 1:Combobox 多選標籤溢出(shape="tag")
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+const labelTags = [
+  { value: 'bug', label: 'bug' },
+  { value: 'p0', label: 'P0' },
+  { value: 'performance', label: 'performance' },
+  { value: 'auth', label: 'auth' },
+  { value: 'frontend', label: 'frontend' },
+]
+
+export const ComboboxTagOverflow: Story = {
+  name: 'Combobox 標籤溢出',
+  render: () => (
+    <div className="flex flex-col gap-3 max-w-sm">
+      <p className="text-caption text-fg-muted">
+        Jira 任務 labels 欄位 — 單行模式時顯示前 2 個 tag,其餘折成 +N hover 展開。
+      </p>
+      <div className="border border-border rounded-md px-3 py-1.5 flex items-center gap-1 bg-surface">
+        {labelTags.slice(0, 2).map((t) => (
+          <Tag key={t.value} size="sm">
+            {t.label}
+          </Tag>
+        ))}
+        <OverflowIndicator count={labelTags.length - 2} shape="tag" size="sm">
+          {labelTags.slice(2).map((t) => (
+            <Tag key={t.value} size="sm">
+              {t.label}
+            </Tag>
+          ))}
+        </OverflowIndicator>
+      </div>
+    </div>
+  ),
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 2:Avatar 人員 stack +N(shape="circle")
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+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 },
+]
+
+export const AvatarStackOverflow: Story = {
+  name: '人員頭像 疊合 +N',
+  render: () => (
+    <div className="flex flex-col gap-3 max-w-sm">
+      <p className="text-caption text-fg-muted">
+        GitHub PR Reviewers — 只顯示前 3 位,其餘 +3 hover 看完整清單。
+      </p>
+      <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)} />
+          </span>
+        ))}
+        <span className="-ml-1.5">
+          <OverflowIndicator count={reviewers.length - 3} shape="circle" size="md">
+            <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)} />
+                  <span>{p.name}</span>
+                </div>
+              ))}
+            </div>
+          </OverflowIndicator>
+        </span>
+      </div>
+    </div>
+  ),
+}
+
+// @story-trait-rationale: Shapes(形狀對照)retired 2026-06-11 per audit Dim 24/25 —
+//   shape × size 全矩陣已由 anatomy ShapeMatrix「Shape × Size 視覺矩陣」+ SizeMatrix
+//   (overflow-indicator.anatomy.stories.tsx)完整覆蓋,展示層只留真實業務場景;
+//   principles UsageGuidance 對應 LinkTo 已同步移除。
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 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 4:DataTable row 的指派人員溢出
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+const rows = [
+  {
+    title: '登入頁改版',
+    assignees: [
+      { name: 'Ada Chen', color: 'indigo' as const },
+      { name: '張美真', color: 'magenta' as const },
+    ],
+  },
+  {
+    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 },
+    ],
+  },
+  {
+    title: '行銷活動著陸頁',
+    assignees: [
+      { name: '蔡佳芸', color: 'blue' as const },
+      { name: '陳俊宇', color: 'purple' as const },
+      { name: '周思涵', color: 'magenta' as const },
+    ],
+  },
+]
+
+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>
+  ),
+}

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

@@ -1,8 +1,12 @@
+/**
+ * @internal — DS-internal 單元(per `.claude/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
+ * 不進 root barrel front-door;由 Combobox / PeoplePicker 等 DS 元件 wrap 消費,end-user app 請用 wrapper 元件。
+ */
 import * as React from 'react'
 import { cn } from '@/lib/utils'
 import { HoverCard, HoverCardTrigger, HoverCardContent } from '@/design-system/components/HoverCard/hover-card'
 import { tagVariants } from '@/design-system/components/Tag/tag'
-import { HOVER_DELAY_RICH_MS, HOVER_DELAY_CLOSE_MS } from '@/design-system/tokens/motion/motion'
+import { HOVER_DELAY_PLAIN_MS, HOVER_DELAY_CLOSE_MS } from '@/design-system/tokens/motion/motion'
 
 /**
  * OverflowIndicator — +N 觸發器 + HoverCard 顯示溢出內容
@@ -96,7 +100,10 @@ const OverflowIndicator = React.forwardRef<HTMLSpanElement, OverflowIndicatorPro
       <span
         ref={ref}
         data-overflow-indicator=""
-        className={cn(tagVariants({ color: 'neutral', size }), 'cursor-default', className)}
+        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}
       >
         <span className="px-1">+{count}</span>
@@ -105,9 +112,13 @@ const OverflowIndicator = React.forwardRef<HTMLSpanElement, OverflowIndicatorPro
       <span
         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-default',
+          'bg-muted text-foreground font-medium leading-none cursor-pointer',
+          'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1',
           triggerSize[size],
           triggerText[size],
           className,
@@ -119,9 +130,11 @@ const OverflowIndicator = React.forwardRef<HTMLSpanElement, OverflowIndicatorPro
     )
 
     // 2026-05-18 fix(per user audit「所有 hovercard 應消費 hover delay token」+ motion.spec.md SSOT):
-    // rich tier(可互動 popup,user 可移浮層上操作)= HOVER_DELAY_RICH_MS;close = HOVER_DELAY_CLOSE_MS。
+    // plain tier(純列表展開、無 fetch)= HOVER_DELAY_PLAIN_MS,per motion.spec.md 對照表 row;
+    // close = HOVER_DELAY_CLOSE_MS。2026-06-11 修:2026-05-18 token 遷移誤挑 rich(原 hardcode 200/300
+    // 兩 tier 皆非,遷移未對照 spec 表)— popup 可互動性由 close 緩衝保障,與 open tier 無關。
     return (
-      <HoverCard openDelay={HOVER_DELAY_RICH_MS} closeDelay={HOVER_DELAY_CLOSE_MS}>
+      <HoverCard openDelay={HOVER_DELAY_PLAIN_MS} closeDelay={HOVER_DELAY_CLOSE_MS}>
         <HoverCardTrigger asChild>
           {trigger}
         </HoverCardTrigger>
@@ -138,7 +151,7 @@ OverflowIndicator.displayName = 'OverflowIndicator'
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const overflowIndicatorMeta = {
   component: 'OverflowIndicator',
-  family: null, // non-family composite / overlay / layout
+  family: 'self-contained', // 對齊 overflow-indicator.spec.md frontmatter family: self-contained(SSOT)
   variants: {
 
   },

package/src/components/PeoplePicker/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './people-picker'

package/src/components/PeoplePicker/people-picker-helpers.ts

@@ -11,7 +11,7 @@
 // 在主檔 SSOT-bearing API 邊界處,本檔屬機械搬移。
 import { nakedCellRowModeAlign } from '@/design-system/components/Field/field-wrapper'
 import type { SelectOption } from '@/design-system/components/Select/select'
-import { buildPersonNameCard, resolvePerson, type PersonValue } from './person-display'
+import { buildPersonProfileCard, resolvePerson, type PersonValue } from './person-display'
 
 // ── Tag wrapper className SSOT ──────────────────────────────────────────────
 //
@@ -26,7 +26,7 @@ import { buildPersonNameCard, resolvePerson, type PersonValue } from './person-d
 // 必經此 helper(hook `check_peoplepicker_ssot_drift.sh` 攔接 wrapper class literal in tsx)。
 //
 // **2026-05-15 SSOT alignment**(user verbatim「單選 people picker 沒壞,難道沒有 SSOT?」):
-// 單選 picker wrapper(`select.tsx:229`)= `flex-1 min-w-0 inline-flex items-center +
+// 單選 picker wrapper(`select.tsx:244` selectedItemRenderer wrapper)= `flex-1 min-w-0 inline-flex items-center +
 // nakedCellRowModeAlign` — proven working,canonical SSOT。本 helper 對齊 single SSOT,
 // **不**自定一套(spec.md §C row 1 +「length=1 視覺 = 跟單人 closed 一致」+ §E「PersonDisplay
 // 共享 renderer」)。
@@ -46,7 +46,7 @@ export const PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS = `flex-1 min-w-0 inline-flex i
 // code-quality-allow: dead-export — paired helper for SSOT primitive(同上 hook + future use rationale)
 export function getPeoplePickerTagWrapperClass(selectedCount: number): string {
   return selectedCount === 1
-    ? PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS  // SSOT aligned to single picker wrapper(select.tsx:229)
+    ? PEOPLE_PICKER_LENGTH1_WRAPPER_CLASS  // SSOT aligned to single picker wrapper(select.tsx:244 selectedItemRenderer wrapper)
     // length>=2 stack 視覺(spec.md §D row 1):圓形 avatar overlap + group/avatar selector for dismiss overlay
     : '-ml-0.5 first:ml-0 relative inline-flex group/avatar'
 }
@@ -58,7 +58,7 @@ export function getPeoplePickerTagWrapperClass(selectedCount: number): string {
 // menu 時 dropdown row 只顯純文字 name(資訊弱)— 現透過 wrapper schema unify 直接帶 avatar /
 // description 給 SelectMenu primitive 渲。
 //
-// 2026-05-18 fix(per user directive「所有 avatar hover 都要 NameCard」+ avatar.spec.md
+// 2026-05-18 fix(per user directive「所有 avatar hover 都要 ProfileCard」+ avatar.spec.md
 // DS-wide canonical):dropdown menu items Avatar 必帶 hoverCard,跟 PersonDisplay / Tag
 // avatar 對齊。漏掉 = user 抓「PeoplePicker 選單內 avatar 沒有 namecard」。
 export function personToSelectOption(person: PersonValue): SelectOption {
@@ -66,7 +66,7 @@ export function personToSelectOption(person: PersonValue): SelectOption {
   return {
     value: p.name,
     label: p.name,
-    avatar: { src: p.avatarUrl, alt: p.name, hoverCard: buildPersonNameCard(p) },
+    avatar: { src: p.avatarUrl, alt: p.name, hoverCard: buildPersonProfileCard(p) },
     description: p.description,
   }
 }