Figma Code Connect 가이드

1. Figma Code Connect란?

"디자인은 끝났는데, 코드는 어디에 있죠?"

개발자와 디자이너 사이의 영원한 숙제를 해결하기 위해 Figma가 내놓은 강력한 솔루션, Figma Code Connect를 소개합니다. 2024년 Dev Mode의 정식 출시와 함께 등장한 이 기능은 단순히 디자인 스펙을 보여주는 것을 넘어, 여러분의 실제 디자인 시스템 코드(React, Swift, Kotlin 등)를 Figma Dev Mode에 직접 주입합니다.

더 이상 개발자가 Figma의 속성 값을 보고 "이건 padding: 16px이니까 size='medium'인가?"라고 추측할 필요가 없습니다. Code Connect는 Figma 컴포넌트와 여러분의 코드베이스를 1:1로 매핑하여, 디자이너가 만든 버튼을 클릭하는 순간 여러분이 작성한 실제 컴포넌트 코드를 바로 보여줍니다.

2. 핵심 개념 및 작동 원리

기존의 Figma 핸드오프가 '이미지'와 'CSS 속성값'을 전달하는 방식이었다면, Code Connect는 '로직'과 '맥락'을 전달합니다.

어떻게 작동하나요?

1. 매핑(Mapping): 코드베이스에 *.figma.tsx와 같은 설정 파일을 생성하여, Figma 컴포넌트의 프로퍼티(예: Variant, Boolean)와 실제 코드의 Props를 연결합니다.
2. 게시(Publishing): CLI 도구를 통해 이 매핑 정보를 Figma 서버로 전송합니다.
3. 확인(Inspect): Dev Mode에서 해당 컴포넌트를 선택하면, Figma가 자동으로 매핑된 코드를 렌더링하여 보여줍니다.

이 과정은 일회성이 아니며, 코드베이스가 업데이트될 때마다 CI/CD 파이프라인을 통해 동기화할 수 있어 항상 '단일 진실 공급원(Single Source of Truth)'을 유지할 수 있습니다.

3. 사전 준비 사항 (Prerequisites)

Code Connect는 강력하지만, 사용을 위해서는 몇 가지 조건이 필요합니다.

• Figma 플랜: Organization 또는 Enterprise 플랜이 필수입니다. (Starter나 Professional 플랜에서는 사용할 수 없습니다.)
• Figma Dev Mode: 개발자 모드 라이선스가 필요합니다.
• 지원 언어/프레임워크: 현재 React (React Native 포함), Swift (iOS), Jetpack Compose (Android) 등을 공식 지원하며, Storybook과의 연동도 강력하게 지원합니다.

4. 빠른 시작 (Quick Start)

React 프로젝트를 기준으로 가장 빠르게 Code Connect를 설정하는 방법을 알아봅니다.

4.1 설치 및 초기화

먼저 프로젝트에 패키지를 설치합니다.

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

그 다음, 초기화 명령어를 실행하여 설정 파일을 생성합니다.

npx figma init

이 명령을 실행하면 프로젝트 루트에 figma.config.json 파일이 생성됩니다. 여기에 Figma 접근 토큰(Access Token)과 문서 URL 등을 설정해야 합니다.

figma.config.json 예시:

{
  "codeConnect": {
    "include": ["src/**/*.figma.tsx"],
    "exclude": ["**/node_modules/**"]
  },
  "interactive": true
}

4.2 컴포넌트 연결하기

Figma 디자인 파일에서 연결하고 싶은 컴포넌트를 우클릭하고 Copy link to selection을 선택하여 URL을 확보합니다. 그리고 CLI를 사용해 스캐폴딩 코드를 생성할 수 있습니다.

npx figma connect create "Figma_Component_URL"

5. 실전 코드 예제: 버튼 컴포넌트 매핑

실제 현업에서 가장 많이 쓰이는 버튼(Button) 컴포넌트를 예로 들어보겠습니다. Button.figma.tsx 파일을 생성하여 다음과 같이 작성합니다.

이 코드는 Figma의 Type 속성을 코드의 variant prop으로, Has Icon 속성을 icon prop 유무로 변환합니다.

import React from 'react';
import { Button } from './Button'; // 실제 컴포넌트
import figma from '@figma/code-connect';

/**
 * Figma Button 컴포넌트와 실제 React 코드를 연결합니다.
 */
