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

package/src/components/Checkbox/checkbox.principles.stories.tsx

@@ -0,0 +1,216 @@
+import React from 'react'
+import LinkTo from '@storybook/addon-links/react'
+import type { Meta, StoryObj } from '@storybook/react'
+import { Checkbox } from './checkbox'
+import { CheckboxGroup } from './checkbox-group'
+import { Switch } from '@/design-system/components/Switch/switch'
+import { RadioGroup, RadioGroupItem } from '@/design-system/components/RadioGroup/radio-group'
+
+const meta: Meta = {
+  title: 'Design System/Components/Checkbox/設計原則',
+  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 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>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+// ── UsageGuidance — 何時用 / 何時不用 / vs 近親元件(合併 WhenToUse + VsSwitchRule + CheckboxVsRadioRule) ──
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => {
+    const [agree, setAgree] = React.useState(false)
+    const [notif, setNotif] = React.useState<'checked' | 'unchecked'>('unchecked')
+    const [bluetooth, setBluetooth] = React.useState(true)
+    const [wifi, setWifi] = React.useState(true)
+    const [selected, setSelected] = React.useState('credit')
+    const [perms, setPerms] = React.useState({ read: true, write: false, admin: false })
+    return (
+      <div>
+        <Rule
+          title="何時用 — 真實業務場景"
+          note="Checkbox 用於「獨立布林開關(on/off)」或「同類選項可複選」場景 — 每個 Checkbox 的值跟其他互不影響(對比 RadioGroup 互斥)。提交前可反悔(state local),點擊即時 toggle 視覺,不需要額外確認。對齊 WAI-ARIA `role=checkbox` / Polaris Choice 共識。"
+        >
+          <ul className="space-y-1">
+            <li>
+              <LinkTo kind="Design System/Components/Checkbox/展示" name="直式群組"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">商品類別的複選清單(直式群組)</span></LinkTo>
+            </li>
+            <li>
+              <LinkTo kind="Design System/Components/Checkbox/展示" name="水平排列"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">篩選列的少量選項複選(水平排列)</span></LinkTo>
+            </li>
+          </ul>
+        </Rule>
+
+        <Rule
+          title="vs Switch — Checkbox 是表單內、隨 submit 才生效、可反悔"
+          note="勾選不代表立刻生效——使用者按「儲存」前都可以反悔。心智模型是「選擇 / 同意」，視覺語言強調「尚未確定」"
+        >
+          <div className="border border-border rounded-lg p-4 space-y-3">
+            <CheckboxGroup>
+              <Checkbox
+                label="我同意服務條款與隱私政策"
+                checked={agree}
+                onCheckedChange={(v) => setAgree(v === true)}
+              />
+              <Checkbox
+                label="訂閱行銷訊息"
+                description="每月最多 2 封，可隨時取消"
+                checked={notif === 'checked'}
+                onCheckedChange={(v) => setNotif(v ? 'checked' : 'unchecked')}
+              />
+            </CheckboxGroup>
+            <div className="flex gap-2 pt-2">
+              <button className="h-field-md px-3 text-body rounded-md bg-primary text-inverse-fg">儲存</button>
+              <button className="h-field-md px-3 text-body rounded-md border border-border">取消</button>
+            </div>
+          </div>
+          <Label>↑ 同意條款、訂閱選擇——form 內、有 submit / cancel button</Label>
+        </Rule>
+
+        <Rule
+          title="Switch — 獨立 inline、切換即生效、無 submit 流程"
+          note="使用者按下那刻 Bluetooth / Wi-Fi / 通知 就已經開 / 關。心智模型是物理開關（真實世界的 light switch），視覺語言強調「現在就是這樣」"
+        >
+          <div className="border border-border rounded-lg p-4 space-y-3">
+            <Switch label="Bluetooth" checked={bluetooth} onCheckedChange={setBluetooth} />
+            <Switch label="Wi-Fi" description="2.4 GHz + 5 GHz" checked={wifi} onCheckedChange={setWifi} />
+          </div>
+          <Label>↑ 系統設定類——獨立 inline control、旁邊沒有 submit 流程</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 用 Switch 做 form 同意"
+          note="「我同意條款」是「勾選 → 送出 → 法律成立」的書面行為。Switch 的物理開關隱喻暗示「我打開了接受條款這個功能」——心智錯位且違反約定俗成"
+        >
+          <div className="border border-border rounded-lg p-4 space-y-3">
+            <Switch label="我同意服務條款" />
+            <div className="flex gap-2 pt-2">
+              <button className="h-field-md px-3 text-body rounded-md bg-primary text-inverse-fg">送出</button>
+            </div>
+          </div>
+          <Label warn>↑ 同意條款用 Switch → 心智模型錯誤 + 與產業共識背離（全球沒有 form 用 Switch 同意條款）</Label>
+        </Rule>
+
+        <Rule
+          title="❌ 用 Checkbox 做即時系統設定"
+          note="按下 Checkbox 在使用者心智裡還是「尚未確定」——但 Bluetooth 已經開了。視覺語言和實際行為脫節，使用者會困惑「我需要再按個儲存嗎？」"
+        >
+          <Checkbox label="Bluetooth" />
+          <Label warn>↑ 即時套用用 Checkbox → 缺少「按下即生效」的視覺指示</Label>
+        </Rule>
+
+        <Rule
+          title="vs Radio — Checkbox 是獨立 toggle(多選 或 單一 agreement)"
+          note="每個 Checkbox 是獨立 boolean——可同時勾多個。也用於單一「我同意 X」agreement"
+        >
+          <CheckboxGroup>
+            <Checkbox
+              label="讀取權限"
+              description="可查看資料"
+              checked={perms.read}
+              onCheckedChange={(v) => setPerms({ ...perms, read: v === true })}
+            />
+            <Checkbox
+              label="寫入權限"
+              description="可新增 / 修改資料"
+              checked={perms.write}
+              onCheckedChange={(v) => setPerms({ ...perms, write: v === true })}
+            />
+            <Checkbox
+              label="管理權限"
+              description="可管理成員與設定"
+              checked={perms.admin}
+              onCheckedChange={(v) => setPerms({ ...perms, admin: v === true })}
+            />
+          </CheckboxGroup>
+          <Label>↑ 權限可以任意組合——多選用 Checkbox</Label>
+        </Rule>
+
+        <Rule
+          title="Radio — 互斥單選（必須在 RadioGroup 內）"
+          note="N 個選項中只能選一個，其他自動變 unchecked。通常可預選常用項；需要使用者主動表態（如付款方式）時可從未選開始（radio-group.spec.md：value=null 為合法初始態），配 required 驗證兜底"
+        >
+          <RadioGroup value={selected} onValueChange={setSelected}>
+            <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="❌ 多選一用 Checkbox"
+          note="使用者可以同時勾 3 個 → 邏輯錯誤，破壞互斥語意"
+        >
+          <CheckboxGroup>
+            <Checkbox label="信用卡" />
+            <Checkbox label="銀行轉帳" />
+            <Checkbox label="貨到付款" />
+          </CheckboxGroup>
+          <Label warn>↑ 付款方式只能一個，卻用 Checkbox 允許多選 → 用 RadioGroup</Label>
+        </Rule>
+
+        <Rule
+          title="判斷法 — 這個值旁邊有 submit / cancel button 嗎?"
+          note="有 → Checkbox;沒有、是獨立 inline control → Switch。Radio 必須在 RadioGroup 內,且至少兩個選項;單一「我同意條款」用 Checkbox。"
+        >
+          <Label>簡單記:旁邊有「儲存 / 取消」按鈕、要送出表單才生效 → Checkbox;切下去就立刻生效(像實體開關)→ Switch。</Label>
+        </Rule>
+      </div>
+    )
+  },
+}
+
+export const ClampPolicyRule: Story = {
+  name: '夾值 政策',
+  render: () => (
+    <div>
+      <Rule
+        title="Label / Description 預設不截斷（'none'）"
+        note="Checkbox / Radio 常承載法律條款、隱私聲明、條件描述——任何截斷都可能讓使用者同意沒看到的內容，是法律或道德問題。與 MenuItem 的「掃視優先」完全相反，SelectionItem 的核心訴求是「完整閱讀後同意」"
+      >
+        <Checkbox
+          label="我同意網站使用 Cookie 以改善瀏覽體驗"
+          description="包含但不限於：分析使用行為以優化內容、個人化廣告推薦、第三方服務整合（Google Analytics、Meta Pixel 等）、以及符合歐盟 GDPR 規範的使用者同意記錄。詳細條款請見隱私政策。"
+        />
+        <Label>↑ 即使文字很長也完整顯示——使用者必須看完才能勾選</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 絕不預設截斷 agreement 類 Label"
+        note="若 consumer 有合理理由（如 settings 頁掃視節奏）想截斷過長文字，需直接改用 SelectionItem 包裝 Checkbox 並傳 labelMaxLines / descMaxLines 覆寫——Checkbox 本身的 label / description prop 不提供截斷控制。截斷應該是例外，不是預設"
+      >
+        <Checkbox
+          label="我同意非常長的服務條款與隱私政策以及所有使用規範這段文字被截斷了你看不到剩下的部分"
+        />
+        <Label warn>↑ 截斷同意條款 → 使用者可能同意了看不到的內容</Label>
+      </Rule>
+
+      <Rule
+        title="Per-instance override：傳 'none' 不是 undefined"
+        note="這組覆寫設定在 SelectionItem 上（Checkbox 內部用它組合 label）。React destructure default 會把 undefined 當「沒傳」→ fallback 到預設。要明確表達「不截」請傳 'none'"
+      >
+        <Label>SelectionItem labelMaxLines='none' / labelMaxLines={1} / labelMaxLines={2}（1-6 的數字；7 以上無對應 line-clamp class，傳了不生效）</Label>
+      </Rule>
+    </div>
+  ),
+}

