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

package/ds-canonical/skills/codify-corrections/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: codify-corrections
+description: Process .claude/logs/user-corrections.jsonl — the Stop-hook-harvested signals of user corrections ("不是" / "不對" / "應該" / "糾正" etc.). Dedup by session + keyword, cluster by topic, propose edits to the right home(CLAUDE.md M-row / memory feedback file / skill reference / spec.md rationale). Each cluster is a Checkpoint — user approves before edit. After codification archive processed entries. Invoke when user-corrections.jsonl > 20 entries(session_start soft reminder)or > 40 entries(hard threshold), OR quarterly. This skill closes the loop between mindset #6 "user tell me once, not twice" and actual governance text changes — without it, corrections die in logs.
+---
+
+# Codify Corrections — 把 user 糾正 log 落到 governance 文件
+
+**目的**:`.claude/logs/user-corrections.jsonl` 是 `stop_passive_logging.sh` R2 `rule_harvest_corrections()`(原 lib/stop_harvest_corrections.sh,已 folded 進統一 Stop hook)從每 session transcript 抓到的「不是 / 不對 / 應該 / 糾正」訊號。骨架存在,但從 log 到實際 CLAUDE.md / memory / spec edit 原本全靠人工讀 + 決定寫哪,實務上堆積 = 骨架失靈。本 skill 把這條 loop 合上。
+
+**對齊 CLAUDE.md**:
+- 治理 canonical L2(per-commit)下游
+- mindset #6「user tell me once,我不該要 tell me twice」執行面
+- M14 AUTO integrate pipeline 第 7 層(memory / CLAUDE.md 落地)
+- 稽核 vs 執行 分權:動 canonical substantive → STOP Checkpoint(本 skill 內建)
+
+## When to run
+
+- User 明言「處理 correction / codify / 看一下 log」
+- `session_start_governance_check.sh` soft reminder(> 20 corrections)或 hard blocker(> 40)
+- 季度(跟 `/knowledge-prune` 同期)
+- `/knowledge-prune` Phase 0.5 external signal 可 chain 本 skill
+
+## Non-goals
+
+- 不改 code(`.tsx` / `.css`)— 只動 governance 文件
+- 不自動 write 任何 M-row(新 Meta-Pattern 必 Checkpoint 3 — 動 canonical substantive)
+- 不刪 jsonl 歷史 — 處理後 append 到 `.processed.jsonl`,raw log 保留 grep evidence
+- 不重跑 harvest — harvest 是 stop_passive_logging.sh R2 rule_harvest_corrections()(原 stop_harvest_corrections.sh,已 folded)的責任
+
+---
+
+## Workflow(5 phases)
+
+### Phase 0 — Scan + dedup
+
+讀 `.claude/logs/user-corrections.jsonl`。每行格式:
+```json
+{"ts":"...", "session":"...", "count":N, "sample":"unescaped correction text"}
+```
+
+**dedup 規則**:
+- 同 session 多行 → 只保留 count 最大那行(log 已 per-session dedup,但防萬一)
+- 跨 session 同 `sample` 內容 > 80% similar(levenshtein / token ratio)→ merge
+
+**output**:`.claude/logs/corrections-pending.md`(session-local 不 commit),每條 entry:
+```
+- [2026-04-22 session:abc123] sample: "不是 X,是 Y"  — occurrences: 3
+```
+
+### Phase 1 — Cluster by topic(AI judgement)
+
+每條 entry 判斷 topic + 應落 home:
+
+| Topic pattern | 應落 home |
+|--------------|----------|
+| 個人偏好 / 工作節奏 / 「我喜歡 X」| `~/.claude/.../memory/feedback_*.md` |
+| 設計 canonical / 元件行為 / prop API | `packages/design-system/src/**/spec.md`(rationale 段) |
+| 跨元件 meta 規則(「凡 overlay 都必 X」)| CLAUDE.md Meta-Pattern M-row(**必 Checkpoint 3**)|
+| Audit protocol / skill workflow | `.claude/skills/*/references/` |
+| Tool / hook 使用方式 | hook docblock or `.claude/hooks/*.sh` 修行為 |
+
+**判斷原則**:先看 sample 是否已有 home — 若 memory 已有相似 entry → 更新既有;無 → 新建。
+
+**output**:`phase1-clusters.md`,每 cluster 含:proposed home / proposed edit text / which jsonl entries subsumed
+
+### ⚠️ Checkpoint 1 — Phase 1 triage
+
+向 user present:
+```
+Phase 0 scan 找到 N 條 pending corrections(dedup 後 M 條)。
+Phase 1 cluster:
+  - P0(auto-apply)AUTO fixes to memory 現有 entry / spec rationale:X 條
+  - P1(review + apply)新建 memory file / spec rationale 新段:Y 條
+  - P2(STOP)新 M-row / 動 CLAUDE.md canonical substantive:Z 條(需 Checkpoint 3)
+
+Proceed P0 auto?然後逐一 review P1?P2 分開討論?
+```
+
+**Do NOT skip**:P2 動 canonical meaning,per 稽核 vs 執行 分權 必 user sign-off。
+
+### Phase 2 — Apply P0 + P1
+
+**P0**(明確 home + 明確 edit):AUTO edit,commit 前最後 show diff 給 user 一次過目。
+
+**P1**(新建 memory / spec 新段):one-by-one present → user approve → edit。
+
+每次 Edit 後 tsc / lint 無需跑(純 governance 文件),但 MEMORY.md index 若有更新必包含。
+
+### ⚠️ Checkpoint 2 — 新 memory 命名 3-test
+
+每個新 memory file 過 CLAUDE.md `## 命名必過三重 test`:
+1. 既有命名 pattern?
+2. ≥ 2 家 world-class DS idiom?
+3. 跨元件認知衝突?
+
+Fail 任一 → 重名或拆分。
+
+### ⚠️ Checkpoint 3 — P2 新 M-row(動 canonical substantive)
+
+**STOP**。present 完整 proposal:
+- Correction cluster 原始 samples
+- Proposed M-row 文字
+- World-class benchmark(≥ 3 家 DS,M8 強制)
+- 被吸收的下游 M-row / specific bug / memory entries 清單(M10 下游刪)
+
+User approve 後才 edit CLAUDE.md。
+
+### Phase 3 — Archive processed entries
+
+處理完畢:
+```bash
+# Append processed entries to .processed.jsonl(保留歷史 grep)
+cat user-corrections.jsonl >> user-corrections.processed.jsonl
+# Truncate main log
+: > user-corrections.jsonl
+```
+
+### Phase 4 — Final report + metric snapshot
+
+```markdown
+## Codify corrections report(N 日期)
+
+### Processed
+- Total entries scanned:N
+- After dedup:M
+- Clustered:K
+
+### Applied
+- P0 auto:X edits to {file list}
+- P1 review:Y edits
+- P2 new M-row:Z(詳列)
+
+### Subsumed downstream(M10 上游加下游減)
+- {list of specific bugs / memory entries / M-row 可刪}
+
+### Still deferred
+- {entries 不適合 codify:過度零散 / scope 不清 / user 已撤回}
+```
+
+Update `.claude/logs/metric-snapshots.jsonl`:
+```json
+{"ts":"...","tag":"codify-corrections-run","processed":N,"p0":X,"p1":Y,"p2":Z}
+```
+
+## Self-improvement capture
+
+```markdown
+## Self-improvement capture
+- 新發現 pattern:{某 topic 反覆出現 → 該抽 meta}OR "無"
+- Harvest miss:{stop_passive_logging.sh R2 rule_harvest_corrections()(原 stop_harvest_corrections.sh,已 folded)沒抓到但該抓的 keyword}OR "無"
+- Codify-to-home 公式漂移:{有 topic 判斷多次走錯 home → 更新 Phase 1 判斷表}OR "無"
+```
+
+---
+
+## 與其他 skill 分工
+
+| Skill | Scope |
+|-------|-------|
+| `stop_passive_logging.sh` R2 rule_harvest_corrections()(原 stop_harvest_corrections.sh,已 folded)| 抓 log — 不 codify |
+| **本 skill**(`/codify-corrections`) | log → governance 文件 edit |
+| `/knowledge-prune` | governance 文件 prune — 不處理新 correction |
+| `/design-system-audit --deep` Phase 4.5 | chain `/knowledge-prune`;未來可 chain 本 skill |
+
+**跟 `/knowledge-prune` 差異**:prune 是「砍冗贅」(retire),本 skill 是「吸收新訊號」(add / update)。兩者對稱,時序:先 codify(加 new)再 prune(砍 old)。
+
+---
+
+## 世界級對照
+
+- GitHub CODEOWNERS diff → assignment:本 skill 類似「correction ownership assignment」
+- Linux kernel `Documentation/process/howto.rst`:upstream patches go through maintainers — 我們 correction 也有「送到對的 home」的流程化
+- RFCs / ADRs workflow:新 canonical 走 Checkpoint 3 等同提 ADR
+
+本 skill 是本 DS 原創,因為 Claude Code 生態沒有同層級的「session log → governance codify」pipeline。
+
+---
+
+## Non-goals 重申
+
+- 不改 code
+- 不自動寫新 M-row
+- 不刪歷史 log
+- 不跑 harvest(是 hook 責任)

