Figma에서 코드로

Figma의 Dev Mode MCP 서버는 2025-06-04에 베타로 나왔다. 지금은 두 가지 방식으로 돌릴 수 있고, 어느 쪽을 고르느냐에 따라 차이가 크다.

2025-09-23에 추가된 원격 서버를 먼저 쓰는 게 맞다. mcp.figma.com/mcp에 호스팅돼 있어서 Figma 데스크톱 앱도, 로컬 프로세스도 필요 없다. Claude Code를 이 엔드포인트에 연결하면 끝이다. 로컬 서버도 아직 있지만, Figma 데스크톱 앱을 통해 돌아가고 Dev 또는 Full 시트가 필요하다.

어느 쪽이든 서버는 다리 역할을 한다. Claude Code는 Figma를 직접 건드리지 않는다. MCP 서버에 요청하면 서버가 Figma와 통신한다. 그러니 다리부터 놓아야 한다. 다리가 서기 전에는 그 뒤의 어떤 단계도 돌아가지 않는다.

파이프라인은 성격이 다른 Figma 소스 두 개에서 출발한다. 디자인 시스템 파일과 화면 파일이다.

디자인 시스템 Figma 파일에는 토큰, 컴포넌트, variant, 사용 가이드라인이 정의돼 있다. Claude Code는 get_design_context를 호출해 이 파일을 읽고, 구조화된 .md 스펙 묶음을 만든다. 맨 위에 design-system.md가 있고, 그 아래에 foundations/(color, typography, spacing)와 components/가 있다. 토큰 값은 get_variable_defs에서 가져온다. 이 도구는 현재 선택 영역에 바인딩된 variable과 style을 돌려준다.

이 도구의 원래 이름은 get_code였다. 이 페이지에 날짜를 붙인 것도 이 이름 변경 때문이다. 도구가 계속 바뀌니, 세부 사항은 특정 시점을 기준으로 적어 둘 수밖에 없다.

화면 Figma 파일은 디자인 시스템으로 조립한 실제 제품 화면이다. 같은 도구로 여기서 patterns/와 templates/를 뽑는다. 화면이 DS 컴포넌트를 어떤 레이아웃과 플로우로 엮는지 정리한 기록이다.

화면 스펙은 DS를 참조만 하고 덮어쓰지 않는다. 항상 DS 정의가 우선한다.

코드를 생성할 때 Claude Code는 화면 Figma를 읽고 각 노드를 대응하는 DS 정의에 매핑한다. 결과물이 div 덩어리가 되지 않게 막아 주는 건 Code Connect다. Figma 노드를 라이브러리의 실제 컴포넌트에 묶어 두는 계약이라서, 생성된 코드가 컴포넌트를 새로 만들지 않고 기존 컴포넌트를 그대로 쓴다. 이 매핑은 CLI로 작성하고, 이제는 앱 안의 매핑 UI로도 할 수 있다. Figma variable은 DS 토큰에 매핑되므로 생성된 컴포넌트도 스펙과 같은 값을 쓴다.

처음 만든 4계층 구조(Base → Semantic → Component → Tailwind)에는 구조적인 문제가 세 가지 있었다. 인터랙션·상태 토큰을 담을 State 계층이 없었고, Component 토큰이 상태 관리까지 떠안고 있었고, Tailwind가 렌더링 계층이 아니라 디자인 계층처럼 너무 앞단에 들어와 있었다.

개정한 구조에는 중요한 계층 두 개를 더했다.

State 계층은 Semantic과 Component 사이에 둔다. State 토큰은 고정 값이 아니라 변환을 정의한다. Hover는 색 토큰에 darken(8%), surface 토큰에 elevate(+1), focus 토큰에 ring(2px)을 적용한다. 컴포넌트는 상태를 인라인으로 정의하지 않고 Semantic과 State 참조를 조합한다. 그래서 sidebar-hover, sidebar-active, sidebar-error 같은 이름이 끝없이 늘어나지 않는다. Component 토큰은 상태 variant가 아니라 변하지 않는 슬롯을 정의한다.

