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

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

@@ -0,0 +1,159 @@
+# Report Template — P0/P1/P2 分類 + 報告格式
+
+---
+
+## Severity 分類
+
+### P0 — 必修(無爭議 bug)
+
+自動 bug / 違反明確 DS 規則 / a11y 必要項缺失:
+
+- Token 硬寫 hex / rgb / shadcn alias
+- Tailwind default shadow(shadow-sm / md / lg)
+- Tailwind v4 `[--foo]` shorthand
+- icon-only 無 aria-label
+- Dialog / Modal 無 DialogTitle
+- 非 button 綁 onClick(a11y 破壞)
+- 巢狀浮層 / 巢狀 Modal(HTML invalid 或 UX 破壞)
+- .claude/references/ui-dev-rules.md「同 flex 列互動 slot 幾何鐵律」違反
+
+**處理**: AI 可直接修(surgical fix),commit 時 user 一併 review。
+
+### P1 — 批次修 + review
+
+設計原則違反 / 元件誤用 / 可改善但無立即 bug:
+
+- Layout primitive 未消費(自 roll Empty / item-layout 等)
+- 硬寫 px 值當應用 token
+- placeholder 文案(Option A/B/C / Lorem ipsum)
+- Primary Button 堆疊
+- 巢狀 Accordion / Tabs / Carousel
+- native overflow 未用 ScrollArea(跨 OS 跑版潛在風險)
+- 硬寫 aspect-* class 未用 AspectRatio
+
+**處理**: 批次 fix,每 Dim 一個 commit,由 user review。
+
+### P2 — 需討論
+
+scope / 設計決策 / 業務判斷:
+
+- cva defaultVariants 三方漂移(可能 intent)
+- Rule B 邊界案例覆蓋不足(scope 決策)
+- 新元件 promotion 判斷
+- 歷史 code 風格差異(rename / refactor 決策)
+- TODO 留白(規格未定)
+
+**處理**: 不自動修,由 user 逐項決策。
+
+---
+
+## Report 格式範本
+
+```markdown
+# Product UI Audit Report
+
+**Scope**: `src/app/features/checkout/` (23 files)
+**Date**: 2026-04-19
+**Dimensions audited**: 6 (Token / Layout primitive / Component / Mindset / Geometry / A11y)
+
+## Summary
+
+| Dim | Total findings | P0 | P1 | P2 |
+|-----|---------------|-----|-----|-----|
+| 1 Token | 3 | 2 | 1 | 0 |
+| 2 Layout primitive | 5 | 0 | 4 | 1 |
+| 3 Component | 2 | 1 | 1 | 0 |
+| 4 Mindset | 4 | 0 | 3 | 1 |
+| 5 Geometry | 1 | 1 | 0 | 0 |
+| 6 A11y | 2 | 2 | 0 | 0 |
+| **Total** | **17** | **6** | **9** | **2** |
+
+## Findings Detail
+
+### P0(必修 6 項)
+
+| # | Dim | File:Line | Finding | Fix |
+|---|-----|-----------|---------|-----|
+| 1 | 1 Token | src/app/checkout/PaymentForm.tsx:87 | 硬寫 `#3b82f6` | 改 `var(--primary)` |
+| 2 | 1 Token | src/app/checkout/Summary.tsx:42 | `shadow-md` | 改 `shadow-[var(--elevation-200)]` |
+| 3 | 3 Component | src/app/checkout/PromoButton.tsx:12 | iconOnly Button 無 aria-label | 加 `aria-label="套用折扣碼"` |
+| 4 | 5 Geometry | src/app/checkout/Actions.tsx:55 | 同 flex 行 Button sm(28)+ICon-only Primary(24)box 不一致 | 統一尺寸,或移 icon 入 Button's startIcon |
+| 5 | 6 A11y | src/app/checkout/ProgressNav.tsx:23 | `<div onClick=...>` | 改 `<button>` 或加 `role="button" tabIndex={0} onKeyDown={...}` |
+| 6 | 6 A11y | src/app/checkout/ConfirmModal.tsx:8 | Dialog 無 DialogTitle | 加 `<DialogTitle>確認結帳</DialogTitle>` |
+
+### P1(批次修 9 項)
+
+{以 Dim 分組,per-Dim table}
+
+### P2(需討論 2 項)
+
+| # | Dim | File:Line | Finding | 為何需討論 |
+|---|-----|-----------|---------|---------|
+| 16 | 2 Layout | src/app/checkout/EmptyCart.tsx:30 | 自 roll icon+title+desc+CTA structure | Consumer 若有品牌化 requirement 可能需 override Empty;需 user 確認 design intent |
+| 17 | 4 Mindset | src/app/checkout/AmountInput.tsx:15 | Input typography 用 `text-[15px]` | 業務要求此欄位字體稍大,需評估 DS 是否加 variant 或 case-by-case 接受 |
+
+## 建議
+
+**先修 P0 6 項**(1 個 commit):無爭議 bug,改完即世界級 baseline。
+**再批次修 P1**(建議按 Dim 分 commit,4 commits):
+1. Token(Dim 1,1 項)
+2. Layout primitive(Dim 2,4 項)— 最大 batch
+3. Component(Dim 3,1 項)
+4. Mindset(Dim 4,3 項)
+
+**最後討論 P2**(stakeholder 共同決策)。
+
+## Next
+
+等待 user Checkpoint 決策:
+- (a) AI 直接修 P0,batch 修 P1,P2 逐項討論
+- (b) 全部 findings 先給 user 自己看,AI 等候指令
+- (c) 只修 P0,其他 park 到下個 sprint
+```
+
+---
+
+## Triage Checkpoint 範本
+
+audit 完,**不可**直接開始修。先 triage 問 user:
+
+```
+🔍 Product UI Audit Report
+
+Scope: {scope}
+Total findings: {N}
+
+P0(必修,無爭議){N0 個} — token 違反 / a11y 必要缺 / 幾何鐵律違反
+P1(批次修 + review){N1 個} — layout primitive 消費 / placeholder 文案 / Button 堆疊
+P2(需討論){N2 個} — scope / 設計決策 / 業務判斷
+
+建議順序:
+1. 先修 P0(1 commit,surgical fix)
+2. 再批次修 P1(每 Dim 一個 commit,共 {N_dims} commits)
+3. P2 逐項討論
+
+你要:
+(a) 按建議順序執行(我開始修 P0)
+(b) 先讓我完整看 findings 再決定
+(c) 跳過 P2,只修 P0+P1
+(d) 縮窄 scope 到 {sub-folder}
+```
+
+絕對不可:AI 自行決定修哪些,必過 triage。
+
+---
+
+## 合法例外聲明範本
+
+若 audit hit 被判定為合法例外(per CLAUDE.md 或 spec documented),在 report 中明文標示:
+
+```markdown
+### Documented exceptions(非 findings,供參考)
+
+| File:Line | Pattern | 例外理由 |
+|-----------|---------|---------|
+| Avatar.tsx:46 | `text: '#fff'` | cva 適用範圍例外(style prop 驅動 object map),per CLAUDE.md `cva 適用範圍` |
+| Rating.spec.md:73 | `bg-warning` 黃星 | 世界級 convention(Amazon / Yelp / Google),documented |
+```
+
+讓 user 知道 AI 有注意到但判斷為合法 — 防被誤解為遺漏。

package/ds-canonical/skills/propose-options/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: propose-options
+description: Auto-invoke when listing options / 建議 / 候選方案. Forces inline 7-Q principle check(M8 benchmark / M17 SSOT / Rule-of-3 / M10 subsumption)per option BEFORE listing. Failures filtered or labeled. Codifies「verify before propose」runtime discipline.
+---
+
+# /propose-options — Propose-time 7-Q Gate
+
+**目的**:Claude 對 user 提建議 / 列 option list 時,**先跑 7 題原則自檢**,通過才寫進回覆。Reject 的不列 OR 列出時標 fail 原因。
+
+**對齊**:
+- CLAUDE.md mindset #1(不取巧)+ #2(消費既有)+ #5(猶豫就問)+ #6(meta 抽象)
+- M8 benchmark / M17 SSOT / M12 binary rule / 治理「加規則前 3 題」
+- 本 skill 是上述 meta 的**propose-time 落地** — meta 寫成文字不夠,要 mechanical workflow 釘住
+
+## When to invoke
+
+**強制 invoke** 在以下情境(不靠 user 提醒):
+- 寫「Option A / B / C」「選 A / B」「3 個方向」 類列表
+- 寫「建議做」「該做」「提議」 類 verb
+- 寫「c. d. e.」 候選清單(像本 conv 我給 c hook + d M18 那種)
+- 任何「if you sign-off, I'll do X」 提案
+
+**不 invoke**:
+- User 已明示要做 X(只是 execute,不 propose)
+- 純資訊回答(描述現況,不選擇)
+- Bug fix 的 surgical solution(無 option,直接修)
+
+---
+
+## Workflow(強制 7 題,缺一就 reject 此 option)
+
+每個 candidate option 過以下 7 題,inline 寫進回覆:
+
+### Q0 — **Pre-ASK self-verify problem 真存在**(2026-05-18 加,absorbs Sheet/inline-action/SurfaceBody 三題誤判事件)
+
+**問**:propose 給 user 拍板前,是否已**grep DS-wide + Read 相關 spec.md / tsx + Read consumer usage** 確認 problem **真存在**?
+
+**為何**:M18 / M23 / M29 都管「決策過程紀律」,但**propose 給 user 前的「problem 真存在?」基本判斷**沒 codify。本 session 我 propose 3 題(Sheet 補 / 5 元件 migrate inline-action / 5 元件 migrate SurfaceBody)**全部不是真 problem** — Sheet spec 已完整、inline-action 已全消費、SurfaceBody 有意設計不該動 — 但我 propose 給 user 拍板浪費 user 時間 + 動搖 user 信任。
+
+**強制檢查**:
+1. **grep 既有 code DS-wide** — 「該 migrate 的 X 元件」真沒消費 primitive?(`rg "<primitive>" packages/design-system/src/components/<X>`)
+2. **Read 相關 spec.md** — spec 有沒有明文 codify 該設計是有意 / 例外 / 合法分支?(本 session 例:Tag inline-action colored host 例外是 spec L52-54 明寫的)
+3. **Read consumer usage** — 該 pattern 已在 N 處 work fine?N ≥ 3 → 該 pattern 是 working canonical,不是 problem
+4. **反問**:「如果 user 答 A,我會做什麼?該動 K 個 file?那 K 個 file 真有問題嗎?還是我假設的?」
+
+**Fail criteria**(任一命中 → reject propose,不丟給 user):
+- 沒 grep 既有就斷言「N 元件缺 X」
+- 沒讀 spec 就斷言「現況違反 canonical」
+- 「我推 A 因 X 比較統一」但 X 已是合法分支(spec 明文)
+- propose 是 mass-migration 但沒列具體哪 K file file:line 需動
+
+**Pass criteria**(全過才能 propose):
+- ✅ 列具體 file:line 證據 problem 存在
+- ✅ 列 spec.md 段落 cite 證明「現況違反 spec」
+- ✅ counter-example scan 跑過:DS 其他元件用一樣 pattern → 反證「這不是 problem」
+- ✅ 給 user 的 option list 含「C. 不動(理由)」且 C 經 grep verify 不是 cheap escape
+
+**例**:
+- ✅ "grep 結果 Input/NumberInput/LinkInput 3 file 都未消費 ItemInlineAction(file:line)+ spec.md L60 表格列為 expected consumer → 真 gap"
+- ❌ "5 元件應該 migrate"(沒 grep / 沒 cite spec / 不知道 K 元件已 migrate / 是 colored host 合法例外)
+
+**對應 hook**:`check_propose_pre_grep_verify.sh`(2026-05-18 加,Edit/Write `*.md` 內含「propose」/「請拍板」/「決策」keyword 但近 N turn 無 grep/Read tool call → P1 warn)
+
+### Q1 — M8 World-class benchmark
+**問**:本 option ≥ 3 家 world-class DS / framework / canonical 有對照嗎?
+**列**:具體實作名 / API 指向 / docs URL
+**Fail**:< 3 家對照 → option 未成熟,不該 propose
+**例**:
+- ✅ "Polaris IconButton padding-free / Atlassian button-iconOnly p:0 / Material UI MuiSvgIcon flex-shrink:0"
+- ❌ "感覺合理 / 可能對 / 沒查"
+
+### Q1' — **M23 DS internal canonical 優先 grep**(2026-05-03 加,chevron 事件後)
+**先 grep DS 既有 token / variant / pattern 命中?有 → 必對齊,Q1 外部 benchmark 只是輔證。**
+**問**:propose 的 visual decision(color / size / spacing / typography / state)是否已 grep `packages/design-system/src/tokens/` + 近親 component spec/tsx 確認沒命中既有?
+**Fail**:跳過 grep 直接搬 world-class → M23 違反(本 conv chevron 用 Ant 5 家 muted 覆蓋 DS 內 icon-only Button = neutral-9 canonical → user 4 輪糾正)
+**例**:
+- ✅ "grep `text-foreground` 已是 icon-only Button 預設(neutral-9 / 85%)→ 對齊;Ant cite 為輔證"
+- ❌ "Ant / Material muted → 直接套(沒 grep 內部 canonical)"
+
+### Q2 — M17 SSOT 必可傳播
+**問**:本 option 動到的 canonical 有真正可執行 SSOT 嗎(token / primitive / utility)?還是只在 markdown 文字?
+**Fail**:只增加 markdown 文字、沒提供 mechanical enforcement → 假 SSOT
+**例**:
+- ✅ "新 utility class `ICON_ONLY_BASE` 共用,2 host import"
+- ❌ "spec 寫一行 rule,未來誰記得就好"
+
+### Q3 — Rule-of-3 SSOT placement
+**問**:本概念在現有 home 已 ≥ 3 處出現?該選 SSOT,其他 pointer。新加的話,SSOT 該住哪 home?
+**Fail**:concept 已 ≥ 3 處仍要新增 home / 重複描述 → 違 Rule-of-3
+**例**:
+- ✅ "uiSize.spec.md 是 SSOT,button.spec.md / segmented-control.spec.md 1 行 pointer"
+- ❌ "每個 spec 各自寫一份"
+
+### Q4 — M10 下游吸收
+**問**:本 option 加入後,既有哪些 rule / memory / bug case 被吸收可刪?
+**Fail**:純 append 沒 retire,違反「上游加 = 下游減」 + 治理 anti-bloat
+**例**:
+- ✅ "M18 加,M12 部分 overlap 但 scope 不同共存(說明)"
+- ❌ "新加 M18,既有 M-row 全保留(沒檢查)"
+
+### Q5 — Issue list 100% mapped(2026-05-05 anti-drift,user trigger 第 5 次後新增)
+**問**:plan iteration / option list 改版時,user 提的**所有** raised issue 是否 100% mapped 到本版的 step / option / 評估?**未 mapped 的逐條 explicit 標**:`done` / `folded into Step X` / `informational(無實作)` / `dropped(原因)` / `pending`。
+**Fail**:silent drop / 沒 mapping table / fold 進 step 沒 trace
+**例**:
+- ✅ "Issue 1-14 列 mapping table,Issue 3+13 標 informational,其他 11 條 mapped"
+- ❌ "改版只列新 Step,沒 walk-through user 之前提的 issue list"
+
+---
+
+## Workflow Output Format
+
+對 user 回覆中的 option list 必含 **inline 7-Q 表 + Issue mapping**(plan iteration 場景):
+
+```markdown
+| 選項 | M23 DS grep | M8 benchmark | M17 SSOT | Rule-of-3 | M10 下游 | Issue cover | 結論 |
+|---|---|---|---|---|---|---|---|
+| A | DS 已有 X token,對齊 | Polaris/Atlassian/Material 輔證 | 抽 utility 共用 | 0 處 SSOT 新增 OK | 可刪 X 條冗餘 | covers 8/14 | **PASS,推薦** |
+| B | 沒 grep | 只查 1 家 | 純 markdown rule | 已 3 處,無新 SSOT 動 | 純 append 沒 retire | covers 4/14 | **REJECT(M23+M8 雙 fail + Q5 不全)** |
+```
+
+**Plan iteration 必含 Issue ↔ Step 完整 mapping table**(不可只列新 step 表,user 看不到原 issue trace):
+```markdown
+| # | Issue (按 user 提出順序) | 處理 |
+|---|---|---|
+| 1 | <user 原文 issue> | Step X / informational / dropped(reason) |
+| ... | ... | ... |
+```
+
+**所有 fail 過 7-Q 的 option 必明示 reject + 原因**,不只 list 不過的。User 看見 reject 過程才能信 propose 過原則。
+
+---
+
+## Edge cases
+
+### 緊急 / surgical bug fix
+不需走全 7 題(沒 option list,直接修)。但 commit message 仍應簡述「修法已知 root cause + 不取巧」(對齊 mindset #1)。
+
+### Option 內含 sub-option(nested)
+每層各自跑 7 題。Skill 不限深度但實作上 ≥ 3 層 nested 已是設計問題,user 該停下重整。
+
+### User 已明示要 X(非 propose)
+不跑 skill。直接執行。
+
+---
+
+## 為什麼這 skill 必要(本 session 教訓)
+
+User 已就「為什麼會給錯誤建議」糾正 ≥ 3 次:
+- session 初:G6/G7/G8 推力,我自己沒 dogfood test → 第 3 次問才補
+- 中:c hook + d M18-inner-area propose,**user sign-off 前剛好我自己覺察跑 7-Q 才撤回**
+- 末:user 直接質問「為什麼會給錯誤建議?如果我答應了會直接執行嗎?」(本 skill 的觸發)
+
+**Infra G6/G7/G8 是 post-edit / session-start 防線,沒 propose-time gate**。Claude Code event model 沒 OnAssistantMessage hook,**只能靠 model-runtime 紀律 + skill self-invoke**。本 skill 就是 mechanical 補位 — invoke 時讀本檔,7-Q 表格自然寫進回覆。
+
+---
+
+## Self-improvement capture
+
+每次 invoke 完,session 結束前自問:
+- (a) 是否每個 option 真跑了 7-Q 還是糊弄填表?
+- (b) 是否有 reject option 曾被 list?(reject 不該被列出)
+- (c) 是否 user 仍質疑 propose 品質?(若是 → 7-Q 沒抓到的 gap → 加 Q5)
+
+回填到本 SKILL.md 或 CLAUDE.md M18(若需 escalate)。
+
+---
+
+## 與其他 skill 對位
+
+| Skill | scope |
+|---|---|
+| `pre_write_subsumption_check.sh`(hook)| Edit/Write 已發生時 |
+| `post_edit_canonical_interrogate.sh`(retired/未實作 — mindset enforcement)| 寫完 canonical 後 3 題 |
+| `check_governance_compliance.sh`(retired/未實作 — 靠 `check_propose_pre_grep_verify.sh` + 加 hook 前 3 題)| 寫新 hook 7 題 |
+| **本 skill** `/propose-options` | **propose-time(寫進 user 回覆前)7 題** |
+
+4 個正交 — propose 前 / write 前 / write 中 / write 後 全 cover。

package/ds-canonical/skills/prototype/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: prototype
+description: Build UI prototypes / MVPs via a structured UX workflow — benchmark world-class, evaluate against DS + business, produce 2-3 shortlisted candidates as Storybook explorations, self-audit via product-ui-audit, let stakeholders decide. Invoke via /prototype ONLY when user explicitly uses the words「prototype」「MVP」「原型」 in their message (e.g.「做 prototype」「做 MVP」「做原型」「prototype 一個 X」). **DO NOT auto-invoke on casual phrases** like「怎麼做世界級」「給我幾個方案」「比版本」「比幾個版本」「還能怎麼做」「有哪些選項」— these are ambient conversation / thought-partnering, not explicit skill requests; instead ask「要走 prototype skill 正式流程嗎?還是只想先口頭討論?」to confirm before invoking.
+---
+
+# Prototype Workflow
+
+Purpose: embody the UX designer's mental model for BUILDING PROTOTYPES — never design by gut; benchmark world-class, filter against DS + business, build multiple shortlisted proposals, self-audit, let stakeholders decide.
+
+This skill is the **structured version** of CLAUDE.md Mindset #1「對標世界級」+ #4「真實業務場景」+ #5「猶豫就問」,and the orchestrator for `src/explorations/` folder usage.
+
+## When to run
+
+**明確觸發**(直接 invoke):user 用「prototype / MVP / 原型」明確字眼。例:「做 prototype」「做 MVP」「做原型」「prototype 一個 X」「做幾個 prototype 版本 compare」。
+
+**模糊觸發**(先 clarify):「給我幾個方案」「怎麼做世界級」「有哪些選項」「比版本」 — 多為 thought-partnering,**先問**「要走正式 prototype skill 還是先口頭討論?」
+
+**不觸發**:已確定單一 feature(直接 implement)/ 單一 pattern 諮詢(直接答)/ 產品交付(走 `/delivery-handoff`)/ DS 本身稽核(走 `/design-system-audit`)/ consumer UI 檢查(走 `/product-ui-audit`)。
+
+**生態位**:`/prototype` → Phase 3.5 chain `/product-ui-audit` gate → stakeholder 決定 → 採用後 `/delivery-handoff`。新 primitive 採用後,加入 DS 時跑 `/design-system-audit` 確保內部健康(正交關注點)。
+
+## Preconditions
+
+- User has briefed a feature / problem / user need (will be clarified in Phase 0)
+- Working directory is project root
+- CLAUDE.md read fully(DS 既有 primitives / layout primitives 清單 / mindset)
+
+---
+
+## 6-Phase Workflow
+
+### Phase 0 — Clarify
+
+**Input**: user's initial request(可能模糊)
+
+**Process**: AI asks user 3-5 targeted questions to lock down:
+- 要做什麼(feature / flow / component)
+- 給誰用(primary user persona)
+- 解決什麼 jobs-to-be-done(具體使用情境,不是 "better UX")
+- 量化指標(若有)(e.g., "減少 50% 流失率")
+- Constraints(mobile-first? accessibility level? 時程?)
+
+**Output**: 一段 1-liner summary 確認 alignment。
+
+### ⚠️ Checkpoint 0 — User confirms framing
+
+User approves the problem framing OR clarifies. Do NOT skip to benchmarking without a clean frame.
+
+### Phase 1 — Benchmark research
+
+**Input**: Phase 0 framing
+
+**Process**: Scan 5+ world-class references. See `references/benchmark-sources.md` for the canonical list of DS + world-class SaaS + industry-specific references.
+
+For each reference,收集**兩類資訊**:
+
+**A. 視覺 / 互動(表層)**:
+- How do they solve this problem?
+- Screenshot(WebFetch or user provides)
+- Key mechanics:layout / interaction pattern / states / a11y
+- 1-2 line summary of approach
+
+**B. OOUX 層(資訊架構深度對標)**:
+- **Core objects** identified(名詞清單 + attributes)
+- **Relationships**(object 間如何連,NOM highlights)
+- **CTAs per role**(key actions each role 對每 object 可做什麼)
+- **UI shape observed**(同一 object 在 list / card / detail / inline 多種 shape 下 attributes 怎麼 progressive disclose)
+
+**為什麼加 OOUX 欄**:視覺只看外型會抄到形式,object model 才是 IA 深度。做完 5 家 benchmark 後,你會發現哪些 object 是業界共識 / 哪些命名是該產品獨有 — 這是 Phase 3 自己建 Object Map 的原料。
+
+詳細 OOUX 分析方法與範本見 [`references/ooux-template.md`](references/ooux-template.md)「Phase 1 用法」節(內含 Linear issue tracking 完整範例)。
+
+**Output**: Markdown scan table(視覺 + OOUX 兩 section):
+
+```
+| Reference | Approach | Key mechanics | Screenshot |
+|-----------|----------|---------------|------------|
+| Linear    | ...      | ...           | link       |
+| Stripe    | ...      | ...           | link       |
+| ...       |          |               |            |
+```
+
+**Report format**: report back to user as the scan table. Do not advance to evaluation yet.
+
+### ⚠️ Checkpoint 1 — Research scope confirmation
+
+User reviews the scan. Options:
+- `(a)` Research is sufficient → proceed to Phase 2
+- `(b)` Add references X, Y → extend Phase 1
+- `(c)` Scope changed → restart Phase 0
+
+### Phase 2 — Evaluate candidates
+
+**Input**: Phase 1 scan table
+
+**Process**: for each candidate,score on 4 axes(see `references/evaluation-matrix.md`):
+
+| Axis | Scale | Meaning |
+|------|-------|---------|
+| 優缺 | Pros / Cons bullets | 每個候選的獨立評估 |
+| DS 一致性 | 1-5 | 能用多少既有元件 / primitives?新元件要不要造? |
+| 業務 fit | 1-5 | 符合 Phase 0 jobs-to-be-done 多深? |
+| 複雜度 | 1-5(低複雜度 = 5) | 開發成本 / 維護負擔 |
+
+**Output**: 評分矩陣 + narrative summary per candidate。
+
+Narrative 必含:
+- 對齊 Mindset #1:「我們 vs 這家做法一樣 / 不同的理由」
+- 對齊 Mindset #4:「搭我們的業務情境會不會水土不服」
+- 對齊 Mindset #2:「這個 pattern 我們有對應 primitive 嗎?」
+
+### ⚠️ Checkpoint 2 — Shortlist decision(MUST ASK)
+
+這是最關鍵的 checkpoint。presenting 評分後,user 決定:
+- 哪 2-3 個候選進 shortlist(要實際做原型)
+- 哪些直接 drop(排除理由寫在 exploration notes)
+- 是否需要混搭(A 的 interaction + B 的視覺 = 新候選 C)
+
+**絕對不可**憑 AI 自己評分就挑 shortlist。這是設計決策,stakeholder 要參與。
+
+### Phase 3.0 — Build Object Map(ORCA,design 前強制)
+
+**Input**: shortlist + Phase 1 benchmark 的 OOUX 分析
+
+**Process**: 在寫任何 candidate story 之前,**先做 Object Map**(全體 candidate 共享同一個)。ORCA 4 步:
+
+1. **O** Objects:feature 的核心名詞(2-7 個理想;命名三重 test)
+2. **R** Relationships(NOM):object 間關聯(1:1 / 1:many / optional)
+3. **C** CTAs per role:每角色對每 object 的動作清單
+4. **A** Attributes per object:core / metadata / identifying
+
+**Output**:`src/explorations/{topic-slug}/notes.md` 增補 OOUX section(見 `references/ooux-template.md`「Phase 3.0」範本 + Step 5 UI Shape → DS 元件映射表)。
+
+**為什麼共享同一 Object Map**:3 個 candidate 差異應在 **UI shape + progressive disclosure + CTA ordering**,不在 object 定義本身。若 A candidate 把 Task 拆成 Task + Subtask、B candidate 只有 Task,stakeholder 比稿會變成「比 data model」失焦。除非該 feature 本質就是 data model 辯論,否則 object 定義應一致。
+
+**何時跳過**:極小 feature(單一 button / 1-object 開關)可跳過 Phase 3.0,在 notes.md 明文標示「feature 範圍小,跳過 ORCA」。
+
+---
+
+### Phase 3 — Design each shortlisted candidate
+
+**Input**: shortlist(2-3 items)+ Phase 3.0 產出的 Object Map
+
+**Phase 3.0a — SSOT 5-step pre-check**:寫任何 candidate code 前必過 CLAUDE.md「SSOT 消費 canonical」+ memory `feedback_proactive_5layer_pipeline.md`「5-step pre-check」(SSOT 在 memory + CLAUDE.md,本 skill 不重複)。`check_story_invariants.sh` R1 anatomy(原 check_story_anatomy.sh folded 折入)PreToolUse 是最後安全網,但 5-step 是事前 discipline。
+
+**Process**: 每個 candidate 建一個 exploration story,**各 candidate 共享 Object Map 但差異在 UI shape + CTAs 順序**。see `references/proposal-template.md` for structure。
+
+目錄結構:
+```
+src/explorations/{topic-slug}/
+├── notes.md                              # 本 topic 概述 + Phase 2 評估摘要 + 3 候選簡介
+├── {CandidateA}.stories.tsx              # 候選 A 原型(Storybook)
+├── {CandidateB}.stories.tsx              # 候選 B 原型
+└── {CandidateC}.stories.tsx              # 候選 C 原型
+```
+
+Storybook title 慣例(不與 Components/ 衝突):
+`Explorations/{Topic}/{CandidateName}`
+
+每個 candidate story 必含:
+- 標題說明(candidate 名 + 一句話 positioning)
+- 實際可互動 prototype(用 packages/design-system/src/ 既有元件!)
+- 若需新元件,在 notes.md 標示「此 candidate 需新增 X 元件(若選用此版)」
+- 3 種以上使用場景示範(對齊 Mindset #4 真實業務場景)
+
+**DS 一致性鐵律**:
+- 優先用既有 `packages/design-system/src/components/` 元件
+- 若需新元件 / primitive,**notes.md 明文標示**(不偷偷 add 到 components/)
+- 所有 token / layout primitive 按 CLAUDE.md「既有 layout primitives 清單」消費
+
+### ⚠️ Checkpoint 3 — 新元件 / primitive 需求
+
+若任一 candidate 需要新 DS 元件,**必須 ASK**:
+- 此新元件是本 candidate 獨有?還是跨 candidate 共用?
+- 若被選中,值得升級到 Components/ 嗎?
+- 三重命名 test 過嗎?(見 CLAUDE.md)
+
+**絕對不可**在 explorations/ 階段就偷偷 add 到 Components/,會污染 DS。
+
+### Phase 3.5 — Self-audit(stakeholder-gate,強制進階 6 維)
+
+**Input**: Phase 3 完成 + Checkpoint 3 資源決策完畢的 exploration stories
+**核心原則**:exploration code 不該直接進 Phase 4 給 stakeholder 看 — AI 必先掃 6 維(對齊 CLAUDE.md `# 稽核 canonical` M6:stakeholder-visible 產出 → 強制進階模式)。
+**Output**: per candidate 6 維 report,彙整成 Phase 3.5 gate report。
+
+**6 維 + 執行順序 + Gate 規則完整詳細** → `references/audit-checks.md`(SSOT;本 skill 不重複)。重點:
+- D1-D5 chain `/product-ui-audit` / `/performance-audit` / `/ux-audit` / `/visual-audit`
+- D6 chain `principle-audit-protocol.md`(設計原則自檢 4 子維)
+- 前置:M15 Flow snapshot coverage(無 OpenSnapshot story = block audit)
+- Gate 規則:P0 必修 / 高 impact 必修 / D6 疑點 STOP 等 sign-off
+
+### Phase 4 — Present & stakeholder decision
+
+**Input**: 3 個 exploration stories
+
+**Process**: 撰寫 summary(放在 `notes.md`):
+- 每 candidate 一句話重述 positioning
+- 每 candidate 3 個適合場景 / 3 個不適合場景
+- 推薦(AI 可 recommend 一個,但表明 user 決定)
+- Link 到各自 Storybook route
+
+**Output**: summary markdown + Storybook URL list → 丟給 stakeholder 評估。
+
+### ⚠️ Checkpoint 4 — Final decision & graduation
+
+User / stakeholder 決定採用某 candidate 後:
+- `(a)` 採用 A,promote 到 `packages/design-system/src/` 正式(若需新元件)或消費既有元件建正式 UI
+- `(b)` 採用 A 但修改(進第二輪 proposal)
+- `(c)` 混搭 A+B 新 hybrid(新 exploration)
+- `(d)` 全部不採用(保留 explorations/ 作紀錄,也是有價值的 ruled-out)
+
+**Graduation 流程**:若升級到正式,在 `explorations/_archive/` 備份 exploration(per CLAUDE.md `# 元件完成 + Exploration`:比稿定案升級 patterns/ 或 components/,舊比稿保留作紀錄),正式 code 進 design-system/。
+
+### Phase 5 — Cleanup
+
+刪除 drop 的 exploration 或移 `_archive/`。更新 `src/explorations/` 索引。
+
+---
+
+## Non-goals
+
+- 不在 explorations/ 階段做 detail pixel polish(focus 在 pattern 可行性 + 使用者反應)
+- 不自動 promote exploration 到 Components/
+- 不代替 stakeholder 決策(AI 可 recommend,但 flag「需 user / stakeholder 決定」)
+- 不跳過 benchmark 憑直覺造 pattern(違反 Mindset #1 / #2)
+- 不在單個 exploration 塞多個 pattern(一個 story = 一個明確 candidate)
+
+## Common failure modes
+
+- **Phase 1 太淺**:只看 shadcn / Material 就收工。世界級 SaaS(Linear / Stripe / Notion / Figma)的在地解法才是精華
+- **Phase 2 評分偏誤**:對 DS 一致性加權過低,結果 shortlist 全是「要造 5 個新元件」 — 違反 DRY
+- **Phase 3 太快**:candidate 只做 1 個 story 沒展示多場景 — stakeholder 看不出 robustness
+- **Checkpoint 2 skip**:AI 自己挑 2 個 shortlist 用戶沒過目 → 建完才發現方向全錯
+- **Phase 4 recommend 太強勢**:summary 幫 user「決定」,違反 skill 精神(exploration 就是讓 stakeholder 評估)
+
+---
+
+## References(`references/`)
+
+- `benchmark-sources.md` 世界級對標 + OOUX
+- `ooux-template.md` ORCA / Object Map / NOM / CTA(Sophia V. Prater)
+- `evaluation-matrix.md` 4 軸評分 + 決策規則
+- `proposal-template.md` explorations/ + Storybook 結構
+- `checkpoints.md` 5 MUST ASK 範本 + 歷史 failure mode

package/ds-canonical/skills/prototype/references/audit-checks.md

@@ -0,0 +1,37 @@
+# Phase 3.5 Self-audit checklist(/prototype 用)
+
+對齊 CLAUDE.md `# 稽核 canonical` M6(stakeholder-visible 產出 → 強制進階模式)。比稿本質是「給 stakeholder 選視覺方向」,6 維任一沒 audit 好就 present = 比稿品質失準。
+
+## 6 維對應 skill
+
+| 維度 | Skill | Audit scope |
+|------|-------|-------------|
+| **D1 設計語言一致** | `/product-ui-audit` | 6 dim(token 紀律 / layout primitive / 元件使用 / mindset / 幾何 / a11y) |
+| **D2 程式語言一致** | `tsc --noEmit` + lint | exploration 目錄 |
+| **D3 元件效能** | `/performance-audit` | render / memo / bundle(per candidate) |
+| **D4 UX 行為** | `/ux-audit` | keyboard / focus / ARIA / animation |
+| **D5 視覺品質** | `/visual-audit` | Layer A mechanical + Layer B AI judgement |
+| **D6 設計原則自檢(4 子維)** | chain `principle-audit-protocol.md` | 合理 / 一致 / 無矛盾 / 完整 |
+
+## 執行順序
+
+0. **Flow snapshot coverage 前置檢查**(M15,Phase 3.5 gate 前必過):exploration 必含 OpenSnapshot 類 stories,涵蓋所有 UI flow state(initial / open / confirm / success / error / empty)。Pattern:`defaultOpen` / `useState(true)` / play() interaction 讓 Playwright 能截圖。未提供 = block audit。
+1. `npm run visual-audit -- --scope=component:{topic-slug}`(D5 Layer A,產 snapshots)
+2. Chain `/product-ui-audit`(D1)scope 到 `src/explorations/{topic-slug}/`
+3. Chain `/performance-audit`(D3)scope 到 exploration
+4. Chain `/ux-audit`(D4)scope 到 exploration
+5. Chain `/visual-audit`(D5 Layer B AI judgement)讀 `snapshots/*.png`
+6. **D6 真 scan**:chain `.claude/skills/design-system-audit/references/principle-audit-protocol.md` 對 exploration code 跑 4 子維;依判斷公式 auto / STOP
+7. **Self-improvement capture**(強制 Phase F step,見 CLAUDE.md `# 治理 canonical`)
+
+## Gate 規則(嚴格)
+
+| Finding | 處理 |
+|---------|------|
+| D1 / D2 P0(token alias / 硬色 / 幾何違反 / tsc error) | 必修 |
+| D5 Layer A violation(contrast AA 不過 / geometry assertion fail) | 必修(視同 P0) |
+| D3 / D4 高 impact finding(render 爆 / keyboard 不通 / ARIA 缺) | 必修 |
+| D5 Layer B 明顯設計問題 | 必修 OR notes.md 明文 rationale |
+| D6 canonical 疑點 | 不 block,列 STOP 區等 user sign-off |
+| Code P1 > 3 筆 | 建議修,user 可決定先 present 或先修 |
+| 無 P0 + Layer A 乾淨 + D3/D4 無高 impact | 可進 Phase 4 |