renderfig

Figma .fig 파일을 템플릿으로 사용하여, 텍스트/이미지/스타일을 프로그래밍적으로 수정한 뒤 특정 프레임을 PNG/JPG로 렌더링하는 CLI 도구.

파이프라인

.fig 파일 → parsefig (파싱) → 노드 트리 + 이미지 추출
  → 오버라이드 적용 (텍스트/이미지/스타일 수정)
  → HTML/CSS 생성
  → Playwright 스크린샷 → PNG/JPG 출력

설치

npm install -g renderfig
npx playwright install chromium

Playwright가 스크린샷 촬영에 Chromium을 사용하므로, 최초 1회 npx playwright install chromium이 필요합니다.

CLI 사용법

inspect - .fig 파일 구조 탐색

# 페이지(캔버스) 목록
renderfig inspect design.fig

# 특정 페이지의 프레임 목록
renderfig inspect design.fig "페이지 이름"

# 특정 프레임의 하위 구조 (depth 지정)
renderfig inspect design.fig "페이지/프레임" --depth 3

# 전체 트리
renderfig inspect design.fig --depth all

출력 예시:

프로필 카드 [CANVAS]
  Channy [FRAME] 480x720 (auto-layout: VERTICAL)
    연락처 [FRAME] 384x120 (auto-layout: HORIZONTAL)
      레이블 [FRAME] 118x120 (auto-layout: VERTICAL)
        전화번호 [TEXT] 70x24
        이메일 [TEXT] 52x24
      값 [FRAME] 173x120 (auto-layout: VERTICAL)
        010-2923-5278 [TEXT] 142x24
        [email protected] [TEXT] 173x24
    소개 [FRAME] 384x427 (auto-layout: VERTICAL)
      사진 [ROUNDED_RECTANGLE] 240x240 (image)
      기본 정보 [FRAME] 384x143 (auto-layout: VERTICAL)
        Channy (차니) [TEXT] 289x43
        Maker [TEXT] 55x29

Mixed text styles 감지: TEXT 노드 내에서 여러 스타일이 혼합된 경우 자동 표시:

배너 텍스트 [TEXT] 243x100 ("진짜 자산관리 시작\n위스키캣 가계부",
  mixed: "진짜 자산관리 시작\n"→Medium 33px, "위스키캣 가계부"→default)

render - 프레임을 이미지로 렌더링

# 기본 렌더링
renderfig render design.fig "페이지/프레임" -o output.png

텍스트 교체 --text

# 전체 교체
renderfig render design.fig "프로필 카드/Channy" \
  --text "Channy (차니)=새이름" \
  --text "Maker=디자이너" \
  -o output.png

# 부분 교체 (스타일 보존): "//"로 노드이름과 검색어를 구분
renderfig render design.fig "홈페이지/배너" \
  --text "타이틀//진짜 자산관리 시작=스마트한 돈 관리" \
  -o output.png

부분 교체 시 // 앞이 노드 target, 뒤가 검색할 텍스트, = 뒤가 대체 텍스트입니다. 검색된 부분만 교체되고 나머지 텍스트와 스타일(폰트 크기, 굵기 등)이 보존됩니다.

전체 교체 시에도 줄 수가 같으면 라인별 스타일이 자동 보존됩니다.

이미지 교체 --image

renderfig render design.fig "프로필 카드/Channy" \
  --image "사진=./new-photo.jpg" \
  -o output.png

스타일 수정 --style

renderfig render design.fig "프로필 카드/Channy" \
  --style "Channy (차니).fontSize=40" \
  --style "Channy (차니).color=#ff0000" \
  --style "Maker.x=100" \
  -o output.png

텍스트 런 단위 스타일 수정: --style "노드이름//검색텍스트.속성=값" 형식으로 특정 텍스트 부분의 스타일만 변경할 수 있습니다. --text의 // 문법과 동일합니다.

# "진짜 자산관리 시작"은 ExtraBold, "위스키캣 가계부"는 Light로 변경
renderfig render design.fig "홈페이지/배너" \
  --style "타이틀//진짜 자산관리 시작.fontWeight=ExtraBold" \
  --style "타이틀//위스키캣 가계부.fontWeight=Light" \
  -o output.png

지원하는 스타일 속성:

위치 & 크기 | 속성 | 설명 | 예시 | |------|------|------| | x | X 좌표 (px) | 100 | | y | Y 좌표 (px) | 200 | | width | 너비 (px) | 300 | | height | 높이 (px) | 400 |

색상 & 외관 | 속성 | 설명 | 예시 | |------|------|------| | color | 채우기 색상 (텍스트 색상 겸용) | #ff0000 | | backgroundColor | 배경 색상 | #f0f4ff | | opacity | 투명도 (0-1) | 0.5 | | visible | 표시 여부 | true / false |

Border | 속성 | 설명 | 예시 | |------|------|------| | cornerRadius | 모서리 반경 (전체) | 16 | | borderRadiusTopLeft | 좌상단 반경 | 8 | | borderRadiusTopRight | 우상단 반경 | 8 | | borderRadiusBottomLeft | 좌하단 반경 | 8 | | borderRadiusBottomRight | 우하단 반경 | 8 | | strokeColor | 테두리 색상 | #cccccc | | strokeWeight | 테두리 두께 (px) | 2 |

Typography (TEXT 노드) | 속성 | 설명 | 예시 | |------|------|------| | fontSize | 글꼴 크기 (px) | 24 | | fontFamily | 글꼴 패밀리 | Pretendard | | fontWeight | 글꼴 스타일 (Bold 등) | Bold | | textAlign | 수평 정렬 | CENTER / LEFT / RIGHT | | textAlignVertical | 수직 정렬 | TOP / CENTER / BOTTOM | | lineHeight | 줄 높이 (px) | 28 | | lineHeightPercent | 줄 높이 (%) | 150 | | letterSpacing | 자간 (px) | 1.5 | | textDecoration | 텍스트 장식 | UNDERLINE / STRIKETHROUGH |

