@wrtnlabs/autoview-figma-cli

Figma CLI - Design Token Extractor & Project Generator

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

🚀 주요 기능

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

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

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

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

🎯 지원하는 토큰 타입

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

📦 설치 및 설정

• 프로젝트 빌드:

cd apps/figma-cli
pnpm install
pnpm build

• CLI 전역 설치:

pnpm link --global

• Figma Personal Access Token 발급:
  • Figma Settings > Personal access tokens에서 토큰 생성

🎯 사용법

명령어 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: create - 프로젝트 생성 (NEW!)

기본 사용법

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"

🔐 Private Repository 지원

방법 1: GitHub Token 사용 (degit)

# GitHub 토큰을 환경변수로 설정
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxx

# Private repository 사용 (degit 방식)
figma-cli create my-project --source github:your-org/private-boilerplate

방법 2: Git Clone 사용

# Git clone 방식으로 private repository 클론
figma-cli create my-project --source github:your-org/private-repo --use-git

# 특정 브랜치에서 클론
figma-cli create my-project \
  --source github:your-org/private-repo \
  --use-git \
  --branch develop

Git 인증 설정

Git clone 방식을 사용할 때는 다음 중 하나의 인증 방법이 필요합니다:

• SSH 키 설정

  # SSH URL 사용
  figma-cli create my-project --source [e-mail]:your-org/private-repo.git --use-git
  

• GitHub CLI 로그인

  gh auth login
  figma-cli create my-project --source github:your-org/private-repo --use-git
  

🎨 생성되는 파일들 (create 명령어)

CLI는 다음 파일들을 자동으로 생성합니다:

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 파일에서 추출할 변수명

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 [e-mail]

# 또는 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"
    }
  ]
}