Figma 목업에서 정확한 코드 받기, Code Connect

게시 2026.07.10 · 최종 업데이트 2026.07.14 · 약 6분 분량

Figma Code Connect는 Figma의 Dev Mode 안에서 디자인 컴포넌트와 코드베이스의 실제 컴포넌트를 이어 주는 기능이다. 한번 연결해 두면 개발자가 Figma에서 컴포넌트를 눌렀을 때 자동 생성된 CSS가 아니라 팀이 실제로 쓰는 코드 스니펫이 나온다. 도입 과정은 npm 패키지 설치, 매핑 파일 작성, publish 이렇게 세 단계로 끝난다.

Figma Code Connect는 무엇을 해결하나

디자인과 코드 사이의 번역 문제를 줄여 준다. Dev Mode의 기본 코드 패널은 도형 정보를 바탕으로 CSS나 대략적인 마크업을 만들어 보여 주는데, 이 결과가 팀의 실제 컴포넌트와 맞지 않는 경우가 많다. 버튼 하나를 넘겨받아도 개발자는 결국 디자인 시스템 문서를 다시 뒤져 우리 Button 컴포넌트가 어떤 prop을 받는지 확인해야 했다.

Code Connect를 붙이면 이 단계가 사라진다. Figma의 그 버튼이 코드에서 어떤 컴포넌트이고 variant나 size 같은 속성을 어떻게 넘기는지가 화면에 그대로 뜬다. 디자인 시스템 규모가 커질수록, 그리고 디자이너와 개발자가 같은 컴포넌트를 서로 다른 이름으로 부를수록 효과가 크다. 피그마가 2024년 4월 공식 블로그에서 베타로 처음 공개한 기능이고, 당시 발표 글도 개발자가 문서를 뒤지는 대신 컴포넌트를 클릭해 승인된 코드 샘플을 바로 얻게 한다는 점을 핵심으로 내세웠다.

설정은 어떻게 하나

먼저 프로젝트에 @figma/code-connect 패키지를 설치한다. 그다음 Figma 액세스 토큰을 발급해 환경 변수나 설정 파일에 넣어 둔다. 피그마 개발자 문서에 따르면 토큰은 Code Connect 스코프를 쓰기(Write), File content 스코프를 읽기(Read)로 발급해야 하고, 환경 변수 FIGMA_ACCESS_TOKEN에 넣어 두면 명령마다 --token 옵션을 붙이지 않아도 된다. CLI에는 create와 publish 명령이 있는데, create는 선택한 컴포넌트의 매핑 파일 뼈대를 만들어 주고 publish는 완성한 매핑을 Figma에 올린다. 발행 명령은 npx figma connect publish --token=<액세스 토큰> 형태다.

매핑 파일은 보통 컴포넌트 옆에 Button.figma.tsx 같은 이름으로 둔다. 그 안에서 figma.connect 함수를 호출해 코드 컴포넌트와 Figma 노드 URL을 연결한다. URL은 대상 컴포넌트를 Figma에서 선택한 뒤 링크를 복사하면 얻을 수 있다. 여기까지 하고 publish하면 Dev Mode 패널에 우리 코드가 노출된다.

React 컴포넌트라면 매핑 파일의 뼈대는 다음과 같은 모양이 된다.

// Button.figma.tsx
import figma from "@figma/code-connect";
import { Button } from "./Button";

figma.connect(Button, "https://www.figma.com/design/FILE?node-id=1-23", {
 props: {
  label: figma.string("Label"),
  variant: figma.enum("Variant", { Primary: "primary", Secondary: "secondary" }),
  disabled: figma.boolean("Disabled"),
 },
 example: ({ label, variant, disabled }) => (
  <Button variant={variant} disabled={disabled}>{label}</Button>
 ),
});

props 매핑은 어떻게 작성하나

figma.connect의 세 번째 인자에 props와 example을 적는다. props는 Figma의 속성 이름을 코드 prop으로 바꾸는 규칙이고, example은 그 컴포넌트를 실제로 쓰는 코드 조각이다. 핵심은 Figma에서 정의한 속성 이름을 정확히 적어 주는 것이다.

자주 쓰는 매핑 도우미는 다음과 같다.

• figma.string은 텍스트 속성을 문자열 prop으로 가져온다. 버튼 라벨 같은 값에 쓴다.
• figma.boolean은 켜고 끄는 속성을 true나 false로 매핑한다. disabled 같은 값에 맞다.
• figma.enum은 여러 옵션 중 하나를 고르는 속성을 코드 값으로 바꾼다. variant나 size에 자주 쓴다.
• figma.instance는 다른 컴포넌트를 품고 있는 속성을 연결한다. 아이콘 슬롯 같은 곳에 쓴다.
• figma.children은 컴포넌트 안에 들어가는 자식 요소를 넘긴다.

이 도우미들이 돌려준 값을 example 안에서 props로 꺼내 쓰면 된다. Figma 속성 이름을 틀리게 적으면 값이 비어서 나오니, 매핑이 이상할 땐 이 부분을 먼저 확인하는 편이 빠르다. 피그마 개발자 문서의 CLI 옵션인 --dry-run을 publish에 붙이면 실제 발행 없이 검증만 돌려볼 수 있어서, 속성 이름 실수를 올리기 전에 잡기 좋다.

어떤 프레임워크를 쓸 수 있나

웹만 되는 기능은 아니다. React를 비롯해 SwiftUI, Jetpack Compose, 일반 HTML과 웹 컴포넌트까지 피그마 개발자 문서가 지원 대상으로 안내한다. 같은 문서 기준으로 React Native, 그리고 HTML 계열인 Angular·Vue도 지원 대상에 들어 있다. 같은 디자인 컴포넌트를 두고 웹 팀과 iOS, Android 팀이 각자 자기 코드로 매핑을 만들 수 있다는 뜻이다.

다만 문법은 프레임워크마다 조금씩 다르다. React라면 JSX로 example을 적고, SwiftUI나 Compose라면 그 언어의 문법으로 적는다. 설치 채널도 갈린다. 피그마 공식 블로그에 따르면 자바스크립트·타입스크립트 프로젝트는 npm으로, SwiftUI는 Swift Package Manager로 설치한다. 팀이 쓰는 스택에 맞는 문서를 먼저 확인하고 시작하는 편이 낫다.

도입 전에 챙길 점

요금제부터 봐야 한다. 피그마 개발자 문서에 따르면 Code Connect는 Organization과 Enterprise 플랜의 Full 시트 또는 Dev 시트에서 제공된다 — 그 아래 플랜은 지원 대상이 아니다. 그리고 Code Connect는 한 번 붙여 놓고 끝나는 작업이 아니다. 코드 컴포넌트의 prop이 바뀌면 매핑도 같이 고쳐 다시 publish해야 화면에 맞는 코드가 나온다. 컴포넌트를 코드베이스에서 들어냈다면 npx figma connect unpublish --node=<노드 URL>로 연결도 함께 내린다.

그래서 처음부터 모든 컴포넌트를 연결하려 들기보다, 버튼이나 입력창처럼 자주 쓰는 핵심 컴포넌트 몇 개로 시작하길 권한다. 효과를 눈으로 확인한 뒤 범위를 넓히면 유지보수 부담도 줄고 팀을 설득하기도 쉽다. 매핑 파일을 컴포넌트 코드 옆에 두고 함께 리뷰하면, prop이 바뀔 때 매핑도 고치는 습관이 자연스럽게 자리 잡는다. 팀 단위 개발 도구의 좌석 과금을 따지는 방법은 깃허브 코파일럿 플랜 글에서와 같은 요령이 통한다.