@qijenchen/design-system 0.1.0-beta.3 → 0.1.0-beta.32

package/ds-canonical/skills/prototype/references/proposal-template.md

@@ -0,0 +1,229 @@
+# Proposal Template — explorations/ 結構 + Storybook 編排
+
+Phase 3 每個 shortlisted candidate 建一個 story + 共用 notes.md。
+
+---
+
+## 目錄結構(對齊 CLAUDE.md「Exploration 規則」)
+
+```
+src/explorations/{topic-slug}/
+├── notes.md                              # 本 topic 的 source of truth
+├── {CandidateA-name}.stories.tsx         # 候選 A 原型(1 檔內 3+ stories 各場景)
+├── {CandidateB-name}.stories.tsx
+├── {CandidateC-name}.stories.tsx
+└── _shared/                              # 僅此 topic 內共用的 helper(可選)
+    └── mock-data.ts
+```
+
+### 檔名慣例
+
+- **Topic slug**:kebab-case,描述問題(`onboarding-tour` / `bulk-action-confirm` / `empty-state-first-visit`)
+- **Candidate stories filename**:kebab-case + 描述性名稱(`linear-quick-filter.stories.tsx`)—**不用 `CandidateA/B/C`**(違反 CLAUDE.md「範例必須真實」mindset)
+
+### Storybook title 慣例(不與 Components/ 衝突)
+
+```tsx
+title: 'Explorations/{Topic Title}/{Candidate Name}'
+```
+
+範例:
+- `Explorations/Bulk Filter/Linear Quick-Filter`
+- `Explorations/Bulk Filter/Notion Command Palette`
+- `Explorations/Bulk Filter/Stripe Step Wizard`
+
+---
+
+## notes.md 範本
+
+```markdown
+# {Topic Title}
+
+## 問題定義(Phase 0 framing)
+
+**誰**:{primary user persona,如「Sales Ops 主管」}
+**想**:{jobs-to-be-done,如「在 50+ 筆 leads 中快速 filter 這週要跟進」}
+**解決**:{解除的痛點,如「現在得滾一頁找 tags,誤點率高」}
+**Constraints**:{mobile?a11y?時程?}
+
+## Phase 2 評估摘要
+
+見 Phase 2 完整評分表(略)。Shortlist 3 個:
+
+| Candidate | 核心機制 | 評分 | Phase 3 檔案 |
+|-----------|---------|------|-------------|
+| Linear Quick-Filter | Popover + checkbox + saved | 14/15 | `linear-quick-filter.stories.tsx` |
+| Notion Command Palette | modal Cmd-K + query | 11/15 | `notion-command-palette.stories.tsx` |
+| Stripe Step Wizard | Dialog + 3 步 fine-grained | 12/15 | `stripe-step-wizard.stories.tsx` |
+
+## Phase 3.0 Object Map(全 candidate 共享)
+
+本 feature 的 canonical object model,由 Phase 1 benchmark 的 OOUX 分析收斂 + Phase 0 framing 收敛而成。**3 個 candidate 共享此 Object Map**,差異只在 UI shape + CTAs 順序。
+
+**Objects**(core nouns):
+- {Object A}(核心名詞 1)
+- {Object B}(核心名詞 2)
+- {Object C}(若有)
+
+**Attributes per object**:
+
+| Object | Core attributes | Metadata | Identifying |
+|--------|----------------|----------|-------------|
+| {A} | ... | ... | ... |
+| {B} | ... | ... | ... |
+
+**Relationships(NOM)**:
+
+| From → To | Relationship |
+|-----------|-------------|
+| {A} → {B} | belongs to / has many / ... |
+| ... | ... |
+
+**CTAs per role per object**:
+
+| Role | {A} CTAs | {B} CTAs |
+|------|----------|----------|
+| Admin | Create / Edit / Delete | ... |
+| Member | View / Comment | ... |
+
+**UI Shape → DS 元件映射**:
+
+| Object | List | Card | Detail | Inline |
+|--------|------|------|--------|--------|
+| {A} | MenuItem / DataTable row | Card / FileItem | Page + Tabs | Tag / Chip |
+| {B} | ... | ... | ... | ... |
+
+完整 ORCA 方法與範本見 [`ooux-template.md`](ooux-template.md)。
+
+## 候選獨立說明
+
+### Linear Quick-Filter
+
+- **positioning**:面向重度 power user,shortcut-first
+- **適合場景**:
+  - Sales Ops 每日追蹤 leads(frequency=high,repeat task)
+  - Project Manager bulk status update
+  - Support 團隊 ticket triage
+- **不適合**:
+  - 新手 user(沒 onboarding 不知道 shortcut)
+  - 行動裝置(shortcut 無對應)
+- **新元件需求**:無(既有 Popover + Checkbox + Button 就夠)
+
+### Notion Command Palette
+
+- **positioning**:開放式 query,unified search
+- **適合場景**:
+  - 多維 filter(人 + tag + date)同時作用
+  - 可 memory 用戶的自訂 query
+- **不適合**:
+  - 情境簡單(2-3 filter)會 overkill
+  - 首次 user onboarding 負擔重
+- **新元件需求**:**可能需 `CommandPalette` 新元件**(本 DS 目前有 `Command` 但無全站 palette 結構)。若採用此 candidate,Checkpoint 3 討論是否升級。
+
+### Stripe Step Wizard
+
+- **positioning**:流程化,降低誤操作
+- **適合場景**:
+  - 破壞性 bulk action(delete 多筆)
+  - 需 audit trail 的金流 / 合規 action
+- **不適合**:
+  - 高頻日常操作(步驟拖慢速度)
+- **新元件需求**:無(既有 Dialog + Steps + Checkbox)
+
+## 下一步
+
+Phase 4 summary 整理完畢後,stakeholder 決定採用,走 graduation 流程:
+- 採用者遷移到 `packages/design-system/src/`(若有新元件)或直接 app-level UI
+- 未採用者:留 `explorations/{topic-slug}/` 或移 `_archive/`(保紀錄)
+
+## 參考
+
+- Phase 1 research 連結(略)
+- Phase 2 評估完整表(略)
+- Storybook 路徑:`Explorations/{Topic Title}/*`
+```
+
+---
+
+## Candidate story 範本
+
+每個 `{candidate-name}.stories.tsx` 建議結構:
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react'
+// 從 DS import 既有元件
+import { Popover, PopoverContent, PopoverTrigger } from '@/design-system/components/Popover/popover'
+import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
+// ...
+
+const meta: Meta = {
+  title: 'Explorations/Bulk Filter/Linear Quick-Filter',
+  parameters: { layout: 'padded' },
+}
+export default meta
+
+type Story = StoryObj
+
+// Story 1:positioning 說明(不可互動也 OK)
+export const Positioning: Story = {
+  name: '1. Positioning',
+  render: () => (
+    <div className="max-w-lg flex flex-col gap-3">
+      <h3 className="text-body-lg font-medium">Linear Quick-Filter</h3>
+      <p className="text-body text-fg-secondary">
+        shortcut `Cmd+Shift+F` 開 Popover,checkbox 多選,支援 saved filter 組合。
+        面向 sales ops 每日場景:速度 > 引導。
+      </p>
+      <div className="border-t border-divider pt-3">
+        <a href="..." className="text-info">Linear 原始參考 →</a>
+      </div>
+    </div>
+  ),
+}
+
+// Story 2-4:具體情境(3 個以上,對齊 Mindset #4)
+export const SalesOpsDaily: Story = {
+  name: '2. Sales Ops 每日追蹤 leads',
+  render: () => { /* 完整互動 prototype */ },
+}
+
+export const ProjectBulkStatus: Story = {
+  name: '3. PM bulk status update',
+  render: () => { /* */ },
+}
+
+export const SupportTriage: Story = {
+  name: '4. Support ticket triage',
+  render: () => { /* */ },
+}
+
+// Story 5(可選):edge case / failure mode(讓 stakeholder 看弱點也是成熟的設計溝通)
+export const NewbieOnboardingConcern: Story = {
+  name: '5. ⚠️ 新手首次遇到(知識死角)',
+  render: () => (
+    <div>
+      {/* 示範新手沒 shortcut 知識時看到什麼 */}
+    </div>
+  ),
+}
+```
+
+---
+
+## DS 使用鐵律(per CLAUDE.md)
+
+Phase 3 建 exploration 時:
+
+1. **優先用既有元件** `packages/design-system/src/components/`,不自創
+2. **Layout primitives 消費**(per CLAUDE.md 清單):Empty / item-layout / overlay-surface / ScrollArea / AspectRatio
+3. **Token 紀律**:只用 semantic token,不硬寫 hex / rgb / shadow-sm
+4. **hook check_token_hygiene 4 項**:shadcn alias / v4 shorthand / hardcoded shadow / native overflow — 4 項全過
+5. **新元件需求**:**notes.md 明文標示**,不偷偷 add 到 Components/(Checkpoint 3 專屬)
+
+---
+
+## Non-goals
+
+- Pixel-perfect 不是目標(Phase 3 看 pattern 可行性)
+- 不做完整 test coverage(exploration 不上 prod)
+- 不覆寫 DS 元件 props(若需 override, 代表這個 candidate 不適合既有 DS)

package/ds-canonical/skills/scan-similar-bugs/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: scan-similar-bugs
+description: Auto-invoke after fix commits — extracts root-cause anti-pattern, greps DS-wide for same pattern, runs visual verify, batches related fixes. Closes M10 mechanical gap. Invoke via /scan-similar-bugs.
+---
+
+# /scan-similar-bugs — Fix-time DS-wide Exhaustive Scan
+
+**目的**:任何 bug fix 提交後,**機械化掃 DS-wide 找同 pattern**,而非靠 model 記得 M10。
+
+**對齊**:
+- CLAUDE.md M10 「Proactive exhaustive scan」mechanical 落地
+- mindset #1「不取巧」+ #2「優先消費既有」+ #6「meta 抽象」
+- 對齊 IDE「find similar / find references」+ Chrome DevTools「find usages」+ GitHub Copilot「related code」3+ 家世界級 idiom
+
+**對位其他 skill**:
+- `/design-system-audit` 是**定期 batch** 7 維 audit
+- `/visual-audit` 是**單次視覺對齊** check
+- 本 skill 是 **batch-end-only root-pattern scan**(2026-05-12 codex 抓 infra conflict 重構:per-fix → batch-end,對齊 `/bug-fix-rhythm` Phase 2-3 batch fix + single end-verify canonical;M32 split 後 batch-end home 移至 bug-fix-rhythm skill)
+
+## When to invoke
+
+**強制(auto-chain)— batch-end only**(2026-05-12 重構,per codex):
+- multi-issue session 結束後**一次**(不是每 fix 一次)
+- session 內 ≥ 2 fix commit 觸發批次 root-pattern scan
+- session_start_governance_check.sh 偵測 上 session 有 ≥ 2 fix commit 但 batch-end scan 沒跑 → 提醒
+
+**手動 invoke**:
+- user 明言「掃同類 bug / 看其他元件有沒有 / 全 DS scan」
+- multi-issue batch session 結束想驗 root-pattern DS-wide
+
+**不 invoke**(對齊 Anthropic Best Practice 小修 skip plan):
+- **Surgical visual bug**(user 列 N 個 visual defects + 無 canonical / API / cross-component → 批 fix + final verify only,不必 scan-similar)
+- pure refactor(無 bug 修復語義)
+- spec.md / docs only commit
+- 純 typo / import cleanup
+
+## Non-goals
+
+- 不擴展 scope 到「audit 7 維品質」(那是 `/design-system-audit`)
+- 不做視覺 regression baseline diff(那是 `/visual-audit`)
+- 不改 canonical(找到 pattern 後修是 surgical fix,動 canonical 走 audit / Checkpoint)
+
+---
+
+## Workflow(5 phases)
+
+### Phase 0 — 抓 root-cause anti-pattern
+
+```bash
+# 讀 last fix commit message + diff
+git log -1 --format='%s%n%n%b'
+git show HEAD --stat
+```
+
+從 commit message + diff 抽出 grep-able pattern。常見類型:
+
+| Bug 類型 | Anti-pattern grep target |
+|---|---|
+| Padding / sizing 公式錯 | `calc((var(--field-height-X) - <num>px) / 2)` etc |
+| Token leak / shadcn alias | `bg-popover / text-muted-foreground / bg-accent` |
+| 硬寫 magic number | `text-[14px] / shadow-[0_2px_8px_...]` |
+| API mis-use(prop combo)| `iconOnly + endIcon` / `loading + disabled` |
+| a11y missing | `<button>` 無 `aria-label` 又無 children |
+| Symbol mis-import | `from 'shadcn/ui/X'` |
+| CSS w/h asymmetric | SVG 量測 width !== height |
+
+**Output**: `ANTI_PATTERN`(grep regex / Playwright assertion)。
+
+### Phase 1 — DS-wide grep / visual scan
+
+選最適合的 detection:
+
+**Static grep**(快,適合 token / class / API mis-use):
+```bash
+grep -rnE "$ANTI_PATTERN" packages/design-system/src/ --include="*.tsx" \
+  | grep -v "test_\|stories\|node_modules"
+```
+
+**Playwright visual scan**(慢,適合 geometry / a11y / interaction):
+```bash
+node scripts/scan-asymmetric-icons.mjs   # 已存在,iconOnly visual scan template
+# 或 base 同 pattern 自寫 dim-specific scan
+```
+
+**Output**:候選清單(file:line + 樣本)。
+
+### ⚠️ Checkpoint 1 — Triage
+
+向 user present:
+```
+Phase 1 found N candidates of same anti-pattern:
+- packages/design-system/src/components/A/a.tsx:42  > grep match
+- packages/design-system/src/components/B/b.tsx:18  > grep match
+- packages/design-system/src/components/C/c.tsx:55  > 視覺 14×16
+
+Proceed?
+- (a) Auto-fix all N(若修法 deterministic 例 token rename)
+- (b) Review per-file(若 fix 需個別判斷)
+- (c) 留 N 個 tech debt 後續處理(寫 memory + 不修)
+```
+
+不可 silent 跳過 user — fix scope 影響 N 元件,**M10 + 稽核 vs 執行 分權**要求 user 拍板。
+
+### Phase 2 — 批量 / 個別 fix
+
+按 Checkpoint 1 user 選的路執行。每修一檔:
+- 用 Edit(不 Write,降風險)
+- 修完 grep 該 anti-pattern 應 0 match
+- npx tsc --noEmit 必過
+
+### Phase 3 — Visual / unit verify
+
+- Visual:跑 `npm run icons:scan` 或 dim-specific scan
+- Unit:跑 `npm run hooks:test`
+- TSC:`npx tsc -b`
+- 全綠才繼續
+
+### Phase 4 — Final report + memory + new defense
+
+```markdown
+## Scan-similar-bugs report
+
+### Root cause(來自 last fix commit `<hash>`)
+- Pattern:{ANTI_PATTERN}
+- Origin file:{first detected location}
+
+### DS-wide impact
+- {N} candidates found
+- {M} fixed this run
+- {K} deferred(spec rationale 已記)
+
+### New defense layer(防 future regression)
+- 加 hook:`.claude/hooks/check_<pattern>.sh`(若 pattern 易 grep)
+- 加 visual test:`scripts/scan-<pattern>.mjs`(若需 Playwright)
+- 加 spec rule:{spec.md anchor}
+
+## Self-improvement capture
+- 新 anti-pattern 加進本 skill 的 Phase 0 「Bug 類型 → grep target」表
+- M10 fire 紀錄(commit 後本 skill invoke vs not)
+```
+
+寫進:
+- 對應 commit message
+- `memory/` 若是 cross-session pattern
+- 本 skill `references/` 若是 reusable detection 公式
+
+---
+
+## ⚠️ Checkpoints(禁止跳)
+
+### Checkpoint 1 — Phase 1 後 Triage
+N 個 candidate 的修法 scope。**禁止 auto-fix 超過 5 檔不 ask user**。
+
+### Checkpoint 2 — 動 canonical
+若 N candidates 都 violate 同 canonical,但 canonical 本身可能 outdated → 走 audit 重訂(不在本 skill scope)。
+
+### Checkpoint 3 — Defer 的 tech debt
+若 user 選 (c) 留 tech debt → 必寫 memory + 標明「deferred at <date>,reason: <reason>」。`/codify-corrections` 季度會 review。
+
+---
+
+## 對位其他 skill / hook
+
+| Tool | scope | 跟本 skill 關係 |
+|---|---|---|
+| `/design-system-audit` | 7 維 batch audit | 本 skill 抓不到的 architectural pattern audit 補位 |
+| `/visual-audit` | 單次視覺對齊 | Phase 3 verify 用 |
+| `/scan-similar-bugs`(本) | **immediate-after-fix grep + verify** | M10 mechanical 落地 |
+| `/knowledge-prune` | 季度 governance prune | 不重複 |
+| `check_l3_primitive_import.sh`(hook) | L3 import 違規 | 即時 detect,本 skill 是 batch retro scan |
+| `pre_write_subsumption_check.sh`(hook)| 新 file / M-row | 不重複 |
+
+**3 層 防線**:
+- Hook(pre/post tool):**寫的瞬間** detect
+- 本 skill(fix-time):**修完瞬間** scan DS-wide
+- `/design-system-audit`(periodic):**季度** 7 維 sweep
+
+---
+
+## 世界級對照
+
+- **Chrome DevTools "find references"**:單元件變更後找其他 consumers
+- **VS Code "find similar code"**:AI-powered same-pattern scan
+- **GitHub Copilot Workspace**:fix 後自動 propose related changes
+- **WebStorm "Inspect Code → Similar Patterns"**:同 pattern detect
+
+我們對齊 4 家但加 **DS-domain-specific anti-pattern table**(Phase 0 列表),是 generic IDE 沒做到的。
+
+---
+
+## Self-improvement capture
+
+每次 invoke 完寫:
+- (a) 新發現 anti-pattern → 加到 Phase 0 表(grep target template 更新)
+- (b) Detection false positive → 修 grep regex 或加 allowlist 註解 pattern
+- (c) Phase 1 漏掃 location → 補 grep scope(extend 到 hooks/ / scripts/ etc)
+
+回填 SKILL.md 或 references/ 形成累積資產。

package/ds-canonical/skills/story-auto-compile-migrate/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: story-auto-compile-migrate
+description: Batch-migrate design system components to Story Auto-Compile Phase 1+2 structure (tsx `componentMeta` export + spec.md YAML frontmatter). Mechanical steps auto (parse cva → generate componentMeta / infer sizes from cva / extract 禁止事項 from spec). Judgment fills (world-class 對照 / when descriptions) go to checkpoint for user/AI sign-off. Invoke via /story-auto-compile-migrate when user says「migrate 元件到 auto-compile / phase 4 migration / 把 X 元件加 componentMeta」OR auto-chained by /design-system-audit Dim 23 when un-migrated components found.
+---
+
+# Story Auto-Compile Migrate — 批次將元件移到 Phase 1+2 結構
+
+**目的**:把 44+ 元件從 hand-written stories 遷到 auto-compile-able 結構(tsx `componentMeta` export + spec YAML frontmatter)。分「mechanical auto」+「judgment checkpoint」兩層。
+
+**不含**:不改元件實作(cva / tsx logic 不動);不產 stories(compile-stories 負責)。只加 metadata。
+
+## When to run
+
+- User 明言「migrate X 元件 / 批次 migrate / phase 4 migration」
+- `/design-system-audit --deep` Dim 23 發現未 migrated 元件 + user 在 Checkpoint 1 sign-off
+- 新建元件 via `/new-component` 時 Phase X 自動跑(未來延伸)
+
+## Non-goals
+
+- 不改 cva variants / defaults(變體結構不動)
+- 不動 stories.tsx 實作
+- 不填 judgment 欄位(world-class / when)— 只擺 TODO placeholder,跑 Phase 2 checkpoint
+
+---
+
+## Workflow(4 phases)
+
+### Phase 0 — Scan 未 migrated 元件
+
+```bash
+node scripts/compile-stories.mjs --all --check 2>&1 | grep "skipped"
+```
+
+得清單:每元件 `{Name}(reason: no componentMeta export | no frontmatter)`。
+
+Output:待 migration 元件清單 + 每元件缺哪層(tsx only / spec only / 兩層都缺)。
+
+### Phase 1 — Mechanical migration(AUTO,per component)
+
+對每元件:
+
+#### 1a. tsx: 加 `componentMeta` export
+
+從 tsx cva 讀:
+- `variants` keys → `componentMeta.variants = { [key]: {} }`(purpose 空)
+- `size` variants keys → `componentMeta.sizes = { [key]: {} }`(fieldHeight/icon/typography 空,待 Phase 2 填)
+- `defaultVariants` → `defaultVariant` / `defaultSize`
+- `states` 預設 `['default', 'hover', 'active', 'focus-visible', 'disabled']`(元件無互動則改)
+- `tokens` — grep tsx 的 `--*` token usage 自動列,或留 `{ bg: [], fg: [], ring: [] }` 待 Phase 2 填
+- `family` — 讀 spec 第一段 Layout Family 宣告
+
+插入位置:tsx 檔案 `export { Component, ... }` 之前。
+
+#### 1b. spec.md: 加 YAML frontmatter
+
+插到 spec.md 頂部(H1 之前):
+```yaml
+---
+component: {Name}
+family: {N from spec Layout Family declaration}
+variants:
+  {key}:
+    when: "TODO: Phase 2 填"
+    world-class: []  # TODO: Phase 2 填 ≥ 3 家對照
+  # ... (mirror tsx.componentMeta.variants keys)
+sizes:
+  {key}: { when: "TODO: Phase 2 填" }
+禁止事項:  # 從 spec 「禁止事項」section 自動 extract,若有
+  - rule: "..."
+    reason: "..."
+    反例: "..."
+related:
+  近親: []  # TODO: Phase 2 填
+  SSOT-anchor: "{name}.spec.md"
+---
+```
+
+#### 1c. 每元件 migrate 完跑 `compile-stories {Name} --check`
+
+- 若 keys 對齊 → ✅ 通過
+- 若不齊 → 檢查 cva 是否有特殊 variant(danger / secondary / ghost 等 mapping 邏輯)需手動對應
+
+Phase 1 output:N 元件成功 mechanical migrated / M 元件遇特殊 cva 邏輯需 Phase 2 手動 mapping。
+
+### ⚠️ Checkpoint 1 — 批量 sign-off
+
+Present user:
+```
+Phase 1 完成:
+- ✅ {N} 元件 mechanical migrated(componentMeta + frontmatter placeholders in,compile --check passed)
+- ⚠️ {M} 元件 needs manual cva mapping(列出 + 原因)
+- TODO: {N+M} 元件 frontmatter 的 variants[].when / world-class[] / sizes[].when / related[] 是 judgment 欄位,Phase 2 填
+
+Proceed Phase 2 judgment fill?(scope big)
+OR commit Phase 1 先(mechanical only)讓後續 session 漸進 fill?
+```
+
+### Phase 2 — Judgment fill(STOP per component)
+
+對每個 migrated 元件:
+- `variants[].when` — 從 spec 現有「variants」section 或近親元件同名 variant 抄
+- `variants[].world-class` — 讀 benchmarks/ 外部 snapshot,或 inline grep 既有 spec 對照
+- `sizes[].when` — 從 spec size table 抄
+- `related.近親` — grep SSOT reciprocal pointers
+
+每元件過 Checkpoint(user 可快速看 frontmatter diff,approve 或 reject 單題)。
+
+### Phase 3 — Verify + commit
+
+```bash
+node scripts/compile-stories.mjs --all --check
+```
+
+必 0 drift。跑 tsc -b 確認 tsx export 無 break。
+
+Commit 每批 5-10 元件一個(不一次全推,好 review)。
+
+### Phase 4 — Self-improvement capture
+
+```markdown
+## Self-improvement capture
+- 新發現 cva patterns: {特殊邏輯整理到 planning/story-auto-compile.md 供未來參考}
+- Mechanical migration 失敗 case: {列出 + 手動 workaround 紀錄}
+- Migration 覆蓋率:{N migrated / 44 total}
+```
+
+---
+
+## Checkpoints(禁止跳)
+
+### ⚠️ Checkpoint 1 — Phase 1 batch sign-off
+
+### ⚠️ Checkpoint 2 — Phase 2 judgment 單題 sign-off(per element × per field)
+
+可 user 批准「全預設套 AI 推斷」模式加速,但每批後 stop 檢查 5-10 element 產出。
+
+### ⚠️ Checkpoint 3 — 特殊 cva 遇到 mechanical 無法 map
+
+STOP 提議 user:(a) 修 cva 對齊標準形;(b) componentMeta 特殊寫法;(c) 跳過該元件到下一個。
+
+---
+
+## 與 /design-system-audit 分工
+
+| Flow | 誰做 |
+|------|------|
+| 偵測未 migrated | `/design-system-audit --deep` Dim 23 |
+| 批次 mechanical migrate | **本 skill Phase 1** |
+| Judgment fill | 本 skill Phase 2(CP 2) |
+| Drift detection(已 migrated)| hook `check_story_compile_drift.sh` + Dim 23 |
+
+**Chain**:user 說「ds 完整 audit」→ `/design-system-audit --deep` Phase 1 跑 Dim 23 → 發現 N 未 migrated → CP 1 提報 user → user sign-off → Phase 3 auto-chain 本 skill → mechanical migrate + judgment CP → 全 migrated + 0 drift。
+
+## References
+
+- `.claude/planning/story-auto-compile.md` — 完整 4-phase plan
+- `scripts/compile-stories.mjs` — compile + verify
+- `.claude/skills/story-writing/references/anatomy-standard.md` — 6-story canonical
+- `.claude/skills/new-component/SKILL.md` — 新建元件流程(本 skill 為已建元件 migration)