package/src/components/Checkbox/checkbox.spec.md

@@ -1,6 +1,6 @@
 ---
 component: Checkbox
-family: 4
+family: self-contained
 variants: {}
 sizes:
   sm:
@@ -10,6 +10,8 @@ sizes:
   lg:
     when: "touch / prominent CTA / stakeholder-facing surface"
 traits:
+  - hasSizes
+  - hasInteractiveStates
   - isSelectionMulti
 benchmark:
   - Radix Checkbox primitive: github.com/radix-ui/primitives/tree/main/packages/react/checkbox
@@ -18,7 +20,8 @@ benchmark:
   - Polaris Checkbox: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Checkbox
 ---
 
-<!-- @benchmark-cited: D5 retrofit 2026-05-18 — body claims marked per-claim @benchmark-unverified inline; canonical source URLs in frontmatter benchmark list. -->
+<!-- @spec-budget-exception: SSOT-heavy 例外(`AGENTS.md`「行數預算」的 foundational SSOT 例外 ≤800-1200)— 本檔持有跨元件 SSOT:「與 Switch 的分界」(~45 行)+「Clamp 政策(Label/Description 行數)」(~35 行);2026-07-14 knowledge-prune P2 結論「殘餘超標內容全是 canonical,再砍必動 meaning」(.claude/logs/prune-p2-candidates.md)。 -->
+
 
 # Checkbox 設計原則
 
