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

package/ds-canonical/fork/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(用 node_modules/@qijenchen/design-system/src/ 既有元件!)
+- 若需新元件,在 notes.md 標示「此 candidate 需新增 X 元件(若選用此版)」
+- 3 種以上使用場景示範(對齊 Mindset #4 真實業務場景)
+
+**DS 一致性鐵律**:
+- 優先用既有 `node_modules/@qijenchen/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 到 `node_modules/@qijenchen/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/fork/skills/prototype/references/audit-checks.md

@@ -0,0 +1,38 @@
+> **⚠️ 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 跑。
+# 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 `node_modules/@qijenchen/design-system/ds-canonical/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 |

package/ds-canonical/fork/skills/prototype/references/benchmark-sources.md

@@ -0,0 +1,94 @@
+# Benchmark Sources — 世界級對標清單
+
+Phase 1 research 的 go-to 資源。**每次 research 至少挑 5 家,跨 DS + SaaS + platform**(不要全抓 component library)。
+
+---
+
+## Tier 1:Design System 官方文件(規則 + rationale)
+
+必掃 — 他們寫出 **why**,不只是 **what**。
+
+| DS | 公司 | 強項 | URL |
+|----|------|------|-----|
+| **Polaris** | Shopify | e-commerce UX 完整 / Content guideline 深 | polaris.shopify.com |
+| **Material 3** | Google | 跨平台 / a11y 最完整 / motion spec | m3.material.io |
+| **Atlassian Design System** | Atlassian | enterprise SaaS(Jira/Confluence)/ tone of voice | atlassian.design |
+| **Ant Design** | Ant Group | data-heavy 後台 / form 元件最豐富 | ant.design |
+| **Carbon** | IBM | enterprise / data viz / 大表單 | carbondesignsystem.com |
+| **Apple HIG** | Apple | native macOS/iOS patterns / 手勢 | developer.apple.com/design/human-interface-guidelines |
+| **Primer** | GitHub | dev tools UX / code-adjacent patterns | primer.style |
+| **Base Web** | Uber | mobility / high-density data tables | baseweb.design |
+| **Fluent 2** | Microsoft | enterprise + Windows 11 native | fluent2.microsoft.design |
+| **Spectrum** | Adobe | creative tools / complex forms | spectrum.adobe.com |
+
+## Tier 2:Shadcn-style component libraries(實作參考)
+
+Shadcn / Radix 為起點,看其他 variants 還做了什麼。
+
+| 資源 | 強項 |
+|------|------|
+| **shadcn/ui** | Radix + Tailwind,我們 DS 的起點參考 |
+| **Radix UI** | 無樣式 primitive,a11y / keyboard 最完整 |
+| **React Aria** | Adobe 的 a11y-first hook 集 |
+| **Headless UI** | Tailwind team 出品 |
+| **Chakra** | 成熟 React DS |
+| **Mantine** | 資料密集 components |
+| **Park UI** | Ark UI based,pattern composition 示範 |
+
+## Tier 3:World-class SaaS(實際產品 UX)
+
+這層是精華 — DS 文件寫不出的 **在地解法**(empty state 怎麼寫 / onboarding 節奏 / 錯誤回饋)。
+
+| 類別 | 推薦產品 | 觀察重點 |
+|------|---------|---------|
+| **Project mgmt** | Linear / Jira / Asana / Notion / ClickUp | task states / filter / bulk actions |
+| **Payments** | Stripe / Square / Paddle | form clarity / confirmation flows / error handling |
+| **Design tools** | Figma / Sketch / Adobe XD / Framer | inspector panels / layers / keyboard shortcuts |
+| **Dev tools** | Vercel / Netlify / Railway / Linear | deployments / logs / CLI-to-UI parity |
+| **Communication** | Slack / Discord / Teams / Zoom | DM vs channels / presence / rich composer |
+| **Analytics / Data** | Amplitude / Mixpanel / Datadog / Grafana | chart types / time range / segment filter |
+| **Content** | Notion / Medium / Substack / Ghost | editor UX / share / versioning |
+| **Commerce** | Shopify / Amazon / IKEA / UNIQLO | product listing / checkout / review |
+| **Travel** | Airbnb / Booking / KKday | search / compare / booking flow |
+| **Finance** | Monzo / Revolut / Wise / PayPal | transaction list / security UX / currency |
+
+## Tier 4:Platform conventions(OS 慣例)
+
+| 平台 | 何時參考 |
+|------|---------|
+| **iOS HIG** | mobile-first / touch gesture / share sheet |
+| **Android Material** | floating action / gesture nav / bottom sheet |
+| **macOS** | menu bar / window chrome / keyboard-first |
+| **Windows 11 Fluent** | tile / acrylic / taskbar interactions |
+| **Web A11y (WCAG)** | keyboard / screen reader / color contrast |
+
+---
+
+## 研究步驟
+
+每個 reference:
+1. **找到該 feature 的 canonical page / screenshot**(1 張截圖就夠,不要試圖全抓)
+2. **3 個問題**:
+   - 他們的核心機制是什麼(layout / interaction / states)?
+   - 哪些是「這家獨特」vs「業界共識」?
+   - 我們若照做,會 fit 業務嗎(Phase 0 framing)?
+3. **1-2 行 summary** — 避免長 essay,user 會讀 5+ 筆,精簡才 scannable
+
+---
+
+## 反-patterns(避免 Phase 1 失敗)
+
+- ❌ 只抓 3 家相同 DS(`shadcn + Material + Ant`)— 沒有多樣性
+- ❌ 全抓 component library 不看 SaaS 實作 — 漏掉在地解法
+- ❌ 用 AI 描述而非看實物 — 描述容易失真,截圖是真實
+- ❌ 跳過 Platform Tier — mobile / keyboard 盲點多
+- ❌ Tier 3 只看「大公司」— 小而精(Linear / Notion / Vercel)常比大廠創新
+
+---
+
+## 截圖取得建議
+
+- **WebFetch** 官方 docs / public blog posts
+- **User 提供**(最快 / 最準 — 他們自己用產品)
+- **公開 UX repos**(dribbble / behance — 僅供視覺參考,不等於真實 interaction)
+- 避免 demo videos(長 / 不精準 / 截圖才好比對)

package/ds-canonical/fork/skills/prototype/references/checkpoints.md

@@ -0,0 +1,191 @@
+# Checkpoints — MUST ASK 時機(skill 內的 user 決策點)
+
+5 個不可略過的 checkpoint。past 失敗都因 AI 自行決定了該問的事。
+
+---
+
+## Checkpoint 0 — Problem framing(Phase 0 後)
+
+**格式範本**:
+
+```
+🎯 Phase 0 Framing(請確認)
+
+問題:{1-liner 重述 user 需求}
+Primary user:{persona}
+Jobs-to-be-done:{具體動機}
+Constraints:{mobile? a11y? 時程?}
+
+對嗎?
+(a) 對,進 Phase 1 benchmark
+(b) 以下需修正:...
+(c) 情境不同 — 改: ...
+```
+
+**絕對不可**:
+- ❌ 跳過 framing 直接開始 benchmark
+- ❌ 假設 user 的 primary user persona(沒問就 "general user")
+
+---
+
+## Checkpoint 1 — Research scope(Phase 1 後)
+
+**格式範本**:
+
+```
+📊 Phase 1 Benchmark Scan(5+ 家)
+
+| Reference | Approach | Key mechanics | Screenshot |
+|-----------|----------|---------------|------------|
+| Linear    | ...      | ...           | link       |
+| Stripe    | ...      | ...           | link       |
+| Notion    | ...      | ...           | link       |
+| ...       |          |               |            |
+
+上面 N 家研究足夠嗎?
+(a) 足夠,進 Phase 2 評估
+(b) 還想加:___ (指定 tier / 產品)
+(c) 對整個 Phase 0 framing 重新思考
+```
+
+**絕對不可**:
+- ❌ 只掃 3 家同 DS 就收工(違反 benchmark-sources.md「至少 5 家跨 tier」)
+- ❌ 直接跳 Phase 2(user 未確認 research 代表)
+- ❌ 抓 demo video / 口述而非 screenshot 或 link(失真)
+
+---
+
+## Checkpoint 2 — Shortlist decision(Phase 2 後,最關鍵)
+
+**格式範本**:
+
+```
+🏆 Phase 2 Evaluation
+
+{評分表,per evaluation-matrix.md 格式}
+
+候選排序:
+- ★ Linear Quick-Filter(14/15)
+- ★ Stripe Step Wizard(12/15)
+- ☆ Notion Command Palette(11/15 邊界)
+- ✗ Atlassian Bulk Popover(8/15 drop 建議)
+
+你決定 Phase 3 做哪 2-3 個?
+(a) 採 AI 推薦:Linear + Stripe(2 個)
+(b) 採 Linear + Notion(混 high + 邊界)
+(c) 3 個全做(含 Notion 邊界 candidate)
+(d) 混搭:Linear 的 interaction + Stripe 的視覺 = 候選 D
+(e) Phase 2 評估偏誤 — 重新評估: ...
+(f) 直接 drop 全部 — 回 Phase 0
+```
+
+**絕對不可**:
+- ❌ AI 自己 shortlist 不問 user(user 最終 accountability)
+- ❌ 跳過 8 分以下 candidate 的 drop 說明(記入 notes.md 是學習價值)
+- ❌ 擅自「混搭」而沒 surface 為新選項
+
+---
+
+## Checkpoint 3 — 新元件 / primitive 需求(Phase 3 中)
+
+若任一 candidate 需要**新 DS 元件或 primitive**,必 pause:
+
+**格式範本**:
+
+```
+⚙️ Phase 3 候選「Notion Command Palette」發現新元件需求
+
+需要新元件:CommandPalette(全站 Cmd-K query 浮層)
+現有相關 primitive:Command(cmdk 搜尋,內建於 SelectMenu);Dialog(modal 容器)
+
+可能路徑:
+(a) CommandPalette 是「Dialog + Command」的 composition,**不需要新元件**,
+    建成 explorations/ 內 composition,採用後由 consumer 組合
+(b) CommandPalette 升級為 Components/ 新元件(若跨 candidate / 未來其他場景也需)
+(c) 不做 Notion candidate — 從 shortlist drop
+
+你決定?
+```
+
+**絕對不可**:
+- ❌ Phase 3 階段偷偷 add 到 Components/(違反 CLAUDE.md 規則分層)
+- ❌ 不 surface 新元件需求(stakeholder 看不到成本)
+- ❌ 混「新 primitive」與「新 variant」(前者 promotion 門檻高,後者在既有元件加)
+
+---
+
+## Checkpoint 4 — Final decision & graduation(Phase 4 後)
+
+**格式範本**:
+
+```
+🎨 Phase 4 Summary — 3 Candidates
+
+## Linear Quick-Filter
+- 適合:sales ops 重度 / PM bulk / support triage
+- 不適合:新手 / mobile fallback 待設計
+- Storybook:Explorations/Bulk Filter/Linear Quick-Filter
+
+## Stripe Step Wizard
+- 適合:destructive bulk / 合規 action
+- 不適合:高頻日常
+- Storybook:Explorations/Bulk Filter/Stripe Step Wizard
+
+## Notion Command Palette
+- 適合:多維 filter / 可 memory query
+- 不適合:簡單情境 / onboarding 負擔
+- Storybook:Explorations/Bulk Filter/Notion Command Palette
+
+AI 推薦:Linear Quick-Filter(業務 fit 最強 + DS 一致性 100%)。
+但最終 stakeholder 決定。
+
+你 / stakeholder 決定:
+(a) 採用 Linear,graduate 到 design-system/
+(b) 採用 Stripe,graduate(低頻場景)
+(c) 採用 Notion,討論 Checkpoint 3 新元件決策
+(d) 混 Linear interaction + Stripe visual = 候選 D(新 exploration 輪)
+(e) 全部不採用 — 本問題待定,保留 explorations/ 紀錄
+(f) 更多輪 proposal:修改 A 的 ... / 加新候選
+```
+
+**絕對不可**:
+- ❌ AI「幫 user 決定」用哪個(違反 exploration skill 精神)
+- ❌ graduate 採用者但不 archive 其他(未採用也有學習價值,不可刪光)
+- ❌ 跳過「為何沒採用 B / C」的 notes.md 記錄
+
+---
+
+## Checkpoint 5 — Cleanup(Phase 5)
+
+決策定案後整理:
+
+**格式範本**:
+
+```
+🧹 Phase 5 Cleanup
+
+採用:Linear Quick-Filter → 已 graduate 到 Components/ 下 ... (或 App-level UI)
+
+其他 candidate 處理:
+(a) Stripe Step Wizard → 移 explorations/_archive/(有未來複用潛力)
+(b) Notion Command Palette → 刪除(新元件成本高,短期無計畫)
+
+exploration notes.md 更新最終決策理由。
+
+確認?
+```
+
+**絕對不可**:
+- ❌ 自動刪除未採用 candidate(user 可能有未來計畫)
+- ❌ 不更新 notes.md 最終決策記錄(未來會忘記為何沒選)
+
+---
+
+## 歷史 failure mode(作為 anchor)
+
+(此 skill 首次建立,尚無 failure 紀錄。將來 skill 使用後踩坑記入此處,如 `design-system-audit` 的 checkpoints.md 歷史段落。)
+
+**預期常見失敗**(前人經驗 + 其他 skill 類比):
+- Checkpoint 2 skip:AI 挑 2 個 shortlist 後發現方向錯要從頭
+- Checkpoint 3 忽視:新元件偷偷進 Components/ 污染 DS
+- Phase 1 淺:只掃 3 家同 DS,Phase 2 評估失去對照