@qijenchen/design-system 0.1.0-beta.72 → 0.1.0-beta.74

package/dist/components/AppShell/_demo-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_demo-helpers.d.ts","sourceRoot":"","sources":["../../../src/components/AppShell/_demo-helpers.tsx"],"names":[],"mappings":"AAiDA,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;EAOX,CAAA;AAqBV,eAAO,MAAM,cAAc,+CAM1B,CAAA;AAID,eAAO,MAAM,UAAU,+CAuBtB,CAAA;AAQD,wBAAgB,WAAW,CAAC,EAC1B,gBAAgB,EAChB,qBAA4B,EAC5B,iBAAwB,GACzB,GAAE;IACD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAA;CACvB,2CAkCL;AAWD,wBAAgB,WAAW,4CAyB1B;AAQD,wBAAgB,YAAY,CAAC,EAAE,SAAS,EAAE,GAAE;IAAE,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAAO,2CAY/E;AASD,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,qBAA4B,GAC7B,EAAE;IACD,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC,2CAOA"}
+{"version":3,"file":"_demo-helpers.d.ts","sourceRoot":"","sources":["../../../src/components/AppShell/_demo-helpers.tsx"],"names":[],"mappings":"AAmDA,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;EAOX,CAAA;AAqBV,eAAO,MAAM,cAAc,+CAM1B,CAAA;AAID,eAAO,MAAM,UAAU,+CAuBtB,CAAA;AAQD,wBAAgB,WAAW,CAAC,EAC1B,gBAAgB,EAChB,qBAA4B,EAC5B,iBAAwB,GACzB,GAAE;IACD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,iBAAiB,CAAC,EAAE,OAAO,CAAA;CACvB,2CAwDL;AAWD,wBAAgB,WAAW,4CAyB1B;AAQD,wBAAgB,YAAY,CAAC,EAAE,SAAS,EAAE,GAAE;IAAE,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;CAAO,2CAY/E;AASD,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,qBAA4B,GAC7B,EAAE;IACD,KAAK,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAA;IAC1B;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;CAChC,2CAOA"}

package/ds-canonical/fork/governance.lock

