@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

package/src/components/Menu/menu-item.spec.md

@@ -0,0 +1,283 @@
+---
+component: MenuItem
+family: 1
+variants: {}
+sizes:
+  sm: {}
+  md: {}
+  lg: {}
+traits:
+  - hasInteractiveStates
+  - isInternal
+benchmark:
+  - Radix Menu primitive: github.com/radix-ui/primitives/tree/main/packages/react/menu
+  - Ant Design Menu: github.com/ant-design/ant-design/tree/master/components/menu
+  - Polaris ActionList: github.com/Shopify/polaris/tree/main/polaris-react/src/components/ActionList
+---
+
+# MenuItem 設計原則
+
+## 定位
+
+MenuItem 是所有 menu 類元件的**共用視覺佈局層**——處理 prefix 對齊、尺寸、狀態。SelectMenu、DropdownMenu、未來的 ContextMenu 等都消費它。它只負責 layout（padding、gap、prefix alignment、typography），互動行為由各 menu 的 Radix primitive 外層控制。
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 1（Menu item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「Menu item layout」章節的 scanning-mode 規格。
+
+---
+
+## 結構
+
+```
+prefix                       content               suffix
+[checkbox?] [icon? | avatar?]  [label + description?]  [tag?]
+```
+
+- **Prefix**：checkbox（多選，由父層注入）+ startIcon 或 avatar（互斥）
+- **Content**：label + 可選 description
+- **Suffix**：tag（ml-auto 靠右）
+
+prefix icon 跟 label 同色（foreground），不是 fg-muted。詳見 item-anatomy.spec.md 的 Icon 色彩原則。
+
+---
+
+## Prefix 對齊——24px 閾值
+
+所有 prefix 元素（checkbox、icon、avatar）共享同一個對齊容器。容器高度決定對齊行為：
+
+| prefix 最大高度 | 容器 | 對齊目標 |
+|---|---|---|
+| ≤ 24px | `h-[1lh]` | 第一行 label 的垂直中心 |
+| > 24px | `h-[calc(1lh+var(--item-gap-label-desc)+desc_1lh)]` | label + gap + description 文字塊的垂直中心 |
+
+**SSOT**:對齊公式封裝於 `patterns/element-anatomy/item-anatomy.tsx` 的 `itemPrefixAlignVariants`(2026-04-23 重構)。MenuItem 消費此 primitive,不自建對齊邏輯;改 gap token(`--item-gap-label-desc`)或 font-size token 一處 → MenuItem 自動同步。
+
+**24px 是物理限制**——16px icon 在 24px 圓內仍可辨識(內部 icon 下限 12px),但在更小的容器中 icon 會低於可讀閾值。
+
+**無 description 時 prefix 上限 24px**——沒有文字塊可對齊,強制 inline。
+
+多行文字超過參考高度時，外層 `items-start` 讓 prefix Y 不隨文字下移。
+
+---
+
+## startIcon vs avatar
+
+| | `startIcon` | `avatar` |
+|---|---|---|
+| 型別 | `LucideIcon` | `AvatarData` |
+| 角色 | **描述**選項的性質（形容詞） | **代表**選項的身份（名詞） |
+| 尺寸 | 16/20px（icon tier，元件控制） | 由 description 決定：無 desc → 20/24/24px，有 desc → 32/32/40px |
+| 對齊 | 永遠 inline（≤ 24px） | 無 desc → inline；有 desc → block |
+
+### avatar 尺寸推導
+
+inline（無 description）= 對應 size 的 Tag 高度：
+
+| sm | md | lg |
+|---|---|---|
+| 20px | 24px | 24px |
+
+block（有 description）= `floor₈(1lh + 2px + desc_1lh)`：
+
+| sm | md | lg |
+|---|---|---|
+| 32px | 32px | 40px |
+
+---
+
+## Size
+
+單行高度對齊 field-height token，與 Button、Input 等互動元件等高。
+
+| Size | 高度 | Label | Description | Icon | Checkbox |
+|---|---|---|---|---|---|
+| sm | `h-field-sm` | `text-body leading-compact` | `text-caption` | 16px | 16px (sm) |
+| md | `h-field-md` | `text-body leading-compact` | `text-caption` | 16px | 16px (md) |
+| lg | `h-field-lg` | `text-body-lg leading-compact` | `text-body leading-compact` | 20px | 20px (lg) |
+
+所有文字使用 `leading-compact` (1.3)——選單選項是短文字，不需要閱讀行距。
+
+description 降一級：sm/md 的 label 14px → description 12px；lg 的 label 16px → description 14px。
+
+---
+
+## Suffix 對齊(實作限制)
+
+依 `item-anatomy.spec.md` 的對齊規則,suffix 應該套用 24px 閾值公式(跟 prefix 同公式但獨立判斷)。但 **MenuItem 的實作把 suffix 寫死成 `h-[1lh]` inline 對齊**——只支援 ≤24px 的小 suffix(Tag、ChevronRight、Badge、計數)。
+
+### 為什麼 hardcode
+
+選單選項的 suffix 99% 是小元素,不會超過 24px。為了避免每個 consumer 都要思考 suffix 對齊規則,MenuItem 直接套用最常見的 inline 對齊。
+
+### 限制
+
+如果你要塞大塊 suffix(thumbnail 40px、stacked badge、multi-line text),**MenuItem 會把它對齊到 label 第一行而不是文字塊中心**,視覺上會跟它修飾的對象失聯。
+
+### 解法
+
+需要大塊 suffix 的場景應該:
+
+1. **重新評估這個東西是不是 menu item**——如果 suffix 是大塊內容,可能需要 ListItem(列表行)而非 menu item
+2. **包一個 wrapper 元件**——consumer 自己組合 prefix + content + 大塊 suffix,套用 item-anatomy.spec.md 的完整 4-slot 規則
+3. 不要 hack `endContent` 塞大東西進去——layout 會壞
+
+---
+
+## Clamp 政策(Label / Description 行數)
+
+| Prop | 預設 | 理由 |
+|---|---|---|
+| `labelMaxLines` | `1` | 選項是供快速掃視的短文字，必須在一行內辨識完 |
+| `descMaxLines` | `1` | 與 label 對稱，維持掃視節奏；description 是補充說明，不是閱讀內容 |
+
+**為什麼 description 也預設 1 行?**
+
+Menu 的設計目的是「**快速掃視多個選項挑一個**」。垂直空間是寶貴的——選單通常要塞 5–20 個選項。如果 description 沒有 clamp,一個過長的 description 會把 item 撐高,破壞 row rhythm,使用者眼睛要重新校準。
+
+整個選單應該只有「**兩種 row 高度**」:
+- 無 description → `field-height`(單行 label)
+- 有 description → `field-height` + 2px + 一行 desc 高度
+
+不能讓 row 高度變成「label 1 行 + desc 1~N 行」這種不可預測的範圍。
+
+**Per-instance override**:consumer 若有合理理由(例如 settings 選單想顯示 2 行說明),可以顯式 `<MenuItem descMaxLines={2} ...>` 覆寫。要顯示完整不截,傳 `descMaxLines="none"`(不能傳 `undefined`,React props 的 destructure default 在 undefined 時會接管,fallback 到預設 `1`)。
+
+---
+
+## 狀態
+
+| 狀態 | 背景 | 文字 | 觸發方式 |
+|---|---|---|---|
+| default | transparent | foreground | — |
+| hover | `--neutral-hover` | foreground | 滑鼠 hover |
+| selected（單選） | `--neutral-selected` | foreground | bg 高亮（不用 ✓ 勾號，避免影響 prefix 對齊） |
+| selected（多選） | transparent | foreground | checkbox 勾選 |
+| disabled | transparent | `--fg-disabled` | disabled prop |
+
+### 選中指示器
+
+| 模式 | 選中指示器 |
+|---|---|
+| 單選 | `bg-neutral-selected` 背景高亮 |
+| 多選 | Checkbox 勾選 |
+
+單選和 DropdownMenu RadioItem 統一用 `bg-neutral-selected`。不用 ✓ 勾號——勾號在 prefix 會影響群組內對齊。
+
+disabled 時所有元素（icon、checkbox、文字）統一 `fg-disabled`。
+
+### 浮層關閉行為
+
+| 模式 | 選了之後 | 原因 |
+|---|---|---|
+| 單選 | **關閉浮層** | 選完就結束 |
+| 多選 | **不關閉** | 需要繼續勾選 |
+| DropdownMenu CheckboxItem | **不關閉** | 同多選邏輯 |
+| DropdownMenu 一般 Item | **關閉** | 執行動作後結束 |
+
+### Prefix icon 色彩
+
+Menu item 的 prefix icon 跟 label 同色（foreground），不是 fg-muted。Prefix icon 是 label 的視覺延伸。
+
+詳見 `item-anatomy.spec.md` 的 Icon 色彩原則。
+
+---
+
+## Group
+
+群組由 `MenuGroup` 包裹，`py-2`（8px）上下內距。群組緊鄰群組，無額外間距。
+
+### Group Header
+
+`header` prop 讓 item 變為群組標題：
+- `font-medium` (500)
+- `text-fg-muted` (neutral-7)
+- 不可選、不可 hover
+- 尺寸與一般 item 相同
+
+---
+
+## Footer（多選）
+
+`MenuFooter` 提供固定底部區域（`border-t` + `py-2`）。
+
+典型用途：「全選」checkbox item，使用 `checked="indeterminate"` 在部分選中時顯示 minus 圖示。
+
+---
+
+## 禁止事項
+
+- ❌ `startIcon` 和 `avatar` 不可同時使用
+- ❌ 無 `description` 時不可使用 > 24px 的 avatar
+- ❌ disabled item 不可有 hover 效果
+- ❌ disabled item 內的所有子元件（icon、checkbox、文字）都必須呈現 disabled 狀態——fg-disabled 統一，checkbox 用 disabled 樣式
+- ❌ header item 不可被選中
+- ❌ 不在 item 內放獨立互動元素（如 Button）——item 本身就是互動單位
+
+---
+
+## 何時用 / 何時不用
+
+**MenuItem 是 internal primitive**——不直接使用，透過 `SelectMenu` / `DropdownMenu` 等外層 menu 元件消費。
+
+| 場景 | 正確做法 |
+|------|---------|
+| 建立操作選單（複製 / 刪除 / 分享）| 用 `DropdownMenu` + `DropdownMenuItem`（內部消費 MenuItem）|
+| 建立選值下拉（選項 + 搜尋）| 用 `SelectMenu`（內部消費 MenuItem）|
+| 建立右鍵選單 | 用未來的 `ContextMenu`（待開發）|
+| 直接在 JSX 中用 `<MenuItem>` | ❌ **禁止**——會失去 menu 外層的 Radix 無障礙 / 鍵盤 / 焦點管理 |
+
+### 消費者
+
+- `../SelectMenu/select-menu.tsx` — 下拉選單浮層
+- `../DropdownMenu/dropdown-menu.tsx` — 操作選單
+- 未來：ContextMenu、CommandPalette
+
+---
+
+## 為何無獨立 StateBehavior story
+
+MenuItem 的狀態色(default / hover / selected / disabled)是**結構性的**——透過 variant(single / multi)× state 的二維矩陣呈現比時序互動更清楚。已在 `ColorMatrix` 用 TOKEN_MAP 完整矩陣覆蓋(單選 multi / 多選 single 各自的 4 state × bg / text / icon / desc token 對照)。
+
+獨立 StateBehavior story 會複製 ColorMatrix 內容——MenuItem 的 state 本身就是色彩表達,無額外「時序 / 動畫」可獨立呈現(不像 Accordion 有 expand/collapse 行為)。Inspector 已互動式展示 selected / disabled 單一 variant 的切換。
+
+對應 anatomy story:保留 `Overview` + `Inspector` + `ColorMatrix`(含完整狀態色矩陣) + `SizeMatrix`。
+
+---
+
+## 邊界案例
+
+- **Disabled**:`disabled` prop 由 MenuItem primitive own;視覺 `text-fg-disabled`(neutral-6,M24 state>emphasis)、無 hover bg、`aria-disabled="true"`、Enter / click 不觸發 onSelect、鍵盤導覽自動 skip(由 consumer SelectMenu / DropdownMenu / cmdk 處理)。已在「選擇 / 狀態視覺規則」段 codify。
+- **Loading**:MenuItem 為單一 row primitive 非 async surface,本身不擁有 loading prop。Async option list 的 loading 由 consumer(SelectMenu / Combobox / DropdownMenu)在 list body 替換為 `<Empty icon={<CircularProgress/>}/>`(SelectMenu SSOT)。
+- **Empty(label-only / icon-only)**:label 為必傳;若無 prefix icon / avatar / checkbox,layout 自動收斂為 `[label] [suffix?]`;若無 suffix(shortcut / endAction / chevron),收斂為純 `[label]`。
+- **Dark mode**:走 semantic token 自動 adapt。
+- **Density**:`size` 由 consumer menu(`Menu` block-tier `compact` / `reading`)決定 row height + padding,MenuItem 自身不持 density state。
+
+---
+
+## 相關
+
+- `../../patterns/element-anatomy/item-anatomy.spec.md` — MenuItem 的 row primitive 繼承規則（prefix / label / suffix 對齊）
+- `../Avatar/avatar.spec.md` — Prefix 的 Avatar 尺寸
+- `../Checkbox/checkbox.spec.md` — CheckboxItem 的視覺規則（DropdownMenu 使用）
+- `../SelectMenu/select-menu.spec.md` — 主要消費者之一
+- `../DropdownMenu/dropdown-menu.spec.md` — 另一個主要消費者
+
+## A11y 預設
+
+**ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。
+
+**Keyboard 行為**:
+
+- Tab — focus container
+- ↑/↓ — 導覽 items
+- Enter — activate
+- Esc — 關閉(若在 menu context)
+
+**Focus**:focus-visible ring 對齊 DS canonical(`outline: 2px solid var(--ring)`);focus management 由元件 own。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `opacity.spec.md`

