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

package/src/components/SegmentedControl/segmented-control.principles.stories.tsx

@@ -0,0 +1,281 @@
+// @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 {
+  AlignLeft, AlignCenter, AlignRight,
+  List, LayoutGrid, Calendar,
+} from 'lucide-react'
+import { SegmentedControl, SegmentedControlItem } from './segmented-control'
+import { Tabs, TabsList, TabsTrigger } from '@/design-system/components/Tabs/tabs'
+import { Button } from '@/design-system/components/Button/button'
+import { Badge } from '@/design-system/components/Badge/badge'
+
+const meta: Meta = {
+  title: 'Design System/Components/SegmentedControl/設計原則',
+  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-4">{children}</div>
+  </div>
+)
+
+const Label = ({ children, warn }: { children: React.ReactNode; warn?: boolean }) => (
+  <p className={`text-footnote leading-normal ${warn ? 'text-error font-medium' : 'text-fg-muted'}`}>{children}</p>
+)
+
+// ── UsageGuidance — 何時用 / 何時不用 / vs 近親元件 ─────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => {
+    const [align, setAlign] = useState('left')
+    const [period, setPeriod] = useState('week')
+    return (
+      <div className="flex flex-col gap-12">
+        {/* vs 近親元件 — 原 WhatItIs(定位與分界) */}
+        <div>
+        <Rule
+          title="vs 近親元件 — SegmentedControl 是 compact control(可驅動下方內容變化)"
+          note="常見誤解：以為 SegmentedControl 只能當 value input（選了就結束）。實際上它可以驅動下方局部內容變化——chart 維度切換、list 排序切換、form 條件欄位切換都是正當用法。關鍵是規模：它切的是局部變體（一個 chart / 一段 form section），不是整個 container"
+        >
+          <div>
+            <Label>✅ 純 value input（值直接送出，不影響下方）</Label>
+            <SegmentedControl value={align} onValueChange={setAlign} iconOnly>
+              <SegmentedControlItem value="left" startIcon={AlignLeft} aria-label="靠左對齊" />
+              <SegmentedControlItem value="center" startIcon={AlignCenter} aria-label="置中對齊" />
+              <SegmentedControlItem value="right" startIcon={AlignRight} aria-label="靠右對齊" />
+            </SegmentedControl>
+          </div>
+          <div>
+            <Label>✅ 驅動下方 chart 維度變化（局部變體，不是結構）</Label>
+            <SegmentedControl value={period} onValueChange={setPeriod}>
+              <SegmentedControlItem value="day">日</SegmentedControlItem>
+              <SegmentedControlItem value="week">週</SegmentedControlItem>
+              <SegmentedControlItem value="month">月</SegmentedControlItem>
+            </SegmentedControl>
+            <Label>↑ 切換會重載下方 chart 資料，但 chart 還是同一個 chart，不是換一整個 view</Label>
+          </div>
+        </Rule>
+
+        <Rule
+          title="何時不用 / 替代元件 — 切的是整塊 container 結構 → 用 Tabs"
+          note="若每個「選項」背後是一整塊獨立子頁（有自己的 toolbar / filters / table / actions），那是 Tabs 的規模不是 SegmentedControl。判斷 fallback：把它跟 Input / Button 並排違不違和？違和 → Tabs"
+        >
+          <div>
+            <Label>❌ 錯用：這三者各自是完整子頁，不該用 SegmentedControl</Label>
+            <SegmentedControl defaultValue="orders">
+              <SegmentedControlItem value="orders">訂單</SegmentedControlItem>
+              <SegmentedControlItem value="customers">顧客</SegmentedControlItem>
+              <SegmentedControlItem value="products">產品</SegmentedControlItem>
+            </SegmentedControl>
+            <Label warn>↑ 改用 Tabs</Label>
+            <Tabs defaultValue="orders" className="mt-2">
+              <TabsList>
+                <TabsTrigger value="orders">訂單</TabsTrigger>
+                <TabsTrigger value="customers">顧客</TabsTrigger>
+                <TabsTrigger value="products">產品</TabsTrigger>
+              </TabsList>
+            </Tabs>
+          </div>
+        </Rule>
+
+        <Rule
+          title="何時不用 / 替代元件 — 單一功能 on/off → 用 Button pressed"
+          note="1 個 item 的 SegmentedControl 沒有選擇語意。二元狀態用 Button pressed"
+        >
+          <Button variant="text" pressed>已釘選</Button>
+        </Rule>
+        </div>
+
+        {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
+        <div>
+        <Rule
+          title="何時不用 / 替代元件 — 5 個以上選項"
+          note="選項多 → Select / RadioGroup。SegmentedControl 視覺會過窄，label 被截斷。Stripe filter 若超過 5 選項會用 Select"
+        >
+          <Label warn>5+ 選項 → Select / RadioGroup,SegmentedControl 空間受限</Label>
+        </Rule>
+
+        <Rule
+          title="何時不用 / 替代元件 — 多選(checkboxes 語義)"
+          note="SegmentedControl 是「選恰好一個」。多選改用 Checkbox 群組。Notion 的權限欄(read / edit / owner)是 radio,不用 SegmentedControl"
+        >
+          <Label warn>多選 → CheckboxGroup,SegmentedControl 是互斥</Label>
+        </Rule>
+
+        <Rule
+          title="何時不用 / 替代元件 — 整塊 view 切換"
+          note="大規模 view 切換(各有 header / toolbar)改用 Tabs。小內容切換(chart type、list layout)才用 SegmentedControl。Figma 的頁面切換用 Tabs"
+        >
+          <Label warn>整塊 view → Tabs,SegmentedControl 只切局部內容</Label>
+        </Rule>
+
+        <Rule
+          title="何時不用 / 替代元件 — 選項需要複雜描述"
+          note="複雜選項(多行文字、icon + 說明)改用 RadioGroup。SegmentedControl 是 compact control,content 受限"
+        >
+          <Label warn>複雜選項 → RadioGroup,SegmentedControl 文字簡短</Label>
+        </Rule>
+        </div>
+      </div>
+    )
+  },
+}
+
+// ── 規模限制 ─────────────────────────────────────────────────────────────────
+
+export const SizeLimits: Story = {
+  name: '選項數量規則',
+  render: () => (
+    <div>
+      <Rule
+        title="✅ 2–5 個 item"
+        note="最少 2 個（1 個沒有選擇語意），最多 5 個（超過會過窄、label 被截斷）"
+      >
+        <SegmentedControl defaultValue="a">
+          <SegmentedControlItem value="a">日</SegmentedControlItem>
+          <SegmentedControlItem value="b">週</SegmentedControlItem>
+          <SegmentedControlItem value="c">月</SegmentedControlItem>
+          <SegmentedControlItem value="d">年</SegmentedControlItem>
+        </SegmentedControl>
+      </Rule>
+
+      <Rule
+        title="❌ 只有 1 個 item"
+        note="沒有選擇語意。單一功能啟用/關閉應該用 Button pressed"
+      >
+        <SegmentedControl defaultValue="a">
+          <SegmentedControlItem value="a">唯一選項</SegmentedControlItem>
+        </SegmentedControl>
+        <Label warn>↑ 改用 &lt;Button pressed&gt;</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 超過 5 個 item"
+        note="視覺過窄、label 被截斷。應改用 Select（下拉）或 RadioGroup（垂直排列）"
+      >
+        <SegmentedControl defaultValue="a">
+          <SegmentedControlItem value="a">一月</SegmentedControlItem>
+          <SegmentedControlItem value="b">二月</SegmentedControlItem>
+          <SegmentedControlItem value="c">三月</SegmentedControlItem>
+          <SegmentedControlItem value="d">四月</SegmentedControlItem>
+          <SegmentedControlItem value="e">五月</SegmentedControlItem>
+          <SegmentedControlItem value="f">六月</SegmentedControlItem>
+        </SegmentedControl>
+        <Label warn>↑ 改用 &lt;Select&gt;</Label>
+      </Rule>
+    </div>
+  ),
+}
+
+// ── iconOnly ─────────────────────────────────────────────────────────────────
+
+export const IconOnlyRule: Story = {
+  name: 'iconOnly 是群組層級決策',
+  render: () => (
+    <div>
+      <Rule
+        title="✅ 全組統一 icon-only 或全組帶 label"
+        note="SegmentedControl 的 iconOnly 是整組決策，不是個別 item。全 icon 或全 label，不可混搭——混搭會破壞 segmented 對稱感，使用者也無法預測哪個 item 有 tooltip"
+      >
+        <div>
+          <Label>✅ 全 icon-only（自動 Tooltip）</Label>
+          <SegmentedControl defaultValue="list" iconOnly>
+            <SegmentedControlItem value="list" startIcon={List} aria-label="清單" />
+            <SegmentedControlItem value="board" startIcon={LayoutGrid} aria-label="看板" />
+            <SegmentedControlItem value="calendar" startIcon={Calendar} aria-label="行事曆" />
+          </SegmentedControl>
+        </div>
+        <div>
+          <Label>✅ 全帶 label（可選配 startIcon）</Label>
+          <SegmentedControl defaultValue="list">
+            <SegmentedControlItem value="list" startIcon={List}>清單</SegmentedControlItem>
+            <SegmentedControlItem value="board" startIcon={LayoutGrid}>看板</SegmentedControlItem>
+            <SegmentedControlItem value="calendar" startIcon={Calendar}>行事曆</SegmentedControlItem>
+          </SegmentedControl>
+        </div>
+      </Rule>
+
+      <Rule
+        title="badge suffix 的使用場景"
+        note="通常用於 filter 切換——「全部 12 / 進行中 3 / 已完成 9」。使用者看計數做決策"
+      >
+        <SegmentedControl defaultValue="all">
+          <SegmentedControlItem value="all" badge={<Badge count={12} />}>全部</SegmentedControlItem>
+          <SegmentedControlItem value="active" badge={<Badge count={3} />}>進行中</SegmentedControlItem>
+          <SegmentedControlItem value="done" badge={<Badge count={9} />}>已完成</SegmentedControlItem>
+        </SegmentedControl>
+      </Rule>
+    </div>
+  ),
+}
+
+// ── fullWidth ────────────────────────────────────────────────────────────────
+
+export const FullWidthRule: Story = {
+  name: 'fullWidth 的適用情境',
+  render: () => (
+    <div>
+      <Rule
+        title="fullWidth 的判準：跟著容器尺度走，不是跟著 label 長度"
+        note="對齊 Apple HIG / Material 3 / Carbon 等世界級定義——segmented 永遠各 item 等寬或全由內容決定，不存在『撐滿但寬度不一』的混血模式。所以 fullWidth 的選擇只看容器大小，不看 label 長度"
+      >
+        <div>
+          <Label>✅ 小容器（Dialog / Sheet / 窄 sidebar / Field row）→ fullWidth</Label>
+          <div className="w-[360px] p-4 border border-border rounded-md">
+            <div className="text-caption text-fg-muted mb-2">Dialog 內（360px 容器）</div>
+            <SegmentedControl defaultValue="day" fullWidth>
+              <SegmentedControlItem value="day">日</SegmentedControlItem>
+              <SegmentedControlItem value="week">週</SegmentedControlItem>
+              <SegmentedControlItem value="month">月</SegmentedControlItem>
+            </SegmentedControl>
+          </div>
+        </div>
+
+        <div>
+          <Label>✅ 寬容器 / toolbar 並排其他 control → hug（預設）</Label>
+          <div className="flex items-center gap-3 p-2 border border-border rounded-md">
+            <span className="text-caption text-fg-muted">Toolbar：</span>
+            <SegmentedControl defaultValue="day" size="sm">
+              <SegmentedControlItem value="day">日</SegmentedControlItem>
+              <SegmentedControlItem value="week">週</SegmentedControlItem>
+              <SegmentedControlItem value="month">月</SegmentedControlItem>
+            </SegmentedControl>
+            <div className="h-5 w-px bg-divider" />
+            <span className="text-body text-fg-muted">其他工具列元素…</span>
+          </div>
+          <Label>↑ 這裡若 fullWidth 會搶走同行其他元素的空間</Label>
+        </div>
+      </Rule>
+
+      <Rule
+        title="常見誤解：「label 長度差異不能用 fullWidth」是錯的"
+        note="SegmentedControl 的 items 永遠等寬（fullWidth 時）或全由內容決定（hug 時），不存在「短 label 周圍空白失衡」的情況——fullWidth 永遠平均分配空間。唯一要擔心的是 label 被截斷，那是 content overflow 問題（該減少選項或改 Select），跟 fullWidth 無關"
+      >
+        <div>
+          <Label>✅ 就算 label 長度差異大，fullWidth 仍然等寬，視覺不會失衡</Label>
+          <div className="w-[480px]">
+            <SegmentedControl defaultValue="all" fullWidth>
+              <SegmentedControlItem value="all">全部</SegmentedControlItem>
+              <SegmentedControlItem value="active">進行中的項目</SegmentedControlItem>
+              <SegmentedControlItem value="done">已完成</SegmentedControlItem>
+            </SegmentedControl>
+          </div>
+        </div>
+      </Rule>
+    </div>
+  ),
+}
+