@@ -92,7 +92,7 @@
     },
     {
       "file": "launchers/inject_fork_governance_preamble.sh",
-      "sha256": "eccf9dbb5ccd3a2e0bea6e3e225de2eb0f1634a6c12c349aab89439cf6e1fb89",
+      "sha256": "06bc80989782d15704a562cd9a7b2c13c063c89f1ee3a6bbfc807056825b20c7",
       "source": "template/.claude/hooks"
     },
     {
@@ -102,11 +102,115 @@
     },
     {
       "file": "manifest.json",
-      "sha256": "ee4f619b722c7d3a4f80dddb52dcee4bf900c7e6923945cd59d290d4a8236e5a"
+      "sha256": "627ff28351c0af0baca271bbcfa9812389979218ffa64c4d23b4abee7606429a"
     },
     {
       "file": "preamble.md",
       "sha256": "394299047d01f60bf1d9fd14a41e173b31d649068c62bd47352556beab9683e1"
+    },
+    {
+      "file": "skills/bug-fix-rhythm/SKILL.md",
+      "sha256": "4bca87df4f2777fe76f8e302698d373fb0ba60699922fb8b35c8aefae1c51ae0"
+    },
+    {
+      "file": "skills/code-quality-audit/SKILL.md",
+      "sha256": "fb65ebf0c72f7b475640f4861a1bfa2e9140727e2ff051fbd58f8348c0dc187d"
+    },
+    {
+      "file": "skills/delivery-handoff/references/flow-diagram.md",
+      "sha256": "b750d5117c92a1d0cde53283951a6848a1d3baa69ef6253cdc308a49720281df"
+    },
+    {
+      "file": "skills/delivery-handoff/references/handoff-template.md",
+      "sha256": "7985469e96766da72032c7aad84e00efbbe0223dcaf7eb6df680b2f31c4d6a6e"
+    },
+    {
+      "file": "skills/delivery-handoff/references/inventory-checklist.md",
+      "sha256": "7be9cbe37788183aad8032373e22f5ca63e05f94f4232784a79f20bc3d122b75"
+    },
+    {
+      "file": "skills/delivery-handoff/SKILL.md",
+      "sha256": "b3ba781857bed71c1bff537519b1e3858e5f115f25fb7c55967e5b147d360f79"
+    },
+    {
+      "file": "skills/performance-audit/SKILL.md",
+      "sha256": "7a77f4999b8d4bb6875c105050196fc3d7b451713da791531d186c37e593020b"
+    },
+    {
+      "file": "skills/product-ui-audit/references/audit-checks.md",
+      "sha256": "4dd879a1c983dedc29520762313b22e3b4d38cb395afe8ca1ecb43eb5e52ef83"
+    },
+    {
+      "file": "skills/product-ui-audit/references/common-misuses.md",
+      "sha256": "5afa85d18b559d1ccb182b50489bd1744968d07203558f8efbccf4444b46b942"
+    },
+    {
+      "file": "skills/product-ui-audit/references/report-template.md",
+      "sha256": "a847aba70e7c8f8cd620420f8d34d7f818070253ece5cdb1010bec16f71f5f57"
+    },
+    {
+      "file": "skills/product-ui-audit/SKILL.md",
+      "sha256": "cef077d82f906fd26d1507bbab00f5215a75583780aa893805d3018eef000a05"
+    },
+    {
+      "file": "skills/propose-options/SKILL.md",
+      "sha256": "3c0f8a8cef70506802ad67350ecde1ff5f633ddab21c22f3a4f91d923b9b9151"
+    },
+    {
+      "file": "skills/prototype/references/audit-checks.md",
+      "sha256": "6f17d6b4bc6ae94eedef8c39b68d4ab1baec92ef1035eeab462e17239c2803e3"
+    },
+    {
+      "file": "skills/prototype/references/benchmark-sources.md",
+      "sha256": "5bf8b038d2476c38c72cbb808f75e023655eaa7735d72c3e6071e199307e594b"
+    },
+    {
+      "file": "skills/prototype/references/checkpoints.md",
+      "sha256": "b37d72ad57392a6dbc75398bd9f9b92868346245530b8bddfbda4729744def33"
+    },
+    {
+      "file": "skills/prototype/references/evaluation-matrix.md",
+      "sha256": "575385e5250ecbe96068a94f71521e5d0bf9a1a33873c79500708ab620067be8"
+    },
+    {
+      "file": "skills/prototype/references/ooux-template.md",
+      "sha256": "7fda191d66844a765a67c4eae6c5c5cd54c45a2b40feff68fa54d33e24639486"
+    },
+    {
+      "file": "skills/prototype/references/proposal-template.md",
+      "sha256": "ec54bb412c255be03dd0269b708be8e8d4797f8bd58f4954a6dc52f955a9a8c6"
+    },
+    {
+      "file": "skills/prototype/SKILL.md",
+      "sha256": "21b6c91550233609274e772f245afa25bbc1aa338cc2a7a135a3577e3b16da77"
+    },
+    {
+      "file": "skills/scan-similar-bugs/SKILL.md",
+      "sha256": "79c5125f6d65d9d530c09ba2f19afe60174278448b122f4d4a66f9280c1312ca"
+    },
+    {
+      "file": "skills/ux-audit/SKILL.md",
+      "sha256": "28673c2f0207a0fa37f262ae8276d2b120b61c3329ada4d900fd6cdca42e35ed"
+    },
+    {
+      "file": "skills/visual-audit/output/.gitkeep",
+      "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+    },
+    {
+      "file": "skills/visual-audit/references/audit-architecture.md",
+      "sha256": "48c931ad559c1e37ecebd08d289509692c79d9c92d2574f65e89bf286b7c95cf"
+    },
+    {
+      "file": "skills/visual-audit/references/visual-checklist.md",
+      "sha256": "1d2d366122227b0665135c9a9f3138385d369996ad870ffa1c58402753b22bd0"
+    },
+    {
+      "file": "skills/visual-audit/references/world-class-benchmarks.md",
+      "sha256": "bdb46cb8d1f164c141e0e7092932a787674fe5bd4defe88ad2ca91d2cfb76bdf"
+    },
+    {
+      "file": "skills/visual-audit/SKILL.md",
+      "sha256": "0af4957c5ab08f8c04bbc944900ae45b719eed879e667de1fd139392e57c4525"
     }
   ]
 }

package/ds-canonical/fork/launchers/inject_fork_governance_preamble.sh

@@ -24,6 +24,14 @@ if [ ! -f "$PREAMBLE" ] && [ -f "$PD/package.json" ]; then
   ( cd "$PD" && npm install @qijenchen/design-system@beta @qijenchen/storybook-config@beta --legacy-peer-deps --no-audit --no-fund >/dev/null 2>&1 ) || true
 fi
 