@@ -90,6 +93,12 @@ Checkbox 和 Radio 是**表單內的選擇控件**，視覺語言完全一致，
 
 - 在 form 裡、旁邊有 submit button / cancel button → **Checkbox**
 - 獨立的 inline control、旁邊沒有 submit 流程 → **Switch**
+- **常見誤解**:「無 submit button 就一定用 Switch」→ 錯。判準是上方三角度(套用時機優先);值仍屬 form 欄位語意(暫存後一併儲存)就用 Checkbox,本 heuristic 只是輔助
+
+### 常見誤解(其餘)
+
+- 只傳 `checked` 不傳 `onCheckedChange` ≠ readonly——那只是值鎖死,仍可 focus / click;readonly 必用 `readOnly` prop(見「Controlled / Uncontrolled API」)
+- `<Field disabled>` cascade 與自身 `disabled` prop 同效(SSOT resolver),不需兩處都傳
 
 ### 情境對照表
 
@@ -123,35 +132,26 @@ Checkbox 和 Radio 是**表單內的選擇控件**，視覺語言完全一致，
 
 - **現況**:控件 sm=16 / md=16 / lg=20px(不等於 `--field-height-sm/md/lg` = 28/32/36px)
 - **Rationale**:Checkbox 控件是**選擇指示器**(indicator),不是容器;field-height 是「可編輯 control 的容器高度」,indicator 視覺上要明顯小於容器,才符合「選項前有個小方框」的心智模型。控件本體走 icon tier(sm/md=16, lg=20),行高對齊透過 SelectionItem 的 `py = (field-height - 1lh) / 2` 保證(控件垂直置中於 1lh 容器)
