figma-use

⚠️ Figma 126+ 버전은 원격 디버깅 (remote debugging)을 차단합니다. figma-use는 여전히 figma-use daemon start --pipe를 통해 작동합니다. 또는 **OpenPencil**을 사용하여 Figma를 완전히 건너뛸 수도 있습니다 — 이는 .fig 파일을 읽고 쓸 수 있으며, AI와 P2P 협업 기능이 내장된 오픈 소스 디자인 에디터입니다.

Figma를 위한 CLI (Command Line Interface)입니다. 터미널에서 명령어나 JSX를 통해 Figma를 제어하세요.

# 생성 및 스타일링
figma-use create frame --width 400 --height 300 --fill "#FFF" --layout VERTICAL --gap 16
figma-use create icon mdi:home --size 32 --color "#3B82F6"
...

이유 (Why)

Figma의 공식 MCP (Model Context Protocol) 플러그인은 파일을 읽을 수는 있지만 수정할 수는 없습니다. 이 도구는 수정이 가능합니다.

LLM (Large Language Models)은 CLI를 알고 있습니다. LLM은 React를 알고 있습니다. 이 도구는 이 두 가지를 결합합니다.

CLI 명령은 간결합니다 — 읽기 쉽고, 생성하기 쉬우며, 체이닝 (chaining)하기 쉽습니다. 작업에 수십 개의 연산이 포함될 때, 절약되는 모든 토큰 (token)이 중요합니다.

JSX는 LLM이 이미 UI를 생각하는 방식입니다. 그들은 수백만 개의 React 컴포넌트를 보았습니다. Figma 레이아웃을 <Frame><Text>와 같이 묘사하는 것은 그들에게 자연스럽습니다 — 특별한 훈련도, 장황한 스키마 (schema)도 필요하지 않습니다.

데모 (Demo)

설치 (Installation)

npm install -g figma-use

또는 설치 없이 직접 실행하세요:

npx figma-use status

원격 디버깅 (remote debugging)이 활성화된 상태로 Figma를 시작하세요:

# macOS
open -a Figma --args --remote-debugging-port=9222

...

연결 확인:

figma-use status

끝입니다. 설치할 플러그인이 없습니다.

두 가지 모드 (Two Modes)

명령형 (Imperative) — 한 번에 하나의 명령:

figma-use create frame --width 400 --height 300 --fill "#FFF" --radius 12 --layout VERTICAL --gap 16

또는 선언적 (Declaratively) 방식 — JSX로 구조를 기술하고 렌더링합니다:

echo '<Frame style={{p: 24, gap: 16, flex: "col", bg: "#FFF", rounded: 12}}>
  <Text style={{size: 24, weight: "bold", color: "#000"}}>Card Title</Text>
  <Text style={{size: 14, color: "#666"}}>Description</Text>
...

표준 입력 (stdin) 모드는 순수 JSX만 허용하며, 변수나 로직은 사용할 수 없습니다. 컴포넌트 (Components), 변형 (Variants), 조건 (Conditions)을 사용하려면 .figma.tsx 파일을 사용하세요.

요소 (Elements): Frame, Rectangle, Ellipse, Text, Line, Star, Polygon, Vector, Group, Icon, Image

예시 (Examples)

아이콘 (Icons)

Iconify에서 이름으로 원하는 아이콘을 삽입하세요. 다운로드, 임포트(Import), 정리 작업이 필요 없습니다.

figma-use create icon mdi:home
figma-use create icon lucide:star --size 48 --color "#F59E0B"

JSX에서 사용 시:

<Frame style={{ flex: 'row', gap: 8 }}>
  <Icon icon="mdi:home" size={24} color="#3B82F6" />
  <Icon icon="lucide:star" size={32} color="#F59E0B" />
...

15만 개 이상의 아이콘 찾아보기: icon-sets.iconify.design

이미지 (Images)

URL에서 이미지를 불러옵니다:

<Image src="https://example.com/photo.jpg" w={200} h={150} />

JSX로 내보내기 (Export to JSX)

모든 Figma 노드 (Node)를 다시 JSX로 변환합니다:

figma-use export jsx 123:456 --pretty

출력 결과:

