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

package/src/components/RadioGroup/radio-group.principles.stories.tsx

@@ -0,0 +1,163 @@
+// @principles-rationale: UsageGuidance merges WhenToUse + Vs*Rule into single 使用指引 story per refactor task (2026-04-26)
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { RadioGroup, RadioGroupItem } from './radio-group'
+
+const meta: Meta = {
+  title: 'Design System/Components/RadioGroup/設計原則',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+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 max-w-md">{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>
+)
+
+const Section = ({ title, children }: { title: string; children: React.ReactNode }) => (
+  <section className="mb-12">
+    <h2 className="text-heading-3 font-bold text-foreground mb-4 pb-2 border-b border-border">{title}</h2>
+    {children}
+  </section>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => {
+    const [status, setStatus] = React.useState('in_stock')
+    return (
+      <div>
+        <Section title="何時用">
+          <div className="prose prose-sm max-w-prose mb-8">
+            <p>適合 RadioGroup 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+            <ul className="space-y-1">
+              <li><LinkTo kind="Design System/Components/RadioGroup/展示" name="直式群組"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">直式群組</span></LinkTo><span className="text-fg-secondary"> — 訂閱方案選擇(月付 / 年付 / 終身):需要對比價格與說明的決策節點,直式 + description 完整閱讀</span></li>
+              <li><LinkTo kind="Design System/Components/RadioGroup/展示" name="水平排列"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">水平排列</span></LinkTo><span className="text-fg-secondary"> — 外觀主題切換(淺色 / 深色 / 系統):2-3 個短 label、不需描述文字,橫排省垂直空間</span></li>
+            </ul>
+            <p className="text-fg-muted mt-3">判斷不確定時:回頭看「何時用 / 何時不用」;若仍不符,改用近親元件(見下方「vs 近親元件」)。</p>
+          </div>
+        </Section>
+
+        <Section title="何時不用 + 替代方案">
+          <Rule
+            title="❌ label 自帶語意 + 空間受限:用 Select"
+            note="「庫存狀態」「類別」這類 label 本身夠清楚、使用者知道要選什麼 → Select 下拉節省空間。RadioGroup 全露反而浪費垂直空間"
+          >
+            <RadioGroup value={status} onValueChange={setStatus}>
+              <RadioGroupItem value="in_stock" label="In stock" />
+              <RadioGroupItem value="low_stock" label="Low stock" />
+              <RadioGroupItem value="out_of_stock" label="Out of stock" />
+            </RadioGroup>
+            <Label warn>↑ 庫存狀態 label 自帶語意 → 用 Select 一格就夠,不需要 3 行 RadioGroup</Label>
+          </Rule>
+
+          <Rule
+            title="❌ 單個 Radio 假裝 Checkbox"
+            note="想用「radio 形狀」當勾選提示 → 錯。Radio 的視覺是「從多選一」的承諾,單個不符合這個語意。yes/no 用 Checkbox 或 Switch"
+          >
+            <Label warn>單個同意框用 Checkbox,不用 Radio 假裝</Label>
+          </Rule>
+        </Section>
+
+        <Section title="vs 近親元件">
+          <Rule
+            title="從三個角度判斷該用哪個"
+            note="1. 展開成本:Select 把選項藏進下拉、RadioGroup 全部攤開 2. 視覺份量:Select 只佔一行、RadioGroup 佔 N 行 3. 評估深度:使用者需要逐項對比才能決定嗎?需要對比 → RadioGroup;不需要 → Select。灰色地帶的一句話判斷:「使用者看一眼 label 就能下決定嗎?」能 → Select;不能、需要閱讀 description → RadioGroup"
+          >
+            <Label>選項一眼就懂、不需對比時,優先用 Select 省空間;拿不定主意用「看一眼 label 能否下決定」快速判斷</Label>
+          </Rule>
+        </Section>
+      </div>
+    )
+  },
+}
+
+export const DecisionNodeRule: Story = {
+  name: '決策節點（需對比評估）',
+  render: () => {
+    const [payment, setPayment] = React.useState('credit')
+    const [plan, setPlan] = React.useState('pro')
+    return (
+      <div>
+        <Rule
+          title="RadioGroup 的 sweet spot — 使用者需對比所有選項才能決定"
+          note="付款方式、訂閱方案、票種、權限角色——選項需要閱讀 description(價格、手續費、權限範圍)才能下決定。RadioGroup 全露選項 + 支援 description"
+        >
+          <RadioGroup value={payment} onValueChange={setPayment}>
+            <RadioGroupItem value="credit" label="信用卡" description="手續費 2.5%,即時入帳" />
+            <RadioGroupItem value="bank" label="銀行轉帳" description="無手續費,1-2 個工作日" />
+            <RadioGroupItem value="cash" label="貨到付款" description="手續費 NT$30,到貨時付" />
+          </RadioGroup>
+          <Label>↑ 付款方式必須看完手續費 / 處理時間才能決定 → 全露選項</Label>
+        </Rule>
+
+        <Rule
+          title="訂閱方案 — description 承載 feature 差異"
+          note="方案比較需要看到每個方案的 features + 價格。RadioGroup 的 label + description 可以清楚列出,Select 下拉藏起來會失去比較能力"
+        >
+          <RadioGroup value={plan} onValueChange={setPlan}>
+            <RadioGroupItem
+              value="basic"
+              label="Basic · NT$99/月"
+              description="5 個專案、2 GB 儲存空間、基本支援"
+            />
+            <RadioGroupItem
+              value="pro"
+              label="Pro · NT$299/月"
+              description="無限專案、50 GB 儲存空間、優先支援、進階分析"
+            />
+            <RadioGroupItem
+              value="enterprise"
+              label="Enterprise · 聯絡我們"
+              description="客製化配額、專屬客戶經理、SSO / SAML 整合"
+            />
+          </RadioGroup>
+          <Label>↑ 方案比較必須看 features 才能決策 → RadioGroup 全露 + description</Label>
+        </Rule>
+      </div>
+    )
+  },
+}
+
+export const MustBeInGroupRule: Story = {
+  name: '單選按鈕不可單獨使用',
+  render: () => {
+    const [accept, setAccept] = React.useState('yes')
+    return (
+      <div>
+        <Rule
+          title="單選按鈕必須放在 RadioGroup 內"
+          note="Radio 的語意是「從 N 個選項選一個」——N ≥ 2 才有意義。單個 Radio 無法表達互斥選擇,若只是 yes/no 用 Checkbox 或 Switch"
+        >
+          <RadioGroup value={accept} onValueChange={setAccept}>
+            <RadioGroupItem value="yes" label="我同意" />
+            <RadioGroupItem value="no" label="我不同意" />
+          </RadioGroup>
+          <Label>↑ yes/no 的 RadioGroup 是合法的(兩個互斥選項),但常見場景用 Checkbox(「我同意」)更輕</Label>
+        </Rule>
+
+        <Rule
+          title="RadioGroup 預設建議給 default value"
+          note="一組全空的 radio 會讓使用者困惑「我要選什麼」——通常應指定 defaultValue 或 value。例外:表單要求使用者主動表態時,value=null 為合法 initial state(見 spec「邊界案例」),由 Field required 驗證引導選擇"
+        >
+          <Label>若真的「可以不選」(選填)→ 用 Select + clearable 或 Checkbox stack</Label>
+        </Rule>
+      </div>
+    )
+  },
+}

