책에 포함된 노트AI 시대의 피그마: 프롬프트로 디자인하고, 디자인으로 출시하는 법

부록 C. Dev Mode와 Code Connect 핸드오프 가이드

2026-04-26Views 57약 7분생성형 AI 활용

부록 C. Dev Mode와 Code Connect 핸드오프 가이드

좋은 핸드오프는 설명이 아니라 연결이다

디자인 핸드오프가 어려운 이유는 정보가 부족해서만이 아니다. 더 자주 문제를 만드는 것은 정보가 서로 떨어져 있다는 점이다. 화면은 피그마에 있고, 토큰은 다른 문서에 있고, 컴포넌트 구현은 저장소에 있고, 상태 정의와 예외 흐름은 회의록에 흩어져 있다. 그러니 개발자는 매번 추측한다. 이 버튼은 진짜 컴포넌트인가, 간격은 고정값인가 토큰인가, 이 화면의 빈 상태는 어디까지 구현해야 하는가.

이 간격을 줄여 주는 대표 도구가 Dev Mode와 Code Connect다. Dev Mode는 디자인 파일을 개발자가 읽기 쉬운 명세 문맥으로 바꿔 주고, Code Connect는 디자인 컴포넌트와 실제 코드 컴포넌트를 연결해 준다. 전자는 "무엇을 봐야 하는가"를 또렷하게 만들고, 후자는 "무엇을 써야 하는가"를 더 분명하게 만든다.¹²

이 부록의 핵심은 하나다. 핸드오프는 파일 전달이 아니라 연결 비용을 줄이는 일이다.

Dev Mode는 왜 필요한가

예전 핸드오프는 종종 스크린샷과 빨간 줄의 시대였다. 개발자는 픽셀 값을 재고, 디자이너는 옆에서 "여기는 12가 아니라 16이에요"라고 설명하고, 또 누군가는 다크 모드나 에러 상태가 빠졌다는 사실을 나중에 발견했다. 이 방식은 작은 팀에서도 피곤하고, 큰 팀에서는 거의 반드시 어딘가가 어긋난다.

Dev Mode는 이 문제를 줄이기 위해 만들어졌다. 같은 디자인 파일을 보더라도 개발자에게는 더 구현 친화적인 시점으로 보여 준다. 레이어 구조, 간격, 크기, 색, 텍스트 정보, 컴포넌트 관계, 일부 코드 예시를 한 맥락에서 읽을 수 있게 해 준다.¹

여기서 중요한 것은 Dev Mode가 자동으로 완벽한 명세를 만들어 주는 마술 도구가 아니라는 점이다. 정리된 파일일수록 Dev Mode도 정확해진다. 이름이 흐릿하고, 인스턴스가 깨져 있고, 오토 레이아웃이 무너져 있으면 개발자가 보게 되는 정보도 애매해진다.

Dev Mode에서 특히 도움이 되는 것들

1. 구조 읽기

개발자는 화면을 그림처럼 보는 대신 구조로 읽는다. 어떤 프레임이 컨테이너인지, 어떤 요소가 반복 컴포넌트인지, 어디에 오토 레이아웃이 걸려 있는지, 어떤 변수가 연결되어 있는지를 빨리 알아야 구현 방향을 정할 수 있다.

2. 수치 확인

간격, 크기, 반경, 색상, 타이포그래피 정보가 구조와 함께 보이면 "대충 비슷하게"가 줄어든다. 특히 spacing token과 raw 값이 섞여 있는 파일에서는 이 차이가 더 커진다.

3. 재사용 단서 파악

메인 컴포넌트와 인스턴스 관계가 정리되어 있으면, 개발자도 "이건 재사용 대상이구나"를 더 쉽게 알아차린다. 즉, Dev Mode는 명세를 보여줄 뿐 아니라 컴포넌트화의 단서도 제공한다.

좋은 Dev Mode를 만드는 사전 준비

Dev Mode는 켠다고 갑자기 좋아지지 않는다. 실제로는 파일 정리가 먼저다. 다음 네 가지는 특히 중요하다.

페이지와 상태를 나눠 두기

대표 화면, 변형 화면, 빈 상태, 에러 상태, 로딩 상태가 섞여 있으면 개발자는 어디를 기준으로 구현해야 할지 헷갈린다. 최소한 기준 화면과 예외 상태는 구분해 두는 편이 좋다.

프레임 이름을 분명하게 짓기

Final, v2, new, 진짜최종 같은 이름은 핸드오프에 거의 도움이 되지 않는다. Checkout / Default, Checkout / Error / Card declined처럼 역할과 상태가 드러나야 한다.

인스턴스를 깨끗하게 정리하기

라이브러리 인스턴스를 과하게 분해하거나, 메인 컴포넌트와 동떨어진 복사본이 많으면 재사용 경계가 흐려진다. 개발자는 결국 매번 새로 만들게 된다.

