Claude Code × Figma MCP × GitHub Actions: 디자인 토큰 CI/CD 자동화 실전 가이드

┌─────────────────────────────────────────────┐
│  1. MCP Layer                               │
│  Claude Code ↔ Figma MCP Server             │
│  (로컬 개발 시 실시간 디자인 컨텍스트 조회)   │
├─────────────────────────────────────────────┤
│  2. Token Sync Layer                        │
│  Figma Variables → Style Dictionary         │
│  → 플랫폼별 토큰 파일 (CSS / iOS / Android) │
├─────────────────────────────────────────────┤
│  3. CI/CD Layer                             │
│  GitHub Actions → 토큰 변경 감지            │
│  → 자동 PR 생성 → 리뷰 → 배포              │
└─────────────────────────────────────────────┘

// tokens/color.json (W3C 표준 포맷 — Style Dictionary v4 기준)
{
  "color": {
    "primary": {
      "500": {
        "$value": "#3B82F6",
        "$type": "color",
        "$description": "Primary brand color"
      }
    }
  }
}

// .mcp.json (프로젝트 루트에 커밋)
{
  "mcpServers": {
    "figma": {
      "type": "http",
      "url": "https://mcp.figma.com/mcp",
      "headers": {
        "Authorization": "Bearer ${FIGMA_PERSONAL_ACCESS_TOKEN}"
      }
    }
  }
}

# ~/.zshrc
export FIGMA_PERSONAL_ACCESS_TOKEN="figd_your_personal_access_token"

# 프로젝트 범위 MCP 등록
# --scope project: 현재 프로젝트에만 적용
# --transport http: HTTP 기반 Remote 서버 방식
claude mcp add --scope project --transport http figma https://mcp.figma.com/mcp
 
# 사용자 전역 범위 등록
# --scope user: 이 사용자의 모든 프로젝트에 적용
claude mcp add --scope user --transport http figma https://mcp.figma.com/mcp

# Claude Code 세션에서 실행
claude "Figma 파일 https://figma.com/file/ABC123 의 Button 컴포넌트를
       우리 디자인 시스템 토큰을 사용해 React 컴포넌트로 구현해줘"

// MCP 컨텍스트로 생성된 Button 컴포넌트
// --color-primary-500, --spacing-* 등 토큰 이름은 get_variable_defs 응답에서 왔습니다
import styles from './Button.module.css';
 
interface ButtonProps {
  variant?: 'primary' | 'secondary';
  size?: 'sm' | 'md' | 'lg';
  children: React.ReactNode;
}
 
export function Button({ variant = 'primary', size = 'md', children }: ButtonProps) {
  return (
    <button className={`${styles.button} ${styles[variant]} ${styles[size]}`}>
      {children}
    </button>
  );
}

/* Button.module.css — 토큰 변수명이 하드코딩 없이 그대로 사용됨 */
.button {
  background-color: var(--color-primary-500);
  color: var(--color-neutral-0);
  padding: var(--spacing-2) var(--spacing-4);
  border-radius: var(--border-radius-md);
  font-size: var(--font-size-sm);
}

Figma Variables 변경
    ↓
Figma REST API (/v1/files/:file_id/variables/local)
    ↓
tokens/figma-variables.json → Git Push
    ↓
GitHub Actions 트리거
    ↓
Style Dictionary 변환 (CSS / iOS / Android)
    ↓
자동 PR 생성 → 리뷰 → Merge → 배포

// scripts/export-tokens.ts
import fs from 'fs/promises';
 
interface FigmaVariable {
  id: string;
  name: string;
  resolvedType: string;
  valuesByMode: Record<string, unknown>;
}
 
interface FigmaVariableCollection {
  id: string;
  name: string;
  modes: Array<{ modeId: string; name: string }>;
  defaultModeId: string;
}
 