+# (1b) 自我修復 skills/commands/agents:本體在但 .claude/skills 尚未送達(C-prime 之前的舊 fork / 尚未 sync-all)→ 從 npm 補。
+# ⚠️ Claude Code 在 SessionStart hook 跑「之前」就掃過 .claude/skills → 補的 skill「下個 session」才可叫用(self-heal,非當場;
+#    全新 use-template/fork 因 committed scaffold 不走此路、session-1 即有)。fail-open:任何錯都不阻擋。
+if [ -f "$PREAMBLE" ] && [ ! -e "$PD/.claude/skills/prototype" ] && [ -f "$PD/scripts/refresh-fork-launchers.mjs" ]; then
+  echo "💡 偵測 .claude/skills 尚未送達 → 從 npm 自我修復(下個 session 可叫用 /prototype 等 skill)…" >&2
+  ( cd "$PD" && node scripts/refresh-fork-launchers.mjs >/dev/null 2>&1 ) || true
+fi
+
 # (2) 本體在(本機持久 / 剛裝完)→ 讀 + 經 additionalContext 注入設計紀律
 if [ -f "$PREAMBLE" ]; then
   CONTENT=$(cat "$PREAMBLE" 2>/dev/null)

package/ds-canonical/fork/manifest.json

@@ -75,5 +75,19 @@
         "bucket": "REPLACE"
       }
     ]
-  }
+  },
+  "skills": [
+    "bug-fix-rhythm",
+    "code-quality-audit",
+    "delivery-handoff",
+    "performance-audit",
+    "product-ui-audit",
+    "propose-options",
+    "prototype",
+    "scan-similar-bugs",
+    "ux-audit",
+    "visual-audit"
+  ],
+  "commands": [],
+  "agents": []
 }

