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

package/src/components/HoverCard/hover-card.anatomy.stories.tsx

@@ -0,0 +1,151 @@
+// @anatomy-rationale:
+//   Inspector / ColorMatrix / SizeMatrix / StateBehavior N/A — HoverCard 是
+//   純行為 primitive(基於 Radix HoverCard),不含視覺樣式。bg / border /
+//   shadow / padding / size 全由 consumer 透過 className 決定;無 own variant /
+//   state / size。Overview + VisualVariants 兩個 story 已涵蓋 consumer 兩種
+//   常見視覺(ProfileCard 亮色 vs OverflowIndicator 深色 tooltip)。
+// @story-trait-allow: missing-opensnapshot — 同 hover-card.stories.tsx 檔頭 rationale:
+//   hover-trigger 行為 primitive 的 anatomy doc 內多個 inline hover demo,forced defaultOpen
+//   會讓多張浮層互疊蓋住規格表;open-state 視覺快照由 consumer canonical(ProfileCard /
+//   OverflowIndicator)各自的 OpenSnapshot 涵蓋。
+import type { Meta, StoryObj } from '@storybook/react'
+import { HoverCard, HoverCardTrigger, HoverCardContent } from './hover-card'
+import { Avatar } from '@/design-system/components/Avatar/avatar'
+import { Button } from '@/design-system/components/Button/button'
+import { H3, Desc, Td, Th } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+const meta: Meta = {
+  title: 'Design System/Internal/HoverCard/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy(純行為 primitive)</H3>
+        <Desc>HoverCard 基於 Radix HoverCard,不含視覺樣式——只提供觸發邏輯、定位、動畫。Bg / border / shadow / padding 由 consumer 決定,符合不同場景的視覺語言。</Desc>
+        <div className="flex items-center gap-6">
+          <HoverCard>
+            <HoverCardTrigger asChild>
+              <Avatar src="https://i.pravatar.cc/80?u=ada-chen" alt="Ada Chen" size={40} />
+            </HoverCardTrigger>
+            <HoverCardContent className="bg-surface-raised border border-border rounded-lg p-4 shadow-[var(--elevation-200)]">
+              <div className="flex flex-col gap-2 w-56">
+                <div className="text-body font-medium">Ada Chen</div>
+                <div className="text-caption text-fg-muted">Design Engineer · 台北</div>
+                <Button variant="tertiary" size="sm">傳訊息</Button>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
+          <span className="text-caption text-fg-muted">← hover Avatar 彈出 ProfileCard(可點按鈕)</span>
+        </div>
+      </div>
+
+      <div>
+        <H3>HoverCard 只提供</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>職責</Th><Th>實作</Th></tr></thead>
+            <tbody>
+              <tr><Td>z-index(浮層層級)</Td><Td mono>z-50</Td></tr>
+              <tr><Td>進出場動畫</Td><Td>fade + zoom + slide(方向感知)</Td></tr>
+              <tr><Td>sideOffset(與 trigger 的間距)</Td><Td mono>預設 8px(跟 Tooltip / Popover 統一)</Td></tr>
+            </tbody>
+          </table>
+        </div>
+        <p className="text-footnote text-fg-muted mt-3">
+          不提供 bg / border / shadow / padding / rounded——consumer 決定。
+        </p>
+      </div>
+
+      <div>
+        <H3>Props 速查</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>元件</Th><Th>主要 Props</Th></tr></thead>
+            <tbody>
+              <tr><Td mono>HoverCard</Td><Td mono>openDelay={`{number}`} closeDelay={`{number}`}</Td></tr>
+              <tr><Td mono>HoverCardTrigger</Td><Td mono>asChild={`{boolean}`}</Td></tr>
+              <tr><Td mono>HoverCardContent</Td><Td mono>align / sideOffset / className(consumer 自套樣式)</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const VisualVariants: Story = {
+  name: '使用方的兩種常見視覺',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>亮色 Card 樣式(ProfileCard pattern)</H3>
+        <Desc>人員資訊卡、內容預覽等可互動浮層。使用 `bg-surface-raised + elevation-200 + rounded-lg + border`。</Desc>
+        <div className="flex items-center gap-6">
+          <HoverCard>
+            <HoverCardTrigger asChild>
+              <Button variant="tertiary" size="sm">Ada Chen</Button>
+            </HoverCardTrigger>
+            <HoverCardContent className="bg-surface-raised border border-border rounded-lg p-4 shadow-[var(--elevation-200)]">
+              <div className="w-56">
+                <div className="text-body font-medium mb-1">Ada Chen</div>
+                <div className="text-caption text-fg-muted mb-3">Design Engineer · 台北</div>
+                <Button variant="tertiary" size="sm">傳訊息</Button>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
+        </div>
+      </div>
+
+      <div>
+        <H3>深色 Tooltip 樣式(OverflowIndicator pattern)</H3>
+        <Desc>溢出清單 / 快速預覽。使用 `bg-tooltip + data-theme="dark" + compact padding`。</Desc>
+        <div className="flex items-center gap-6">
+          <HoverCard>
+            <HoverCardTrigger asChild>
+              <Button variant="tertiary" size="sm">+3 位協作者</Button>
+            </HoverCardTrigger>
+            <HoverCardContent className="bg-tooltip rounded-md px-3 py-2" data-theme="dark">
+              <div className="text-caption w-56 flex flex-col gap-1">
+                <span>林思妤</span>
+                <span>陳柏宇</span>
+                <span>Aisha Khan</span>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
+        </div>
+      </div>
+
+      <div>
+        <H3>選擇對照</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Consumer</Th><Th>視覺風格</Th><Th>典型用途</Th></tr></thead>
+            <tbody>
+              <tr><Td>ProfileCard</Td><Td mono>亮色 Card(bg-surface-raised + elevation-200)</Td><Td>人員 / 組織 / 文件預覽</Td></tr>
+              <tr><Td>OverflowIndicator</Td><Td mono>深色 Tooltip(bg-tooltip + data-theme dark)</Td><Td>+N 溢出清單</Td></tr>
+              <tr><Td>Custom</Td><Td>Consumer 自訂</Td><Td>任何需要可互動 hover 浮層的場景</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+// ── Accessibility ─────────────────────────────────────────────────────────
+// 2026-05-17 ship per audit Dim 13(story-rules.md 6-canonical 含 Accessibility)
+export const Accessibility = {
+  name: '無障礙與鍵盤',
+  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">{"ARIA 與互動模式:Radix HoverCard 不設 popup role、aria-* 或 trigger 關聯，也不提供鍵盤可操作的 popup 語意；它會把卡片內可 Tab 的節點移出循序 Tab order，但不代表內容已從 accessibility tree 隱藏。其餘只提供 hover / focus 開、Esc 關 + data-state。觸發元素的可聚焦性需 consumer 自補(例如 Avatar 的 hoverCard 在元件內手動加 tabIndex=0 + role=\"img\" + aria-label;2026-07-06 拆除 role=\"button\" / aria-haspopup=\"dialog\" 空承諾 — 無 Enter/Space 行為卻宣告 popup ARIA = 對輔助技術的假承諾,對齊 avatar.tsx:252-256 + hover-card.spec.md:144)。\n\n鍵盤操作:\n\n- Tab — 焦點移到觸發元素\n- Hover 或 focus — 開啟浮層卡片\n- Esc — 關閉卡片\n\n焦點行為:這是非阻斷(non-modal)的浮層,focus 會開啟卡片但不會把焦點鎖在裡面;焦點仍留在觸發元素,按 Esc 即可關閉。觸發元素 focus 時顯示可見的外框(2px 實線,使用 --ring 色),與整個設計系統的 focus-visible 樣式一致。\n\n鍵盤限制:Radix HoverCard 會把卡片內所有可 Tab 的節點強制設成 tabindex=\"-1\",因此卡片內部的按鈕 / 連結鍵盤 Tab 到不了 — 鍵盤使用者僅能 focus 觸發元素開卡 + Esc 關卡,無法進入卡片操作互動內容。關鍵互動勿放 HoverCard 內,需鍵盤可達的互動浮層請用 Popover(click 觸發)。\n\n驗證:Storybook 無障礙檢測面板應為 0 項嚴重違規;文字對比至少 4.5:1、UI 元素對比至少 3:1,符合 WCAG AA。"}</p>
+    </div>
+  ),
+}

package/src/components/HoverCard/hover-card.principles.stories.tsx

@@ -0,0 +1,211 @@
+// @principles-rationale: Merged WhenToUse + VsTooltipRule + NotForCriticalInfoRule
+// into a single `UsageGuidance` story (3 sections) per 2026-04-26 user mandate to
+// consolidate decision-related stories. PureBehaviorPrimitiveRule kept as separate principle.
+// @story-trait-allow: missing-opensnapshot — 同 hover-card.stories.tsx 檔頭 rationale:
+// 原則頁多個 inline hover demo,forced defaultOpen 會多張浮層互疊;open-state 快照由
+// consumer canonical(ProfileCard / OverflowIndicator)的 OpenSnapshot 涵蓋。
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { ExternalLink } from 'lucide-react'
+import { HoverCard, HoverCardTrigger, HoverCardContent } from './hover-card'
+import { Avatar } from '@/design-system/components/Avatar/avatar'
+import { Button } from '@/design-system/components/Button/button'
+
+const meta: Meta = {
+  title: 'Design System/Internal/HoverCard/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-body-lg font-semibold text-foreground mb-3 pb-1 border-b border-divider">{title}</h2>
+    <div>{children}</div>
+  </section>
+)
+
+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>
+)
+
+// ── UsageGuidance — 使用指引(何時用 / 何時不用 + 替代 / vs 近親) ──
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div>
+      <Section title="何時用">
+        <div className="prose prose-sm max-w-prose">
+          <p>適合 HoverCard 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+          <ul className="space-y-1">
+            <li>
+              <LinkTo kind="Design System/Internal/HoverCard/展示" name="人員頭像 ProfileCard"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">人員頭像 ProfileCard</span></LinkTo>
+            </li>
+            <li>
+              <LinkTo kind="Design System/Internal/HoverCard/展示" name="連結預覽卡"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">連結預覽卡</span></LinkTo>
+            </li>
+            <li>
+              <LinkTo kind="Design System/Internal/HoverCard/展示" name="溢出清單"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">溢出清單</span></LinkTo>
+            </li>
+            <li>
+              <LinkTo kind="Design System/Internal/HoverCard/展示" name="儲存庫資訊卡"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Repository 資訊卡</span></LinkTo>
+            </li>
+            <li>
+              <LinkTo kind="Design System/Internal/HoverCard/展示" name="觸發點類型與延遲"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">Trigger 類型與 delay</span></LinkTo>
+            </li>
+          </ul>
+          <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方「vs 近親」)。</p>
+        </div>
+      </Section>
+
+      <Section title="何時不用 + 替代">
+        <Rule
+          title="❌ 關鍵資訊不放 HoverCard(觸控裝置無法 hover)"
+          note="手機 / 平板沒有 hover 事件,HoverCard 根本不會觸發。關鍵資訊(錯誤警告、必要操作說明、付款條款)如果只靠 HoverCard,觸控使用者會完全錯過"
+        >
+          <HoverCard>
+            <HoverCardTrigger asChild>
+              <Button variant="primary" danger>刪除帳號</Button>
+            </HoverCardTrigger>
+            <HoverCardContent className="bg-surface-raised border border-error rounded-lg p-4">
+              <div className="w-64">
+                <div className="text-body font-medium text-error mb-1">永久刪除警告</div>
+                <p className="text-caption">此動作會永久刪除所有資料</p>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
+          <Label warn>↑ 刪除警告只靠 hover → 手機使用者點按鈕前根本沒看到 → 改用 Dialog 確認</Label>
+        </Rule>
+
+        <Rule
+          title="✅ 補充資訊 / 預覽 / 人員卡適合 HoverCard"
+          note="看到更好、看不到也不影響主流程的場景。即便觸控裝置沒 hover,使用者透過點擊人員 / 連結仍能取得完整資訊(HoverCard 只是桌機的快捷預覽)"
+        >
+          <HoverCard>
+            <HoverCardTrigger asChild>
+              <a
+                href="https://help.acme.com/user-manual"
+                target="_blank"
+                rel="noreferrer"
+                className="text-primary underline cursor-pointer inline-flex items-center gap-1"
+              >
+                使用者手冊 <ExternalLink size={12} />
+              </a>
+            </HoverCardTrigger>
+            <HoverCardContent className="bg-surface-raised border border-border rounded-lg p-4">
+              <div className="w-64">
+                <div className="text-body font-medium mb-1">使用者手冊</div>
+                <p className="text-caption text-fg-muted">完整操作指南與常見問題</p>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
+          <Label>↑ 連結預覽,hover 才看到是加分,沒看到點進去也行</Label>
+        </Rule>
+      </Section>
+
+      <Section title="vs 近親 — HoverCard vs Tooltip(主檔)">
+        <Rule
+          title="HoverCard — 內容可互動、滑鼠移到浮層上不消失"
+          note="適合放按鈕、連結、需要選取的文字。使用者 hover trigger → 浮層出現 → 滑鼠移到浮層上繼續停留並點擊按鈕 / 連結都沒問題"
+        >
+          <HoverCard>
+            <HoverCardTrigger asChild>
+              <span className="underline cursor-pointer">@Ada Chen</span>
+            </HoverCardTrigger>
+            <HoverCardContent className="bg-surface-raised border border-border rounded-lg p-4 shadow-[var(--elevation-200)]">
+              <div className="flex flex-col gap-2 w-64">
+                <div className="flex items-center gap-3">
+                  <Avatar src="https://i.pravatar.cc/80?u=ada-chen" alt="Ada Chen" size={40} />
+                  <div>
+                    <div className="text-body font-medium">Ada Chen</div>
+                    <div className="text-caption text-fg-muted">Design Engineer</div>
+                  </div>
+                </div>
+                <Button variant="tertiary" size="sm">傳訊息</Button>
+              </div>
+            </HoverCardContent>
+          </HoverCard>
+          <Label>↑ hover @mention 彈出 ProfileCard,滑鼠可移到浮層點「傳訊息」</Label>
+        </Rule>
+
+        <Rule
+          title="Tooltip — 純文字、不可互動、離開 trigger 即消失"
+          note="適合一句話的提示(icon-only 的 aria-label、字串截斷補全)。無法互動,滑鼠離開 trigger 立刻消失。完整對照見 spec 的「與 Tooltip 的分界」"
+        >
+          <Label>完整情境對照與三角度分析見 hover-card.spec.md「與 Tooltip 的分界」(主檔)</Label>
+        </Rule>
+
+        <Rule
+          title="判斷法:「使用者會想移到浮層上做事嗎?」"
+          note="需要 → HoverCard;純看一句話 → Tooltip"
+        >
+          <div className="flex items-center gap-4">
+            <div className="flex flex-col gap-1">
+              <HoverCard>
+                <HoverCardTrigger asChild>
+                  <Avatar src="https://i.pravatar.cc/64?u=ada-chen" alt="Ada Chen" size={32} />
+                </HoverCardTrigger>
+                <HoverCardContent className="bg-surface-raised border border-border rounded-lg p-3">
+                  <div className="flex flex-col gap-2 w-56">
+                    <div className="text-body font-medium">Ada Chen</div>
+                    <Button variant="tertiary" size="sm">查看 profile</Button>
+                  </div>
+                </HoverCardContent>
+              </HoverCard>
+              <Label>HoverCard(可點按鈕)</Label>
+            </div>
+            <div className="flex flex-col gap-1 items-center">
+              <span title="此設定影響全域" className="text-footnote text-fg-muted underline decoration-dotted">全域設定 (hover)</span>
+              <Label>Tooltip(純文字提示)</Label>
+            </div>
+          </div>
+        </Rule>
+      </Section>
+    </div>
+  ),
+}
+
+export const PureBehaviorPrimitiveRule: Story = {
+  name: '純行為元件——視覺由使用方決定',
+  render: () => (
+    <div>
+      <Rule
+        title="HoverCard 只擁有觸發、定位與開關行為"
+        note="背景、邊框、陰影、圓角與內距必須由真正的內容 owner 決定：ProfileCard 是明色人員資訊卡，OverflowIndicator 可是緊湊清單。若 HoverCard 自帶一套 chrome，兩個 consumer 都必須 override，結果反而會產生漂移。"
+      >
+        <Label>完整的亮色／深色渲染對照請看「設計規格 / 視覺變體」；這裡保留的是 ownership 判斷。</Label>
+      </Rule>
+
+      <Rule
+        title="人員 Avatar 由 Avatar / ProfileCard 組合擁有視覺"
+        note="人員場景使用 Avatar 的 `hoverCard` prop 連接互動，content 依 ProfileCard 規格撰寫；consumer 不重複手組 HoverCardTrigger，也不讓底層 primitive 擁有人員卡片樣式。"
+      >
+        <div className="flex items-center gap-3">
+          <Avatar src="https://i.pravatar.cc/80?u=ada-chen" alt="Ada Chen" size={40} hoverCard={
+            <div className="flex flex-col gap-2 w-56">
+              <div className="text-body font-medium">Ada Chen</div>
+              <div className="text-caption text-fg-muted">Design Engineer · 台北</div>
+              <Button variant="tertiary" size="sm">傳訊息</Button>
+            </div>
+          } />
+          <span className="text-body">Ada Chen</span>
+        </div>
+        <Label>Avatar 負責 trigger 整合，ProfileCard 負責內容與 chrome，HoverCard 只負責行為。</Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/HoverCard/hover-card.spec.md

@@ -19,8 +19,10 @@ Hover 觸發的**可互動浮層**，基於 Radix HoverCard。
 
 **實作基礎**：基於 Radix HoverCard——純行為 primitive，只提供觸發邏輯、定位、動畫，不含視覺樣式。
 
-- **是**：hover 顯示可互動內容（按鈕、連結、可選取文字）的浮層容器
-- **不是**：Tooltip（純文字提示、不可互動、hover 離開即消失）
+**分類**：Internal primitive——不進 root barrel front-door、不裸用;DS 內由 Avatar(`hoverCard`)/ OverflowIndicator / ProfileCard 場景組合消費;consumer 需要時可經 per-component subpath 包裝並自行確認後使用(`.claude/rules/ui-development.md`「Root barrel front-door 排除」SSOT,internal ≠ 禁用)(frontmatter `isInternal`:root barrel 排除,storybook `Design System/Internal/HoverCard`)。
+
+- **是**：hover 顯示可互動內容（按鈕、連結、可選取文字——**滑鼠互動**；鍵盤進不了卡片，見「A11y 預設」）的浮層容器，定位為滑鼠 / focus 使用者的補充閱讀 surface
+- **不是**：Tooltip（純文字提示、**內容不可互動**；指標可短暫移到浮層屬 WCAG 1.4.13 hoverable grace，非「立即消失」）；也不是鍵盤可操作的互動浮層（那是 Popover）
 
 **Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
 
@@ -28,7 +30,7 @@ Hover 觸發的**可互動浮層**，基於 Radix HoverCard。
 
 ## 何時用
 
-- **人員資訊卡**：Avatar hover 顯示 NameCard（姓名、角色、聯絡按鈕）
+- **人員資訊卡**：Avatar hover 顯示 ProfileCard（姓名、角色、聯絡按鈕）
 - **溢出項目展開**：人員列表 `+N` hover 展示完整清單
 - **內容預覽**：連結 / 文件 hover 顯示標題 / 縮圖 / 摘要預覽
 - **不破壞當前畫面的補充資訊**：hover 可看細節，不 hover 也能使用主要介面
@@ -51,12 +53,12 @@ Hover 觸發的**可互動浮層**，基於 Radix HoverCard。
 | | HoverCard | Tooltip |
 |---|---|---|
 | 觸發 | hover | hover |
-| **內容可互動** | 是（按鈕、連結、hover 子元素） | 否（純文字） |
-| 停留行為 | 滑鼠移到浮層上不消失 | 滑鼠離開 trigger 即消失 |
+| **內容可互動** | 是——限滑鼠（Radix 設 content 內 tabbable node 為 `tabindex="-1"`，鍵盤不可達，見「A11y 預設」） | 否（純文字） |
+| 停留行為 | 滑鼠可移到浮層互動不消失 | 滑鼠可短暫移到浮層（WCAG 1.4.13 grace，`tooltip.tsx` 未設 `disableHoverableContent`），但內容不可互動 |
 | 視覺樣式 | 由 consumer 決定（亮色 card 或深色 tooltip 風格皆可） | 統一深色背景 |
-| 典型用例 | NameCard、內容預覽、溢出清單 | icon 用途、shortcut、截斷文字補全 |
+| 典型用例 | ProfileCard、內容預覽、溢出清單 | icon 用途、shortcut、截斷文字補全 |
 
-**Fallback**：需要放按鈕 / 連結 → HoverCard；一句話純文字 → Tooltip。
+**Fallback**：需要放按鈕 / 連結（滑鼠增強）→ HoverCard；鍵盤必須可操作的互動浮層 → Popover；一句話純文字 → Tooltip。
 
 **本節是 HoverCard vs Tooltip 的 SSOT**，Tooltip spec 指回本節。
 
@@ -71,7 +73,7 @@ HoverCardContent 只提供：
 
 | Consumer | 視覺風格 |
 |---|---|
-| NameCard | 亮色 card（`bg-surface-raised` + `elevation-200` + `rounded-lg` + `border`） |
+| ProfileCard | 亮色 card（`bg-surface-raised` + `elevation-200` + `rounded-lg` + `border`） |
 | OverflowIndicator | 深色 tooltip 風格（`bg-tooltip` + `data-theme="dark"`） |
 
 ## sideOffset
@@ -80,11 +82,11 @@ HoverCardContent 只提供：
 
 ## align
 
-**HoverCard 走「輕量浮層」例外**(見 `../Popover/popover.spec.md`「SSOT 適用範圍」)—— hover 觸發、預設展示為主、寬度隨內容自適應,Radix 預設 `center` 即可涵蓋絕大多數情境。`align` 由 consumer 視視覺需求自選(NameCard hover 常用 `start` 對齊 avatar 左邊緣),**不強制對齊 structured overlay 的 trigger-position canonical**。
+**HoverCard 走「輕量浮層」例外**(見 `../Popover/popover.spec.md`「SSOT 適用範圍」)—— hover 觸發、預設展示為主、寬度隨內容自適應,Radix 預設 `center` 即可涵蓋絕大多數情境。`align` 由 consumer 視視覺需求自選(ProfileCard hover 常用 `start` 對齊 avatar 左邊緣),**不強制對齊 structured overlay 的 trigger-position canonical**。
 
 ## 用途
 
-- **NameCard**：人員 Avatar hover 顯示詳細資訊
+- **ProfileCard**：人員 Avatar hover 顯示詳細資訊
 - **Overflow person list**：溢出的人員列表 hover 展開
 - **Preview card**：內容預覽（文件、連結）
 
@@ -98,10 +100,10 @@ Avatar 元件的 `hoverCard` prop 接受 HoverCard content，自動將 Avatar
 
 HoverCard 是**純行為 primitive**(只提供 hover 觸發邏輯 + 定位 + 動畫,不含視覺樣式),設計上刻意不擁有變體:
 
-- **無 Inspector**:HoverCard 的互動 prop 只有 `sideOffset`(預設 8px,統一浮層間距)與 placement(side / align),再多就侵入 consumer 的職責。元件特有 `VisualVariants` story 展示「同一個 HoverCard primitive 如何被 NameCard / OverflowIndicator 兩個 consumer 包出完全不同的視覺」才是 HoverCard 的設計精神——互動 Inspector 無法呈現此點。
-- **無 ColorMatrix**:HoverCardContent **不提供** `bg` / `border` / `shadow` / `rounded`(見本 spec「純行為 primitive」段),consumer 決定視覺(NameCard 亮色 card / OverflowIndicator 深色 tooltip 風格)。色彩不屬 HoverCard 職責。
+- **無 Inspector**:HoverCard 的互動 prop 只有 `sideOffset`(預設 8px,統一浮層間距)與 placement(side / align),再多就侵入 consumer 的職責。元件特有 `VisualVariants` story 展示「同一個 HoverCard primitive 如何被 ProfileCard / OverflowIndicator 兩個 consumer 包出完全不同的視覺」才是 HoverCard 的設計精神——互動 Inspector 無法呈現此點。
+- **無 ColorMatrix**:HoverCardContent **不提供** `bg` / `border` / `shadow` / `rounded`(見本 spec「純行為 primitive」段),consumer 決定視覺(ProfileCard 亮色 card / OverflowIndicator 深色 tooltip 風格)。色彩不屬 HoverCard 職責。
 - **無 SizeMatrix**:無 size prop,尺寸由 content 決定,寬高繼承 consumer。
-- **無 StateBehavior**:passive open / close(hover 觸發),無 hover / selected / active / disabled——這些屬於 consumer 元件(NameCard 的 section, OverflowIndicator 的 item)。
+- **無 StateBehavior**:passive open / close(hover 觸發),無 hover / selected / active / disabled——這些屬於 consumer 元件(ProfileCard 的 section, OverflowIndicator 的 item)。
 
 對應 anatomy story:保留 `Overview` + 元件特有 `VisualVariants`(展示 primitive + consumer 視覺解耦的 hero story)。
 
@@ -111,26 +113,35 @@ HoverCard 是**純行為 primitive**(只提供 hover 觸發邏輯 + 定位 + 動
 
 - ❌ 把關鍵資訊放在 HoverCard — 觸控裝置無 hover 能力,user 永遠看不到;關鍵 info 直接顯示或 Popover(click 觸發)
 - ❌ HoverCard 內塞表單 / 多步流程 — hover 離開可能誤關閉,複雜互動用 Dialog / Sheet
-- ❌ HoverCard 自帶 bg / border / shadow / padding 套在 HoverCardContent 上 — HoverCard 是純行為 primitive,視覺由 consumer NameCard / OverflowIndicator 各自決定(見「純行為 primitive」段)
-- ❌ HoverCard delay 設 0(立即彈出)— 滑鼠掃過所有 trigger 都彈,視覺雜訊;遵循 Radix delay 預設 700ms open / 300ms close
+- ❌ HoverCard 自帶 bg / border / shadow / padding 套在 HoverCardContent 上 — HoverCard 是純行為 primitive,視覺由 consumer ProfileCard / OverflowIndicator 各自決定(見「純行為 primitive」段)
+- ❌ HoverCard delay 設 0(立即彈出)— 滑鼠掃過所有 trigger 都彈,視覺雜訊;delay tier SSOT 見 `tokens/motion/motion.spec.md`(rich 700ms open / close 200ms;2026-06-11 起 HoverCard Root 內建預設,裸用即得 canonical,consumer 可 per-instance override — 如 OverflowIndicator 傳 plain)
 - ❌ 拿 HoverCard 當 Tooltip(純文字提示)— 用 Tooltip(統一深色背景 + ARIA `role="tooltip"`),HoverCard 是 interactive surface 角色不同
 
-## 空值 / 驗證 / loading / a11y
+## 常見誤解
+
+- 「HoverCard 內的按鈕鍵盤可達」——錯。Radix 把 content 內 tabbable node 設 `tabindex="-1"`,鍵盤使用者進不了卡片(見 A11y 預設);需鍵盤可達的互動浮層用 Popover
+- 「HoverCard = 大一點的 Tooltip」——錯。Tooltip 純文字不可互動;HoverCard 是 interactive surface(分界 SSOT 見上方)
+- 「觸控裝置也會開卡」——觸控無 hover;關鍵資訊不可只放 HoverCard(見禁止事項)
+
+## 邊界案例 / 空值
 
-純行為 primitive,無獨立 empty / validation / loading;a11y 由 Radix HoverCard 提供(open on hover / focus,Escape 關)。
+- **重複快速 hover**:open / close delay 自然 debounce——滑過不停留不開卡(open delay),短暫滑出再滑回不閃爍(close delay 緩衝)
+- **Content 為空**:純行為 primitive 不驗證 content,傳空仍渲染空浮層;consumer(如 Avatar `hoverCard`)應在無資料時不掛 hoverCard prop
+- **浮層超出 viewport**:Radix collision 自動 flip / shift(`collisionPadding=12` 保證視覺 ≥ 8px 邊距);高度以 `--radix-hover-card-content-available-height` 為 max-h + flex chain 壓縮 scroll(M25)
+- **Disabled / loading**:純行為 primitive 無此 state;fetch 中的內容(如 ProfileCard loading)由 consumer 自行渲 skeleton
 
 ---
 
 ## 相關
 
 - `../Tooltip/tooltip.spec.md` — 純文字 hover 提示（HoverCard vs Tooltip 的分界 SSOT 在本 spec）
-- `../NameCard/name-card.spec.md` — 人員資訊卡（HoverCard 最常見 content）
+- `../ProfileCard/profile-card.spec.md` — 人員資訊卡（HoverCard 最常見 content）
 - `../Avatar/avatar.spec.md` — 人員 Avatar 自動 hoverCard 整合
-- Popover（`components/Popover/`，shadcn passthrough 無 spec）— 點擊觸發的浮層
+- `../Popover/popover.spec.md` — 點擊觸發的浮層(align canonical SSOT,本 spec「align」段引用)
 
 ## A11y 預設
 
-**ARIA / Pattern**:繼承 Radix `hover-card` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/hover-card#accessibility)。
+**ARIA / Pattern**:Radix `hover-card` 刻意**不**設 popup `role`、`aria-*` 或 trigger 關聯，定位為 sighted-mouse-user 增強；它不提供可由鍵盤操作的 popup 語意，並把 content 內可 Tab 的節點移出循序 Tab order，但不代表已把渲染內容從 accessibility tree 隱藏。Radix 只提供:hover / focus 開、Esc 關 + `data-state`。Trigger 的可聚焦性需 consumer 自補(如 Avatar `hoverCard` 在 `avatar.tsx` 手動加 `tabIndex=0` + `aria-label`;**不掛 role/aria-haspopup**——2026-07-06 拆除,無 activation 行為的 role 宣告 = 對 AT 空承諾,對齊 Radix 官方零 role/aria 定位)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/hover-card#accessibility)。
 
 **Keyboard 行為**:
 
@@ -138,20 +149,19 @@ HoverCard 是**純行為 primitive**(只提供 hover 觸發邏輯 + 定位 + 動
 - Hover / focus — 開啟 card
 - Esc — 關閉
 
-**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+**Focus**:non-modal hover/focus surface — focus 開啟 surface,**不 trap**,focus 仍在 trigger,Esc 關閉。Visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。(2026-05-27 修正 codex M31 finding:HoverCard 非 modal,不該有 focus trap)
 
-**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+**驗證**:Storybook a11y addon panel 應 0 critical violation;WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。**注意鍵盤限制**:Radix HoverCard 會把 content 內所有 tabbable node 強制設 `tabindex="-1"`,故卡片**內部**的按鈕 / 連結鍵盤 Tab 到不了 — 鍵盤使用者僅能 focus trigger 開卡 + Esc 關卡,無法進入卡片操作互動內容。關鍵互動勿放 HoverCard 內(見「禁止事項」),需鍵盤可達的互動浮層用 Popover(click 觸發)。
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `avatar.spec.md`
 - `carousel.spec.md`
 - `coachmark.spec.md`
-- `overflow-indicator.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
 - `motion.spec.md`
+- `overflow-indicator.spec.md`
+- `popover.spec.md`
+- `profile-card.spec.md`
+- `tooltip.spec.md`