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

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

@@ -0,0 +1,145 @@
+// @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)。
+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 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">hover 看 Card</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">hover 看 Tooltip 樣式</Button>
+            </HoverCardTrigger>
+            <HoverCardContent className="bg-tooltip rounded-md px-3 py-2" data-theme="dark">
+              <div className="text-caption w-56">
+                深色樣式——常見於 OverflowIndicator 顯示溢出清單(+3 more 的 hover 展開)
+              </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 刻意不設角色語意 / aria-* 屬性(定位為 sighted-mouse-user 增強,卡片內容不暴露給輔助技術),只提供 hover / focus 開、Esc 關 + data-state。觸發元素的可聚焦性需 consumer 自補(例如 Avatar 的 hoverCard 在元件內手動加 tabIndex=0 + role=\"button\" + aria-haspopup=\"dialog\")。\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,222 @@
+// @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.
+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 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 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 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 不含視覺樣式——bg / border / shadow / padding 由 consumer 決定"
+        note="HoverCard 本身只提供 z-index、動畫、sideOffset。視覺由消費者(ProfileCard / OverflowIndicator / custom)各自決定,符合不同場景的視覺語言"
+      >
+        <div className="flex gap-6">
+          <HoverCard>
+            <HoverCardTrigger asChild>
+              <Button variant="tertiary" size="sm">亮色 Card 樣式</Button>
+            </HoverCardTrigger>
+            <HoverCardContent className="bg-surface-raised border border-border rounded-lg p-4 shadow-[var(--elevation-200)]">
+              <div className="w-48 text-body">ProfileCard 風格:亮底 + 邊框 + elevation</div>
+            </HoverCardContent>
+          </HoverCard>
+
+          <HoverCard>
+            <HoverCardTrigger asChild>
+              <Button variant="tertiary" size="sm">深色 Tooltip 樣式</Button>
+            </HoverCardTrigger>
+            <HoverCardContent className="bg-tooltip text-on-emphasis rounded-md px-3 py-2" data-theme="dark">
+              <div className="w-48 text-caption">OverflowIndicator 風格:深底 + compact</div>
+            </HoverCardContent>
+          </HoverCard>
+        </div>
+        <Label>↑ 同一個 HoverCard primitive 兩種視覺——consumer 根據場景選樣式</Label>
+      </Rule>
+
+      <Rule
+        title="Avatar 自動整合(建議 pattern)"
+        note="人員類 Avatar 透過 `hoverCard` prop 自動 wrap HoverCardTrigger,不需要 consumer 手動組合。統一人員 hover 提供 ProfileCard 的體驗"
+      >
+        <div className="flex items-center gap-3">
+          <Avatar 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 hoverCard prop 自動整合,無需手動 HoverCardTrigger</Label>
+      </Rule>
+    </div>
+  ),
+}

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

