Design SystemInternalWorkflow

Workflow

Internal維護者文件，不是 Design System 內容。

Governance Views（系統入口）

三個 data-driven 視圖。每個答一個不同問題，互相透過 entity id / signature 跳轉。 這一段是 /workflow 從 prose 頁轉為系統入口頁的新增區——以下的 prose section 為歷史內容，待逐步遷移進 registry / views。

Authority Stack

誰在衝突時贏？

5 層垂直 stack（L1-sot → L5-advisory）。每個 entity 標記 blocking / helper 行為。用於判決規則衝突、理解 override 關係。

Entity Index

這是什麼？住在哪？

34 個 active governance 項目 + 3 個 deprecated 的 filterable 目錄。用於查某條 rule / skill / script 的 spec、source、trigger。

Decision Ledger

這個 finding 早被裁決過了嗎？

B/C audit 重新評估的 decisions[] 聚合。audit 提 finding 前必須查此頁；用於減少重複發現「非問題」的噪音。

Overview

Opinion Trade 採用 dark-first / code-first 設計流程。所有 UI 從 Claude Code 產出，Figma 僅作為 layout 與內容參考。流程分為兩個 Phase，嚴格分離，禁止混合使用。

Source of Truth

Code component library 是唯一的 source of truth，不是 Figma。

Dark-first

所有設計以 dark mode 為基準，light mode 由 token 自動轉換。

Composition First

優先用現有 base / application / product components 組合，不發明新 component。

Token Enforcement

所有 spacing、color、radius 必須使用 semantic tokens，禁止 arbitrary values。

Phase A / Phase B

Phase A — Migration / Analysis

分析、拆解、mapping（禁止產出 code）

接受 Figma URL、截圖或頁面描述。產出固定 6-section 分析（Page Objective → Recommended Build Order）。所有 spacing、token、component 必須對應現有系統。Decision Point 必須附預設決策。

  • 輸入 — Figma URL / 截圖 / 頁面描述
  • 輸出 — 6-section 結構化分析 + 預設決策清單

Phase B — Builder / Implementation

建構（禁止重新設計或新增結構）

根據已完成的 Phase A 分析結果，用現有組件庫組出 React page。組件使用優先順序：Product Components → Application Components → Base Components。Phase A 不完整時必須停止。

  • 輸入 — 一份完成的 Phase A 分析
  • 輸出 — 使用現有組件的 React page code

Migration Workflow

1

Understand

理解頁面目的、目標用戶、在 flow 中的位置

2

Section

拆解頁面為命名 section，標記層級關係

3

Map

對每個 section 做 component mapping（先查 Pattern Mapping 表，檢查 Product Components）

4

Gap

找出缺口（無對應組件、需新 variant、token 不存在）

5

Decide

對每個 Gap 指定預設決策（A: 擴展組件庫 / B: 簡化設計 / C: Placeholder）

6

Build

Phase B 按決策逐 section 實作

Step 1–5 = Phase A 的輸出。全部完成後才能進入 Step 6（Phase B Build）。

流程規則

✗Phase A 禁止產出任何 code（React / HTML / JSX）
✗Phase A 每個 Decision Point 必須附預設決策，不得只列選項
✗Phase B 禁止重新分析或重新解讀設計
✗Phase B 禁止增加功能、重新設計、或偏離 Phase A 分析
✗Phase B 組件使用順序：Product Components → Application → Base
✗Phase B 未通過 Phase A 分析時必須停止，不可 placeholder 猜測
✗系統規則 override 設計偏好

Skills & Build Step

Skills（共用模組）

design_analyzer

設計分析

分析設計稿或需求，產出 6-section 結構化輸出（Page Objective、Section Breakdown、Component Mapping、Gap List、Risk / Decision Points、Recommended Build Order）。不產出 code。

system_mapper

系統驗證

驗證分析結果是否符合 design system 規則。檢查 component mapping、token compliance、system fit，輸出 Build Readiness Verdict。

