Figma Code Connect로 디자인 컴포넌트에 실제 코드 연결하기
Figma Code Connect는 Figma의 Dev Mode 안에서 디자인 컴포넌트와 코드베이스의 실제 컴포넌트를 이어 주는 기능이다. 한번 연결해 두면 개발자가 Figma에서 컴포넌트를 눌렀을 때 자동 생성된 CSS가 아니라 팀이 실제로 쓰는 코드 스니펫이 나온다. 도입 과정은 npm 패키지 설치, 매핑 파일 작성, publish 이렇게 세 단계로 끝난다.
Figma Code Connect는 무엇을 해결하나
디자인과 코드 사이의 번역 문제를 줄여 준다. Dev Mode의 기본 코드 패널은 도형 정보를 바탕으로 CSS나 대략적인 마크업을 만들어 보여 주는데, 이 결과가 팀의 실제 컴포넌트와 맞지 않는 경우가 많다. 버튼 하나를 넘겨받아도 개발자는 결국 디자인 시스템 문서를 다시 뒤져 우리 Button 컴포넌트가 어떤 prop을 받는지 확인해야 했다.
Code Connect를 붙이면 이 단계가 사라진다. Figma의 그 버튼이 코드에서 어떤 컴포넌트이고 variant나 size 같은 속성을 어떻게 넘기는지가 화면에 그대로 뜬다. 디자인 시스템 규모가 커질수록, 그리고 디자이너와 개발자가 같은 컴포넌트를 서로 다른 이름으로 부를수록 효과가 크다.
설정은 어떻게 하나
먼저 프로젝트에 @figma/code-connect 패키지를 설치한다. 그다음 Figma 액세스 토큰을 발급해 환경 변수나 설정 파일에 넣어 둔다. CLI에는 create와 publish 명령이 있는데, create는 선택한 컴포넌트의 매핑 파일 뼈대를 만들어 주고 publish는 완성한 매핑을 Figma에 올린다.
매핑 파일은 보통 컴포넌트 옆에 Button.figma.tsx 같은 이름으로 둔다. 그 안에서 figma.connect 함수를 호출해 코드 컴포넌트와 Figma 노드 URL을 연결한다. URL은 대상 컴포넌트를 Figma에서 선택한 뒤 링크를 복사하면 얻을 수 있다. 여기까지 하고 publish하면 Dev Mode 패널에 우리 코드가 노출된다.
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 속성 이름을 틀리게 적으면 값이 비어서 나오니, 매핑이 이상할 땐 이 부분을 먼저 확인하는 편이 빠르다.
어떤 프레임워크를 쓸 수 있나
웹만 되는 기능은 아니다. React를 비롯해 SwiftUI, Jetpack Compose, 그리고 일반 HTML과 웹 컴포넌트를 지원하는 것으로 알려져 있다. 같은 디자인 컴포넌트를 두고 웹 팀과 iOS, Android 팀이 각자 자기 코드로 매핑을 만들 수 있다는 뜻이다.
다만 문법은 프레임워크마다 조금씩 다르다. React라면 JSX로 example을 적고, SwiftUI나 Compose라면 그 언어의 문법으로 적는다. 팀이 쓰는 스택에 맞는 문서를 먼저 확인하고 시작하는 편이 낫다.
도입 전에 챙길 점
Dev Mode는 유료 플랜에서 제공되는 것으로 알려져 있으니, 팀 요금제부터 확인하는 게 좋다. 그리고 Code Connect는 한 번 붙여 놓고 끝나는 작업이 아니다. 코드 컴포넌트의 prop이 바뀌면 매핑도 같이 고쳐 다시 publish해야 화면에 맞는 코드가 나온다.
그래서 처음부터 모든 컴포넌트를 연결하려 들기보다, 버튼이나 입력창처럼 자주 쓰는 핵심 컴포넌트 몇 개로 시작하길 권한다. 효과를 눈으로 확인한 뒤 범위를 넓히면 유지보수 부담도 줄고 팀을 설득하기도 쉽다. 매핑 파일을 컴포넌트 코드 옆에 두고 함께 리뷰하면, prop이 바뀔 때 매핑도 고치는 습관이 자연스럽게 자리 잡는다.