Skip to content

@wrtnlabs Wrtn Technologies

autoview-figma-cli 0.5.0

Install from the command line:
Learn more about npm packages
$ npm install @wrtnlabs/autoview-figma-cli@0.5.0
Install via package.json:
"@wrtnlabs/autoview-figma-cli": "0.5.0"

About this version

Figma CLI - Design Token Extractor & Component Code Generator

Personal Access Token을 사용하여 Figma 파일에서 디자인 토큰을 추출하고, 컴포넌트 코드를 생성하며, boilerplate와 함께 새로운 프로젝트를 생성하는 CLI 도구입니다.

🚀 주요 기능

🎨 디자인 토큰 추출 (extract 명령어)

  • 🔐 대화형 토큰 입력: Personal Access Token을 안전하게 입력받습니다
  • 🌐 유연한 파일 지정: URL 또는 파일 키로 Figma 파일에 접근
  • 🔗 다양한 URL 형식 지원: 기존 /file/ 형식과 새로운 /design/ 형식 모두 지원
  • 📁 자동 파일 저장: JSON 형식으로 디자인 토큰을 저장

⚡ 컴포넌트 코드 생성 (generate 명령어) - NEW!

  • 🔧 Component Set 기반: Figma Component Set에서 React 컴포넌트 코드 자동 생성
  • 🎯 Variant 지원: 모든 variant를 포함한 완전한 컴포넌트 코드
  • 📝 자동 파일 생성: 각 Component Set마다 개별 .tsx 파일 생성
  • 🔍 선택적 생성: 전체 또는 특정 이름의 Component Set만 선택 생성
  • 📋 Component Set 목록: 파일 내 모든 Component Set 조회 기능

🛠️ 프로젝트 생성 (create 명령어)

  • 올인원 솔루션: 한 명령어로 boilerplate 클론 + Figma 토큰 추출 + 프로젝트 설정 완료
  • Private/Public Repository 지원: GitHub token 또는 git clone 방식 선택 가능
  • 자동 토큰 통합: CSS Variables, TypeScript 타입 정의 자동 생성
  • 대화형 인터페이스: 단계별 안내로 쉬운 프로젝트 생성

🎯 지원하는 토큰 타입

  • Color Styles: Figma에서 정의한 색상 스타일
  • Typography Styles: 텍스트 스타일
  • Variables: Figma Variables (색상, 숫자, 문자열, 불린)
  • Collections: 변수 컬렉션 정보

📦 설치 및 설정

  1. 프로젝트 빌드:
cd apps/figma-cli
pnpm install
pnpm build
  1. CLI 전역 설치:
pnpm link --global

  1. Figma Personal Access Token 발급:

  2. Figma MCP 서버 실행 (컴포넌트 코드 생성 시 필요):

    • MCP 서버가 localhost:3845에서 실행되어야 합니다
    • 실제 코드 생성은 MCP 서버를 통해 수행됩니다

🎯 사용법

명령어 1: extract - 디자인 토큰 추출

기본 사용법 (대화형)

figma-cli extract

옵션을 사용한 실행

# 토큰과 URL 미리 제공
figma-cli extract --token YOUR_TOKEN --url "https://www.figma.com/design/FILE_KEY/FILE_NAME"

# 출력 파일 경로 지정
figma-cli extract --output ./my-tokens.json

# 환경변수 사용
export FIGMA_ACCESS_TOKEN=your_token_here
figma-cli extract --url "https://www.figma.com/design/FILE_KEY/FILE_NAME"

명령어 2: generate - 컴포넌트 코드 생성 (NEW!)

기본 사용법

# 모든 Component Set 코드 생성
figma-cli generate --url "https://www.figma.com/design/FILE_KEY/FILE_NAME"

# 페이지에서 사용된 Component Set만 생성 (NEW!)
figma-cli generate --url "https://www.figma.com/design/FILE_KEY/FILE_NAME?node-id=1-2" --page

# Component Set 목록 보기
figma-cli generate --list --url "https://www.figma.com/design/FILE_KEY/FILE_NAME"

# 특정 이름의 Component Set만 생성
figma-cli generate --name "Button" --url "https://www.figma.com/design/FILE_KEY/FILE_NAME"

🎯 페이지 기반 컴포넌트 생성 (핵심 기능!)

사용자가 원하는 워크플로우를 위한 핵심 기능입니다! 특정 페이지에서 사용된 마스터 컴포넌트들만 선별하여 코드를 생성합니다.

사용법:

  1. Figma에서 원하는 페이지로 이동
  2. URL 복사 (node-id 파라미터가 포함되어야 함, 예: ?node-id=1-2)
  3. --page 옵션과 함께 명령어 실행:
figma-cli generate \
  --url "https://www.figma.com/design/abc123/TestPage?node-id=200-6444" \
  --page \
  --token YOUR_TOKEN

