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

package/ds-canonical/fork/skills/prototype/references/evaluation-matrix.md

@@ -0,0 +1,141 @@
+# Evaluation Matrix — 4 軸評分 + 決策規則
+
+Phase 2 將 Phase 1 scan 結果變成可決策的評分表。
+
+---
+
+## 4 軸評分表
+
+### 結構
+
+```
+| Candidate | 優缺(pros / cons) | DS 一致性(1-5) | 業務 fit(1-5) | 複雜度(1-5,低=高分) | 小計 | 備註 |
+|-----------|---------------------|------------------|------------------|------------------------|------|------|
+| Linear 風格 | + 簡潔直覺 / - 太新 consumer 不熟 | 5(全用既有) | 4 | 5(複用 Button/Popover) | 14/15 | Mindset #1 我們 / Linear 一樣簡潔,差別: ... |
+| Notion 風格 | + 高階彈性 / - 學習曲線陡 | 3(需新 Command Palette) | 3 | 2(重度自訂) | 8/15 | Mindset #2 需新 primitive 評估 |
+| Stripe 風格 | + 流程嚴謹 / - 太多 modal | 4(消費 Dialog) | 5(業務就是金流) | 3 | 12/15 | ... |
+```
+
+---
+
+## 每軸打分規則
+
+### 優缺(bullets,不打分)
+
+列 3-5 個 pros + 3-5 個 cons。**避免抽象形容詞**(「好看 / 直覺」— meaningless),用:
+- 具體機制(「一鍵快速篩選」)
+- 業務對映(「能直接表達 VIP 客戶分類」)
+- 量化預期(「估可減 30% 誤點擊」)
+
+### DS 一致性(1-5,5 最高)
+
+- **5**:全部消費 `node_modules/@qijenchen/design-system/src/components/` 既有元件 + 既有 layout primitives
+- **4**:0-1 個新 primitive / 新 variant(低成本)
+- **3**:1-2 個新元件或顯著新 pattern(中成本)
+- **2**:3+ 個新元件 / 新 pattern(高成本 — 審慎)
+- **1**:衝突(違反既有 mindset / layout primitive SSOT)
+
+**扣分場景**:
+- 候選需要覆蓋 `--chart-*` token 家族 → DS 一致性扣
+- 需要 hack Popover / Dialog 基底 → DS 一致性扣
+- 違反 token 防線 lib/_token_hygiene.sh 5 條守則 → 直接 1(這是 bug,不是 DS 選擇)
+
+### 業務 fit(1-5,5 最高)
+
+依 Phase 0 framing 打分:
+- **5**:完美對映 primary jobs-to-be-done;使用者直接看懂情境
+- **4**:對映但需要少量 onboarding
+- **3**:可用但需要使用者重新學習
+- **2**:不完全對映,但有救(次級情境)
+- **1**:語境衝突(「這個 pattern 是 e-commerce 的,我們是 B2B SaaS」)
+
+### 複雜度(1-5,**低複雜度 = 高分**,反向)
+
+- **5**:一週內可完成
+- **4**:1-2 週
+- **3**:2-4 週
+- **2**:1-2 個月
+- **1**:>2 個月(通常 skill 不走這條)
+
+## 小計 & 決策門檻
+
+**小計 = DS一致性 + 業務 fit + 複雜度**(滿分 15)。
+
+**決策規則**:
+- ≥ 12/15 → **strong shortlist**(必進 Phase 3)
+- 9-11/15 → **可 shortlist**(若有特別理由,如業務 fit=5 彌補其他)
+- ≤ 8/15 → **drop**(記入 notes.md ruled-out reasons,保留學習價值)
+
+**Tie-breaker**(兩個 12/15):
+1. 業務 fit 分數高者優先
+2. DS 一致性分數高者次之
+3. 都平手 → 同時進 Phase 3(讓 stakeholder 決)
+
+**不以 AI 決定 drop**:邊界 candidate(9-11)user 可能有戰略理由選中,flagging + 等 Checkpoint 2 決策。
+
+---
+
+## Narrative 必寫項目(對齊 Mindset)
+
+**每個 candidate 的 1-2 段摘要必含**:
+
+1. **對齊 Mindset #1「對標世界級」**:
+   - 「我們的做法 vs 這家是一樣 / 不同,不同的理由是 ___」
+   - 說不出理由 = 設計 bug
+
+2. **對齊 Mindset #2「不憑直覺發明」**:
+   - 「此 candidate 需要的新 primitive 是 ___ / 既有 primitive `X` 已可滿足」
+   - grep 既有 DS 的證據
+
+3. **對齊 Mindset #4「真實業務場景」**:
+   - 「此候選在我們的 `{業務場景 A}` / `{場景 B}` 會呈現 ___」
+   - 不是抽象「UX 好」
+
+4. **OOUX / IA 深度對標**(see `ooux-template.md`):
+   - 「此 candidate 的 object model 對應競品的 `{Linear/Jira}` 方式,差異在 `{relationship depth / progressive disclosure 策略}` 是 ___」
+   - 不是只比視覺表皮;若 candidate 實際上是同個 object model 的 UI shape 變體,narrative 需明點出
+   - 若候選會變更 object definition(拆分 / 合併 object),**扣 DS 一致性分**(代表與 product canonical object model 漂移)
+
+4. **對齊 Mindset #5「猶豫就問」**:
+   - 若 candidate 的某部分無法評(資訊不足),**flag 而非猜**
+
+---
+
+## 輸出範本
+
+```markdown
+## 候選 A:Linear-style Quick Filter(推薦★)
+
+**核心機制**:Popover + 多 checkbox + saved filter。
+
+**優**:
+- Shortcut(`Cmd+Shift+F`)符合 power user 習慣
+- 我們既有 Popover + Checkbox 直接能組,零新元件
+- 「saved filter」延伸功能未來 scalable
+
+**缺**:
+- 初次使用需 onboarding(Mindset #4:我們客群是 enterprise 中小企業,重度用戶少,需評估滲透率)
+- shortcut 行動裝置 fallback 需另設計
+
+**評分**:
+- DS 一致性 **5**(100% 既有元件)
+- 業務 fit **4**(power user 場景 100%,輕度用戶 onboarding 佔 20% 扣)
+- 複雜度 **5**(預計 3 天完成)
+- 小計 **14/15** → **strong shortlist**
+
+**Mindset check**:
+- #1:我們 vs Linear 一樣簡潔,差別我們加 filter preview(e-commerce 業務)
+- #2:無需新 primitive
+- #4:對 B2B SaaS 真實場景契合(sales daily filter 使用頻率高)
+```
+
+---
+
+## 反-patterns(評分偏誤)
+
+- ❌ **偏好視覺酷炫**:Notion-style 華麗 = 高分 → 忽略業務/DS 扣分
+- ❌ **偏好「我們獨創」**:自創 pattern 在 DS 一致性給高分 → 違反 Mindset #2
+- ❌ **過度保守**:只打 3 分求穩 → Phase 2 失去篩選功能
+- ❌ **抽象優缺**:「好看」「直覺」「簡潔」— 無決策力,等於沒寫
+- ❌ **跳 tie-breaker 規則**:AI 挑一個 convenient 進 shortlist,違反 Checkpoint 2 精神
+- ❌ **只比視覺不比 IA**:只看 Phase 1 表層 / 沒分析 object model 就打分 → 抄到形式,抄不到深度(見 ooux-template.md)