function transformVariablesToTokens(
  variables: Record<string, FigmaVariable>,
  collections: Record<string, FigmaVariableCollection>
): Record<string, unknown> {
  const tokens: Record<string, unknown> = {};
 
  for (const variable of Object.values(variables)) {
    const collection = collections[
      Object.keys(collections).find(id =>
        collections[id].name === variable.name.split('/')[0]
      ) ?? ''
    ];
    const defaultModeId = collection?.defaultModeId;
    const value = defaultModeId ? variable.valuesByMode[defaultModeId] : undefined;
 
    // "color/primary/500" → { color: { primary: { "500": { $value, $type } } } }
    const parts = variable.name.split('/');
    let cursor = tokens;
    for (let i = 0; i < parts.length - 1; i++) {
      if (!cursor[parts[i]]) cursor[parts[i]] = {};
      cursor = cursor[parts[i]] as Record<string, unknown>;
    }
    cursor[parts[parts.length - 1]] = {
      $value: value,
      $type: variable.resolvedType.toLowerCase(),
    };
  }
 
  return tokens;
}
 
async function main() {
  const fileId = process.env.FIGMA_FILE_ID;
  const token = process.env.FIGMA_TOKEN;
 
  if (!fileId || !token) {
    throw new Error('FIGMA_FILE_ID와 FIGMA_TOKEN 환경변수가 필요합니다');
  }
 
  // /local 엔드포인트: 이 파일에 정의된 로컬 변수만 반환
  const response = await fetch(
    `https://api.figma.com/v1/files/${fileId}/variables/local`,
    { headers: { 'X-Figma-Token': token } }
  );
 
  if (!response.ok) {
    throw new Error(`Figma API 오류: ${response.status} ${response.statusText}`);
  }
 
  const { meta } = await response.json();
  const tokens = transformVariablesToTokens(
    meta.variables,
    meta.variableCollections
  );
 
  await fs.mkdir('tokens', { recursive: true });
  await fs.writeFile('tokens/figma-variables.json', JSON.stringify(tokens, null, 2));
 
  // GitHub Actions output 설정
  const changedCount = Object.keys(meta.variables).length;
  const outputFile = process.env.GITHUB_OUTPUT;
  if (outputFile) {
    await fs.appendFile(outputFile, `changed_count=${changedCount}\n`);
  }
 
  console.log(`토큰 추출 완료: ${changedCount}개`);
}
 
main().catch(err => {
  console.error(err);
  process.exit(1);
});

// style-dictionary.config.js (ES Module 기준)
// CommonJS 환경이라면: module.exports = { ... }
export default {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'src/styles/tokens/',
      files: [{ destination: 'variables.css', format: 'css/variables' }],
    },
    ios: {
      transformGroup: 'ios-swift',
      buildPath: 'ios/DesignTokens/',
      files: [{ destination: 'DesignTokens.swift', format: 'ios-swift/class.swift' }],
    },
    android: {
      transformGroup: 'android',
      buildPath: 'android/src/main/res/values/',
      files: [{ destination: 'design_tokens.xml', format: 'android/resources' }],
    },
  },
};

# .github/workflows/sync-design-tokens.yml
name: Sync Design Tokens
 
on:
  push:
    paths:
      - 'tokens/**'
  workflow_dispatch:
    inputs:
      figma_file_id:
        description: 'Figma File ID'
        required: true
 
jobs:
  sync-tokens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - uses: pnpm/action-setup@v3
        with:
          version: 9
 
      - name: Install dependencies
        run: pnpm install
 
      - name: Export Figma Variables
        id: export
        env:
          FIGMA_TOKEN: ${{ secrets.FIGMA_PERSONAL_ACCESS_TOKEN }}
          FIGMA_FILE_ID: ${{ github.event.inputs.figma_file_id || vars.FIGMA_FILE_ID }}
        run: pnpm tokens:export
 
      - name: Build Tokens
        run: pnpm tokens:build
 
      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v6
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          commit-message: 'chore: sync design tokens from Figma'
          title: '[Design System] Figma 토큰 자동 동기화'
          branch: 'chore/sync-design-tokens'
          body: |
            Figma Variables에서 자동으로 추출된 토큰 변경사항입니다.
            - 변경된 토큰: ${{ steps.export.outputs.changed_count }}개
 
            변경 전 리뷰 후 Merge해 주시기 바랍니다.