동작 방식:

  • 지정된 페이지에서 사용된 컴포넌트 인스턴스들을 분석
  • 해당 인스턴스들이 참조하는 마스터 Component Set들을 식별
  • 식별된 Component Set들과 모든 variant들의 코드만 생성
  • 각 Component Set마다 개별 .tsx 파일 생성 (예: Tab.tsx, Priority.tsx, Row.tsx)

예시 시나리오:

  • 첫 번째 이미지(페이지 디자인)에서 Tab, Priority, Row 컴포넌트를 사용
  • 두 번째 이미지(마스터 컴포넌트)에 해당 Component Set들과 variants 존재
  • --page 옵션으로 해당 페이지의 Component Set들만 선별 생성

고급 옵션

# 환경변수로 토큰 사용
export FIGMA_ACCESS_TOKEN=your_token_here
figma-cli generate --url "https://www.figma.com/design/FILE_KEY/FILE_NAME"

# 페이지 기반 생성 + 출력 디렉토리 지정
figma-cli generate \
  --url "https://www.figma.com/design/FILE_KEY/FILE_NAME?node-id=1-2" \
  --page \
  --output ./src/page-components

# 토큰 직접 제공
figma-cli generate --token YOUR_TOKEN --url "..."

# 파일 키로 직접 접근
figma-cli generate --key FILE_KEY --token YOUR_TOKEN

출력 예시

페이지 기반 생성:

🔍 Starting Figma component code generation...

📄 File Key: abc123def456
🎯 페이지 기반 생성 모드: 노드 ID 200:6444
🔍 페이지 200:6444에서 사용된 컴포넌트들을 분석합니다...
📄 페이지 찾음: Test for Local Components
🔍 발견된 컴포넌트 인스턴스: 4개
✓ 사용된 Component Set: Tab
✓ 사용된 Component Set: Priority
✓ 사용된 Component Set: Row
📋 발견된 Component Set: 3개
   - Tab (123:456)
   - Priority (123:789)
   - Row (123:012)

🔍 Processing: Tab (1/3)
✅ Tab - 3개 variant 처리 완료
🔍 Processing: Priority (2/3)
✅ Priority - 2개 variant 처리 완료
🔍 Processing: Row (3/3)
✅ Row - 4개 variant 처리 완료

📊 페이지 기반 처리 결과:
   ✅ 성공: 3개
   ⚠️ 건너뜀: 0개
   📁 총 발견: 3개

📁 출력 디렉토리: ./generated-components
✅ Tab → Tab.tsx (3개 variant)
✅ Priority → Priority.tsx (2개 variant)
✅ Row → Row.tsx (4개 variant)

📊 생성 완료:
   ✅ Component Set 파일: 3개
   📄 총 variant: 9개
   📁 출력 위치: ./generated-components
   📄 요약 파일: generation-summary.json

전체 생성:

🎨 Figma Component Code Generator
==================================

🔍 모든 Component Set의 코드 생성 중...
✅ Button → Button.tsx
   📁 /path/to/generated-components/Button.tsx
   🎯 3개 variant 포함
✅ Input → Input.tsx
   📁 /path/to/generated-components/Input.tsx
   🎯 2개 variant 포함

✅ 코드 생성 완료!
📁 출력 디렉토리: /path/to/generated-components
🎯 생성된 Component Set: 2개
📄 요약 파일: generation-summary.json

명령어 3: create - 프로젝트 생성

기본 사용법

figma-cli create my-awesome-project

고급 옵션

# 토큰 추출 건너뛰기
figma-cli create my-project --skip-tokens

# 다른 boilerplate 저장소 사용
figma-cli create my-project --source github:your-org/your-boilerplate

# 특정 경로에 생성
figma-cli create my-project --destination ./projects

# Private repository에서 git clone 사용
figma-cli create my-project --source github:your-org/private-repo --use-git

# 특정 브랜치 사용
figma-cli create my-project --source github:your-org/repo --use-git --branch develop

# Figma 정보 미리 제공
figma-cli create my-project --token YOUR_TOKEN --url "https://www.figma.com/design/FILE_KEY/FILE_NAME"

🎨 생성되는 파일들

generate 명령어로 생성되는 파일들

generated-components/
├── Button.tsx                  # Button Component Set 코드
├── Input.tsx                   # Input Component Set 코드
├── Card.tsx                    # Card Component Set 코드
└── generation-summary.json     # 생성 요약 정보

생성된 컴포넌트 파일 예시

// Component Set: Button
// Description: Primary button component
// Component Set ID: 123:456
// Total Variants: 3
// Variant: 123:457
import React from "react";

interface ButtonProps {
  size?: "small" | "medium" | "large";
  variant?: "primary" | "secondary";
}

export const Button: React.FC<ButtonProps> = ({
  size = "medium",
  variant = "primary",
}) => {
  return <button className={`btn btn-${variant} btn-${size}`}>Button</button>;
};

// Variant: 123:458
// ... 추가 variant 코드 ...

생성 요약 파일 예시

{
  "generatedAt": "2024-01-15T10:30:00.000Z",
  "figmaFileKey": "abc123def456",
  "componentSets": [
    {
      "id": "123:456",
      "name": "Button",
      "description": "Primary button component",
      "variantCount": 3,
      "fileName": "Button.tsx"
    }
  ]
}

