@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.131

package/src/components/Avatar/avatar.principles.stories.tsx

@@ -0,0 +1,249 @@
+// @principles-rationale: UsageGuidance merges WhenToUse + Vs*Rule into single 使用指引 story per refactor task (2026-04-26)
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Settings, Bell, Home } from 'lucide-react'
+import { Avatar } from './avatar'
+import { MenuItem } from '@/design-system/components/Menu/menu-item'
+import { ProfileCard, ProfileCardDefaultActions } from '@/design-system/components/ProfileCard/profile-card'
+
+const meta: Meta = {
+  title: 'Design System/Components/Avatar/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+const Rule = ({
+  title, note, children,
+}: {
+  title: string; note?: string; children: React.ReactNode
+}) => (
+  <div className="mb-14">
+    <h3 className="text-body font-bold text-foreground mb-1">{title}</h3>
+    {note && <p className="text-caption text-fg-muted mb-5 max-w-[720px] leading-relaxed">{note}</p>}
+    <div className="flex flex-col gap-3 max-w-md">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-h3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    {children}
+  </section>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose mb-8">
+          <p>Avatar 代表「誰」——人、團隊、組織、專案的視覺身份。適合的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li>留言者、指派者、團隊成員列表的人員識別;workspace / 組織 / App 的身份標識 —— 見 <LinkTo kind="Design System/Components/Avatar/展示" name="四模式"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">四模式</span></LinkTo></li>
+            <li>成員沒上傳照片、或頭像圖片載入失敗時,以名字首字 + 色彩維持可辨識 —— 見 <LinkTo kind="Design System/Components/Avatar/展示" name="備援顯示"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">備援顯示</span></LinkTo></li>
+            <li>通訊錄、成員選單、chat 列表等列表項目的主視覺 prefix —— 見 <LinkTo kind="Design System/Components/Avatar/展示" name="情境用例"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">情境用例</span></LinkTo></li>
+          </ul>
+          <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方 vs 近親 段)。</p>
+        </div>
+      </Section>
+
+      <Section title="何時不用 + 替代方案">
+        <Rule
+          title="❌ 代表抽象概念:用 Lucide Icon"
+          note="「設定」「通知」「首頁」這類功能 / 動作 / 概念不是「誰」,是「做什麼」。Icon 更適合——Avatar 用在這裡會讓使用者以為是某個人的頭像"
+        >
+          <div role="listbox" aria-label="Avatar 誤用範例" className="border border-divider rounded-lg bg-surface py-1">
+            {/* 真實誤用:把功能名「設定」直接當 avatar 的 alt,fallback 渲染首字「設」的色塊,看起來像某個成員或群組 */}
+            <MenuItem avatar={{ alt: '設定' }}>設定</MenuItem>
+          </div>
+          <Label warn>↑ ❌ 「設定」是功能不是「誰」,套 Avatar 後 fallback 渲染首字「設」的色塊,使用者誤以為是某位成員或群組。功能導覽應用 Lucide icon</Label>
+          <div role="listbox" aria-label="功能圖示正確用法" className="border border-divider rounded-lg bg-surface py-1">
+            <MenuItem startIcon={Settings}>設定</MenuItem>
+          </div>
+          <Label>↑ ✓ 功能 / 動作 / 概念用 Lucide icon,語義清楚不會誤認身份</Label>
+        </Rule>
+
+        <Rule
+          title="❌ src 壞掉又沒 name → 空 avatar(不可辨識)"
+          note="Avatar 的核心是識別身份,沒 name 又沒 src 等於失去意義。必須至少有 name"
+        >
+          <Avatar alt="" size={40} src="https://invalid-url.example/fail.jpg" />
+          <Label warn>↑ 空 avatar → 使用者不知道是誰</Label>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親元件">
+        <Rule
+          title="Avatar 代表身份,Icon 代表概念"
+          note="判斷法:「這代表『誰』還是『做什麼』?」誰 / 什麼實體 → Avatar;做什麼 / 某個概念 → Icon"
+        >
+          <div role="listbox" aria-label="身份與功能圖示對照" className="border border-divider rounded-lg bg-surface py-1">
+            {/* 人員 → 真實人像;團隊 / 組織 → 首字 + 色彩(非人臉,letter mark 是 Slack workspace idiom)*/}
+            <MenuItem avatar={{ src: 'https://i.pravatar.cc/48?u=ada-chen', alt: 'Ada Chen' }}>Ada Chen 的留言</MenuItem>
+            <MenuItem avatar={{ alt: 'Engineering Team', color: 'blue' }}>Engineering Team 專案</MenuItem>
+          </div>
+          {/* 視覺圖例(legend),非 list item */}
+          <div className="flex items-center gap-3 flex-wrap mt-2">
+            {/* @anatomy-exempt-next */}
+            <div className="flex items-center gap-2">
+              <Avatar src="https://i.pravatar.cc/48?u=ada-chen" alt="Ada Chen" size={24} />
+              <span className="text-footnote text-fg-muted">人員</span>
+            </div>
+            <div className="flex items-center gap-2">
+              <Home size={16} />
+              <span className="text-footnote text-fg-muted">首頁(概念)</span>
+            </div>
+            {/* @anatomy-exempt-next */}
+            <div className="flex items-center gap-2">
+              <Avatar alt="ABC Corp" size={24} color="purple" />
+              <span className="text-footnote text-fg-muted">組織</span>
+            </div>
+            <div className="flex items-center gap-2">
+              <Bell size={16} />
+              <span className="text-footnote text-fg-muted">通知(動作)</span>
+            </div>
+          </div>
+        </Rule>
+      </Section>
+    </div>
+  ),
+}
+
+export const FallbackRule: Story = {
+  name: '後備順序',
+  render: () => (
+    <div>
+      <Rule
+        title="有 src → 顯示圖片;沒有 src / 圖片載入失敗 → 顯示 initials"
+        note="Fallback 用 `alt` 取首字母(一律取第一個字元並轉大寫,不分中英)。背景色由 `color` prop 決定"
+      >
+        {/* 刻意示範 initials fallback:後三顆**必須**無 src(fallback 順序示範,
+            2026-07-08 demo 人像真實化 sweep 豁免保留) */}
+        <div className="flex items-center gap-3">
+          <Avatar alt="Ada Chen" size={40} src="https://i.pravatar.cc/80?img=1" />
+          <Avatar alt="Ada Chen" size={40} />
+          <Avatar alt="Alice Wang" size={40} />
+          <Avatar alt="ABC Corp" size={40} color="blue" />
+        </div>
+        <Label>↑ 依序:有圖 / 無 src 取首字母 / 英文取首字母 / 組織首字 + 色彩</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const WithBadgeOverlayRule: Story = {
+  name: '頭像疊加層:在線小點 / 計數徽章',
+  render: () => (
+    <div>
+      <Rule
+        title="Avatar 右下角 status dot — presence(在線 / 忙碌 / 離開 / 離線)"
+        note="用 Avatar 的 `status` prop(不是手刻 `<Badge dot>`)—— 顏色走 presence semantic token(`--status-online` 等,獨立於 success / error / warning),位置固定 avatar 右下角,尺寸程式化 28%"
+      >
+        <div className="flex items-center gap-4">
+          <Avatar src="https://i.pravatar.cc/80?u=ada-chen" alt="Ada" size={40} status="online" />
+          <Avatar src="https://i.pravatar.cc/80?u=alex-wang" alt="Alex" size={40} status="busy" />
+          <Avatar src="https://i.pravatar.cc/80?u=ben-liu" alt="Ben" size={40} status="away" />
+          <Avatar src="https://i.pravatar.cc/80?u=bella-wu" alt="Bella" size={40} status="offline" />
+        </div>
+        <Label>↑ online / busy / away / offline ── 狀態點本身不另發語音標籤,在線狀態整合進頭像的 alt 文字(例 alt="Ada(在線)"),避免一長串成員名單同時朗讀造成讀屏洪水</Label>
+      </Rule>
+
+      <Rule
+        title="Avatar 右上角 count badge — 未讀訊息(chat / messenger 場景)"
+        note="用 Avatar 的 `badgeCount` prop(不是手刻 `<Badge count>`)—— 內部消費 DS Badge critical variant + surface ring,max=99 自動處理 99+"
+      >
+        <div className="flex items-center gap-4">
+          <Avatar src="https://i.pravatar.cc/80?u=ada-chen" alt="Ada" size={40} badgeCount={3} />
+          <Avatar src="https://i.pravatar.cc/80?u=alex-wang" alt="Alex" size={40} badgeCount={12} />
+          <Avatar src="https://i.pravatar.cc/80?u=ben-liu" alt="Ben" size={40} badgeCount={128} />
+        </div>
+        <Label>↑ count 3 / 12 / 128(超過 99 顯示 "99+")</Label>
+      </Rule>
+
+      <Rule
+        title="✅ status(右下 presence)+ badgeCount(右上 count)可並存"
+        note="兩者是不同角、不同語義的 slot(presence=這個人的線上狀態,右下;count=此對話未讀量,右上),對齊 `badge.spec.md`「Avatar 可疊 status + count」canonical + Slack / Teams / iMessage / LINE 標配。signal crowding 只禁「同一角疊兩個同類 indicator」(如右上同時 count + dot),不禁不同角不同語義的兩個訊號"
+      >
+        <div className="flex items-center gap-4">
+          <Avatar src="https://i.pravatar.cc/80?u=ada-chen" alt="Ada" size={40} status="online" badgeCount={3} />
+          <Avatar src="https://i.pravatar.cc/80?u=alex-wang" alt="Alex" size={40} status="busy" />
+          <Avatar src="https://i.pravatar.cc/80?u=ben-liu" alt="Ben" size={40} badgeCount={12} />
+        </div>
+        <Label>↑ Ada 同時 presence(右下)+ count(右上)並存;Alex 只 presence;Ben 只 count</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+export const HoverCardIntegrationRule: Story = {
+  name: 'Avatar + ProfileCard 整合',
+  render: () => (
+    <div>
+      <Rule
+        title="人員 Avatar 的 hover 預覽必須用 ProfileCard"
+        note="ProfileCard 是 DS 設計準則 人員 hover 內容元件(avatar + name + subtitle + actions + status + fields 統一佈局)。Avatar 的 hoverCard prop 接 ProfileCard,不可手刻 JSX — 手刻會漂移出 ProfileCard 對齊 / 間距 / status token 規則"
+      >
+        <Avatar
+          src="https://i.pravatar.cc/80?u=ada-chen"
+          alt="Ada Chen"
+          size={40}
+          hoverCard={
+            <ProfileCard
+              name="Ada Chen"
+              subtitle="Design Engineer · 台北"
+              avatar={{ src: 'https://i.pravatar.cc/80?u=ada-chen', alt: 'Ada Chen' }}
+              status="online"
+              statusMessage="Out of Office: Back on Monday!"
+              actions={<ProfileCardDefaultActions />}
+              fields={[
+                { label: 'ID', value: 'YHANAX' },
+                { label: 'Employee number', value: '1234567' },
+              ]}
+              onViewMore={() => {}}
+            />
+          }
+        />
+        <Label>↑ hover avatar 彈出 ProfileCard(action 列:Chat + Audio call 設計準則)</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 關鍵資訊只靠 hover 顯示(觸控裝置看不到)"
+        note="ProfileCard hover 本身用法沒錯,問題是「資訊的唯一出口」。觸控裝置無 hover 能力,若必看資訊(狀態角色、是否離職、權限等)只出現在 hover 浮層裡,平板 / 手機使用者完全錯過。hover 是補充資訊管道,不是關鍵資訊唯一載體"
+      >
+        <div className="flex items-start gap-8">
+          <div className="flex flex-col gap-2">
+            <Avatar src="https://i.pravatar.cc/96?u=alex-wang" alt="Alex Wang" size={48}
+              hoverCard={
+                <ProfileCard name="Alex Wang" subtitle="Engineer · 已離職" onViewMore={() => {}} />
+              }
+            />
+            <Label warn>❌ 「已離職」只出現在 hover 內 — 觸控使用者看不到,可能誤發訊息給已離職成員</Label>
+          </div>
+          <div className="flex flex-col gap-2">
+            {/* 主畫面呈現關鍵狀態:Family 2 row 結構(avatar + label + description)由 MenuItem
+                承載——size=lg 觸發 block 對齊(avatar 跨越 label + description 中心)。
+                這正是 item-anatomy.spec.md 的 Family 2 設計準則,不手刻 flex row。 */}
+            <div role="listbox" aria-label="成員狀態列表" className="border border-divider rounded-lg bg-surface py-1 w-full">
+              <MenuItem
+                size="lg"
+                avatar={{ src: 'https://i.pravatar.cc/64?u=alex-wang', alt: 'Alex Wang' }}
+                description={<span className="text-error">已離職</span>}
+              >
+                Alex Wang
+              </MenuItem>
+            </div>
+            <Label>✅ 關鍵狀態直接在主畫面呈現(Family 2 MenuItem 的 description slot 標示),hover 只補充細節</Label>
+          </div>
+        </div>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/Avatar/avatar.spec.md

@@ -12,7 +12,6 @@ benchmark:
   - Polaris Avatar: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Avatar
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # Avatar 設計原則
 
@@ -31,7 +30,7 @@ Avatar 是視覺身份標識——代表一個人、一個實體（專案、組
 - **人員識別**：留言者頭像、指派者、作者、團隊成員列表
 - **組織 / 專案識別**：workspace logo、專案 icon、app 身份
 - **列表項目的主視覺 prefix**：通訊錄、成員管理、chat room 列表
-- **hover 顯示完整人員卡**：與 HoverCard 搭配呈現 NameCard content
+- **hover 顯示完整人員卡**：與 HoverCard 搭配呈現 ProfileCard content
 
 ## 何時不用
 
@@ -39,14 +38,14 @@ Avatar 是視覺身份標識——代表一個人、一個實體（專案、組
 |------|------|------|
 | 抽象概念 icon（設定、通知、搜尋）| Lucide Icon | Avatar 代表實體身份，icon 代表動作 / 概念 |
 | 純文字的 name chip（「Ada Chen」單獨顯示）| `Tag` / 純文字 | Avatar 是視覺 + fallback 文字，純文字 label 用 Tag |
-| 人員資訊卡（name + title + actions）| `NameCard`（內部含 Avatar）| NameCard 是組合元件，Avatar 是其中的身份 prefix |
+| 人員資訊卡（name + title + actions）| `ProfileCard`（內部含 Avatar）| ProfileCard 是組合元件，Avatar 是其中的身份 prefix |
 | 通知計數指示 | `Badge`（可疊加在 Avatar 右上）| Avatar 承載身份，Badge 承載計數 |
 
 ---
 
 ## Avatar HoverCard 原則(DS-wide canonical,必遵守)
 
-**任何 person avatar,hover 必出現 NameCard(HoverCard)。預設行為,不 opt-in**。
+**任何 person avatar,hover 必出現 ProfileCard(HoverCard)。預設行為,不 opt-in**。
 
 **消費者實作 canonical**:
 ```tsx
@@ -55,11 +54,11 @@ Avatar 是視覺身份標識——代表一個人、一個實體（專案、組
   src={person.photoUrl}
   alt={person.name}
   hoverCard={
-    <NameCard
+    <ProfileCard
       name={person.name}
       avatar={{ src: person.photoUrl, alt: person.name }}
       subtitle={`${person.role}｜${person.employeeId}`}
-      actions={<NameCardDefaultActions />}
+      actions={<ProfileCardDefaultActions />}
       // ↓ hover context 必含 View more:hover 只顯示精簡資料,user 需要 escape hatch 到完整 profile 頁
       onViewMore={() => navigate(`/people/${person.id}`)}
     />
@@ -68,57 +67,34 @@ Avatar 是視覺身份標識——代表一個人、一個實體（專案、組
 ```
 
 **`onViewMore` 為 hover context 必含**(2026-04-23 canonical):
-hover NameCard 是 preview,所有 preview 必提供「看完整資料」的路徑。
-缺 `onViewMore` 使用者點不到完整 profile → hover 成單向死路。對齊 Slack / Linear / Notion / Figma / Gmail hover-profile popover 必有 "View profile" link 的世界級 pattern。詳 `../NameCard/name-card.spec.md`「View more」canonical。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
-
-**適用範圍(ALL person avatars,無例外)**:
-- PeoplePicker tag / table cell 頭像 / sidebar user / comment author / avatar 堆疊
-- Dialog / Sheet body 的 member list
-- FileItem rich 的 author avatar
-- Menu / Dropdown 的 assignee / owner
-- Chat / thread / notification 頭像
-
-**世界級對照**(hover → profile 是 default,不是 opt-in):
-- Slack:hover user avatar → profile popover(default)
-- Figma:hover member avatar → profile card(default)
-- Linear:hover assignee avatar → user card(default)
-- Notion:hover person tag → user card(default)
-- GitHub:hover username + avatar → user hover card(default)
-
-**例外(不適用)**:
-- Entity avatar(專案 / 組織 logo / app icon)— 不代表人員,hover 無 NameCard
-- Bot / automated account avatar(Atlas / Octocat 等)— 本 DS 後續視需求決
+hover ProfileCard 是 preview,所有 preview 必提供「看完整資料」的路徑。
+缺 `onViewMore` 使用者點不到完整 profile → hover 成單向死路。詳 `../ProfileCard/profile-card.spec.md`「View more」canonical；該 action 是從 preview 進入完整資料的必要路徑。
+
+**適用範圍(ALL person avatars,無例外)**:PeoplePicker tag / table cell 頭像 / sidebar user / comment author / avatar 堆疊 / Dialog·Sheet member list / FileItem rich author / Menu·Dropdown assignee·owner / chat·thread·notification 頭像。
+
+**世界級對照**(hover → profile 是 default,不是 opt-in):Slack / Figma / Linear / Notion / GitHub —— hover person avatar(或 username)→ profile popover / user card,全部 default 行為。
 
-**為什麼必 default**:
-- Person avatar 單獨無 context(只有照片 + 首字),user 不知是誰
-- 世界級 collaboration tool 都把 NameCard 當「身份展開」default affordance
-- Opt-in 模式會讓一半的 consumer 忘記加,DS 品質不可控
+**例外(ProfileCard 不適用,但 hoverCard 通用行為仍可用)**:
+- Entity avatar(專案 / 組織 logo / app icon)— 不代表人員,**不自動套 ProfileCard**(ProfileCard 是人專用內容模板:64px 圓形 + presence 狀態 + Chat/通話 動作,實體沒有)。但 `hoverCard` prop 本身是**通用行為**(型別 `React.ReactNode`,avatar.tsx `AvatarProps.hoverCard`),entity / square avatar **仍可配 hoverCard 顯示其他內容**(如實體資訊卡);此時 focus ring 自動跟隨 square 形狀(rounded-md)。未來若需實體資訊卡,做成**平行的內容元件**(對齊 Atlassian `ProfileCard` / `TeamProfileCard` 分離 + GitHub `data-hovercard-type` 各 type 獨立內容),**不泛化 ProfileCard**。
+- Bot / automated account avatar(Atlas / Octocat 等)— 本 DS 後續視需求決
 
-**違規檢測(M10 proactive scan)**:
-`grep '<Avatar.*alt=\{'` 全 src,檢查有無 person name(非 entity)alt 且沒 `hoverCard` prop。
-未來會加 hook `check_avatar_hovercard.sh` 自動攔截。
+**為什麼必 default**:Person avatar 單獨無 context(只有照片 + 首字),user 不知是誰;opt-in 模式會讓一半 consumer 忘記加,DS 品質不可控。**違規檢測(M10 proactive scan)**:`grep '<Avatar.*alt=\{'` 全 src,檢查 person name(非 entity)alt 且沒 `hoverCard` prop 者;目前無專用 hook,靠 grep 掃描。
 
 **Keyboard 可達 canonical(2026-04-22 D4 UX audit 補齊)**:
-當 Avatar 有 `hoverCard` prop,Avatar wrapper **必 keyboard focusable**,讓 keyboard-only user 也能 reach NameCard popover。Avatar 元件內部自動套:
-- `tabIndex=0`(可 Tab 到)
-- `role="button"` + `aria-haspopup="dialog"`(告訴 AT 這是可觸發 popover)
+當 Avatar 有 `hoverCard` prop,Avatar wrapper **必 keyboard focusable**,讓 keyboard-only user 也能 reach ProfileCard popover。Avatar 元件內部自動套:
+- `tabIndex=0`(可 Tab 到;focus 時 Radix hover-card 自動開卡)
+- `role="img"` + `aria-label`(取 `alt`)——2026-07-07 CI axe 補修:aria-label 掛在無 role 的 generic `<div>` 是 ARIA 禁用組合(axe `aria-prohibited-attr`,serious);Avatar 語義本質 = 身份圖像,`role="img"` 讓命名合法、子孫自動 presentational、不對 AT 承諾任何互動行為
 - `focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1`(keyboard focus 視覺 indicator)
+- **不掛 `role="button"` / `aria-haspopup`**(2026-07-06 user 拍板拆除):原本宣告了卻無 Enter/Space 行為、無 `aria-expanded` = 對 AT 的空承諾(D4 finding);對齊 Radix hover-card 官方(刻意零 popup ARIA,定位 sighted-user 輔助)+ GitHub hovercard(trigger 無 popup ARIA)
 - 若無 `hoverCard` → 純展示 `<div>` 不 focusable(避免 tabTrap 噪音)
 
-Rationale:Radix `HoverCardTrigger asChild` 不自動加 tabIndex 給 non-focusable child。若 Avatar wrapper 是 `<div>` 沒 tabIndex,keyboard user 無法 reach NameCard content,違反 WCAG 2.1.1(Keyboard)+ 4.1.2(Name, Role, Value)。此 canonical 確保 DS-wide 「person avatar → NameCard」同時對 keyboard / screen reader 可達。
+Rationale:Radix `HoverCardTrigger asChild` 不自動加 tabIndex 給 non-focusable child。若 Avatar wrapper 是 `<div>` 沒 tabIndex,keyboard user 無法 reach ProfileCard content,違反 WCAG 2.1.1(Keyboard)。此 canonical 確保 DS-wide「person avatar → ProfileCard」keyboard 可達,且 ARIA 只宣告真的有的行為。
 
 **Status dot a11y(2026-04-22 D4 UX audit 調整)**:Avatar status dot 內部 span 從原 `role="status"` + `aria-label="presence: online"` 改為 `aria-hidden`。Rationale:`role="status"` 是 live region,多 Avatars(member list / mention picker)會造成 SR 洪水噪音;presence 資訊應整合進 parent avatar 的 `aria-label`(world-class Slack / Teams / Discord 共通)— consumer 傳 `alt` 時自帶語意(e.g. `alt="Alan Chen (online)"`)。
 
-**不論頭像出現在 PeoplePicker tag、table cell、sidebar、comment、avatar 堆疊——只要是人員頭像,hover 一律觸發 HoverCard 顯示 name card**(完整姓名、部門、聯絡方式等)。
-
 ### 溢出人員列表（+N）
 
-Avatar 堆疊的「+N」hover 也出 **HoverCard**（不是 Tooltip），因為：
-- 列表內的 person tag 需要 dismiss 功能（互動）
-- 每個 person tag hover 需要再出 name card（嵌套 HoverCard）
-- Tooltip 是非互動的，不支援上述需求
-
-架構：`+N → HoverCard（人員列表）→ 每個人名 → HoverCard（name card）`
+Avatar 堆疊的「+N」hover 也出 **HoverCard**（不是 Tooltip）——列表內 person tag 需要 dismiss 互動、每個 person tag hover 需再出 name card（嵌套 HoverCard），Tooltip 非互動不支援。架構：`+N → HoverCard（人員列表）→ 每個人名 → HoverCard（name card）`
 
 ### 純文字截斷 vs 人員頭像
 
@@ -139,8 +115,6 @@ Avatar 堆疊的「+N」hover 也出 **HoverCard**（不是 Tooltip），因為
 | **Icon** | 有 `icon` 或 src 載入失敗且無 alt | LucideIcon 在底色背景 | 類別標識、預設頭像 |
 | **Text** | 有 `alt` 且無 src/icon | 首字大寫 | 無照片時的 fallback |
 
-圖片載入失敗自動降級為 Icon 或 Text fallback。
-
 ---
 
 ## 尺寸
@@ -166,7 +140,7 @@ Avatar 堆疊的「+N」hover 也出 **HoverCard**（不是 Tooltip），因為
 | Text fallback 字體 | `round(size × 0.5)`（fill 模式用 `font-size:50cqi`） | 16px |
 
 - Icon 60%：業界標準（Material Design、Apple HIG）
-- Text 50%：業界標準（Material Design、GitHub），且自動對齊我們的字體 scale（10→12→16→20px） <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- Text 50%：讓 initials 與圓形留出一致內距，且自動對齊本 DS 字體 scale（10→12→16→20px）
 
 ### 常用尺寸參考
 
@@ -175,7 +149,9 @@ Avatar 堆疊的「+N」hover 也出 **HoverCard**（不是 Tooltip），因為
 | 場景 | Avatar 用法 |
 |---|---|
 | Menu item / List item inside prefix slot | `<Avatar size="fill" />`（讓父 prefix 控制尺寸） |
-| 獨立使用（page header user avatar 等） | `<Avatar size={40} />`（顯式指定 px） |
+| 獨立使用（獨立頁面 hero / profile header 的大 avatar） | `<Avatar size={40} />`（顯式指定 px） |
+
+> **勿混**：上表「page header 40px」指**獨立頁面 hero / profile header** 的大 avatar。**App chrome / global header 內的 avatar（品牌 + 帳號入口）≠ 此處**——走 `../../patterns/header-canonical/header-canonical.spec.md` 4.5 = **24px density-fixed**（chrome header avatar canonical），兩者 scope 不同。
 
 ---
 
@@ -186,49 +162,27 @@ Avatar 堆疊的「+N」hover 也出 **HoverCard**（不是 Tooltip），因為
 | `circle`（預設） | 人物（照片、姓名） |
 | `square` | 實體（專案、組織、App、品牌） |
 
-**判斷標準：「這個 avatar 代表一個人，還是一個東西？」** 圓角 token 見 `.tsx` cva。
+**判斷標準：「這個 avatar 代表一個人，還是一個東西？」** 圓角由 `.tsx` inline style 決定（無 cva），消費 radius token：`circle` = `var(--radius-full)`、`square` = `var(--radius-md)`（avatar.tsx `radius` ternary；不硬寫裸值，token 調整時自動跟隨）。
 
 ---
 
 ## 背景色
 
-Icon 和 Text 模式使用 primitive step-1 subtle 背景 + 對應 step-7 前景色。`solid` boolean prop 可切換為 step-6 全色背景 + 白色前景。
+Icon 和 Text 模式使用 primitive step-1 subtle 背景 + 對應 step-7 前景色。`solid` boolean prop 可切換為 step-6 全色背景 + on-emphasis 配對前景(yellow / amber / orange / lime 深字,詳「Solid」段)。
 
-與 Tag 元件完全對齊——所有有色 variant 直接使用 primitive token（`--color-blue-*`、`--color-deep-orange-*` 等），不使用 semantic token（`--primary`、`--error`）。Avatar 的「blue」代表藍色本身，不代表「主要操作」語義。neutral 用 `foreground`，有色用 primitive step-7（`--color-{hue}-7`）優先辨識度。
+與 Tag 元件完全對齊——**消費同一組 categorical 色相 SSOT**（`tokens/categorical-color.ts`），所有有色 variant 直接使用 primitive token（`--color-{hue}-*`），不使用 semantic token（`--primary`、`--error`）。色名即色相 1:1 對 color token（零 offset）。Avatar 的「blue」代表藍色本身，不代表「主要操作」語義。neutral 用 `foreground`，有色用 primitive step-7（`--color-{hue}-7`）優先辨識度。
 
-**注意**：`red` variant 使用 primitive `deep-orange`（`--color-deep-orange-*`）。
+**注意**：`red` variant = `--color-red-*`（品牌紅家族 hue 25），**與語意 `--error`（= `--color-deep-orange-6`，hue 38）無關**。2026-06-04 修正原「red variant 接 deep-orange」offset。12 色相與 Tag / Calendar event 完全一致。
 
 ### Subtle（預設，`solid=false`）
 
-| Color | 背景 | 前景 |
-|---|---|---|
-| neutral（預設） | `--muted` | **`--foreground`** |
-| blue | `--color-blue-1` | `--color-blue-7` |
-| red | `--color-deep-orange-1` | `--color-deep-orange-7` |
-| green | `--color-green-1` | `--color-green-7` |
-| yellow | `--color-yellow-1` | `--color-yellow-7` |
-| turquoise | `--color-turquoise-1` | `--color-turquoise-7` |
-| purple | `--color-purple-1` | `--color-purple-7` |
-| magenta | `--color-magenta-1` | `--color-magenta-7` |
-| indigo | `--color-indigo-1` | `--color-indigo-7` |
+**通則**:12 色相一律 `--color-{hue}-1` subtle 背景 + `--color-{hue}-7` 前景（1:1 零 offset,無 per-hue 特例）。**neutral 例外**（非色相）:`--muted` 背景 + `--foreground` 前景。逐色 mapping 的 implementation SSOT = `tokens/categorical-color.ts`。
 
 ### Solid（`solid=true`）
 
-step-6 全色背景 + 白色前景，適合需要更強視覺權重的場景。
+**通則**:12 色相一律 `--color-{hue}-6` 全色背景;**neutral 例外**:`--color-neutral-9` 背景 + `--inverse-fg` 前景。前景依底色明暗分桶（見下）。
 
-| Color | 背景 | 前景 |
-|---|---|---|
-| neutral | `--color-neutral-9` | `--inverse-fg` |
-| blue | `--color-blue-6` | white |
-| red | `--color-deep-orange-6` | white |
-| green | `--color-green-6` | white |
-| yellow | `--color-yellow-6` | **`--warning-foreground`** |
-| turquoise | `--color-turquoise-6` | white |
-| purple | `--color-purple-6` | white |
-| magenta | `--color-magenta-6` | white |
-| indigo | `--color-indigo-6` | white |
-
-**yellow 例外**：yellow solid 背景亮度高，白字對比不足，改用 `--warning-foreground`（深色文字）。
+**Solid 文字色規則（on-emphasis 配對,2026-06-04,與 Tag 共用 SSOT）**：依 step-6 底色明暗分桶,合規門檻 = WCAG **large/bold 3:1**（user 拍板「以最低為原則」）。底夠深 → `--on-emphasis`（白）；底太亮 → `--on-emphasis-dark`（深,= `black-a85`,原 `warning-foreground` 改名）:**yellow / amber / orange / lime** 四色用深字,其餘用白。**★ green 例外**:white 實測 2.47 連 3:1 都不過,但維持白字（慣見「綠底白字」觀感）= documented exception。對比由 `categorical-color-invariants.mjs` I4 機械驗(green exempt);逐色 mapping SSOT = `tokens/categorical-color.ts`。
 
 Image 模式不顯示背景色（圖片填滿），`solid` prop 無效果。
 
@@ -236,24 +190,24 @@ Image 模式不顯示背景色（圖片填滿），`solid` prop 無效果。
 
 ## Disabled
 
-Avatar 在 disabled 元件內使用 `opacity-disabled`（由宿主元件控制，非 Avatar 自身 prop）。詳見 `color.spec.md` 的 Disabled 狀態。
+Avatar 包在 disabled Field wrapper context 內時，會經 `useResolvedFieldDisabled()`（讀 `fieldCtx.disabled`，**涵蓋 `<Field disabled>` 與 `<Field mode="disabled">` 兩者**）**自己**套 `opacity-disabled`（= `var(--opacity-disabled)`，0.45）self-dim（取代既有 wrapper blanket opacity-disabled 逃生艙，2026-05-13 R3.5；**2026-06-08 trigger 由「只認 `mode==='disabled'`」改為 `fieldCtx.disabled`，與其他 field 控件的 disabled cascade 統一**——`<Field disabled>` 內 PeoplePicker 人名變灰時 avatar 同步變淡，視覺一致）；沒包在 Field wrapper 內的 standalone Avatar（ProfileCard / FileItem / HoverCard / Dialog 等 display 場景）維持原樣不變（`fieldCtx=null` → 不觸發）。Avatar 不提供自身 `disabled` prop。詳見 `color.spec.md` 的 Disabled 狀態。
 
 ---
 
-## Overlay:Status dot OR Count badge(擇一,不並存)
+## Overlay:Status dot + Count badge(可並存,不同角)
+
+Avatar 支援兩個 overlay API(`status` 右下 presence / `badgeCount` 右上 count),**可同時並存** — 兩者是不同角、不同語義的 slot,對齊 `badge.spec.md`「Avatar 可疊 status + count」canonical + Slack / Teams / iMessage / LINE 標配。
 
-Avatar 支援兩個 overlay API(`status` / `badgeCount`),**但同時只能用一個** — 對齊 **Badge canonical「一個 anchor 最多 1 個 indicator」原則**(2026-04-21 決策,user AR22)。
+> **2026-06-01 修正**:原「擇一不並存」(AR22)決策與 `badge.spec.md`(明文「Avatar 可疊兩個 badge」)+ `avatar.tsx`(兩個 prop 各自獨立 render,從未 type-level 互斥)三方衝突。經 M26 source-verified benchmark(Slack / MS Teams / iMessage 標配 presence dot + count badge 並存)+ user 拍板,統一為「**可並存(視覺照舊,code 不變)**」。
 
-**為什麼不並存**:即使 status(presence dot)是 Avatar 內部 SVG 非 `<Badge>` 元件,視覺上 user 仍會把兩個右角落的小圓點視為「兩個訊號」。並存違反 **signal crowding** 原則(使用者無法判斷哪個訊號重要),對齊 Badge canonical 統一規則。
+**為什麼可並存(且不同角)**:presence(右下,跟著臉看)是「這個人的線上狀態」,count(右上,視覺掃描 inbox 的自然落點)是「此對話的未讀量」——語義不同、不同角。**signal crowding** 原則真正禁止的是「**同一角疊兩個同類 indicator**」(如右上同時塞 count + dot),不是「不同角、不同語義」的兩個訊號。世界級 chat app(Slack / Teams / Discord / iMessage)標配兩者並存、把兩者分開不疊在同一角。
 
 | Overlay | Prop | 元件本體 | 位置 | 語義 | 世界級對照 |
 |---------|------|---------|------|------|-----------|
-| Status dot(presence)| `status="online"/"away"/"busy"/"offline"` | **Avatar 內部 SVG**(非 Badge) | **右下角**(circle avatar 圓周 45°) | 此人現在線上狀態 | Slack / Teams / Discord |
+| Status dot(presence)| `status="online"/"away"/"busy"/"offline"` | **Avatar 內部 `span`**(非 Badge) | **右下角**(circle avatar 圓周 45°) | 此人現在線上狀態 | Slack / Teams / Discord |
 | Count badge(通知)| `badgeCount={N}` | **`<Badge variant="critical">`**(此 anchor 唯一 Badge) | **右上角** | 此對話 / 此使用者有 N 條新事件 | iMessage / Slack thread / LINE / WhatsApp |
 
-**為什麼不同角**:語義不衝突但不同面向——presence 是「這個人是誰 + 狀態」(右下跟著臉看);count 是「關於此對話的未讀量」(右上是視覺掃描 inbox 的自然落點)。世界級 chat app 把兩者分開,**不疊在同一角**。
-
-**為什麼 status 做 Avatar 內部 SVG 而不是 `<Badge dot>`**:兩者語義完全不同——presence 是「這個人的狀態」,Badge 是「計數 / 通知緊急度」。若用 Badge 承載 presence,color token 會混用(Badge 有 low/medium/high/critical 對應緊急度,presence 有 online/busy/away/offline 對應狀態;強行映射會失真);brand 也無法獨立調 presence 色而不動 Badge 色。世界級 Slack / Teams / Discord 同樣把 presence dot 做成 avatar 自有 primitive,不走 badge 系統。
+**為什麼 status 做 Avatar 內部 span 而不是 `<Badge dot>`**:兩者語義完全不同——presence 是「這個人的狀態」,Badge 是「計數 / 通知緊急度」。若用 Badge 承載 presence,color token 會混用(Badge 有 low/medium/high/critical 對應緊急度,presence 有 online/busy/away/offline 對應狀態;強行映射會失真);brand 也無法獨立調 presence 色而不動 Badge 色。世界級 Slack / Teams / Discord 同樣把 presence dot 做成 avatar 自有 primitive,不走 badge 系統。
 
 ### Status dot 尺寸與比例
 
@@ -288,42 +242,51 @@ Avatar `badgeCount` 內部消費 DS `<Badge variant="critical" max={99}>`,加上
 - **`alt` 必傳**:即使有 `src`,`alt` 是 image fallback / SR 訊號雙重來源。Person avatar `alt` 應含 name + presence(例 `"Alan Chen (online)"`),entity avatar 用品牌 / 專案名,純裝飾(極罕見)用空字串 `alt=""`(`aria-hidden`)。
 - **無 `alt` 時 fallback**:image 模式自動降級 initials / icon;一律不靜默渲染無 SR 標的元素。
 - **Status dot SR 處理**:status dot 內部 span `aria-hidden`(presence 訊號整合進 parent `alt`),避免 `role="status"` live region 在 member list 造成 SR 洪水(詳「Status dot a11y」段)。
-- **`badgeCount` 語意**:內部消費 `<Badge>`,Badge 自帶 `aria-label="N 則未讀"` 等語義(詳 `badge.spec.md`);`badgeCount={0}` 不渲染避免空 announce。
-- **HoverCard 整合**:Avatar 帶 `hoverCard` prop 時自動 `tabIndex=0` + `role="button"` + `aria-haspopup="dialog"` + `focus-visible:ring-2`,確保 keyboard user 能 Tab 進入觸發 NameCard popover(詳「Keyboard 可達 canonical」段)。
+- **`badgeCount` 語意**:內部消費 `<Badge variant="critical">`,由 Avatar 傳入 `aria-label="N unread"` 提供計數語義(Badge 本身只有 `role="status"`,不自產 aria-label);`badgeCount <= 0` 不渲染避免空 announce。
+- **HoverCard 整合**:Avatar 帶 `hoverCard` prop 時自動 `tabIndex=0` + `role="img"` + `aria-label`(取 `alt`;**與 `badgeCount` 並用時 count 併入同一 aria-label** — `role="img"` 使子孫 presentational、內層 Badge 計數語義被壓平,故外層 label = `${alt}, ${badgeAriaLabel ?? 'N unread'}`,對齊 Slack 單一 accessible name 做法,2026-07-14 補修)+ `focus-visible:ring-2`,確保 keyboard user 能 Tab 進入觸發 ProfileCard popover;**不掛 `role="button"` / `aria-haspopup`**(2026-07-06 拆除;role="img" 為 2026-07-07 axe 補修,詳「Keyboard 可達 canonical」段)。
 - **Image alt 語意**:meaningful image(person photo / brand logo)用實質 `alt`;decorative-only(極少)走 `alt=""`,但 Avatar 本質是身份識別,decorative 用法應改用 Icon 元件。
 
 ---
 
-## 為何無 StateBehavior
+## StateBehavior 範疇
 
-Avatar 是**身份視覺 primitive**(顯示人 / 組織 / 物件的代表視覺),本身**非互動元件**:
+Avatar 是**身份視覺 primitive**(顯示人 / 組織 / 物件的代表視覺),本身無自有的 hover / active / selected 互動 state。但有兩個由 context 委派 / 自管的視覺 state,故 anatomy 仍有 `StateBehavior` story(內容降級 fallback chain + status presence dot 四態):
 
-- 無 hover / focus / active / selected / disabled 這類 state。
-- disabled 由宿主元件透過 `opacity-disabled` 控制(見本 spec「Disabled」段),不是 Avatar 自身的 state。
-- hover 行為(彈 NameCard)由 `hoverCard` prop 委託給 HoverCard primitive 處理,屬 HoverCard 的 state 不屬 Avatar。
+- **focus-visible**:Avatar 帶 `hoverCard` prop 時 wrapper 變 focusable,委派 keyboard focus + `focus-visible:ring-2 focus-visible:ring-ring` 給該 wrapper(見「Keyboard 可達 canonical」段);無 `hoverCard` 則純展示不 focusable。
+- **disabled**:Avatar 在 disabled Field wrapper context 內經 `fieldCtx` 自套 `opacity-disabled` self-dim(見「Disabled」段),非互動 state 而是視覺 context state。
+- hover 行為(彈 ProfileCard)由 `hoverCard` prop 委託給 HoverCard primitive,屬 HoverCard 的 state 不屬 Avatar。
 
-對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix` + `SizeMatrix`。
+對應 anatomy story:`Overview` + `Inspector` + `ColorMatrix` + `SizeMatrix` + `StateBehavior` + `Accessibility`。
 
 ---
 
-## 空值 / 驗證
+## 空值 / 驗證 / 邊界
+
+非互動 primitive,無 loading / error state;各邊界已散見對應段,此處收斂索引:
+
+- **`src` null / 圖片載入失敗**:自動降級 Icon / Text fallback chain(見「三種內容模式」)。
+- **`alt` 缺失**:fallback 與 SR 行為見「A11y 預設」(alt 必傳 canonical)。
+- **`size="fill"` 無確定尺寸的父容器**:fill 以父容器尺寸為準,僅用於「父已決定尺寸」的 slot(見「兩種模式」表);父無確定尺寸時改用顯式 `size={px}`。
+- **Disabled context**:見「Disabled」段(fieldCtx self-dim)。
 
-N/A(非互動 primitive,consumer 決定何時渲染;`src` 為 null / 載入失敗時 fallback 到 initials)。
+## 相關
+
+- `../HoverCard/hover-card.spec.md` — `hoverCard` prop 的浮層容器(觸發與定位由 HoverCard 負責)
+- `../ProfileCard/profile-card.spec.md` — person avatar hover 必出的人員資訊卡內容
+- `../Badge/badge.spec.md` — `badgeCount` 內部消費的 count badge(右上角 overlay)
+- `../Tag/tag.spec.md` — categorical 色相 SSOT 共用(`tokens/categorical-color.ts`,12 色相 1:1)
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `account-menu.spec.md`
+- `badge.spec.md`
 - `file-item.spec.md`
 - `hover-card.spec.md`
 - `menu-item.spec.md`
+- `motion.spec.md`
 - `overflow-indicator.spec.md`
 - `people-picker.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `motion.spec.md`
-- `opacity.spec.md`
+- `profile-card.spec.md`
 - `uiSize.spec.md`