package/src/components/SegmentedControl/segmented-control.spec.md

@@ -0,0 +1,297 @@
+---
+component: SegmentedControl
+family: 3
+variants: {}
+sizes:
+  xs:
+    px: 24
+    when: "row-embedded inline action(DataTable row inline action / Toolbar 內塞 segmented filter);text-caption"
+    world-class: ["Ant Segmented size=small(28)", "Atlassian Toggle compact"]
+  sm:
+    px: 28
+    when: "form field-height 28 / compact chrome bar(Filter bar / dense Toolbar)"
+    world-class: ["Ant Segmented size=small", "Material ToggleButtonGroup size=small"]
+  md:
+    px: 32
+    when: "預設 — 跟 Button / Input / 所有 field-height 系列一致;通用 form 內 toggle"
+    world-class: ["Ant Segmented default", "Material ToggleButtonGroup default", "Carbon ContentSwitcher default"]
+  lg:
+    px: 36
+    when: "touch / prominent 切換(landing 主視覺切 chart 維度、marketing form);text-body-lg"
+    world-class: ["Ant Segmented size=large", "Material ToggleButtonGroup size=large"]
+traits:
+  - hasSizes
+  - hasInteractiveStates
+benchmark:
+  - Radix ToggleGroup primitive: github.com/radix-ui/primitives/tree/main/packages/react/toggle-group
+  - Ant Design Segmented: github.com/ant-design/ant-design/tree/master/components/segmented
+  - MUI ToggleButtonGroup: github.com/mui/material-ui/tree/master/packages/mui-material/src/ToggleButtonGroup
+  - Carbon ContentSwitcher: github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/ContentSwitcher
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# SegmentedControl 設計原則
+
+## 定位
+
+SegmentedControl 是**互斥多選一的 compact control**——從 2–5 個選項裡挑恰好一個，視覺上是一排連體的分段按鈕。基於 Radix ToggleGroup（`type="single"`），橋接設計系統 token。
+
+**SegmentedControl 的選值可以驅動下方內容變化**——這是正當用法，不要誤以為它只能當表單輸入（「切 value 不能切 view」是錯的二分法）。
+
+**Layout Family**：每個 SegmentedControlItem 是 CLAUDE.md 4-Family Model **Family 3（Pill Layout）action trigger sub-profile** 的消費者——內部結構 `[startIcon?] [<span px-1>label</span>] [suffix]` 繼承 Button canonical。SSOT 在 `components/Button/button.spec.md`「Pill Layout」章節。SegmentedControl 外層容器的「分段連體」（`-ml-px` border 重疊、首尾 `rounded-l-md/rounded-r-md`）是本元件特有視覺規格，非 Family 3 共用。
+
+---
+
+## 何時用
+
+- **表單內的互斥選項**：對齊（左 / 中 / 右）、檢視模式（清單 / 看板 / 行事曆）
+- **Filter / toolbar 的分段切換**：全部 / 進行中 / 已完成、日 / 週 / 月
+- **Chart 的資料維度切換**：本週 / 本月 / 本季
+- **「選了之後下方欄位跟著變」的 form section**：付款方式、配送方式
+
+## 何時不用
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 選項 > 5 個 | `Select` / `RadioGroup` | 視覺會過窄、label 被截斷 |
+| 只有 1 個 | `Button pressed` | 沒有選擇語意 |
+| 切換的是 container 結構（整塊 view 有自己的 header / toolbar / filters）| `Tabs` | 見下「與 Tabs 的分界」 |
+| 選項需要描述文字 / 複雜排版 | `RadioGroup` | compact control 不支援多行內容 |
+
+---
+
+## 與 Tabs 的分界（詳見 `../Tabs/tabs.spec.md`）
+
+兩者都能「切換下方顯示的內容」，分界不是「切 view vs 切 value」，而是三個角度：
+
+1. **規模**：SegmentedControl 切換的是 **局部內容的變體**（一個 chart、一個 list、一段 form section）；Tabs 切換的是 **整塊 container**（可能有自己的 header / toolbar / 多個 section）
+2. **結構角色**：SegmentedControl 是 **control**（可跟 Button / Input 並排），Tabs 是 **container 的結構元件**（跨越父容器整行）
+3. **值生命週期**：SegmentedControl 的值常綁 form state / URL param / 會被持久化，Tabs 的切換通常不進表單狀態
+
+**Fallback**：跟 Input / Button 並排不違和 → SegmentedControl；必須佔一整行當 section header → Tabs。
+
+**完整灰色地帶對照表在 `tabs.spec.md` 的「Tabs 與 SegmentedControl 的分界」段落**——以該段為 single source of truth，此處不重複列舉。
+
+---
+
+## 與 Button 的血緣
+
+SegmentedControl item 的**內部結構、padding、字體、icon size 全部鏡射 Button**，這是刻意的一致性——使用者對 Button 的視覺肌肉記憶可以直接套用到 SegmentedControl。
+
+**但兩者是獨立元件，不共用 `buttonVariants`**：
+- Button 的 variant 語意（primary / secondary / tertiary / text / link）在 SegmentedControl 不適用——SegmentedControl 只有「選中 / 未選」兩種狀態，沒有強調層級
+- Button 的 `danger` / `pressed` / `loading` 在 SegmentedControl 全部不適用——SegmentedControl 是 value 選擇器，不是 action button
+
+---
+
+## 內部結構
+
+```
+SegmentedControl (root, role="group")
+  ├─ Item  [startIcon?] [label?] [suffix: badge?]
+  ├─ Item  ...
+  └─ Item  ...
+```
+
+**單個 Item 內部**（與 Button 完全對齊）：
+
+```
+[startIcon?]  [<span px-1>label</span>]  [<span gap-1>suffix?</span>]
+  ↑             ↑                           ↑
+  16/20px       text                        badge (未來可能: endIcon)
+  │─── gap-1 ─│─── gap-1 ─────────────────│
+```
+
+- Slot 間留 Button 同等 gap（與 Button size sm/md/lg 一致）
+- Label 帶水平 breathing（與 Button label 一致 — 多語言 / 大寫字距更穩）
+- Suffix 是 inline 視覺群容器，**即使目前只有 badge，wrapper 也要從第一天存在**——未來若開放 endIcon，群距已烤在 wrapper 上，零漂移風險
+
+### Slot 支援與不支援
+
+| Slot | 狀態 | 說明 |
+|------|------|------|
+| `startIcon` | ✅ 支援 | `LucideIcon`，最多一個，放 label 左側 |
+| `label` | ✅ 支援 | `iconOnly` 為 true 時可省略 |
+| `badge` | ✅ 支援 | 通常是計數指示器（「全部 12」「進行中 3」）|
+| `endIcon` | ❌ 不支援 | Button 的 endIcon 是「會展開下一層」的訊號（chevron），SegmentedControl 既不下拉也不跳出，加了會誤導 |
+| `danger` | ❌ 不支援 | SegmentedControl 是選值，不是動作，沒有破壞性語意 |
+| `loading` | ❌ 不支援 | 載入的應是 SegmentedControl 背後的資料區，不是 item 本身 |
+
+---
+
+## Size — 直接複用 `--field-height-*`
+
+SegmentedControl 必須能塞進 `Field` 容器（就像 `Input` / `Button` / `Select`），因此 **size 完全對齊 Button / Field**：
+
+| Size | md density | lg density | token | padding | 字體 |
+|------|-----------|-----------|-------|---------|------|
+| `xs` | 24 | 24（固定）| `h-field-xs` | `px-2` | `text-caption` (12) |
+| `sm` | 28 | 32 | `h-field-sm` | `px-3` | `text-body` (14) |
+| `md` ★default | 32 | 36 | `h-field-md` | `px-3` | `text-body` (14) |
+| `lg` | 36 | 40 | `h-field-lg` | `px-3` | `text-body-lg` (16) |
+
+**為什麼 default 是 md 不是 sm**：跟 Button / Input / Select / Checkbox 等所有 field-height 系列元件的 default size 一致——consumer 在表單場景裡一組並排的 control 才能自動對齊而不用手動傳 size。違反這個一致性會讓「放著不管就對齊」的 consumer 體驗破功。
+
+**在 Field 內自動讀 size**：透過 `useFieldContext()`，SegmentedControl 在 Field 內時 size 跟著 Field 的 size 走，不需 consumer 重複指定——機制與 Button 完全相同。Field 內明確傳 `size` prop 時以 prop 為準（解析順序 prop > Field context > `md`，經 `useResolvedFieldSize` SSOT hook）。
+
+**Icon size**：xs/sm/md = 16、lg = 20（對齊 `uiSize.spec.md` Icon Size Tier L132-143 統一規則,2026-05-18 retire 過去 xs=14 例外。Cite:Carbon icon-only line tabs 40/16,Ant small input 24/16）。
+
+### xs 的專屬用途：icon-only toolbar utility
+
+跟 Button xs 相同約束——`xs` size 主要用在 **toolbar 的 icon-only compact** 場景（text editor / design canvas / 極密集空間）：
+- **24px 固定**，不隨 density 縮放
+- **主要 iconOnly 模式**（無 label 或 極短 label）
+- **不配對 Field**（Field 家族用 sm/md/lg）
+- 有 label 的 compact SegmentedControl 建議直接用 `sm`（28px）
+
+詳見 `button.spec.md`「Pill Layout → xs 的專屬用途」（兩者共用 Family 3 action trigger 規格）。
+
+---
+
+## fullWidth
+
+`fullWidth` prop（boolean，預設 `false`）：
+
+- **false（hug content）★default**：SegmentedControl 寬度由 item 總寬決定，items 各自照內容寬度排列
+- **true**：SegmentedControl 撐滿父容器，所有 item 等分該寬度。fullWidth 與 size 正交——只影響寬度分配，高度仍由 `size` 決定（xs fullWidth 仍是 24px 固定）
+
+> **不論 `fullWidth` 為何，items 之間永遠等寬或全由內容決定，不存在「撐滿但各自不同寬」的混血模式**。這是 SegmentedControl 的身份特徵，對齊 Apple HIG、Material 3 Segmented Button、Carbon ContentSwitcher 等世界級系統：「all segments have the same width」是 segmented 的視覺定義之一。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+### fullWidth 的判準：**跟著容器尺度走，跟 label 長度無關**
+
+- ✅ **小容器 / 狹窄上下文** → `fullWidth = true`
+  - Mobile viewport
+  - 窄 Sidebar 面板
+  - Dialog / Sheet 內
+  - Field 表單 row（搭配 Field 容器寬度）
+  - 原因：在小容器內，SegmentedControl 通常是該區塊的主要寬度元件，留白反而浪費
+- ✅ **寬容器 / toolbar / 跟其他 control 並排** → `fullWidth = false`（hug）
+  - Desktop 一般頁面 toolbar
+  - Filter bar 跟其他 Button / Select 並排
+  - Chart 上方 density 切換
+  - 原因：若 fullWidth，它會搶走同行其他元素的空間；hug 保持 compact 尺寸才能融入 toolbar
+
+### 常見誤解
+
+**誤解**：「label 長度差異大時不該用 fullWidth，會視覺失衡」。
+**事實**：fullWidth 永遠等分空間，各 item 視覺上等寬，不存在「短 label 周圍空白失衡」的問題。唯一需要留意的是：若 label 太長導致在狹小容器內被截斷，那是 **content overflow**（應該換 Select / 減少選項），不是 fullWidth 的問題。
+
+---
+
+## iconOnly 是 group-level，不是 item-level
+
+與 Button 不同：Button 的 `iconOnly` 是 **per-instance** prop，SegmentedControl 的 `iconOnly` 是 **group-level** prop。
+
+**理由**：SegmentedControl 作為整體，要嘛全都是 icon-only（純視覺 toolbar，如對齊左中右），要嘛全都帶 label。混搭會讓使用者無法預測哪個 item 有 tooltip、哪個沒有，也破壞 segmented 的對稱感。
+
+```tsx
+// ✅ 全部 icon-only
+<SegmentedControl iconOnly value={align} onValueChange={setAlign}>
+  <SegmentedControlItem value="left" startIcon={AlignLeft} aria-label="靠左" />
+  <SegmentedControlItem value="center" startIcon={AlignCenter} aria-label="置中" />
+  <SegmentedControlItem value="right" startIcon={AlignRight} aria-label="靠右" />
+</SegmentedControl>
+```
+
+混搭（部分 item 帶 label、部分 icon-only）禁止——見「禁止事項」。
+
+`iconOnly` 為 true 時：
+- 每個 item 變正方形（`aspect-square p-0`）
+- 每個 item 必須設定 `aria-label`（語意契約；TS 層做不到 conditional 強制，改以 dev-mode runtime `console.warn` 提醒）
+- 每個 item 自動以 `aria-label` 渲染 tooltip（與 Button icon-only 一致）
+
+---
+
+## 狀態
+
+### 選中 / 未選
+
+- **選中**：文字與邊框都用 `--primary-hover`（底色維持 surface 不變）——pill 風格元件（Chip / SegmentedControl）共用的選中規則；selected item 提升 z-index 讓邊框浮在相鄰 item 之上，避免被重疊的 border 切掉（class 實作見 `segmented-control.tsx` `data-[state=on]` cva）
+- **未選**：surface 底 + `--fg-secondary` 文字 + `--border` 邊框
+  - hover：文字轉 `--foreground` + 邊框加深一階（`--border-hover`）+ 微提升 z-index；不改 bg，避免 hover 狀態與 selected 搶戲
+
+### Item 連體手法
+
+Items 之間 `-ml-px`（除了第一個）讓相鄰 border 重疊、視覺上只有一條線。第一個 item `rounded-l-md`，最後一個 `rounded-r-md`，中間 `rounded-none`。
+
+### disabled
+
+- **整個 SegmentedControl disabled**：所有 item 變灰，不可互動
+- **個別 item disabled**：該 item 灰化，其他仍可選
+- Disabled item 不得是當前 value——consumer 必須確保 value 永遠落在可選 item 上
+
+### focus-visible
+
+由 Radix ToggleGroup 原生處理——左右箭頭在 items 間移動 focus，空白/Enter 選取。Focus ring 對齊 Button：`ring-2 ring-ring ring-offset-1`。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## 規模限制與邊界案例
+
+- **最少 2 個 item**——只有 1 個沒有選擇語意，應直接用 `Button pressed`
+- **最多 5 個 item**——超過 5 個視覺會過窄、label 被截斷，改用 `Select` / `RadioGroup`
+- **不支援 overflow / scroll**——若選項可能超出容器寬度，代表選錯元件了
+- **未傳 `value` / `defaultValue`**：初始無選中 item——違反 radio 語意（見禁止事項），consumer 必提供 default value
+- **點擊已選中 item**：不取消選取——wrapper 忽略 Radix single ToggleGroup 的 deselect（空字串），維持「恆有一值」的 radio 語意
+- **個別 item disabled**：Radix roving focus 跳過該 item（`focusable: !disabled`），方向鍵不停留；disabled item 不得是當前 value（contract，見「狀態 › disabled」）
+- **所有 item disabled**：整組無可聚焦 item，Radix roving focus 將 group 的 tab 停留點設為 `tabIndex=-1`，Tab 直接跳過
+- **disabled × fullWidth 並存**：兩者正交——fullWidth 只控寬度等分，disabled 只控互動與色彩，無交互規則
+
+---
+
+## 禁止事項
+
+- ❌ 只有 1 個 item——用 Button pressed
+- ❌ 超過 5 個 item——用 Select / RadioGroup
+- ❌ `iconOnly` 與帶 label 的 item 混搭——必須全組一致
+- ❌ 使用 `endIcon` 或 `danger` / `loading` prop——不在支援範圍
+- ❌ 用 SegmentedControl 切換整塊 content view——應用 Tabs
+- ❌ 用 SegmentedControl 做表單多選（multi-select）——應用 CheckboxGroup
+- ❌ 未傳 `value` 時預設「全都未選」——SegmentedControl 必須有 default value，這是 radio 語意
+- ❌ `iconOnly` 時省略 item 的 `aria-label`——tooltip 由元件自動產生，但 label 是必要輸入
+- ❌ 直接暴露 Radix `ToggleGroup` 的 `type="multiple"`——SegmentedControl wrapper 固定 single，不開放切換
+
+---
+
+## 為何無 ColorMatrix
+
+- **無 ColorMatrix**:SegmentedControl 沒有 Button 那種強調層級 variant(primary / secondary / tertiary / text)——只有「選中 / 未選」兩種 **state**,色彩變化純由 state 驅動(底色恆為 `bg-surface` 不變;選中 = `text-primary-hover` + `border-primary-hover`;未選 hover = `text-foreground`,詳「狀態」段)。這是 pill 風格元件(Chip / SegmentedControl)共用的選中規則,非 Button variant。因此 ColorMatrix(逐 variant 列色)不適用,狀態色已在 `StateBehavior` 完整覆蓋。
+
+對應 anatomy story:`Overview` + `Inspector` + `SizeMatrix` + `StateBehavior` + 元件特有 `FullWidthMatrix` + `IconOnlyMatrix` + `Accessibility`。Inspector 用 Storybook Controls 即時切 `size` × `fullWidth` × `iconOnly`(取代 Figma inspect);三張矩陣 story(`SizeMatrix` / `FullWidthMatrix` / `IconOnlyMatrix`)則提供結構性並排對照,兩者互補。
+
+---
+
+## 相關
+
+- `../Button/button.spec.md` — item 內部結構與 size 系統的來源
+- `../Tabs/tabs.spec.md` — container 切換 vs control 切換的判斷（完整分界 SSOT 在 Tabs spec「Tabs 與 SegmentedControl 的分界」段落）
+- `../Field/field-controls.spec.md` — SegmentedControl 作為 Field control 時的 size 繼承機制
+- `../Checkbox/checkbox.spec.md` — RadioGroup 共用規則（選項數量多或需要描述文字時的替代）
+
+## A11y 預設
+
+**ARIA / Pattern**:繼承 Radix `toggle-group` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/toggle-group#accessibility)。
+
+**Keyboard 行為**:
+
+- Tab — 進入 group(focus 落在選中項;無選中時落在上次 focus 過的 item——Radix roving focus 記住停留點,初次進入才是第一項)
+- ←/→ — 在 item 間移動 roving focus(只移焦點,不切換選取)。WAI-ARIA APG 對水平 segmented/radio group 的主要導覽鍵
+- ↑/↓ — 同 ←/→,也會在 item 間移動 roving focus。Radix `toggle-group` 未鎖 `orientation`(沿用 default 雙軸 roving),APG 接受 group 同時支援兩軸方向鍵
+- Enter / Space — 選取目前 focus 的 item
+
+**Focus**:Radix primitive 採 roving tabindex（整組共用單一 tab 停留點，方向鍵在 item 間移動焦點，不切換選取），非 Dialog 式 focus trap / restoration。Focus ring 對齊 Button focus-visible canonical（`focus-visible:ring-2 ring-ring ring-offset-1`——box-shadow ring，非 CSS outline）。
+
+**驗證**: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。若要手動補充,寫在本節之前。
+
+- `button.spec.md`
+- `chip.spec.md`
+- `horizontal-overflow.spec.md`
+- `radio-group.spec.md`
+- `select.spec.md`
+- `slider.spec.md`
+- `tabs.spec.md`

