Figma API와 Gemini Vision을 연동해 디자인 스펙을 마크다운 개발 문서로 자동 전환하기

디자이너와 개발자 사이의 제품 핸드오프(Handoff) 과정은 서비스 구축 과정에서 가장 많은 병목이 발생하는 구간 중 하나입니다. 디자이너가 피그마(Figma)에 시안을 완성하더라도, 개발자는 레이아웃 구조, 인터랙션 예외 처리, 반응형 대응 기준, 접근성(A11y) 가이드라인을 직접 확인하고 이를 문서화하거나 이해하는 데 여전히 많은 시간을 소비합니다.

피그마의 ’Dev Mode’나 기본 스펙 추출 기능이 점차 진화하고 있지만, 컴포넌트의 비즈니스 로직이나 상황별 상태 변화(Active, Hover, Disabled, Error 등)를 체계적인 마크다운(Markdown) 개발 문서로 자동 재구성해 주지는 못합니다.

이 문제를 해결하기 위해 Figma REST API로 디자인 데이터와 이미지 렌더링을 추출하고, 이를 시각적·문맥적 이해 능력이 뛰어난 **Gemini Vision(Gemini 1.5 Pro / Flash)**에 전달하여 기술 스펙 문서를 자동 생성하는 파이프라인을 구축할 수 있습니다.

기존 핸드오프 방식과 Gemini Vision 기반 자동화 비교

디자인 핸드오프 자동화를 고민할 때 가장 먼저 비교해야 할 것은 ’기존 도구들이 해결해주지 못하는 지점이 무엇인가’입니다.

구분 피그마 수동 작성 핸드오프 Figma Dev Mode 단독 사용 Figma API + Gemini Vision 자동화 파이프라인
문서화 주체 디자이너 또는 FE 개발자 개발자가 피그마 내에서 직접 확인 AI 파이프라인이 마크다운 파일 자동 생성
상태(State) 정의 텍스트 메모로 개별 작성 필요 레이어 탐색을 통해 개별 확인 필요 프레임 내 상태 변화를 감지하여 마크다운 표로 정형화
개발 문서 통합 Notion, Jira, GitHub Wiki에 복사/붙여넣기 피그마 링크 공유 위주 (외부 문서 연동 번거로움) GitHub PR, Notion, Confluence API로 즉시 동기화
비즈니스 예외 로직 디자이너의 구두 전달 또는 주석에 의존 코드 스니펫 위주 표출로 한계 존재 이미지 시각 정보와 노드 트리를 종합해 예외 상황 추론 및 작성
소요 시간 화면당 30분 ~ 1시간 이상 소요 화면당 10분 ~ 20분 탐색 파이프라인 호출 후 수십 초 내 완료 (이미지·노드 추출, 전처리, Vision 생성까지 포함)

단순히 피그마 노드 JSON 데이터만 LLM에 넘길 경우, 복잡하게 중첩된 Auto-layout과 임의로命名된 레이어 이름 때문에 프롬프트 토큰 소모가 극심해지고 환각(Hallucination)이 발생하기 쉽습니다. 반대로 이미지만 넘기면 정확한 패딩(Padding), 색상 헥사 코드(Hex code), 폰트 스타일 값을 놓치게 됩니다.

핵심은 **Figma API의 메타데이터(노드 구조 및 디자인 토큰)**와 Gemini Vision의 시각적 렌더링 분석을 결합하는 ‘하이브리드 콘텍스트’ 공급 방식입니다.

파이프라인 아키텍처 및 데이터 흐름

이 자동화 시스템은 크게 4단계 프로세스로 구동됩니다.

[Figma Webhook / Plugin] 
       │ (1) 특정 프레임 ID 전달
       ▼
[Figma REST API] ───► Image API (/v1/images) ────► 이미지 URL (PNG)
       │         └──► Node API (/v1/files/nodes) ──► 노드 트리 JSON (필터링됨)
       ▼
[Context Preprocessing] ──► 토큰 절약을 위한 노드 정형화 & 시각 자료 패킹
       ▼
[Gemini Vision API] ────► System Prompt 적용 및 마크다운 생성
       ▼
[Documentation Hub] ───► GitHub repository, PR, Notion 페이지 자동 업로드

1. Figma API 데이터 추출

Figma API에서 두 가지 데이터를 수집합니다:

2. 콘텍스트 전처리 (Context Pruning)

Figma의 Node API 응답값은 필요 이상으로 거대합니다. LLM의 콘텍스트 윈도우를 효율적으로 사용하고 비용을 절감하기 위해 불필요한 메타데이터(vectorPaths, fillGeometry 등)를 제거하고 다음 요소만 추출해 정형화합니다:

3. Gemini Vision을 통한 텍스트/시각 교차 분석

추출된 이미지 버퍼와 정제된 JSON을 Gemini 1.5 Pro 혹은 Flash에 동시에 전달합니다. Gemini 1.5 라인업은 멀티모달 입력 처리 성능과 인스트럭션 팔로잉 능력이 우수하여, 디자인 시안 속 UI 컴포넌트의 상하 관계와 시각적 상태(Default, Hover, Disabled 등)를 정교하게 식별합니다.

Gemini Vision 전용 시스템 프롬프트 및 스키마 설계

