awoooi/docs/adr/ADR-049-figma-code-connect-design-system.md

# ADR-049: Figma Code Connect 設計系統同步

| 項目 | 內容 |
|------|------|
| **狀態** | 📋 已批准，待實作 |
| **日期** | 2026-04-01 |
| **決策者** | 首席架構師 + 統帥 |
| **觸發** | MCP 整合長期計畫 |

## 背景

前端 UI 元件與 Figma 設計稿可能產生漂移（drift）：設計師在 Figma 更新了元件樣式或佈局，但 `apps/web/src/components/` 下的 React 元件未同步更新，導致 QA 發現視覺差異時已累積大量技術債。

目前缺乏任何機制能夠：
1. 讓設計師在 Figma 中直接看到對應的程式碼元件
2. 在 Code Review 時確認 UI 實作與設計稿的一致性
3. 系統化追蹤哪些元件存在 design-code drift

## 問題

| 面向 | 現況 | 目標 |
|------|------|------|
| 設計-代碼映射 | 無正式對應關係 | Figma 元件 ↔ React 元件 1:1 映射 |
| 漂移偵測 | 手動 QA 發現 | 每週自動掃描確認映射狀態 |
| 設計師工作流 | 不知道對應哪支 component | Figma Dev Mode 直接顯示程式碼 |

## 決策

使用 **Figma Code Connect** 建立 `.figma.js` 映射文件，將每個 Figma 元件對應到 React 元件的 import 與 props 結構。

定期（每週）使用 Figma MCP 掃描設計稿，確認映射是否需要更新。

## 架構

### 文件結構

```
apps/web/src/components/
├── ui/
│   ├── button/
│   │   ├── Button.tsx
│   │   └── Button.figma.js          ← Code Connect 映射
│   ├── card/
│   │   ├── Card.tsx
│   │   └── Card.figma.js
│   └── badge/
│       ├── Badge.tsx
│       └── Badge.figma.js
├── incident/
│   ├── IncidentCard.tsx
│   └── IncidentCard.figma.js
└── approval/
    ├── ApprovalCard.tsx
    └── ApprovalCard.figma.js
```

### Code Connect 映射格式

```js
// Button.figma.js
import figma from '@figma/code-connect'
import { Button } from './Button'

figma.connect(Button, 'https://www.figma.com/design/FILEID?node-id=NODE_ID', {
  props: {
    variant: figma.enum('Variant', {
      primary: 'primary',
      secondary: 'secondary',
      destructive: 'destructive',
    }),
    size: figma.enum('Size', {
      sm: 'sm',
      md: 'md',
      lg: 'lg',
    }),
    label: figma.string('Label'),
    disabled: figma.boolean('Disabled'),
  },
  example: ({ variant, size, label, disabled }) => (
    <Button variant={variant} size={size} disabled={disabled}>
      {label}
    </Button>
  ),
})
```

### 每週掃描流程

```
Claude Code + Figma MCP
  → get_design_context (核心元件節點)
  → get_code_connect_suggestions
  → 比對現有 .figma.js 映射
  → 輸出「drift report」
  → 若有差異 → 建立 GitHub Issue
```

## 實作計畫

### P1：核心 UI 元件（第 1 週）

| 元件 | Figma 節點 | React 路徑 |
|------|------------|------------|
| Button | TBD | `components/ui/button/Button.tsx` |
| Card | TBD | `components/ui/card/Card.tsx` |
| Badge | TBD | `components/ui/badge/Badge.tsx` |
| Input | TBD | `components/ui/input/Input.tsx` |
| Modal | TBD | `components/ui/modal/Modal.tsx` |

**前置條件**: 確認 Figma 文件 URL 與節點 ID（需統帥提供）

### P2：業務元件（第 2-3 週）

| 元件 | Figma 節點 | React 路徑 |
|------|------------|------------|
| IncidentCard | TBD | `components/incident/IncidentCard.tsx` |
| ApprovalCard | TBD | `components/approval/ApprovalCard.tsx` |
| AlertBanner | TBD | `components/alert/AlertBanner.tsx` |
| StatusBadge | TBD | `components/status/StatusBadge.tsx` |

### P3：Storybook 整合（第 4 週，視現況決定）

- 確認是否已有 Storybook 設置
- 若已有：在 Story 中引用 Code Connect 映射
- 若未有：評估導入成本，記入 INSPIRATION_LAB.md 待批准

## 工具需求

```json
// package.json (apps/web)
{
  "devDependencies": {
    "@figma/code-connect": "^1.x"
  }
}
```

發布指令（需 Figma Personal Access Token）：
```bash
npx figma connect publish --token $FIGMA_ACCESS_TOKEN
```

## 注意事項

1. **Figma URL 需要統帥提供**：在執行 P1 前，需要確認 Figma 設計稿的文件 ID 和各核心元件的節點 ID
2. **Token 管理**：`FIGMA_ACCESS_TOKEN` 需存入 K8s Secrets，不得 hardcode
3. **每週掃描**：由 Claude Code + Figma MCP 執行，不需要新增 CI 步驟
4. **`.figma.js` 檔案不影響 build**：只在開發環境和 Code Connect 發布時使用

## 影響

| 面向 | 影響 |
|------|------|
| **設計師** | Figma Dev Mode 可直接看到對應元件的 import 和 props |
| **前端開發** | PR 時有明確參考，減少「我以為設計是這樣」問題 |
| **QA** | 視覺差異有跡可查，drift report 提前預警 |
| **Build 時間** | 無影響，`.figma.js` 不參與 webpack/next build |

## 相關文件

- [feedback_design_system_quickref.md](~/.claude/projects/-Users-ogt-awoooi/memory/feedback_design_system_quickref.md)
- [feedback_ui_collaboration_protocol.md](~/.claude/projects/-Users-ogt-awoooi/memory/feedback_ui_collaboration_protocol.md)
- Figma Code Connect 官方文件：https://www.figma.com/developers/code-connect