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

package/src/components/Chip/chip.principles.stories.tsx

@@ -0,0 +1,228 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Chip, ChipGroup } from './chip'
+import { SegmentedControl, SegmentedControlItem } from '@/design-system/components/SegmentedControl/segmented-control'
+import { Badge } from '@/design-system/components/Badge/badge'
+import { Tag } from '@/design-system/components/Tag/tag'
+
+const meta: Meta = {
+  title: 'Design System/Components/Chip/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+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">{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>
+)
+
+// ── 定位與分界 ───────────────────────────────────────────────────────────────
+
+// ── WhenToUse — 何時使用 Chip ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / WhenNotToUse / VsSegmentedRule(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => {
+    const [langs, setLangs] = React.useState<string[]>(['js', 'ts'])
+    const [period, setPeriod] = React.useState('week')
+    return (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 Chip 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/Chip/展示" name="預設"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">技術文章列表的語言標籤濾鏡(多選)</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Chip/展示" name="帶 Badge"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">任務列表的狀態篩選 — Badge 顯示各狀態筆數</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Chip/展示" name="單選"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">程式語言擇一的單選濾鏡(type="single")</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見下方「vs 近親元件」段)。</p>
+    </div>
+
+      {/* vs 近親元件 — 原 VsSegmentedRule */}
+      <div>
+        <Rule
+          title="vs 近親元件 — Chip 是多選濾鏡(可選任意數量)"
+          note="Material Design Filter Chip 的實作:一排獨立 pill,可勾選任意組合。典型場景:技術文章列表的語言標籤濾鏡、商品列表的類別篩選、搜尋結果的多維度過濾"
+        >
+          <div>
+            <Label>✅ 部落格文章的語言濾鏡（可多選）</Label>
+            <ChipGroup type="multiple" value={langs} onValueChange={(v) => setLangs(v as string[])}>
+              <Chip value="js">JavaScript</Chip>
+              <Chip value="ts">TypeScript</Chip>
+              <Chip value="py">Python</Chip>
+              <Chip value="go">Go</Chip>
+              <Chip value="rs">Rust</Chip>
+            </ChipGroup>
+            <Label>↑ 目前選了 {langs.length} 種語言</Label>
+          </div>
+        </Rule>
+
+        <Rule
+          title="vs 近親元件 — 互斥單選(同時只能選一個)用 SegmentedControl"
+          note="2–5 個互斥選項、視覺要表達「連體」關係,用 SegmentedControl。Chip 各自獨立的視覺反而模糊了「只能選一個」的語意"
+        >
+          <div>
+            <Label>❌ 錯用：時間週期是互斥單選,卻用 Chip</Label>
+            <ChipGroup type="single" defaultValue="week">
+              <Chip value="day">日</Chip>
+              <Chip value="week">週</Chip>
+              <Chip value="month">月</Chip>
+            </ChipGroup>
+            <Label warn>↑ 改用 SegmentedControl（視覺連體 = 互斥語意更清楚）</Label>
+            <SegmentedControl value={period} onValueChange={setPeriod} className="mt-2">
+              <SegmentedControlItem value="day">日</SegmentedControlItem>
+              <SegmentedControlItem value="week">週</SegmentedControlItem>
+              <SegmentedControlItem value="month">月</SegmentedControlItem>
+            </SegmentedControl>
+          </div>
+        </Rule>
+
+        <Rule
+          title="vs 近親元件 — 純顯示、不可互動用 Tag"
+          note="Chip 是 control(選擇 / 未選),Tag 是 label(資訊標記)。商品卡上「新品 / 熱銷」是 Tag 不是 Chip"
+        >
+          <div className="flex items-center gap-2">
+            <Tag color="red">熱銷</Tag>
+            <Tag color="blue">新品</Tag>
+          </div>
+          <Label>↑ 純顯示用 Tag,不要誤用 Chip</Label>
+        </Rule>
+      </div>
+
+      {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
+      <div>
+      <Rule
+        title="何時不用 / 替代元件 — 加 dismiss X(再點一次 deselect 就是 dismiss)"
+        note="Filter chip 的「移除這個 filter」由 toggle(再點一次)承擔。加 X 等於同一動作有兩個 affordance,違反 Hicks's Law。Material 3 / Atlassian / Polaris filter chips 都不提供 X"
+      >
+        <Label warn>（範例省略）Chip 型別不提供 onRemove,設計上就擋住這個錯用</Label>
+      </Rule>
+
+      <Rule
+        title="何時不用 / 替代元件 — Chip 單獨使用,沒有 ChipGroup 包覆"
+        note="Chip 的選擇狀態由 Radix ToggleGroup 管理,沒 ChipGroup 會失去 keyboard navigation / a11y / state sync"
+      >
+        <Label warn>（範例省略）Chip 必須在 ChipGroup 內,對齊 RadioGroup / SegmentedControl 的結構</Label>
+      </Rule>
+    </div>
+    </div>
+    )
+  },
+}
+
+// ── Layout ────────────────────────────────────────────────────────────────
+
+export const LayoutRule: Story = {
+  name: '超出處理:換行 vs 捲動 vs 選單',
+  render: () => {
+    const [tagsW, setTagsW] = React.useState<string[]>(['react'])
+    const [tagsS, setTagsS] = React.useState<string[]>(['react'])
+    const [tagsM, setTagsM] = React.useState<string[]>(['react'])
+    const options = ['react', 'vue', 'svelte', 'angular', 'solid', 'qwik', 'ember', 'backbone', 'knockout']
+    const labels: Record<string, string> = {
+      react: 'React', vue: 'Vue', svelte: 'Svelte', angular: 'Angular',
+      solid: 'Solid', qwik: 'Qwik', ember: 'Ember', backbone: 'Backbone', knockout: 'Knockout',
+    }
+    return (
+      <div>
+        <Rule
+          title="wrap（預設）— filter panel / tag cloud"
+          note="塞不下換行,預設選擇。垂直空間充足,filter panel / 設定頁 tag 選取等場景"
+        >
+          <div className="max-w-md border border-border rounded-md p-3">
+            <ChipGroup type="multiple" value={tagsW} onValueChange={(v) => setTagsW(v as string[])}>
+              {options.map(o => <Chip key={o} value={o}>{labels[o]}</Chip>)}
+            </ChipGroup>
+          </div>
+          <Label>↑ 設定頁的技術選取 — 換行展示所有選項</Label>
+        </Rule>
+
+        <Rule
+          title="scroll — 單行 toolbar / header 必須固定高度"
+          note="垂直空間受限(toolbar / card header),橫向捲動 + fade mask 指示溢出。搭配左右 scroll arrow 給鍵盤和滑鼠使用者"
+        >
+          <div className="max-w-md border border-border rounded-md p-3">
+            <ChipGroup type="multiple" layout="scroll" value={tagsS} onValueChange={(v) => setTagsS(v as string[])}>
+              {options.map(o => <Chip key={o} value={o}>{labels[o]}</Chip>)}
+            </ChipGroup>
+          </div>
+          <Label>↑ 新聞網站的分類 toolbar — 固定高度,滑動看更多</Label>
+        </Rule>
+
+        <Rule
+          title="menu — 單行但要完整選項可見"
+          note="單行水平捲動,chip 全可見不隱藏;dropdown(ChevronDown)永遠列出全部 chip。對齊 Chrome tab dropdown / VS Code editor tabs 的「show all」pattern。menu 模式必須 controlled(value + onValueChange)"
+        >
+          <div className="max-w-md border border-border rounded-md p-3">
+            <ChipGroup type="multiple" layout="menu" value={tagsM} onValueChange={(v) => setTagsM(v as string[])}>
+              {options.map(o => <Chip key={o} value={o}>{labels[o]}</Chip>)}
+            </ChipGroup>
+          </div>
+          <Label>↑ ListView 工具列 — 單行 + ⋯ 展開全部選項</Label>
+        </Rule>
+      </div>
+    )
+  },
+}
+
+// ── 選中視覺 ─────────────────────────────────────────────────────────────
+
+export const SelectedStyleRule: Story = {
+  name: '選中狀態：文字 + 邊框 同染，不用背景強調',
+  render: () => (
+    <div>
+      <Rule
+        title="選中 = primary text + border，底色不變"
+        note="對齊 SegmentedControl / Tabs 的選中 canonical:primary 底色同時染文字和線條(瞬時 hover 用弱色、持續選中用強色)。用 bg 強調會讓 chip 看起來變成「按鈕」,混淆多選濾鏡的語意"
+      >
+        <ChipGroup type="multiple" defaultValue={['react', 'ts']}>
+          <Chip value="react">React</Chip>
+          <Chip value="vue">Vue</Chip>
+          <Chip value="ts">TypeScript</Chip>
+          <Chip value="js">JavaScript</Chip>
+        </ChipGroup>
+        <Label>↑ 選中(React / TypeScript)= primary 文字 + 邊框,底色仍 bg-surface</Label>
+      </Rule>
+
+      <Rule
+        title="badge suffix — 計數指示"
+        note="filter chip 常配計數:「React(24) / Vue(8)」,使用者看計數做決策。Badge 放在 chip 末端"
+      >
+        <ChipGroup type="multiple" defaultValue={['react']}>
+          <Chip value="react" badge={<Badge count={24} />}>React</Chip>
+          <Chip value="vue" badge={<Badge count={8} />}>Vue</Chip>
+          <Chip value="svelte" badge={<Badge count={3} />}>Svelte</Chip>
+        </ChipGroup>
+        <Label>↑ 文章列表的語言濾鏡,顯示每種語言有幾篇</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+// ── 禁止 ────────────────────────────────────────────────────────────────
+

package/src/components/Chip/chip.spec.md

@@ -2,7 +2,8 @@
 component: Chip
 family: 3
 variants: {}
-sizes: {}
+sizes:
+  sm: { when: "單一尺寸(h-field-sm 28/32 依 density、icon 16、text-body)— 對齊 chip.tsx componentMeta" }
 traits:
   - hasInteractiveStates
 benchmark:
@@ -11,16 +12,22 @@ benchmark:
   - Carbon Tag: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Tag
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
 
 # Chip 設計原則
 
 ## 定位
 
-Chip 是 **Material Design Filter Chip** 的實作——用於從多個選項裡**選取任意數量（多選）或單一選項（單選）**，視覺上是一排獨立的 pill。
-基於 Radix ToggleGroup，橋接設計系統 token。
+Chip 是 **Material Design Chips** 的實作(M3 taxonomy:https://m3.material.io/components/chips/guidelines),涵蓋兩個分支:
 
-**Layout Family**：CLAUDE.md 4-Family Model **Family 3（Pill Layout）action trigger sub-profile**。內部結構 `[startIcon?] [<span px-1>label</span>] [suffix badge? + endIcon?]` 繼承 Button canonical（code docblock 明寫「鏡射 Button」）。SSOT 在 `components/Button/button.spec.md`「Pill Layout」章節。Chip 特有視覺（`rounded-full`、單一固定 `h-field-sm` size、hover/selected 色彩規則）寫在本 spec 下方章節。
+- **filter(預設)**:從多個選項裡**選取任意數量(多選)或單一選項(單選)**,視覺上是一排
+  獨立的 pill。基於 Radix ToggleGroup,必須在 ChipGroup 內。
+- **assist(`variant="assist"`,2026-09-02 加;AgentPanel 附件拍板消費)**:**按鈕語意**——
+  點擊觸發動作,無 toggle、無 selected 態(M3「Assist chips」同上 URL);渲染 plain button,
+  **可獨立使用**。視覺與 filter 同款(單一 cva;差異是結構分支非視覺 variant)。
+
+兩分支都橋接設計系統 token。
+
+**Layout Family**：本元件是 `components/Button/button.spec.md`「Pill Layout」所擁有的 **Family 3（Pill Layout）action trigger sub-profile** 消費者。內部結構 `[startIcon?] [<span px-1>label</span>] [suffix badge? + endIcon?]` 繼承 Button canonical（code docblock 明寫「鏡射 Button」）。Chip 特有視覺（`rounded-full`、單一固定 `h-field-sm` size、hover/selected 色彩規則）寫在本 spec 下方章節。
 
 ---
 
@@ -82,11 +89,11 @@ Chip 是 **Material Design Filter Chip** 的實作——用於從多個選項裡
 
 Filter chip 的「移除這個 filter」動作已由「再點一次 deselect」承擔。加 dismiss X 等於同一動作有兩個 affordance，違反 Hicks's Law。Material 3 / Atlassian / Polaris filter chips 都不提供 dismiss。
 
-**需要 dismiss 的情境** = active filter token / 使用者輸入 token，那是 Input chip 的語意（走 `LinkInput` / `Tag` + `onDismiss` 路線），不是 Filter chip。
+**需要 dismiss 的情境** = active filter token / 使用者輸入 token，那是 Input chip 的語意（走 `LinkInput` / `Tag` + `onRemove` 路線），不是 Filter chip。
 
 ### 為什麼不需要 checkmark-on-selected
 
-Material 3 filter chip 在 selected 時會把 startIcon 換成 `Check`。我們不做，因為視覺層已經用 **primary-hover border + text + `primary-subtle` 背景**明確表達 selected 狀態，再加 icon 是冗餘信號。
+Material 3 filter chip 在 selected 時會把 startIcon 換成 `Check`。我們不做，因為視覺層已經用 **primary border + text（底色維持 surface 不變）**明確表達 selected 狀態，再加 icon 是冗餘信號。
 
 ---
 
@@ -94,7 +101,7 @@ Material 3 filter chip 在 selected 時會把 startIcon 換成 `Check`。我們
 
 Chip **只有一個 size**，對應 `h-field-sm`（md density 28px / lg density 32px）。
 
-對齊 Material 3 / Atlassian / Polaris / Ant Design 的世界級共識：chips 使用單一高度，不暴露 size prop。使用場景（filter bar、tag panel）高度一致，多 size 不增加表達力、只增加 API 負擔。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+Chip 使用單一高度，不暴露 size prop。既有使用場景（filter bar、tag panel）共享同一密度，多 size 不增加語意表達力，只會擴張 API 與組合分歧。
 
 **為什麼用 `--field-height-sm` 不用獨立 token**：chip 高度仍需 density 感知，沿用 `field-height-sm` 保證跟 Button / Input 的 density 節奏一致。若未來需要跟 form 高度解耦再新增 `--chip-height`。
 
@@ -106,18 +113,21 @@ Chip **只有一個 size**，對應 `h-field-sm`（md density 28px / lg density
 
 | State | 樣式 |
 |---|---|
-| **Default** | `bg-surface border-border text-foreground` |
+| **Default** | `bg-surface border-border text-fg-secondary`（未選文字用 neutral-8，對齊 SegmentedControl / Tabs 未選狀態；hover 才轉 `text-foreground`）|
 | **Hover**（未選）| `hover:border-border-hover`（對齊 Input / SegmentedControl hover 的 border 加深一階）|
-| **Selected** | `bg-primary-subtle border-primary-hover text-primary-hover`（對齊 `semantic.css:67` canonical 選中規則）|
+| **Selected** | `border-primary text-primary`，底色維持 `bg-surface` 不變（primary base 同時染 border + text，不染底色，跟 SegmentedControl 一致）|
+| **Hover（選中之上）** | `border-primary-hover text-primary-hover`——選中元素的 hover = 同色相升 hover 階（2026-07-06 拍板；Button pressed hover 家族 + Ant active hover 同派），**不用** neutral 灰底 |
 | **Disabled** | `cursor-not-allowed text-fg-disabled`，border 維持 `border-border` 不變色 |
+| **Disabled × Selected** | disabled 全滅（primary 描邊/染字一併退場 → `border-border text-fg-disabled`）——M24 state > emphasis，Checkbox checked+disabled 全滅同族（2026-07-07 補明文，原 code 只滅字不滅框 = 半滅已修） |
 
-Hover 和 selected 的色彩都對齊系統 canonical 規則，跟 SegmentedControl / Input / Tabs underline 使用同一套 primary-hover token，保持選中語意的視覺統一。
+選中色對齊系統選中 canonical（semantic.css「選中狀態」段 SSOT），跟 SegmentedControl / Tabs underline 使用同一套 **primary base** token——2026-07-06 user 拍板自 primary-hover 改 base（Ant / Atlassian / Material 三家實錘「瞬時弱、持續強」：hover 階專屬瞬時態，持續選中站 base）。**❌ 選中態不得用 primary-hover**（那是瞬時 hover 專用階）。
 
 ---
 
-## ChipGroup — Chip 必須在群組內
+## ChipGroup — filter 分支必須在群組內
 
-Chip **不可單獨使用**，必須放在 `<ChipGroup>` 裡。跟 SegmentedControl / RadioGroup 的結構對齊。
+filter Chip **不可單獨使用**,必須放在 `<ChipGroup>` 裡。跟 SegmentedControl / RadioGroup
+的結構對齊。(assist 分支=按鈕語意,獨立使用,不進 ChipGroup。)
 
 ```tsx
 <ChipGroup type="multiple" value={tags} onValueChange={setTags}>
@@ -129,11 +139,13 @@ Chip **不可單獨使用**，必須放在 `<ChipGroup>` 裡。跟 SegmentedCont
 
 ### Type
 
-| Type | 語意 | 預設 |
+| Type | 語意 | 備註 |
 |---|---|---|
-| `multiple` | 可勾選任意數量（checkbox 語意）| ★ **預設**（filter 最常見） |
+| `multiple` | 可勾選任意數量（checkbox 語意）| filter 最常見 |
 | `single` | 互斥單選（radio 語意）| 從 tag 群裡選唯一主要 tag |
 
+`type` 必填——Radix ToggleGroup discriminated union,無 API default(anatomy「Props 速查」同)。
+
 ### Layout
 
 Chip 的 overflow 處理有三種模式：
@@ -142,7 +154,7 @@ Chip 的 overflow 處理有三種模式：
 |---|---|---|
 | `wrap` ★default | 塞不下時換到下一排 | 大多數情況（filter panel / tag cloud） |
 | `scroll` | 單行、水平滾動，邊緣 fade mask 指示還有內容 | Toolbar / header filter 必須單行 |
-| `menu` | 塞不下的 chips 收進 `⋯` dropdown menu | 單行且需要完整選項可見（ListView toolbar）|
+| `menu` | 單行水平捲動;dropdown(`ChevronDown` trigger)永遠列出全部 chip(show-all navigator)| 單行且需要完整選項可見（ListView toolbar）|
 
 **詳見 overflow 段落。**
 
@@ -170,35 +182,39 @@ Chip 的 overflow 處理有三種模式：
 
 **為什麼要 scroll arrow buttons**（與 Tabs scroll 同規則）：鍵盤用方向鍵、trackpad 用兩指滑、滑鼠滾輪使用者只能靠 arrows（`Shift+wheel` 太隱晦）。Material 3 / Ant Design / Carbon 都這麼做。
 
-### menu — 收進 DropdownMenu
+### menu — 水平捲動 + show-all navigator dropdown
 
-- 所有 Chip 渲染在 DOM 中（保留 Radix ToggleGroup 的 a11y）
-- 用 `useOverflowIndices()` 偵測哪些 chip 溢出
-- 溢出的 chip 套 `invisible`（`visibility: hidden`，不佔 hit test 但保持 layout）
-- 右側渲染 `<Button variant="text" iconOnly startIcon={MoreVertical} />`(overflow menu canonical icon,見 CLAUDE.md「常用 icon canonical」;對齊決策 10)
-- 點擊開 DropdownMenu，內容是 `DropdownMenuCheckboxItem` 陣列，checked 狀態跟 ChipGroup 當前 value 同步
-- 點 menu item 時呼叫 ChipGroup 的 `onValueChange`，更新的值同時反映到可見 chips 和 menu checked state
+採 **show-all navigator** pattern（對齊 Chrome tab dropdown / VS Code editor tabs）——menu 不做動態 overflow 計算，永遠把全部 chip 列在 dropdown 裡：
 
-**a11y 保留機制**：因為溢出的 chips 只是視覺隱藏、仍在 DOM，Radix ToggleGroup 的 roving tabindex 依然可以 focus 它們。鍵盤使用者可以透過 Tab 進入 ChipGroup，用方向鍵在所有 chips 之間導覽（含視覺隱藏的），或用 Tab 到 `⋯` 按鈕用 dropdown 介面。兩條互動路徑同時可用。
+- 所有 Chip 永遠渲染在水平 `overflow-x-auto` 容器（保留 Radix ToggleGroup 的 a11y），靠 scroll 顯示而非 hide/show；邊緣用 fade mask 軟化硬邊
+- 不偵測哪些 chip 溢出、不套 `invisible` / `visibility:hidden`——所有 chip 都正常可見可點
+- 容器可捲動時（`canScroll`），右側渲染 canonical `<OverflowMenuTriggerButton />`（= `<Button variant="text" size="sm" iconOnly startIcon={ChevronDown} />`，跟 Tabs menu trigger 共用同一 primitive，見 `horizontal-overflow.spec.md`）
+- 點擊開 DropdownMenu，內容是**全部 chip** 的 `DropdownMenuCheckboxItem` 陣列，checked 狀態跟 ChipGroup 當前 value 同步
+- 點 menu item 時呼叫 ChipGroup 的 `onValueChange` toggle 選取，並把該 chip `scrollIntoView`（捲到容器中央）；更新的值同時反映到可見 chips 和 menu checked state
+
+**a11y 保留機制**：所有 chip 都在 DOM 且視覺可見，Radix ToggleGroup 的 roving tabindex 可以 focus 全部 chip。鍵盤使用者可以透過 Tab 進入 ChipGroup，用方向鍵在所有 chips 之間導覽（焦點移動時 chip 隨 scroll 進入視圖），或用 Tab 到 dropdown 觸發按鈕用 menu 介面。兩條互動路徑同時可用。
 
 **menu 模式需要 controlled ChipGroup**：菜單 items 透過 `onValueChange` 觸發選擇變化，因此 ChipGroup 必須傳 `value` + `onValueChange`（controlled）。uncontrolled mode（`defaultValue`）的 menu 模式無法讓 menu items 與 chips 同步狀態。
 
+**RTL**：不支援；全域 LTR-only compatibility contract 見 `packages/design-system/README.md#compatibility-matrix`。本元件的 `scrollLeft` / fade / arrow physical-direction 限制不在此重複建立第二決策。
+
 ---
 
 ## 禁止事項
 
-- ❌ Chip 單獨使用——必須在 ChipGroup 內
+- ❌ filter Chip 單獨使用——必須在 ChipGroup 內(assist 分支才可獨立)
+- ❌ assist Chip 放進 ChipGroup 當可選項——按鈕語意無 toggle,混用會誤導選取心智模型
 - ❌ 用 `danger` / `loading` / `pressed` / `asChild` / `iconOnly`——不支援
-- ❌ 加 dismiss X——用 Input chip / Tag 代替
+- ❌ 加 dismiss X——用 Input chip / Tag 代替(assist 分支同樣不支援 dismiss)
 - ❌ 手動改 `data-state` 或 `aria-pressed` / `aria-checked`——由 Radix 管理
 - ❌ 把 Chip 塞進 Field 當 form control——規模語意不對，用 SegmentedControl
 - ❌ Menu 模式搭配 uncontrolled（只給 `defaultValue`）——menu items 無法同步狀態，TS 不擋但 runtime 會看到 menu 勾選失效
 
-## 為何無 Inspector
+## 設計規格 story 結構
 
-Chip 決策維度是「selection 行為(single / multi / menu)」× layout(連體 / 間隔)× overflow——已在 `SelectionMatrix` / `LayoutMatrix` 兩張結構矩陣覆蓋。互動 Inspector 無法呈現 selection model 的差異(需要 side-by-side 對照)。
+Chip 決策維度是「selection type(`single` / `multiple`)」×「layout(`wrap` / `scroll` / `menu`)」× overflow——由 `Inspector`(互動切換 type / selected / disabled / startIcon / layout)、`SelectionMatrix`、`LayoutMatrix` 三者覆蓋。
 
-ColorMatrix 已建:展示 default / hover / selected / disabled 四狀態的 bg / border / text / icon token 對照,採 pill-canonical 規則(`--primary-hover` 同步染 border + text,bg 維持 surface 不染色),對齊 SegmentedControl / Tabs 未選 hover。
+ColorMatrix:展示 default / hover / selected / disabled 四狀態的 bg / border / text / icon token 對照,採 pill-設計準則:selected 時 `--primary` 同時染 border + text(selected × hover 深化為 `--primary-hover`),底色維持 `--surface` 不染色,對齊 SegmentedControl / Tabs。
 
 ---
 
@@ -207,7 +223,7 @@ ColorMatrix 已建:展示 default / hover / selected / disabled 四狀態的 bg
 - Button (`button.spec.md`) — Chip 內部結構對標的來源
 - SegmentedControl (`segmented-control.spec.md`) — compact 連體單選變體
 - Tag — 純顯示 / dismissible tag
-- `useOverflowItems` hook (`packages/design-system/src/hooks/use-overflow-items.ts`) — scroll / menu 的共用追蹤邏輯，Tabs 也消費同一個 hook
+- `horizontal-overflow` pattern (`patterns/horizontal-overflow/horizontal-overflow.spec.md`) — Chip 的 scroll / menu 模式實際 import 來源(`useScrollEdges` / `useScrollByPage` / `buildFadeMask` / `OverflowScrollArrow` / `OverflowMenuTriggerButton`),Tabs 也共用同一套。底層 scroll-edge 追蹤 hook 是 `useScrollEdges`(`hooks/use-overflow-items.ts`)
 
 ## A11y 預設
 
@@ -215,11 +231,12 @@ ColorMatrix 已建:展示 default / hover / selected / disabled 四狀態的 bg
 
 **Keyboard 行為**:
 
-- Tab — 進入 group
-- ←/→ — 切換
-- Enter / Space — toggle
+- Tab — 進入整組 chip（整組只有一個 Tab 停留點）
+- ←/→ — 在組內 chip 之間移動焦點
+- Tab（再按一次）— 離開整組
+- Enter / Space — 切換選取
 
-**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+**Focus**:整組 chip 採 roving tabindex——Tab 進入整組、方向鍵在組內移動焦點、再按 Tab 離開整組（不是 Dialog 那種把焦點鎖在裡面、Tab 無法離開的 focus trap）。focus-visible 時顯示 focus ring（`focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-1`,以 box-shadow 實作並 `outline-none`）。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -228,10 +245,5 @@ ColorMatrix 已建:展示 default / hover / selected / disabled 四狀態的 bg
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
 - `badge.spec.md`
+- `pagination.spec.md`
 - `tag.spec.md`
-
-## 被引用(auto-maintained,Dim 3 reciprocal audit)
-
-> 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
-
-- `opacity.spec.md`

package/src/components/Chip/chip.stories.tsx

@@ -0,0 +1,111 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import type { Meta, StoryObj } from '@storybook/react'
+import { useState } from 'react'
+import { FileText } from 'lucide-react'
+import { Chip, ChipGroup } from './chip'
+import { Badge } from '@/design-system/components/Badge/badge'
+
+const meta: Meta<typeof ChipGroup> = {
+  title: 'Design System/Components/Chip/展示',
+  tags: ['autodocs'],
+  component: ChipGroup,
+  parameters: {
+    layout: 'padded',
+    docs: { description: { component: '表示可切換的篩選條件或輕量選項，ChipGroup 管理單選、多選與水平溢出。使用者需要在內容上方快速套用少量篩選時使用；純分類標籤改用 Tag。' } },
+  },
+}
+export default meta
+
+type Story = StoryObj<typeof ChipGroup>
+
+// ── Default ──────────────────────────────────────────────────────────────────
+
+export const Default: Story = {
+  name: '預設',
+  render: () => {
+    const [value, setValue] = useState<string[]>(['TypeScript'])
+    return (
+      <ChipGroup type="multiple" value={value} onValueChange={setValue}>
+        <Chip value="JavaScript">JavaScript</Chip>
+        <Chip value="TypeScript">TypeScript</Chip>
+        <Chip value="Python">Python</Chip>
+        <Chip value="Rust">Rust</Chip>
+        <Chip value="Go">Go</Chip>
+      </ChipGroup>
+    )
+  },
+}
+
+// ── States ───────────────────────────────────────────────────────────────────
+
+export const States: Story = {
+  name: '狀態',
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <div>
+        <div className="text-caption text-fg-muted mb-2">Default / hover / selected / disabled</div>
+        <ChipGroup type="multiple" defaultValue={['typescript']}>
+          <Chip value="react">React</Chip>
+          <Chip value="typescript">TypeScript</Chip>
+          <Chip value="deprecated" disabled>Deprecated</Chip>
+        </ChipGroup>
+      </div>
+    </div>
+  ),
+}
+
+// @story-history: WithIcon retired per F migration 2026-05-15 — anatomy.stories.tsx auto-compile owns icon slot showcase。
+// ── With badge ──────────────────────────────────────────────────────────────
+
+export const WithBadge: Story = {
+  name: '帶 Badge',
+  render: () => {
+    const [value, setValue] = useState<string[]>(['all'])
+    return (
+      <ChipGroup type="multiple" value={value} onValueChange={setValue}>
+        <Chip value="all" badge={<Badge count={24} />}>全部</Chip>
+        <Chip value="active" badge={<Badge count={3} />}>進行中</Chip>
+        <Chip value="done" badge={<Badge count={21} />}>已完成</Chip>
+      </ChipGroup>
+    )
+  },
+}
+
+// ── Single type ─────────────────────────────────────────────────────────────
+
+export const SingleSelection: Story = {
+  name: '單選',
+  render: () => {
+    const [value, setValue] = useState('typescript')
+    return (
+      <ChipGroup type="single" value={value} onValueChange={(v) => v && setValue(v as string)}>
+        <Chip value="javascript">JavaScript</Chip>
+        <Chip value="typescript">TypeScript</Chip>
+        <Chip value="python">Python</Chip>
+      </ChipGroup>
+    )
+  },
+}
+
+// @story-history: LayoutWrap / LayoutScroll / LayoutMenu retired 2026-05-17 per audit Dim 24 —
+//   anatomy.stories.tsx LayoutMatrix(3 layout values side-by-side)+ principles.stories.tsx LayoutRule
+//   已 cover layout 機制比較與業務情境。展示層保留 typical 情境(Default / States / WithBadge / SingleSelection)。
+//   注意:Chip 是 filter chip,不提供 dismiss / 可移除態(spec「禁止事項」),故無 Removable story。
+
+/** assist 分支(2026-09-02):按鈕語意、可獨立使用——智慧代理訊息內的附件開啟(真實消費場景)。 */
+export const AssistAttachments: Story = {
+  name: '按鈕語意附件',
+  render: () => (
+    <div className="max-w-xs rounded-md bg-secondary px-3 py-2">
+      <div className="mb-2 flex flex-wrap gap-1">
+        <Chip variant="assist" startIcon={FileText} aria-label="附件:sprint-42-backlog.csv" onClick={() => {}}>
+          sprint-42-backlog.csv
+        </Chip>
+        <Chip variant="assist" startIcon={FileText} aria-label="附件:排程規則.md" onClick={() => {}}>
+          排程規則.md
+        </Chip>
+      </div>
+      <p className="text-body">把這份待辦按優先級重排,衝突的排程幫我標出來。</p>
+    </div>
+  ),
+}