@@ -0,0 +1,167 @@
+---
+component: HoverCard
+family: composite
+variants: {}
+sizes: {}
+traits:
+  - isOverlay
+  - isInternal
+benchmark:
+  - Radix HoverCard primitive: github.com/radix-ui/primitives/tree/main/packages/react/hover-card
+  - Ant Design Popover: github.com/ant-design/ant-design/tree/master/components/popover
+---
+
+# HoverCard 設計原則
+
+## 定位
+
+Hover 觸發的**可互動浮層**，基於 Radix HoverCard。
+
+**實作基礎**：基於 Radix HoverCard——純行為 primitive，只提供觸發邏輯、定位、動畫，不含視覺樣式。
+
+**分類**：Internal primitive——consumer 不直接 import;由 Avatar(`hoverCard`)/ OverflowIndicator / ProfileCard 場景組合消費(frontmatter `isInternal`:root barrel 排除,storybook `Design System/Internal/HoverCard`)。
+
+- **是**：hover 顯示可互動內容（按鈕、連結、可選取文字）的浮層容器
+- **不是**：Tooltip（純文字提示、不可互動、hover 離開即消失）
+
+**Layout Family**：非上述 family — composite / multi-section（多區塊組合，自 own layout）。
+
+---
+
+## 何時用
+
+- **人員資訊卡**：Avatar hover 顯示 ProfileCard（姓名、角色、聯絡按鈕）
+- **溢出項目展開**：人員列表 `+N` hover 展示完整清單
+- **內容預覽**：連結 / 文件 hover 顯示標題 / 縮圖 / 摘要預覽
+- **不破壞當前畫面的補充資訊**：hover 可看細節，不 hover 也能使用主要介面
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 純文字提示（icon 用途、shortcut）| `Tooltip` | 見下「與 Tooltip 的分界」 |
+| 點擊觸發（非 hover） | `Popover` | HoverCard 觸發是 hover，點擊用 Popover |
+| 需要阻斷背景的流程 | `Dialog` | HoverCard 非阻斷、hover 離開自動消失 |
+| 關鍵資訊（必須被看到）| 直接顯示在畫面上 | 觸控裝置無法 hover，關鍵資訊不可只靠 HoverCard |
+
+---
+
+## 與 Tooltip 的分界
+
+兩者都是 hover 觸發，判斷用**互動性**和**內容性質**：
+
+| | HoverCard | Tooltip |
+|---|---|---|
+| 觸發 | hover | hover |
+| **內容可互動** | 是（按鈕、連結、hover 子元素） | 否（純文字） |
+| 停留行為 | 滑鼠移到浮層上不消失 | 滑鼠離開 trigger 即消失 |
+| 視覺樣式 | 由 consumer 決定（亮色 card 或深色 tooltip 風格皆可） | 統一深色背景 |
+| 典型用例 | ProfileCard、內容預覽、溢出清單 | icon 用途、shortcut、截斷文字補全 |
+
+**Fallback**：需要放按鈕 / 連結 → HoverCard；一句話純文字 → Tooltip。
+
+**本節是 HoverCard vs Tooltip 的 SSOT**，Tooltip spec 指回本節。
+
+## 純行為 primitive
+
+HoverCardContent 只提供：
+- `z-50`（浮層層級）
+- 進出場動畫（fade + zoom + slide，方向感知）
+- `sideOffset`（與 trigger 的間距）
+
+**不提供** `bg`、`border`、`shadow`、`padding`、`rounded`——consumer 根據場景自行決定：
+
+| Consumer | 視覺風格 |
+|---|---|
+| ProfileCard | 亮色 card（`bg-surface-raised` + `elevation-200` + `rounded-lg` + `border`） |
+| OverflowIndicator | 深色 tooltip 風格（`bg-tooltip` + `data-theme="dark"`） |
+
+## sideOffset
+
+預設 `8px`，與系統其他浮層（Tooltip、Popover）統一。
+
+## align
+
+**HoverCard 走「輕量浮層」例外**(見 `../Popover/popover.spec.md`「SSOT 適用範圍」)—— hover 觸發、預設展示為主、寬度隨內容自適應,Radix 預設 `center` 即可涵蓋絕大多數情境。`align` 由 consumer 視視覺需求自選(ProfileCard hover 常用 `start` 對齊 avatar 左邊緣),**不強制對齊 structured overlay 的 trigger-position canonical**。
+
+## 用途
+
+- **ProfileCard**：人員 Avatar hover 顯示詳細資訊
+- **Overflow person list**：溢出的人員列表 hover 展開
+- **Preview card**：內容預覽（文件、連結）
+
+## Avatar 整合
+
+Avatar 元件的 `hoverCard` prop 接受 HoverCard content，自動將 Avatar 包在 HoverCardTrigger 內。人員類 Avatar 應統一使用此 pattern 提供 hover 資訊。
+
+---
+
+## 為何無 Inspector / ColorMatrix / SizeMatrix / StateBehavior
+
+HoverCard 是**純行為 primitive**(只提供 hover 觸發邏輯 + 定位 + 動畫,不含視覺樣式),設計上刻意不擁有變體:
+
+- **無 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 元件(ProfileCard 的 section, OverflowIndicator 的 item)。
+
+對應 anatomy story:保留 `Overview` + 元件特有 `VisualVariants`(展示 primitive + consumer 視覺解耦的 hero story)。
+
+---
+
+## 禁止事項
+
+- ❌ 把關鍵資訊放在 HoverCard — 觸控裝置無 hover 能力,user 永遠看不到;關鍵 info 直接顯示或 Popover(click 觸發)
+- ❌ HoverCard 內塞表單 / 多步流程 — hover 離開可能誤關閉,複雜互動用 Dialog / Sheet
+- ❌ 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 角色不同
+
+## 常見誤解
+
+- 「HoverCard 內的按鈕鍵盤可達」——錯。Radix 把 content 內 tabbable node 設 `tabindex="-1"`,鍵盤使用者進不了卡片(見 A11y 預設);需鍵盤可達的互動浮層用 Popover
+- 「HoverCard = 大一點的 Tooltip」——錯。Tooltip 純文字不可互動;HoverCard 是 interactive surface(分界 SSOT 見上方)
+- 「觸控裝置也會開卡」——觸控無 hover;關鍵資訊不可只放 HoverCard(見禁止事項)
+
+## 邊界案例 / 空值
+
+- **重複快速 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）
+- `../ProfileCard/profile-card.spec.md` — 人員資訊卡（HoverCard 最常見 content）
+- `../Avatar/avatar.spec.md` — 人員 Avatar 自動 hoverCard 整合
+- `../Popover/popover.spec.md` — 點擊觸發的浮層(align canonical SSOT,本 spec「align」段引用)
+
+## A11y 預設
+
+**ARIA / Pattern**:Radix `hover-card` 刻意**不**設 `role` / `aria-*`,定位為 sighted-mouse-user 增強,content 不暴露給輔助技術(grep Radix source 0 命中 role/aria-*)。Radix 只提供:hover / focus 開、Esc 關 + `data-state`。Trigger 的可聚焦性需 consumer 自補(如 Avatar `hoverCard` 在 `avatar.tsx` 手動加 `tabIndex=0` + `role="button"` + `aria-haspopup="dialog"`)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/hover-card#accessibility)。
+
+**Keyboard 行為**:
+
+- Tab — 進入 trigger
+- Hover / focus — 開啟 card
+- Esc — 關閉
+
+**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)。**注意鍵盤限制**: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`
+- `motion.spec.md`
+- `overflow-indicator.spec.md`
+- `popover.spec.md`
+- `profile-card.spec.md`
+- `tooltip.spec.md`