Figma 화면을 개발 코드로 옮길 때 시간이 많이 드는 부분은 CSS 한 줄을 작성하는 일이 아닙니다. 프레임 이름을 확인하고, 텍스트와 이미지를 찾고, 같은 구조가 반복되는지 분류하는 작업이 더 오래 걸립니다.

화면 수가 적으면 직접 확인하는 편이 빠릅니다. 수십 개의 프레임에서 같은 정보를 반복해서 꺼내야 한다면 Figma REST API와 파이썬을 이용해 작업 목록을 만들 수 있습니다.

이 글에서는 Figma 파일의 노드 구조를 읽어 다음 정보를 CSV로 저장합니다.

  • 화면과 프레임 이름
  • 텍스트 내용과 글자 크기
  • 이미지로 내보낼 수 있는 노드
  • 컴포넌트와 인스턴스의 위치

완성된 HTML이나 React 코드를 자동으로 만드는 예제는 아닙니다. 디자인 파일을 개발 가능한 작업 목록으로 바꾸는 데 초점을 맞춥니다.

플러그인과 REST API 중 무엇을 쓸까

Figma 자동화에는 크게 두 가지 방법이 있습니다.

Figma 플러그인은 편집기 안에서 실행됩니다. 선택한 노드를 바로 읽거나 수정하고, exportAsync로 이미지를 내보내는 작업에 적합합니다. 반면 REST API는 Figma 편집기를 열지 않고 외부 프로그램에서 파일과 노드 정보를 조회할 수 있습니다.

이번 예제처럼 파이썬으로 파일 구조를 분석하고 CSV를 만들 때는 REST API가 단순합니다. Figma 공식 문서에서 REST API가 파일의 객체와 레이어, 속성을 조회할 수 있다고 설명하고 있으며, 파일 엔드포인트를 통해 전체 파일이나 특정 노드의 JSON 표현을 가져올 수 있습니다.

준비할 것

  • Python 3
  • 읽을 권한이 있는 Figma 파일
  • Figma 개인 액세스 토큰 또는 OAuth 토큰
  • requests 패키지

개인 작업이라면 Figma 개인 액세스 토큰 안내에 따라 토큰을 만들 수 있습니다. 여러 사용자가 쓰는 서비스라면 개인 토큰을 공유하지 말고 OAuth와 필요한 권한 범위를 설계해야 합니다.

토큰은 코드에 직접 적지 않습니다. 셸 환경변수로 전달합니다.

export FIGMA_TOKEN="발급받은_토큰"
export FIGMA_FILE_KEY="파일_키"
python3 extract_figma_nodes.py

파일 키는 Figma 파일 URL에서 확인할 수 있습니다.

https://www.figma.com/design/{FILE_KEY}/파일이름

전체 파일 구조 가져오기

다음 코드를 extract_figma_nodes.py로 저장합니다.

import csv
import os
from collections.abc import Iterator

import requests

TOKEN = os.environ["FIGMA_TOKEN"]
FILE_KEY = os.environ["FIGMA_FILE_KEY"]
API_URL = f"https://api.figma.com/v1/files/{FILE_KEY}"


def fetch_file() -> dict:
    response = requests.get(
        API_URL,
        headers={"X-Figma-Token": TOKEN},
        timeout=30,
    )
    response.raise_for_status()
    return response.json()


def walk(node: dict, path: tuple[str, ...] = ()) -> Iterator[dict]:
    current_path = path + (node.get("name", ""),)
    yield {
        "id": node.get("id", ""),
        "name": node.get("name", ""),
        "type": node.get("type", ""),
        "path": " / ".join(part for part in current_path if part),
        "text": node.get("characters", ""),
        "font_size": node.get("style", {}).get("fontSize", ""),
        "component_id": node.get("componentId", ""),
    }

    for child in node.get("children", []):
        yield from walk(child, current_path)


def write_csv(rows: Iterator[dict], output_path: str) -> None:
    columns = [
        "id",
        "name",
        "type",
        "path",
        "text",
        "font_size",
        "component_id",
    ]
    with open(output_path, "w", encoding="utf-8-sig", newline="") as file:
        writer = csv.DictWriter(file, fieldnames=columns)
        writer.writeheader()
        writer.writerows(rows)


def main() -> None:
    data = fetch_file()
    write_csv(walk(data["document"]), "figma_nodes.csv")
    print("figma_nodes.csv 저장 완료")


if __name__ == "__main__":
    main()

실행에 필요한 패키지를 설치합니다.

python3 -m pip install requests
python3 extract_figma_nodes.py

실행이 끝나면 현재 폴더에 figma_nodes.csv가 생깁니다. 한 행은 Figma 노드 하나입니다. path 열을 보면 페이지, 프레임, 그룹 안에서 해당 노드가 어디에 있는지 확인할 수 있습니다.

필요한 노드만 추리기

전체 노드가 필요하지 않다면 타입으로 거를 수 있습니다. 예를 들어 텍스트만 저장하려면 main 함수를 다음처럼 바꿉니다.