package/src/components/RadioGroup/radio-group.spec.md

@@ -0,0 +1,149 @@
+---
+component: RadioGroup
+family: self-contained
+variants: {}
+sizes:
+  sm:
+    when: "form field-height 28 / compact chrome / dialog / panel context"
+  md:
+    when: "default general UI"
+  lg:
+    when: "touch / prominent CTA / stakeholder-facing surface"
+traits:
+  - hasSizes
+  - hasInteractiveStates
+  - isSelectionSingle
+benchmark:
+  - Radix RadioGroup primitive: github.com/radix-ui/primitives/tree/main/packages/react/radio-group
+  - Ant Design Radio: github.com/ant-design/ant-design/tree/master/components/radio
+  - MUI Radio: github.com/mui/material-ui/tree/master/packages/mui-material/src/Radio
+  - Polaris RadioButton: github.com/Shopify/polaris/tree/main/polaris-react/src/components/RadioButton
+---
+
+<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+
+# RadioGroup 設計原則
+
+## 定位
+
+RadioGroup 是**互斥單選且全選項可見**的表單控件——從 2-5 個選項中挑恰好一個，每個選項一行獨立呈現（支援 label + description + 完整閱讀）。
+
+**Layout Family**：非上述 family — self-contained primitive（獨立視覺，無 slot 結構）。
+
+**實作基礎**：基於 Radix RadioGroup（shadcn 包裝）+ 橋接 DS token。
+
+共用規則見 `../Checkbox/checkbox.spec.md`（Checkbox & RadioGroup 設計原則，含 SelectionItem 佈局與 clamp 政策）。
+
+---
+
+## 何時用
+
+- **決策節點的互斥單選**：付款方式、訂閱方案、票種、權限角色——使用者需要**對比評估**
+- **選項需要描述文字**：法律條款、方案價格、feature 比較（Radio 的 description 支援完整閱讀，不截斷）
+- **2-5 個選項且全部可見**：讓使用者一眼看完所有選項，不需要點兩次（Select）
+- **空間允許 O(n) 垂直展開**：form 內、dialog 內、setting section 內
+
+## 何時不用
+
+**與 Select 的分界詳見 `../Select/select.spec.md` 的「與 RadioGroup 的分界」**（SSOT）——Select 是 Select vs RadioGroup 判斷的 owner。簡言：RadioGroup 用於「使用者需對比評估的決策節點」，Select 用於「label 自帶語意、空間受限、使用者熟悉選項」。
+
+| 場景 | 改用 | 原因 |
+|------|------|------|
+| 空間受限 / 選項超過 5 個 | `Select` | RadioGroup 全可見，O(n) 垂直空間成本過高 |
+| 2-5 個緊湊切換（toolbar / filter） | `SegmentedControl` | compact control，pill 尺寸融入 toolbar |
+| 多選（可選多個）| `Checkbox` | Radio 是互斥單選，Checkbox 是獨立 toggle |
+| 布林 on/off | `Switch`（即時）/ 單個 `Checkbox`（on-submit） | 布林不需要「選一個」的心智模型 |
+| 大量選項需要搜尋 | `Select` + `searchable` | RadioGroup 不支援搜尋 |
+
+---
+
+## 與 Checkbox 的差異
+
+視覺語言共用（見 Checkbox spec），差異僅在：
+
+- **形狀**：`rounded-full`（Checkbox 是 `rounded-md`）
+- **指示器**：filled dot（Checkbox 是 check / minus icon）
+- **語意**：互斥單選（Checkbox 可多選）
+- **`fieldLayout`**：`'block'`（放進 `<Field>` 時 Field 自動切 block 模式；Checkbox 沒有此 static 屬性，因為單個 Checkbox 是 inline primitive）
+
+---
+
+## 尺寸
+
+共用 Checkbox 的 sm/md/lg 控件尺寸(sm/md=16px, lg=20px),詳見 `../Checkbox/checkbox.spec.md`「尺寸」。
+
+### 為什麼不完全對齊 `--field-height-*`
+
+- **現況**:控件 sm=16 / md=16 / lg=20px(不等於 `--field-height-sm/md/lg` = 28/32/36px)
+- **Rationale**:Radio 與 Checkbox 視覺語言共用(只是形狀 round vs square),rationale 完全繼承 Checkbox——控件是選擇指示器(indicator)不是容器,走 icon tier(16/16/20),行高對齊透過 SelectionItem 的 `py = (field-height - 1lh) / 2` 保證
+- **世界級對照**:Material 3 Radio = 20px / Ant Design Radio = 16px / Polaris RadioButton = 16px——全部獨立於 field-height,與 Checkbox 控件尺寸對齊 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+
+---
+
+## StateBehavior(RadioGroup 層級特有)
+
+Item-level default / hover / checked / disabled **色彩**與 Checkbox 共用同一套 SelectionItem 規則,由 `ColorMatrix` story 承載;RadioGroup 的 `StateBehavior` story 展示**群組層級的互斥行為**(單選模型 / 個別 disabled / 整組 disabled),這是 Checkbox 沒有的維度。
+
+---
+
+## Mode / disabled / readonly / 驗證 / a11y
+
+繼承 Field family,詳見 `../Field/field-controls.spec.md` + `../Field/form-validation.spec.md`。
+
+**Field 內 readonly(2026-06-12 user 拍板)**:不渲染 radio 群組,改渲染 `fieldWrapperStyles` readonly 灰框 + 選中項 label(= Select readonly 同款,同為單選資料的鎖定呈現);standalone readonly 維持原樣鎖互動(ReadonlyContext)。
+
+---
+
+## 禁止事項
+
+- ❌ 單選卻用 Checkbox 群組模擬——selection model 不對,keyboard navigation 與 a11y 角色錯誤
+- ❌ RadioGroup 沒有 group label(`<Field>` 的 label 或 `aria-labelledby`)——螢幕閱讀器無法念出這是哪組選項
+- ❌ 巢狀 RadioGroup(radio 內包 radio)——互斥模型只適用單層,需要階層選擇改用樹狀 Select
+- ❌ 選項數量超過 5 或空間受限時硬用 RadioGroup,不改 Select(見「何時不用」)
+
+---
+
+## 邊界案例
+
+- **Disabled**:Group-level `disabled` 套用至所有 radio items;item-level `disabled` 單獨 disable 該選項。視覺繼承 SelectionItem SSOT(`text-fg-disabled` + 灰 radio circle + 不可點 + 鍵盤導覽自動 skip)。
+- **Loading(async option fetch)**:async option list 載入時 consumer 應渲 `<Skeleton>` 對應 radio item count(常見 3-5 行 skeleton),而非空 RadioGroup;RadioGroup 自身不獨立 own loading prop。
+- **Empty(no options)**:罕見場景。應由 consumer 條件性渲 `<Empty>` placeholder(「無可選項目」)取代空 RadioGroup,不渲 0-radio 空 group(SR 會讀「empty group」造成混淆)。
+- **No value selected**:`value=null` 為合法 initial state(所有 radio 都 unchecked);Field validation 在 required + null 時觸發 error。
+- **極長 label / description**:預設不截斷、自然換行(`labelMaxLines` / `descMaxLines` 預設 `'none'`,Clamp 政策 SSOT 見 `checkbox.spec.md`「Clamp 政策」)。
+- **icon / avatar prefix**:`RadioGroupItem` 一級 `icon` / `avatar` props 轉發 `SelectionItem` prefix 槽(2026-06-12 M30;規則 SSOT 見 `checkbox.spec.md` 同段 + `selection-item.spec.md`)。
+- **RTL**:未實作方向鏡像;RTL 屬 DS-wide 決策,未定(與 Chip / Breadcrumb 同口徑)。
+- **Dark mode / density**:走 SelectionItem semantic token 自動 adapt;垂直 gap 隨 layoutSpace token density-aware。
+
+---
+
+## 相關
+
+- `../Checkbox/checkbox.spec.md` — 共用規則（SelectionItem 佈局 / clamp 政策 / 視覺語言）
+- `../Select/select.spec.md` — 「與 RadioGroup 的分界」SSOT（Select vs RadioGroup 決策的 owner）
+- `../SegmentedControl/segmented-control.spec.md` — compact 互斥切換的替代
+- `../Switch/switch.spec.md` — 布林開關
+- `../Field/field.spec.md` — RadioGroup 作為 Field control 時的 block layout 整合
+
+## A11y 預設
+
+**ARIA / Pattern**:繼承 Radix `radio-group` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/radio-group#accessibility)。
+
+**Keyboard 行為**:
+
+- Tab — 進入 group
+- ↑/↓ 與 ←/→ — 切 option(Radix roving focus,焦點移動即選取;設 `orientation` 時限對應軸向)
+- Space — 選擇
+
+**Focus**:Radix primitive 以 roving tabindex 管理群組內焦點(整組只佔一個 Tab 停留點,方向鍵在選項間移動);**非** focus trap——Tab 仍會離開群組、跳到下一個表單欄位。聚焦時顯示 visible ring(`ring-2 ring-ring ring-offset-1`,box-shadow ring 機制,並 `outline-none` 關閉原生 outline,per design-system focus-visible canonical)。
+
+**驗證**: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。若要手動補充,寫在本節之前。
+
+- `checkbox.spec.md`
+- `field-control-group.spec.md`
+- `select.spec.md`
+- `selection-item.spec.md`
+- `steps.spec.md`