-- **世界級對照**:Material 3 Checkbox = 18px touch target 內的 18px container / Ant Design Checkbox = 16px 控件 / Polaris Checkbox = 16px——全部獨立於 field-height,控件 icon 與 field 分離是共識 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+- **幾何 owner**:Checkbox control 與 field-height 分開管理；field row 擁有可點範圍與垂直置中，control source 擁有 icon box 的確切尺寸。
 
 ---
 
 ## Label 對齊
 
-Checkbox/Radio 不內建 label。Label 組合使用 `SelectionItem` 元件。
+Checkbox/Radio 控件本體不畫 label——label 由 `SelectionItem` 承載:提供一級 `label` / `description` props 時元件內部自動包 `SelectionItem`(checkbox.tsx,consumer 不手刻);需自訂佈局時才手動組合 `SelectionItem`。
 
-對齊機制：
-1. 外層 `<div>` 設 `text-body` / `text-body-lg`（建立 line-height context）
-2. 控件包在 `h-[1lh]` 的容器內（容器高度 = 一行文字高度）
-3. `flex items-center`（控件在文字行高內垂直置中）
-4. 外層 `flex items-start`（多行時控件對齊第一行）
+**icon / avatar prefix(2026-06-12 M30 轉發)**:一級 `icon`(LucideIcon)/ `avatar`(AvatarData)props 直接轉發 `SelectionItem` 既有三槽 canonical 的 prefix 槽(互斥;尺寸與 inline/block 對齊規則 SSOT = `selection-item.spec.md`「3-slot 結構」+ selection-item.tsx jsDoc)。RadioGroupItem 同。
 
-`1lh` 在 `<div>` 上正常繼承，改字體自動重算。
+對齊機制(`text-body[-lg]` 建立 `1lh` context / 控件包 `h-[1lh]` 容器垂直置中 / 外層 `items-start` 多行對齊第一行)**SSOT → `../SelectionControl/selection-item.spec.md`「結構 / 字體」**,本 spec 不重述(2026-07-14 收斂原重述段,措辭已現 drift)。
 
 ---
 
 ## SelectionItem 佈局
 
-垂直排列和水平排列共用 `SelectionItem`。
-
-| | 垂直 | 水平 |
-|---|---|---|
-| Item 間距 | 0（padding 處理） | 24px（gap-6） |
-| Item padding | `py = (field-height - 1lh) / 2` | 同左 |
-| Label ↔ Description | 2px（`--item-gap-label-desc-reading` / `-reading-lg`,size-aware） | 同左 |
-| 單行高度 | = field-height（對齊 Input） | 同左 |
-| 多行高度 | padding 維持不變，總高度 = `1lh × line-count + py × 2` | — |
+垂直排列和水平排列共用 `SelectionItem`,各值 SSOT 不重述:
+- **Item padding / 單行高度 = field-height / 多行撐高公式** → `selection-item.spec.md`「Padding 公式」(`py = (field-height - 1lh) / 2`)
+- **Label ↔ Description 2px gap** → `item-anatomy.spec.md`「Label ↔ Desc 間距」(`--item-gap-label-desc-reading[-lg]`,size-aware)
+- **Item 間距**(垂直 0 / 水平 `gap-4`)→ 下方「群組模式」zero-gap 鐵律 + Orientation 段
 
 ---
 
@@ -199,14 +199,16 @@ Checkbox / Radio 在 form 內承載的常常是:
 | 狀態 | 邊框 | 底色 | 指示器 |
 |------|------|------|--------|
 | unchecked | border | surface | 無 |