def main() -> None:
    data = fetch_file()
    rows = (
        row
        for row in walk(data["document"])
        if row["type"] == "TEXT" and row["text"].strip()
    )
    write_csv(rows, "figma_texts.csv")

컴포넌트 인스턴스만 찾으려면 INSTANCE를 사용합니다.

if row["type"] == "INSTANCE"

이 결과를 이용하면 화면별 문구 검수표, 번역 대상 목록, 컴포넌트 사용 현황을 만들 수 있습니다.

이미지는 별도 엔드포인트로 내보낸다

파일 조회 응답에는 노드 구조가 들어 있지만 PNG나 SVG 파일 자체가 모두 포함되지는 않습니다. 이미지가 필요한 노드 ID를 모은 뒤 Figma 이미지 엔드포인트에 요청해야 합니다.

def get_image_urls(node_ids: list[str], image_format: str = "png") -> dict:
    response = requests.get(
        f"https://api.figma.com/v1/images/{FILE_KEY}",
        headers={"X-Figma-Token": TOKEN},
        params={
            "ids": ",".join(node_ids),
            "format": image_format,
            "scale": 2,
        },
        timeout=30,
    )
    response.raise_for_status()
    return response.json()["images"]

반환값은 노드 ID와 임시 이미지 URL의 조합입니다. 실제 자동화에서는 URL을 받은 뒤 파일명 규칙을 적용해 다운로드하고, 실패한 노드를 별도 로그로 남기는 편이 좋습니다.

바로 HTML이나 React로 만들지 않은 이유

Figma 노드에는 위치, 크기, 색상과 텍스트 정보가 있지만 제품 코드의 의도까지 들어 있지는 않습니다.

예를 들어 Figma에서 비슷해 보이는 카드 세 개가 실제 개발에서는 하나의 반복 컴포넌트일 수 있습니다. 반대로 같은 컴포넌트처럼 보이지만 권한과 데이터 로딩 방식이 달라 별도 구현이 필요할 수도 있습니다. 반응형 규칙, 접근성, 상태 변화와 API 연결도 디자인 좌표만으로 결정할 수 없습니다.

그래서 자동화의 첫 단계는 코드를 생성하는 것보다 다음 항목을 정리하는 편이 안전합니다.

  1. 화면과 컴포넌트 목록
  2. 텍스트와 이미지 자산
  3. 반복되는 패턴
  4. 개발자가 판단해야 할 예외

이 목록이 안정되면 프로젝트 규칙에 맞는 React 컴포넌트나 스타일 토큰을 생성하는 두 번째 자동화를 붙일 수 있습니다.

실제 작업에서 자주 막히는 부분

403 또는 404 응답

토큰에 파일 접근 권한이 없거나 파일 키가 잘못됐을 가능성이 큽니다. 브라우저에서 같은 계정으로 파일을 열 수 있는지 먼저 확인합니다. 조직 파일이라면 관리자가 API 접근을 제한했는지도 확인해야 합니다.

노드가 너무 많아 처리하기 어려움

처음부터 모든 속성을 저장하지 말고 필요한 타입과 필드만 남깁니다. 특정 프레임만 필요하다면 전체 파일을 매번 분석하지 않고 노드 엔드포인트로 범위를 줄입니다.

파일 이름 충돌

Figma에서는 서로 다른 프레임 안에 같은 레이어 이름을 쓸 수 있습니다. 이미지 파일명을 레이어 이름만으로 만들면 덮어쓰기가 생깁니다. 노드 ID나 전체 경로를 함께 사용해야 합니다.

토큰 노출

개인 액세스 토큰을 저장소에 커밋하지 않습니다. .env를 사용한다면 .gitignore에 포함하고, CI에서는 비밀변수로 등록합니다. 유출됐다고 판단되면 즉시 토큰을 폐기하고 새로 발급합니다.

자동화가 실제로 줄여주는 일

이 스크립트가 디자인을 완성된 제품 코드로 바꾸지는 않습니다. 대신 사람이 반복해서 하던 다음 작업을 줄여줍니다.

  • 화면과 레이어 목록 만들기
  • 텍스트 검수표 만들기
  • 내보낼 이미지 후보 찾기
  • 컴포넌트 인스턴스 사용 현황 확인하기
  • 변경 전후 파일 구조 비교하기

프로젝트마다 이름 규칙과 컴포넌트 기준이 다르므로, 먼저 CSV 결과를 검토한 뒤 생성 범위를 넓히는 것이 좋습니다. 자동화는 판단을 없애기보다 판단할 대상을 줄일 때 효과가 큽니다.

디자인 파일 정리부터 프런트엔드 구현, 반복 작업 자동화까지 함께 검토해야 한다면 프로젝트 문의에 현재 파일 구조와 원하는 산출물을 알려주세요. 자동화할 부분과 사람이 확인할 부분을 나눠 답하겠습니다.

  • figma
  • python
  • script
  • markup
  • 마크업추출