package/ds-canonical/fork/skills/bug-fix-rhythm/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: bug-fix-rhythm
+description: Batch-end-verify rhythm + parallel tool batch + user-listed N-rule MUST-ALL + claim runtime verify. Invoke when entering multi-fix session 或 user 列 numbered rules. Replaces M32(c)(d)(h1)(h2) sub-invariants(2026-05-12 split per Knowledge-Prune Checkpoint 2)。
+---
+
+> **⚠️ Fork 工具註記(build 自動加)**:本 skill 提到的 `scripts/*.mjs` 或非標準 `npm run <audit>` 是 **DS-author repo 的機械工具,未隨 fork 套件附帶**(Claude Code 不掃 node_modules,fork 也無這些 executor + dep)。你的 product fork 用本 skill 的**方法論**(human / AI judgment)+ 既有 committed governance hook 的機械強制即可;要 mechanical 腳本層(截圖 / CI gate)請自行設置對應工具,或把該檢查 PR 回 DS repo 跑。
+
+# /bug-fix-rhythm — 多 fix session 的 rhythm canonical
+
+**目的**:當 session 有 ≥ 2 fixes(常見 visual bug session / user 列 N 條 numbered 規則),走 batch-end-verify rhythm,而非 per-fix verify cycle waste。**M32 split 後 (c)(d)(h1)(h2) 的 home**。
+
+**對齊**:
+- CLAUDE.md mindset #6「大原則吸收瑣碎」+ M14「對話結論 AUTO integrate」
+- Bazel incremental-build / GitHub Actions matrix-batch idiom(per-step incremental = waste,batch-end = canonical)
+- Anthropic Claude Code prompt engineering「single-message multi-tool-call」canonical
+- Toyota TPS jidoka(per-station per-item verify,不可 skip 任何 item)
+
+## When to invoke
+
+**強制 auto-chain**:
+- multi-issue session 內 ≥ 2 fix 待處理(visual / behavior / code 任 mix)
+- user 列 numbered N 條規則(「規則 1...規則 N」/「Q1...QN」/ image 標 1234)→ 視作 **MUST-ALL checklist**
+
+**手動 invoke**:user 明言「批 fix」「一次做完」「跑完再驗」「列規則」
+
+**不 invoke**(對齊 Anthropic Best Practice 小修 skip):
+- 單一 surgical fix(無 numbered rule + 無 cross-component)— per-fix verify 即可
+- pure refactor / typo / import cleanup
+- spec.md docs only
+
+## Non-goals
+
+- 不擴展到「audit full-dim」(那是 `/design-system-audit`)
+- 不取代 `/scan-similar-bugs`(那是 fix 後 root-pattern scan;本 skill 是 fix-過程 rhythm)
+- 不動 canonical 語意(走 audit-vs-execute STOP 提議)
+
+---
+
+## Workflow(4 phases)
+
+### Phase 0 — Intake & MUST-ALL checklist 化(原 M32(h1))
+
+讀 user message:
+
+**If user 列 numbered rules**(「規則 1: X / 規則 2: Y / ...」/「Q1 / Q2 / ...」/ image 標號 / bulleted list)→ 抽出 **MUST-ALL checklist**:
+
+```markdown
+## MUST-ALL checklist(per-rule 不可下放)
+- [ ] 規則 1: <verbatim user wording> — 對應 fix: <target>
+- [ ] 規則 2: <verbatim user wording> — 對應 fix: <target>
+- ...
+- [ ] 規則 N: <verbatim user wording> — 對應 fix: <target>
+```
+
+**禁止**:
+- 把 N 條視作 ranked-priority(「先修 1-3,4 之後再說」)
+- 漏 N 條中第 K 條當「做完」report
+- 改寫 user wording 為自己 paraphrase(verbatim 保留)
+
+### Phase 1 — Parallel tool batch(原 M32(d))
+
+Read / Grep / Glob 多檔需求 → **single message multi-tool-call**:
+
+```
+✓ Good: 1 message with [Read A, Read B, Read C, Grep D, Grep E]  (~2s)
+✗ Bad : 5 messages sequential                                       (~10s)
+```
+
+**Heuristic**:任何 tool call 之間**無 dependency**(後一個不需前一個結果) → 必 parallel。
+
+對齊 Anthropic Claude Code best practice:「Maximize use of parallel tool calls where possible」。
+
+### Phase 2 — Batch fix(原 M32(c))
+
+每 fix 用 Edit(不 Write,降風險)。**禁止 per-fix tsc / audit cycle**:
+
+```
+✓ Good: [Edit A] [Edit B] [Edit C] [Edit D] → final tsc + audit + visual (once)
+✗ Bad : [Edit A → tsc → audit → visual] [Edit B → tsc → audit → visual] ...  (5× waste)
+```
+
+例外:某 fix 確實依賴前一 fix 的 type 結果 → sequential 必要時可,但 verify cycle 仍 batch-end-only。
+
+### ⚠️ Checkpoint 1 — Substantive vs surgical 分流
+
+每 fix 落地前 inline 判斷:
+
+- **Surgical**(CLAUDE.md「Scope classifier — Surgical visual bug」):pixel / token / class adjustment, no new SSOT / API / cross-component → AUTO ship 此 fix
+- **Substantive**(audit-vs-execute 分權):新 SSOT / 新 prop / 新 canonical meaning / cross-component semantic → **STOP propose**,等 user verbatim 拍板才 ship
+
+混合 batch:surgical 部分 ship,substantive 部分 propose。**禁止**:substantive 偷渡進 surgical batch。
+
+### Phase 3 — Final batch-end verify(原 M32(c)(h2))
+
+全 fix 完成後**一次性**驗證:
+
+```bash
+npx tsc -b                                    # type
+npm run hooks:test                            # invariant
+node scripts/visual-audit-<target>.mjs        # pixel-quantified per M32(a)
+```
+
+**MUST-ALL re-check**(per Phase 0 checklist):
+
+```markdown
+## MUST-ALL verify report
+- [x] 規則 1: ✓ verified via <tsc | audit script | pixel measurement | playwright>
+- [x] 規則 2: ✓ verified via ...
+- ...
+- [x] 規則 N: ✓ verified via ...
+```
+
+**禁止**(原 M32(h2) claim runtime verify):
+- 寫「不會有問題」「無 side-effect」「verified」「都實作完了」**沒**對應 verify trace
+- code-reading 推論當「verified」
+- ranked-priority 漏 N 條中第 K 條當「做完」
+
+若某條無法 runtime verify → 明撤回 **「規則 K:未驗證,推論而已,user 真機 verify needed」**,不可假宣告。
+
+對齊 M20 claim-verify gap(M20 是 stop-hook 機制;本 skill Phase 3 是 active workflow side)。
+
+---
+
+## ⚠️ Checkpoints(禁止跳)
+
+### Checkpoint 1 — Phase 2 surgical vs substantive(見上)
+
+### Checkpoint 2 — Phase 3 verify trace 缺漏
+若 MUST-ALL N 條有 K 條無 verify trace → STOP report,先補 verify 再報 user。
+
+### Checkpoint 3 — User-listed rule wording 改寫
+若 Phase 0 抽 checklist 時改了 user wording → STOP,重抓 verbatim。
+
+---
+
+## 與其他 skill / hook 的關係
+
+| Tool | Scope | 跟本 skill 關係 |
+|---|---|---|
+| `/scan-similar-bugs` | fix 後 DS-wide root-pattern scan | 本 skill batch-end-verify 後**才** chain `/scan-similar-bugs` |
+| `/visual-audit` | 單次視覺對齊 | Phase 3 sub-step,本 skill 包它 |
+| `/component-quality-gate` | stakeholder gate | 不重疊(stakeholder vs daily bug fix) |
+| `stop_self_audit.sh`(hook) | claim-verify gap 攔 | 本 skill Phase 3 是 active side;hook 是 passive trip-wire |
+| `check_pixel_quantified_audit.sh`(hook) | M32(a) audit script 必 pixel | 本 skill Phase 3 跑該 audit |
+
+**3 層 防線**:
+- **本 skill**(active workflow):MUST-ALL checklist + batch-end-verify rhythm
+- **stop_self_audit.sh / check_codex_collab_5step.sh**(passive hook):claim-verify gap 攔
+- **M20 / M32(a)**(meta-rule):上游 invariant
+
+---
+
+## 世界級對照
+
+- **Bazel `bazel test //...`**:全 target 並行 + final report,而非 per-target sequential
+- **GitHub Actions matrix**:N 個 job 並行,final aggregate verdict
+- **Toyota TPS jidoka**:每 station per-item verify,**但** verify 是 station-end 而非 in-progress checkpoint
+- **Anthropic Claude Code prompt eng**:「Maximize use of parallel tool calls」
+- **Stripe / Linear engineering blog**:「batch deploy + single canary verify」over「per-PR canary」
+
+---
+
+## Self-improvement capture
+
+每次 invoke 完寫:
+- (a) Phase 0 抽 MUST-ALL 時 user wording 是否變形?
+- (b) Phase 2 surgical/substantive 分流是否準確?(false-positive 偷渡記錄)
+- (c) Phase 3 verify trace 有沒有「runtime verify needed」的條目漏標?
+- (d) 新發現 numbered-rule pattern → 加進 Phase 0 抽取 heuristic
+
+回填本 SKILL.md 或 references/。
+
+---
+
+## 歷史 absorbed failures(M32 split 來源)
+
+2026-05-12 4 prior failures absorbed by M32 → split 後本 skill 承接 (c)(d)(h1)(h2):
+1. cell-align audit「Δ=0 ALL PASS」但 user 抓 SKU/Qty 視覺垂直置中於 88px 高 row(audit 沒驗 Field collapse)
+2. divider 2px audit「ALL PASS」但 pinned panel 邊仍 2px(audit 沒驗 pixel overlap)
+3. breadcrumb tooltip audit「ALL PASS」但 user 連抓 hover 不 fire(audit 沒驗 Portal DOM bounding rect)
+4. row-alignment audit「Δ=0 ALL PASS」(attr 對齊,Field collapse 沒抓)
+
+具體 M32(a) pixel-quantified rule 仍在 meta-patterns.md,本 skill 是其 workflow side。