엣지 케이스를 숨기지 않기

실서비스 구현에서 자주 문제가 되는 것은 기본 상태가 아니라 예외 상태다. 긴 텍스트, 비어 있는 목록, 오류 메시지, 비활성 버튼, 다크 모드, 로딩 상태가 드러나 있어야 핸드오프가 덜 위험하다.

최소 핸드오프 세트는 무엇인가

실무에서 항상 엄청난 문서가 필요한 것은 아니다. 오히려 핵심만 빠지지 않는 편이 더 중요하다. 아래 정도만 갖춰도 핸드오프 품질이 눈에 띄게 좋아진다.

구현 기준이 되는 대표 프레임
연결된 컴포넌트와 인스턴스
변수·모드 정보
필요한 에셋의 export 설정
인터랙션과 예외 상태에 대한 짧은 주석
구현에서 제외되는 범위

여기서 마지막 항목이 특히 중요하다. 무엇을 하라는지 못지않게 무엇을 아직 하지 말아야 하는지를 밝혀야 추측 구현이 줄어든다.

Dev Mode의 코드 스니펫은 어디까지 믿어야 하나

Dev Mode가 보여 주는 코드 스니펫은 유용하지만, 그대로 프로덕션 코드가 되는 것은 아니다. 참고용 출발점으로는 좋지만, 팀의 컴포넌트 구조, 네이밍, 토큰 체계, 상태 처리 방식까지 완전히 대체하지는 못한다.¹

그래서 스니펫을 볼 때는 이렇게 읽는 편이 좋다.

구조를 이해하는 참고 자료로 읽기
CSS나 레이아웃 관계를 파악하는 단서로 쓰기
실제 코드베이스에는 팀 규칙에 맞게 다시 연결하기

이 태도를 놓치면 "Figma에서 코드가 나왔으니 이걸 그대로 쓰면 되겠지"라는 오해가 생긴다. 실무에서는 그 오해가 나중에 유지보수 비용으로 돌아온다.

Code Connect는 무엇을 더해 주는가

Code Connect는 디자인 컴포넌트와 코드 컴포넌트를 직접 연결해 주는 기능이다. 이 연결이 생기면 개발자는 Dev Mode에서 디자인을 보다가 곧바로 "이건 저장소의 어떤 컴포넌트인가"를 더 쉽게 파악할 수 있다. MCP를 쓰는 팀이라면 AI 에이전트도 그 연결 정보를 활용해 더 정확한 코드 생성을 시도할 수 있다.²³

여기서 중요한 차이가 하나 있다. Code Connect는 단순한 코드 예시보다 강하다. 왜냐하면 "이런 식으로 만들 수 있다"를 넘어서 "우리는 실제로 이것을 쓴다"에 가까운 단서를 주기 때문이다.

Code Connect UI와 CLI는 어떻게 다른가

공식 문서는 Code Connect를 두 흐름으로 설명한다.²⁴

Code Connect UI

Figma 안에서 시각적으로 매핑하는 방식이다. 라이브러리 컴포넌트를 코드 경로와 연결하고, 필요하면 GitHub와 연결하거나 수동으로 경로를 입력할 수 있다. 설정 장벽이 비교적 낮고, 디자인 팀과 개발 팀이 같이 보기 쉽다.

다만 현재 기준으로 UI 방식은 Inspect 패널에 완전한 코드 스니펫을 보여주는 용도라기보다, 연결된 컴포넌트 경로와 이름, 그리고 MCP용 코드 생성 문맥을 강화하는 쪽에 더 가깝다.⁴

Code Connect CLI

저장소 안에서 로컬로 구성하는 방식이다. prop 매핑과 더 정확한 코드 예시, 실제 디자인 시스템 구조 반영에 유리하다. 개발자가 주도해서 더 정밀하게 맞추고 싶다면 이쪽이 강하다.

즉, 요약하면 이렇다.

빠르게 시작하고 시각적으로 관리하려면 UI
더 정밀한 prop 매핑과 실제 코드 예시가 필요하면 CLI

실무에서는 둘 중 하나만 고집할 필요는 없다. 디자인 시스템 안에서도 컴포넌트마다 접근 방식을 섞어 쓸 수 있다.

Code Connect를 쓰기 전에 꼭 알아야 할 제약

이 부분은 특히 정확하게 기억해야 한다. Code Connect는 모든 플랜에서 제공되지 않는다. 공식 기준으로는 Organization과 Enterprise 플랜에서, Dev seat 또는 Full seat 사용자에게 제공된다.²⁴ 또한 연결하려는 디자인 컴포넌트는 보통 팀 라이브러리에 게시된 상태여야 한다.

그래서 팀이 아직 Professional 플랜이라면 Dev Mode는 유용하게 써도 Code Connect는 바로 못 쓰는 상황이 충분히 가능하다. 핸드오프 전략을 짤 때 이 차이를 구분해야 한다.