-| checked | primary | primary | white check |
-| indeterminate | primary | primary | white minus |
-| hover unchecked | neutral-6 | surface | 無 |
-| hover checked | primary-hover | primary-hover | white check |
-| hover indeterminate | primary-hover | primary-hover | white minus |
-| disabled unchecked | 無 | neutral-2 | 無 |
-| disabled checked | 無 | neutral-2 | fg-disabled check |
-| disabled indeterminate | 無 | neutral-2 | fg-disabled minus |
+| checked | primary | primary | on-emphasis check |
+| indeterminate | primary | primary | on-emphasis minus |
+| hover unchecked | border-hover | surface | 無 |
+| hover checked | primary-hover | primary-hover | on-emphasis check |
+| hover indeterminate | primary-hover | primary-hover | on-emphasis minus |
+| disabled unchecked | transparent | bg-disabled | 無 |
+| disabled checked | transparent | bg-disabled | fg-disabled check |
+| disabled indeterminate | transparent | bg-disabled | fg-disabled minus |
+
+(token 名對齊 `checkbox.tsx` cva 真值;表內一律 semantic token,不寫視覺色名)
 
 ### Indeterminate（半選）
 
@@ -214,7 +216,9 @@ Checkbox / Radio 在 form 內承載的常常是:
 
 典型場景：SelectMenu 的「全選」checkbox——當部分選項被勾選時顯示 indeterminate。
 
-Indeterminate 是由父層邏輯控制的狀態，Checkbox 本身不會自動進入 indeterminate——必須明確傳入 `checked="indeterminate"`。
+Indeterminate 是由父層邏輯控制的狀態，Checkbox 本身不會自動進入 indeterminate——必須明確傳入 `checked="indeterminate"`（controlled 與 uncontrolled `defaultChecked="indeterminate"` 皆正確渲染 Minus——圖示切換由 Radix `data-state` CSS 驅動,2026-07-14 修復原「只讀 `props.checked`」的 uncontrolled known-gap）。**常見誤解**:「部分子項已選」不可用 disabled + checked 混搭表達——半選是可互動狀態,disabled 是鎖互動,語意不同。
+
+**狀態切換視覺**(code 真值):unchecked ↔ checked / indeterminate 之間色彩走 `transition-colors` 150ms;Check ↔ Minus 圖示由 `data-state` CSS 即時 swap,無過渡動畫。
 
 ### Radio
 
@@ -222,10 +226,14 @@ Indeterminate 是由父層邏輯控制的狀態，Checkbox 本身不會自動進
 |------|------|------|--------|
 | unchecked | border | surface | 無 |
 | checked | primary | surface | primary dot |
-| hover unchecked | neutral-6 | surface | 無 |
+| hover unchecked | border-hover | surface | 無 |
 | hover checked | primary-hover | surface | primary-hover dot |
-| disabled unchecked | 無 | neutral-2 | 無 |
-| disabled checked | 無 | neutral-2 | fg-disabled dot |
+| disabled unchecked | transparent | bg-disabled | 無 |
+| disabled checked | transparent | bg-disabled | fg-disabled dot |
+
+### Loading（N/A）
+
+Checkbox / Radio **無 Loading 狀態**——選擇控件是同步 toggle,值隨 form submit 才套用(見「定位」),不承載非同步進度。提交進行中的 loading 狀態由**表單的 submit `Button` loading state** 擁有;提交期間若需鎖定選項,將 Checkbox 設 `disabled` 即可,不在控件本體加 spinner。（對齊 Switch spec「無 loading state」——async 進度不屬選擇控件本體。）
 
 ---
 
@@ -235,15 +243,27 @@ Indeterminate 是由父層邏輯控制的狀態，Checkbox 本身不會自動進
 
 - **Uncontrolled**:只傳 `defaultChecked`,DOM 自管 — 適合表單 native submit
 - **Controlled**:傳 `checked` + `onCheckedChange`,React state 主導 — 適合需即時聯動其他欄位
