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

package/ds-canonical/rules/story-rules.md

@@ -0,0 +1,56 @@
+---
+paths:
+  - "**/*.stories.tsx"
+---
+
+# Story 規則(path-scoped)
+
+僅在編 `*.stories.tsx`(showcase / anatomy / principles 三層)時 load。
+**完整 workflow → `/story-writing` skill**。
+
+## 三層定位
+
+| 層 | 檔案 | Canonical | Hook | Audit Dim |
+|---|------|-----------|------|-----------|
+| 1 展示 | `*.stories.tsx` | trait-based v2 | `check_story_category.sh` | 29 |
+| 2 設計規格 | `*.anatomy.stories.tsx` | 6-canonical(Overview / Inspector / ColorMatrix / SizeMatrix / StateBehavior / Accessibility)| `check_story_anatomy.sh` | 13 |
+| 3 設計原則 | `*.principles.stories.tsx` | Polaris-aligned ≥ 2 of {WhenToUse / WhenNotToUse / Vs*Rule / ContentGuidelines};v3 預設整合 `UsageGuidance` 單一 export(Polaris/Material/Ant 共識) | `check_principles_canonical.sh` | 30 |
+
+## Title 命名
+
+`Design System/{Tokens|Patterns|Components|Internal}/{Name}/{展示|設計規格|設計原則}`。
+
+第一層英 / PascalCase / 子頁中文 / 子頁前不加元件名(❌ `MenuItem 展示` → ✅ `展示`)。
+
+**Internal vs Components 三 test**:(1) 有預設視覺?(2) 直接 `<X>` 有視覺?(3) 所有消費者都包 wrapper?三題傾向 Internal → `Internal/`。**例外:compound-component public API**(`Dialog.Root/Trigger/Content` / `Field + FieldLabel + FieldError + FieldDescription` 等定義 sub-component 給 consumer 拼的 documented composition pattern)豁免三-test — 它**定義** sub-components,不是被 wrap 的零件。對齊 Radix Dialog / MUI FormControl + InputLabel + FormHelperText / Mantine Input.Wrapper compound idiom。
+
+**Title canonical 4-part exemption**(2026-05-16 codified):**Tokens / Patterns** 為 single-file showcase(無 anatomy/principles 對應)→ 3-part title 是 intentional convention(`Design System/Tokens/{Name}` / `Design System/Patterns/{Name}`),不是違反。**Components / Internal** 必 4-part(`/{Name}/{展示|設計規格|設計原則}`)因有 3 stories 對應 file 需 subpage 分流。
+
+**MenuItem-as-listbox-child 鍵盤 delegation 例外**(2026-05-16 codified per Combobox spec.md L130-142):MenuItem `<div role="option">` 不需自帶 Enter/Space handler — 由 parent listbox(Combobox / SelectMenu / DropdownMenu)的 hidden native `<select>` handle 鍵盤導覽(對齊 Material/Atlassian/GitHub mixed-control「單 native tab stop + 多 mouse click surface」 canonical)。MenuItem 為 building block 不該重複 handler。
+
+**Story `name:` field 必中文人話**(no auto-compile 豁免):`compile-stories.mjs` auto-generate 已產生中文 name(如 `'元件總覽'`)。Manually-written stories `name:` 用純英文 implementation label(`'Default'` / `'Pressed'` / `'SizeMatrix'`)= drift,**必 humanize 中文**。Export const 維持 PascalCase(英)為 code identifier,**`name:` field 為 reader-facing 必中文**(術語例外:`FAQ` / 元件名 `Avatar/Tooltip` 等專有可保英)。
+
+## 範例最高準則
+
+精簡幹練、0 重複、每 story earn its existence(audit Dim 24/25/28/29/30 抓)。
+
+**Earn-existence 2 test**:(a) 教別 story 沒教的原則?(b) 移除後 spec 理解 degrade?兩題皆 NO → retire。
+
+**Production-grade composition fidelity**(2026-05-20 codify per codex anti-drift D2):
+- 寫 stories wrap **既有 primitive**(`<Sidebar>` / `<ChromeHeader>` / `<Dialog>` / `<DataTable>` 等)時,**必先 grep 該 primitive `*.stories.tsx` 找「完整佈局」類 story**(eg. `sidebar.stories.tsx IconCollapse` / `data-table.stories.tsx WithBulkActions`),Read 其 helper(`WorkspaceBrand` / `UserFooter` / `PageContent` / toolbar pattern 等)**當 baseline reference**
+- 禁直接寫 simplified mock(`<SidebarHeader><span>name</span>` / `<SidebarMenuButton><Icon className="size-4">` / `<ChromeHeader><span flex-1>title</span>`)= drift
+- 標 `// @story-baseline: <path>#<StoryName>` 在 stories.tsx 檔頭,reference 哪個 baseline。Hook `check_story_invariants.sh R7` 攔 drift(2026-05-20 ship)。
+
+**拆分原則**(對齊 Polaris / Carbon / Storybook):
+- 不同 affordance 必分(IconOnly / FullWidth)
+- AllVariants & AllSizes 對照各 1
+- 同 affordance 內 prop variations 用 Controls 不另開(❌ `WithStartIcon`+`WithEndIcon` → ✓ `WithIcon` grid)
+- Compound 有 new constraint 才分
+
+**展示 v2 trait-based**:spec.md frontmatter `traits:` array → required core stories 衍生 + hook `check_story_category.sh` 攔。
+
+**Principles canonical**(Polaris-aligned):universal core ≥ 2 of `WhenToUse`/`WhenNotToUse`/`Vs*Rule`/`ContentGuidelines` + hook 攔。SSOT → `/story-writing` skill `references/category-templates.md`。
+
+## 禁止
+
+❌ 佔位符 / 抽象代號 / 極端不現實 / 視覺符號 / spec 內部代號。詳 → `/story-writing` skill。