figma.connect(
  Button,
  "https://www.figma.com/design/abcdef/MySystem?node-id=123-456", // Figma 컴포넌트 링크
  {
    props: {
      // Figma의 'Label' 텍스트 레이어 내용을 children으로 매핑
      label: figma.string('Label'),

      // Figma의 'Type' Variant (Primary, Secondary)를 enum으로 매핑
      variant: figma.enum('Type', {
        'Primary': 'primary',
        'Secondary': 'secondary',
        'Ghost': 'ghost',
      }),

      // Figma의 'Disabled' Boolean 속성을 boolean으로 매핑
      disabled: figma.boolean('Disabled'),

      // Figma의 'Has Icon'이 true일 때만 특정 아이콘 코드 노출
      icon: figma.boolean('Has Icon', {
        true: <Icon name="check" />,
        false: undefined,
      }),

      // 이벤트 핸들러 예시
      onClick: figma.value(() => console.log('Clicked!')),
    },
    // Dev Mode에 표시될 예시 코드 템플릿
    example: ({ label, variant, disabled, icon, onClick }) => (
      <Button 
        variant={variant} 
        disabled={disabled} 
        onClick={onClick}
        icon={icon}
      >
        {label}
      </Button>
    ),
  }
);

이렇게 작성하면 Figma Dev Mode에서 Primary 버튼을 클릭했을 때, <Button variant="primary">...</Button>과 같은 정확한 코드가 표시됩니다.

6. 시뮬레이션: CLI 게시 및 결과

⚠️ 아래 내용은 실제 실행 결과가 아닌 텍스트 시뮬레이션입니다.

Code Connect 설정을 마친 후, Figma 서버에 이 정보를 게시하는 과정을 시뮬레이션해 봅니다.

명령어 실행:

npx figma connect publish

터미널 출력 결과:

> my-design-system@1.0.0 figma-connect
> figma connect publish

Running Code Connect publish...
Parsing configuration from figma.config.json...
Found 15 Code Connect files in src/

Analyzing Button.figma.tsx... OK
Analyzing Card.figma.tsx... OK
Analyzing Input.figma.tsx... 
  Warning: Property 'ShowLabel' in Figma does not match any prop in the code definition. 
  It will be ignored.
Analyzing Modal.figma.tsx... OK

Validating against Figma design file...
✔ Successfully connected 14 components
⚠ 1 component has warnings

Uploading metadata to Figma...
✔ Published to file "Design System v2.0"

You can now view your connected components in Dev Mode!
🔗 https://www.figma.com/file/abcdef/MySystem

시나리오 분석:

1. 경고 발생 (Input.figma.tsx): Figma에는 ShowLabel이라는 Variant가 있지만, 코드 매핑 설정에서 이를 누락했거나 이름이 일치하지 않아 경고가 발생했습니다. 하지만 게시 자체는 성공하여 다른 속성들은 정상적으로 보입니다.
2. 성공: 나머지 14개 컴포넌트는 완벽하게 동기화되었습니다. 이제 디자이너가 디자인을 수정해도 개발자는 항상 최신 코드를 참조할 수 있습니다.

7. 결론

Figma Code Connect는 디자인 시스템을 운영하는 조직에게 선택이 아닌 필수가 되어가고 있습니다. 단순히 시간을 절약하는 것을 넘어, 디자인과 개발 간의 언어 장벽을 허무는 역할을 합니다.

초기 설정에는 약간의 공수가 들지만, 한 번 구축해 두면 개발자는 더 이상 "이 버튼 마진이 왜 이렇죠?"라고 묻는 대신, "코드에 정의된 대로 구현되었습니다"라고 자신 있게 말할 수 있게 됩니다. 지금 바로 여러분의 팀에 '진실된 코드'를 연결해 보세요.

8. TL;DR

• Dev Mode 전용: Figma Dev Mode에서 실제 컴포넌트 코드를 바로 볼 수 있게 해주는 기능입니다.
• 1:1 매핑: 단순 스니펫 생성이 아니라, figma.connect API를 통해 Figma 속성과 코드 Props를 정밀하게 연결합니다.
• 엔터프라이즈 기능: Organization 또는 Enterprise 플랜에서만 사용 가능합니다.
• 자동화 가능: CLI를 통해 CI/CD 파이프라인에 통합하여 디자인과 코드의 싱크를 자동으로 맞출 수 있습니다.
• 다양한 지원: React, Swift, Android(Compose) 등을 공식 지원합니다.

9. 참고 링크

• Figma 공식 문서: Code Connect
• npm: @figma/code-connect
• Figma Dev Mode 소개