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

package/ds-canonical/skills/new-component/SKILL.md

@@ -7,9 +7,9 @@ description: Create-phase workflow for building a new design-system component fr
 
 ## 存在意義
 
-`/component-quality-gate` 是 **review-phase** gate(元件做完後驗 45 項),但建 **create-phase** 沒 workflow guide → AI 每次從 CLAUDE.md 零散規則自己湊,容易漏規則、誤套 pattern。
+`/component-quality-gate` 是 **review-phase** gate(元件做完後驗 35 項),但建 **create-phase** 沒 workflow guide → AI 每次從 AGENTS.md + canonical rules 零散規則自己湊,容易漏規則、誤套 pattern。
 
-本 skill 填 create-phase 空缺:6 phase 帶著 AI 一步一步建元件,對齊 CLAUDE.md 所有規則(Layout Family / Props 命名 / Spec 7 維度 / Stories 真實業務場景 / visual audit),最後自動 chain `/component-quality-gate` 做 exit check。
+本 skill 填 create-phase 空缺:6 phase 帶著 AI 一步一步建元件,對齊 AGENTS.md + canonical rules 所有規則(Layout Family / Props 命名 / Spec 7 維度 / Stories 真實業務場景 / visual audit),最後自動 chain `/component-quality-gate` 做 exit check。
 
 **跟 /component-quality-gate 互補**:create(本 skill)在元件沒寫前先指引;quality-gate 在元件寫完後驗收。兩者不重疊。
 
@@ -28,13 +28,13 @@ description: Create-phase workflow for building a new design-system component fr
 
 - User 已給出新元件的 **名字 + 大致用途**(否則先對話釐清,再 invoke)
 - 元件 folder 不存在於 `packages/design-system/src/components/`(真的是新的)
-- 已讀 CLAUDE.md(skill 會 re-ref 關鍵章節,但 session 整體已有 context 更好)
+- 已讀 AGENTS.md(skill 會 re-ref 關鍵章節,但 session 整體已有 context 更好)
 
 ## Workflow(6 phase + 多 checkpoint)
 
 ### Phase 1 — 近親 spec 掃讀(不憑直覺發明)
 
-對齊 CLAUDE.md mindset #2 + `# 遇不確定時的協議` Step 2 + memory `feedback_proactive_5layer_pipeline.md`「5-step pre-check」(寫 tsx 前必含 CLAUDE.md SSOT 清單 + tsx 開頭「── 消費的 SSOT ──」段)。
+對齊 AGENTS.md mindset #2 + `# 遇不確定時的協議` Step 2 + `packages/design-system/ds-canonical/references/ssot-consultation.md`「5-step pre-check」(寫 tsx 前必含 repository instruction SSOT 清單 + tsx 開頭「── 消費的 SSOT ──」段)。
 
 1. **識別 2-3 個近親元件**(同 family、同 pattern、同職責):
    - 視覺相似?(例:新 `StatusChip` → 近親 `Tag` / `Badge` / `Chip`)
@@ -46,23 +46,27 @@ description: Create-phase workflow for building a new design-system component fr
    - 禁止事項(往往透露 gotcha)
    - SSOT anchor(往哪指)
 3. **查世界級對照**:Polaris / Material / Atlassian / Ant / Apple HIG 有沒對應元件?**至少 2 個** DS 的做法,記 3 行筆記(naming / API / 視覺模式)。
-4. **查 baseline 狀況**:`ls packages/design-system/src/components/` 確認名字衝突;`grep` CLAUDE.md「失敗記憶索引」看有沒同類別的歷史 bug。
+4. **查 baseline 狀況**:`ls packages/design-system/src/components/` 確認名字衝突;`grep` AGENTS.md「失敗記憶索引」看有沒同類別的歷史 bug。
+5. **產出「primitive 覆蓋對照表」artifact**(2026-07-07 治理進化方向 3 洞 c,強制產物非心算):逐 anatomy 段列「這段 × 消費哪個既有 primitive」——row → item-anatomy、浮層 → overlay-surface、chrome 標題列 → ChromeHeader、橫向溢出 → horizontal-overflow、輸入 chrome → field-wrapper、pill → Button「Pill Layout」。**每段必有著落;對不上的段才准自建,且必附「自建 + 理由」**(進 spec 定位段)。寫 tsx 時此表轉錄為檔頭「── 消費的 SSOT ──」段(hook `check_ssot_header_declaration.sh` P0 驗新檔必有)。
 
-### Checkpoint 1 — 定位 Proposal(STOP 點)
+### Checkpoint 1 — 定位 receipt / conditional P2H
 
-回報 user:
-- 元件名稱(按 CLAUDE.md `# 命名與語言一致性` 三重 test)
+記錄:
+- 元件名稱(按 AGENTS.md `# 命名與語言一致性` 三重 test)
 - 近親元件清單 + 跟本元件的異同一句話
 - 世界級對照 2 個(Ant Design 叫 X / Material 叫 Y)
-- **問 user**:「這個 positioning 對嗎?要不要改名 / 重 scope?」
+- **primitive 覆蓋對照表**(Phase 1 step 5 artifact;自建段落 + 理由醒目標出)
 
-**User 點頭才進 Phase 2。** 定位錯的話在此階段轉向最便宜。
+若名稱、scope 或 public component semantics 仍有多個可行選擇，且會導向不同產品／
+UI／UX outcomes，才把唯一剩餘取捨整理成 exact target-bound P2H decision。若 user
+requirement、近親 SSOT 與 benchmark 已唯一決定 positioning，直接記錄 selection receipt
+並進 Phase 2；不得把 checkpoint 本身當成 user approval gate。
 
 ### Phase 2 — Layout Family 判定
 