package/ds-canonical/fork/skills/prototype/references/ooux-template.md

@@ -0,0 +1,198 @@
+# OOUX Template — Object-Oriented UX(Object Map + NOM + CTA Inventory)
+
+Object-Oriented UX 是 Sophia V. Prater(Rewired UX)提出的方法論。核心主張:使用者想的是**物件**,不是流程。設計 UI 前先盤核心 objects(名詞),產出以物件為中心的 UI。
+
+**為什麼本 skill 整合 OOUX**:
+- Phase 1 benchmark 只看視覺 + 功能 = 抄形式,抄不到 **information architecture**;加 OOUX 看物件結構才是深度對標
+- Phase 3 每 candidate 先定 object model,UI 決策變 derivation(list view 顯示什麼 attributes / detail view 什麼 CTAs)— 不靠直覺
+- 跨 candidate 共享同一 product-level object 定義,stakeholder 比稿時不被物件命名差異污染
+
+出處:[Sophia V. Prater — OOUX](https://www.ooux.com/) / [Rewired UX podcast](https://rewiredux.com/)
+
+---
+
+## ORCA Process(4 步)
+
+1. **O**bjects — 找出產品核心「名詞」
+2. **R**elationships — 物件間如何關聯(NOM = Nested Object Matrix)
+3. **C**TAs — 每個物件 per user role 可做什麼動作
+4. **A**ttributes — 每個物件的 properties
+
+Airbnb 範例(參考 reference model):
+
+| Object | Attributes | Relationships | CTAs(Host) | CTAs(Guest) |
+|--------|-----------|---------------|------------|------------|
+| Listing | title / photos / price / amenities / location | has many Reviews / belongs to Host / has many Reservations | Edit / Delist / Update price | Book / Save / Share |
+| Reservation | check-in / check-out / total / status | belongs to Listing / belongs to Guest | View / Cancel | View / Cancel / Review |
+| Review | rating / text / photos / date | belongs to Listing / by Guest | Reply | Write / Edit / Delete |
+| Host | name / avatar / bio / languages / response-rate | has many Listings / has many Reviews | Edit profile | View profile / Message |
+| Guest | name / avatar / verified / trips | has many Reservations / has many Reviews | — | Edit profile |
+
+注意:一個 object 可能有**不同 UI 展示 shape**(list row / card / detail page / inline chip),OOUX 不決定 shape,只決定 structure。shape 選擇走 Phase 3 時 consume DS 元件決定。
+
+---
+
+## Phase 1 用法 — 分析每個競品的 object model
+
+benchmark scan 時,每個 reference 後加 mini object map:
+
+```markdown
+### Reference: Linear(issue tracking)
+
+**Core objects identified**:
+- Issue(title / desc / priority / assignee / labels / cycle / status)
+- Cycle(name / start-end / scope / issues)
+- Project(name / description / lead / issues / status)
+- User(avatar / name / role)
+- Team(name / members / issues)
+
+**Relationships**(NOM highlights):
+- Issue belongs to Project(1:1 optional)+ Cycle(1:1 optional)+ Assignee(1:1)
+- Issue has many Comments / many Labels
+- Cycle belongs to Team / has many Issues
+- Project has many Issues / has Lead(= User)
+
+**CTAs per role**(key ones):
+- Admin/Lead:create / archive Project;set Cycle;assign Issue
+- Member:create Issue;comment;change status;assign self
+
+**UI shape observed**:
+- Issue:row in list view / card in board view / detail page / quick-preview peek panel
+- Cycle:sidebar entry / breadcrumb / filter chip
+- Project:sidebar nav / breadcrumb / filter
+
+**深度觀察**(比視覺更有價值的 pattern):
+- Issue 物件在 5 種 UI shape 中 attributes 顯示不同但 identity 一致 — row 只看 title + assignee,card 加 priority + label,detail 全顯示。這種「attribute progressive disclosure by context」是 Linear IA 強項。
+```
+
+做完 5+ 家 benchmark 後,可能發現:
+- 每家都有 "Issue / Task / Ticket / Work Item" 類的 object → 我們也該命名一個 canonical 名詞(Phase 3 用)
+- 關係模型普遍是 `Item → Project → Team` 三層,有例外值得留意
+
+---
+
+## Phase 3.0 — Build our own Object Map(design 前強制步驟)
+
+每個 shortlisted candidate 開始 design 前,先完成 ORCA。不是每個 candidate 都有獨立 object map — 通常**同一 feature 的 3 個 candidate 共享 product-level object definition**,差異只在 UI shape + CTAs 順序。
+
+### Step 1:Objects(從 Phase 0 framing + Phase 1 benchmark 抽)
+
+列出核心名詞。**原則**:
+- 2-7 個 objects 最理想(>7 通常是合併機會)
+- 命名三重 test(CLAUDE.md):既有設計語言 / 世界級 idiom / 跨元件認知衝突
+- 若 benchmark 發現 Linear 叫 "Issue"、Jira 叫 "Ticket"、我們叫什麼?根據自身業務 + 目標 user 慣用語 pick one,整個 skill 延伸統一用此命名
+
+```markdown
+## Our Feature Object Map
+
+**Objects**(我們 feature 的核心名詞):
+1. Task(對齊 Jira convention,台灣用戶更熟)
+2. Sprint(對齊 Agile convention)
+3. User
+4. Comment
+5. Attachment
+```
+
+### Step 2:Attributes per object
+
+```markdown
+| Object | Core attributes | Metadata | Identifying |
+|--------|----------------|----------|-------------|
+| Task | title / description / priority / status / assignee | created-at / updated-at | id / title |
+| Sprint | name / start-end / goal / velocity | state(active/closed) | id / name |
+| User | avatar / name / role / email | joined-at | id / email |
+| Comment | body / author / timestamp | edited / reactions | id |
+| Attachment | filename / size / type / url | uploaded-by | id |
+```
+
+### Step 3:Relationships(NOM)
+
+```markdown
+| From → To | Relationship |
+|-----------|-------------|
+| Task → Sprint | belongs to(optional,unscheduled Task 也 OK) |
+| Task → User(assignee) | belongs to(1:1 optional) |
+| Task → User(reporter) | belongs to(1:1 required) |
+| Task → Comments | has many |
+| Task → Attachments | has many |
+| Sprint → Tasks | has many |
+| Sprint → Team(via Users) | indirect |
+| Comment → Task | belongs to(1:1 required) |
+| Comment → User(author) | belongs to(1:1 required) |
+| Attachment → Task | belongs to(1:1 required) |
+```
+
+### Step 4:CTAs per role per object
+
+```markdown
+## CTA Inventory
+
+### Role: Admin
+- Task: Create / Edit / Delete / Assign / Change status / Move to sprint
+- Sprint: Create / Close / Reopen / Edit goal
+- User: Invite / Remove / Change role
+- Comment: Pin / Delete any
+- Attachment: Delete any
+
+### Role: Member(assignee)
+- Task: Create / Edit own / Change status / Add comment / Add attachment
+- Sprint: View / Join
+- User: Edit own profile
+- Comment: Edit own / Delete own
+- Attachment: Add / Delete own
+
+### Role: Viewer
+- Task: View / Add comment
+- Sprint: View
+- User: View profile
+- Comment: Add
+```
+
+### Step 5:以 Object Map 推 UI 決策
+
+每個 object 要決定的展示 shape(consume DS 元件):
+
+```markdown
+## UI Shape per Object
+
+| Object | List | Card | Detail | Inline |
+|--------|------|------|--------|--------|
+| Task | MenuItem(sidebar quick) / DataTable row(board) | FileItem-style card 若有 attachment preview / 普通 Card | Page 全螢幕 + Tabs 切換 | Tag(labels)/ Chip(status) |
+| Sprint | MenuItem | Summary Card | Dialog + Tabs | Badge(active dot) |
+| User | Avatar + name(inline)/ MenuItem(picker) | NameCard(hover) | Profile Page | Avatar(chip) |
+| Comment | Message item(chat style) | — | — | Thread inline |
+| Attachment | FileItem compact | FileItem rich | — | Link(inline mention) |
+```
+
+此表直接對齊 DS 既有元件(MenuItem / DataTable / Card / Avatar / NameCard / FileItem / Tag / Chip 等)。若某 cell 找不到對應 DS 元件 → Phase 3 可能需要新 primitive(走 Checkpoint 3)。
+
+---
+
+## Object Map 跨 candidate 一致性
+
+**關鍵 insight**:Phase 3 每 candidate 共享同一 Object Map。候選差別在:
+- Attributes progressive disclosure 策略不同(Linear:list 只秀 3 attr / Jira:list 秀 8 attr)
+- CTAs 順序 / 預設值不同(Notion:Edit 藏 hover 選單 / Jira:直接可見)
+- Relationship 展示方式不同(Linear:inline chip / Jira:separate section)
+
+但 **object 本身的定義**(什麼是 Task / 什麼是 Sprint / 怎麼關聯)必須 identical。否則 stakeholder Phase 4 比稿變成「比物件定義」,失焦。
+
+---
+
+## 何時 OOUX 不適用 / 過度
+
+- 極小 feature(單一 button 加到既有 page,無新 object)→ 跳過 ORCA,直接 Phase 3
+- 純視覺 refresh(無 data model 改動)→ 跳過
+- 1-object features(e.g., 設定單一開關)→ ORCA 退化為「這 object 有哪些 attributes」
+
+判斷法:若 Phase 0 framing 涉及 2+ 名詞互動 → OOUX 有用;若只涉及 1 動作 1 物件 → 跳過。
+
+---
+
+## References
+
+- Sophia V. Prater, "OOUX: A Foundation for Interaction Design" — Rewired UX blog
+- [ooux.com/tools](https://www.ooux.com/tools) — Object Map / NOM / CTA template 原版
+- Rewired podcast(搜「OOUX」)
+- Dan Klyn "Information Architecture Institute" 相關 IA 理論
+- Alan Cooper "About Face" — 互動設計經典,object-centric 思維源頭之一

package/ds-canonical/fork/skills/prototype/references/proposal-template.md

@@ -0,0 +1,229 @@
+# Proposal Template — explorations/ 結構 + Storybook 編排
+
+Phase 3 每個 shortlisted candidate 建一個 story + 共用 notes.md。
+
+---
+
+## 目錄結構(對齊 CLAUDE.md「Exploration 規則」)
+
+```
+src/explorations/{topic-slug}/
+├── notes.md                              # 本 topic 的 source of truth
+├── {CandidateA-name}.stories.tsx         # 候選 A 原型(1 檔內 3+ stories 各場景)
+├── {CandidateB-name}.stories.tsx
+├── {CandidateC-name}.stories.tsx
+└── _shared/                              # 僅此 topic 內共用的 helper(可選)
+    └── mock-data.ts
+```
+
+### 檔名慣例
+
+- **Topic slug**:kebab-case,描述問題(`onboarding-tour` / `bulk-action-confirm` / `empty-state-first-visit`)
+- **Candidate stories filename**:kebab-case + 描述性名稱(`linear-quick-filter.stories.tsx`)—**不用 `CandidateA/B/C`**(違反 CLAUDE.md「範例必須真實」mindset)
+
+### Storybook title 慣例(不與 Components/ 衝突)
+
+```tsx
+title: 'Explorations/{Topic Title}/{Candidate Name}'
+```
+
+範例:
+- `Explorations/Bulk Filter/Linear Quick-Filter`
+- `Explorations/Bulk Filter/Notion Command Palette`
+- `Explorations/Bulk Filter/Stripe Step Wizard`
+
+---
+
+## notes.md 範本
+
+```markdown
+# {Topic Title}
+
+## 問題定義(Phase 0 framing)
+
+**誰**:{primary user persona,如「Sales Ops 主管」}
+**想**:{jobs-to-be-done,如「在 50+ 筆 leads 中快速 filter 這週要跟進」}
+**解決**:{解除的痛點,如「現在得滾一頁找 tags,誤點率高」}
+**Constraints**:{mobile?a11y?時程?}
+
+## Phase 2 評估摘要
+
+見 Phase 2 完整評分表(略)。Shortlist 3 個:
+
+| Candidate | 核心機制 | 評分 | Phase 3 檔案 |
+|-----------|---------|------|-------------|
+| Linear Quick-Filter | Popover + checkbox + saved | 14/15 | `linear-quick-filter.stories.tsx` |
+| Notion Command Palette | modal Cmd-K + query | 11/15 | `notion-command-palette.stories.tsx` |
+| Stripe Step Wizard | Dialog + 3 步 fine-grained | 12/15 | `stripe-step-wizard.stories.tsx` |
+
+## Phase 3.0 Object Map(全 candidate 共享)
+
+本 feature 的 canonical object model,由 Phase 1 benchmark 的 OOUX 分析收斂 + Phase 0 framing 收敛而成。**3 個 candidate 共享此 Object Map**,差異只在 UI shape + CTAs 順序。
+
+**Objects**(core nouns):
+- {Object A}(核心名詞 1)
+- {Object B}(核心名詞 2)
+- {Object C}(若有)
+
+**Attributes per object**:
+
+| Object | Core attributes | Metadata | Identifying |
+|--------|----------------|----------|-------------|
+| {A} | ... | ... | ... |
+| {B} | ... | ... | ... |
+
+**Relationships(NOM)**:
+
+| From → To | Relationship |
+|-----------|-------------|
+| {A} → {B} | belongs to / has many / ... |
+| ... | ... |
+
+**CTAs per role per object**:
+
+| Role | {A} CTAs | {B} CTAs |
+|------|----------|----------|
+| Admin | Create / Edit / Delete | ... |
+| Member | View / Comment | ... |
+
+**UI Shape → DS 元件映射**:
+
+| Object | List | Card | Detail | Inline |
+|--------|------|------|--------|--------|
+| {A} | MenuItem / DataTable row | Card / FileItem | Page + Tabs | Tag / Chip |
+| {B} | ... | ... | ... | ... |
+
+完整 ORCA 方法與範本見 [`ooux-template.md`](ooux-template.md)。
+
+## 候選獨立說明
+
+### Linear Quick-Filter
+
+- **positioning**:面向重度 power user,shortcut-first
+- **適合場景**:
+  - Sales Ops 每日追蹤 leads(frequency=high,repeat task)
+  - Project Manager bulk status update
+  - Support 團隊 ticket triage
+- **不適合**:
+  - 新手 user(沒 onboarding 不知道 shortcut)
+  - 行動裝置(shortcut 無對應)
+- **新元件需求**:無(既有 Popover + Checkbox + Button 就夠)
+
+### Notion Command Palette
+
+- **positioning**:開放式 query,unified search
+- **適合場景**:
+  - 多維 filter(人 + tag + date)同時作用
+  - 可 memory 用戶的自訂 query
+- **不適合**:
+  - 情境簡單(2-3 filter)會 overkill
+  - 首次 user onboarding 負擔重
+- **新元件需求**:**可能需 `CommandPalette` 新元件**(本 DS 目前有 `Command` 但無全站 palette 結構)。若採用此 candidate,Checkpoint 3 討論是否升級。
+
+### Stripe Step Wizard
+
+- **positioning**:流程化,降低誤操作
+- **適合場景**:
+  - 破壞性 bulk action(delete 多筆)
+  - 需 audit trail 的金流 / 合規 action
+- **不適合**:
+  - 高頻日常操作(步驟拖慢速度)
+- **新元件需求**:無(既有 Dialog + Steps + Checkbox)
+
+## 下一步
+
+Phase 4 summary 整理完畢後,stakeholder 決定採用,走 graduation 流程:
+- 採用者遷移到 `node_modules/@qijenchen/design-system/src/`(若有新元件)或直接 app-level UI
+- 未採用者:留 `explorations/{topic-slug}/` 或移 `_archive/`(保紀錄)
+
+## 參考
+
+- Phase 1 research 連結(略)
+- Phase 2 評估完整表(略)
+- Storybook 路徑:`Explorations/{Topic Title}/*`
+```
+
+---
+
+## Candidate story 範本
+
+每個 `{candidate-name}.stories.tsx` 建議結構:
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react'
+// 從 DS import 既有元件
+import { Popover, PopoverContent, PopoverTrigger } from '@/design-system/components/Popover/popover'
+import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
+// ...
+
+const meta: Meta = {
+  title: 'Explorations/Bulk Filter/Linear Quick-Filter',
+  parameters: { layout: 'padded' },
+}
+export default meta
+
+type Story = StoryObj
+
+// Story 1:positioning 說明(不可互動也 OK)
+export const Positioning: Story = {
+  name: '1. Positioning',
+  render: () => (
+    <div className="max-w-lg flex flex-col gap-3">
+      <h3 className="text-body-lg font-medium">Linear Quick-Filter</h3>
+      <p className="text-body text-fg-secondary">
+        shortcut `Cmd+Shift+F` 開 Popover,checkbox 多選,支援 saved filter 組合。
+        面向 sales ops 每日場景:速度 > 引導。
+      </p>
+      <div className="border-t border-divider pt-3">
+        <a href="..." className="text-info">Linear 原始參考 →</a>
+      </div>
+    </div>
+  ),
+}
+
+// Story 2-4:具體情境(3 個以上,對齊 Mindset #4)
+export const SalesOpsDaily: Story = {
+  name: '2. Sales Ops 每日追蹤 leads',
+  render: () => { /* 完整互動 prototype */ },
+}
+
+export const ProjectBulkStatus: Story = {
+  name: '3. PM bulk status update',
+  render: () => { /* */ },
+}
+
+export const SupportTriage: Story = {
+  name: '4. Support ticket triage',
+  render: () => { /* */ },
+}
+
+// Story 5(可選):edge case / failure mode(讓 stakeholder 看弱點也是成熟的設計溝通)
+export const NewbieOnboardingConcern: Story = {
+  name: '5. ⚠️ 新手首次遇到(知識死角)',
+  render: () => (
+    <div>
+      {/* 示範新手沒 shortcut 知識時看到什麼 */}
+    </div>
+  ),
+}
+```
+
+---
+
+## DS 使用鐵律(per CLAUDE.md)
+
+Phase 3 建 exploration 時:
+
+1. **優先用既有元件** `node_modules/@qijenchen/design-system/src/components/`,不自創
+2. **Layout primitives 消費**(per CLAUDE.md 清單):Empty / item-layout / overlay-surface / ScrollArea / AspectRatio
+3. **Token 紀律**:只用 semantic token,不硬寫 hex / rgb / shadow-sm
+4. **token 防線 lib/_token_hygiene.sh 5-check**:shadcn alias / v4 shorthand / hardcoded shadow / primitive-color-as-utility / native overflow — 5 項全過
+5. **新元件需求**:**notes.md 明文標示**,不偷偷 add 到 Components/(Checkpoint 3 專屬)
+
+---
+
+## Non-goals
+
+- Pixel-perfect 不是目標(Phase 3 看 pattern 可行性)
+- 不做完整 test coverage(exploration 不上 prod)
+- 不覆寫 DS 元件 props(若需 override, 代表這個 candidate 不適合既有 DS)