package/ds-canonical/rules/ui-development.md

@@ -0,0 +1,87 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.ts"
+  - "packages/design-system/src/**"
+  - "src/explorations/**"
+  - "src/app/**"
+---
+
+# UI 開發 + Tailwind + Token + Props 命名規則(path-scoped)
+
+僅在編 `.tsx` / `.ts` 或 DS / explorations / app code 時 load。
+
+## Public component vs Internal primitive canonical(SSOT,2026-05-23 user 永久拍板)
+
+**Public component**(consumer-facing):**end-user app 直接寫 `<X />` 就能 render 出有意義的 UI**,不需要再 wrap / 不需要再 compose 其他 DS 元件。Examples:`<Button>` / `<Avatar>` / `<Dialog>` / `<DataTable>` / `<MenuItem>` / `<ActionBar>` / `<ResizeHandle>`。
+
+**Internal primitive**:**供 DS 內部其他元件 wrap / compose 用**。end-user app 直接 render 無 functioning UI,或必須先 import 多個 DS 元件一起組才有結果。Examples:`<ChromeHeader>`(Sidebar 內部消費)/ `<SurfaceHeader/Body/Footer>`(Dialog 內部)/ `useOverflowItems` hook / `<ItemIcon>` / `<ItemAvatar>`(MenuItem 內部 slot)。
+
+**Mechanical test(verifiable)**:
+- 問:end-user app `<X />`(空 children / 無 props / 無 wrapper context)render → 有 functioning visible UI 嗎?
+  - YES → **public**
+  - NO → **internal**
+
+**Folder + storybook canonical**:
+- public:`components/<Name>/` OR `patterns/<name>/`(frontmatter 無 `internal: true`),storybook title `Design System/Components/<Name>/...` OR `Design System/Patterns/<Name>`
+- internal:`components/Internal/<Name>/` OR `patterns/<name>/`(frontmatter `internal: true`),storybook title `Design System/Internal/<Name>/...` OR `Design System/Internal Patterns/<Name>`(end-user 設計師 default 過濾掉,DS contributor 看 reference 用)
+- export jsDoc 加 `@internal` marker(IDE intellisense 警示 end-user)
+
+**對齊世界級**:Polaris 「Building blocks」(public) vs「layout primitives」(internal)/ Material UI `@mui/material`(public)vs `@mui/utils` `@mui/system`(internal hooks/primitives)/ Atlassian `@atlaskit/<component>`(public)vs internal `<unstyled>` primitives / Carbon turnkey components + internal utilities / Apple HIG「Presented controls」vs「implementation primitives」 共識。
+
+## 建立 UI 前必讀
+
+**先 `ls packages/design-system/src/{components,patterns}/`**。必查 spec:Tokens(`tokens/{color|typography|density|uiSize|layoutSpace|elevation|radius}/*.spec.md`)/ Row + List item(`item-anatomy.spec.md` Family 1+2 SSOT)/ Action bar / Overflow / Overlay(`patterns/{action-bar,horizontal-overflow,overlay-surface}/*.spec.md`)/ Field(`components/Field/*.spec.md`)。
+
+**既有 primitive 優先消費**:命中既有 → 必消費不 hand-craft。**自我檢查**:icon+text 垂直 → `<Empty>`;橫向 row → `<MenuItem>` + slot;浮層 → `overlay-surface`;跨 OS 捲軸 → `<ScrollArea>`;鎖長寬比 → `<AspectRatio>`。完整對照 → `.claude/references/build-ui-canonicals.md`。
+
+## UI 開發 4 條核心
+
+必重用既有 `components/` / 必用 design tokens(禁硬寫色/字/間距/圓角)/ 建新 UI 前查 pattern / 用 `cn()`(`@/lib/utils`)合併 Tailwind class。
+
+深度規則 → `.claude/references/ui-dev-rules.md`(slot 幾何 / Padding source / Icon size 3 層)。
+
+**一句話 pointer**:
+- 新 row 元件 → `patterns/element-anatomy/item-anatomy.spec.md`「自我檢查」
+- 清 unused imports / export 異動後:`npx tsc -b` → grep `export {}` → `npm run storybook` → 互動驗
+- Inline Action vs Button → item-anatomy.spec.md「Inline Action 設計規格」
+- 陰影:必 `--elevation-*`;禁 `shadow-sm/md/lg/xl/2xl`
+- 視覺容器 breathing:有邊界 → 必 inner padding
+
+## Tailwind 5 條核心(每條過真實 bug,詳 `.claude/references/tailwind-gotchas.md`)
+
+1. **CSS variable 必 `var()` 包覆** — `w-[var(--foo)]` 而非 `w-[--foo]`(v4 silent 失效)
+2. **自訂 utility 必在 `lib/utils.ts` 註冊 group** — 否則 tailwind-merge 誤判 strip
+3. **禁 `shadow-sm/md/lg` / `text-xs/sm/base` / 硬寫色值** — 用 `shadow-[var(--elevation-N)]` (N ∈ {100,200,300}) / `text-body`
+4. **禁 shadcn compat alias**(`bg-popover` / `text-muted-foreground` / `bg-accent` 等)— 用 direct token
+5. **禁 primitive 色名作 utility**(`bg-neutral-3` / `text-blue-6`)— 用 semantic utility 或 `bg-[var(--color-blue-6)]`
+
+## Token 命名 4 條硬規則
+
+1. **對齊既有 family**(不孤立發明)— 詳 `tokens/color/color.spec.md`
+2. **不混語義與色名**:Tag/Avatar 用 primitive(`var(--color-deep-orange-1)`);Button/Checkbox 用 semantic(`var(--error-subtle)`)
+3. **新增語意色相**走 `tokens/color/color.spec.md`「新增語意色相流程」SSOT。本系統採 **Atlassian-style Semantic State Token**
+4. **禁止**:籠統命名 / 孤立命名 / 自創縮寫 / Primitive 帶語意 / Semantic 帶色相 / Categorical 中間層(已廢除)
+
+## 元件 Props 命名
+
+**按「是什麼」命名,不按「在哪裡」命名**(Material Chip / Ant Tag idiom):
+- slot 只接 icon → `startIcon` / `endIcon`(型別 `LucideIcon`,元件控尺寸)
+- slot 接任意視覺 → 描述內容類型(`avatar`,型別 `ReactNode`)
+- slot 是行為 → callback(`onDismiss`,元件渲染互動 + 樣式)
+- ❌ 禁 `prefix` / `suffix` / `left` / `right`(位置名不傳達本質)
+
+**4 名關閉 / 移除 callback**(詳 `.claude/references/props-naming.md`):
+`onClose` / `onDismiss` / `onRemove` / `onClear` 各有語意不合併。
+
+**Badge 命名按放置**:`badge`(inline)/ `overlayBadge`(疊視覺重心 iconOnly)/ `badgeCount`(Avatar count)/ `status`(Avatar presence dot)。
+
+**Icon canonical**:Overflow `MoreVertical` / Breadcrumb ellipsis `MoreHorizontal` / Close `X` / 成功 `Check` / 警告 `TriangleAlert` / 資訊 `Info`。
+
+## shadcn 元件規範
+
+**結構**:每元件 `{name}.{tsx,spec.md,stories.tsx,anatomy.stories.tsx,principles.stories.tsx}`。tsx 用 forwardRef + cva + VariantProps + cn() + `{Component, componentVariants}` export。Import `@/design-system/components/{Name}/{name}`(無 barrel)。`npx shadcn add` 後**立刻 grep 移除 shadcn compat alias**。
+
+**cva 適用**:className-only 差異 → cva;style 物件 → object map + `style={{}}`;不同 JSX 樹 → conditional rendering。
+
+**元件不得自包全域 Provider**(Tooltip / Theme / Toast / Portal)— 由應用層統一設定。**判斷**:Context 是行為狀態(open / size)→ 可包;全域外觀配置(delay / theme / portal / variant defaults)→ 禁止。