-對齊 CLAUDE.md `# 4-Family Layout Model`。
+對齊 AGENTS.md `# 4-Family Layout Model`。
 
-**判斷流程**(照 CLAUDE.md 既有):
+**判斷流程**(照 AGENTS.md 既有):
 1. 垂直列表裡? → Family 1(menu)/ Family 2(reading)
 2. 單行可點擊 pill? → Family 3(action trigger / data indicator sub-profile)
 3. 單行可編輯? → Family 4(Field control,視覺對齊 Family 1)
@@ -77,7 +81,7 @@ description: Create-phase workflow for building a new design-system component fr
 
 ### Phase 3 — 寫 spec.md 7 維度(先 spec 後 code,spec 是 judgment home)
 
-對齊 `.claude/rules/spec-rules.md`。7 維度缺一不可(除非元件本質無該面向,寫「本元件無 X 狀態」):
+對齊 `packages/design-system/ds-canonical/rules/spec-rules.md`。7 維度缺一不可(除非元件本質無該面向,寫「本元件無 X 狀態」):
 
 1. **定位**(positioning + 實作基礎 + Layout Family + 世界級對照)
 2. **何時用**(3-5 個情境,真實業務,不 generic)
@@ -87,19 +91,22 @@ description: Create-phase workflow for building a new design-system component fr
 6. **空值呈現 / 驗證時機**(Field 家族必寫 / 非 Field 可簡答)
 7. **Loading / 無障礙**(async 場景的 state / a11y 預設)
 
-**Checkpoint 2**:spec 寫完,回報 user → 請 user 看 spec 判定 positioning 是否 lock in。改 positioning 比改 code 便宜得多。
+**Positioning receipt / conditional P2H checkpoint**:spec 寫完先以近親 SSOT、benchmark
+與 user 已明示 requirement 驗證 positioning。若答案唯一或 user 已 exact 指定，記錄 receipt
+後直接進 Phase 4；只有仍有多個可行 public component semantics／UI outcomes 時，才請 user
+做 exact target-bound P2H decision。不得把 spec milestone 本身當 approval gate。
 
 ### Phase 4 — 寫 tsx(shadcn 結構 + cva + 對齊 spec)
 
-對齊 `.claude/rules/ui-development.md`「shadcn 元件規範」 + `.claude/references/cva-patterns.md`。
+對齊 `packages/design-system/ds-canonical/rules/ui-development.md`「shadcn 元件規範」 + `packages/design-system/ds-canonical/references/cva-patterns.md`。
 
 1. **結構**:`forwardRef + cva + VariantProps + cn() + { Component, componentVariants } export`
 2. **cva 適用法**:className variant 用 cva;style prop variant 用 object map;結構 variant 用 conditional rendering(見 cva-patterns.md)
-3. **Props 命名**:按 `.claude/rules/ui-development.md`「元件 Props 命名」:
-   - 行為 → `onDismiss` / `onClose` / `onClear` / `onRemove`(語意分層,見 CLAUDE.md)
+3. **Props 命名**:按 `packages/design-system/ds-canonical/rules/ui-development.md`「元件 Props 命名」:
+   - 行為 → `onDismiss` / `onClose` / `onClear` / `onRemove`(語意分層,見 `packages/design-system/ds-canonical/references/props-naming.md`)
    - Slot icon → `startIcon` / `endIcon`(type `LucideIcon`)
    - Slot media → `avatar`(type `ReactNode`)
-4. **Token 消費**:Padding / icon size / hover bg / shadow 全走 token(見 `.claude/rules/ui-development.md` 三層分層)
+4. **Token 消費**:Padding / icon size / hover bg / shadow 全走 token(見 `packages/design-system/ds-canonical/rules/ui-development.md` 三層分層)
 5. **禁止 shadcn compat alias**(`bg-popover` / `text-muted-foreground` 等)—— 用 direct token
 6. **Field 家族元件**:default `size="md"` 對齊 field-height family(見 `tokens/uiSize/uiSize.spec.md`)
 7. **cva defaultVariants 異動**:改之後必 grep 元件所有檔案同步三方(spec / docblock / anatomy story)
@@ -134,9 +141,9 @@ traits:
 
 **Phase 5.1-5.3 — 三層 stories**:
 
-1. **`{name}.stories.tsx` 展示**:per Phase 5.0 declared traits → 對照 `category-templates.md` 衍生 required core stories(`hasVariants` → AllVariants / `hasSizes` → AllSizes / `isOverlay` → OpenSnapshot 等)。再加 1-2 真實業務 scenario(Jira / Stripe / Notion 過 earn-existence)。Hook `check_story_category.sh` write-time 攔不符 trait core。
+1. **`{name}.stories.tsx` 展示**:per Phase 5.0 declared traits → 對照 `category-templates.md` 衍生 required core stories(`hasVariants` → AllVariants / `hasSizes` → AllSizes / `isOverlay` → OpenSnapshot 等)。再加 1-2 真實業務 scenario(Jira / Stripe / Notion 過 earn-existence)。Hook `check_story_invariants.sh` R3 category(原 check_story_category.sh folded 折入)write-time 攔不符 trait core。
 2. **`{name}.anatomy.stories.tsx` 設計規格**:5-story 標準(Overview + SizeMatrix + ColorMatrix + StateBehavior + Inspector)或合理 subset + rationale。
