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

package/src/components/SelectionControl/selection-item.spec.md

@@ -0,0 +1,141 @@
+---
+component: SelectionItem
+family: 2
+variants: {}
+sizes:
+  sm: {}
+  md: {}
+  lg: {}
+traits:
+  - hasSizes
+  - isStructural
+  - isInternal
+benchmark:
+  - Radix Checkbox primitive: github.com/radix-ui/primitives/tree/main/packages/react/checkbox
+  - Radix RadioGroup primitive: github.com/radix-ui/primitives/tree/main/packages/react/radio-group
+  - Polaris Checkbox: github.com/Shopify/polaris/tree/main/polaris-react/src/components/Checkbox
+---
+
+# SelectionItem 設計原則
+
+## 定位
+
+SelectionItem 是 **Checkbox 和 RadioGroup 共用的 item 佈局 primitive**——提供 control + optional prefix（icon/avatar）+ content（label/description）的 3-slot 結構，並處理 padding 公式（`py = (field-height - 1lh) / 2`）讓單行高度對齊同 size 的 Input。
+
+> **關於資料夾命名**: `SelectionControl/` 是**概念群組**名稱（對齊 `Menu/` 包 `menu-item.tsx` / `Field/` 包 `field.tsx` 的專案慣例），其內包含主要 primitive `selection-item.tsx`。未來可能增加 `selection-indicator.tsx` 等相關 primitive 到同一資料夾。spec / file 以 main primitive 為準命名(見 `menu-item.spec.md` 先例)。
+
+**實作基礎**：自建 internal primitive——純視覺佈局 + padding 公式，無 external primitive base。
+
+**Layout Family**：CLAUDE.md 4-Family Model **Family 2（List item layout）** 消費者。結構繼承 `patterns/element-anatomy/item-anatomy.spec.md`「List item layout」章節的 reading-mode 規格。SelectionItem 是 Family 2 的 SelectionItem variant：prefix 放 Checkbox/Radio indicator 而非 icon/avatar。
+
+---
+
+## 何時用 / 何時不用
+
+**SelectionControl 是 internal primitive**——不直接使用，透過 Checkbox / RadioGroup 消費。
+
+**icon / avatar prefix 消費路徑(2026-06-12 M30 修)**:`<Checkbox icon={...}>` / `<RadioGroupItem avatar={...}>` 直接轉發本 primitive 的既有槽(本檔「3-slot 結構」+ selection-item.tsx jsDoc 為對齊規則 SSOT)——不需也不准裸用 `<SelectionItem>`。
+
+| 場景 | 正確做法 |
+|------|---------|
+| 建立一組 Checkbox 選項 | 用 `Checkbox`（內部消費 SelectionItem）|
+| 建立一組 Radio 選項 | 用 `RadioGroup` + `RadioGroupItem`（內部消費 SelectionItem）|
+| 直接用 `<SelectionItem>` | ❌ **禁止**——會失去 Checkbox / Radio 的 ARIA state、keyboard、form integration |
+
+---
+
+## 為什麼要獨立 primitive
+
+Checkbox 和 Radio 視覺幾乎完全一致（差異只在形狀 `rounded-md` vs `rounded-full` 和指示器 check icon vs filled dot），佈局邏輯（control / prefix / content 對齊、`py` padding 公式、clamp 政策、disabled 狀態處理）100% 共享。
+
+**不獨立**的話兩邊各自實作會漂移——某天改了 Checkbox 的 gap 或 clamp，Radio 會忘記同步。獨立成 SelectionItem 保證兩者視覺 / 行為永遠一致。
+
+---
+
+## 結構
+
+```
+[control]  [optional prefix (icon | avatar)]  [content: label + description]
+```
+
+- `flex items-start gap-2`：控件與 content 對齊第一行
+- 控件包在 `h-[1lh]` 容器中，跟第一行文字垂直置中
+- 多行 label 時，控件保持對齊第一行（不跳到中間）
+
+### 字體
+
+- `text-body` (sm/md) / `text-body-lg` (lg)——建立 `1lh` context 讓控件高度跟隨字體
+
+### Padding 公式
+
+`py = (field-height - 1lh) / 2`
+
+- 單行時總高度 = field-height（對齊同 size 的 Input）
+- 多行時 padding 不變，自然撐高
+- density 切換時 field-height 自動調整，padding 跟著算
+- **size 對應**：sm / md → `text-body` + `--field-height-{sm,md}`；lg → `text-body-lg` + `--field-height-lg`——與同 size Input 消費同一 token，是「單行高度對齊 Input」的機械保證
+
+### Clamp 政策
+
+見 `../Checkbox/checkbox.spec.md`「Clamp 政策」——Label / Description 預設 `'none'`（完整閱讀優先），非「掃視優先」。
+
+---
+
+## 禁止事項
+
+- ❌ 直接在 JSX 用 `<SelectionItem>`——透過 Checkbox / Radio 消費
+- ❌ 在 Checkbox / Radio 之外複製 SelectionItem 邏輯——共用源頭一定是 SelectionControl
+- ❌ 改動 `py` padding 公式只針對某一 variant——Checkbox 和 Radio 必須同步
+
+---
+
+## 為何無 ColorMatrix / StateBehavior
+
+SelectionItem 是**純 layout primitive**,只處理 3-slot 結構 + padding 公式,無獨立色彩與互動狀態:
+
+- **無 ColorMatrix**:SelectionItem 本身**不設** bg / border color,也**不擁有** control 視覺(Checkbox 方框 / Radio 圓圈)——control 由 consumer 傳入(`control` prop 接 ReactNode)。色彩決策屬於 Checkbox / Radio 層級,其 `.anatomy.stories.tsx` 負責 ColorMatrix(如 Checkbox 的 unchecked / checked / indeterminate × default / hover / disabled 矩陣)。
+- **無 StateBehavior**:SelectionItem 只有 `disabled` 把所有文字 / icon 載體統一切 `text-fg-disabled`(label / description / prefix icon,M24 disabled>muted),無 selected / checked / hover / active——這些狀態屬於傳入的 `control`。Disabled 行為在 `Inspector` 的 props 已足夠展示,不需獨立 story。
+
+對應 anatomy story:保留 `Overview` / `Inspector` / `SizeMatrix`,額外追加元件特有的 `PrefixAlignment`(展示 24px 閾值下 icon/avatar 的 inline vs block 對齊行為——這是 SelectionItem 最重要的結構規則,取代 ColorMatrix)。
+
+---
+
+## 邊界案例
+
+- **Disabled**:`disabled` 把 label / description / prefix icon 統一切 `text-fg-disabled`(M24 disabled>muted);control(Checkbox 方框 / Radio 圓圈)的 disabled 視覺由 consumer control 自己 own。SelectionItem 不獨立 own control state。
+- **Loading**:SelectionItem 為 layout primitive 非 async surface;無 loading state。傳入的 control(Checkbox / Radio)亦無 loading prop(tsx 驗證);group-level loading 由 consumer(CheckboxGroup / RadioGroup)在外層處理(Skeleton stack)。
+- **Empty**:label 為 required prop(省略 = TS error);傳空字串不防呆——會渲染空 `<label>`(點擊目標退化),consumer(Checkbox / RadioGroup)契約上必傳有效 label。若 `description` 缺,layout 自動收斂為單行。
+- **Dark mode / density**:走 semantic token 自動 adapt;`py` padding 公式對齊 `--field-height-{sm/md/lg}` density token。
+
+---
+
+## 相關
+
+- `../Checkbox/checkbox.spec.md` — 主要消費者之一，含 Clamp 政策 SSOT
+- `../RadioGroup/radio-group.spec.md` — 另一消費者
+- `../../patterns/element-anatomy/item-anatomy.spec.md` — 4-slot 結構的 pattern 來源
+- `../../tokens/uiSize/uiSize.spec.md` — `--field-height-*` token
+
+## A11y 預設
+
+SelectionItem 是純佈局元件,本身**不接管**鍵盤、焦點與勾選狀態——只渲染外層 `<div>` 容器加上指向控件的 `<label htmlFor>`(點文字會觸發控件)。鍵盤、焦點環、勾選都由傳入的 `control`(Checkbox / Radio)負責。
+
+**ARIA / Pattern**:對齊 [W3C ARIA Authoring Practices Guide](https://www.w3.org/WAI/ARIA/apg/patterns/) 對應 checkbox / radio pattern——由 control 提供。
+
+**Keyboard 行為**(由 control 提供,SelectionItem 無 keyboard handler):
+
+- Tab — focus 落在 control 本身
+- Space — 由 control 切換勾選狀態
+
+**Focus**:focus-visible ring 對齊 DS canonical(`outline: 2px solid var(--ring)`),由 control 自己畫;SelectionItem 不獨立 own focus management。
+
+**驗證**: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`
+- `item-anatomy.spec.md`
+- `menu-item.spec.md`
+- `radio-group.spec.md`

package/src/components/SelectionControl/selection-item.stories.tsx

@@ -0,0 +1,137 @@
+// @story-trait-rationale: SelectionControl 是 isInternal primitive,被 Checkbox / RadioGroup 消費;hasSizes 由 anatomy.stories.tsx SizeMatrix auto-compile owns size showcase(2026-05-15 F-migration);Default 由 NotificationPreferences / PlanPicker 等真實 consumer 情境覆蓋。
+import type { Meta, StoryObj } from '@storybook/react'
+import { Mail, Bell, Folder, Shield } from 'lucide-react'
+import { SelectionItem } from './selection-item'
+import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
+import { RadioGroup, RadioGroupItem } from '@/design-system/components/RadioGroup/radio-group'
+
+const meta: Meta<typeof SelectionItem> = {
+  title: 'Design System/Internal/SelectionControl/展示',
+  component: SelectionItem,
+  tags: ['!dev'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'SelectionItem 是 Checkbox 與 RadioGroup 共用的 item 佈局 primitive——提供 control + optional prefix(icon/avatar) + content(label/description) 的 3-slot 結構,並處理 `py = (field-height - 1lh) / 2` 的 padding 公式讓單行高度對齊同 size 的 Input。App 層級應使用 Checkbox / RadioGroup,不直接使用 SelectionItem——前兩個情境展示 primitive 被 Checkbox / RadioGroup 包出的樣貌;後兩個(前綴圖示 / 前綴頭像)直接以 primitive 展示 prefix slot 結構(docs 結構展示用,非 App 層用法)。',
+      },
+    },
+  },
+}
+export default meta
+type Story = StoryObj<typeof SelectionItem>
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 1:Checkbox consumer — 通知偏好設定
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+export const NotificationPreferences: Story = {
+  name: '通知偏好',
+  render: () => (
+    <div className="flex flex-col gap-2 max-w-md">
+      <p className="text-caption text-fg-muted mb-2">
+        帳號設定頁 — 勾選要接收的通知類型。由 Checkbox 消費 SelectionItem 提供結構。
+      </p>
+      <Checkbox defaultChecked label="產品更新電子報" description="每兩週寄送,可隨時取消訂閱" />
+      <Checkbox label="安全性警告" description="登入裝置變動、密碼變更等重要事件" />
+      <Checkbox defaultChecked label="Workspace 邀請通知" />
+      <Checkbox label="行銷活動優惠" description="我想收到優惠碼與限時活動資訊" />
+    </div>
+  ),
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 2:RadioGroup consumer — 計畫方案選擇
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+export const PlanPicker: Story = {
+  name: '方案選擇',
+  render: () => (
+    <div className="flex flex-col gap-2 max-w-md">
+      <p className="text-caption text-fg-muted mb-2">
+        帳單頁切換付款週期 — RadioGroup 消費 SelectionItem。
+      </p>
+      <RadioGroup defaultValue="annual" className="flex flex-col gap-2">
+        <RadioGroupItem value="monthly" label="月繳" description="$12 / 月 · 可隨時取消" />
+        <RadioGroupItem value="annual" label="年繳(省 20%)" description="$115 / 年 · 相當於 $9.6 / 月" />
+        <RadioGroupItem value="lifetime" label="終身買斷" description="$299 一次付款 · 僅限 Pro plan" />
+      </RadioGroup>
+    </div>
+  ),
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 3:Prefix icon(Checkbox + icon)
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+export const WithPrefixIcon: Story = {
+  name: '前綴圖示',
+  render: () => (
+    <div className="flex flex-col gap-2 max-w-md">
+      <p className="text-caption text-fg-muted mb-2">
+        Figma-like permission scope picker — control + icon(24px 閾值內 inline)+ label + description。
+      </p>
+      <SelectionItem
+        control={<Checkbox defaultChecked />}
+        icon={Mail}
+        label="讀取 email 信箱"
+        description="僅用於通知,永遠不會外流"
+      />
+      <SelectionItem
+        control={<Checkbox />}
+        icon={Folder}
+        label="存取 Drive 檔案"
+        description="讀取並修改你授權的資料夾"
+      />
+      <SelectionItem
+        control={<Checkbox defaultChecked />}
+        icon={Bell}
+        label="推播通知權限"
+      />
+      <SelectionItem
+        control={<Checkbox />}
+        icon={Shield}
+        label="Admin 層級操作"
+        description="僅限 workspace owner 開啟"
+        disabled
+      />
+    </div>
+  ),
+}
+
+/* ═══════════════════════════════════════════════════════════════════════════
+   Story 4:Prefix avatar block(Checkbox + avatar + description)
+   ═══════════════════════════════════════════════════════════════════════════ */
+
+export const WithPrefixAvatarBlock: Story = {
+  name: '前綴頭像',
+  render: () => (
+    <div className="flex flex-col gap-2 max-w-md">
+      <p className="text-caption text-fg-muted mb-2">
+        多選 reviewer — control + avatar(32px block 模式,跟 control 一起對齊 text block center)+ name +
+        role。
+      </p>
+      <SelectionItem
+        control={<Checkbox defaultChecked />}
+        avatar={{ alt: 'Ada Chen', color: 'indigo' }}
+        label="Ada Chen"
+        description="Design Engineer · Frontend team"
+      />
+      <SelectionItem
+        control={<Checkbox />}
+        avatar={{ alt: '張美真', color: 'magenta' }}
+        label="張美真"
+        description="Product Designer · Platform team"
+      />
+      <SelectionItem
+        control={<Checkbox defaultChecked />}
+        avatar={{ alt: '林伯彥', color: 'green' }}
+        label="林伯彥"
+        description="Staff Engineer · Infra team"
+      />
+    </div>
+  ),
+}
+
+/* @story-trait-rationale: AllSizes retired per F migration 2026-05-15 — anatomy.stories.tsx SizeMatrix auto-compile owns size showcase。 */

package/src/components/SelectionControl/selection-item.tsx

@@ -1,3 +1,7 @@
+/**
+ * @internal — DS-internal 單元(per `.claude/rules/ui-development.md` Public vs Internal canonical;spec frontmatter `isInternal`)。
+ * 不進 root barrel front-door;由 Checkbox / RadioGroup wrap 消費,end-user app 請用 wrapper 元件。
+ */
 import * as React from 'react'
 import { cva, type VariantProps } from 'class-variance-authority'
 import type { LucideIcon } from 'lucide-react'
@@ -9,7 +13,7 @@ import { ICON_SIZE, AVATAR_SIZE } from '@/design-system/patterns/element-anatomy
 // Checkbox 和 RadioGroup 共用的 item 佈局。
 //
 // 結構(item-anatomy.spec.md 4-slot 模型):
-//   [control] [optional prefix(icon|avatar)] [content(label/desc)] [optional suffix]
+//   [control] [optional prefix(icon|avatar)] [content(label/desc)](3-slot,見 spec「定位」)
 //
 // padding 公式：py = (field-height - 1lh) / 2
 //   - 單行時 item 高度 = field-height（對齊同 size 的 Input）
@@ -169,6 +173,8 @@ function ContentSlot({ htmlFor, disabled, label, description, sizeKey, labelClam
     <div className="min-w-0 flex-1">
       <label
         htmlFor={htmlFor}
+        // 2026-06-10 a11y:styled-disabled label 明告 inactive(WCAG 1.4.3 豁免可機判;對齊 FieldLabel 同修;a11y 補強不動 SSOT = AUTO 分權,user verbatim「確保所有的任務你都有做到完美做到完整」)
+        aria-disabled={disabled || undefined}
         className={cn(
           'cursor-pointer block break-words',
           labelClampClass,
@@ -252,7 +258,7 @@ export const selectionItemMeta = {
     lg: {},
   },
   defaultSize: 'md',
-  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
+  states: ['default', 'disabled'], // disabled 是唯一視覺狀態;selected / hover 屬傳入的 control(spec「為何無 ColorMatrix / StateBehavior」)
   tokens: {
     fg: ['text-foreground', 'text-fg-secondary', 'text-fg-disabled'],
   },

package/src/components/Separator/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './separator'

package/src/components/Separator/separator.anatomy.stories.tsx

@@ -0,0 +1,125 @@
+// @anatomy-rationale:
+//   Inspector / ColorMatrix / SizeMatrix / StateBehavior N/A — Separator 是
+//   最薄的語意 primitive(Radix Separator passthrough),只有 orientation 與
+//   decorative 兩個 prop;1px 固定厚度、永遠走 --divider token、非互動。本檔
+//   僅保留 Overview + TokenMatrix 兩個 story 教 SSOT 分工(--divider vs
+//   --border),完整設計規則見 separator.spec.md。
+import type { Meta, StoryObj } from '@storybook/react'
+import { Separator } from './separator'
+import { H3, Desc, Td, Th } from '@/design-system/stories-helpers/anatomy/anatomy-utils'
+
+/**
+ * Separator 是最薄的語意 primitive——Radix Separator 的 shadcn passthrough。
+ * 只有 `orientation` 與 `decorative` 兩個 prop,**沒有 size / color / variant**。
+ * 色彩固定用 `--divider` token(content 分隔 canonical)。因此本 spec 只有
+ * Overview + Token Matrix 兩個 story——沒有 SizeMatrix(單一 1px)、沒有獨立
+ * ColorMatrix(永遠 divider)、沒有 StateMatrix(非互動)。完整設計規則見
+ * `separator.spec.md`。
+ */
+
+const meta: Meta = {
+  title: 'Design System/Components/Separator/設計規格',
+  parameters: { layout: 'padded' },
+}
+export default meta
+type Story = StoryObj
+
+export const Overview: Story = {
+  name: '元件總覽',
+  render: () => (
+    <div className="flex flex-col gap-10">
+      <div>
+        <H3>Anatomy</H3>
+        <Desc>Separator 是語意分隔元件——consumer 手動放置的分隔線。基於 Radix Separator(shadcn passthrough),提供正確的 ARIA 語意:預設 `decorative=true` 時 render `role="none"`(SR 跳過),`decorative={false}` 時 render `role="separator"` + orientation 語意。元件固定結構(header/footer 邊框)和裝飾性邊框**不使用 Separator**。</Desc>
+        <div className="border border-border rounded-lg p-4 max-w-md">
+          <div className="flex flex-col gap-2 py-2">
+            <div className="text-body">個人資訊</div>
+            <Separator />
+            <div className="text-body">團隊與權限</div>
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <H3>Orientation</H3>
+        <div className="flex gap-8 border border-border rounded-lg p-4">
+          <div className="flex flex-col gap-2">
+            <div className="text-body">Horizontal(預設)</div>
+            <Separator />
+            <div className="text-body">分隔水平群組</div>
+          </div>
+          <div className="flex items-center gap-4 h-20">
+            <div className="text-body">左側</div>
+            <Separator orientation="vertical" />
+            <div className="text-body">右側(vertical)</div>
+          </div>
+        </div>
+      </div>
+
+      <div>
+        <H3>Props 速查</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>Prop</Th><Th>Type</Th><Th>Default</Th><Th>說明</Th></tr></thead>
+            <tbody>
+              {[
+                ['orientation', "'horizontal' | 'vertical'", "'horizontal'", '分隔線方向'],
+                ['decorative', 'boolean', 'true', 'true=裝飾性(role="none",SR 跳過)/ false=語意分隔(role="separator")'],
+              ].map(([p, t, d, desc]) => (
+                <tr key={p}><Td mono>{p}</Td><Td mono>{t}</Td><Td mono>{d}</Td><Td>{desc}</Td></tr>
+              ))}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+export const TokenMatrix: Story = {
+  name: '設計變數 規則（--divider vs --border）',
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <div>
+        <H3>兩個不同 token 的語意分工</H3>
+        <Desc>`--divider`(neutral-4,較淡)用於內容分隔;`--border`(neutral-5,較深)用於控件 / 容器邊框。視覺接近但語意不同,**分隔線一律用 `--divider`**。</Desc>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>用途</Th><Th>Token</Th><Th>值</Th><Th>範例</Th></tr></thead>
+            <tbody>
+              <tr><Td>分隔線(content separation)</Td><Td mono>--divider</Td><Td mono>neutral-4</Td><Td>SidebarSeparator、DropdownMenuSeparator、ButtonDivider、群組分隔</Td></tr>
+              <tr><Td>控件邊框(container/control edge)</Td><Td mono>--border</Td><Td mono>neutral-5</Td><Td>Input / Checkbox 外框、Card / Dialog 容器邊線、DataTable 格線</Td></tr>
+            </tbody>
+          </table>
+        </div>
+      </div>
+
+      <div>
+        <H3>決策法:「誰決定這裡要分隔?」</H3>
+        <div className="overflow-x-auto">
+          <table className="text-caption border-collapse">
+            <thead><tr><Th>決策者</Th><Th>使用</Th><Th>理由</Th></tr></thead>
+            <tbody>
+              <tr><Td>Consumer 手動放置</Td><Td mono>&lt;Separator /&gt;</Td><Td>需要語意標記(role="separator")讓輔助技術辨識</Td></tr>
+              <tr><Td>元件自動分隔相鄰群組</Td><Td mono>CSS [&+&]</Td><Td>MenuGroup / SidebarGroup——無處插入 DOM node</Td></tr>
+              <tr><Td>元件固定結構</Td><Td mono>CSS border-t/b</Td><Td>Dialog Header/Footer、Sidebar Header/Footer——結構的一部分</Td></tr>
+              <tr><Td>控件外框 / 容器輪廓</Td><Td mono>CSS border</Td><Td>Input 外框、Card 容器——不分隔內容,是元件邊緣</Td></tr>
+            </tbody>
+          </table>
+        </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">{"Separator 非互動元件——不取得 focus、無鍵盤行為。ARIA role 視 decorative 而定(對齊 Radix Separator primitive):\n\n- 預設 decorative=true:render role=\"none\",screen reader 跳過(避免「separator」雜訊干擾 list 朗讀)\n- 語意分隔場景 decorative={false}:render role=\"separator\"(aria-orientation 僅 orientation=\"vertical\" 時輸出;horizontal 為預設方向,Radix 省略冗餘屬性),screen reader 讀出群組邊界\n\n判斷:同 list 內 item 之間的視覺隔線 = decorative(預設);跨 region 的結構分隔(sidebar group / menu group)= semantic。詳 separator.spec.md「A11y 預設」段。"}</p>
+    </div>
+  ),
+}

package/src/components/Separator/separator.principles.stories.tsx

@@ -0,0 +1,141 @@
+// @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 { Pencil, Copy, Trash2 } from 'lucide-react'
+import { Separator } from './separator'
+import { Button } from '@/design-system/components/Button/button'
+import {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+} from '@/design-system/components/DropdownMenu/dropdown-menu'
+
+const meta: Meta = {
+  title: 'Design System/Components/Separator/設計原則',
+  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>
+)
+
+// ── Stories ───────────────────────────────────────────────────────────────────
+
+// ── WhenToUse — 何時使用 Separator ──────────────────────
+
+// ── UsageGuidance — 整合何時用 / 何時不用 / vs 近親(Polaris/Material/Ant 共識)
+// 合併自舊 WhenToUse / WhenNotToUse(2026-04-26 v3 canonical)
+
+export const UsageGuidance: Story = {
+  name: '使用指引',
+  render: () => (
+    <div className="flex flex-col gap-12">
+      {/* 何時用 — 原 WhenToUse */}
+      <div className="prose prose-sm max-w-prose">
+      <p>適合 Separator 的真實業務場景(點擊跳轉「展示」頁範例):</p>
+      <ul className="space-y-1">
+        <li>
+          <LinkTo kind="Design System/Components/Separator/展示" name="水平"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">水平分隔</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Separator/展示" name="垂直"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">垂直分隔</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Separator/展示" name="在 DropdownMenu 內"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">在 DropdownMenu 內</span></LinkTo>
+        </li>
+        <li>
+          <LinkTo kind="Design System/Components/Separator/展示" name="在 DescriptionList 區塊之間"><span className="text-primary hover:text-primary-hover font-medium cursor-pointer">在 DescriptionList 區塊之間</span></LinkTo>
+        </li>
+      </ul>
+      <p className="text-fg-muted mt-3">判斷不確定時:對照 spec.md「何時用 / 何時不用」段;若仍不符,改用近親元件(見 <code>Vs*Rule</code> stories)。</p>
+    </div>
+
+      {/* 何時不用 / 替代元件 — 原 WhenNotToUse */}
+      <div>
+      <Rule
+        title="❌ 不用 Separator 元件做元件固定結構的邊框"
+        note="Dialog / Sidebar header-footer 的邊界用 CSS border，不用 Separator 元件。Separator 只用 consumer 手動放置的分隔。Notion dialog 的 header bottom 邊界是 CSS，不是 Separator"
+      >
+        <Label warn>固定結構邊界 → CSS border-divider，不用元件</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 不用 --border token 做分隔線"
+        note="分隔線一律用 --divider（較淡），--border 只用控件邊框。Jira menu 項目間的線用 --divider"
+      >
+        <Label warn>分隔線 → --divider，--border 只用容器邊框</Label>
+      </Rule>
+
+      <Rule
+        title="❌ 不用 Separator 做裝飾性邊框"
+        note="輪廓邊框（Input / Card / DataTable 邊線）用 CSS border-border，不用 Separator。Separator 有 role 語意，裝飾邊不需要"
+      >
+        <Label warn>裝飾邊框 → CSS border-border，Separator 只用分隔內容</Label>
+      </Rule>
+    </div>
+    </div>
+  ),
+}
+
+export const DecorativeSemanticRule: Story = {
+  name: '裝飾性 vs 語意分隔（讀屏的差別）',
+  render: () => (
+    <div>
+      <Rule
+        title="預設 decorative=true — 純視覺分隔,screen reader 跳過"
+        note="大多數場景(settings panel 內的區塊分組、toolbar 間隔、menu 項目分組)屬視覺性分隔。讓 screen reader 跳過,避免語意噪音"
+      >
+        <DropdownMenu>
+          <DropdownMenuTrigger asChild>
+            <Button variant="tertiary" size="sm">更多操作</Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="start">
+            <DropdownMenuItem startIcon={Pencil}>重新命名</DropdownMenuItem>
+            <DropdownMenuItem startIcon={Copy}>複製連結</DropdownMenuItem>
+            <DropdownMenuSeparator />
+            <DropdownMenuItem startIcon={Trash2}>刪除</DropdownMenuItem>
+          </DropdownMenuContent>
+        </DropdownMenu>
+        <Label>↑ DropdownMenu 的 separator 讓「編輯類」與「破壞類」視覺分組,a11y 已由 Radix 處理</Label>
+      </Rule>
+
+      <Rule
+        title="明確結構性分組(語意分隔)→ decorative={false}"
+        note={'當 Separator 真的代表內容層級的結構邊界(例如 profile page 的「個人」vs「團隊」兩個 section),設 decorative={false},讓 screen reader 讀出 role="separator"'}
+      >
+        <div className="border border-border rounded-lg p-4 max-w-md flex flex-col gap-3">
+          <div>
+            <div className="text-body font-medium">個人資訊</div>
+            <div className="text-caption text-fg-muted">姓名、email、時區</div>
+          </div>
+          <Separator decorative={false} />
+          <div>
+            <div className="text-body font-medium">團隊資訊</div>
+            <div className="text-caption text-fg-muted">所屬團隊、職稱</div>
+          </div>
+        </div>
+        <Label>↑ 兩個 section 是頁面結構的主層級 → 需要 a11y 語意</Label>
+      </Rule>
+    </div>
+  ),
+}
+