create 명령어로 생성되는 파일들

my-project/
├── src/
│   ├── styles/
│   │   └── tokens.css          # CSS Variables
│   └── tokens/
│       └── index.ts            # TypeScript 타입 정의
├── design-tokens.json          # 원본 토큰 JSON
├── package.json               # 프로젝트명 업데이트됨
└── README.md                  # 프로젝트명 업데이트됨

CSS Variables 예시

:root {
  /* Colors */
  --color-blue-500: #71a9dc;
  --color-pink-400: #e6bce6;
  --color-system-blue-000: #2388f3;

  /* 추가된 색상들... */
}

TypeScript 타입 예시

// Auto-generated design tokens from Figma

export type ColorToken = "blue-500" | "pink-400" | "system-blue-000";

export const colors = {
  "blue-500": "#71a9dc",
  "pink-400": "#e6bce6",
  "system-blue-000": "#2388f3",
} as const;

📋 명령어 옵션

extract 명령어 옵션

  • -t, --token <token>: Figma Personal Access Token (선택사항)
  • -u, --url <url>: Figma 파일 URL (선택사항)
  • -k, --key <key>: Figma 파일 키 (선택사항)
  • -o, --output <path>: 출력 파일 경로 (기본값: ./design-tokens.json)
  • -j, --json <path>: 추가 JSON 파일에서 변수 추출
  • -v, --variable <name>: JSON 파일에서 추출할 변수명

generate 명령어 옵션

  • -u, --url <url>: Figma 파일 URL (선택사항)
  • -l, --list: Component Set 목록 보기
  • -n, --name <name>: 특정 이름의 Component Set만 생성
  • -o, --output <path>: 출력 디렉토리 지정 (선택사항)
  • -t, --token <token>: Figma Personal Access Token (선택사항)
  • -k, --key <key>: Figma 파일 키 (선택사항)

create 명령어 옵션

  • -s, --source <url>: Boilerplate Git 저장소 URL (기본값: github:wrtnlabs/autoview-boilerplate)
  • -d, --destination <path>: 생성할 디렉토리 (기본값: 현재 디렉토리)
  • --skip-tokens: Figma 토큰 추출 건너뛰기
  • --use-git: Git clone 사용 (private repo용)
  • --branch <branch>: 클론할 브랜치 (git clone 사용시)
  • -t, --token <token>: Figma Personal Access Token (선택사항)
  • -u, --url <url>: Figma 파일 URL (선택사항)
  • -k, --key <key>: Figma 파일 키 (선택사항)

🌟 사용 예시

완전 자동화된 워크플로우

# 환경변수 설정
export FIGMA_ACCESS_TOKEN=figd_xxxxxxxxxxxxxx
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxx

# 프로젝트 생성 (토큰 입력 없이)
figma-cli create design-system-app

# 결과: Figma 토큰이 통합된 완성된 프로젝트

Private Repository 사용 예시

# Private boilerplate + Figma 토큰 통합
figma-cli create my-company-project \
  --source github:my-company/private-boilerplate \
  --use-git \
  --branch company-template \
  --token figd_xxxxxxxxxxxxxx \
  --url "https://www.figma.com/design/FILE_KEY/FILE_NAME"

토큰 추출만 하기

# 디자인 토큰만 추출하고 싶을 때
figma-cli extract --token figd_xxxxxxxxxxxxxx --url "https://www.figma.com/design/FILE_KEY/FILE_NAME"

🛠 개발 워크플로우

# 1. 토큰 추출 + 프로젝트 생성
figma-cli create my-project

# 2. 프로젝트 디렉토리로 이동
cd my-project

# 3. 의존성 설치
npm install

# 4. 개발 서버 시작
npm run dev

🚨 문제 해결

Degit 실패 시

# Private repository인 경우
figma-cli create my-project --source github:org/repo --use-git

# 또는 GitHub token 설정
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxx
figma-cli create my-project --source github:org/private-repo

Git Clone 실패 시

# SSH 키 설정 확인
ssh -T git@github.com

# 또는 HTTPS 인증 설정
gh auth login

📊 출력 형식 (extract 명령어)

추출된 디자인 토큰은 다음과 같은 JSON 형식으로 저장됩니다:

{
  "colors": [
    {
      "name": "Primary Blue",
      "description": "Main brand color",
      "type": "color",
      "value": "rgba(0, 123, 255, 1)",
      "source": "style"
    }
  ],
  "typography": [
    {
      "name": "Heading 1",
      "description": "Main heading style",
      "type": "typography",
      "value": {
        "fontFamily": "Inter",
        "fontSize": 32,
        "fontWeight": 700,
        "lineHeight": "normal"
      },
      "source": "style"
    }
  ]
}

Details

Assets

  • autoview-figma-cli-0.5.0.tgz

Download activity

  • Total downloads 0
  • Last 30 days 0
  • Last week 0
  • Today 0

Recent versions

View all