-3. **`{name}.principles.stories.tsx` 設計原則**(對齊 Polaris/Carbon/Ant canonical,2026-04-26):universal core ≥ 2 of {`WhenToUse` / `WhenNotToUse` / `Vs{Sibling}Rule` / `ContentGuidelines`}。do / don't 情境對照,每則 Rule title + Rule note + 範例。Hook `check_principles_canonical.sh` write-time 攔不符。
+3. **`{name}.principles.stories.tsx` 設計原則**:預設單一完整 `UsageGuidance`(何時用 + 何時不用 + sibling boundary)即 sufficient。只有 distinct topic 通過 earn-existence 才加第二篇；若採 split style，至少涵蓋 2 個不同 decision dimensions(`WhenToUse` / `WhenNotToUse` / `Vs{Sibling}Rule` / `ContentGuidelines`)。Hook `check_canonical_propagation.sh` E.1 write-time 同規則。
 
 **兩個 test**:
 - 「人」test — 遮標題 5 秒讀者看懂情境?
@@ -144,24 +151,25 @@ traits:
 
 ### Phase 6 — Self quality-gate(exit check)
 
-**Mandatory**。chain `/component-quality-gate` 走 45 項 checklist + Phase 4.5 visual audit(Layer A + B)+ **Dim 27 code quality audit**(2026-04-24 新:`node scripts/code-quality-audit.mjs --scope=component:{Name} --check`,P0 violation 必 block)。對齊 CLAUDE.md 稽核 canonical Tier 1 stakeholder-gate:元件要 merge 前 code + visual + clean-code 三層過關。
+**Mandatory**。chain `/component-quality-gate` 走 35 項 checklist + Phase 4.5 visual audit(Layer A + B)+ **Dim 27 code quality audit**(2026-04-24 新:`node scripts/code-quality-audit.mjs --scope=component:{Name} --check`,P0 violation 必 block)。對齊 AGENTS.md `# 稽核 canonical` Tier 1 stakeholder-gate:元件要 merge 前 code + visual + clean-code 三層過關。
 
 **如何 chain**:
 1. Invoke `/component-quality-gate` skill,以本元件為 scope
-2. 45 項全綠 + visual 過關才算 create-phase 完成
+2. 35 項全綠 + visual 過關才算 create-phase 完成
 3. 若 quality-gate 發現問題 → 回 Phase 3 / 4 / 5 對應階段修,再跑 quality-gate
 4. 通過 → 回報 user「元件 {Name} 建立完成,已過 create + review 雙 gate」
 
 ## Non-goals
 
 - 不自動進入 `packages/design-system/src/components/`(explorations/ 才是實驗場;prototype 階段跑 `/prototype` skill)
-- 不替 user 決定 positioning(Checkpoint 1 必須 user 點頭)
-- 不跳過 spec(`.claude/rules/spec-rules.md`:先 spec 後 code,spec 是 judgment home)
+- 不替 user 決定真正產品／UI／UX positioning tradeoff；但既有 SSOT／明確 requirement
+  已唯一決定的 positioning 必自主落地，不得重問。
+- 不跳過 spec(`packages/design-system/ds-canonical/rules/spec-rules.md`:先 spec 後 code,spec 是 judgment home)
 - 不省略 quality-gate(Phase 6 chain mandatory,merge 前必過)
 
 ## References
 
-- `references/new-component-checklist.md` — 完整 6 phase checklist + 各項 CLAUDE.md pointer
+- `references/new-component-checklist.md` — 完整 6 phase checklist + 各項 AGENTS.md pointer
 
 ## 相關 skill
 

package/ds-canonical/skills/new-component/references/new-component-checklist.md

@@ -11,17 +11,18 @@
 - [ ] 抓到 Layout Family 宣告、API surface、禁止事項、SSOT anchor
 - [ ] 查至少 2 個世界級 DS(Polaris / Material / Atlassian / Ant / Apple HIG)對應元件
 - [ ] `ls packages/design-system/src/components/` 確認名字無衝突
-- [ ] grep CLAUDE.md `# 失敗記憶索引` 查同類歷史 bug
+- [ ] grep AGENTS.md `# 失敗記憶索引` 查同類歷史 bug
 
-## Checkpoint 1 — 定位 Proposal
+## Positioning evidence / conditional P2H checkpoint
 
-- [ ] 元件名通過「命名三重 test」(既有語言 / 世界級 idiom / 跨元件無衝突,見 CLAUDE.md `# 命名與語言一致性`)
-- [ ] 報 user:元件名 / 近親 / 世界級對照 / positioning 一句話
-- [ ] User 點頭
+- [ ] 元件名通過「命名三重 test」(既有語言 / 世界級 idiom / 跨元件無衝突,見 AGENTS.md `# 命名與語言一致性`)
+- [ ] 記錄元件名 / 近親 / 世界級對照 / positioning 一句話
+- [ ] 若既有 SSOT 或 user 明確 requirement 已唯一決定，記 receipt 後自主接續
+- [ ] 只有多個可行 public component/UI semantics 仍並存時，取得 exact target-bound P2H decision
 
 ## Phase 2 — Layout Family 判定
 
-- [ ] 走 CLAUDE.md `# 4-Family Layout Model` 判斷流程
+- [ ] 走 AGENTS.md `# 4-Family Layout Model` 判斷流程
 - [ ] 若 Family 1/2 → 確認消費 `<MenuItem>` + slot components(不重寫 row 結構)
 - [ ] 若 Family 3 → follow `Button Pill Layout` canonical(見 button.spec.md)
 - [ ] 若 Family 4 → follow field-controls.spec.md
@@ -36,14 +37,14 @@
 - [ ] 相關 / SSOT pointer(互相 link,ownership 明確)
 - [ ] 空值呈現 / 驗證時機(若不適用寫明文「本元件無 X」)
 - [ ] Loading / 無障礙(若不適用寫明文)