package/ds-canonical/fork/skills/code-quality-audit/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: code-quality-audit
+description: Clean code 量化稽核 — `any` 使用 / dead export / file size / long function / circular dep / magic number。補 `/design-system-audit` 只管「design canonical」的缺口。Invoke via /code-quality-audit scope=all(release / 季度)OR scope=changed(daily)OR scope=component:X(focused)。Auto-chain by `/design-system-audit --deep` Dim 27 + `/component-quality-gate` Ship phase + `/new-component` Phase 4.5。
+---
+
+> **⚠️ Fork 工具註記(build 自動加)**:本 skill 提到的 `scripts/*.mjs` 或非標準 `npm run <audit>` 是 **DS-author repo 的機械工具,未隨 fork 套件附帶**(Claude Code 不掃 node_modules,fork 也無這些 executor + dep)。你的 product fork 用本 skill 的**方法論**(human / AI judgment)+ 既有 committed governance hook 的機械強制即可;要 mechanical 腳本層(截圖 / CI gate)請自行設置對應工具,或把該檢查 PR 回 DS repo 跑。
+
+# Code Quality Audit — Clean Code 量化稽核
+
+Scope:**tsx / ts code hygiene**,跟 design canonical 正交。
+
+## 為什麼要這 skill
+
+`/design-system-audit`(全 dim per design-system-audit SSOT)管 design / spec / canonical correctness。但 **clean code 面向**(`any` 濫用 / dead export / 函式爆長 / circular dep / 檔案超標)**無任何 dim 覆蓋**。每次建元件 / audit / ship 都該跑這層。
+
+## 6 個 check
+
+| # | Check | Severity | 如何判定 |
+|---|-------|---------|---------|
+| 1 | `any` 使用 | P0 | grep `: any` / `as any` / `<any>` / `any[]` / `Record<X, any>`;支援 `// any-allow: {rationale}` 逃生口(同行或上一行) |
+| 2 | File size(.tsx)| P0 > 800 / P1 > 500 | `wc -l`;budget 500 / transition cap 800;spec 同 `check_file_size_budget.sh` policy |
+| 3 | Long function | P1 > 80 行 | naive:`function`/`const` 宣告到 matching `}` indent 行距 |
+| 4 | Dead export | P1 | `export` 名稱在其他 src/ 檔無出現;exempt `*Props/Options/Config/Args/Context/Variants/Value` 型別 API 慣例 |
+| 5 | Circular dep | P0 | DFS import graph,找 cycle |
+| 6 | Magic number | P1 | 覆蓋不完整 → 由 token 防線(`lib/_token_hygiene.sh` + `check_opacity_token_usage.sh`)層負責(primitive color / shadow / Tailwind v4 `[--foo]`);本 skill 不重複 |
+
+## When to run
+
+- **Daily**:`/code-quality-audit --scope=changed`(git diff)
+- **Component ship**:`/component-quality-gate` Ship phase auto-chain
+- **New component**:`/new-component` Phase 4.5 auto-chain
+- **Release / 季度**:`/code-quality-audit --scope=all`
+- **Focus one component**:`/code-quality-audit --scope=component:<Name>`
+- **CI gate**:`node scripts/code-quality-audit.mjs --check`(P0 violation → exit 1)
+
+## Workflow
+
+1. Run `node scripts/code-quality-audit.mjs [--scope=<scope>]`
+2. Triage findings into P0 / P1 / P2
+3. Auto-fix trivial(unused imports,trivial `any` casts with obvious type)
+4. STOP for user decision on:
+   - File-size P0(大 component architectural split)
+   - Circular dep(需設計層面重組)
+   - 無法 auto-type 的 `any`(需 design judgment 訂 proper type)
+
+## 禁止
+
+- 禁 silent 吞 `any`(必加 `// any-allow: {rationale}`)
+- 禁把 dead export 直接刪(可能是 planned API surface);flag → user 決策
+- 禁把 long function 硬拆(拆錯比爆長還糟);只提議,user sign-off
+
+## Integration points
+
+| Skill / Hook | How |
+|---|---|
+| `/design-system-audit` Dim 27 | `--deep` 必 chain 本 skill scope=all |
+| `/component-quality-gate` Ship | chain 本 skill scope=component:{Name} |
+| `/new-component` Phase 4.5 | 元件建完必跑 scope=component:{Name} |
+| Hook `check_code_quality.sh` | PostToolUse Edit/Write on src/ — 只跑 any + file-size(quick) |
+
+## References
+
+- `scripts/code-quality-audit.mjs` — 實作
+- `.claude/hooks/check_code_quality.sh` — per-edit lite check
+- 相關:token 防線 `lib/_token_hygiene.sh` + `check_opacity_token_usage.sh`(正交 — token 紀律 vs code 紀律)