import { Frame, Icon, Text } from 'figma-use/render'
export default function SaveButton() {
  return (
...

벡터 도형을 Iconify 아이콘과 자동으로 매칭합니다:

npm install whaticon  # 선택적 의존성 (Optional dependency)
figma-use export jsx 123:456 --match-icons --prefer-icons lucide

두 노드를 JSX 차이점 (Diff)으로 비교합니다:

figma-use diff jsx 123:456 789:012

Storybook으로 내보내기 (실험적 기능, Experimental)

컴포넌트를 Storybook 스토리 (Stories)로 내보냅니다:

figma-use export storybook --out ./stories
figma-use export storybook --out ./stories --match-icons --prefer-icons lucide

컴포넌트 속성(properties)으로부터 타입이 지정된 props를 가진 .stories.tsx를 생성합니다.

컴포넌트 (Components)

.figma.tsx 파일에서 컴포넌트를 정의할 수 있습니다. 첫 번째 호출은 마스터(master)를 생성하고, 나머지는 인스턴스(instances)를 생성합니다:

import { defineComponent, Frame, Text } from 'figma-use/render'

const Card = defineComponent(
...

베리언트 (Variants)

모든 조합을 포함하는 컴포넌트 세트(ComponentSet):

import { defineComponentSet, Frame, Text } from 'figma-use/render'

const Button = defineComponentSet(
...

이는 단순히 4개의 별개 버튼을 만드는 것이 아니라, Figma 내에 4개의 베리언트(variants)를 가진 실제 컴포넌트 세트(ComponentSet)를 생성합니다.

그리드 레이아웃 (Grid Layout)

캘린더, 대시보드, 갤러리와 같은 2D 레이아웃을 위한 CSS 그리드 (CSS Grid):

<Frame
  style={{
    display: 'grid',
...

px, fr, 그리고 auto/hug를 지원합니다. 간격(gaps)은 colGap과 rowGap으로 구분합니다.

CLI에서:

figma-use set layout <id> --mode GRID --cols "100px 1fr 100px" --rows "auto" --gap 16

토큰으로서의 변수 (Variables as Tokens)

이름을 통해 색상을 Figma 변수(variables)에 바인딩합니다. 16진수(hex) 값은 폴백(fallback)으로 사용됩니다:

import { defineVars, Frame, Text } from 'figma-use/render'

const colors = defineVars({
...

CLI에서는 모든 색상 옵션에 var:Colors/Primary 또는 $Colors/Primary를 사용할 수 있습니다.

디프 (Diffs)

두 프레임을 비교하여 패치(patch)를 가져옵니다:

figma-use diff create --from 123:456 --to 789:012

--- /Card/Header #123:457
+++ /Card/Header #789:013
@@ -1,5 +1,5 @@
...

패치를 원본 프레임에 적용합니다. 적용 시 현재 상태가 예상 상태와 일치하는지 검증하며, 일치하지 않으면 실패합니다.

시각적 디프(Visual diff)는 변경된 픽셀을 빨간색으로 강조합니다:

figma-use diff visual --from 49:275096 --to 49:280802 --output diff.png

검사 (Inspection)

읽기 쉬운 형태의 페이지 트리:

$ figma-use node tree
[0] frame "Card" (1:23)
    400×300 at (0, 0) | fill: #FFFFFF | layout: col gap=16
...

단 하나의 명령어로 모든 노드(node) 또는 스크린샷을 내보낼(Export) 수 있습니다.

정렬 (Arrange)

캔버스 레이아웃을 정리합니다 — 특히 에이전트가 동일한 위치에 여러 프레임(frame)을 생성한 후에 유용합니다:

figma-use arrange                              # 모든 최상위 노드를 그리드(Grid)로 정렬
figma-use arrange --mode row --gap 60          # 가로 행(Horizontal row)으로 정렬
figma-use arrange --mode squarify --gap 60     # 다양한 크기를 위한 스마트 패킹(Smart packing)

squarify 및 binary 모드에는 d3-hierarchy treemap을 사용하여 크기를 고려한 직사각형 패킹(rectangle packing)을 수행합니다.

벡터 (Vectors)

SVG를 가져오거나 경로(path)를 직접 다룹니다 — 읽기, 수정, 변환(translate), 크기 조절(scale), 뒤집기(flip)가 가능합니다:

figma-use path get <id>
figma-use path set <id> "M 0 0 L 100 100 Z"
figma-use path scale <id> --factor 1.5
...

쿼리 (Query)

XPath 선택자(selector)를 사용하여 노드를 찾습니다:

figma-use query "//FRAME"                              # 모든 프레임(frame)
figma-use query "//FRAME[@width < 300]"                # 너비가 300px 미만인 프레임
figma-use query "//COMPONENT[starts-with(@name, 'Button')]"  # 이름이 'Button'으로 시작하는 컴포넌트(component)
...

술어(predicates), 함수(functions), 산술(arithmetic), 축(axes)을 포함한 전체 XPath 3.1을 지원합니다.

분석 (Analyze)

디자인 시스템(design systems)을 이해하기 위한 탐색 도구입니다:

# 반복되는 패턴(잠재적 컴포넌트) 찾기
figma-use analyze clusters

...

출력 예시:

[0] 48× frame "Header" pattern (100% match)
    1280×56 | Frame > [Frame×2, Text]
    examples: 53171:21628, 53171:21704
...

린트 (Lint, 실험적 기능)

디자인의 일관성(consistency), 접근성(accessibility) 및 권장 사항(best practices)을 확인합니다:

figma-use lint                          # 권장 규칙(Recommended rules)
figma-use lint --page "Components"      # 특정 페이지에 대해 린트 수행
figma-use lint --preset strict          # 프로덕션 환경을 위한 더 엄격한 설정
...

출력:

✖ Header/Title (1:234)
    ✖  대비 비율(Contrast ratio) 2.1:1이 AA 임계값(4.5:1) 미만입니다    color-contrast
    ⚠  터치 대상(Touch target) 32x32가 최소 크기인 44x44 미만입니다    touch-target-size
...

6개 카테고리에 걸친 17가지 규칙 (rules):

CI/CD를 위한 JSON 출력:

figma-use lint --json > report.json

댓글 기반 워크플로우 (Comment-Driven Workflow, 실험적 기능)

AI 에이전트가 Figma 댓글을 기다렸다가 응답할 수 있습니다:

figma-use comment watch --json   # 새로운 댓글이 있을 때까지 대기 (Blocks)
figma-use comment resolve <id>   # 완료로 표시

댓글 텍스트, 작성자, 그리고 댓글 핀이 위치한 정확한 요소인 target_node를 반환합니다. 에이전트는 요청을 처리하고 댓글을 해결(resolve)한 다음, 다음 댓글을 위해 다시 watch를 실행합니다.

전체 명령어 참조 (Full Command Reference)

100개 이상의 전체 명령어 목록은 REFERENCE.md를 참조하세요.

MCP 서버

Model Context Protocol (MCP)를 지원하는 AI 에이전트를 위한 기능입니다:

figma-use mcp serve

90개 이상의 도구(tools)를 노출합니다. 설정 방법은 MCP.md를 참조하세요.

설정 (Configuration)

Storybook 내보내기 및 린팅 (linting)을 위해 설정 파일을 생성하세요:

figma-use init

.figma-use.json 파일을 생성합니다:

{
  "storybook": {
    "page": "Components",
...

CLI 인자(arguments)는 설정 값을 덮어씁니다.

AI 에이전트용

Claude Code, Cursor 및 기타 에이전트를 위한 참조 문서인 SKILL.md가 포함되어 있습니다.

작동 원리

┌─────────────┐            ┌─────────────┐
│   터미널 (Terminal)  │────CDP────▶│   Figma     │
│  figma-use  │  port 9222 │             │
...

figma-use는 Chrome DevTools Protocol (CDP)를 통해 Figma와 직접 통신합니다. Figma를 --remote-debugging-port=9222 옵션과 함께 실행하기만 하면 준비가 완료됩니다.

명령어는 Figma의 JavaScript 컨텍스트 내에서 Runtime.evaluate를 통해 실행되며, Plugin API에 대한 모든 권한을 가집니다.

데몬 (Daemon)

선택 사항인 데몬은 연속적인 명령어를 더 빠르게 실행할 수 있도록 CDP 연결을 유지(warm)합니다:

figma-use daemon start    # 백그라운드 데몬 실행 (~25% 더 빠른 명령어 실행)
figma-use daemon stop     # 데몬 중지
figma-use daemon status   # 실행 상태 확인

파이프 전송 (Pipe Transport)

패치를 위한 관리자 권한(admin access)이 없는 Figma 126+ 버전의 경우, 데몬은 대신 --remote-debugging-pipe를 사용하여 Figma를 실행할 수 있습니다:

figma-use daemon start --pipe   # Figma를 실행하고 stdio 파이프를 통해 연결

사용자 정의 바이너리 위치를 지정하려면 FIGMA_BIN을 설정하세요. 데몬이 파이프 연결을 유지하며, 모든 명령어는 자동으로 이를 통해 라우팅됩니다.

라이선스 (License)

MIT