package/ds-canonical/skills/codify-principle/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: codify-principle
+description: User 提出新設計原則 → auto 5-layer artifact generation pipeline。將原則文字自動轉化為 SSOT canonical text + hook scaffold + audit dim + scaffold update + memory entry,放入正確 home。對齊 M14 + M19 + 8-home 治理 canonical。Invoke when user says「我想加一條設計原則 X」「新原則 Y」「ensure X always」OR auto-recognize trigger phrase。本 skill 把 reactive markdown rule 升級成 proactive principle-to-artifact generator。
+---
+
+# Codify Principle Skill — 原則 → 5-layer artifacts auto-generator
+
+User mandate「我說一條原則 → 自動轉化產生正確 artifacts 放正確位置」(2026-04-26)。本 skill 是 M19 ensure-canonical pipeline 的 generator 上層,接受 principle text 為 input,output 5-layer 完整落地。
+
+## When to invoke
+
+- User 明說「我想加一條設計原則 X」「新原則 Y」
+- User 描述新規則 + 期望「永遠遵守」/「不可漂移」
+- M19 trigger phrase(確保 / 一定 / 永遠不漂移)+ 涉及新原則內容
+- Auto-chained from `/ensure-canonical` 當 trigger 是「新原則」非「既有原則 enforce」
+
+## Non-goals
+
+- 不直接動既有 canonical without sign-off(改 substantive meaning 走 STOP)
+- 不跳過 M8 benchmark — 任何新 cross-component 原則必 ≥ 3 家世界級對照
+- 不省略 user sign-off checkpoint
+- 不替換 user 判斷 — 模糊原則需要 user 親自釐清
+
+## Workflow(7 phases)
+
+### Phase 1 — Parse principle text(Auto)
+
+User 提供 principle text。Skill 提取:
+- **Scope**:跨元件 / 單元件 / 跨 layer / governance-only
+- **Type**:Absolute(機械可驗)/ Consistency(對照可驗)/ Judgement(無 mechanical)
+- **Affected homes**(8-home matching):
+  - `CLAUDE.md` 章節?
+  - `*.spec.md` 哪個元件?
+  - 新 hook?
+  - 新 audit dim?
+  - 新 skill?
+  - Memory entry?
+
+### Phase 2 — M8 benchmark(STOP if missing)
+
+對 cross-component 原則(scope ≠ governance-only),**強制** M8 ≥ 3 家世界級 DS 對照:
+1. 跑 web research(WebFetch Polaris / Material / Carbon / Atlassian / Ant 等對應 component / pattern)
+2. 列對照表:每家做法 + 我們對齊 / 偏離 + 偏離 rationale
+3. **STOP** 若 < 3 家對照 → 跟 user 確認原則是否成熟
+
+### Phase 3 — Draft 5 layer artifacts(STOP per layer)
+
+每 layer 產 draft + Checkpoint sign-off:
+
+| Layer | Action |
+|-------|--------|
+| 1. SSOT canonical | 寫 markdown text 到對應 home(CLAUDE.md 章節 / spec.md 段 / references/{topic}.md);包含 rule + Why + How to apply + 世界級 anchor |
+| 2. Spec frontmatter | 若 trait-like → 加入 `traits:` array OR 新增 frontmatter field |
+| 3. Hook | 若 Absolute → scaffold `.claude/hooks/check_{topic}.sh` 含 P0/P1 detection logic + 7-Q self-check 模板 |
+| 4. Audit dim | 加 dim N 到 `/design-system-audit` SKILL + audit-prompts.md(periodic verify) |
+| 5. Memory | 寫 `~/.../memory/project_{topic}_{date}.md` + add MEMORY.md index entry |
+
+**每 layer 都 Checkpoint user sign-off**:
+```
+Phase 3 Layer N draft ready:
+{draft content}
+Approve? Edit? Skip?
+```
+
+### Phase 4 — Auto-generate scaffold update
+
+若原則是「新元件 / 新 story 該滿足」 → 更新 `/new-component` Phase 5 scaffold + `/story-writing` Phase 0。
+
+### Phase 5 — Auto-generate hook test
+
+若 Layer 3 hook 建立 → scaffold `.claude/hooks/tests/test_{topic}.sh` 含 ≥ 5 smoke tests(silent skip / canonical compliance / drift block / rationale escape / per-trait verify)。
+
+### Phase 6 — Apply + verify(分組 commit)
+
+Per layer 一個 commit:
+1. SSOT commit
+2. Hook + test commit
+3. Audit dim commit
+4. Scaffold update commit
+5. Memory + final verify commit
+
+每 commit 後跑:
+- `npx tsc -b`
+- 新 hook test
+- `node scripts/audit-content-quality.mjs --check`(防 content drift)
+
+### Phase 7 — Self-improvement capture
+
+```markdown
+## Self-improvement capture
+- 新原則 SSOT home: {path}
+- 新 hook: {filename} / fires on: {pattern}
+- 新 audit dim: N
+- 5-layer 落地完整度: {% layers actually shipped}
+- 跳過的 layer + rationale: {if any}
+```
+
+更新 `.claude/logs/codified-principles.jsonl` log:
+```json
+{"date":"2026-04-26", "principle":"...", "scope":"...", "layers":["ssot","hook","audit","scaffold","memory"], "commits":[...]}
+```
+
+## Checkpoints(禁止跳)
+
+### ⚠️ Checkpoint 1 — Phase 1 parse
+User 親自確認 scope / type / affected homes 是否正確,禁 AI 單方面決定。
+
+### ⚠️ Checkpoint 2 — Phase 2 benchmark
+< 3 家世界級對照 → STOP,跟 user 確認是否走 OG-only(原創原則,需 rationale 文檔)。
+
+### ⚠️ Checkpoint 3 — Phase 3 per-layer
+每 layer draft 都過 user。SSOT 是 canonical 改變,動 substantive meaning → 必 sign-off。
+
+### ⚠️ Checkpoint 4 — Phase 6 verify
+任何 layer commit 後 tsc / hook test fail → 回該 phase 修,**不繞過**。
+
+## 與既有 skills 分工
+
+| Skill | Scope |
+|-------|-------|
+| `/ensure-canonical` | 既有原則 enforcement(hook / audit 補強)|
+| `/codify-principle`(本)| **新原則** 從 0 生成 5-layer artifacts |
+| `/knowledge-prune` | 反向:既有原則太多時 retire |
+| `/design-system-audit` | periodic verify 既有 artifacts compliance |
+
+`/codify-principle` 是新原則 entry point;落地後其他 skill 接管 enforcement / verify / retire。
+
+## References
+
+- `~/.../memory/MEMORY.md` — index of codified principles
+- `.claude/logs/codified-principles.jsonl` — execution log
+- CLAUDE.md `# 治理 canonical` 8-home — home 識別 rules
+- CLAUDE.md `# Meta-Pattern 預警` M14 / M19 — 上游 pipeline rules
+
+## 範例呼叫
+
+User 說:「我要加一條原則:所有 form-like 元件必須支援 controlled + uncontrolled dual-mode」
+
+Skill 自動:
+1. Parse:scope=cross-component,type=Absolute(可機械驗 prop pair)
+2. M8:Polaris/Material/Atlassian React form lib 都支援 dual-mode ✓ (3/3 ≥3)
+3. Draft layer:
+   - SSOT:`.claude/rules/ui-development.md`「元件 Props 命名」 + form spec
+   - Hook:`.claude/hooks/check_form_dual_mode.sh`(未實作;此為 5-layer 產物範例 — audit-only via dim,無 write-time hook)偵測 missing pair
+   - Audit dim:Dim 31「Dual-mode coherence」(已存在 Dim 26 — STOP 提議擴充而非新增)
+   - Scaffold:`/new-component` Phase 4 加 dual-mode template
+   - Memory:`project_form_dual_mode_2026_04_26.md`
+4. Per-layer Checkpoint
+5. Hook test + audit prompt
+6. Apply + tsc + verify
+7. Capture