package/src/components/SegmentedControl/segmented-control.stories.tsx

@@ -0,0 +1,33 @@
+// @story-trait-rationale: 6 stories(Default/WithStartIcon/WithBadge/IconOnly/FullWidth/Disabled)
+// 2026-05-17 retire per audit Dim 24:跟 anatomy.stories.tsx 4 個 matrix
+// (Overview/IconOnlyMatrix/FullWidthMatrix/StateBehavior)完全 trait-grid 重複,無 unique teaching。
+// 真實業務情境靠 principles.stories.tsx 的 UsageGuidance / IconOnlyRule / FullWidthRule;
+// trait matrix 靠 anatomy.stories.tsx;本檔保留 1 典型「Jira-style view switcher」入口情境。
+import type { Meta, StoryObj } from '@storybook/react'
+import { useState } from 'react'
+import { List, LayoutGrid, Calendar } from 'lucide-react'
+import { SegmentedControl, SegmentedControlItem } from './segmented-control'
+
+const meta: Meta<typeof SegmentedControl> = {
+  title: 'Design System/Components/SegmentedControl/展示',
+  component: SegmentedControl,
+  parameters: { layout: 'padded' },
+}
+export default meta
+
+type Story = StoryObj<typeof SegmentedControl>
+
+// 典型 Jira / Notion / Linear view switcher 入口情境(對齊 mindset #4「真實業務場景」)
+export const ViewSwitcher: Story = {
+  name: '視圖切換器',
+  render: () => {
+    const [view, setView] = useState('list')
+    return (
+      <SegmentedControl value={view} onValueChange={setView}>
+        <SegmentedControlItem value="list" startIcon={List}>清單</SegmentedControlItem>
+        <SegmentedControlItem value="board" startIcon={LayoutGrid}>看板</SegmentedControlItem>
+        <SegmentedControlItem value="calendar" startIcon={Calendar}>行事曆</SegmentedControlItem>
+      </SegmentedControl>
+    )
+  },
+}