-- [ ] **Checkpoint 2**:spec 寫完停下報 user,lock in positioning
+- [ ] spec 寫完重驗 positioning；唯一答案記 receipt 後接續，真正 P2H 取捨才停下
 
 ## Phase 4 — tsx
 
 - [ ] 結構 shadcn + forwardRef + cva + VariantProps + cn()
-- [ ] cva 適用正確(見 `.claude/references/cva-patterns.md`;style prop / 結構性 variant 不硬塞 cva)
+- [ ] cva 適用正確(見 `packages/design-system/ds-canonical/references/cva-patterns.md`;style prop / 結構性 variant 不硬塞 cva)
 - [ ] Props 命名按「是什麼」不按「在哪裡」(startIcon / endIcon / avatar / onDismiss / onClose / onClear / onRemove)
-- [ ] callback 命名分層正確(`.claude/rules/ui-development.md`「元件 Props 命名」 的 canonical)
+- [ ] callback 命名分層正確(`packages/design-system/ds-canonical/rules/ui-development.md`「元件 Props 命名」 的 canonical)
 - [ ] Token 消費三層分層(chrome/layout-space / 元件內/Tailwind p-N / 精確幾何/calc)
 - [ ] Icon size 三層分層(row 走 RowSizeContext / Button 走 Button mapping / 一次性 inline size={n} 對齊 uiSize)
 - [ ] 無 shadcn compat alias(bg-popover 等)
@@ -59,13 +60,13 @@
 - [ ] `{name}.principles.stories.tsx` 含 do/don't Rule stories,每則 title + note + 範例
 - [ ] 「人」test 過:遮標題 5 秒能懂情境
 - [ ] 「舉一反三」test 過:讀者推得出自己產品怎用
-- [ ] hook `check_story_anatomy.sh` 未觸發 block(無手刻 list item / label Button dismiss / 自刻 overlay)
+- [ ] hook `check_story_invariants.sh` R1 anatomy(原 check_story_anatomy.sh folded 折入)未觸發 block(無手刻 list item / label Button dismiss / 自刻 overlay)
 - [ ] Storybook title path 正確(`Design System/Components/{Name}/{中文子頁}` 或 `Internal/{Name}/...`)
 
 ## Phase 6 — Self quality-gate chain
 
 - [ ] Invoke `/component-quality-gate` skill
-- [ ] 45 項全綠
+- [ ] 35 項全綠
 - [ ] Phase 4.5 visual audit Layer A 過(0 contrast / 0 geometry violation)
 - [ ] Phase 4.5 Layer B AI 視覺判斷過(或有 documented rationale)
 - [ ] 回報 user「元件 {Name} 建立完成,已過 create + review 雙 gate」

package/ds-canonical/skills/performance-audit/SKILL.md

@@ -14,7 +14,7 @@ description: Performance audit for design-system components and product UI. Chec
 
 本 skill 作為稽核 6 維度的 **D3 元件效能** canonical home。
 
-## 觸發時機(對齊 CLAUDE.md 稽核 canonical)
+## 觸發時機(對齊 shared governance 稽核 canonical)
 
 | 情境 | 模式 | 本 skill 跑什麼 |
 |------|------|----------------|
@@ -47,7 +47,7 @@ description: Performance audit for design-system components and product UI. Chec
 
 **工具**:
 - React DevTools Profiler record → 看 flame graph
-- `why-did-you-render` dev dep 觸發警告(未來可加)
+- `why-did-you-render` dev dep 觸發警告(**尚未落地**;trigger = 下一個 render-storm 類 bug 實例時一併引入,roadmap 殘項列冊)
 - 直接 grep pattern(inline style / arrow onClick)
 
 ### Phase 2 — Memoization / dependency
@@ -66,9 +66,9 @@ description: Performance audit for design-system components and product UI. Chec
 
 **工具**:
 - `npx vite build --report`(vite bundle visualizer)
-- bundle-size CI check(未來可加)
+- **bundle-size gate(已落地 2026-07-07)**:`npm run check:bundle-size`(budget SSOT = `packages/design-system/bundle-budget.json`,total + top-8 entry 各 +10% headroom;release-preflight 內建必跑;蓄意增大 → `--init` 更新 budget + commit 說明)
 
-### Phase F — Report(必 STOP,對齊分權 canonical)
+### Phase F — Report and route
 
 產出:
 
@@ -85,13 +85,16 @@ description: Performance audit for design-system components and product UI. Chec
 - 位置: {file:line}
 - 現況: {render count / bundle contribution}
 - 建議: {具體修法}
-- 是 canonical 修實作(auto),還是原則待討論(STOP)?
+- 是工程／治理修實作(P2E auto)，還是產品／UI／UX SSOT 真取捨(P2H)?
 
-## 提議討論(待 user sign-off)
-- {若發現 canonical 本身有問題,列於此,不自改}
+## Authority classification
+- P2E:{工程／治理 finding，交 canonical owner 自主修復}
+- P2H:{只有真正產品／UI／UX SSOT 取捨才列 exact target-bound decision}
 ```
 
-**STOP 點**:report 寫完**不自動修**。分權對齊 CLAUDE.md `# 稽核 canonical`(內含「Audit-vs-execute 分權」inline rule)。
+本 skill 保持 read-only，report 是 evidence receipt；caller／canonical owner 對 P2E 直接接續
+修復與驗證，不把 read-only skill boundary 誤當 user checkpoint。只有 P2H 或
+shared-governance human-only boundary 才停止。
 
 ## Non-goals
 
@@ -101,7 +104,7 @@ description: Performance audit for design-system components and product UI. Chec
 
 ## 相關
 
