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

package/ds-canonical/skills/story-writing/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: story-writing
+description: Guide for writing Storybook stories (.stories.tsx / .principles.stories.tsx / .anatomy.stories.tsx) with world-class example quality. Enforces real-product scenarios, 「人」+「舉一反三」tests, Rule-note 原則>結論, and anatomy 6-story structure(含 A11y,2026-04-24). Invoke when user says「寫 story」「新增範例」「補 anatomy」「principles story」or is about to create/edit any `.stories.tsx` file in design-system.
+---
+
+# Story Writing
+
+Purpose: Storybook 是公開文件,範例 = 設計系統品質。本 skill 把「怎麼挑範例 / 怎麼寫 anatomy / 三方連動怎麼不漂移」集中成 invoke-time playbook,CLAUDE.md 只留最高準則 + 禁止清單。
+
+## When to run
+
+- User 說「寫 story」「新增範例」「補 anatomy」「principles story」「審 story」
+- AI 即將建立 / 編輯任一 `.stories.tsx` / `.principles.stories.tsx` / `.anatomy.stories.tsx`
+- Review 其他 contributor 的 story PR
+
+## Preconditions
+
+- 讀過 `.claude/rules/story-rules.md`(三層定位 + title 命名 + 範例最高準則)
+- 該元件的 `.spec.md` 已存在且本 session 已讀(stories 必須反映 spec,不發明新規則)
+- 若寫 anatomy:元件 `.tsx` 的 cva 定義已看過(TOKEN_MAP / SIZE_SPECS 必須與 code 一致)
+
+## Workflow
+
+### Phase 0.0 — Registry-driven baseline grep(2026-05-20 升級 per codex Layer B D4)
+
+**MUST 在 Phase 0 / 0.5 / 1+ 之前先跑**:
+
+1. **Load registry**:Read `.claude/references/story-baseline-registry.json`。檔內列每個 primitive(Sidebar / DataTable / ChromeHeader / etc.)的:
+   - `baseline`:production-grade canonical story path#StoryName
+   - `requiredHelpers`:必 import 的 helper list(WorkspaceBrand / MAIN_NAV / etc.)
+   - `antiPatterns`:regex + severity(block / warn)+ rationale
+   - `variantRules`:variant + size + prop combo canonical(eg. DataTable toolbar = text + sm + iconOnly + pressed)
+2. **Read baseline + helpers**:跑 grep + Read 取真實 production canonical 用法,Read 對應 helper source code
+3. **Produce diff table**:`primitive → baseline path → copied structure → deviations(if any with rationale)`
+4. **No registry entry?**:STOP,先 add registry entry 才能寫 story。不能憑直覺寫 simplified mock。
+5. **Marker required**:story 檔頭標 `// @story-baseline: <path>#<StoryName>` cite。
+
+### Phase 0 — Baseline grep(legacy,2026-05-20 由 Phase 0.0 registry 取代)
+
+(per M35 升 registry-driven,Phase 0 內容由 Phase 0.0 自動 cover。保留段供 legacy reference。)
+
+### Phase 0.5 — 展示層拆分原則 mapping(展示 stories 必走)
+
+對 `{name}.stories.tsx`(展示)層,寫前必走 4 步(對齊 memory `feedback_proactive_5layer_pipeline.md`「5-step pre-check」— 若寫 stories 時消費其他元件 tsx,該層也適用):
+
+1. **對 category**(see `references/category-templates.md`)— 元件屬 A-G 哪 category,suggested core stories 是什麼?
+2. **讀 spec.md** 列該元件 distinct rules(每 variant / prop / state 一條)+ 對照 category core list 補缺
+3. **產 mapping table** rule → story(對齊 Polaris / Carbon / Storybook 官方,2026-04-26 verified):
+   - 同 affordance 同 rule 的 prop variations → **1 story + Controls 切**(❌ `WithStartIcon`+`WithEndIcon` → ✓ `WithIcon` 對照 grid)
+   - 不同 affordance → 必分(`IconOnly` / `FullWidth` / `Disclosure`)
+   - AllVariants / AllSizes 對照各 1
+   - Compound 有 new constraint(prop 名變 + 必某 affordance)→ 必分(`OverlayBadgeOnIconOnly`)
+   - 真實業務情境 → 1 場景 1 故事
+4. **present mapping** 給 user sign-off(若走 skill);user 拍板才寫;反 pattern 在 step 3 即可避免
+
+Hook `check_story_slot_split.sh` write-time block 同源反 pattern。Audit `/design-system-audit` Dim 28 後驗。
+
+### Phase 1 — 定位(決定寫哪層 story)
+
+問自己:這個 story 的受眾要做什麼?
+
+| 目的 | 寫哪 | 職責 |
+|------|------|------|
+| 掃視 variant × size × state 渲染結果 | `{name}.stories.tsx`(展示) | 視覺目錄 |
+| 查 token / 尺寸 / Inspect 面板取代 Figma | `{name}.anatomy.stories.tsx`(設計規格) | 技術查閱 |
+| 學「何時用哪個 variant」的判斷 | `{name}.principles.stories.tsx`(設計原則) | 使用判斷 |
+
+混層 = 污染(principles 放 anatomy 資料 / 展示塞 do/don't)。走錯層 → 重選。
+
+### Phase 2 — 範例選擇(最高準則 + 驗收 test)
+
+**參考 `references/example-selection.md`**——完整合法來源 / 禁止清單 / 2 個 test / 正確範例對照 / Rule note 品質 / 視覺品質。
+
+核心三問:
+1. 範例來源是真實 SaaS / 常見業務(Jira / Stripe / Notion / Figma 付款 / Slack 通知)?
+2. 遮掉 title / label,5 秒看懂情境?(「人」test)
+3. 讀者能推出自己產品怎麼用?(「舉一反三」test)
+
+任一不過 → 改範例,不是補說明文字。
+
+### Phase 3 — anatomy 6-story 結構(僅 anatomy 適用)
+
+**參考 `references/anatomy-standard.md`**——每個元件 anatomy 必備 **6 件套**(`export const Overview / Inspector / ColorMatrix / SizeMatrix / StateBehavior / Accessibility`,一字不差;Accessibility 第 6 章 2026-04-24+ 對齊 Material / Polaris / Atlassian) + Inspect 面板規格 + token-first 原則 + 值溯源完整性。
+
+**偏離 canonical 規則**(CLAUDE.md 「Consistency Audit 原則」):
+- 追加第 7+ 個元件特有 story → OK,免 rationale
+- 取代 6-canonical 中某個 → **必須在元件 spec.md 寫 rationale**
+- 同概念改名(如 `VisualTokens` 取代 `ColorMatrix`) → **禁止**
+
+`/design-system-audit` Dimension 13 會強制 grep 比對偏離 + rationale 追溯。
+
+Checkpoint: 寫完後必驗:
+- TOKEN_MAP / SIZE_SPECS 每筆對得上元件 .tsx 的 cva 定義?
+- 藍圖每層 padding/margin/gap 都畫?(含子元素 `px-1`)
+- State 用開發術語(default 不是 rest)?
+- 色塊用 `var()` inline style(dark mode 自動更新)?
+
+### Phase 4 — 連動檢查(stop 點)
+
+改 `.tsx` 或 `.spec.md` 後寫 story:
+- **高風險漂移點:cva `defaultVariants`** → grep `star 預設 default` 該元件所有檔案,一次改完
+- spec 新加 rule → principles stories 必有對應 do/don't 範例
+- 元件改 variant/size → anatomy TOKEN_MAP / SIZE_SPECS 同步
+
+**STOP 條件**:若三方(code / spec / story)任一有矛盾且原因不清楚 → 停下問 user,不默默改一邊。
+
+### Phase 5 — 自我檢查 checklist
+
+**參考 `references/self-check.md`**——7 題 checklist 全部打勾才算完成:範例真實性 / 「人」test / 舉一反三 / 無極端案例 / 無代號 / Rule note 原則>結論 / 無中英夾雜。
+
+## References
+
+- `references/category-templates.md` — 7 category(A-G)suggested core stories(展示層 emergent typology)
+- `references/example-selection.md` — 完整範例選擇原則(合法來源 / 禁止清單 / 2 test / 正確範例 / Rule note / 視覺品質)
+- `references/anatomy-standard.md` — anatomy 6-story 結構 + Inspect 面板 + 品質規則
+- `references/self-check.md` — 7 題自我檢查 checklist
+
+## 相關
+
+- `.claude/rules/story-rules.md`:三層定位 + title 命名(high-level signal)
+- CLAUDE.md `# 失敗記憶索引` → 三方漂移:SegmentedControl cva defaultVariants bug
+- `.claude/hooks/check_sync_update.sh`:Edit 後自動提醒三方連動

package/ds-canonical/skills/story-writing/references/anatomy-standard.md

@@ -0,0 +1,217 @@
+# anatomy Story 標準(`{name}.anatomy.stories.tsx`)
+
+以 `Button/button.anatomy.stories.tsx` 為範本。每個元件的設計規格必須包含以下 5 個 story。
+
+## 為什麼有「設計規格」(anatomy.stories.tsx 的目的)
+
+設計規格取代 Figma inspect,是**元件的技術規格表**。滿足兩個 audience:
+
+1. **設計師 / PM 讀 spec**:詳盡解剖學(anatomy 圖標示每個 slot)、每個數值的 token 來源、每個 variant × state 的色彩組合、每個 size 的尺寸藍圖 — **檢閱方便性必須超越 Figma**,不需切工具,一頁看完
+2. **工程師讀 code**:依規格資訊能直接開發出一模一樣的 tsx,不靠設計師協助 — token name / Tailwind class / padding / gap / typography 全部在規格上,Inspect 面板即時 resolve 出 px 值
+
+因此 6-canonical / 6 件套 story(含 Accessibility 第 6 章,2026-04-24+)不是裝飾,是**兩個 audience 各自需要的資訊分層**:
+- `Overview` = anatomy 圖 + variant 一覽 + props 速查(「這元件長什麼樣」)
+- `Inspector` = 即時預覽 + inspect 面板(「各 prop 切換時 token 怎麼變」,超越 Figma 的互動檢閱)
+- `ColorMatrix` = variant × state 色彩矩陣(「每格色彩 token 是哪個」)
+- `SizeMatrix` = size × variant 尺寸藍圖(「每格尺寸 token 是哪個」)
+- `StateBehavior` = 互動狀態前後對照(「hover / active / disabled 怎麼變」)
+
+任一分層缺口 = 規格不完整 = Figma inspect 的替代目標沒達到。這就是為什麼 6-canonical(含 Accessibility)不是 N 個 random story,而是「足以 100% 還原元件 + 對齊世界級 a11y 章程」的最小必要切片。
+
+## Canonical `export const` 名稱 + 中文顯示名(6 件套)
+
+每個 `.anatomy.stories.tsx` 的 `export const` 識別名稱必須用英文、中文 story 顯示名必須**強制 `name:` 覆寫**,且兩者**一字不差對齊**以下 canonical:
+
+| 順序 | `export const` | 中文 story `name`(強制覆寫,**不加序號**) |
+|------|--------------|---------------------|
+| 1 | `Overview` | `'元件總覽'` |
+| 2 | `Inspector` | `'元件檢閱器'` |
+| 3 | `ColorMatrix` | `'色彩對照表'` |
+| 4 | `SizeMatrix` | `'尺寸對照表'` |
+| 5 | `StateBehavior` | `'狀態行為'` |
+| 6 | `Accessibility` | `'無障礙與鍵盤'`(互動元件強制,純視覺 indicator N/A)|
+| 7+ | 元件特有 | 中文命名,見下方擴充規則 |
+
+```ts
+export const Overview = {
+  name: '元件總覽',  // ← 強制覆寫,不可省
+  render: () => (...),
+} satisfies Story
+```
+
+### 為什麼強制 `name:` 覆寫(不加序號)
+
+- **強制中文覆寫**:不覆寫時 Storybook sidebar 顯示英文 identifier(`Overview`),中英混雜破壞中文 spec 一致性
+- **不加序號**(2026-04-26 起 user 反饋):序號無價值且容易跳號(N/A skip 後 1 2 3 5 視覺破碎)。Sidebar 排序由 `export` 順序決定(Storybook 預設 `storySort: 'function'` 已對應 export 順序;若依字母排,本系統元件數有限,人工順序可接受)
+- **世界級對照**:Polaris(Anatomy / Variants / States)/ Material(Anatomy / Guidelines)/ Atlassian(Examples / Code) 的 Storybook 皆為每個 story 明確標題,**無一使用序號前綴**
+
+### Canonical 是**預設 6 section 都要建**(含 Accessibility),N/A 是嚴格例外
+
+**6-canonical section = 每個 Components/(public)元件預設都該有**(Accessibility 第 6 章 2026-04-24+ 加入,對齊 Material / Polaris / Atlassian)。N/A 不是「省工豁免」,是嚴格例外 — 必須是「建了毫無意義 / 反而有害」才算 N/A。下方判斷標準**從嚴**。
+
+**判斷預設 applicable**(採 Polaris / Material / Atlassian 世界級 baseline):
+- **Inspector**:**幾乎所有 public 元件都 applicable**。只要元件有 ≥ 2 props,就該有 Inspector 讓 designer 切 props 看 render + token 對照。拒絕 Inspector 的唯一理由 = 元件 props < 2(極罕見,例 Separator / Skeleton 無互動 prop)
+- **ColorMatrix**:applicable 如元件有 variant / hue / severity / theme。N/A 僅當元件色彩完全繼承 context(例 HoverCard 繼承 page theme 無自己 palette)
+- **SizeMatrix**:applicable 如元件有 size prop(sm/md/lg)。固定尺寸才 N/A(Notice / Chip / Avatar 的特定固定場合)
+- **StateBehavior**:applicable 如元件有任何互動 state(hover / selected / disabled / loading / error / focus)。純靜態 indicator(Badge / Tag)才 N/A
+- **Accessibility**(2026-04-24 加,對齊 Material / Polaris / Atlassian 專章):applicable 如元件有任何鍵盤互動 / ARIA / focus 管理。內含:ARIA props 對照表 / Keyboard map(Tab/Enter/Esc/arrow)/ Focus order 圖 / WCAG AA 對比 snapshot。純視覺 indicator(Badge / Tag / Separator)才 N/A。**Migration strategy**:existing 元件**不 retroactively backfill**;新元件 / 重大修改時建;`/design-system-audit` 稽核發現缺 → flag + 補
+
+**嚴格警告**:曾經被誤用「applicable-where-meaningful」放行大量元件跳 Inspector,造成 anatomy 紙本文件不如世界級。**2026-04-21 audit 重修:policy 改回「6-canonical 預設全建(含 Accessibility),N/A 要硬 rationale」**。N/A 不是省工通行證。
+
+### 允許的偏離(CLAUDE.md「Consistency Audit 原則」公式)
+
+#### `@anatomy-rationale:` 檔頭註解(scope-N/A 的 canonical escape)
+
+當某 section(Inspector / ColorMatrix / SizeMatrix / StateBehavior / Accessibility)是**設計上 N/A**(非「未做完」),於 `*.anatomy.stories.tsx` 檔頭以**多行註解**列出 N/A 段 + 一行原因:
+
+```ts
+// @anatomy-rationale:
+// SizeMatrix N/A — Skeleton 為純結構 placeholder,寬高由 consumer 控制,無 size tier
+// StateBehavior N/A — Skeleton 無互動 state(僅 loading 一態,Overview 已示範)
+import type { Meta, StoryObj } from '@storybook/react'
+// ...
+```
+
+**何時用**:section 是**設計範圍外**的 N/A — 例:Skeleton 無互動 state / Separator 為結構元件 / 無參數的 layout primitive。
+**何時不用**:section 只是還沒填完 — 補完內容,不要拿 escape 規避。
+**世界級對照**:對齊 ESLint `eslint-disable-next-line {rule}` 的 per-line allowlist idiom — 每個豁免必有具名 rule + 一行 rationale,不允許整檔默默繞過。
+
+`check_story_anatomy.sh` 識別 `@anatomy-rationale:` block:列出的 section 視為 legitimately N/A;未列出的 missing section 仍 violation。
+
+#### 其他允許的偏離
+
+1. **追加第 6+ 個元件特有 story**:OK,不需 rationale。命名遵循以下格式:
+   - `export const` 用 PascalCase 英文(如 `StandardRatios` / `LayoutMatrix` / `ColorBindingRule`)
+   - 中文 `name:` 必須用編號前綴 + 中文描述:`'6. 標準比例'` / `'6. 佈局矩陣'` / `'6. 色彩綁定規則'`
+   - ❌ 不准用素顏型 `'色彩綁定規則'`(破壞編號連續性)
+   - ❌ 不准帶括號 context `'6. Orientation(horizontal / vertical)'` — 括號寫在 story 標題本體,不影響 sidebar 文字
+2. **缺 6-canonical 某一項(N/A)**:**必須在元件 spec.md 寫一段 rationale**,格式:「本元件無 `{SectionName}` story,因為 {原因}」。典型原因:
+   - Badge / Tag:純視覺 indicator,無互動狀態 → 不需 StateBehavior
+   - Chart:色彩來自 ChartConfig 不來自元件 variant → 不需 ColorMatrix
+   - Separator / Skeleton / CircularProgress / Avatar:無 size tier(自由 number)→ 不需 SizeMatrix(或 SizeMatrix 改為「範圍展示」)
+   - Notice / Alert:固定單一 size(Material Banner / Polaris Banner 共識) → 不需 SizeMatrix
+3. **保留 canonical 編號**:若有 Overview(1) + ColorMatrix(3) + StateBehavior(5),**編號保持 3 和 5**,不重編為 2 和 3 — 這讓讀者在 sidebar 一眼看出「這個元件跳過了 2 和 4」而非誤以為 canonical 就只有 3 個 section(6-canonical 模型同理)
+4. **同概念改名**:不允許(如 `VisualTokens` 取代 `ColorMatrix` / `StyleMatrix` 取代 `ColorMatrix`)一律改回 canonical
+
+**`/design-system-audit` Dimension 13 強制 grep 比對**:
+- `export const` 名稱 ≠ canonical → violation
+- 無 `name:` 覆寫(依賴 identifier) → violation
+- `name:` 值 ≠ canonical 中文(含編號前綴) → violation
+- 缺 6-canonical 某項且 spec.md 無 rationale → violation
+
+## 元件總覽(Overview)
+
+- Anatomy 圖——標示所有 slot(標準版面 + iconOnly 等變體版面)
+- Variant 一覽——每個 variant 一行:渲染元件 + 一句話角色描述
+- Props 速查表——prop / type / default / 說明
+
+## 元件檢閱器(Inspector,取代 Figma inspect)
+
+- 控制項:variant / danger / state / size / iconOnly(依元件調整)
+- 左側:即時預覽 + 尺寸藍圖
+- 右側:Inspect 面板,分區顯示 Color / Layout / Typography / Style
+- **State 使用開發術語**:default / hover / active / disabled(不用 rest)
+
+## 色彩對照表(ColorMatrix)
+
+- Variant × State 矩陣
+- 每格:渲染元件 + bg / text / border token 標註(含即時色塊)
+- 標準 variant 與 danger variant 分開
+
+## 尺寸對照表(SizeMatrix)
+
+- Size token 對照表(每個 size 的所有 token 一覽)
+- 含 iconOnly 等變體模式的覆寫說明
+- 視覺預覽矩陣(Variant × Size,含變體模式)
+
+## 狀態行為(StateBehavior)
+
+- 每個互動狀態的前後對照(如 loading spinner 替換規則)
+- 所有 variant 的 disabled 渲染(含變體模式)
+- 元件特有狀態(如 checked toggle)
+
+## 無障礙與鍵盤(Accessibility,2026-04-24 新增,對齊 Material / Polaris / Atlassian 專章)
+
+**對齊世界級**:Material 3 / Polaris / Atlassian DSP 三家元件文件皆有 A11y + Keyboard 專章。散在 StateBehavior(focus/disabled)+ principles(do/don't)不夠突出,designer / audit 找 a11y 資訊需要翻多檔。
+
+**包含**(applicable 時必有):
+- **ARIA props 對照表**:每 prop 對應的 aria-* mapping(e.g. `disabled` → `aria-disabled` / `required` → `aria-required`)
+- **Keyboard map**:Tab / Shift+Tab / Enter / Space / Esc / Arrow keys(↑↓←→) 各做什麼
+- **Focus order 圖**:複合元件(DatePicker / Combobox / DropdownMenu)的 focus 進入 → 內部 navigation → 退出流程
+- **WCAG AA 對比 snapshot**:主要 state(default / hover / focus / disabled)對比度通過 visual-audit Layer A
+
+**N/A 條件**:純視覺 indicator(Badge / Tag / Separator / Skeleton / Avatar 非 interactive 時)— rationale 寫 spec「本元件無互動」。
+
+**Migration**:
+- 新元件 / 元件重大修改時**強制**建
+- **既有元件不 retroactively backfill**(尊重 user 2026-04-24 指示)
+- `/design-system-audit` Dim 10(a11y 覆蓋)擴充:發現 interactive 元件缺 Accessibility story → flag
+- 新元件 checklist 加 `Accessibility story 建立`
+
+## 三層 stories 互聯 cross-link(2026-04-24 新增)
+
+每個 story 頂部 meta 或底部 Rule note 必含統一 **「See also」** 區塊,讓讀者從任一層入口跳到其他角度:
+
+```markdown
+See also:
+- 展示({name}.stories.tsx) — 真實業務場景
+- 設計規格({name}.anatomy.stories.tsx) — 6-matrix inspect
+- 設計原則({name}.principles.stories.tsx) — do/don't + 情境選擇
+```
+
+**為什麼需要**:展示 / 設計規格 / 設計原則 3 層職責不重複但視角不同(「看 → 查 → 判斷」)。沒有 cross-link 讀者容易 stuck 在一層,漏看其他角度的 canonical。
+
+**實作**:`compile-stories.mjs` 自動在每個 story 的 docs meta 注入此 section;consumer 不手寫。
+
+## Story earn-existence philosophy(2026-04-24 新增 — audit Dim 24/25 對應)
+
+每個 manual story(非 auto-compiled 的部分)必 earn its existence。理由:多餘 story = noise,增加維護成本 + drift 風險 + 讀者(人 + AI)認知負擔。
+
+**核心 philosophy**:
+1. **以「可舉一反三」為主** — 一個 story 教一條原則,讀者能類推到其他情境
+2. **Manual 補充模糊原則,讓抽象具象化** — spec 有模糊 rule 時,manual story 用具體 Jira/Stripe/Notion 劇情把原則釘下來。給「人」看得懂為主
+3. **禁止湊數 / 重複 / 秀肌肉**
+
+**每 manual story 必過 2 earn test**:
+- (a) **unique teaching** — 這個 story 教一條其他 story 沒教的原則?
+- (b) **grounding necessity** — 移除後,spec 某條抽象原則會 degrade 為難懂?
+
+兩題皆 NO → retire 候選(audit Dim 24/25 會抓)。兩題任一 YES → 合法保留。
+
+**範例(illustrative)**:
+- ✅ OK:`DialogWithForm` — 教 Dialog 內 form field-wrapper canonical(grounds 抽象「form gap」rule)
+- ❌ redundant:`DialogWithFormAndCancelButton` — 跟 `DialogWithForm` 只差 cancel button,不新教任何原則
+- ❌ showing-off:`DialogHugeSize1000px` — 極端 size 不教原則,只秀技術
+
+## 設計規格品質規則
+
+- **Token-first**:所有數值以 token name 為主(如 `h-field-sm`),resolved px 值為輔助灰字。開發者只需確認 token 正確——theme / density 的值解析由系統處理
+- **不含 density 雙值**:不顯示 `28px (md) / 32px (lg)`,只顯示 token name + 當前 resolved 值
+- **Dev 語言**:使用開發術語(default 不是 rest,用 Tailwind utility name 如 `px-3` `gap-1`)
+- **藍圖完整性**:render 函式中**每一層**的 padding / margin / gap 都必須在藍圖中呈現——包括子元素的間距(如 label span 的 `px-1`),不可遺漏
+- **範例驗證**:每個範例必須用 spec.md 的所有規則逐條驗證(如 badge 不應出現在 loading / disabled 狀態)
+- **色塊即時渲染**:使用 `var()` 內聯樣式,確保切換 dark mode / density 時自動更新
+- **資料正確性**:TOKEN_MAP / SIZE_SPECS 等資料必須與元件 `.tsx` 的 `cva()` 定義交叉比對,確認完全一致
+- **值溯源完整性**:設計規格中出現的每個行為描述,必須追到 code 中的具體值。不可只描述行為模式而省略數值——包括 Provider 層級設定(如 `delayDuration`)、全域設定檔(`main.tsx`、`preview.tsx`)、CSS 變數定義檔。規則:**如果 code 裡有具體數字,設計規格就必須標出來**
+
+## 連動更新規則
+
+三份文件互為依賴,任一變動必須同步更新其他兩份:
+
+| 異動來源 | 必須連動更新 |
+|---------|-------------|
+| **`.tsx` 元件程式碼**(variant / size / token / 內部結構) | → 設計規格(TOKEN_MAP、SIZE_SPECS、藍圖、Inspect 面板)<br>→ 展示(如有對應的 story) |
+| **`.spec.md` 設計原則**(新增 / 修改 / 刪除規則) | → 設計原則 stories(do/don't 範例必須反映最新 spec)<br>→ 設計規格(範例驗證:確認規格中的範例不違反新規則) |
+| **設計規格 story**(結構調整、新增對照維度) | → 展示(確保展示仍是規格的便利瀏覽版,不脫節) |
+
+## 高風險漂移點:`cva()` defaultVariants
+
+**`defaultVariants` 是三方(code / spec / story)最容易漂移的位置,改之前必須意識到四方聯動:**
+
+| 改什麼 | 必須同步 |
+|--------|---------|
+| `cva()` 裡的 `defaultVariants.size`(或 variant / state) | 1. 元件 `.spec.md` 的 prop 表 / 預設標記<br>2. 元件 `.tsx` 頂端 docblock 的 `★ 預設` 標記<br>3. `{name}.anatomy.stories.tsx` 的 SIZE_SPECS 表 / default marker<br>4. 若屬 field-height family → `tokens/uiSize/uiSize.spec.md` 的 family 清單 |
+
+**曾發生的 bug**:SegmentedControl 的 cva `defaultVariants.size` 是 `md`,spec.md + docblock + anatomy 都寫 `sm ★default`——三方不一致持續存在到 audit 才發現(2026-04-18 修正)。
+
+**預防法**:改 `defaultVariants` 前,grep 該元件所有檔案(`grep "★\|預設\|default" packages/design-system/src/components/{Name}/`),一次改完所有出現位置,不單改 code 就收工。

package/ds-canonical/skills/story-writing/references/category-templates.md

@@ -0,0 +1,174 @@
+# 展示 Story Trait-Based Typology v2(2026-04-26)
+
+世界級 DS(Polaris / Material / Atlassian / Ant / Carbon / Storybook 官方)的 Storybook story 結構**不是** category-based prescription(「button-likes 必有 5 stories」),是**trait-based**——元件依自身能力宣告 traits,required stories 由 trait 衍生。本 doc 是本 DS canonical typology v2,取代 v1 7-category。
+
+對應 `.claude/rules/story-rules.md`「拆分原則」+ M8 world-class benchmark。
+
+## 為什麼 v2 trait-based(取代 v1 category-based)
+
+v1 7 categories(A 視覺 variant / B field control / C selection / D structural / E scenario / F media / G internal)在實踐中暴露 4 盲點:
+1. **Over-engineered**:A 要求 ≥5 stories 比 Carbon 整 component 還多
+2. **Switch 一刀切**:C 要求 group stories,但 Material/Polaris/Carbon 的 Switch 全是 standalone(對齊 single-toggle idiom)
+3. **Scope-N/A 沒寫**:Toast 沒 size 軸,A 卻硬要 AllSizes
+4. **G 不該定 required stories**:Internal 是 DS visibility governance,不是 story shape
+
+**M8 benchmark 證據**(2026-04-26 raw source 掃 5 系統):
+- **Carbon Button**:10 stories,disabled/sizes 走 args(Controls)
+- **Polaris Button**:24 stories(variant × tone matrix,但 sizes 散在 per-variant)
+- **MUI Button**:18 example files,trait-driven(BasicButtons / OutlinedButtons / IconLabelButtons / LoadingButtons)
+- **Ant Button**:22 demos,one demo = one focused trait
+- **Storybook 官方**:推薦 Default first + CSF3 args,**不 prescribe count or required set**
+- **共識**:`Default` 必有 / `WithIcon` merged grid 不拆 / overlay default-open `useState(true)` / Disabled 多數有但非絕對 / scenarios 多寡看 component 性質
+
+→ trait-based 對齊 5/5 benchmark systems(M8 ≥ 3 ✓ overshot)。
+
+## Trait-based core canonical
+
+### Universal(每元件必有)
+
+- **Default** — 最 minimal 代表性範例(對齊 Storybook 官方 + Carbon idiom)
+
+### Conditional traits → required stories
+
+元件在 **spec.md frontmatter** 的 `traits: [...]` 宣告,`scripts/compile-stories.mjs` + hook 會驗證 required stories 齊全:
+
+| Trait | 何時宣告 | Required stories(traits 觸發後必有) |
+|-------|---------|----------------------------------|
+| `hasVariants` | ≥ 2 visual variants(primary/secondary/danger 等) | `AllVariants` 對照 grid,**或** ≥ 2 個 per-variant exports |
+| `hasSizes` | ≥ 2 sizes(sm/md/lg 等) | `AllSizes` merged grid(❌ 禁止 per-size 拆 `Small`+`Medium`+`Large`) |
+| `hasInteractiveStates` | hover / focus / disabled / loading 任一可見 | `Disabled` own story(`Loading` 視 prop / `Error` 視 validation 而定) |
+| `isOverlay` | Dialog / Sheet / Popover / Tooltip / Drawer 類 portal-rendered | `OpenSnapshot` story(`defaultOpen` / `useState(true)` 對齊 M15)+ ≥ 3 業務 scenarios |
+| `isInputLike` | text / number / search / textarea field | `WithError` + `WithHelpText` + `WithIcon` merged grid |
+| `isSelectionMulti` | Checkbox / Radio / 多選 toggle | `States`(checked/unchecked/indeterminate/disabled)+ `VerticalGroup` + `Disabled`(group level) |
+| `isSelectionSingle` | Switch / 單一 toggle(無群組概念) | `States` only(對齊 Material/Polaris/Carbon Switch idiom — 無 group story) |
+| `isMatrixHeavy` | Avatar / Skeleton / Spinner / Badge / Slider 等 token × size 正交視覺軸 | ≥ 4 matrix stories(`Modes` / `Shapes` / `Colors` / `AllSizes` 任 4) |
+| `isStructural` | DataTable / Steps / Tabs / Accordion 結構主導 | 每結構變體 1 story(無固定數,過 earn-existence) |
+| `isInternal` | L3 building block(被其他元件消費) | 1 `Default` + ≤ 1 composition scenario(寬鬆,Internal/ 命名空間下) |
+
+### Optional universal
+
+- 1+ `RealScenario` story(Jira / Stripe / Notion / Figma / Slack / Gmail 真實業務情境),**過 earn-existence 2 test 才開**:
+  - Q1:教別 story 沒教的原則?
+  - Q2:移除後 spec 理解 degrade?
+  - 兩題皆 NO → retire 候選
+
+## Typical story counts(對齊 Carbon / Polaris median)
+
+| 元件類型 | Stories range | 對照 |
+|---------|---------------|------|
+| L1 minimal(Switch / Skeleton)| 1-3 | Carbon Checkbox 5 |
+| L1 standard(Button / Input)| 4-8 | Carbon Button 10 |
+| Overlay(Dialog / Sheet)| 6-12 | Polaris Modal 16 / Ant Modal 17 |
+| Matrix-heavy(Avatar)| 4-6 | Polaris Avatar 5 |
+| Structural(DataTable)| 8-12 | (本 DS 11) |
+| Internal primitive | 1-2 | Carbon hidden _PrefixedExport |
+
+## Scope-N/A 例外子句
+
+某 trait 在 spec.md「邊界案例 scope」明示 N/A → 該 trait required stories 跳過,不違反 typology:
+
+- **Toast**:`hasSizes=false`(ephemeral notification 單尺寸)→ AllSizes 跳過
+- **Coachmark**:`hasInteractiveStates=false`(無 disabled / loading 概念)→ Disabled 跳過
+- **Skeleton**:`hasVariants=false`(只 default skeleton 形狀)→ AllVariants 跳過
+
+**規則**:跳過 trait 時 spec.md 必明文 rationale(例「Toast 是 ephemeral notification,單尺寸對齊 Sonner / Polaris Toast idiom,無 size 軸」)。**禁止**默默 skip。
+
+## How to use(寫 / audit story 時)
+
+1. 該元件宣告哪些 traits?(讀 spec.md frontmatter `traits:` array)
+2. 對照本 doc traits → required stories list
+3. 缺哪個 → 補(若 spec.md 該 trait 真有效)
+4. 多哪個 → 過 earn-existence 2 test;不過 → retire
+5. **scope-N/A 例外**:該 trait 在 spec.md 明示 N/A → 跳過 OK,但 spec.md 必有 rationale
+
+## 邊界 case
+
+- **多 trait 元件**(e.g. Button = `hasVariants` + `hasSizes` + `hasInteractiveStates`)→ 各 trait required 都有
+- **Family 跨界**(Field control 同時 isInputLike + hasInteractiveStates)→ Union of all traits
+- **新 trait 提議**:跑 M8(≥ 3 家 DS benchmark)+ Checkpoint user sign-off,不孤立發明
+
+## Typology 演進規則(對齊 user mandate「除非調整標準」)
+
+本 typology 是 canonical SSOT。**禁止**單元件偏離不記 rationale。Typology 本身可演進,但流程:
+
+1. 提案 invoke `/ensure-canonical` skill(M19 trigger)
+2. 跑 M8 benchmark(≥ 3 家 DS)
+3. Checkpoint sign-off
+4. 落地 5-layer pipeline(typology + hook + audit + scaffold + memory)
+
+## Cross-link
+
+- `.claude/rules/story-rules.md`「拆分原則」— canonical 上游 one-liner
+- `/story-writing` SKILL.md Phase 0 — write-time mapping
+- Hook `check_story_category.sh` — pre-write enforcement(攔不符 trait core)
+- `/design-system-audit` Dim 29 — periodic verify
+- `/new-component` Phase 5 — 新元件 trait-based scaffold
+- `scripts/compile-stories.mjs` — runtime trait → required stories check
+
+# Principles canonical(設計原則層,2026-04-26 加)
+
+第三層 stories `{name}.principles.stories.tsx` 的 canonical structure。對齊 M8 benchmark(Polaris / Carbon / Ant 3 家 verifiable):
+
+## 世界級對照
+
+3 種哲學:
+- **Carbon**(超嚴謹):~10 H2(`Overview / Formatting / Content / Universal behaviors / Modifiers / Related`)
+- **Polaris**(中等):4 H2(`Best practices / Content guidelines / Related components / Accessibility`)
+- **Ant**(極薄):1 H2(`When To Use`)
+
+採 **Polaris-aligned 中等**(避免 Carbon-style 過細 + Ant-style 過薄)+ 接受既有 project naming(`VsXRule` 對齊 Carbon「X versus Y」)。
+
+## Universal core(每元件 ≥ 1)— 2026-04-26 v3 整合
+
+**重要**:WhenToUse + WhenNotToUse + VsXRule 都教「何時用 X」decision tree,**過度切割造成 noise**。對齊 Polaris/Material/Ant 共識(ONE integrated section),預設整合成單一 story。
+
+| Story name(canonical)| 教什麼 | 世界級 anchor |
+|---------------------|--------|---------------|
+| **`UsageGuidance`**(預設,整合)| **何時用 + 何時不用 + 替代元件 / sibling comparison** 統一 decision tree | Polaris `Best practices` / Material `Usage` / Ant `When To Use`(共識) |
+| `Vs{Sibling}Rule` | 視覺 deep-dive 對照(若需要 visual matrix 比較,deep-dive 才用)| Carbon `X versus Y` H3 |
+| `ContentGuidelines` | 文案 do/don't(若元件 render 使用者文案)| Polaris `Content guidelines` H2 |
+
+**判斷整合 vs split**:
+- 對 80% 元件:**ONE `UsageGuidance`** 涵蓋 何時用 / 何時不用 / sibling 已足夠 — 對齊 Polaris/Material/Ant
+- 對 20% 元件(超複雜 sibling matrix,如 Toast vs Alert vs Dialog):integrate 後加 `VsXRule` deep-dive(視覺 do/don't 對照,文字無法表達)
+- `ContentGuidelines` 永遠獨立(文案 vs 元件選擇 是不同主題)
+
+**Legacy aliases 接受**(不強制 rename 既存 stories):
+- `WhenToUse` / `WhenNotToUse` / `Vs*Rule` 任 1 已存在 = 算「has core」
+- 新元件用 `UsageGuidance` 整合單一 story
+
+**規則**:每元件 principles 至少 **2 個 stories**(任意 combo:canonical 4 + component-specific `*Rule` + 描述性名稱如 `BlueConnectorLogic` / `ParentControlled` 都算 valid)。**全 4 個必有** = over-engineer(Polaris 4/4,但 Carbon Ant 都不到);**少於 2 stories** = principles 太薄無教學價值。Audit `audit-content-quality.mjs` 採寬鬆 ≥ 2 exports 標準(承認既有 component-specific naming idiom)。
+
+## Canonical naming(取代既有 drift 變體)
+
+| 既有 drift 命名 | Canonical | Rationale |
+|---------------|-----------|-----------|
+| `Forbidden*` / `Donts` / `Pitfalls` / `Prohibitions` / `NonGoals` / `VisualDonts` | **`WhenNotToUse`** | Polaris/Carbon 共識用「When NOT to use」semantics |
+| `UsageScenarioRule` / `WhatItIs` / `MvpScope` | **`WhenToUse`** | 對齊 Polaris/Carbon/Ant 三家 |
+| `Vs{X}Rule`(`VsTabsRule` / `VsCheckboxRule` 等) | **保留**(對齊 Carbon `versus` idiom)| 已是世界級 |
+| `{Topic}Rule`(其他 component-specific) | **保留**(過 earn-existence 即可)| 可選 component-specific 規則 |
+
+## 可選 stories(過 earn-existence)
+
+- `VariantDecision` — 元件 ≥ 3 variants 各自 semantic 不同(Button / Banner / Notification)時可加
+- `CompositionRules` — 元件可 non-trivial 組合(Field family / ActionBar)時可加
+- `AccessibilityNotes` — 非 mechanical a11y(mechanical 留 anatomy)
+- 其他 component-specific `XRule` — 過 earn-existence 2-test
+
+## 跟 anatomy / showcase 分權
+
+| 該放 principles | 該放 anatomy | 該放 showcase |
+|-----------------|--------------|---------------|
+| Do/don't 視覺對照 | Token / size matrix | 真實場景 + variant grid |
+| 跟近親元件比較 | Inspector 數值 | AllVariants / AllSizes |
+| 何時用 / 不該用 | StateBehavior 視覺 | Disabled / Loading state demo |
+| 文案 / 內容 guidelines | ColorMatrix | 業務 scenario 範例 |
+
+**禁止**:do/don't 對照放 showcase(屬 principles)/ token table 放 showcase(屬 anatomy)/ 純 variant grid 無 rule 放 principles(屬 showcase)。
+
+## 強制機制
+
+- **Hook** `check_principles_canonical.sh`:PreToolUse 攔不符 ≥ 2 universal core
+- **Audit Dim 30**:periodic verify
+- **`/new-component` Phase 5.3**:scaffold 4 universal stories template
+

package/ds-canonical/skills/story-writing/references/example-selection.md

@@ -0,0 +1,70 @@
+# 範例選擇原則(完整)
+
+每次新增、修改、或審查 story 範例時的第一準則——適用 `.stories.tsx` / `.principles.stories.tsx` / `.anatomy.stories.tsx` 的所有範例情境。
+
+## 最高準則:用耳熟能詳的真實業務場景,禁止極端 / 虛構 / 佔位案例
+
+Storybook 是**公開文件**,受眾是任何打開的設計師 / 開發者 / PM。範例的核心功能是**教學**,不是展示元件能跑——不是跑得起來就算,而是要讓讀者從範例**推得出自己產品該怎麼用**。
+
+## 合法場景來源(按優先序)
+
+1. **對標世界級 SaaS 的真實功能**:Jira task status、Linear priority、Slack DM notification、Notion settings toggle、Figma toolbar、GitHub PR review、Stripe 付款、Airtable filter、Google Docs 權限設定
+2. **台灣 / 全球常見業務流程**:電商結帳(信用卡 / 轉帳 / 貨到付款)、訂閱方案(月付 / 年付 / 企業)、文件協作(編輯 / 評論 / 唯讀)、表單提交(送出 / 儲存草稿 / 放棄變更)
+3. **該元件原生生態的慣用場景**:Segmented 的「全部 / 進行中 / 已完成」、Tabs 的「總覽 / 活動 / 成員 / 設定」、RadioGroup 的付款方式、Checkbox 的同意條款
+
+## 明確禁止
+
+| 禁止類型 | 範例 | 為什麼 |
+|---------|------|-------|
+| **佔位符** | `Option A / B / C`、`Lorem ipsum`、`foo / bar`、`Test value` | 無情境,讀者學不到任何東西 |
+| **抽象代號** | `按鈕一 / 按鈕二`、`Variant X`、`Rule A / B` | 不是產品語言,破壞「受眾是設計師」的前提 |
+| **極端不現實案例** | 單 button「刪除全部使用者資料包含備份無法復原」、filter 有 50 個項目、dialog 嵌套 5 層 | 非日常使用情境,失去教學價值 |
+| **視覺符號表達式** | `│─ 業務 ─│`、`A → B → C`、ASCII art | 不是產品 UI,污染 Storybook 視覺 |
+| **spec 內部代號** | 「符合 Rule 3.2」「遵循 Convention A」 | 讀者沒讀 spec 也要看得懂 |
+
+## 兩個驗收 test(寫完 / 審時自問)
+
+### Test 1 — 「人」test
+新加入的設計師打開 Storybook,**遮住所有 title / label / note**,只看元件裡的文字和情境,能不能 5 秒內說出「喔這是在做 X 流程」?
+- 能 → 場景有教學力
+- 不能 → 改成具體業務場景,不是補說明文字
+
+### Test 2 — 「舉一反三」test
+讀者看完這 3-5 個範例,**推得出自己專案類似情境該怎麼用嗎**?
+- 能 → 範例涵蓋了決策維度(如 RadioGroup 的付款方式 + 訂閱方案 + 權限角色 = 教會讀者「決策節點類」的三個面向)
+- 不能 → 範例之間同質、缺維度——增加互補場景而非重複
+
+**黃金比例**:5 個具代表性的真實場景 > 20 個重複 placeholder。
+
+## 正確範例(✅)對照
+
+- **Button**:「送出表單 / 儲存草稿 / 放棄變更」(表單流程三按鈕)、「刪除專案」(destructive confirm)
+- **Badge**:「3 個新通知」、「未讀訊息 12」、「必填」、「Beta」
+- **SegmentedControl**:「總覽 / 活動 / 成員 / 設定」(workspace tab)、「日 / 週 / 月」(時間範圍)
+- **RadioGroup**:「信用卡 / 銀行轉帳 / 超商付款」(付款方式)、「月付 / 年付(省 20%)/ 企業」(訂閱)
+- **Switch**:「Bluetooth 開 / 關」、「Email 通知」、「Dark mode」
+- **Checkbox**:「我同意服務條款」、「寄送促銷 email」(訂閱偏好)
+
+## 適用範圍
+
+| Story 類型 | 適用性 | 備註 |
+|-----------|-------|------|
+| `.principles.stories.tsx` | **最嚴格** | 教學性高,範例品質 = 設計系統品質 |
+| `.stories.tsx`(展示) | 嚴格 | 範例代表元件「日常應該長這樣」,不是 test case |
+| `.anatomy.stories.tsx` | 彈性 | token 藍圖 / inspect 面板可用合成內容,但**元件渲染範例仍須真實場景** |
+| `explorations/` | 寬鬆 | 比稿可用抽象內容,但定案後轉入正式系統前須替換 |
+
+## Rule note 品質
+
+**Rule note 必須傳達原則而非結論**,讓讀者能舉一反三——寫「為什麼」而不只是「是什麼」。例如:
+- ❌「禁止 primary」 → ✅「工具層必須是視覺重量最低的一層,否則搶走業務焦點」
+- ❌「全程 icon-only」 → ✅「這些 icon 在此脈絡下約定俗成,使用者不需 label 就能辨識」
+
+## 視覺與文案品質
+
+- **Toolbar 範例**統一使用 `ToolbarFrame`(滿版 + 短標題),不用裸 `ButtonGroup` 漂在半空
+- `ToolbarFrame` 標題模擬真實產品(2–4 字如「文件」「專案」),說明放在下方 `Label`,不塞進標題導致文字與按鈕碰撞
+- 同一個 story 內的範例容器必須一致,不混用不同寬度
+- ❌/✅ 判斷放在 `Label`,不放在 ToolbarFrame 標題內
+- **排版層級清晰**:主標用 `h3`(深色、正常大小),副標用 `text-caption`(灰色、限寬 720px),Label 用 `text-footnote`(最小字、範例解說)。三層視覺上必須有明顯區隔
+- **icon-only 按鈕有 `aria-label`**;互動範例可用鍵盤操作

package/ds-canonical/skills/story-writing/references/self-check.md

@@ -0,0 +1,20 @@
+# Story 自我檢查清單
+
+寫完 / 審時逐條打勾:
+
+- [ ] 所有範例文字是真實產品可能出現的句子(不是 Option A/B/C、不是「按鈕一」)
+- [ ] 每個範例可追溯到世界級 SaaS 或常見業務場景(能說出「這參考 Jira / Stripe / Notion 哪個功能」)
+- [ ] 沒有極端不現實案例(50 個 filter、5 層 dialog、單 button 寫滿 3 行)
+- [ ] 「人」test 通過(遮標題光看元件懂情境)
+- [ ] 「舉一反三」test 通過(讀者能推出自己產品該怎麼用)
+- [ ] Label / note 沒有 spec 代號(Rule A、Variant X)或抽象符號表達式
+- [ ] Rule note 傳達原則(「為什麼」),不只是結論(「是什麼」)
+- [ ] 檔內註解語言一致(中文檔純中文、英文檔純英文,不中英夾雜)
+- [ ] 若是 anatomy:TOKEN_MAP / SIZE_SPECS 和 .tsx 的 cva 完全一致
+
+## 交付前最後一輪
+
+- [ ] `npm run storybook` 本地跑過,每個 story 視覺正常渲染
+- [ ] `npx tsc --noEmit` 無錯
+- [ ] dark mode 切換正常(色塊 / 文字色自動更新)
+- [ ] density 切換正常(若元件屬 field-height family)