-- **Read-only**:傳 `checked` 不傳 `onCheckedChange` → Radix 視同 controlled disabled state
+- **Read-only**:用 `readOnly` prop(不是省略 `onCheckedChange`)。standalone:`readOnly` 設 `aria-readonly` / `data-readonly` / `tabIndex=-1` + cva `pointer-events-none` + onClick preventDefault guard(2026-07-05 D4 補:`<label htmlFor>` 的 synthetic click 非 pointer event,`pointer-events-none` 攔不到,需 guard 才真鎖),鎖互動但保留 checked 視覺;**Field 內(無 inline label)改渲染 readonly 灰框 + ✓/—**(見上方 mode 段)。注意:只傳 `checked` 而不傳 `onCheckedChange` 僅讓 Radix 把值鎖在 prop(不會更新),控件仍可 focus / click、不會進 disabled state — 那不是 readonly
+
+### `mode` prop(Field mode,正交於 size)
+
+`mode?: 'edit' | 'view' | 'readonly' | 'disabled'`(默認 inherit Field context 或 `'edit'`),對齊 `field-types.ts` FieldMode(完整 4-mode canonical SSOT → `Field/field-controls.spec.md`;本段鏡像 switch.spec.md 同名段):
+- `edit`(預設)— 可勾選的 Checkbox。
+- `view` — **純展示**:渲染 **Check icon(true=勾)/ X icon(false=叉)**,中性 `text-foreground` 色,非互動、無 input chrome,供 DataTable boolean cell 非編輯態共用。boolean 值符號 SSOT = `../SelectionControl/boolean-value.tsx`(勾/叉 icon + 中性色;M22 世界級:MUI X DataGrid Check/Close icon 中性色 / React-admin TrueIcon-FalseIcon;false 中性非紅 = 「否」值非「錯誤」)。
+- `readonly` — **Field 內(無 inline label)**= `fieldWrapperStyles` readonly 灰框 + 勾/叉 icon(與 Input readonly 同一視覺語言,2026-06-12 user 拍板;世界級:Salesforce output ✓ glyph / SAP 靜態文字);**standalone / 有 inline label**(SelectionItem row)= 正常色鎖互動(同下方 Read-only)。
+- `disabled` — 落到真 disabled chrome(`effectiveDisabled`,2026-06-12 修:mode='disabled' 直傳〔如 `<Field mode="disabled">` cascade〕與 `disabled` prop 等效,降色 + 不可 focus)。DataTable cell 無 disabled 態(已廢除);cell 非編輯態 = `view` 純展示。
+
+CheckboxGroup 是純 layout primitive — **不**持有 group-level selection state(無 `value` / `defaultValue` / `onValueChange`)。每個 `<Checkbox>` child 各自管自己的 `checked` / `defaultChecked` / `onCheckedChange`;CheckboxGroup 只透過 `CheckboxGroupContext` 告知 child「你在 group 裡」(保留各自 label)。
 
-CheckboxGroup 額外提供 `value` / `defaultValue` / `onValueChange`(string[] 多選 array)— group-level controlled 模式;item 不傳獨立 onChange(group 統一 dispatch)。
+### 表單驗證接線(useFormValidation v1 邊界)
+
+Checkbox 值走 `onCheckedChange`(非 value/onChange 型控件),接 `useFormValidation`(`../Field/form-validation.spec.md`)時用 **`setFieldValue` 自接、不經 `getInputProps`**。這是該 spec「v1 邊界」誠實記載的已知限制:**無自動 blur 驗證 / 邊改邊清 error**(該層 timing 只覆蓋 value/onChange 型控件)—— Checkbox 值變更後由 consumer 於 `setFieldValue` 後自行 re-validate,或隨 submit 全驗。**error 視覺不受此限制影響**:`Field invalid` context 是 engine-agnostic 的,紅框 + `FieldError` 照常呈現;`<Field>` 錯誤群組化見 field.spec.md。
 
 ---
 
 ## 群組模式(CheckboxGroup)
 
-**`<CheckboxGroup>`** 是多選 Checkbox 的 layout primitive,跟 `<Checkbox>` **同資料夾**(合併於 2026-04-21,原單獨 `CheckboxGroup/` folder 併入)。對齊 Ant Design `Checkbox.Group` / Chakra `CheckboxGroup` / Mantine `Checkbox.Group` 世界級:standalone + group 家族同資料夾。 <!-- @benchmark-unverified: see frontmatter benchmark list for canonical DS source URL -->
+**`<CheckboxGroup>`** 是多選 Checkbox 的 layout primitive,跟 `<Checkbox>` **同資料夾**(合併於 2026-04-21,原單獨 `CheckboxGroup/` folder 併入)。兩者共享 selection semantics、Field integration 與 group context，因此由同一元件家族維護。
 
 ### Canonical 鐵律:零外部 gap
 