Platform 계층은 Component와 Tailwind 사이에 둔다. 테마 해석(라이트/다크 모드), 밀도 variant(compact/cozy), 동작 줄이기 설정을 처리한다. Platform 토큰은 맥락에 따라 다른 값으로 해석된다. --primary는 라이트 모드에서 #0F62FE, 다크 모드에서 #4589FF가 된다. DS 자체는 특정 기술에 묶이지 않는다. Tailwind에서 CSS-in-JS나 네이티브로 옮겨도 바꿀 건 플랫폼 다리뿐이다.

전체 구조 밑에는 토큰 의존성 그래프가 있다. primary-hover → primary → accent-600. 모든 토큰이 자기 상위 출처를 안다. 그래서 accent-600이 바뀌면 어디가 깨지는지 추적할 수 있고, 다크 모드를 자동으로 파생하고, QA에서 회귀를 잡을 수 있다.

전체 파이프라인: Figma → Base → Semantic → State → Component → Platform → Tailwind.

리뷰는 한꺼번에 병렬로 돌리지 않고 의존성 순서를 따른다. 먼저 Design Agent와 Copywriter Agent가 병렬로 돈다. 시각 충실도와 텍스트·톤은 서로 의존하지 않기 때문이다. 디자인 결과는 Dev Agent로 넘어가 코드 품질, 토큰 사용, 컴포넌트 구조를 검토받는다. 카피 리뷰는 그사이 병렬로 마무리되고, QA 전에 반영된다.

QA Agent는 마지막 관문으로 맨 끝에 돈다. 토큰 감사, Figma 원본과의 시각 diff, WCAG AA 접근성 검사를 한다. QA는 항상 리뷰가 모두 끝난 빌드만 본다. 중간 상태는 보지 않는다.

FAIL은 한데 묶지 않고 종류별로 나눈다. QA는 실패를 원인이 있는 곳으로 돌려보낸다. 디자인 문제는 Design Agent로, 코드·토큰 문제는 Dev Agent로 보내고, 접근성 문제는 실패한 WCAG 기준을 명시해서 돌려보낸다. 이렇게 하면 "빌드로 되돌림"만 남고 아무도 뭘 고쳐야 할지 모르는 상황을 막을 수 있다.

파이프라인은 실제로 돌아가지만 매끄럽지는 않다. 아예 못 나르는 것들이 있고, 그건 금방 드러난다.

응답 하나는 약 20kb로 제한된다. 큰 프레임을 선택하면 호출이 넘쳐 버린다. Figma 문서도 선택 영역이 크면 모델의 최대 출력을 넘길 수 있다고 경고한다. 그래서 좁게 선택하고, 생성하고, 다음으로 넘어간다.

이미지와 에셋은 넘어오지 않는다. 아트워크 자리에는 placeholder가 들어가고, 실제 파일은 직접 연결해야 한다. 커스텀 폰트도 지원하지 않는다. 시스템 폰트는 렌더되지만 내가 쓰는 서체는 안 된다.

호출 횟수에도 상한이 있다. Pro와 Org 시트는 하루 200회, Enterprise는 600회다. 작업 세션 하나에는 충분하지만 마음 놓고 쓸 정도는 아니다.

이 사이트를 만들면서 실제로 걸린 건 더 가까운 데 있었다. Claude Code는 MCP 도구 응답 하나를 기본 25,000토큰으로 제한한다. 내용이 많은 DS 스펙이 이 선을 넘으면서 호출이 에러를 냈다. 해결은 환경 변수 하나였다. MAX_MCP_OUTPUT_TOKENS를 올려 응답에 여유를 줬다. 벽에 부딪히고 나서가 아니라 미리 설정해 두는 게 좋다.

제약도 파이프라인의 일부다. 한 번 기록해 두면 다음 화면에서 같은 문제를 다시 발견할 일이 없다.