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

package/ds-canonical/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/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 評估失去對照

package/ds-canonical/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**:全部消費 `packages/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 一致性扣
+- 違反 hook check_token_hygiene.sh 4 條守則 → 直接 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/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 思維源頭之一