-- `.claude/skills/design-system-audit/SKILL.md` — 全 dim 統籌(per design-system-audit SSOT);本 skill 是 D3 補位
-- `.claude/skills/visual-audit/SKILL.md` — pixel 層(D5)
-- `.claude/skills/ux-audit/SKILL.md` — UX 行為層(D4)
-- `.claude/skills/component-quality-gate/SKILL.md` — Phase 4.5 進階模式 chain 本 skill
+- `packages/design-system/ds-canonical/skills/design-system-audit/SKILL.md` — 全 dim 統籌(per design-system-audit SSOT);本 skill 是 D3 補位
+- `packages/design-system/ds-canonical/skills/visual-audit/SKILL.md` — pixel 層(D5)
+- `packages/design-system/ds-canonical/skills/ux-audit/SKILL.md` — UX 行為層(D4)
+- `packages/design-system/ds-canonical/skills/component-quality-gate/SKILL.md` — Phase 4.5 進階模式 chain 本 skill

package/ds-canonical/skills/product-ui-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: product-ui-audit
-description: Audit product / consumer UI code (非 design-system 本身) against DS usage discipline + mindset adherence. Catches element misuse / design principle violations / token leakage / geometry bugs / a11y gaps across 6 dimensions. Invoke via /product-ui-audit when user says「audit 這個 UI」「檢查 X feature 用對 DS 嗎」「這段 code 符合設計原則嗎」,or auto-invoked by /prototype Phase 3.5 gate.
+description: Audit product / consumer UI code (非 design-system 本身) against DS usage discipline + mindset adherence. Catches element misuse / design principle violations / token leakage / geometry bugs / a11y gaps across 7 dimensions. Invoke via /product-ui-audit when user says「audit 這個 UI」「檢查 X feature 用對 DS 嗎」「這段 code 符合設計原則嗎」,or auto-invoked by /prototype Phase 3.5 gate.
 ---
 
 # Product UI Audit Workflow