@@ -290,12 +310,6 @@ Horizontal 需 `gap-4` 因 row 的 py 不擴散到左右。
 ### 用法範例
 
 ```tsx
-<CheckboxGroup>
-  <Checkbox label="待處理" defaultChecked />
-  <Checkbox label="進行中" defaultChecked />
-  <Checkbox label="已完成" />
-</CheckboxGroup>
-
 <Field orientation="horizontal">
   <FieldLabel>通知方式</FieldLabel>
   <CheckboxGroup orientation="horizontal">
@@ -306,12 +320,14 @@ Horizontal 需 `gap-4` 因 row 的 py 不擴散到左右。
 </Field>
 ```
 
+（垂直 group / defaultChecked 等更多場景 → `checkbox.stories.tsx`）
+
 ---
 
 ## 禁止事項
 
 - ❌ Radio 不可單獨使用——必須在 RadioGroup 內
-- ❌ Checkbox 不內建 label——label 組合用 SelectionItem
+- ❌ 不手刻外部 `<label>` 排版——用 `label` prop(內部自動包 SelectionItem)或手動組合 `SelectionItem`
 - ❌ 垂直 CheckboxGroup 加 `gap-y-*` / `space-y-*`——違反 zero-gap canonical
 - ❌ 多選一不用 Checkbox——用 Radio 或 Select
 - ❌ 即時套用的布林開關用 Checkbox——用 Switch（見「與 Switch 的分界」）
@@ -327,12 +343,13 @@ Horizontal 需 `gap-4` 因 row 的 py 不擴散到左右。
 - `../RadioGroup/radio-group.spec.md` — Radio 的 group 容器 + 結構對稱 reciprocal
 - `../SelectionControl/selection-item.spec.md` — Checkbox / Radio 共用的 SelectionItem 佈局 primitive（本 spec 的 Clamp 政策為其 SSOT）
 - `../Field/field-controls.spec.md` — Field Control 共用規則
