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

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/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/number-input.spec.md

@@ -0,0 +1,126 @@
+---
+component: NumberInput
+family: 4
+variants: {}
+sizes: {}
+traits:
+  - hasInteractiveStates
+  - isInputLike
+benchmark:
+  - Ant Design InputNumber: github.com/ant-design/ant-design/tree/master/components/input-number
+  - MUI TextField (number): github.com/mui/material-ui/tree/master/packages/mui-material/src/TextField
+---
+
+# NumberInput 設計原則
+
+## 定位
+
+NumberInput 是**數值的**輸入與顯示元件。格式化邏輯：`toLocaleString()` + prefix/suffix + precision。
+
+共用規則見 `../Field/field-controls.spec.md`。本文件只記錄 NumberInput 特有的原則。
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 4（Field control layout）** 消費者。結構繼承 `components/Field/field-controls.spec.md` 的 `fieldWrapperStyles + [startIcon?] [<editable>] [endAction?]` 規格,視覺對齊 Family 1（Menu item）讓 SelectMenu trigger + options 連續一致。
+
+---
+
+## 何時用
+
+- **所有數值資料**：金額、數量、百分比、比率、測量值、年齡、計數
+- **需要格式化的 value**：千分位（`1,234,567`）、貨幣前綴（`$2,490`）、百分比後綴（`85.5%`）、小數精度（`0.00`）
+- **需要 locale-aware 顯示**（`toLocaleString()` 自動處理千分位分隔符、小數點形式）
+- **DataTable 的數值欄位**（right-aligned + 自動格式化）
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 純文字 / 看起來像數字的字串（電話、郵遞區號）| `Input` | 電話不是算術型數字，不需要千分位 / 不該用 step |
+| 日期 / 時間戳 | `DatePicker` | 需要日期語意和 picker 互動 |
+| 視覺調整數值（音量、亮度、滑動調整）| `Slider` | 使用者目標是「感受」而非「輸入精確值」 |
+| 大量帶小數的科學計算 | `Input` + 自訂驗證 | 極端精度需求超出 NumberInput 格式化能力 |
+
+---
+
+## 格式化選項
+
+| 選項 | 說明 | 範例 |
+|------|------|------|
+| `prefix` | 前綴字串（如貨幣符號） | `$2,490` |
+| `suffix` | 後綴字串（如百分比） | `85.5%` |
+| `precision` | 小數位數 | `85.50` |
+| `locale` | 數字格式 locale | 預設 `en-US` |
+
+## 對齊
+
+- **Edit 模式（input）**：靠左——input 內打字是左到右
+- **Table cell（Display）**：靠右——縱向比較位數需要右對齊（由 DataTable 的 column type `number` / `currency` 控制）
+
+## Display
+
+`<NumberInput mode="display">` 在 table cell 和 Form readonly 共用 `formatNumber()` 格式化函式。
+
+- 有值：格式化輸出（prefix + localized number + suffix）
+- null / undefined：`—`（em dash），`text-fg-muted`
+
+## DataTable 整合
+
+```tsx
+// 自動格式化——不需要手寫 cell
+col.accessor('price', {
+  header: 'Price',
+  meta: { type: 'currency', prefix: '$' },
+})
+```
+
+`currency` 類型預設 `prefix: '$'`，其餘等同 `number`。
+
+---
+
+## Mode / Validation / a11y
+
+詳見 `../Field/field-controls.spec.md`(Mode / Validation)+ `../Field/form-validation.spec.md`(驗證時機)。
+
+---
+
+## 禁止事項
+
+- ❌ 不要拿 NumberInput 顯示電話 / 郵遞區號 / 身分證號(非算術型數字)— 用 `Input`(電話千分位無意義 / step 不適用)
+- ❌ 不要把 `precision` 設超過 6(浮點精度雜訊)— 極端精度需求超出格式化能力,改用 `Input` + 自驗證
+- ❌ 不要在 DataTable cell 用左對齊 NumberInput(縱向比較位數需右對齊)— 走 DataTable column type `number` / `currency` 預設右對齊
+- ❌ 不要把 `prefix='$'` 跟 `suffix='元'` 同時用 — 貨幣語意衝突,擇一即可
+- ❌ 不要拿 NumberInput 做百分比但 value 存 0–1(`0.85` × 100 = 85%)— DS canonical 是 value 直接存百分比數值(85),`suffix='%'` 純顯示
+- ❌ 不要自加 step ↑↓ button — Native `<input type="number">` 已支援(若顯示則由 spec 統一決定外觀,目前 hide 避免視覺雜訊)
+
+---
+
+## 邊界案例
+
+- **Disabled**:由 Field SSOT own(`Field/field-controls.spec.md` State machine 段)。視覺:wrapper bg → `bg-fg-disabled-subtle`、formatted text → `text-fg-disabled`(M24 state>emphasis)、step ↑↓ button(若有)自動 disabled 不可點。Display mode + disabled 維持格式化輸出但 token 切 disabled。
+- **Loading**:走 Field SSOT 的 `loading?: boolean`(`field-controls.spec.md` L70-115);endAction slot 自動切 `<CircularProgress/>` + `aria-busy="true"`,input 仍可編輯。
+- **Empty(null / undefined / 空字串)**:Display mode 渲 `—`(em dash + `text-fg-muted`);Edit mode placeholder 走 default placeholder color。
+- **Invalid input**(non-numeric):由 native `<input type="number">` + Field validation 處理,渲 error variant(`aria-invalid="true"` + `text-fg-error` border + 下方 error message)。
+- **Dark mode / density**:走 Field SSOT,不獨立 own。
+
+---
+
+## 相關
+
+- `../Input/input.spec.md` — 純文字（含電話 / 郵遞區號等「看起來像數字」的資料）
+- `../DatePicker/date-picker.spec.md` — 日期
+- `../Slider/slider.spec.md` — 視覺調整數值（音量、亮度）
+- `../Field/field-controls.spec.md` — Field Control 共用規則（mode / size / endAction / error）
+
+## A11y 預設
+
+**ARIA / Pattern**:native `<input>` element 預設 a11y;Field wrapper 補 `aria-labelledby` / `aria-invalid` / `aria-describedby`。
+
+**Keyboard 行為**:
+
+- Tab — focus
+- ↑/↓ — 加 / 減 step
+- 字母鍵 — 輸入數字
+
+**Focus**:native input focus ring;DS focus-visible ring(`focus-visible:!border-primary`)由 Field wrapper 提供。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+

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