Gemini API 호출 시 일관된 마크다운 구조를 얻기 위해 구체적인 인스트럭션과 Output Format을 지정해야 합니다. 다음은 실제 파이프라인에서 활용할 수 있는 프롬프트 구조 예시입니다.

You are a Senior Frontend Engineer and UI/UX System Architect.
Analyze the provided Figma design frame image and node JSON hierarchy to generate a developer-ready Markdown technical specification.

### Guidelines:
1. Do not use generic summary bullet points at the end.
2. Structure the document clearly using H2 (##) and H3 (###) headers.
3. Extract exact style values (Colors, Typography, Spacing) from the Node JSON when available.
4. Infer interactive behaviors, responsiveness, and state handling based on visual cues and Auto-layout settings.

### Output Format Schema:
## 1. Component Overview
- Component Name / ID:
- Primary Purpose:
- Visual Hierarchy & Target Screen:

## 2. Layout & Responsive Specifications
- Flex/Grid Architecture:
- Spacing & Padding Rules:
- Breakpoint & Responsive Rules (Desktop / Mobile adaptations):

## 3. UI States & Edge Cases
| State | Visual Trigger | Expected Behavior / Props |
| :--- | :--- | :--- |
| Default | Normal view | Render standard props |
| Disabled | Opacity 50%, Pointer-events: none | Block user interaction |
| Error | Red border (#FF0000), Toast display | Show validation message |

## 4. Accessibility (A11y) & Semantic Markup
- Recommended HTML Element: (e.g., `<button>`, `<section>`, `<article>`)
- ARIA Attributes: (e.g., `aria-expanded`, `aria-label`)
- Color Contrast Assessment: (Pass/Fail estimation based on WCAG AA)

이 프롬프트를 Gemini 1.5 Pro에 전달하면, 시각 자료 기반의 추론과 JSON 데이터의 명확한 수치값이 혼합된 정교한 마크다운 문서를 곧바로 얻을 수 있습니다.

실무 적용 시 발생할 수 있는 주요 과제 및 해결 전략

이 기술을 프로덕션 환경에 적용할 때 반드시 고려해야 할 실무적 변수들과 대처법입니다.

1. 피그마 노드 명명 규칙의 불확실성

디자이너가 레이어 이름을 Frame 1234, Group 98과 같이 방치해 두는 경우 AI가 컴포넌트의 역할 파악에 어려움을 겪을 수 있습니다.

2. API 호출 비용 및 속도 최적화

모든 피그마 프레임 변경 건에 대해 Gemini 1.5 Pro를 호출하면 비용과 소요 시간이 늘어날 수 있습니다.

화면 1개당 평균 생성 시간과 월간 API 비용은 디자인 복잡도, 선택한 모델(Flash vs Pro), 프레임 전환 빈도에 따라 크게 달라지므로, 실제 도입 전에 샘플 프레임 몇 개로 파이프라인을 시험 실행해 직접 측정해 보는 것이 좋습니다.

자주 묻는 질문 (Q&A)

Q. 이 파이프라인이 피그마의 Dev Mode를 완전히 대체할 수 있나요? A. 대체보다는 상호 보완적인 관계에 가깝습니다. Dev Mode는 개발자가 코드를 작성하며 피그마 내부에서 픽셀 단위 측정이나 CSS 스니펫을 즉시 확인하기에 유용합니다. 반면, 본 자동화 시스템은 PR 검토, 아키텍처 설계, Notion/Jira 등 중앙집중식 기술 문서 보관소에 **‘텍스트 기반 개발 표준 및 사양서’**를 자동으로 최신화해 두는 용도로 강력한 효과를 발휘합니다.

Q. 디자인 시스템(Design System) 토큰과의 연동도 가능한가요? A. 가능합니다. Node JSON을 수집할 때 피그마 파일의 styles 및 variables 객체를 함께 파싱하여 Gemini에 프롬프트로 전달하면, 단순 Hex 값이 아닌 “YourSystem/Colors/Primary-500”과 같이 기업 내부 디자인 토큰 이름으로 마크다운 문서를 매핑하여 출력하도록 지정할 수 있습니다.

디자이너와 개발자의 협업 방식을 바꾸는 자동화의 지향점

피그마 API와 Gemini Vision의 연동을 통한 문서 자동화는 단순한 노동 절감 이상의 의미를 갖습니다. 디자이너에게는 “개발 문서 작성을 위해 주석 플러그인을 붙이고 텍스트 박스를 일일이 기입해야 하는 커뮤니케이션 비용”을 줄여주고, 개발자에게는 “해당 UI가 오류 상태일 때 어떻게 동작해야 하는지” 피그마 화면 구석구석을 찾아 헤매는 시간을 없애줍니다.

자동화된 마크다운 개발 문서를 GitHub 저장소의 시안 경로 옆에 .md 파일로 동기화하거나 PR 시 자동 댓글로 등록되도록 GitHub Actions 파이프라인을 구축해 보시기 바랍니다. 시각적 맥락과 텍스트 스펙이 유기적으로 결합된 단일 진실 공통체(SSOT)를 구축함으로써, 팀 전체가 정교하고 민첩한 개발 프로세스를 경험할 수 있게 될 것입니다.

연관 글