package/src/components/NameCard/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 './name-card'

package/src/components/NameCard/name-card.spec.md

@@ -0,0 +1,171 @@
+---
+component: NameCard
+family: composite
+traits:
+  - isInternal
+variants: {}
+sizes: {}
+benchmark:
+  - Polaris MediaCard: github.com/Shopify/polaris/tree/main/polaris-react/src/components/MediaCard
+  - MUI Card: github.com/mui/material-ui/tree/master/packages/mui-material/src/Card
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# NameCard 設計原則
+
+人員 HoverCard 的內容元件。提供統一的人員資訊展示格式，作為 HoverCard 的 content 消費者。
+
+**實作基礎**：組合元件——Avatar + Text + Button 配 HoverCard 浮層。NameCard 本身不含觸發或定位邏輯（那是 HoverCard 的職責），只是 HoverCard content 的標準人員模板。
+
+**Layout Family**:非上述 family — composite(Avatar prefix + text block + action suffix,組合自 HoverCard content 內部;跨 section 垂直堆疊由 `border-t border-divider` 分隔,不屬 Family 1-4 的任何單行結構)。
+
+---
+
+## 何時用
+
+- **Avatar hover 顯示人員詳情**：留言者 / 指派者 / 成員列表 hover 彈出詳細資訊
+- **@提及互動**：`@username` hover 顯示該使用者的 card
+- **團隊 / 成員快速預覽**：Settings 頁的成員列表、PR reviewer 清單的 hover 預覽
+- **需要快速動作的人員資訊**：NameCard 可放 CTA button（Message / Invite / Follow）
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 點擊進入人員 profile 頁 | `<a>` 或 Link | Navigation 不需 hover card 的浮層 |
+| 人員清單 row（不需要 hover 展開詳情）| `Avatar` + inline text | NameCard 是 hover content，list row 不需要 |
+| 單純顯示一個名字 | `Avatar` + `Text` | NameCard 是完整資訊卡，單名字用更輕量元件 |
+| 複雜人員表單（編輯角色 / 權限）| `Dialog` 或專用頁面 | NameCard 是快速預覽，不承載複雜互動 |
+
+## 結構
+
+NameCard 是**三層 chrome 結構**(2026-04-23 canonical):
+
+```
+┌─────────────────────────────┐
+│ HEADER(固定,shrink-0)       │  ← Profile(Avatar + Name + Subtitle)+ Actions(選用)
+├─────────────────────────────┤
+│ BODY(flex-1,可垂直捲動)      │  ← Status section(v12 conditional)+ Info fields(always-render)
+│ ↕ 空間不足時此區 ScrollArea   │    Status undefined → 整 status block skip
+├─────────────────────────────┤
+│ FOOTER(固定,shrink-0)       │  ← View more(hover context 必含,詳「View more canonical」)
+└─────────────────────────────┘
+```
+
+- **Header 固定**:Profile + Actions 一體,**不捲動**(使用者的視覺 anchor:誰 + 可對他做什麼)
+- **Body 可捲動**:Status section + Info fields。以 `<ScrollArea>` 包(cross-OS overlay 捲軸)
+- **Footer 固定**:View more **永遠可見**(hover preview 的 escape hatch 到完整 profile)
+
+**Status section v12 conditional rule(2026-05-14 user 拍板)**:`status` 在 production 一定會被設定(每個 user 都有 presence state)。如果 status undefined,**唯一可能性 = 資料還沒讀到(loading transient)**,**不**是「user 沒設定狀態」。所以 status undefined 期間 → **整 status block 隱藏**(等資料到才 render),**禁** render「Status not set」這種 placeholder 文字(語義錯,user presence 不會「沒設定」)。**此規則 NameCard-specific 不外推至 DS 其他元件**(FileItem / DescriptionList / DataTable cell 各自 placeholder 邏輯 unrelated)。
+
+**取消「精簡版」變體**:NameCard 只有**一種結構**,consumer 未傳的 section 不另開 minimal variant。世界級對照:Slack / GitHub / LinkedIn hover-profile 皆單一結構,不分「簡版/full 版」。
+
+**DS-wide PersonData 預設展示一致 canonical**:任何 PersonData 來源展示 NameCard 時,`description` / `fields` 預設都應提供;`status` / `statusMessage` opt-in(僅 loading transient 或 consumer mock data 才會缺,production data 必有)。
+
+Section 之間用 `border-t border-divider` 分隔(見 `separator.spec.md`「元件固定結構 → CSS border-t/b」)。詳細 class / padding token 見 `name-card.tsx`。
+
+<!-- 2026-05-18 D2 fix:width SSOT 統一 320(對齊 tsx `w-[320px]`)。本檔之前 L150 殘留「280px」自相矛盾已撤,只保留 L72 320 canonical。 -->
+
+**View more 按鈕 padding**:固定 `py-3`(12px),比 Body `py-3` 同位 — 讓 footer 有明顯呼吸空間,不跟 body section 邊界混淆。
+
+## 寬度（元件級常數）
+
+NameCard 固定 **320px 寬**（見 `.tsx` 的 `w-[320px]`）——HoverCard 浮層寬度由 NameCard 決定，不隨內容伸縮（避免 hover 時浮層寬度跳動）。
+
+對照世界級：Material Snackbar 固定 344px、Slack message modal 固定寬度——**單一元件的 canonical 寬度屬於該元件自己的 design spec，不抽為跨元件 token**。Token 系統只管共享值（如 `--field-height-*`、`--layout-space-*`）；單一元件獨有的結構常數留在 component code + 本 spec。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+## Action 行(2026-04-20 canonical)
+
+Action 區的 layout **永遠等寬均分容器寬度**——multiple actions 每個 Button 取相同 `1fr` 寬、single action 撐滿整個 NameCard width。實作 = `grid grid-flow-col auto-cols-fr gap-2` + `[&>*]:w-full` 強制每個 child fill grid cell。
+
+```
+[ Chat      ][ Audio call ▾ ]   ← 2 個 action:各 50%
+[     Message           ]       ← 1 個 action:100%
+[ Follow  ][ Message ][ ...]    ← 3 個 action:各 33%
+```
+
+**為什麼等寬均分**:
+- NameCard 是**人員關係卡**,action 是 relationship actions(Chat / Audio / Message / Follow)——這類動作視覺權重對等,無主次之分,等寬最直覺
+- Single action 撐滿讓「行動列」永遠占滿 card 底部,視覺節奏一致(不會「單一 button 孤零零縮在左邊」)
+- 世界級對照:iOS Contact card / macOS Contact / LinkedIn profile card / Slack profile modal 的 action row——全部等寬 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+**Consumer 跨 story / 跨 consumer 必須用同一組 canonical actions**:
+
+NameCard 的 default actions **是 `Chat + Audio call`**(chat app 標配,對齊 name-card.stories.tsx 的 `actionButtons` 常數)。story / principles / consumer code 不要每個範例改成不同 action——同一個元件在不同 demo 下出現 3 種不同 action 組合,讓 consumer 誤以為 action 會隨情境自動變。**例外**:要展示 single-action / 3-action 數量差異時才改,並明示「這是展示 action 數量變化」。
+
+## Profile Header
+
+- **Avatar**：透過 Avatar `status` prop 顯示狀態圓點（見 `avatar.spec.md`）
+- **Text column 對齊**：最小高度對齊 avatar 高度——短文字（單行名字）垂直置中於 avatar；長文字（多行名字 + subtitle）自然撐高
+- **字級層級**：Name > Subtitle；name 為 strong weight,subtitle 為 secondary color
+
+## Status 區
+
+非互動狀態標籤以 `bg-muted` 承載(不用 `bg-secondary`——Muted 視覺重量更低,對齊 Badge / Skeleton family)。狀態點顏色走 `--status-*` presence token(2026-04-20):`online` / `away` / `busy` / `offline`——跟 Avatar status 同源、獨立於 success/warning/error(presence 不是 validation state)。訊息必須包在 `<DescriptionList>` 內以 `<DescriptionItem>` 呈現(不可孤立 dt/dd),clamp 兩行避免無限伸展。
+
+## Info Fields
+
+使用 `DescriptionList cols={2}`，適合展示 ID、員工編號等短屬性。
+
+## View More
+
+`Button variant="link" size="sm" className="w-full"`——填滿容器寬度的文字按鈕。位於獨立的 bordered section（`border-t border-divider`），`py-2` 較緊湊。
+
+只在傳入 `onViewMore` callback 時顯示。
+
+## 設計決策
+
+- **固定寬度而非 min/max**：HoverCard 內容量可預期，固定寬度避免不同人員 card 寬度跳動
+- **Section 用 border-t 分隔**：清晰的資訊分區，每個 section 獨立存在或不存在
+- **Status badge 用 muted 而非 interactive 色**：狀態是展示資訊，不可點擊，不應暗示互動性
+
+---
+
+## 禁止事項
+
+- ❌ 不要在 HoverCard 外直接用 NameCard 當 standalone card——它不是獨立 Card primitive,是 HoverCard content 模板,缺少浮層外殼(radius / border / shadow)與定位邏輯。需要 card 佈局時用專屬元件或自組 Surface
+- ❌ 不要硬寫內部 Avatar size——NameCard Profile Header 的 avatar 尺寸由元件內部規格決定,consumer 覆寫會破壞 text column 對齊公式
+- ❌ 不要 override HoverCard `z-index` / `sideOffset` / `collisionPadding`——浮層行為由 `../HoverCard/hover-card.spec.md` + `../../patterns/overlay-surface/overlay-surface.spec.md` 管理,單獨 override 會破壞跨浮層的一致 stacking
+- ❌ 不要把非人員資料塞進 NameCard(例如檔案預覽、物件資訊)——NameCard 是人員專屬模板,語意不可挪用;其他 hover 詳情請自組 HoverCard content
+- ❌ Status section 的狀態點不要自訂色——走 `--status-online/away/busy/offline` presence token canonical,與 Avatar status 同源,改色會跨元件漂移
+- ❌ Action button 不要放動詞性 icon-only(例 Trash2 刪除)——NameCard actions 是關係型快速動作(Message / Invite / Follow),破壞性操作應走 Dialog confirm flow
+
+---
+
+## A11y 預設
+
+> 命名對齊 DS canonical(2026-05-18,per `# 命名與語言一致性`)。本節原標題「無障礙」,改「A11y 預設」與其他 spec 一致。
+
+- **Trigger 整合**:Avatar 作為 HoverCard trigger 時,`onFocus` / `onBlur` 與 mouseenter/leave 同時觸發由 Radix HoverCard 管理——鍵盤使用者 Tab 到 avatar 可自動顯示 card,Escape 關閉
+- **Focus 順序**:NameCard 內若有 Action button,Tab 順序為 trigger(Avatar)→ 第一個 action → 後續 action → view more;不抓取 focus 進入浮層(保留 Radix `HoverCard` 預設語意,與 Popover 的 focus trap 不同)
+- **Live region 語意**:NameCard 是展示內容,非 announcement,不套 `aria-live`
+- **DL 語意**:Info Fields 使用 DescriptionList(`<dl>/<dt>/<dd>`),screen reader 會讀成「term X, description Y」對話;詳見 `../DescriptionList/description-list.spec.md`「無障礙」段
+- **CTA button aria-label**:icon-only action button 必須帶 `aria-label`(「傳訊息給 {name}」「加入 {name} 為好友」),不只是 icon 視覺
+- **色彩對比**:Status badge `bg-muted` + `text-foreground` / Avatar status 圓點均通過 WCAG AA,不依賴單一色彩載體(搭配文字標籤)
+
+---
+
+## 為何無 Inspector / SizeMatrix
+
+- **無 Inspector**:NameCard 的決策維度是「section 組合」(avatar + profile / status / info / viewMore 的開關)——互動 Inspector 切換 toggle 可以做,但 `SectionMatrix` 的 side-by-side 矩陣(最簡 → 中 → full)對 consumer 的判斷更直接(「什麼 section 組合適合什麼 context」)。多維組合用矩陣呈現比單組合互動玩耍有效。
+- **無 SizeMatrix**:NameCard 固定 **320px 寬**(元件級常數,見本 spec「寬度」段),跨 consumer / variant 不變——人員資訊卡的 canonical width 屬於元件自身,不抽為 token。Section 高度由內容撐開,無 size tier。
+
+對應 anatomy story:保留 `Overview` + `SectionMatrix` + `ColorMatrix`(Status 色) + 元件特有 `HoverCardIntegration`(canonical usage pattern) + `StateBehavior`(空值 / 過長文字邊界)。
+
+---
+
+## 相關
+
+- `../HoverCard/hover-card.spec.md` — NameCard 的浮層容器（觸發與定位由 HoverCard 負責）
+- `../Avatar/avatar.spec.md` — Profile header 的身份視覺（Avatar 的 `hoverCard` prop 自動整合 NameCard）
+- `../Tooltip/tooltip.spec.md` — 純文字 hover 提示（NameCard 是可互動 hover content）
+- `../DescriptionList/description-list.spec.md` — Info fields 的 label / value 佈局
+- `../Button/button.spec.md` — Action button（Message / Invite 等 CTA）
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `people-picker.spec.md`
+- `tag.spec.md`