design_auditor

品質審核

審核實作產出的 token usage、interaction consistency、accessibility、spacing / typography。找出結構性問題，標記為 backlog。

Internal Build Step

Code Generation

Internal Build Step（非 Skill）

內嵌在兩個 agent 的 Step 3。根據已鎖定的分析與 mapping 結果建構 React page。不重新設計，不做假設。只在 READY FOR BUILD 後執行。

design_analyzer（Skill）

必須輸出固定 6 個 section，不可省略或改變順序：

1
Page Objective— 頁面目的、目標用戶、核心功能
2
Section Breakdown— 頁面拆成哪些 section（附命名）
3
Component Mapping— 每個 section 對應哪些現有組件
4
Gap List— 缺少什麼？需要新 variant？組件不存在？
5
Risk / Decision Points— 需要人工決定的事項
6
Recommended Build Order— 建議的建構順序

關鍵規則

✓每個 Risk / Decision Point 必須附 default decision
✓Component mapping 只能用現有 system 語言
✓若 design 稿要求 system 內不存在的東西，必須列入 Gap List
✓必須區分 system gap 與 design ambiguity

system_mapper（Skill）

驗證 Analyzer 的輸出是否符合設計系統規則。

必須檢查

✓Component mapping 是否正確對應到現有 components
✓是否應優先使用 Product Component
✓Token compliance（無 raw colors、無 arbitrary spacing）
✓現有組件優先重用，新建需有理由

輸出

✓Mapping Validation
✓Product Component Priority Check
✓Pattern Mapping Compliance
✓Token / Spacing / State Compliance
✓Gap Resolution Recommendation
✓Build Readiness Verdict（READY FOR BUILD / NOT READY FOR BUILD）

禁止

✗修改或重寫 Analyzer 的原始輸出
✗為了滿足 design reference 而 override system
✗把不明確的東西直接放行

Code Generation（Internal Build Step）

只在 READY FOR BUILD 後才開始建構。內嵌在 agent 內部，不是獨立 skill。

✗不可重新設計
✗不可做任何假設
✗必須完全遵循 Analyze + Map 輸出
✗資訊不足時必須停止，不可猜測
✗不可根據對比自動調整顏色
✗不可替換 semantic token
✗不可生成新的 color 組合

design_auditor（Skill）

評估實作後的系統層級品質。標記問題但不阻擋實作。

評估範圍

✓Token 使用正確性
✓Interaction consistency
✓Accessibility（WCAG AA 基線）
✓Spacing / typography validation
✓組件可擴展性

行為

✓標記問題為 backlog
✓不阻擋 implementation
✓WCAG 為 advisory（除非明確 enforced）
✓所有對比問題由 token 層解決

Failure Modes（來自 OutcomeAction 迭代）

以下為真實迭代中發現的錯誤模式，已納入流程規則防止再次發生。

F1 — 缺少 Affordance Classification

interactive 元素被 mapping 為 Badge（Display 類），導致無 hover / active / focus。

攔截層：Analyzer（Section 3）

F2 — 缺少 Visual Weight Map

Resolved 狀態的視覺權重未定義，導致 Badge size=sm 無法表達 emphasis。

攔截層：Analyzer（Section 4）+ Mapper（weight 驗證）

F3 — 缺少 Spatial Intent

未標註 density，Generator 使用系統預設 spacing，與設計稿的 compact 密度不符。

攔截層：Analyzer（Section 5）

F4 — WCAG 決策混入錯誤階段

Generator 試圖根據 contrast ratio 自動調整顏色，而非由 Auditor 標記、token 層修正。

攔截層：Generator 規則（禁止 WCAG workaround）

F5 — Generator 做了視覺決策

Generator 自行決定 state hierarchy（outline vs fill），而非由設計決策鎖定。

攔截層：Decision Lock 必須在 Build 之前完成

Definition of Done

一個 component 在以下條件全部滿足前，不算完成：