package/ds-canonical/skills/component-quality-gate/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: component-quality-gate
+description: Pre-merge quality gate for new or significantly refactored design-system components. Walks through Spec / Code / Stories / Ship checklist (35 items) to ensure world-class discipline before a component enters `packages/design-system/src/components/`. Invoke when user says「元件做完了」「這元件可以收工了嗎」「元件 ready 嗎」「check 這個 element」「要 merge 進 DS 了」or before closing a component PR.
+---
+
+# Component Quality Gate
+
+Purpose: 元件進 `packages/design-system/src/components/` 前的最終 checklist。防止「code 寫完但 spec / stories / token 消費紀律有漂移」的半成品進入系統。
+
+## When to run
+
+- 新元件即將合入 design-system
+- 既有元件大改(variant / size / token 結構重構)
+- Code review 前的自審
+- `/design-system-audit` 發現某元件偏離 checklist 後的修復驗證
+
+**不 invoke 的情境**:小改(typo / 單 bug fix),走 spec 本身的 sync hook 即可。
+
+## Preconditions
+
+- 元件 folder 存在於 `packages/design-system/src/components/{Name}/`
+- 該元件的 `.spec.md` / `.tsx` / `.stories.tsx` / `.anatomy.stories.tsx` / `.principles.stories.tsx` 已完成初稿
+- 已讀相關 path-scoped rules(`.claude/rules/spec-rules.md` / `.claude/rules/ui-development.md`(含 Tailwind / Token 命名 / Props 命名 / shadcn 元件規範) / `.claude/rules/story-rules.md`)
+
+## Workflow
+
+### Phase 1 — Spec 審查(先於 code,spec 是 judgment home)
+
+逐條走 `references/checklist.md` 的 **Spec section**(12 項):定位明確 / 實作基礎宣告 / 每個 prop/variant 有何時用何時不用 / 互斥規則 / 為什麼不只是什麼 / 術語一致 / 無視覺描述 / 禁止事項列出 / 邊界案例覆蓋 / 近親 SSOT pointer / 對標世界級 7 維度。
+
+任一不過 → 停下補 spec。**不往下跑 Phase 2**。
+
+### Phase 2 — Code 審查
+
+走 **Code section**(13 項):shadcn 基底完整 / cva() 不條件字串 / data-* selector / 無硬寫 token / Tailwind v4 var() 正確 / 無自包 Provider / Props 命名按「是什麼」/ ARIA 齊 / defaultVariants size=md 若屬 field-height family。
+
+cva `defaultVariants` 異動 → 強制 grep 該元件所有檔案確認三方同步(見 `.claude/skills/story-writing/references/anatomy-standard.md` → 高風險漂移點)。
+
+### Phase 3 — Stories 審查
+
+走 **Stories section**(6 項):展示 / 設計規格 5-story 齊全 / TOKEN_MAP 對得上 cva / Rule note 傳達原則 / title 命名對齊 / Internal vs Components 判斷正確。
+
+範例品質問題 → invoke `/story-writing` skill 做深度審。
+
+### Phase 4 — Ship 審查(最後驗證)
+
+走 **Ship section**(6 項):
+1. `npm run storybook` 本地渲染正常
+2. `npx tsc -b` 無錯(**禁用 `--noEmit`**,root tsconfig `files: []` silent pass)
+3. import 路徑 `@/design-system/...`
+4. 分類標註(Internal vs public)正確
+5. **Visual audit 過關**(2026-04-21,stakeholder-gate 強制)
+6. **Story canonical-drift 過關**(2026-04-24,Phase 4 story auto-compile)— 若元件已 migration(有 `componentMeta` export + spec frontmatter)→ 跑 `node scripts/compile-stories.mjs {Name} --check` 必 exit 0;migration 未做 → skip 此項(另 new-component skill 推動逐步 migration)
+7. **Code quality 過關**(2026-04-24,Dim 27)— 跑 `node scripts/code-quality-audit.mjs --scope=component:{Name} --check` 必 exit 0(無 P0 clean-code violation)。P1 flag 但不 block;P0(`any` 無 escape / file-size > 800 / circular dep)必修才 ship
+
+### Phase 4.5 — 進階稽核 6 維(強制 chain,對齊 CLAUDE.md `# 稽核 canonical` M6)
+
+**這是 stakeholder-gate,不能跳**。元件 merge = stakeholder-visible 產出,**必過進階模式 6 維**(非高效)。
+
+| 維度 | 做法 | Chain 的 skill / tool |
+|------|------|--------------------|
+| D1 設計語言一致 | Phase 1-3 已覆蓋 | — |
+| D2 程式語言一致 | Phase 2 + tsc + lint | — |
+| **D3 元件效能** | 檢查 render / memo / bundle | chain `/performance-audit` |
+| **D4 UX 行為** | keyboard / focus / ARIA / animation / interaction canonical | chain `/ux-audit` |
+| **D5 視覺品質** | Layer A mechanical + Layer B AI judgement | Auto `npm run visual-audit -- --scope=component:{Name}` + chain `/visual-audit` |
+| D6 設計原則自檢(4 子維)| chain `principle-audit-protocol.md` 對該元件 scope scan | 合理 / 一致 / 無矛盾 / 完整;auto vs STOP 依判斷公式 |
+
+**執行步驟**:
+
+1. `npm run visual-audit -- --scope=component:{Name}`(D5 Layer A:WCAG / 幾何 assertion / retina screenshot)
+2. Layer A exit code != 0 → 停下修到 0
+3. Chain `/visual-audit`(D5 Layer B):讀 `snapshots/{Name}-*.png` 做 AI judgement
+4. Chain `/performance-audit --scope=component:{Name}`(D3)
+5. Chain `/ux-audit --scope=component:{Name}`(D4)
+6. **D6 真 scan**:讀 `.claude/skills/design-system-audit/references/principle-audit-protocol.md` 對該元件 + 其 spec 跨指的 kin specs 跑 4 子維(合理 / 一致 / 無矛盾 / 完整);先讀「常見 FP 記憶」節避免誤報
+7. 彙整 6 維 findings:**依 protocol 判斷公式 — 動 canonical substantive → STOP;對齊 canonical → AUTO**
+8. **Self-improvement capture**(強制):Phase 結束寫「新 FP / 新 pattern / user 糾正」—見 CLAUDE.md `# 治理 canonical` → Audit skill Phase F 節
+
+**為什麼 mandatory**:code / spec 對不夠;效能 / UX / 視覺三維各有歷史 bug(DatePicker 四邊不對稱、DropdownMenu 鍵盤不通、Badge 位置離譜、Rating 邊框、Carousel 箭頭壓文字、inline 物件 prop 造成 render 爆)。merge 前沒過 6 維 = 把 bug 帶進 DS。
+
+**合理跳過情境**(極少):純 spec.md 文字修正(無 tsx 改動)→ 視覺 / 效能 / UX 無變,可跳 Phase 4.5;但 tsx / token / cva / style 任一動 → 必跑全 6 維。
+
+### Phase 5 — 簽結(Checkpoint — STOP 點)
+
+全部打勾後,回報 user:
+- 「元件 {Name} 已過 quality gate,35 項全綠(含 Layer A visual)+ Layer B AI 視覺判斷通過」
+- 列出 Phase 1-4.5 各 section 打勾結果
+- 列出 `snapshots/report.json` 摘要(contrast / geometry violation 數 = 0)
+- 若任一 phase 有合理例外(documented 在 spec),列出例外清單
+
+**STOP 條件**:任一項不過 + 原因不清楚 → 停下問 user,不默默放行。**Phase 4.5 Layer A 有 violation 絕不放行**。
+
+## References
+
+- `references/checklist.md` — 完整 35 項 checklist(Spec 12 / Code 13 / Stories 6 / Ship 4 + 各項的 CLAUDE.md pointer)
+
+## 相關
+
+- `.claude/skills/design-system-audit/` — 本 skill focus 在單元件進 DS 的 gate;design-system-audit 是系統級 full-dim sweep(per design-system-audit SSOT),兩者互補
+- `.claude/skills/story-writing/` — Phase 3 story 深審可 chain 進去
+- `.claude/hooks/pre_edit_spec_check.sh`(retired;改靠 M3 mindset #3「改一處看三處」)— 編輯 tsx 前提醒讀 spec(session 級)

package/ds-canonical/skills/component-quality-gate/references/checklist.md

@@ -0,0 +1,79 @@
+# 元件完成 Checklist(完整 45 項)
+
+每個元件在進入 design-system 前必須逐項對照。這是品質閘門,不可跳過。
+
+**本 checklist 是純勾選表**——規則定義在各自的 canonical home,此處只做 checkbox + pointer。勾每項前先讀該 pointer 指向的章節。
+
+---
+
+## Phase 1 — Spec(`{name}.spec.md`)
+> 規則定義:`.claude/rules/spec-rules.md`
+
+- [ ] 元件定位一句話(是什麼 / 不是什麼)
+- [ ] 定位段落宣告實作基礎(基於 Radix X / cmdk / sonner / native / 自建 + 理由)
+- [ ] 每個 prop / variant / size / state 都有「何時用 / 何時不用」+ 理由
+- [ ] 互斥規則列出(哪些 props 不能並用)
+- [ ] 每個規則有「為什麼」(寫 rationale,不只結論)
+- [ ] 術語一致(同一概念不用兩種名稱)
+- [ ] 無視覺描述污染(「窄長形」「會變寬」等屬 story 不屬 spec)
+- [ ] 禁止事項(❌)列出常見誤用
+- [ ] 邊界案例覆蓋(disabled / loading / empty / dark mode / density / icon-only 適用時)
+- [ ] 「相關」section 指向近親元件 + SSOT pointer(reciprocal 成立)
+- [ ] 對標世界級 DS 的 7 個維度(何時用 / 分界 / 常見誤解 / 相關 / 空值 / 驗證時機 / a11y)
+- [ ] Layout Family 宣告(第一段必含——1/2/3/4 或「非 family,自己的結構」)
+
+---
+
+## Phase 2 — Code(`{name}.tsx`)
+> 規則定義:`.claude/rules/ui-development.md`(含「shadcn 元件規範」/「Tailwind 5 條核心」/「Token 命名 4 條硬規則」/「元件 Props 命名」)
+
+- [ ] 以 shadcn 為基底,forwardRef / displayName / asChild / ...props spread 齊全
+- [ ] variants 用 cva(),不條件拼字串(或 documented 例外:style-prop variant → object map / 結構性 variant → if-branches)
+- [ ] 同時 export 元件本體 + cva(供外部組合)
+- [ ] 保留 Radix `data-state` / `data-disabled` / `data-orientation` 等 attribute
+- [ ] 樣式優先用 `data-*` selector,而非自訂 class 模擬狀態
+- [ ] 無硬寫顏色 / 字體 / padding / radius / 高度——全用 design token
+- [ ] `cn()` 合併 class;Tailwind v4 CSS var 必用 `var(...)` 包覆
+- [ ] 未包 Provider(Tooltip / Theme / Toast 等由應用層設定)
+- [ ] Props 命名按「是什麼」而非「在哪裡」(icon / avatar / onDismiss,不 prefix / suffix)
+- [ ] 互動元素有 ARIA 屬性;icon-only 有 `aria-label`
+- [ ] 若屬 field-height family,`defaultVariants.size = 'md'`
+- [ ] 若修改 cva `defaultVariants`,已同步 spec / docblock / anatomy 三方(見 `.claude/skills/story-writing/references/anatomy-standard.md` → 高風險漂移點)
+- [ ] 未使用 shadcn compat alias(`bg-popover` / `text-muted-foreground` / `bg-accent` 等),改用我們的 direct token
+
+---
+
+## Phase 3 — Stories(展示 / 設計規格 / 設計原則)
+> 規則定義:`.claude/skills/story-writing/`(完整 workflow) + `.claude/rules/story-rules.md`(high-level)
+
+- [ ] 範例選擇原則的自我檢查清單全部打勾(詳見 `.claude/skills/story-writing/references/self-check.md`)
+- [ ] 設計規格 5 個 story 齊全(總覽 / 檢閱器 / 色彩對照 / 尺寸對照 / 狀態行為)
+- [ ] TOKEN_MAP / SIZE_SPECS 資料與 cva() 定義完全一致
+- [ ] Rule note 傳達原則(「為什麼」),不只結論(「是什麼」)
+- [ ] Storybook title 對齊命名規則;元件放對 `Components/` vs `Internal/`(見 `.claude/rules/story-rules.md` → 「Internal vs Components 三 test」)
+- [ ] 每個重要規則有正確範例;常見誤用有錯誤範例(對比呈現)
+
+---
+
+## Phase 4 — Ship(上線前)
+
+- [ ] `npm run storybook` 本地確認所有 stories 正常渲染
+- [ ] `npx tsc --noEmit` 無錯誤
+- [ ] Import 路徑正確(`@/design-system/...`)
+- [ ] 若為 internal primitive 或 shadcn passthrough,分類標註正確
+
+---
+
+## 簽結報告格式
+
+```
+元件 {Name} Quality Gate 結果:
+- Phase 1 Spec: 12/12 ✓
+- Phase 2 Code: 13/13 ✓  (cva defaultVariants = 'sm',已同步 spec+docblock+anatomy)
+- Phase 3 Stories: 6/6 ✓
+- Phase 4 Ship: 4/4 ✓
+Total: 35/35 ✓
+
+Documented 例外:
+- (無 / 或列出元件 spec 明文允許的偏離 + 理由)
+```