package/ds-canonical/fork/skills/delivery-handoff/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: delivery-handoff
+description: Generate stakeholder-ready handoff documentation when a product / feature is confirmed final. Produces Storybook handoff page + UI flow diagram + component usage inventory + token consumption report + a11y checklist + per-screen spec — a Figma-like inspectable delivery package. Invoke via /delivery-handoff when user says「要交付」「handoff」「交付文件」「給 X 團隊的文件」「產品確認要上線了」. **只在產品確認 final 後才 invoke**,非 prototype 階段。
+---
+
+# Delivery Handoff Workflow
+
+Purpose: 產品 / feature 通過 prototype → audit → stakeholder 決策後確認 final,需要產 **Figma-like inspectable handoff documentation** 給工程 / PM / QA / 其他 stakeholder。
+
+本 skill **不是** prototype 階段文件(那是 `/prototype` 的 notes.md),而是**正式交付包**。
+
+## When to run
+
+**明確觸發**:
+- User 說「要交付」「handoff」「交付文件」「給 X 團隊的文件」
+- User 說「產品確認要上線了」「final 了做 handoff」「給工程交接」
+- Final decision 已下 + product-ui-audit P0 都修完
+
+**不觸發**:
+- Prototype 階段(走 `/prototype`,產 exploration notes)
+- Audit 階段(走 `/product-ui-audit`)
+- DS 本身的 spec 維護(不走任何 skill,直接在 `.spec.md` 編)
+- 要跑 audit 檢查 DS 用對不對 → `/product-ui-audit`
+
+## 生態位
+
+```
+  /prototype           → exploration + shortlist
+  /product-ui-audit    → QA gate
+  [stakeholder decides final]
+  [P0 fixed, P1 resolved]
+  /delivery-handoff    ← 本 skill,只在 final confirmed 後
+```
+
+## Preconditions
+
+- 產品 / feature 已 final(stakeholder 書面或對話確認)
+- `/product-ui-audit` Zero P0(必要)/ P1 有計畫 resolve(建議)
+- 代碼已 merge 或即將 merge 到 main branch
+- 有明確 **target audience**(給工程? 給 PM? 給設計 review? 給跨團隊交接?)— AI 在 Phase 0 clarify
+
+---
+
+## 5-Phase Workflow
+
+### Phase 0 — Scope & audience
+
+**clarify with user**:
+1. 交付**哪個 feature**?(single screen? full flow? 整個 module?)
+2. **給誰**?
+   - 工程團隊(實作參考 / QA test case)
+   - PM / BA(業務理解 / 邊界 case)
+   - 設計 review(世界級評估)
+   - 跨團隊(onboarding 他們使用)
+3. **format 需求**:
+   - Storybook 原生頁(最推薦)
+   - Markdown 可 export PDF
+   - Mermaid diagram(UI flow)
+   - Screenshot / mockup 用 Storybook render
+
+### Phase 1 — Inventory 生成
+
+scan 目標 feature 的 code,自動 inventory:
+
+1. **Component 清單**(哪些 DS 元件被此 feature 消費):
+   ```
+   | Component | Count | Consumer files |
+   |-----------|-------|----------------|
+   | Button    | 12    | Checkout.tsx, Summary.tsx, ... |
+   | Dialog    | 2     | Confirm.tsx, Edit.tsx |
+   | Empty     | 1     | NoItems.tsx |
+   ```
+
+2. **Token 使用報告**:
+   ```
+   | Token | Usage | Files |
+   |-------|-------|-------|
+   | --primary | 8 hits | ... |
+   | --fg-secondary | 14 hits | ... |
+   | --error | 3 hits | ... |
+   ```
+
+3. **Layout primitives 消費**: Empty / item-layout / overlay-surface / ScrollArea / AspectRatio 各幾次。
+
+4. **A11y checklist**(先掃再人工 review):
+   - aria-label 齊全
+   - role / keyboard
+   - Dialog title
+   - color contrast(此層 AI 報 visible,人工 review 判 final)
+
+### Phase 2 — UI flow 圖生成
+
+用 **Mermaid** 產 flow(Storybook 支援 render,也可 export PDF)。
+
+範本:
+
+```mermaid
+flowchart TD
+  Start([進入 Checkout]) --> Review[結帳 Review]
+  Review -->|修改| Edit[編輯 Cart Dialog]
+  Edit --> Review
+  Review -->|確認| Payment[付款方式 Step]
+  Payment -->|信用卡| Card[Card Form]
+  Payment -->|轉帳| Bank[Bank Instructions]
+  Card --> Confirm[確認 Dialog]
+  Bank --> Confirm
+  Confirm -->|確定| Success([訂單成立])
+  Confirm -->|取消| Review
+```
+
+AI 根據 code(route / onClick / navigation)auto-generate,user review 後微調。
+
+### Phase 3 — Per-screen spec sheet
+
+每個 screen / modal / flow step 一頁 spec(Storybook 的 Handoff story,或 Markdown 章節):
+
+```markdown
+## Screen: Checkout Review
+
+**Storybook**: `Features/Checkout/Review`
+**File**: `src/app/features/checkout/Review.tsx`
+
+### 用途
+使用者進入結帳後,第一屏預覽購物車 + 小計 + 折扣碼輸入。
+
+### 主要元件
+- DataTable(訂單 items)
+- Input(折扣碼)
+- Button(套用)
+- Dialog(編輯 item 彈出)
+- Empty(購物車空狀態)
+
+### States
+- **default**: 載入後正常顯示(≥1 item)
+- **empty**: 購物車無 item — 顯示 Empty 元件 + 「回去繼續購物」CTA
+- **error**: 折扣碼無效 — Input error state + Alert 說明
+
+### Interactions
+- 點擊 item → open Edit Dialog
+- 輸入 discount → debounce 500ms → auto-validate
+- 按 Apply → post /discount API
+
+### A11y
+- ✓ 所有 icon-only 有 aria-label
+- ✓ Dialog 有 title + description
+- ✓ keyboard 可 tab 所有互動
+- ✓ color contrast 通過 WCAG AA
+
+### 邊界 case
+- 折扣碼已套用:顯示 "已套用 {code}",Apply Button 變 Clear
+- 網路錯誤:顯示 Alert + retry button
+- 折扣超過總額:capped 折扣 = 總額,顯示說明
+```
+
+### Phase 4 — Handoff Storybook page
+
+在 Storybook 建立 `Features/{Feature}/Handoff` page,內含:
+
+- **Overview**: feature 一句話重述
+- **UI Flow**: Mermaid diagram(Storybook 支援 render)
+- **Inventory**: 元件 / token / a11y 報告
+- **Screens**: 每個 screen 可點進去的 story link + inline preview
+- **Spec table**: per-screen spec 嵌入
+
+Storybook title: `Features/{FeatureName}/Handoff`
+
+此 page 就是「Figma-like 的 inspectable 交付」— stakeholder 打開就看到全景。
+
+### ⚠️ Checkpoint — User review handoff package
+
+Phase 4 產出後 pause,讓 user review:
+
+```
+📦 Handoff Package Ready
+
+Scope: {feature}
+Audience: {engineering / PM / designer / cross-team}
+Package:
+- Storybook page: Features/{Feature}/Handoff
+- Inventory: {N components / M tokens}
+- UI Flow: Mermaid diagram ({N nodes})
+- Spec sheets: {N screens}
+- A11y checklist: {N passed / M needs review}
+
+Export formats:
+- Storybook URL: {link}
+- Markdown(可 export PDF): {path}
+
+請 review:
+(a) 通過,準備 share 給 {audience}
+(b) 需要修改: ...
+(c) 還缺 ... 補齊
+(d) Audience 換人,調整語氣 / 深度
+```
+
+---
+
+## 世界級 handoff 標準(reference)
+
+本 skill 對標:
+- **Figma Dev Mode** — inspectable 元件 + token + spacing
+- **Zeplin** — per-screen spec + asset export
+- **Shopify Polaris Pattern pages** — 完整 flow + usage + edge cases
+- **Material Design Showcase** — UI + spec + code sample 三欄
+
+我們的 Storybook handoff page 整合上述 3 個 tool 的優勢到一頁。
+
+---
+
+## Non-goals
+
+- 不替代工程 code review(本 skill 是 **設計 handoff**,不是 code 品質審核)
+- 不寫實作 / fix bug(已經 audit 過,final 了才 invoke 本 skill)
+- 不生成業務需求文件(那是 PM 職責)
+- 不管 release scheduling / branching strategy(那是 DevOps)
+
+## Common failure modes
+
+- **Audience 不清**: user 說「要 handoff」但沒說給誰 → Phase 0 必 clarify,否則 format 錯
+- **UI flow 過度簡化**: flow 圖少 error path / loading / edge case → 讓 handoff 失真
+- **Component inventory 漏掉 hidden consumption**:e.g., 內部某 function 呼叫 Toast → 需 grep 所有 imports
+- **A11y checklist 自動判 pass**:checklist 只能「visible hits」,color contrast / keyboard 實測需人工
+- **Spec sheet 寫成 code comment 複製**:spec 應該是 design 語言而非 code 描述,翻譯為 UX 詞彙
+
+## References
+
+- [references/handoff-template.md](references/handoff-template.md) — Storybook Handoff page 結構 + Markdown spec 範本
+- [references/flow-diagram.md](references/flow-diagram.md) — Mermaid UI flow 指引 + 世界級 reference
+- [references/inventory-checklist.md](references/inventory-checklist.md) — 元件 / token / a11y 清單 + grep pattern