✓所有 state 在 Preview page 中已渲染
✓State matrix 完整（含 hover / active 靜態 snapshot）
✓所有 token 使用一致（無 raw color、無 arbitrary value）
✓無未解決的 system gap（或已標記為 backlog）
✓已知 tradeoff 已文件化（在 preview page 的 backlog section）

Governance & Enforcement

Product Component Governance

Usage Enforcement

UI intent 與現有 Product Component ≥70% 相似 → 必須使用，禁止重組。

Variant vs New Component

優先新增 variant。只有結構 / 場景 / props 都無法表達時才允許新 component。

Allowed List Enforcement

只有 CLAUDE.md Allowed Product Components List 中的 Product Component 才能使用。新增時必須提供完整規格（Name / Usage / Composition / Props / Constraints）。

Rule Enforcement

如果違反以下任一規則，Claude 必須立即停止、指出違反的規則、回到正確步驟：

✗跳過 Pipeline 步驟
✗Analyze 階段產出 code
✗Build 階段重新設計或新增結構
✗未使用 Pattern Mapping 而直接發明 component
✗Build step 自行做 token / color 決策
✗Token Enforcement：spacing / color / radius 必須使用 token，禁止 arbitrary value
✗Interaction State：禁止使用 'active' 作為 state 名稱；使用 pressed（短暫）或 selected（持久）

System Migration 規則

當進行 system-level 變更（如 height scale migration）時，必須遵守以下規則。

Spec Freeze

Scale 確認後不可在 implementation 階段再修改。所有數值在 execution 前鎖定。

Execution Scope

  • 每輪只修改明確列出的 component（如 Button + OutcomeAction）
  • 不可順便修改其他 component（如 ButtonGroup、InputGroup、Select）
  • 不可修改 product page（如 MarketCard、markets-page）

Verification

  • 所有目標 height 必須在 preview 中實測通過
  • Icon-only 必須維持正方形
  • 無 TypeScript 錯誤

Rollback 條件

  • layout shift > 4px → 停止
  • ButtonGroup misalignment → 停止
  • Input / Select height mismatch → 停止
  • 觸發時：回報 diff，不繼續

Audit Backlog

以下為已確認需要但尚未執行的 system-level audit 項目（截至 2026-04-16）。

Height Scale Migration — Phase 2

Button scale v1 (24/28/32/36/40) 已套用至 Button + OutcomeAction。以下 component 尚未對齊：

  • ButtonUtility — 獨立 size system，需 audit 是否與新 scale 衝突
  • ButtonGroup — wraps Buttons，需驗證 alignment 無 layout shift
  • InputGroup — in-data-input-wrapper overrides 參考舊 padding，需對齊
  • Select — trigger height 可能與新 Button scale 不一致

Outcome Color — Token Fixes

  • outcome-b-solid dark mode contrast (4.40:1) — 需 token 層調整 ✓ 2026-04-26 已修正（migrated to outcome-no + text-on-outcome-no-solid，per-family contrast 重新調校）
  • Light mode contrast — outcome-a-secondary 全面低於 AA，需 semantic token remap ✓ 2026-04-26 已修正（migrated to outcome-yes-secondary，green palette 在 light mode contrast 自然合規）

MarketCard — OutcomeAction Integration

MarketCard 仍使用 Badge + Button，需更新為 OutcomeAction。

Action group spacing — CDS row / list-item

MarketCdsRow 內 Buy Protection 與 Earn Yield 兩個 OutcomeAction 之間 gap 消失（預期 12–16px）。下一輪統一處理 spacing / layout polish。

  • MarketCdsRow — 確認內部 ACTION GROUP wrapper（grid grid-cols-2 gap-3）是否被 padding / divider 吃掉
  • MarketListItem — 同一 dual-action 結構，順便檢查是否有相同問題
  • 決定 spacing token：cluster-internal vs item-internal 應採 gap-3 還是 gap-4