# ChipK 設計 × 產品 × 工程協作流程（Skill Pipeline 指南）

> **這是產品功能管線的正本，web 與 native 共用**——閘門條件、階段產物、角色分工以本文為準。不管目標平台是哪個，做功能都讀這份；只有階段 3 的實作 skill 依平台分流。
>
> 🔁 **雙份維護**：白話旅程版是 [product-feature.html](./product-feature.html)（給 PM 與主管；Pages 首頁是 [index.html](./index.html) 文件索引）。兩份服務不同讀者、深度不同，**不是重複**；本文的事實有變更時要同步改 HTML。
>
> 📱 **Native App 功能**：階段 1–2 與閘門 B 跟 web 完全一樣（同一份 Prototype、同一包交接文件、同一個蓋章），**分岔在階段 3**——web 用 `/frontend-product-implementation`，iOS／Android 用 `/native-product-implementation`（見〈階段 3〉的〈平台分流〉）。native 端的元件層交接包（design-contracts、原生套件、handoff tag）與責任邊界仍以 [HANDOFF_PROTOCOL.md](../../design-system/HANDOFF_PROTOCOL.md) 為正本，白話版在 [native-app.html](./native-app.html)。
>
> 🧰 **skill 的用途、正本與安裝**：見 [guides/skills.md](../guides/skills.md)。圖解版是 [CM Skills 指南](https://harrychuang-cm.github.io/skills/docs/skills-guide.html#/skills)（依情境挑 skill、口令表），正本在 [GitHub harrychuang-cm/skills](https://github.com/harrychuang-cm/skills)。本文只寫「哪個階段用哪支、閘門在哪」。

---

## TL;DR：整條管線長什麼樣

```
[設計素材]              [產品構想/PRD]             [確認後的 Handoff 文件]
    │                        │                           │
    ▼                        ▼                           ▼
┌───────────┐ 閘門A ┌───────────┐        ┌───────────┐ 閘門B ┌────────────────────────┐        ┌────────────┐
│ 階段 1a    │ ────▶ │ 階段 1b    │ ─────▶ │ 階段 2     │ ────▶ │ 階段 3  Production 組裝  │ ─────▶ │ 階段 4      │
│ 設計系統抽取│ 抽取核准│ 元件庫落地  │ 元件庫完備│ 產品      │ 交接確認│ （mock 模式，依平台二選一）│ 組裝完成 │ 資料串接     │
│ extractor  │       │ to-storybook│        │ Prototype │       │ web → frontend-p-i      │ 交第三棒 │ data-integ. │
└───────────┘       └─────▲─────┘        └─────┬─────┘       │ app → native-p-i        │        └─────┬──────┘
                          │   Component Gaps    │             └────────────────────────┘              │
                          └──── promotion ◀─────┘                                              閘門C：驗收
                              （回流迴圈，常態）                                  （PM 對 ACCEPTANCE 逐項；視覺 QA）
```

- **階段 1a + 1b**：**設計師主導**（AI 執行）建立設計系統與元件庫（本專案**已完成**，目前為維護模式）
- **階段 2**：**設計師或 PM** 把這個 Storybook 專案下載到自己電腦，做出可點擊的 Prototype + 7 份交接文件（framing 的產品問題由 PM 回答）。**目標平台（web／app／hybrid）在這一站由 PM 定案**，寫進 `PRODUCTION_HANDOFF.md` 的 Target Surfaces
- **階段 3**：Prototype 蓋章後，**Production 端的 RD 或 AI** 把交接文件組裝成 production 前端（mock 資料驅動）。**依 Target Surfaces 選 skill**：web → `/frontend-product-implementation`；iOS／Android → `/native-product-implementation`。兩支讀同一包文件、過同樣的閘門、交出同樣形狀的 `IMPLEMENTATION_MAP.md`
- **階段 4**：記名的第三棒（`/production-data-integration` 或指定團隊）把 mock 換成真實 API／auth／persistence，用 contract test 證明；**不動 UI**
- 三個閘門（A：抽取核准、B：Prototype 交接確認、C：Production 完成交接）都需要**人**做決策，AI 不可自行通過；閘門 C 拆成「組裝完成交第三棒」與「串接完成驗收」兩段勾選

---

## Storybook 的角色定位：為什麼是它，不是只有 Figma？

**Storybook 是元件的倉庫兼展示間**——一個在瀏覽器裡打開的網頁，放著產品的每一顆積木（按鈕、卡片、列表、到整個頁面）。重點是它們**全都是真的程式碼**：可以點、可以切換 hover／載入中／錯誤等狀態。本專案中「元件長什麼樣」以 Storybook 為準。

**和 Figma 的分工**：

| | Figma | Storybook |
|---|---|---|
| 本質 | 畫的是「圖」 | 放的是「真的元件」 |
| 適合 | 發想、探索視覺方向 | 定案後的唯一真相 |
| 落差 | 工程要照圖重寫一次，總有落差、永遠在校稿 | 設計師確認的就是上線用的同一份程式碼，**確認過不走樣** |

**和過去流程的差異**：過去是「設計師畫稿 → 工程照稿刻 → 來回校稿 → 下個功能重刻一次」，愈刻愈不一致；現在是「積木做一次進倉庫 → 新功能用現成積木組裝」，設計檢查的是「組得對不對」而不是「刻得像不像」，AI 也照同一批積木組、不會自己發明樣式。

**共用積木協作模式的三條規矩**：

1. **積木只有一份**——設計師組原型、RD 做產品，拿的是同一個倉庫的同一批元件，原型和成品天生長得一樣
2. **缺的積木先收編再用**——prototype 自建元件經 promotion 決策進倉庫，不允許各功能私刻按鈕
3. **顏色與間距不寫死**——全部連到設計系統 token，改一處全產品生效

**優勢**：組裝比重刻快、視覺一致、確認過的元件不必重複校稿、改版便宜（token 改一次全站生效）、AI 好指揮（有明確積木清單）。

---

## 角色分工總表

| | 階段 1a 抽取 | 階段 1b 元件庫 | 階段 2 Prototype | 階段 3 Production 組裝（web／native） | 階段 4 資料串接 |
|---|---|---|---|---|---|
| **設計師** | **主導**：提供素材、仲裁視覺決策 | **主導**：AI 執行；確認 state coverage、parity 視覺裁決 | **主導或參與**：可自行發起 prototype；Component Map confirm/veto、視覺把關 | 被諮詢：缺 token / 缺元件時裁決；native 目標另要補齊用到元件的 design-contract | — |
| **PM** | — | — | **主導或參與**：可自行發起 prototype；回答 framing 問答（**含定案目標平台**）、demo review、改 confirmed | 看 mock 全流程 demo（`AC-P (assembly)`） | 驗收：ACCEPTANCE.md 逐項驗收（含 `AC-P (integration)`） |
| **RD（工程師）** | 支援：環境問題 | 支援：framework / 依賴 / token pipeline 等工程判斷 | 支援：環境、安裝 | **主導**（或當 AI 的 gate 回答者）；native 目標由該平台（iOS／Android）工程師擔任 | **主導**：handoff 記名的第三棒（或當 AI 的 owner 回答者） |
| **AI（Claude/Codex）** | 執行 | 執行 | 執行 | 執行：`/frontend-product-implementation` 或 `/native-product-implementation` | 執行：`/production-data-integration` |

> 關鍵原則：**AI 是執行者，人是決策者。** 每個 skill 都內建「停下來問人」的關卡（gate），
> 遇到 gate 時 AI 會等待指定角色回答，不能被授權「自己決定就好」。

---

## 階段 1a：設計系統抽取 `/design-system-extractor`

**目的**：從證據（Figma、截圖、既有 App、prototype 程式碼）萃取出有證據背書的設計系統規格包——不寫任何產品 UI 程式碼。

📖 skill 正本：[design-system-extractor](https://github.com/harrychuang-cm/skills/tree/main/design-system-extractor)・圖解指南情境：[我有設計稿，準備開始做](https://harrychuang-cm.github.io/skills/docs/skills-guide.html#/j/from-design)、[既有產品整理成系統](https://harrychuang-cm.github.io/skills/docs/skills-guide.html#/j/from-legacy)

- **誰主導**：設計師（AI 執行，設計師提供素材並仲裁）
- **輸入**：Figma URL / Figma Variables、UI 截圖、既有 web / native 專案、prototype 程式碼。混合來源時依證據等級排序（production Figma 最高、口頭描述最低）
- **產出**：
  - `design-system/`：DESIGN_PRINCIPLES、TOKEN_ARCHITECTURE、COMPONENT_INVENTORY、`components/*.md` 元件規格、ANTI_AI_STYLE_RULES、SESSION_STATE（進度與決策紀錄）等
  - `tokens/`：`tokens-ref.css` → `tokens-sys.css` → `tokens-comp.css` 三層 token
  - `docs/design-system/index.html`（開發者文件）與 `review.html`（視覺審查佇列）
- **設計師會被問到的決策**（skill 會停下來等答案）：
  - 近似 token 要 merge 還是 keep distinct（手寫值永不自動合併）
  - 相似元件要 merge / variant / keep distinct
  - 重複來源要 reuse 還是分開登錄
  - 之後才拿到更權威的來源（如 production Figma）時，重校準表逐項裁決
- **地雷**：
  - 這個階段**沒有可跑的畫面**——產出是規格不是程式碼，PM 別在此階段要 demo
  - `docs/design-system/*.html` 是產生檔，不可手改；改 Markdown / token 後重新產生
  - vibe-coded 專案的檔名不算證據，必須以實際渲染截圖驗證

### 閘門 A：抽取核准（Checkpoint）

進入階段 1b 前必須通過。**核准人：設計師（或指定 reviewer）**。

- [ ] `docs/design-system/review.html` 的待裁決項（重複來源／近似 token／相似元件）全部處理完
- [ ] 三支 `--strict` audit（sources / tokens / components）全部通過
- [ ] `docs/design-system/index.html` 為最新產生版本
- [ ] SESSION_STATE.md 寫明 recommended next prompt
- [ ] 核准人明確表示「可以進入 Storybook 落地」

> Skill 明文禁止在 checkpoint 前寫任何產品 UI / Storybook 程式碼（Implementation Boundary Gate）。

---

## 階段 1b：元件庫落地 `/design-system-to-storybook`

**目的**：把設計系統規格包落地成 Storybook foundations + token-backed 共用元件庫。

📖 skill 正本：[design-system-to-storybook](https://github.com/harrychuang-cm/skills/tree/main/design-system-to-storybook)・parity 用 [ui-pixel-align-report](https://github.com/harrychuang-cm/skills/tree/main/ui-pixel-align-report)／[ui-compare-to-reference](https://github.com/harrychuang-cm/skills/tree/main/ui-compare-to-reference)・圖解指南情境：[我有設計稿，準備開始做](https://harrychuang-cm.github.io/skills/docs/skills-guide.html#/j/from-design)、[做出來的跟設計稿不一樣](https://harrychuang-cm.github.io/skills/docs/skills-guide.html#/j/fix-drift)

- **誰主導**：設計師（AI 執行）。過程中的 framework 選擇、npm 安裝、token pipeline 等工程判斷，需要時找 RD 支援
- **設計師的決策點**：state coverage 事前確認（哪些互動狀態做/不做）、design parity 視覺裁決、Figma importer 檢視
- **輸入**：階段 1a 的完整 design-system package + 產品 repo + 實作範圍（scope）
- **產出**：
  - `src/components/<Name>/`：co-located 元件 + `.stories.tsx`（含 Figma 來源 URL）
  - Storybook foundations 文件頁（色彩／字體／spacing／radius／motion）
  - `design-system/STORYBOOK_COMPONENT_PLAN.md`、`STORYBOOK_COMPONENT_QUEUE.md`（依賴順序批次佇列）、`STORYBOOK_IMPLEMENTATION_MAP.md`（決策紀錄）
  - 選配：Figma export addon（`.storybook/vendor/`）+ Storybook Code To Design importer（`figma/storybook-code-to-design/`，設計師在 Figma Desktop 一次性 import manifest 後即可用）
- **工程判斷類 gate（設計師可找 RD 支援）**：framework 選擇（greenfield／多 root／遷移必問）、npm install 同意、token pipeline 沿用或匯入
- **設計判斷類 gate（設計師回答）**：每個元件動工前的 state coverage 清單、parity strict drift 逐筆 fixed 或 adjudicated
- **硬性品質關卡（Design Parity Gate）**：有 Figma／圖片證據的元件必須產出 `ui-pixel-align-report` 比對報告（`reports/design-pixel-align/<component>/`），不能只靠目測；截圖比對前要先做字型環境 preflight（fallback 字型會造成約 30% 假性尺寸漂移）
- **地雷**：
  - 新元件 story 必須 co-located，不可放獨立 stories/ 資料夾
  - 有 token 對應的視覺值不可 hardcode
  - 依賴元件未完成前不做 composite；共用元件未完成前不組頁面

**本專案現況**：此階段已完成——118 個元件、component queue 全數關閉（SESSION_STATE.md，2026-08-03）。新元件只會從「階段 2 的 promotion」或「新的權威證據批次」進來，不需要重跑 extractor。

---

## 階段 2：產品 Prototype `/storybook-product-prototype`

**目的**：把產品構想變成 PRD 主導、可點擊的 Storybook Prototype，並產出 7 份可直接交給工程師或 AI 的交接文件。

📖 skill 正本：[storybook-product-prototype](https://github.com/harrychuang-cm/skills/tree/main/storybook-product-prototype)・圖解指南情境：[我有產品想法，想先做個可以點的](https://harrychuang-cm.github.io/skills/docs/skills-guide.html#/j/idea-to-proto)

- **誰主導**：設計師或 PM（AI 執行）。做法：把這個 Storybook 專案下載到自己電腦（git clone），用 `/storybook-product-prototype` 開工。framing 的**產品問題必須由 PM 回答**——PM 不在場流程走不下去
- **輸入**：
  - **必要**：產品構想或 PRD 草稿 + PM 本人。skill 是 framing 對話制、一次一題：entry route、目標平台（web/app/hybrid）、必要 routes 與分支狀態、transitions、驗收標準——PM 不在場流程走不下去
  - **輔助（可選）**：Figma 設計稿（佐證用，不是驅動輸入）、UI 截圖（會委派 building-block inventory）
  - 執行前必須先跑 `design-system-governance` discovery（skill 契約強制項）
- **產出**（`src/pages/prototypes/<feature-prototype>/`）：
  - 可點擊的 interactive prototype story + Static Flow export story
  - typed UI Flow（stable route id + transitions）、deterministic fixtures（不打真 API）
  - `docs/` 7 份交接文件：**PRD.md、UI_SPEC.md、FLOW_SPEC.md、DATA_SPEC.md、PRODUCTION_HANDOFF.md、ACCEPTANCE.md、IMPLEMENTATION_GUIDE.md**
  - 機器載體（階段 3 的 skill 直接讀，不從 TypeScript 反推）：`fixtures/*.json`（與 `*Data.ts` 同值）、`docs/TOKENS.json`（W3C DTCG，`export_prototype_contracts.py` 產）、`docs/flow.json`（`export_flow.py` 產；app 目標可加 `--swift`／`--kotlin` 出導覽鷹架）、`docs/HANDOFF_MANIFEST.json`（`--handoff-ready` 通過時才寫）
  - Storybook toolbar 的 Prototype Inspector（Story／Docs／UI Flow／Data 檢視，本專案已安裝）
- **人的介入點**：
  - PM：framing 問答、Storybook demo review 確認產品方向、Open Product Decisions 清空或明列殘留
  - 設計師：Component Map confirm/veto（AI 掃描證據填寫、人只做確認）、token binding 與互動狀態的視覺品質
  - Demo review 後的 **promotion 決策**：哪些 Component Gaps（prototype 自建的一次性元件）要升格進共用元件庫？要升格的走 `/design-system-to-storybook` 收編（**這就是回到階段 1b 的回流迴圈，是常態不是例外**）
- **開口範例**（對 AI 說）：
  - 「用 `/storybook-product-prototype` 做一個『到價提醒設定』的原型。使用者從個股頁的鈴鐺圖示進來，目標平台是 app。有不清楚的地方一次一題問我。」（沒有 PRD 也能開始，AI 會用問答幫你把 PRD 長出來）
  - 「這是 PRD 草稿（貼上內容或給檔案位置）。先列出你需要釐清的問題，再動工。」
  - 「打開『字級設定』原型，補上『載入中』和『錯誤』兩個狀態。」（打磨迭代——AI 改原型時會同步更新交接文件）
- **地雷**：
  - 嚴禁接真實 API／auth／persistence；API 不明就記入 Open Product Decisions，不可捏造 endpoint
  - route/trigger 一律用 stable id（如 `quoteRow.click`），不可用畫面文字當路由邏輯
  - 目標平台未定是 PM 決策點，不能留給 AI 假設
  - 目標是 app 時，非 `return` 的 transition 要帶 `presentation`（離開不是單純 pop 時再加 `backBehavior`），`FLOW_SPEC.md` 的 Production Navigation Map 要填 iOS／Android 欄——這些是階段 3 native skill 的直接輸入，空格會變成接棒時的 blocking question

### 閘門 B：Prototype 交接確認（Review Status Gate）

進入階段 3 前必須通過。**這是整條管線最重要的人為關卡。**

- [ ] 團隊完成 Storybook demo review（PM 確認方向與 acceptance；設計師確認 Component Map 與視覺品質）
- [ ] Open Product Decisions 清空，或明確列出殘留項與 owner
- [ ] Component Gaps 的 promotion 決策已做（升格的元件已回 1b 收編完成，或明確決定留 local）
- [ ] **由人（非 AI）**把 `PRODUCTION_HANDOFF.md` 的 Review Status 從 `pending` 改為 `confirmed`，記錄誰、何時、review 了哪個 story
- [ ] 目標平台在 `PRODUCTION_HANDOFF.md` 的 **Target Surfaces** 寫明（web／app／hybrid）；app 目標的 `FLOW_SPEC.md` **Production Navigation Map** 的 iOS／Android 欄已填——空格在接棒時是 blocking question，不是留給 AI 猜
- [ ] `validate_prototype.py --handoff-ready` 通過，並產出 `docs/HANDOFF_MANIFEST.json`（版本戳記；接棒方會記下它的 digest，之後文件被改會被 `--verify-manifest` 抓到）
- [ ] 交接發起人（PM 或設計師）把 `docs/` 資料夾路徑交給接收方，並講明目標平台（決定接棒用哪支 skill）

> 接收方（工程師／AI）收到的文件若 Review Status 不是 `confirmed`，應退回，不可開工。
> 文件在 confirmed 之後又有任何修改 → Review Status 退回 `pending`，重新 demo review。

---

## 階段 3：Production 組裝 `/frontend-product-implementation`（web）／`/native-product-implementation`（iOS・Android）

**目的**：把 7 份交接文件組裝成目標 repo 內 framework-native 的 production 前端——**mock 模式**：畫面、導覽、互動狀態全做，資料留可替換的接縫（DataSource seam）給階段 4。

📖 skill 正本：[frontend-product-implementation](https://github.com/harrychuang-cm/skills/tree/main/frontend-product-implementation)（web）・[native-product-implementation](https://github.com/harrychuang-cm/skills/tree/main/native-product-implementation)（iOS／Android）・圖解指南情境：[我有產品想法，想先做個可以點的](https://harrychuang-cm.github.io/skills/docs/skills-guide.html#/j/idea-to-proto)（web 接棒段）、[同一份交接文件，我要做 iOS／Android 版](https://harrychuang-cm.github.io/skills/docs/skills-guide.html#/j/to-native)

### 平台分流：同一包文件，兩支執行 skill

分岔點在閘門 B **之後**，不在之前。階段 1–2 是平台中立的：PRD、flow 狀態機、驗收條目、JSON Schema、DTCG token 描述的是產品，不是 runtime。一份 handoff、一個 manifest、一次蓋章，然後依 `PRODUCTION_HANDOFF.md` 的 **Target Surfaces** 選 skill：

| Target Surfaces | 用哪支 | 執行層 | 目標 repo 長相 |
|---|---|---|---|
| **Web**（React／Vue／Angular／Svelte／meta-framework） | `/frontend-product-implementation` | 該 repo 的 framework 慣例（**不預設 React**） | `package.json`、既有 routes／screens、Storybook |
| **App**（iOS SwiftUI／Android Jetpack Compose） | `/native-product-implementation` | SwiftUI + NavigationStack／Compose + NavHost | `.xcodeproj`／`.xcworkspace`／`Package.swift`、`settings.gradle(.kts)`／`AndroidManifest.xml` |
| **Hybrid**／兩個平台都要 | **各跑一次**，對同一份 manifest | — | 交接表用 `Scope(web)`／`Scope(app)` 雙欄；web 已上線的區域在 app 常常是新的 |

**兩支共用的契約**（語意完全相同，換 skill 不用重學）：

- 讀序：`PRODUCTION_HANDOFF.md` 先讀，再 PRD → FLOW_SPEC → UI_SPEC → DATA_SPEC → ACCEPTANCE → IMPLEMENTATION_GUIDE
- Review Status 閘門：`pending` 或缺這一節 → 停下來問「團隊 demo 確認做了沒」，不開工
- Scope 逐字帶入：`A` 已上線（**禁止重建**，要在目標 repo 找到證據路徑）／`B` 新建／`C` 僅 Storybook／`U` 未查證＝blocking question。**不可自行重判**
- Consumed Manifest：記下 `docs/HANDOFF_MANIFEST.json` 的 `docsDigest` 與版本；沒有就記 `unversioned`
- **Component Reuse Map**：動任何 UI 前，把 in-scope 元件逐列解成 `reused`／`composed`／`extended`／`created`／`deferred`；解不掉的列先問 governance gate（缺元件問組合、缺 token 問 token），不寫那塊 UI
- 產出 `IMPLEMENTATION_MAP.md` 五節：Consumed Manifest、Route Outcomes、Acceptance Traceability、Data Adapter Seams、Component Map；用 `frontend-product-implementation/scripts/validate_implementation.py` 稽核（**native 也用這支，所以做 native 目標時兩支 skill 都要裝**）
- 驗收編號：`AC-S-*` 在階段 2 結案、`AC-H-*` 在閘門 B、`AC-P (assembly)` 由 **mock 全流程走通**結案、`AC-P (integration)` 留給階段 4
- 資料邊界是硬的：任何情況都不接真實 API／auth／persistence；交出 typed DataSource + Mock，把替換工作連同契約轉給 `Data Integration Ownership` 記名的第三棒。沒記名 → 列為 blocking open decision 要人指定

**Native 專屬差異**（`/native-product-implementation` 多做的事）：

- **平台適用性 gate**：讀 Target Surfaces 的 `App:` 與 `FLOW_SPEC.md` Production Navigation Map 的 `iOS destination`／`Android route` 欄。App 標 Not in scope 且該欄全 Not in scope → 這是 web-only handoff，**停下來**：退回階段 2 補 App 目標與導覽欄，或由人明確同意「無 native spec 直接推導」並記為 divergence。欄位部分空白 → 空格逐列當 blocking question，不停整批
- **native 架構決策紀錄**：從 repo 證據判定 Xcode／SPM／Gradle 目標、SwiftUI／UIKit 或 Compose／Views 的邊界、導覽框架、最低 OS／SDK、DI／state 模式。既有 app 一律繼承不再追問；**一個功能需求永遠不是換 UI 框架、升最低版本、改依賴管理的授權**
- **Token 來源**：讀 `docs/TOKENS.json`（W3C DTCG）生成 Swift `Color`／`Font` extension 或 Compose theme object；**DTCG 檔存在時禁止手抄 prototype CSS**。目標 app 沒有 token 系統時停下來問，同 web 的 token-bootstrap gate
- **導覽語意對映**：transition 的 `presentation`（push／modal／sheet／fullscreen／replace）與 `backBehavior`（pop／popToRoot／dismiss／none）→ SwiftUI `NavigationStack`／`.sheet`／`.fullScreenCover` 或 Compose `navigate`／`popUpTo`／`ModalBottomSheet`；`kind: return` 一律做返回、不做 push。可用 `storybook-product-prototype/scripts/export_flow.py --swift/--kotlin` 產導覽鷹架，**鷹架要併進 app 既有 router，不是直接上線**
- **DataSource 形狀**：`<Feature>DataSource` Swift protocol／Kotlin interface + `Mock<Feature>DataSource` 讀 `fixtures/*.json`（iOS 走 bundle resource、Android 走 assets）；entity 型別從 DATA_SPEC 的 JSON Schema 生成
- **governance 的 web 措辭要換成 native 對應物，不能整份跳過**：Storybook story → SwiftUI `#Preview`／Compose `@Preview`；hover → pressed／focused；CSS keyframes → token 層的 `Animation`／`AnimationSpec`；px breakpoint → size class／window size class；`src/components/` → 原生共用元件 module（通常在 app module 之外，先讀依賴宣告）
- **驗證鏈**：iOS `xcodebuild build/test`（要帶 `-destination` 模擬器）＋ `swiftlint`；Android `./gradlew :<module>:assembleDebug/testDebugUnitTest/lintDebug`＋ `detekt`；再在模擬器／模擬機走完 mock 全流程並截圖。**沒有模擬器不能寫「passed」**——要記降級替代（哪些項目用 JVM／Paparazzi 蓋到、哪些沒蓋到、誰負責補跑）
- **Route Outcomes 多一個值 `not-applicable`**（該 route 在本平台 out of scope）。共用稽核腳本目前會把它報成失敗——這是已知落差，**不可改成 `deferred` 讓稽核變綠**，要在報告裡逐列引用 Navigation Map 的格子說明

### 執行細節（兩支共用）

- **誰主導**：Production 端的 RD 或 AI。**走 AI 分支時，必須同時指定一位 RD 當 gate 回答者**——skill 有多個必須停下來等人的關卡，AI 不能自行往下走；native 目標由該平台（iOS／Android）工程師擔任
- **開工前的兩個決策（由工程負責人拍板，寫入 decision record）**：
  1. **目標 repo / app root 是哪裡**（ds-lab 是實驗場；production 目標要明確指定——web 是 package root，native 是 Xcode project／SPM package／Gradle module）
  2. **執行架構是什麼**——prototype 用 React 不代表 production 就用 React，也不代表 native 要照翻 web 寫法；handoff 是證據不是授權；re-platform 一律要人明確批准
- **輸入**：階段 2 的 7 份文件（`PRODUCTION_HANDOFF.md` 優先讀）+ 機器載體（`docs/HANDOFF_MANIFEST.json`、`docs/TOKENS.json`、`docs/flow.json`、`fixtures/*.json`、DATA_SPEC 的 JSON Schema）+ 目標 repo
- **強制 companion**：`design-system-governance` Phase 0 discovery（盤點 tokens／grid／motion／i18n／共用元件；native 對原生的 theme／token／共用元件 module／localization 來源做）不可跳過；缺 token 或缺共用元件必須停下取得核准；目標 repo 完全沒有 token 系統時，經核准後走 token-bootstrap 從 prototype 端移植最小 token 子集
- **產出**：
  - Production routes／screens／元件／state／i18n（跟隨目標 repo 既有慣例）
  - Typed DataSource + Mock（讀 fixtures）+ 記錄好的替換點（injection site）——真實 API／auth／persistence 刻意不接
  - `IMPLEMENTATION_MAP.md`（五節）+ 架構決策紀錄 + 最終報告（prototype→production 元件對照表、Acceptance Traceability、open decisions 清單）
- **驗證順序**：web：lint → typecheck → tests → Storybook build → app build → mock 全流程走通；native：見上方驗證鏈。每個 Scope `B` 畫面都要與 prototype 並排做 parity（`ui-pixel-align-report` 出證據、`ui-compare-to-reference` 修），Scope `A` 明文排除——**prototype 的長相永遠不是改已上線畫面的理由**
- **交接與開口範例**：
  - 交接訊息範本（發起人 → 接棒者）：「《到價提醒設定》原型已 demo 確認，PRODUCTION_HANDOFF.md 是 confirmed。文件在 `src/pages/prototypes/price-alert-prototype/docs/`。目標是 **web**，請用 `/frontend-product-implementation` 實作——產品問題找我，工程決策找（RD 的名字）。」（四要素：文件位置＋已蓋章＋目標平台＋誰回答什麼問題）
  - 給 AI 的開工指令（web）：「用 `/frontend-product-implementation` 接手 `src/pages/prototypes/price-alert-prototype/docs/` 的交接文件。目標 repo 是（production 專案路徑），framework 依那個 repo 的現況，不要自己換。要做決定的事來問（RD）。」
  - 給 AI 的開工指令（native）：「用 `/native-product-implementation` 接手 `src/pages/prototypes/font-size-setting-prototype/docs/` 的交接文件。目標是（Android app repo 路徑）的 `:app` module，架構依 repo 現況，不要換框架、不要升最低 SDK。Production Navigation Map 的 Android route 欄有空格就來問（Android RD），不要自己發明 destination。真實持久化不要接，留 DataSource seam。」
  - 保險做法（先看計畫再放行）：「先讀完 docs/ 的七份文件，列出實作計畫、Component Reuse Map 草稿、打算重用哪些現成元件、還有哪些沒答案的問題——先不要動工。」
- **地雷**：
  - **「做完」≠「可上線」**：產出是 mock 資料驅動的前端，這是契約設計不是沒做完；接真資料是階段 4
  - 只能實作 prototype 真的存在的 variants，且必須剝除 Storybook-only 的邊界（inspector hooks、static-flow scaffolding、`parameters.prototype`）
  - 禁止 hardcode 視覺值與 i18n／localization 來源之外的顯示文字
  - Scope `A` 的畫面不建 DataSource seam、不做 parity 修正、不進第三棒的工作清單——它已經在線上
  - web-only 的 handoff 丟給 native skill 會停在平台適用性 gate，這是正確行為；不要繞過，回階段 2 補 Target Surfaces 與 Navigation Map
  - native 沒有 hover——把「缺 hover story」報成缺口是 governance 措辭沒轉譯；該蓋 pressed／focused
- **與 `HANDOFF_PROTOCOL.md` 的關係**：該文件定義 native 的**交接包內容**（Storybook 網址、handoff tag、design-contracts、原生套件）與**責任邊界**（native-owned 的手勢／a11y／haptics／導覽副作用）；`/native-product-implementation` 是接收端執行它第 4 步「實作」的 skill。兩者目前對文件件數與機器載體的敘述不一致，見〈已知問題〉第 2 點

---

## 階段 4：資料串接 `/production-data-integration`

**目的**：把階段 3 交出的 mock DataSource 換成真實 API client、auth／session、cache、storage、persistence 與環境設定，並用 contract test 證明真實回應符合文件寫的契約。**這是 prototype → production 鏈的第三棒，只動 seam 後面的東西。**

📖 skill 正本：[production-data-integration](https://github.com/harrychuang-cm/skills/tree/main/production-data-integration)・圖解指南情境：[畫面在跑假資料，我要換成真的](https://harrychuang-cm.github.io/skills/docs/skills-guide.html#/j/real-data)

- **誰主導**：`PRODUCTION_HANDOFF.md` 的 `Data Integration Ownership` 記名的承接者——可以是這支 skill（AI 執行、RD 當 owner 回答者），也可以是指定團隊或系統。本專案 `font-size-setting-prototype` 的第三棒記名 Android Platform（該功能沒有遠端 API，第三棒實際是本機持久化與既有畫面接線）
- **四項固定輸入**（缺任何一項先補、不猜）：
  1. `PRODUCTION_HANDOFF.md` 的 API And Data Contracts（含 `Adapter interface` 欄與 `Semantics` 欄：pagination／sort-filter／freshness／mutation／error taxonomy）
  2. `IMPLEMENTATION_MAP.md` 的 Data Adapter Seams 表（介面名、mock 路徑、injection site）
  3. `fixtures/*.json`（shape 的黃金參考，比欄位型別不比值）
  4. `DATA_SPEC.md` 的 Data Schemas（JSON Schema）
- **邊界（硬性）**：不改 UI 行為、route flow、元件、token、驗收條目本身。契約與真實 API 不符 → 回報並問契約 owner 改哪邊；契約要改就回寫 PRODUCTION_HANDOFF／DATA_SPEC + Storybook regression story，並把 Review Status 退回 `pending`。**絕不為了配合沒寫進文件的回應形狀就地改 UI**
- **產出**：每個 seam 的真實實作 + injection site 換好；mock 保留給 tests／previews；每個 fixture group 一組 contract test（schema 驗證、error taxonomy 對映、每個 Semantics 條目一條行為斷言）；`IMPLEMENTATION_MAP.md` Data Adapter Seams 表補上真實實作路徑；環境設定與 secrets 走 repo 既有機制、不進 git
- **開口範例**：「用 `/production-data-integration` 把 `src/pages/prototypes/price-alert-prototype/docs/` 這個功能在（production repo 路徑）的 mock adapter 換成真實 API，契約以 PRODUCTION_HANDOFF.md 與 IMPLEMENTATION_MAP.md 的 Data Adapter Seams 為準。endpoint 或 auth 不明就來問（後端 owner），不要自己發明。」
- **地雷**：
  - endpoint、auth 機制、Semantics 有 `unknown` → 停下來問記名 owner，不發明、不放 placeholder base URL
  - 沿用 repo 既有的 client／auth／cache／DI／test 慣例，不引入新 pattern
  - Scope `A` 畫面的 fixtures 不是這一棒的工作——它們在階段 3 就被排除

### 閘門 C：Production 完成交接

閘門 C 有兩段，**組裝完成不等於可以驗收**：

**C-1 組裝完成，交第三棒**（階段 3 → 階段 4）

- [ ] `IMPLEMENTATION_MAP.md` 五節齊全，`validate_implementation.py` 稽核通過（native 的 `not-applicable` 列依已知落差逐列說明）
- [ ] mock 全流程走通有紀錄（web 在瀏覽器、native 在模擬器／模擬機；降級替代要寫清楚沒蓋到什麼、誰補跑）
- [ ] `AC-P (assembly)` 全數 pass；Scope `B` 畫面的 parity 證據齊
- [ ] 最終報告產出：用了哪些文件、manifest digest、架構決策、Component Map、open decisions
- [ ] **每一個真實整合項目都有記名承接者**（`Data Integration Ownership`：`/production-data-integration` 或指定團隊），沒有的列為 blocking open decision——不可靜默 defer

**C-2 串接完成，驗收**（階段 4 → 上線）

- [ ] 每個 fixture group 的 seam 都換成真實實作，mock 保留給 tests／previews
- [ ] contract test 全過
- [ ] `AC-P (integration)` 全數結案，Acceptance Traceability 表沒有空格
- [ ] PM 對 `ACCEPTANCE.md` 逐項驗收
- [ ] 視覺 QA：依風險決定是否再跑一輪 parity 報告（由工程負責人觸發）

---

## 回流迴圈（不是單行道）

| 迴圈 | 觸發時機 | 走法 |
|---|---|---|
| **Component Gaps promotion** | 階段 2 demo review 後 | 人決定哪些 gap 元件升格 → 走 `/design-system-to-storybook` 收編進共用元件庫（回階段 1b）|
| **文件變更 re-review** | 閘門 B 之後 7 份文件有任何修改 | Review Status 退回 `pending` → 重新 demo review → 重跑 `--handoff-ready` |
| **實作期發現問題回寫** | 階段 3 發現文件衝突、缺 token、缺元件 | 停下問人 → 答案回寫文件：設計側改 UI_SPEC／token、產品側改 PRD／FLOW_SPEC，不要只留在對話裡 |
| **新的權威證據** | 拿到新的 production Figma／改版 | 回階段 1a 跑增量抽取（Late-Arriving Authoritative Source 重校準）|
| **web-only handoff 遇到 native 目標** | 階段 3 的 `/native-product-implementation` 停在平台適用性 gate | 回階段 2：補 `Target Surfaces` 的 App 目標、填 `FLOW_SPEC.md` Production Navigation Map 的 iOS／Android 欄、寫 App Implementation Notes → 重跑 `--handoff-ready` |
| **契約與真實 API 不符** | 階段 4 contract test 失敗或回應形狀不同 | 問契約 owner 改哪邊 → 改契約就回寫 PRODUCTION_HANDOFF／DATA_SPEC + regression story，Review Status 退回 `pending`；**不就地改 UI** |

---

## 另一條入口：拿 UI 圖來的時候（Component Coverage Analyzer）

「我有一張 UI 圖／mockup，想知道元件庫夠不夠、怎麼做」——不用走完整 prototype 流程。本專案已裝好專用動線：**送件（設計師／PM）→ AI 分析 → 逐塊裁決（工程師）→ AI 依決策實作**，結果可併入階段 2 的 Component Map。

📖 **完整操作、決策語彙、API 契約與疑難排解都在正本：[tools/component-coverage-analyzer.md](../tools/component-coverage-analyzer.md)**

這個工具頁由 [storybook-tools-install](https://github.com/harrychuang-cm/skills/tree/main/storybook-tools-install) 安裝與更新（圖解指南情境：[我想在 Storybook 裡加上團隊工具頁](https://harrychuang-cm.github.io/skills/docs/skills-guide.html#/j/add-tools)）；單張畫面圖也可以走 [ui-screenshot-to-storybook-product](https://github.com/harrychuang-cm/skills/tree/main/ui-screenshot-to-storybook-product)（[我只有一張畫面圖](https://harrychuang-cm.github.io/skills/docs/skills-guide.html#/j/one-screen)）。

---

## 環境需求（per 角色）

| 需求 | 設計師 | PM | RD／AI 執行機 |
|---|---|---|---|
| Node.js + npm | ✅（下載專案自跑 prototype／Storybook）| ✅（自己跑 prototype 時）| ✅ |
| Python 3 | ✅（自己跑 prototype 時）| ✅（自己跑 prototype 時）| ✅（prototype scripts：scaffold／inventory／validate；階段 3／4 的 `validate_implementation.py`、`export_flow.py`）|
| Xcode + iOS Simulator | — | — | ✅ native（iOS）目標：`xcodebuild -destination` 與 `simctl` 走 mock 全流程；沒有就只能記降級替代，不能寫 passed |
| Android SDK + Emulator（`adb`） | — | — | ✅ native（Android）目標：`./gradlew :<module>:…` 與 `adb` 截圖；同上 |
| `frontend-product-implementation` skill 已安裝 | — | — | ✅ **做 native 目標也要裝**——`validate_implementation.py` 稽核腳本只在它底下，`native-product-implementation` 沒有自己的 `scripts/` |
| `rg`（ripgrep）在 PATH | — | — | ✅（`npm run check` 需要，已知坑）|
| Storybook port 6006 | 開 `npm run storybook` | 由執行者提供網址 | 固定 `-p 6006`；與 `extract:figma:serve` 等常駐服務並行時注意佔用 |
| Figma Desktop + importer | ✅（每台機器一次性 import manifest）| — | — |
| Figma MCP 存取 | 視檔案而定 | — | **file-specific**：remote server 讀得到 `vSr4NtEwPVs6wLpqCT5PtV`、讀不到 chipK-demo（`EYuByMMhMsPb4DwX4caKoA`，改用 export／re-import）；desktop MCP 要求檔案在 Figma Desktop 開啟中 |

---

## 本專案現況（2026-09-03）

| 階段 | 狀態 | 證據 |
|---|---|---|
| 1a 抽取 | ✅ 完成，維護模式 | `design-system/` 治理文件 + 每顆元件 spec；三層 tokens 落地。Figma 抽取管線仍在持續增量供稿 |
| 1b 元件庫 | ✅ 完成，維護模式 | `src/components/` 元件庫 + stories；component queue 全數關閉（2026-08-03）。新元件只從「階段 2 的 promotion」或「新的權威證據批次」進來，不需要重跑 extractor |
| 2 Prototype | 🟡 已啟動 | `font-size-setting-prototype`（Target Surfaces：**Android app**，web Not in scope）、`inventory-prototype`（目標平台 unknown）兩個 prototype 存在，七份交接文件皆齊備。font-size 已產出機器載體：`docs/TOKENS.json`、`docs/flow.json`、`fixtures/*.json`、`docs/FontSizeSettingNavigation.kt`（Kotlin 導覽鷹架）。兩者 Review Status 皆為 `pending`，閘門 B 尚未蓋章，因此 `HANDOFF_MANIFEST.json` 尚未產出 |
| 3 Production 組裝 | ⬜ 未開始 | 尚無 production 交接紀錄。兩支實作 skill 皆未在本專案跑過；`/native-product-implementation` 依 skill repo 自述「機制完備，尚未對真實 Xcode／Gradle 專案跑過一次完整交付」，第一次用要預留驗證時間 |
| 4 資料串接 | ⬜ 未開始 | font-size 的第三棒已記名 Android Platform；inventory 的 Integration Ownership 仍是舊版兩段式寫法，未記名 stage-3 承接者 |

> 規模數字（元件數、change 數）請查 [文件索引 →〈規模快照〉](../README.md#規模快照2026-08-27)，不寫進本文以免過期。

## 已知問題（寫入流程前先知道）

依嚴重度排序：

1. **閘門 B 已接線，但 validate 仍有缺口（中）**：兩個 prototype 都已有 `PRODUCTION_HANDOFF.md`（Review Status 皆為 `pending`，待團隊 demo review 後由人改 `confirmed`）。`font-size-setting-prototype` 的那份於 2026-08-27 補回——它原本由 `3969d1c2` 建立、被 `486adb08` 連同原型一起刪除，`3f62ebc7` 依定案流程板重建原型時沒補回來。補回時同步把七文件的章節契約補齊，`validate_prototype.py --handoff-ready` 從「6 warnings + 20 errors」降到「0 warnings + 6 errors」，剩下的是 Review Status 待人蓋章、缺 static flow export，以及下述檔名／id 層級問題。
   - **font-size-setting 的驗證從未真正生效**：驗證腳本以 `*PrototypeFlow.ts` / `*PrototypeData.ts` / `*PrototypeMeta.ts` 尋找檔案，而該 prototype 的檔名是 `fontSizeSettingFlow.ts` 等，於是 route/transition/fixture 交叉檢查整段被跳過。實測改名後會再暴露 20 餘條 `unknown target`——因為腳本假設 flow 只有**一層** route id，而該 prototype 刻意分兩層（3 個導覽路由 vs 7 個流程板畫面狀態）。要接上驗證得先裁定：收斂成單層 id（偏離定案流程板），或讓 skill 的驗證腳本支援雙層。
   - `inventory-prototype` 的既有缺口（transition metadata 缺 to/trigger、meta 缺 PRODUCTION_HANDOFF raw import）尚未處理。
2. **native 的交接真相有三份，件數與載體對不上（中，待裁定）**：
   - [HANDOFF_PROTOCOL.md](../../design-system/HANDOFF_PROTOCOL.md)（2026-07-07 定案）寫 **6 份文件**（不含 `PRODUCTION_HANDOFF.md`）+ design-contracts + 原生套件 + handoff tag；
   - `src/pages/prototypes/README.md` 與 `npm run check:prototype-docs` 要求 **7 份**；
   - `/native-product-implementation` 讀的是 **7 份 + 機器載體**（`HANDOFF_MANIFEST.json`、`TOKENS.json`、`flow.json`、`fixtures/*.json`），且**第一份就讀 `PRODUCTION_HANDOFF.md`**——它的 Review Status、Target Surfaces、Scope 欄是整條閘門的載體，少了它 skill 會直接停。
   本文與三份 HTML 已依「7 份 + 機器載體」敘述；`font-size-setting-prototype/docs/PRODUCTION_HANDOFF.md` 的〈適用管線〉也把這件事列為待裁定項。**待辦：把 HANDOFF_PROTOCOL.md 第 2 層改成七份、第 3 層補機器載體。** 同時該文件自列的四項一次性前置作業（Storybook 發佈網址、tag 慣例、gap report template、套件引用方式）一項都未完成，`git tag` 本地與遠端皆為 0 筆——依其自述「未完成前，交接流程不算可用」。
   另外，第 3 層（design-contracts + `packages/android`）覆蓋不足：font-size 真正要新建的三個浮層元件（PopupDialog／Snackbar／SegmentedButtonGroup）與 TopAppBar 擴充插槽都還沒有 contract；`design-contracts/manifest.json` 為四個元件宣告了磁碟上不存在的 Android `componentPath`，而 `npm run check:native-spike` 仍回報 passed。
3. **與 Spectra 的粒度未定義（中）**：本專案所有變更以 Spectra change 為單位。建議粒度：一個 feature prototype = 一個 change；Component Gap promotion = 獨立 change；production 實作在目標 repo 依該 repo 的流程。**尚未寫成規則**。
4. **流程狀態沒有可靠的單一入口（低）**：`.pipeline-board/board.html` 是給設計師／PM 看「進行到哪、誰被 block」的現成工具，但它是**未進 git 的衍生檔**，快照可能很舊。即時狀態要看 Coordinator 的 `/ops` 或 Design Automation Hub 的流程狀態。

## 與既有文件的關係

| 文件 | 角色 |
|---|---|
| 本指南 `docs/workflows/product-feature.md` + `.html` | **產品功能**協作管線的正本（4 個階段、6 支 skill：階段 3 依平台在 `/frontend-product-implementation` 與 `/native-product-implementation` 二選一、階段 4 `/production-data-integration`；3 閘門）。native 功能的階段 1–3 也看這裡 |
| `design-system/HANDOFF_PROTOCOL.md` + `docs/workflows/native-app.html` + `docs/workflows/native-design-contracts.html` | **native app** 的交接包與責任邊界（design-contracts + 原生套件 + handoff tag，工程端不讀 React）；`/native-product-implementation` 是接收端執行其第 4 步「實作」的 skill |
| `docs/design-system/index.html` / `review.html` | 設計系統開發者文件／視覺審查佇列（階段 1a 產出）|
| `.pipeline-board/board.html` | 管線即時狀態看板 |
| `src/pages/prototypes/README.md` | prototype 資料夾契約（7 文件版本）|
| `docs/tools/component-coverage-analyzer.md` | Component Coverage Analyzer 的正本 |
| `docs/guides/` | 角色指南（設計師／PM／RD）與名詞對照表 |
| `openspec/` | Spectra SDD：specs 與 change proposals |
| `docs/guides/skills.md` | 本專案用到的 skill 清單、每支的正本連結與安裝方式（正本） |
| [CM Skills 圖解指南](https://harrychuang-cm.github.io/skills/docs/skills-guide.html#/skills)・[GitHub harrychuang-cm/skills](https://github.com/harrychuang-cm/skills) | skill 的公開說明（依情境挑、工具目錄、口令表）與正本 repo |