package/src/components/Notice/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 './notice'

package/src/components/Notice/notice.spec.md

@@ -0,0 +1,149 @@
+---
+component: Notice
+family: 2
+variants: {}
+sizes: {}
+traits:
+  - isInternal
+benchmark:
+  - Ant Design Alert: github.com/ant-design/ant-design/tree/master/components/alert
+  - Polaris Banner: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Banner
+  - Carbon Notification: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Notification
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# Notice 設計原則
+
+**Toast / Alert 共用的視覺佈局層**——跟 MenuItem 為 SelectMenu / DropdownMenu 共用是同一個架構概念。Notice 只負責 layout 和 icon 選擇，色彩由消費者透過 `data-theme` 控制。
+
+## 定位
+
+Notice 是純視覺 primitive，不是獨立使用的元件。消費者：
+- **Toast**：浮動 + 自動消失（Sonner）
+- **Alert**：inline / fixed 持久通知
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」章節的 reading-mode 規格。Notice 語意為 notification（非 row collection），但視覺排版遵循 Family 2 確保跨元件視覺一致。
+
+**尺寸偏離（documented exception）**：Notice / Alert / Toast **單一固定 size**，**不**實作 Family 2 baseline 的 sm/md/lg。世界級共識（Material Banner/Snackbar、Polaris Banner、Atlassian InlineMessage、GitHub Flash）都是**單一 prominent size**——通知的使命是「搶注意」而非「在密度選擇裡協調」，提供 size 選項反而會讓 consumer 糾結（該用哪個 size？）而稀釋元件的目的性。同理 padding 也不隨 density 變（`px-4 py-3` 固定）——通知是跨 density 一致的訊息載體。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+## Typography
+
+md tier，固定不隨 density 變：
+- title: `text-body`（14px）`leading-compact`（1.3）— 有 description 時加 `font-medium`
+- description: `text-body`（14px）`leading-compact` + `text-fg-secondary`（neutral-8）
+
+相同 body 字級,層級靠 font-weight / color 區分。
+
+## Padding（固定）
+
+| 屬性 | 值 | 理由 |
+|---|---|---|
+| px | `px-4`（16px） | 世界級系統共識（Atlassian/GitHub/Material/Linear 都是 16px） | <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+| py | `py-3`（12px） | 介於 row（7px）和 section（16px）之間，通知的 sweet spot |
+| gap | `gap-2`（8px） | 跟 item-layout icon-text gap 一致 |
+
+不隨 density 變——Toast/Alert 是通知，不是工作區域元件。
+
+## Layout
+
+item-layout 4-slot：
+```
+[status icon?]  [title + description?]  [endContent?]  [dismiss X?]
+```
+
+- Icon: 16px，`h-[1lh]` inline 對齊 first line
+- Dismiss X: `<Button iconOnly dismiss size="xs" />` — chrome corner action group region(Cat 3)。xs 是 **Notification banner family canonical**(Notice / Alert / Toast inherit):ephemeral banner `px-4 py-3` 固定不隨 density,dismiss 邊角小 affordance 輕量不搶眼。詳見 `patterns/overlay-surface/overlay-surface.spec.md`「Chrome dismiss size canonical — 三家族分類」+ `patterns/element-anatomy/item-anatomy.spec.md`「Dismiss canonical — X close only」
+- endContent: 通常放 `<Button variant="tertiary" size="xs">`
+
+## Variant
+
+| Variant | Icon | 語意 |
+|---|---|---|
+| neutral | 無 | 一般訊息 |
+| info | Info（ℹ） | 資訊提示 |
+| success | CircleCheck（✓） | 操作成功 |
+| warning | TriangleAlert（⚠） | 警告 |
+| error | XCircle（✕） | 錯誤 |
+
+## Theme 策略
+
+Notice **不設** bg 和 text color。消費者在 container 設 `data-theme` + `text-foreground`，Notice 內所有 token 自然適配。
+
+消費者的 data-theme 策略：
+
+| 場景 | data-theme | text 結果 |
+|---|---|---|
+| 有色相 solid（info/success/error） | `"dark"` | neutral-9 = 白 |
+| warning solid | `"light"`（永遠） | neutral-9 = 黑 |
+| neutral solid | `{inverse}`（跟頁反） | 跟隨翻轉 |
+| subtle | 不設（跟隨頁面） | 跟隨頁面 |
+
+### 為什麼 data-theme 要搭配 text-foreground
+
+CSS `color` 從 body 繼承的是**已解析的計算值**，不是 `var(--foreground)` 表達式。`data-theme` 改變 `--foreground` 的值，但不改 `color` 屬性。在 theme boundary 設 `text-foreground` class 強制 `color: var(--foreground)` 在正確 context 重新解析。
+
+## 何時用 / 何時不用
+
+**Notice 是 internal primitive**——不直接使用，透過 `Alert` / `Toast` 等外層通知元件消費。
+
+| 場景 | 正確做法 |
+|------|---------|
+| Inline / fixed 持久通知 | 用 `Alert`（內部消費 Notice）|
+| 浮動自動消失的短暫通知 | 用 `Toast`（內部消費 Notice + sonner）|
+| 直接在 JSX 中用 `<Notice>` | ❌ **禁止**——失去 Alert / Toast 外層的生命週期與定位管理 |
+
+### 消費者
+
+- `../Alert/alert.spec.md` — inline / fixed 持久通知
+- `../Toast/toast.spec.md` — 浮動非阻斷短暫通知
+
+---
+
+## 為何無 SizeMatrix / ColorMatrix
+
+Notice 是 **Toast / Alert 共用的 layout primitive**,刻意不擁有尺寸與色彩變體:
+
+- **無 SizeMatrix**:Notice / Alert / Toast **單一固定 size**(見本 spec「尺寸偏離」段),不實作 Family 2 baseline 的 sm/md/lg——通知的使命是「搶注意」而非「在密度選擇裡協調」。padding 固定 `px-4 py-3`,typography 固定 md tier(14px),不隨 density 變。
+- **無 ColorMatrix**:Notice 本身**不設 bg / text color**(見本 spec「Theme 策略」段),色彩完全由 consumer(Alert / Toast)透過 `data-theme` + `text-foreground` 控制。Notice 層級的色彩矩陣沒有意義——視覺對照屬於 consumer 的職責,應查 `alert.anatomy.stories.tsx` 與 `toast.anatomy.stories.tsx` 的 ColorMatrix。
+
+對應 anatomy story:保留 `Overview` / `Inspector` / `StateBehavior`,額外追加元件特有的 `VariantIconMap`(展示 5 種 variant 對應的 status icon + 語意)。
+
+---
+
+## 邊界案例
+
+- **Disabled(dismiss button)**:Notice 本身不擁有 disabled state(internal primitive,無互動);內嵌的 `<Button iconOnly dismiss size="xs" />` 自動繼承 Button disabled 視覺(`text-fg-disabled` + `cursor-not-allowed`)。Consumer(Alert / Toast)若需 disable dismiss,應透過 consumer-level prop pass-through。
+- **Loading**:Notice 非 async surface,無 loading state。Body 內若 consumer 注入 CTA Button,該 Button 自行處理 loading。
+- **Empty**:Notice 必有 title 或 description 其一(消費合約);無 title-only icon-less 形態,layout 至少 1 行內容。
+- **Icon-only / variant=neutral**:`neutral` variant 不渲 status icon,layout 自動收斂為 `[title + description?]  [endContent?]  [dismiss X?]` 三 slot。
+
+---
+
+## 相關
+
+- `../Alert/alert.spec.md` — 主要消費者（持久通知）
+- `../Toast/toast.spec.md` — 主要消費者（短暫通知）
+- `../../patterns/element-anatomy/item-anatomy.spec.md` — Notice 的 layout 共用規則
+- `../../tokens/color/color.spec.md` — color tokens 和 variant × theme 策略
+- `../../tokens/color/primitives.css` — primitives nested theme（`:root, [data-theme]` pattern）
+
+## A11y 預設
+
+**ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。
+
+**Keyboard 行為**:
+
+- Tab — focus dismiss button(若 dismissible)
+- Esc — dismiss(若 dismissible)
+
+**Focus**:focus-visible ring 對齊 DS canonical(`outline: 2px solid var(--ring)`);focus management 由元件 own。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+
+## 被引用(auto-maintained,Dim 3 reciprocal audit)
+
+> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
+
+- `bulk-action-bar.spec.md`
+- `coachmark.spec.md`

package/src/components/NumberInput/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 './number-input'