Auto Layout (FRAME 노드) | 속성 | 설명 | 예시 | |------|------|------| | gap | 자식 간 간격 (px) | 12 | | padding | 패딩 전체 (px) | 16 | | paddingHorizontal | 좌우 패딩 (px) | 24 | | paddingVertical | 상하 패딩 (px) | 16 | | paddingTop | 상단 패딩 (px) | 8 | | paddingRight | 우측 패딩 (px) | 8 | | paddingBottom | 하단 패딩 (px) | 8 | | paddingLeft | 좌측 패딩 (px) | 8 | | alignItems | 교차축 정렬 | MIN / CENTER / MAX | | justifyContent | 주축 정렬 | MIN / CENTER / MAX / SPACE_BETWEEN |

폰트 지정 --font

renderfig render design.fig "프로필 카드/Channy" \
  --font "Pretendard=./fonts/Pretendard-Regular.woff2" \
  --font "Noto Sans KR=./fonts/NotoSansKR.woff2" \
  -o output.png

출력 옵션

| 옵션 | 설명 | 기본값 | |------|------|--------| | -o, --output <path> | 출력 파일 경로 (필수) | - | | --format png\|jpeg | 출력 포맷 | 확장자에서 자동 감지, png | | --quality <n> | JPEG 품질 (0-100) | - | | --scale <n> | 디바이스 스케일 팩터 (1, 2, 3) | 1 |

Programmatic API

import { renderFrame } from 'renderfig';

const buffer = await renderFrame({
  figFile: './design.fig',
  frameName: '프로필 카드/Channy',
  output: './output.png',
  scale: 2,
  overrides: [
    { type: 'text', target: 'Channy (차니)', value: '새이름' },
    { type: 'text', target: '타이틀', search: '원래텍스트', value: '새텍스트' },
    { type: 'image', target: '사진', src: './photo.jpg' },
    { type: 'style', target: 'Maker', props: { fontSize: 24, color: '#0066ff' } },
    // 텍스트 런 단위 스타일: search로 특정 부분만 변경
    { type: 'style', target: '타이틀', search: '위스키캣 가계부', props: { fontWeight: 'Light' } },
  ],
  fonts: [
    { family: 'Pretendard', src: './fonts/Pretendard-Regular.woff2' },
  ],
});

renderFrame(options): Promise<Buffer>

| 속성 | 타입 | 설명 | |------|------|------| | figFile | string | .fig 파일 경로 | | frameName | string | 렌더링할 프레임 경로 ("페이지/프레임") | | output | string | 출력 파일 경로 | | format | 'png' \| 'jpeg' | 출력 포맷 (기본: 확장자에서 감지) | | quality | number | JPEG 품질 0-100 | | scale | number | deviceScaleFactor (기본: 1) | | overrides | Override[] | 텍스트/이미지/스타일 오버라이드 | | fonts | FontMapping[] | 로컬 폰트 매핑 |

Override 타입

type Override =
  | { type: 'text'; target: string; value: string; search?: string }
  | { type: 'image'; target: string; src: string }
  | { type: 'style'; target: string; props: Record<string, string | number>; search?: string }

target은 노드 이름 (예: "Channy (차니)") 또는 / 구분 경로 (예: "기본 정보/Channy (차니)")로 지정합니다.

동일한 이름의 노드가 여러 개인 경우 이름[n] 인덱스 문법 (0-based)으로 구분합니다 (예: 이메일[0], 이메일[1]).

텍스트 오버라이드에서 search 필드를 지정하면 해당 부분만 교체하고 나머지 텍스트와 스타일을 보존합니다.

스타일 오버라이드에서 search 필드를 지정하면 해당 텍스트 런의 스타일만 개별 변경합니다 (fontWeight, fontFamily, fontSize, color 등).

폰트 처리

렌더링 시 프레임에서 사용되는 모든 폰트 패밀리를 자동으로 수집하여 다음 순서로 처리합니다:

1. --font 로컬 폰트 - 지정된 폰트 파일을 @font-face로 HTML에 인라인 임베드 (.woff2, .woff, .ttf, .otf 지원)
2. Google Fonts 자동 로딩 - --font로 지정되지 않은 폰트는 Google Fonts API에서 자동 로딩 시도
3. 시스템 폰트 폴백 - 위 두 방법 모두 해당하지 않으면 시스템에 설치된 폰트 또는 sans-serif 폴백

Google Fonts에 없는 폰트(예: Pretendard, SUIT 등)는 --font로 직접 지정해야 정확하게 렌더링됩니다.

지원하는 Figma 노드

| Figma 노드 | 렌더링 방식 | |------------|------------| | FRAME (auto layout) | display:flex + hug/fixed sizing + gap + padding | | FRAME (absolute) | position:relative / 자식 position:absolute | | TEXT | mixed styles (characterStyleIDs) + font + color + text-align | | ROUNDED_RECTANGLE | background + border-radius | | ELLIPSE | border-radius:50% | | INSTANCE / COMPONENT | 재귀적으로 자식 렌더링 | | IMAGE fill | background-image: url(data:...) 인라인 | | VECTOR / BOOLEAN_OPERATION | SVG <path> 렌더링 (fillGeometry blob 디코딩) | | LINE | border-bottom 렌더링 | | 그라디언트 | linear-gradient / radial-gradient 지원 |

라이선스

MIT