package/ds-canonical/skills/README.md

@@ -0,0 +1,88 @@
+# .claude/skills/ Charter
+
+## 這裡只收:多步驟 workflow + user 決策點
+
+每個 skill 一個 folder,內含:
+- `SKILL.md` — frontmatter(`name` / `description`) + 完整 workflow body
+- `references/` — 深度細節檔(AI 在跑 workflow 時按需讀)
+
+**核心特徵**:**只在 user invoke 時載入**(不佔每 session context);流程包含 checkpoint 讓 user 介入決策。
+
+## 當前居民(22 skills,2026-05-14 update)
+
+**Audit / Quality(5)**:
+| Skill | Invoke 時機 | Scope |
+|-------|-----------|-------|
+| `design-system-audit/` | user 要求 audit DS 本身 | DS 內部 spec/cva/SSOT 33 維度(Phase 0 自建 baseline)|
+| `product-ui-audit/` | 「audit 這個 UI / 檢查 DS 用對嗎」| consumer UI 6 維檢核 |
+| `component-quality-gate/` | 元件 merge / ready / check | 45+ 項 checklist + Phase 4 Ship 6 項 |
+| `visual-audit/` | 視覺對齊 / 排版問題 / gap 錯 | pixel-level Layer A + B |
+| `code-quality-audit/` | 量化 clean code(any / dead export / file-size / long fn / circular dep / magic number)| chained by /design-system-audit Dim 27 |
+
+**Performance / UX(2)**:
+| `performance-audit/` | 「這元件效能如何」 | render / memo / bundle |
+| `ux-audit/` | 「鍵盤用不了 / focus 跑飛 / 無障礙」 | keyboard / ARIA / animation |
+
+**Build-phase workflow(3)**:
+| `new-component/` | 「做新元件 X」 | 6-phase 建新元件 |
+| `prototype/` | 「做 prototype / MVP / 原型」 | exploration + Phase 3.5 gate |
+| `delivery-handoff/` | 「要交付 / handoff」 | figma-like 交付包 |
+
+**Story 層(2)**:
+| `story-writing/` | 「寫 story / 補 anatomy / principles story」 | 6-story 結構 + 範例品質 |
+| `story-auto-compile-migrate/` | 「migrate 元件到 auto-compile」/ auto-chained by audit Dim 23 | 批次加 `componentMeta` export + spec YAML frontmatter(Phase 1+2 migration) |
+
+**Governance(6)**:
+| `knowledge-prune/` | 季度 / CLAUDE.md > 800 / MEMORY.md > 20 / audit 報 sprawl | 治理冗贅深度 prune |
+| `governance-health/` | 月度 / auto-chain by audit | continuous metric monitor + auto-propose |
+| `propose-options/` | 給 option A/B/C 前必走 M18 4-Q gate | M8 benchmark / M17 SSOT / Rule-of-3 / M10 下游 |
+| `scan-similar-bugs/` | 修 bug 後 M10 mechanical exhaustive scan | DS-wide 同類 bug 全清 |
+| `codify-corrections/` | user 糾正後 codify 到正確 home(memory / CLAUDE.md / spec / hook) | 跨 home 路由 |
+| `ensure-canonical/` | user 說「確保 X 一定要 / 永不漂移」trigger phrase(M19)| 自動規劃 5-layer defense-in-depth(canonical+hook+skill+audit+verify),至少 3 層落地 |
+
+## 這裡**不收**(反例 + 正確去處)
+
+| 疑似要放這但其實不是 | 實際應去 | 為什麼 |
+|-------------------|---------|--------|
+| 單步驟 scaffold / one-shot action | `.claude/commands/` | skill 是多步驟 + checkpoints,命令是單步 |
+| 自動機械檢查(pre/post tool) | `.claude/hooks/` | skill 需 AI 走流程,hook 是 tool-level 自動 |
+| 每 session 都要的 signal rule | `CLAUDE.md` | skill 只在 invoke 時載入,會 miss signal |
+| 隨時間變化的狀態(audit progress) | `memory/` | skill 是不變的 workflow,state 屬 memory |
+| 元件 runtime primitive | `packages/design-system/src/patterns/` | skill 是 AI workflow,不是 UI code |
+
+## 新 skill 的 criteria(必須全部通過)
+
+1. **多步驟 workflow**(不只是單一 check,有明確 phase)
+2. **有 user 決策 checkpoint**(AI 需要停下問 user)
+3. **只在特定 invoke 情境需要**(不是每 session signal)
+4. **重複使用 ≥ 3 次**(一次性任務不建 skill)
+5. **invoke trigger 明確**(frontmatter description 裡清楚列出 user 說什麼會觸發)
+
+任一不過 → 改建 command / hook / spec / CLAUDE.md rule,不硬塞。
+
+## SKILL.md 必須包含
+
+```markdown
+---
+name: skill-name-kebab-case
+description: 一句話說明 skill 做什麼 + 何時 invoke(user 說哪些話觸發)
+---
+
+# Skill Title
+
+## When to run
+[明確觸發 trigger]
+
+## Preconditions
+[必要條件]
+
+## Workflow
+[Phase 1 / 2 / 3 + 每個 phase 的 checkpoint]
+
+## References
+[指向 references/*.md 的深度細節]
+```
+
+## 建立前必 Read
+
+本 README + CLAUDE.md `# 治理 canonical` 的 Skill 章節 + 最接近的既有 skill 當範本。

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

@@ -0,0 +1,181 @@
+---
+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)。
+---
+
+# /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 7 維」(那是 `/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/skills/code-quality-audit/SKILL.md

@@ -0,0 +1,63 @@
+---
+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。
+---
+
+# 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 | 覆蓋不完整 → 由 `check_token_hygiene.sh` hook 層負責(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
+- 相關:`check_token_hygiene.sh`(正交 — token 紀律 vs code 紀律)