@@ -38,26 +38,34 @@ Purpose: design-system-audit audits the **DS itself**(spec / cva / SSOT 三方
 ## Preconditions
 
 - User 指定 audit target(file path / folder / feature area)
-- Target 是 consumer 層 UI code(`src/app/**` / `src/explorations/**` / `src/pages/**` / `src/features/**`等 — **不掃 `packages/design-system/src/`**)
-- CLAUDE.md 全讀(6 維 audit 都依此為基準)
+- Target 是 consumer 層 UI code(`src/app/**` / `src/explorations/**` / `src/pages/**` / `src/features/**` / `apps/**`(含 DS repo 自家 `apps/template` + create-app 產物)等 — **不掃 `packages/design-system/src/`**)
+- shared governance instructions 全讀(7 維 audit 都依此為基準)
 
 ---
 
-## 6-Dimension Audit
+## 7-Dimension Audit
+
+### Full-repository preflight(release / full or deep audit only)
+
+Feature-scoped UI audit 不擴張到無關檔案；但 release、full-repo 或 deep audit 必先依
+`node_modules/@qijenchen/design-system/ds-canonical/references/repository-hygiene.md` 完成一次
+Git-index + nonignored worktree inventory。若 authority repo 的 portable gate 可用，執行
+`node scripts/repository-hygiene-invariant.mjs --profile=product-consumer --check`；否則依同一
+canonical 手動分類。未掛載的 registered repo 是 unobserved，不可寫成 PASS。
 
 每個 dimension 獨立檢查,產出 findings。詳細 grep pattern + rule 見 `references/audit-checks.md`。
 
 ### Dim 1 — Token 紀律(token hygiene)
 
 - 硬寫 hex / rgb / rgba / hsl 色值
-- shadcn compat alias(bg-popover / text-muted-foreground / bg-accent / bg-destructive / bg-background / bg-card / border-input / text-primary-foreground / text-accent-foreground / text-card-foreground / text-popover-foreground)
+- shadcn compat alias(bg-popover / text-muted-foreground / bg-accent / bg-destructive / bg-background / bg-card / border-input / text-primary-foreground / text-accent-foreground / text-card-foreground / text-popover-foreground)**(完整 deny-list SSOT:`packages/design-system/src/tokens/utility-registry.json`;此處 inline 為 grep 便利,新增 alias 改 registry)**
 - Tailwind default shadow(shadow-sm / md / lg / xl / 2xl / inner)— 應走 elevation token
 - Tailwind v4 `[--foo]` shorthand 靜默失效
 - 硬寫 px 值當該用 token(`w-[48px]` 應改 token)
 
-此維對齊既有 `check_token_hygiene.sh` hook 的 4 項 + 擴充硬色值 / 硬 px 檢查。
+此維對齊既有 token 防線(`lib/_token_hygiene.sh` 5-check:shadcn alias / v4 shorthand / hardcoded shadow / primitive-color-as-utility / native overflow，由 `post_edit_dispatcher.sh` source；+ `check_opacity_token_usage.sh` 對齊 utility-registry.json 類別 — pattern hardcode 於 hook,registry 僅存在性 fallback gate)+ 擴充硬色值 / 硬 px 檢查。
 
-### Dim 2 — Layout primitive 消費(per CLAUDE.md 清單)
+### Dim 2 — Layout primitive 消費(per shared governance 清單)
 
 掃是否正確消費既有 layout primitives(非自 roll):
 
@@ -87,15 +95,15 @@ Purpose: design-system-audit audits the **DS itself**(spec / cva / SSOT 三方
 
 ### Dim 4 — Mindset adherence
 
-對齊 CLAUDE.md 5 條 mindset:
+對齊 shared governance 6 條 mindset(逐條檢查 #1-#5;#6「大原則吸收瑣碎」屬 governance meta 層,不在 consumer code audit scope。編號用 mindset #N,避免撞 meta-patterns M-rules 編號):
 
-- **M1 對標世界級**:新 pattern 有對標備註? 或找得到對應既有元件?
-- **M2 不憑直覺發明**:新數值(gap / padding / font-size)前有 grep 既有?
-- **M3 改一處看三處**:若改 DS 的 cva defaultVariants,spec / docblock / anatomy 三方同步?
-- **M4 真實業務場景**:stories / examples 用真實場景 (Jira / Stripe / Notion...)?無 `Option A/B/C` / `按鈕一` / `Rule A`?
-- **M5 猶豫就問**:code 裡有 TODO-未確認留白?
+- **mindset #1 對標世界級**:新 pattern 有對標備註? 或找得到對應既有元件?
+- **mindset #2 不憑直覺發明**:新數值(gap / padding / font-size)前有 grep 既有?
+- **mindset #3 改一處看三處**:若改 DS 的 cva defaultVariants,spec / docblock / anatomy 三方同步?
+- **mindset #4 真實業務場景**:stories / examples 用真實場景 (Jira / Stripe / Notion...)?無 `Option A/B/C` / `按鈕一` / `Rule A`?
+- **mindset #5 先證據、再分權**:code 裡有 TODO-未確認留白?兩類都 flag——屬產品／UI／UX SSOT 真取捨 → 列入 user 決策清單;屬純工程 → 違反「依證據自主收斂」(工程不確定性不得留 TODO,應當場收斂)
 
-### Dim 5 — 視覺幾何(Mindset #1 視覺擴充 + CLAUDE.md「同 flex 列互動 slot 幾何鐵律」)
+### Dim 5 — 視覺幾何(Mindset #1 視覺擴充 + `packages/design-system/ds-canonical/references/ui-dev-rules.md`「同 flex 列互動 slot 幾何鐵律」)
 
 - 同 flex 行的互動 slot box 尺寸一致(例:FileItem status / delete 都 h-field-sm)
 - hover-bg / ring / focus outline 不溢出 box 吃 gap token
@@ -114,14 +122,16 @@ Purpose: design-system-audit audits the **DS itself**(spec / cva / SSOT 三方
 
 ### Dim 7 — D6 設計原則自檢(consumer 是否牴觸 DS canonical)
 
-chain `.claude/skills/design-system-audit/references/principle-audit-protocol.md` 做 4 子維 scoped 對 consumer code:
+chain `packages/design-system/ds-canonical/skills/design-system-audit/references/principle-audit-protocol.md` 做 4 子維 scoped 對 consumer code:
 
 - **D6a 合理性**:consumer 自己的設計判斷是否有 rationale(為什麼這樣用 DS 元件)
 - **D6b 一致性**:跨 feature 同概念處理一致(同 team 兩頁面 dismiss 不應用不同方式)
 - **D6c 無矛盾**:consumer 實作是否牴觸 DS spec 聲明(例:用 Button 作 dismiss 明顯違 item-anatomy SSOT)
 - **D6d 完整性**:state 覆蓋(error / loading / empty)
 
-判斷 auto vs STOP 依 protocol 公式。修 consumer code 一致化 = AUTO;建議修 DS canonical 本身 = STOP 提議。
+判斷 auto vs STOP 依 protocol 的 authority classifier。修 consumer code 一致化、工程 bug、
+a11y、performance 與治理修復 = AUTO；只有建議會改變產品／UI／UX SSOT 且存在真實取捨時
+才 STOP 提議。修改 DS canonical 本身不自動等於 human gate。
 
 ---
 
@@ -129,11 +139,14 @@ chain `.claude/skills/design-system-audit/references/principle-audit-protocol.md
 
 ### Phase 0 — Scope
 
-確認 audit target:file / folder / feature area。提問 user 若模糊。禁止掃整個 repo(失焦)。
+從 explicit request、目前 frozen scope、changed paths 與 registered feature owner 解析 audit
+target(file / folder / feature area)。工程範圍模糊時選最小完整 affected scope 並記錄 rationale；
+只有不同 scope 會導致真正產品／UI／UX SSOT 取捨時才提問 user。禁止無 evidence 掃整個 repo
+(失焦)，也禁止把可由 repository evidence 解出的 scope 轉交 user。
 
-### Phase 1 — Parallel 6-dim audit
+### Phase 1 — Parallel 7-Dimension audit
 
-6 個維度各自獨立 grep + code review。可 parallelize。
+7 個維度各自獨立 grep + code review。可 parallelize。
 
 ### Phase 2 — Report
 
@@ -148,7 +161,7 @@ chain `.claude/skills/design-system-audit/references/principle-audit-protocol.md
 | ... |
 ```
 
-### ⚠️ Checkpoint 1 — Triage & fix decision
+### Checkpoint 1 — Triage evidence receipt
 
 類似 design-system-audit 的 triage checkpoint:
 
@@ -157,25 +170,27 @@ chain `.claude/skills/design-system-audit/references/principle-audit-protocol.md
 
 P0(必修,無爭議):N 項
 P1(批次修 + review):M 項
-P2(需討論):K 項
+P2E(工程／治理，自主修):K 項
+P2H(產品／UI／UX SSOT 真取捨):J 項
 
-先修 P0?還是全給 user 看?
+P0/P1/P2E 依 frozen scope 自主修；只有 P2H 要 exact target-bound user decision。
 ```
 
 詳見 `references/report-template.md`。
 
-### Phase 3 — Fix(optional)
+### Phase 3 — Fix
 
-若 user 同意 fix,surgical 修復。每批(Dim 1 / Dim 2 / ...)一個 commit。
+P0/P1/P2E 依 Standing Authorization surgical 修復；每批(Dim 1 / Dim 2 / ...)一個
+可驗證 change set。P2H 在 exact decision 前保持 proposal-only。
 
 ### Phase 4 — Verify
 
-- `npx tsc --noEmit` 通過
+- `npx tsc -b` 無錯(禁 `--noEmit` — root tsconfig `files: []` silent pass;動型別 surface 加跑 `npm run build:lib`,對齊 component-quality-gate + self-verify.md)
 - re-run 本 skill(縮窄到原 findings)確認 zero regression
 
 ### Phase 5 — Visual audit(stakeholder-gate,mandatory on stakeholder-visible work)
 
-對齊 **CLAUDE.md 稽核 canonical Tier 1 stakeholder-gate**:產品 UI 要給 stakeholder / end-user 看之前,**code + visual 雙層都要過**。Phase 1-4 是 code 層;本 Phase 補視覺層。
+對齊 **shared governance 稽核 canonical Tier 1 stakeholder-gate**:產品 UI 要給 stakeholder / end-user 看之前,**code + visual 雙層都要過**。Phase 1-4 是 code 層;本 Phase 補視覺層。
 
 **Input**:Phase 4 verify 過關的產品 UI(screens / routes / embedded widgets)
 
@@ -183,16 +198,19 @@ P2(需討論):K 項
 1. 確認 user 有提供 **URL 清單**(產品 app routes)或 **Storybook scenario id**(若產品 stories 在 Storybook):
    - URL mode:`npm run visual-audit -- --urls=<csv>`(例:`--urls=http://localhost:3000/inbox,http://localhost:3000/settings`)
    - Storybook mode:`npm run visual-audit -- --scope=component:<topic>`
-2. **Layer A mechanical**(auto):WCAG 對比度 + DOM 幾何 assertion + retina screenshot → `snapshots/`
+2. **Layer A mechanical**(auto):WCAG 對比度 + DOM 幾何 assertion + 1x screenshot(retina 需 `--retina` opt-in)→ `snapshots/`
 3. **Layer B AI judgement**(chain `/visual-audit` skill):讀 `snapshots/*.png`,判斷設計合理性(視覺對齊 / 覆蓋限制 / 世界級對照 / typography hierarchy)
 4. Violation 分級:
    - Contrast AA 不過 → **P0**(a11y 強制)
    - Geometry assertion fail → **P0**(機械規則違反)
    - Layer B AI 視覺判斷 finding → 按嚴重度 P0 / P1 / P2
 
-**Gate 規則**:P0 有 → 停下修,不放給 stakeholder;P1 / P2 走跟 Phase 2 Report 同樣 user-decision 流程。
+**Gate 規則**:P0 有 → 停下修,不放給 stakeholder；P1/P2E 自主修復與驗證；只有
+P2H 產品／UI／UX SSOT 真取捨走 exact target-bound user-decision 流程。
 
-**何時可跳**:內部 UI(只給 engineer / admin 看,非 stakeholder / end-user)→ user 明示 skip,但建議跑一次 Layer A 抓 a11y P0。
+**何時可縮窄**:內部 UI(只給 engineer / admin 看,非 stakeholder / end-user)可依
+canonical scope evidence 縮窄 Layer B，但 Layer A a11y P0 不得省略；這是工程判斷，
+不是 user approval gate。
 
 **為什麼 mandatory**:code audit 對 + spec 對,視覺仍可能錯(對比不夠、overlay 疊到文字、跨 OS 捲軸跑版)——這類 bug 只有視覺層抓得到。產品給 stakeholder / user 看時 = stakeholder-visible artifact,必過 Tier 1 gate。
 
@@ -205,26 +223,26 @@ audit 完畢報告應含:
 2. **Summary**:per dimension 的 pass/fail 數
 3. **Findings table**:具體 file:line + severity + fix
 4. **Recommendations**:P0 優先 / 建議修順序
-5. **Next step**:等 user Checkpoint 1 決策
+5. **Next step**:列出已自主處理的 P0/P1/P2E；只有 P2H 才列唯一需要的 user decision
 
 ---
 
 ## Non-goals
 
 - 不 audit DS 本身(走 /design-system-audit)
-- 不改 user 未同意的 P1/P2(僅 P0 可自動修,需 user 決策 P1+)
+- 不把 P1/P2 severity 當成 human gate；依 P2E/P2H authority class 處理。
 - 不 audit 業務邏輯正確性(本 skill 管 UI / DS consumption / design principles,不管 data flow 對不對)
 - 不 replace code review(本 skill 是 pre-review self-check,不是 final QA)
 
 ## Common failure modes
 
-- **Scope 太廣**:掃整個 repo 導致 findings 爆量,triage 崩潰 → 限制 scope 到 feature / folder
+- **Scope 模式混淆**:feature audit 才限制到指定 folder；release/full/deep audit 必依 preflight 全 repo、NO-SAMPLE 掃完，再以 severity/authority 分批 remediation，不得用「finding 太多」縮 scope
 - **Dim 間互相矛盾**:Dim 2 建議用 Empty 但 Dim 3 說 Button 該在某處 — surface 而非自己選
 - **P0/P1 分類偏誤**:把明確 bug 當 P1 / 把 style preference 當 P0 — 嚴格按 audit-checks.md 分類
-- **AI 自行修 P2**:違反 checkpoint 精神,每個 P2 都是設計決策
+- **把所有 P2 當 human gate**:severity 不等於決策 authority；P2E 工程／治理 remediation 自主完成，只有 genuine product/UI/UX SSOT 取捨的 P2H 才停下請 user 拍板
 
 ## References
 
-- [references/audit-checks.md](references/audit-checks.md) — 6 維度具體 grep pattern + rule
+- [references/audit-checks.md](references/audit-checks.md) — 7 維度具體 grep pattern + rule
 - [references/common-misuses.md](references/common-misuses.md) — 常見元件誤用 negative example 庫
 - [references/report-template.md](references/report-template.md) — P0/P1/P2 severity 分類 + report 格式

package/ds-canonical/skills/product-ui-audit/references/audit-checks.md

@@ -1,4 +1,4 @@
-# Audit Checks — 6 維度 grep pattern + rule
+# Audit Checks — 7 維度 grep pattern + rule
 
 每個維度的具體 check。AI Phase 1 parallel 執行時依此 grep + rule 判斷。
 
@@ -12,7 +12,7 @@
 grep -nE '\b(bg-popover|text-popover-foreground|text-muted-foreground|bg-accent|text-accent-foreground|bg-destructive|bg-background|bg-card|text-card-foreground|border-input|text-primary-foreground)\b' {target}
 ```
 
-**Severity**: P0。**Fix**: 對映見 `check_token_hygiene.sh` hook。
+**Severity**: P0。**Fix**: 對映見 token 防線 `lib/_token_hygiene.sh` + `check_opacity_token_usage.sh`。
 
 ### Check 1.2: Tailwind default shadow
 
@@ -20,7 +20,7 @@ grep -nE '\b(bg-popover|text-popover-foreground|text-muted-foreground|bg-accent|
 grep -nE '\bshadow-(sm|md|lg|xl|2xl|inner)\b' {target}
 ```
 
-**Severity**: P0。**Fix**: shadow-sm → shadow-[var(--elevation-100)] / shadow-md → shadow-[var(--elevation-200)] / shadow-lg → shadow-[var(--elevation-300)]。
+**Severity**: P0。**Fix**: shadow-sm → shadow-[var(--elevation-100)] / shadow-md → shadow-[var(--elevation-200)] / shadow-lg → shadow-[var(--elevation-200)](elevation-300 不存在,最高 tier 200)。
 
 ### Check 1.3: Tailwind v4 `[--foo]` shorthand
 
@@ -36,7 +36,7 @@ grep -nE '\[--[a-z][a-z0-9-]*\]' {target} | grep -v '\[&'
 grep -nE '#[0-9a-fA-F]{3,8}\b|rgb\(|rgba\(|hsl\(|hsla\(' {target}
 ```
 
-**Severity**: P0。**Exception**: `#fff` 在 Avatar / Tag 白字變體是 documented cva exception(object map 非 cva,per CLAUDE.md `cva 適用範圍`);anatomy inspector chrome 顏色 highlight(`bg: 'rgba(...)'` in `.anatomy.stories.tsx`)。**Fix**: 改 semantic token(`var(--primary)` / `bg-primary` 等)。
+**Severity**: P0。**Exception**: `#fff` 在 Avatar / Tag 白字變體是 documented cva exception(object map 非 cva,per shared governance `cva 適用範圍`);anatomy inspector chrome 顏色 highlight(`bg: 'rgba(...)'` in `.anatomy.stories.tsx`)。**Fix**: 改 semantic token(`var(--primary)` / `bg-primary` 等)。
 
 ### Check 1.5: 硬寫 px 當應用 token
 
@@ -176,7 +176,10 @@ grep -nE '(Option [A-E]|按鈕[一二三四五]|Rule [A-E]|Variant [A-E]|Placeho
 grep -nE '(TODO:\s*待確認|TODO:\s*decide|FIXME|XXX)' {target}
 ```
 
-**Severity**: P2(必討論)。**Fix**: 若是規格未定應 surface 給 user 決策,不在 code 留模糊 TODO。
+**Severity**:先依 authority classifier 分流。工程 debt、測試缺口、既有 SSOT 落地或可由
+repo evidence 唯一推導的留白 = P2E，自主修復／移除並驗證；只有 TODO 真正代表未決的
+產品／UI／UX SSOT 選擇，且 evidence 收斂後仍有取捨，才是 P2H 並 surface exact target。
+不得把所有 TODO/FIXME/XXX 一律當 user decision。
 
 ### Check 4.3: cva defaultVariants 三方漂移(M3)
 
@@ -192,7 +195,7 @@ grep -nE '(TODO:\s*待確認|TODO:\s*decide|FIXME|XXX)' {target}
 
 例: FileItem `status slot(16px)` + `delete Button sm(28px)` = 不一致 → hover-bg 吃 gap。
 
-**Severity**: P0(世界級 DS 鐵律違反,違反 CLAUDE.md「同 flex 列的互動 slot 幾何鐵律」)。
+**Severity**: P0(世界級 DS 鐵律違反,違反 `packages/design-system/ds-canonical/references/ui-dev-rules.md`「同 flex 列的互動 slot 幾何鐵律」)。
 
 ### Check 5.2: 自造 typography tier
 
@@ -236,7 +239,7 @@ grep -nE '<(div|span)[^>]*onClick='
 
 ## 合法例外(documented)
 
-以下 hit 不是 bug,由既有 spec / CLAUDE.md 記錄為合理例外:
+以下 hit 不是 bug,由既有 spec / shared governance 記錄為合理例外:
 
 - **Avatar 白字**(`text: '#fff'`): cva 適用範圍例外(style prop 驅動用 object map 而非 cva),per `cva 適用範圍` 章節。
 - **Anatomy inspector chrome**(`bg: 'rgba(...)'` in `.anatomy.stories.tsx`): dev-tool highlight 非 consumer UI token。