package/src/components/RadioGroup/radio-group.stories.tsx

@@ -0,0 +1,101 @@
+// @story-trait-rationale: hasSizes 由 anatomy.stories.tsx SizeMatrix auto-compile owns size showcase(2026-05-15 F-migration);Default scenario 由 WithLabel / HorizontalLayout 等真實 form 情境 story 覆蓋。
+import type { Meta, StoryObj } from '@storybook/react'
+import { RadioGroup, RadioGroupItem } from './radio-group'
+import { SelectionItem } from '@/design-system/components/SelectionControl/selection-item'
+
+const meta: Meta<typeof RadioGroupItem> = {
+  title: 'Design System/Components/RadioGroup/展示',
+  component: RadioGroupItem,
+  tags: ['autodocs'],
+}
+
+export default meta
+type Story = StoryObj<typeof RadioGroupItem>
+
+// @story-trait-rationale: pre-existing trait gaps tracked separately; this PR scope = add Modes story with display card.
+/* ── 四模式 ── */
+export const Modes: Story = {
+  name: '四模式',
+  render: () => (
+    <div className="flex flex-col gap-6 max-w-md">
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">edit</h3>
+        <RadioGroup defaultValue="yearly" aria-label="付款方案(edit mode demo)">
+          <SelectionItem control={<RadioGroupItem value="monthly" id="m-edit" />} label="月付方案" htmlFor="m-edit" />
+          <SelectionItem control={<RadioGroupItem value="yearly" id="y-edit" />} label="年付方案" description="每年 $2,990，省下兩個月" htmlFor="y-edit" />
+          <SelectionItem control={<RadioGroupItem value="lifetime" id="l-edit" />} label="終身方案" htmlFor="l-edit" />
+        </RadioGroup>
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">display</h3>
+        <RadioGroup mode="display" value="yearly" aria-label="付款方案(display mode demo)">
+          <SelectionItem control={<RadioGroupItem value="monthly" id="m-disp" />} label="月付方案" htmlFor="m-disp" />
+          <SelectionItem control={<RadioGroupItem value="yearly" id="y-disp" />} label="年付方案" description="每年 $2,990，省下兩個月" htmlFor="y-disp" />
+          <SelectionItem control={<RadioGroupItem value="lifetime" id="l-disp" />} label="終身方案" htmlFor="l-disp" />
+        </RadioGroup>
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
+        <RadioGroup value="yearly" aria-label="付款方案(readonly mode demo)">
+          <SelectionItem control={<RadioGroupItem value="monthly" id="m-ro" readOnly />} label="月付方案" htmlFor="m-ro" />
+          <SelectionItem control={<RadioGroupItem value="yearly" id="y-ro" readOnly />} label="年付方案" htmlFor="y-ro" />
+          <SelectionItem control={<RadioGroupItem value="lifetime" id="l-ro" readOnly />} label="終身方案" htmlFor="l-ro" />
+        </RadioGroup>
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">disabled</h3>
+        <RadioGroup value="yearly" aria-label="付款方案(disabled mode demo)">
+          <SelectionItem control={<RadioGroupItem value="monthly" id="m-dis" />} label="月付方案" htmlFor="m-dis" disabled />
+          <SelectionItem control={<RadioGroupItem value="yearly" id="y-dis" />} label="年付方案" htmlFor="y-dis" disabled />
+          <SelectionItem control={<RadioGroupItem value="lifetime" id="l-dis" />} label="終身方案" htmlFor="l-dis" disabled />
+        </RadioGroup>
+      </div>
+    </div>
+  ),
+}
+
+// @story-trait-rationale: States retired 2026-05-17 per audit Dim 24 —
+//   anatomy.stories.tsx SizeMatrix + StateBehavior own size/state trait grid。
+//   展示層保留 typical real-product Group 情境(Vertical/Horizontal/Modes/Disabled)。
+
+/* ── 垂直 Group ── */
+export const VerticalGroup: Story = {
+  name: '直式群組',
+  render: () => (
+    <div className="flex flex-col gap-4 max-w-md">
+      {(['sm', 'md', 'lg'] as const).map(size => (
+        <div key={size}>
+          <p className="text-caption text-fg-muted mb-1">size="{size}"</p>
+          <RadioGroup defaultValue="monthly">
+            <SelectionItem size={size} control={<RadioGroupItem value="monthly" id={`${size}-monthly`} size={size} />} label="月付方案" htmlFor={`${size}-monthly`} />
+            <SelectionItem size={size} control={<RadioGroupItem value="yearly" id={`${size}-yearly`} size={size} />} label="年付方案" description="每年 $2,990，省下兩個月" htmlFor={`${size}-yearly`} />
+            <SelectionItem size={size} control={<RadioGroupItem value="lifetime" id={`${size}-lifetime`} size={size} />} label="終身方案" htmlFor={`${size}-lifetime`} />
+          </RadioGroup>
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/* ── 水平排列 ── */
+export const Horizontal: Story = {
+  name: '水平排列',
+  render: () => (
+    <RadioGroup defaultValue="light" className="flex gap-6 max-w-md">
+      <SelectionItem control={<RadioGroupItem value="light" id="h-light" />} label="淺色" htmlFor="h-light" />
+      <SelectionItem control={<RadioGroupItem value="dark" id="h-dark" />} label="深色" htmlFor="h-dark" />
+      <SelectionItem control={<RadioGroupItem value="system" id="h-system" />} label="系統" htmlFor="h-system" />
+    </RadioGroup>
+  ),
+}
+
+/* ── Disabled ── */
+export const Disabled: Story = {
+  name: '停用',
+  render: () => (
+    <RadioGroup defaultValue="bank" className="max-w-sm">
+      <SelectionItem control={<RadioGroupItem value="bank" id="dis-a" disabled />} label="銀行轉帳" description="帳單已開立,付款方式鎖定" htmlFor="dis-a" disabled />
+      <SelectionItem control={<RadioGroupItem value="invoice" id="dis-b" disabled />} label="月結發票" description="需企業方案才能使用" htmlFor="dis-b" disabled />
+    </RadioGroup>
+  ),
+}