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

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

@@ -0,0 +1,422 @@
+// @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.
+// @anatomy-exempt: anatomy specs / token 對照表格用 raw <table>,非業務資料表。業務資料表才用 <DataTable>。
+import type { Meta, StoryObj } from '@storybook/react'
+import { Star, Tag as TagIcon } from 'lucide-react'
+import { Chip, ChipGroup } from './chip'
+import { H3, Desc, Td, Th, TokenCell, Swatch } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+type InspectorArgs = {
+  type: 'single' | 'multiple'
+  selected: boolean
+  disabled: boolean
+  withStartIcon: boolean
+  layout: 'wrap' | 'scroll' | 'menu'
+}
+
+const meta: Meta = {
+  title: 'Design System/Components/Chip/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+type InspectorStory = StoryObj<InspectorArgs>
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>Chip 是 **Material Design Filter Chip** 實作——多選或單選的 pill 控件(`type` 必填)。基於 Radix ToggleGroup,橋接 DS token。視覺上是一排獨立的 `rounded-full` pill,各自有 `gap-2` 間距(非連體,這是跟 SegmentedControl 的主要差異)。</Desc>
+        <ChipGroup type="multiple" defaultValue={['electronics', 'food']}>
+          <Chip value="electronics">電子產品</Chip>
+          <Chip value="furniture">家具</Chip>
+          <Chip value="food">食品</Chip>
+          <Chip value="clothing">服飾</Chip>
+          <Chip value="books">書籍</Chip>
+        </ChipGroup>
+      </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>ChipGroup</Td><Td mono>type: 'single' | 'multiple'(必填,Radix ToggleGroup 要求),value / onValueChange,layout</Td></tr>
+              <tr><Td mono>Chip</Td><Td mono>value(必填),startIcon,badge(計數指示器,ReactNode),endIcon(如 ChevronDown),disabled</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div>
+        <H3>與 SegmentedControl 的差異</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th></Th><Th>Chip</Th><Th>SegmentedControl</Th></tr></thead>
+            <tbody>
+              <tr><Td>選擇語意</Td><Td>多選為主,可選單選</Td><Td>固定單選(radio)</Td></tr>
+              <tr><Td>視覺連接</Td><Td mono>各自獨立 pill,gap-2</Td><Td mono>Items 連體,-ml-px border 重疊</Td></tr>
+              <tr><Td>圓角</Td><Td mono>rounded-full(M3 身份特徵)</Td><Td mono>rounded-md</Td></tr>
+              <tr><Td>溢出處理</Td><Td>layout="scroll" / "menu"(共用 horizontal-overflow pattern)</Td><Td>不支援 overflow</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const Inspector: InspectorStory = {
+  name: '元件檢閱器',
+  parameters: {
+    docs: {
+      description: {
+        story: '在右側 Controls 面板切換 type / selected / disabled / startIcon / layout,即時查看 Chip 狀態。世界級 DS 的 Inspector = Figma inspect 替代。',
+      },
+    },
+  },
+  args: {
+    type: 'multiple',
+    selected: true,
+    disabled: false,
+    withStartIcon: false,
+    layout: 'wrap',
+  },
+  argTypes: {
+    type: {
+      control: 'radio',
+      options: ['single', 'multiple'],
+      description: 'ToggleGroup 選擇模式(必填,Radix 要求):multiple(多選)/ single(單選互斥)',
+    },
+    selected: {
+      control: 'boolean',
+      description: '「精選」chip 是否選中(預覽選中態視覺)',
+    },
+    disabled: {
+      control: 'boolean',
+      description: '「下架」chip 是否停用',
+    },
+    withStartIcon: {
+      control: 'boolean',
+      description: '是否在 chip 加 startIcon(Tag / Star)',
+    },
+    layout: {
+      control: 'radio',
+      options: ['wrap', 'scroll', 'menu'],
+      description: 'overflow 行為:wrap(換行,預設)/ scroll(fade mask)/ menu(收入 Dropdown)',
+    },
+  },
+  render: (args) => {
+    const groupProps =
+      args.type === 'multiple'
+        ? ({ type: 'multiple' as const, defaultValue: args.selected ? ['featured'] : [] })
+        : ({ type: 'single' as const, defaultValue: args.selected ? 'featured' : '' })
+    return (
+      <div className="max-w-md border border-border rounded-md p-3">
+        <ChipGroup layout={args.layout} {...groupProps}>
+          <Chip value="featured" startIcon={args.withStartIcon ? Star : undefined}>精選</Chip>
+          <Chip value="new" startIcon={args.withStartIcon ? TagIcon : undefined}>新品</Chip>
+          <Chip value="sale">特價</Chip>
+          <Chip value="limited">限量</Chip>
+          <Chip value="discontinued" disabled={args.disabled}>下架</Chip>
+        </ChipGroup>
+      </div>
+    )
+  },
+}
+
+export const ColorMatrix: Story = {
+  name: '色彩對照表',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>狀態 × 色彩 Token 矩陣</H3>
+        <Desc>
+          Chip 採 pill-設計準則 選中規則(跟 SegmentedControl 共用):selected 時 `--primary-hover` 同時染 border 和 text,
+          **底色維持 `--surface` 不變**——不用 primary-subtle 底色(那是 Button subtle 的視覺語言,跟 filter chip 不同)。
+          視覺輕量是 filter 語意必要條件,避免 chip 群組喧賓奪主壓過資料表格。
+        </Desc>
+        <div className="overflow-x-auto mb-4">
+          <table className="text-caption border-collapse min-w-[640px]">
+            <thead>
+              <tr>
+                <Th>狀態</Th>
+                <Th>Background</Th>
+                <Th>Border</Th>
+                <Th>Text</Th>
+                <Th>Icon</Th>
+              </tr>
+            </thead>
+            <tbody>
+              <tr>
+                <Td mono>default(unselected)</Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--surface" size="sm" /><span className="font-mono">--surface</span></span></Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--border" size="sm" /><span className="font-mono">--border</span></span></Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--fg-secondary" size="sm" /><span className="font-mono">--fg-secondary</span></span></Td>
+                <Td mono>currentColor</Td>
+              </tr>
+              <tr>
+                <Td mono>hover(unselected)</Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--surface" size="sm" /><span className="font-mono">--surface</span></span></Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--border-hover" size="sm" /><span className="font-mono">--border-hover</span></span></Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--foreground" size="sm" /><span className="font-mono">--foreground</span></span></Td>
+                <Td mono>currentColor</Td>
+              </tr>
+              <tr>
+                <Td mono>selected</Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--surface" size="sm" /><span className="font-mono">--surface(不變)</span></span></Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--primary-hover" size="sm" /><span className="font-mono">--primary-hover</span></span></Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--primary-hover" size="sm" /><span className="font-mono">--primary-hover</span></span></Td>
+                <Td mono>currentColor</Td>
+              </tr>
+              <tr>
+                <Td mono>disabled</Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--surface" size="sm" /><span className="font-mono">--surface</span></span></Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--border" size="sm" /><span className="font-mono">--border(不升階)</span></span></Td>
+                <Td><span className="inline-flex items-center gap-1.5"><Swatch value="--fg-disabled" size="sm" /><span className="font-mono">--fg-disabled</span></span></Td>
+                <Td mono>currentColor</Td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div>
+        <H3>視覺並列對照</H3>
+        <Desc>左 default / 中 selected / 右 disabled,觀察 border 同時升階到 primary-hover 的視覺變化(非 bg 變化)。</Desc>
+        <div className="flex items-center gap-8 px-6 py-5 rounded-lg bg-canvas border border-divider">
+          <div className="flex flex-col gap-2 items-start">
+            <span className="text-[11px] text-fg-muted font-mono">default</span>
+            <ChipGroup type="multiple" defaultValue={[]}>
+              <Chip value="electronics">電子產品</Chip>
+            </ChipGroup>
+          </div>
+          <div className="flex flex-col gap-2 items-start">
+            <span className="text-[11px] text-fg-muted font-mono">selected</span>
+            <ChipGroup type="multiple" defaultValue={['electronics']}>
+              <Chip value="electronics">電子產品</Chip>
+            </ChipGroup>
+          </div>
+          <div className="flex flex-col gap-2 items-start">
+            <span className="text-[11px] text-fg-muted font-mono">disabled</span>
+            <ChipGroup type="multiple" defaultValue={[]}>
+              <Chip value="electronics" disabled>電子產品</Chip>
+            </ChipGroup>
+          </div>
+          <div className="flex flex-col gap-2 items-start">
+            <span className="text-[11px] text-fg-muted font-mono">selected + disabled</span>
+            <ChipGroup type="multiple" defaultValue={['electronics']}>
+              <Chip value="electronics" disabled>電子產品</Chip>
+            </ChipGroup>
+          </div>
+        </div>
+        <p className="text-footnote text-fg-muted mt-3">
+          世界級對照:Material 3 Filter Chip / Atlassian Chip / Polaris Filter 全部採「border + text 同步染 primary」而非 bg 染色——保持 filter row 的視覺輕量。
+        </p>
+      </div>
+
+      <div>
+        <H3>為什麼不用 primary-subtle 底色</H3>
+        <Desc>
+          `--primary-subtle` 的 bg 染色是 Button subtle variant 的視覺語言,適用於「行為選項」(如 pagination hover);
+          Chip 是「篩選條件」,多選時可能同時亮 5-10 個——若每個都填底色,filter row 會蓋過主內容表格,破壞資訊層次。
+          只染 border + text 保持背景通透,對齊 SegmentedControl / Tabs 未選 hover 的 pill-設計準則。
+        </Desc>
+      </div>
+    </div>
+  ),
+}
+
+export const SelectionMatrix: Story = {
+  name: '多 vs 單 選擇',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>Multiple</H3>
+        <Desc>選取任意數量——filter panel 的 tag 選取、toolbar 多選過濾。</Desc>
+        <ChipGroup type="multiple" defaultValue={['zh', 'en']}>
+          <Chip value="zh">中文</Chip>
+          <Chip value="en">英文</Chip>
+          <Chip value="ja">日文</Chip>
+          <Chip value="ko">韓文</Chip>
+        </ChipGroup>
+      </div>
+
+      <div>
+        <H3>Single(單選)</H3>
+        <Desc>互斥單選——當需要 chip 的視覺感(rounded-full, 獨立 pill)但語意是互斥時使用。若需 compact 連體,改用 SegmentedControl。</Desc>
+        <ChipGroup type="single" defaultValue="all">
+          <Chip value="all">全部</Chip>
+          <Chip value="active">進行中</Chip>
+          <Chip value="done">已完成</Chip>
+        </ChipGroup>
+      </div>
+    </div>
+  ),
+}
+
+export const SizeMatrix: Story = {
+  name: '尺寸對照表',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>單一 size = h-field-sm(28 / 32 density-aware)</H3>
+        <Desc>
+          Chip 故意**只有一種尺寸**——對齊 Material 3 / Atlassian / Polaris 的 filter chip
+          設計準則 共識。Chip 是 filter 語意,filter 列的視覺重量應該固定;如果需要多 tier,那是
+          Button 或 Tabs 的領域。
+        </Desc>
+        <div className="overflow-x-auto mb-4">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>項目</Th><Th>值</Th><Th>Token / 對齊</Th></tr></thead>
+            <tbody>
+              <tr><Td>高度</Td><Td mono>h-field-sm</Td><Td>28px (md) / 32px (lg) — density-aware</Td></tr>
+              <tr><Td>水平 padding</Td><Td mono>px-3</Td><Td>12px(對齊 Button sm)</Td></tr>
+              <tr><Td>內部 gap</Td><Td mono>gap-1</Td><Td>4px(icon → label → suffix)</Td></tr>
+              <tr><Td>Label 左右留白</Td><Td mono>px-1</Td><Td>4px 貼合視覺中心</Td></tr>
+              <tr><Td>Chip 之間 gap</Td><Td mono>gap-2</Td><Td>8px(獨立 pill 間距)</Td></tr>
+              <tr><Td>Icon size</Td><Td mono>16px</Td><Td>對齊 Button sm icon</Td></tr>
+              <tr><Td>Border radius</Td><Td mono>rounded-full</Td><Td>M3 身份特徵</Td></tr>
+              <tr><Td>Typography</Td><Td mono>text-body font-medium</Td><Td>14px 500 leading-compact</Td></tr>
+            </tbody>
+          </table>
+        </div>
+        <ChipGroup type="single" defaultValue="all">
+          <Chip value="all">全部</Chip>
+          <Chip value="active">進行中</Chip>
+          <Chip value="done">已完成</Chip>
+        </ChipGroup>
+      </div>
+    </div>
+  ),
+}
+
+export const StateBehavior: Story = {
+  name: '狀態行為',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>四種狀態 × 色彩 Token</H3>
+        <Desc>
+          選中態走 pill-設計準則 規則(跟 SegmentedControl 完全一致):
+          **primary-hover 同時染 border 和 text**,底色維持 bg-surface 不變——不用 primary-subtle
+          底色(那是 Button subtle 的視覺語言,跟 chip 不同)。
+        </Desc>
+        <div className="overflow-x-auto mb-4">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>狀態</Th><Th>Background</Th><Th>Border</Th><Th>Text</Th></tr></thead>
+            <tbody>
+              <tr>
+                <Td mono>default</Td>
+                <Td><TokenCell token="--surface" /></Td>
+                <Td><TokenCell token="--border" /></Td>
+                <Td><TokenCell token="--fg-secondary" /></Td>
+              </tr>
+              <tr>
+                <Td mono>hover(未選)</Td>
+                <Td><TokenCell token="--surface" /></Td>
+                <Td><TokenCell token="--border-hover" display="border-hover" /></Td>
+                <Td><TokenCell token="--foreground" /></Td>
+              </tr>
+              <tr>
+                <Td mono>selected (data-state=on)</Td>
+                <Td><TokenCell token="--surface" /></Td>
+                <Td><TokenCell token="--primary-hover" display="primary-hover" /></Td>
+                <Td><TokenCell token="--primary-hover" display="primary-hover" /></Td>
+              </tr>
+              <tr>
+                <Td mono>disabled</Td>
+                <Td><TokenCell token="--surface" /></Td>
+                <Td><TokenCell token="--border" /></Td>
+                <Td><TokenCell token="--fg-disabled" display="fg-disabled" /></Td>
+              </tr>
+            </tbody>
+          </table>
+        </div>
+
+        <div>
+          <div className="text-caption text-fg-muted mb-2">四種狀態並存(hover 可在 Storybook 上試)</div>
+          <ChipGroup type="multiple" defaultValue={['selected']}>
+            <Chip value="default">Default(未選)</Chip>
+            <Chip value="hover">Hover 我 ↓</Chip>
+            <Chip value="selected">Selected</Chip>
+            <Chip value="disabled" disabled>Disabled</Chip>
+          </ChipGroup>
+        </div>
+      </div>
+
+      <div>
+        <H3>Selected 色彩跟 SegmentedControl 完全一致</H3>
+        <Desc>
+          兩者都是 pill 選擇語意(filter / 單選 radio),選中態視覺語言統一:
+          primary-hover 染 border + text,底色不變。只有「連體 vs 獨立」的視覺差異,選中規則是同一套。
+        </Desc>
+        <div className="border border-dashed border-divider rounded-md p-4">
+          <div className="text-caption text-fg-muted mb-2">Chip(獨立 pill)</div>
+          <ChipGroup type="single" defaultValue="active">
+            <Chip value="all">全部</Chip>
+            <Chip value="active">進行中</Chip>
+            <Chip value="done">已完成</Chip>
+          </ChipGroup>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const LayoutMatrix: Story = {
+  name: '排版（換行 vs 捲動 vs 選單）',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>wrap(預設)</H3>
+        <Desc>超出容器自然換行。適合空間充裕的 filter panel。</Desc>
+        <div className="max-w-md border border-border rounded-md p-3">
+          <ChipGroup type="multiple" defaultValue={['a']}>
+            {['電子產品', '家具', '食品', '服飾', '書籍', '運動', '玩具', '美妝', '家電'].map(label => (
+              <Chip key={label} value={label}>{label}</Chip>
+            ))}
+          </ChipGroup>
+        </div>
+      </div>
+
+      <div>
+        <H3>scroll</H3>
+        <Desc>水平捲動 + fade mask(共用 `horizontal-overflow` pattern,跟 Tabs 一致)。適合空間受限但希望保留 chip 視覺的場景。</Desc>
+        <div className="max-w-md border border-border rounded-md p-3">
+          <ChipGroup type="multiple" layout="scroll" defaultValue={['a']}>
+            {['電子產品', '家具', '食品', '服飾', '書籍', '運動', '玩具', '美妝', '家電'].map(label => (
+              <Chip key={label} value={label}>{label}</Chip>
+            ))}
+          </ChipGroup>
+        </div>
+      </div>
+
+      <div>
+        <H3>menu(show-all navigator dropdown)</H3>
+        <Desc>所有 chip 留在單行水平捲動容器,全部可見可點(不隱藏);dropdown 永遠列出全部 chip 供快速勾選(對齊 Chrome tab dropdown / VS Code editor tabs)。適合 chip 很多但使用者不常切後面的場景。</Desc>
+        <div className="max-w-md border border-border rounded-md p-3">
+          <ChipGroup type="multiple" layout="menu" defaultValue={['a']}>
+            {['電子產品', '家具', '食品', '服飾', '書籍', '運動', '玩具', '美妝', '家電'].map(label => (
+              <Chip key={label} value={label}>{label}</Chip>
+            ))}
+          </ChipGroup>
+        </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">{"詳 「無障礙設計」段。摘要:\n\n  ARIA / Pattern  :繼承 Radix toggle-group 鍵盤模式(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/toggle-group#accessibility)。\n\n  Keyboard 行為  :\n\n- Tab — 進入整組 chip(只有一個 Tab 停留點)\n- ←/→ — 在組內 chip 之間移動焦點\n- Tab — 再按一次離開整組\n- Enter / Space — 切換選取\n\n  Focus  :焦點環為 2px 的 --ring 色描邊(focus-visible 才顯示)。整組 chip 用方向鍵移動焦點、Tab 進出整組——這不是 Dialog 那種把焦點鎖在裡面的行為。\n\n  驗證  :Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA 對比 ≥ 4.5:1(文字)"}</p>
+    </div>
+  ),
+}

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-hover text + border，底色不變"
+        note="對齊 SegmentedControl / Tabs / Input 的設計準則 選中規則(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-hover 文字 + 邊框,底色仍 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>
+  ),
+}
+
+// ── 禁止 ────────────────────────────────────────────────────────────────
+