+- `../Field/form-validation.spec.md` — 表單驗證引擎;Checkbox 用 `setFieldValue` 自接的 v1 邊界見「Controlled / Uncontrolled API → 表單驗證接線」
 
 ## A11y 預設
 
 **ARIA / Pattern**:繼承 Radix `checkbox` primitive a11y 預設(role / aria-* / 鍵盤導覽)。詳 [Radix Accessibility docs](https://www.radix-ui.com/primitives/docs/components/checkbox#accessibility)。
 
-**Focus**:Radix primitive 自管 focus trap / restoration / visible ring(`outline: 2px solid var(--ring)` per design-system focus-visible canonical)。
+**Focus**:單一 toggle 控件,無 focus trap / restoration(那是 Dialog / Sheet 等浮層容器的行為);聚焦中被切 disabled 時由瀏覽器原生 drop focus(native disabled button 行為),不另行管理。鍵盤聚焦時顯示 visible ring(`focus-visible:ring-2 ring-ring ring-offset-1` per design-system focus-visible canonical)。
 
 **驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
@@ -340,5 +357,11 @@ Horizontal 需 `gap-4` 因 row 的 py 不擴散到左右。
 
 > 本節由 `scripts/add-reciprocal-pointers.mjs` 自動維護,列出在 SSOT 語境下指向本 spec 的其他 spec。若要手動補充,寫在本節之前。
 
+- `combobox.spec.md`
+- `field-control-group.spec.md`
 - `menu-item.spec.md`
+- `radio-group.spec.md`
 - `segmented-control.spec.md`
+- `select.spec.md`
+- `selection-item.spec.md`
+- `switch.spec.md`

package/src/components/Checkbox/checkbox.stories.tsx

@@ -0,0 +1,119 @@
+// @story-history: hasSizes/hasInteractiveStates 由 anatomy.stories.tsx SizeMatrix + StateBehavior
+// owns 完整 trait grid;展示層 States 保留為 compact all-states overview(對齊 Switch 同 Family 檔頭豁免,
+// 2026-07-14 audit Dim 46 補),跟 anatomy focused subsection 不同教學,不另開抽象 Default/AllSizes。
+import type { Meta, StoryObj } from '@storybook/react'
+import { Checkbox } from './checkbox'
+
+const meta: Meta<typeof Checkbox> = {
+  title: 'Design System/Components/Checkbox/展示',
+  component: Checkbox,
+  tags: ['autodocs'],
+  parameters: {
+    docs: { description: { component: '切換彼此獨立的布林選項，支援 checked、unchecked 與 indeterminate。使用者可以同時選多項或單獨同意條款時使用；互斥選擇改用 RadioGroup。' } },
+  },
+}
+
+export default meta
+type Story = StoryObj<typeof Checkbox>
+
+/* ── 四模式 ── */
+export const Modes: Story = {
+  name: '四模式',
+  render: () => (
+    <div className="flex flex-col gap-6 max-w-sm">
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">edit</h3>
+        <Checkbox defaultChecked aria-label="同意條款(edit mode demo)" />
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">view</h3>
+        <Checkbox mode="view" checked />
+        <p className="text-caption text-fg-muted mt-1">純視覺 glyph（勾/叉 icon，Check/X）；語意由 context（如 DataTable 表頭 + 行標籤）提供，view 不暴露獨立 aria-label。需螢幕報讀器可讀的勾選請用 edit / readonly 模式。</p>
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">readonly</h3>
+        <Checkbox readOnly checked aria-label="同意條款(readonly mode demo)" />
+      </div>
+      <div>
+        <h3 className="text-body font-bold text-foreground mb-2">disabled</h3>
+        <Checkbox disabled checked aria-label="同意條款(disabled mode demo)" />
+      </div>
+    </div>
+  ),
+}
+
+/* ── 狀態 ── */
+export const States: Story = {
+  name: '狀態',
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <div>
+        <p className="text-caption text-fg-muted mb-2">md（16px，預設）</p>
+        <div className="flex items-center gap-4">
+          <Checkbox aria-label="off" />
+          <Checkbox defaultChecked aria-label="on" />
+          <Checkbox checked="indeterminate" aria-label="indeterminate" />
+          <Checkbox disabled aria-label="disabled off" />
+          <Checkbox disabled defaultChecked aria-label="disabled on" />
+          <Checkbox disabled checked="indeterminate" aria-label="disabled indeterminate" />
+        </div>
+        <div className="flex items-center gap-4 mt-1 text-[10px] text-fg-muted">
+          <span className="w-4 text-center">off</span>
+          <span className="w-4 text-center">on</span>
+          <span className="w-4 text-center">—</span>
+          <span className="w-4 text-center">off</span>
+          <span className="w-4 text-center">on</span>
+          <span className="w-4 text-center">—</span>
+        </div>
+      </div>
+      <div>
+        <p className="text-caption text-fg-muted mb-2">lg（20px）</p>
+        <div className="flex items-center gap-4">
+          <Checkbox size="lg" aria-label="off" />
+          <Checkbox size="lg" defaultChecked aria-label="on" />
+          <Checkbox size="lg" checked="indeterminate" aria-label="indeterminate" />
+          <Checkbox size="lg" disabled aria-label="disabled off" />
+          <Checkbox size="lg" disabled defaultChecked aria-label="disabled on" />
+          <Checkbox size="lg" disabled checked="indeterminate" aria-label="disabled indeterminate" />
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+/* ── 垂直 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>
+          <div className="grid">
+            {/* 公開 API:`<Checkbox label>` 自動包 SelectionItem + wire id/htmlFor(selection-item.spec.md 禁裸用) */}
+            <Checkbox size={size} label="Electronics" />
+            <Checkbox size={size} label="Furniture" description="桌椅、收納、辦公家具" />
+            <Checkbox size={size} label="Food & Beverage" />
+          </div>
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/* ── 水平排列 ── */
+export const Horizontal: Story = {
+  name: '水平排列',
+  render: () => (
+    <div className="flex gap-4 max-w-md">
+      <Checkbox label="Electronics" />
+      <Checkbox label="Furniture" />
+      <Checkbox label="Food" />
+    </div>
+  ),
+}
+
+// @story-history: Disabled retired 2026-05-17 per audit Dim 24/25 strict re-run —
+//   anatomy.stories.tsx StateBehavior「Disabled — 品牌色移除,統一 neutral」段(L535-558)已 cover。
+//   非 trait-required(`isSelectionMulti` 不 mandate Disabled);RadioGroup 同 Family 已 retire 同類。
+//   States showcase (compact all-states overview)保留,跟 anatomy「focused subsection」不同教學。