@@ -0,0 +1,120 @@
+---
+component: OverflowIndicator
+family: self-contained
+variants: {}
+sizes: {}
+traits:
+  - isInternal
+benchmark:
+  - Radix ScrollArea primitive: github.com/radix-ui/primitives/tree/main/packages/react/scroll-area
+---
+
+# OverflowIndicator 設計原則
+
+## 定位
+
+OverflowIndicator 是 **`+N` 溢出指示器 + HoverCard 顯示隱藏內容**——當 row / container 中的項目無法全部顯示時,剩餘項目以 `+N` 形式提示,hover 展開完整清單。
+
+**實作基礎**:自建 internal primitive——消費 HoverCard + tagVariants,無直接 external primitive base。
+
+**Layout Family**:非上述 family — self-contained Tag-like primitive(自帶 `+N` 計數、單一 trigger pill + hover 展開 popover,無 prefix / content / suffix 的 slot 結構;視覺尺寸對齊 Tag family 但不屬 Family 1-4 的任何 row 結構)。
+
+---
+
+## 何時用 / 何時不用
+
+**OverflowIndicator 是 internal primitive**——由需要處理「溢出 +N」的元件消費，不直接使用。
+
+| 場景 | 正確做法 |
+|------|---------|
+| Combobox 多選 tag 溢出 | `Combobox` 單行模式內部消費 OverflowIndicator |
+| Tabs 水平溢出 | `Tabs` 內部消費（搭配 `horizontal-overflow` pattern）|
+| Avatar stack 溢出（「+3 more」）| Avatar.Group（未來）內部消費 |
+| 人員列表行尾 +N | 列表元件自行組合 OverflowIndicator + PersonDisplay |
+| 直接在 JSX 用 `<OverflowIndicator>` | 僅當消費者是自訂 list / custom overflow pattern 時 |
+
+---
+
+## 為什麼用 HoverCard 而非 Tooltip
+
+溢出內容**可能需要互動**——而非純文字提示：
+
+- **人員 +N**：hover 清單中每個人可能需要 tag dismiss 或 hover 該人再看 NameCard（nested HoverCard）
+- **Tag +N**：hover 清單中每個 tag 可能需要個別 dismiss
+- **一般 +N**：穩定顯示、使用者可把滑鼠移到浮層上閱讀
+
+Tooltip 純文字、不可互動、滑鼠離開 trigger 即消失——不適合承載這些需求。
+
+### trigger 不用 Tag 元件
+
+Tag 內建 truncation Tooltip 會跟 OverflowIndicator 的 HoverCard 衝突。改用 `tagVariants` 直接套樣式，保持視覺一致但不含 Tag 的額外行為。
+
+---
+
+## 尺寸
+
+| Size | Trigger 高度 | 文字 |
+|------|------------|------|
+| sm | `h-5 min-w-5`（20px）| `text-[10px]` |
+| md | `h-6 min-w-6`（24px）| `text-caption` |
+| lg | `h-6 min-w-6`（24px）| `text-caption` |
+
+sm / md 跟 Tag 同階（20/24px），lg 對齊 md（尺寸需求一致，不需要再大）。
+
+**sm 用 `text-[10px]` 的理由**：sub-footnote 特殊例外,與 Badge 共享「micro-indicator typography」tier——trigger 數字是次要輔助 indicator（非主訊息）,在 20px 小容器內 12px 會擠。完整理由與 pattern-family 說明詳見 `badge.spec.md`「字體例外：`text-[10px]`」。若未來 OverflowIndicator / Badge 以外的元件也需要 sub-footnote 尺寸,應在 typography system 加 `--font-micro` token,再改用 token 而非 arbitrary value。
+
+---
+
+## 禁止事項
+
+- ❌ 用 Tooltip 取代 HoverCard——溢出內容可能需要互動
+- ❌ trigger 用 Tag 元件——Tag 內建 Tooltip 會跟 HoverCard 衝突
+- ❌ 省略 `+N` 指示器（直接截斷隱藏）——使用者無法知道「還有多少被隱藏」
+- ❌ 在 HoverCard 內再嵌 Tooltip——tooltip 是資訊終點，不可巢狀
+
+---
+
+## 為何無 ColorMatrix / StateBehavior
+
+OverflowIndicator 是**承載 count + HoverCard 的 trigger primitive**,無獨立色彩與互動狀態變體:
+
+- **無 ColorMatrix**:trigger 只有 neutral 一種色彩(`circle` 用 `bg-muted` / `tag` 用 `tagVariants` 的 neutral),無 variant 色彩選項——OverflowIndicator 是結構 primitive,色彩屬於 consumer 決策(若需要色相,trigger 的外框 / 內容由 consumer 包)。
+- **無 StateBehavior**:trigger 只有 passive display(`cursor-default`),hover 只觸發 HoverCard 開啟,本身無 hover / active / disabled / selected 變化——互動狀態屬於 HoverCard trigger 行為(見 `hover-card.spec.md`),不屬 OverflowIndicator 層級。
+
+對應 anatomy story:保留 `Overview` / `Inspector` / `SizeMatrix`,額外追加元件特有的 `ShapeMatrix`(取代 ColorMatrix 展示 circle vs tag 兩種形狀變體)。
+
+---
+
+## shadcn passthrough 例外說明
+
+OverflowIndicator 是 **composite**(HoverCard trigger + tag-styled `+N` span + HoverCard content + rendered chips list),純 declarative API(`items` array + `visibleCount`)。**不套 `forwardRef` / `...props` spread**:
+
+- **沒有單一 DOM root 可 ref**:consumer 期待 ref 指向「`+N` trigger」還是「HoverCard content」?兩者都不對——前者在 hover 前才出現(conditional),後者在 portal(DOM 離散)
+- **`...props` 無明確 spread 目標**:composite 無 identity root wrapper
+- **API 邊界明確優先於 DOM 控制**:OverflowIndicator 暴露「溢出計數 + hover 展開」語意,DOM 細節留給底層 HoverCard / Tag
+
+若 consumer 需要程式化控制(trigger refs / custom Portal),應改用 HoverCard + Tag 自組,不透過 OverflowIndicator。`displayName = 'OverflowIndicator'` 保留。
+
+---
+
+## 相關
+
+- `../HoverCard/hover-card.spec.md` — 浮層容器（OverflowIndicator 消費）
+- `../Tag/tag.spec.md` — trigger 的 `tagVariants` 樣式來源
+- `../Combobox/combobox.spec.md` — 主要消費者（多選溢出）
+- `../../patterns/horizontal-overflow/horizontal-overflow.spec.md` — 水平溢出 pattern（OverflowIndicator 是其中的「menu 模式」trigger）
+- `../Avatar/avatar.spec.md` — Avatar stack 溢出場景（未來消費者）
+
+## A11y 預設
+
+**ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 pattern。
+
+**Keyboard 行為**:
+
+- Tab — focus indicator
+- Enter — show overflow menu
+
+**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)。
+