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 映射格式

// 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 待批准

工具需求

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

發布指令（需 Figma Personal Access Token）：

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
• feedback_ui_collaboration_protocol.md
• Figma Code Connect 官方文件：https://www.figma.com/developers/code-connect