Figma Code Connect 2026: 컴포넌트 매핑으로 디자인-개발 싱크 자동화하기

이 글은 누구를 위한 것인가

• Figma Dev Mode를 사용하면서 "이 컴포넌트 코드가 어디 있지?"를 반복하는 개발자
• 디자인과 코드 사이의 불일치를 줄이고 싶은 디자인 시스템 팀
• Code Connect를 처음 도입하려는 프론트엔드 엔지니어

---

들어가며

Figma Dev Mode에서 컴포넌트를 클릭하면 CSS 속성이 나온다. 하지만 실제로 개발자가 필요한 것은 "이 컴포넌트를 코드에서 어떻게 사용하는가"다. CSS 값을 보고 직접 컴포넌트를 찾아서 Props를 맞추는 과정이 지금도 많은 팀에서 반복되고 있다.

Figma Code Connect는 이 문제를 해결한다. Figma 컴포넌트와 실제 코드 컴포넌트를 연결하면, Dev Mode에서 컴포넌트를 클릭할 때 실제 사용 코드 스니펫이 바로 표시된다. "디자인을 보면 코드를 바로 복사해서 쓸 수 있는" 경험이다.

이 글은 bluefoxdev.kr의 Figma 개발자 워크플로우 를 참고하고, Code Connect 실전 적용 관점에서 확장하여 작성했습니다.

---

1. Code Connect 설치와 초기 설정

1.1 설치

npm install --save-dev @figma/code-connect

1.2 Figma 토큰 설정

# Figma Personal Access Token 설정
export FIGMA_ACCESS_TOKEN="your_token_here"

# 또는 .env 파일에 저장
FIGMA_ACCESS_TOKEN=your_token_here

1.3 첫 번째 연결 파일 생성

# Code Connect가 컴포넌트를 자동 감지하여 연결 파일 초안 생성
npx figma connect create https://www.figma.com/design/[file-key]/[file-name]

# 특정 컴포넌트만 생성
npx figma connect create --node-id [node-id]

---

2. 컴포넌트 매핑 실전

2.1 기본 컴포넌트 연결

// src/components/Button/Button.figma.ts
import figma from '@figma/code-connect';
import { Button } from './Button';

figma.connect(
  Button,
  'https://www.figma.com/design/FILE_KEY/Design-System?node-id=123:456',
  {
    props: {
      // Figma의 "Label" 텍스트 레이어 → children prop
      children: figma.string('Label'),
      
      // Figma의 "Variant" 속성 → variant prop 매핑
      variant: figma.enum('Variant', {
        'Primary': 'primary',
        'Secondary': 'secondary',
        'Destructive': 'destructive',
        'Ghost': 'ghost',
      }),
      
      // Figma의 "Size" 속성 → size prop
      size: figma.enum('Size', {
        'Small': 'sm',
        'Medium': 'md',
        'Large': 'lg',
      }),
      
      // Figma의 "Disabled" boolean → disabled prop
      disabled: figma.boolean('Disabled'),
      
      // Figma의 "Icon" 인스턴스 → 아이콘 컴포넌트
      leftIcon: figma.instance('Left Icon'),
    },
    
    example: ({ children, variant, size, disabled, leftIcon }) => (
      <Button
        variant={variant}
        size={size}
        disabled={disabled}
        leftIcon={leftIcon}
      >
        {children}
      </Button>
    ),
  }
);

2.2 복잡한 컴포넌트: 카드

// Card.figma.ts
import figma from '@figma/code-connect';
import { Card, CardHeader, CardContent, CardFooter } from './Card';

figma.connect(
  Card,
  'https://www.figma.com/design/FILE_KEY/Design-System?node-id=789:012',
  {
    props: {
      title: figma.string('Title'),
      description: figma.string('Description'),
      hasBorder: figma.boolean('Has Border'),
      isElevated: figma.boolean('Elevated'),
      footer: figma.boolean('Show Footer'),
    },
    
    example: ({ title, description, hasBorder, isElevated, footer }) => (
      <Card
        variant={isElevated ? 'elevated' : hasBorder ? 'outlined' : 'filled'}
      >
        <CardHeader>
          <h3>{title}</h3>
        </CardHeader>
        <CardContent>
          <p>{description}</p>
        </CardContent>
        {footer && (
          <CardFooter>
            <Button variant="primary">확인</Button>
          </CardFooter>
        )}
      </Card>
    ),
  }
);

---

3. 자동 동기화 파이프라인 구축

3.1 GitHub Actions로 배포 자동화

# .github/workflows/code-connect.yml
name: Figma Code Connect Sync

on:
  push:
    branches: [main]
    paths:
      - 'src/components/**/*.figma.ts'

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Publish Code Connect
        run: npx figma connect publish --token ${{ secrets.FIGMA_ACCESS_TOKEN }}
        
      - name: Notify on success
        uses: slackapi/slack-github-action@v1
        with:
          payload: '{"text":"✅ Figma Code Connect 업데이트 완료"}'
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK }}

3.2 연결 상태 검증

# 연결 파일 파싱 오류 확인
npx figma connect parse

# 연결된 컴포넌트 목록 확인
npx figma connect list

# 실제 Figma에 게시하기 전 드라이런
npx figma connect publish --dry-run

---

4. Storybook 연동

Code Connect와 Storybook을 함께 사용하면 시너지가 크다. Figma에서 컴포넌트를 보면서 코드 스니펫을 확인하고, Storybook에서 동작하는 컴포넌트를 직접 확인하는 흐름이 이어진다.

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta = {
  title: 'Components/Button',
  component: Button,
  parameters: {
    design: {
      type: 'figma',
      url: 'https://www.figma.com/design/FILE_KEY/Design-System?node-id=123:456',
    },
  },
} satisfies Meta<typeof Button>;

export const Primary: StoryObj<typeof Button> = {
  args: {
    variant: 'primary',
    size: 'md',
    children: '버튼',
  },
};

---

5. 실전 팀 도입 사례

5.1 도입 전/후 비교

항목	도입 전	도입 후
컴포넌트 검색 시간	5~10분	즉시
Props 확인 방법	개발자 직접 문서 확인	Figma Dev Mode에서 바로 확인
디자인-코드 불일치	주 2~3건 발생	90% 감소
신규 개발자 온보딩	1~2주	3~4일

---

마무리: Code Connect 도입 체크리스트

• 핵심 컴포넌트 20~30개 우선 연결 (버튼, 입력, 카드, 모달)
• CI/CD 파이프라인에 자동 게시 추가
• Storybook과 Figma URL 연동
• 팀 온보딩: 개발자와 디자이너 모두 사용법 공유
• 분기마다 연결 상태 점검 (컴포넌트 변경에 따른 업데이트)

Code Connect는 도구가 아니라 워크플로우 변화다. 처음 설정 비용이 있지만, 팀 전체의 커뮤니케이션 효율이 눈에 띄게 향상된다.