Figma Design Rule Extractor

Figma MCP를 활용하여 디자인 시스템을 분석하고, .claude/rules/design-system/ 규칙 파일을 생성합니다.

핵심 원칙

| 원칙 | 설명 | |------|------| | Rule Output Only | .css/.js 파일 생성 X → 규칙 파일만 생성 | | Comprehensive Analysis | 토큰뿐 아니라 컴포넌트, 레이아웃, 패턴까지 분석 | | Conflict Detection | 기존 규칙과 충돌 시 사용자 확인 후 진행 | | Parallel Processing | 깊은 레이어 구조는 병렬 처리 |

실행 워크플로우

┌─────────────────────────────────────────────────────────────┐
│  Step 1: 사용자 정보 수집 & 충돌 감지                         │
│  - Figma URL, clientLanguages, clientFrameworks             │
│  - 기존 .claude/rules/design-system/ 존재 여부 확인          │
│  - 충돌 시 사용자에게 처리 방법 질문                          │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 2: 구조 분석 (get_metadata)                            │
│  - 전체 레이어 구조 파악                                     │
│  - 깊은 depth 감지 시 하위 nodeId 목록화 → 병렬 처리 준비     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 3: 병렬 정보 수집                                      │
│  ┌─────────────┬─────────────┬─────────────┐               │
│  │ 토큰 추출    │ 컴포넌트 분석 │ 레이아웃 분석│               │
│  │ (variables) │ (metadata)  │ (metadata)  │               │
│  └─────────────┴─────────────┴─────────────┘               │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 4: 분석 & 정리                                         │
│  - 공통 컴포넌트 식별 및 중복 개수 집계                       │
│  - 레이아웃 패턴 추출 (Header, Footer, Sidebar 등)           │
│  - 토큰 체계 정리 (Color, Spacing, Typography, Radius 등)   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  Step 5: 규칙 파일 생성                                      │
│  - Progressive Disclosure 원칙에 따라 구조화                 │
│  - .claude/rules/design-system/ 디렉토리 생성               │
└─────────────────────────────────────────────────────────────┘

Step 1: 사용자 정보 수집 & 충돌 감지

필수 질문

| 항목 | 설명 | |------|------| | Figma URL | 디자인 시스템 파일 URL | | Node ID (선택) | 특정 페이지/프레임 (전체 파일은 생략) | | clientLanguages | typescript, css 등 | | clientFrameworks | react, nextjs, tailwind 등 |

프로젝트 내 기존 자산 감지

반드시 다음 파일/디렉토리 존재 여부 확인:

# 토큰 관련
ls tailwind.config.* 2>/dev/null
ls **/tokens.* **/design-tokens.* 2>/dev/null
ls **/variables.scss **/variables.css 2>/dev/null

# 컴포넌트 관련
ls -d components/ ui/ src/components/ src/ui/ 2>/dev/null

# 기존 규칙
ls .claude/rules/design-system/ 2>/dev/null

기존 자산이 있을 경우 반드시 질문:

📁 프로젝트에 기존 디자인 자산이 발견되었습니다.

토큰 파일:

tailwind.config.ts (Tailwind 설정)

src/styles/tokens.css (CSS 변수)

컴포넌트:

src/components/ (23개 컴포넌트)

src/ui/ (12개 UI 요소)

기존 규칙:

.claude/rules/design-system/ (이전 추출본)

어떻게 처리할까요?

참조하여 병합 - 기존 자산과 Figma 정보를 비교하여 통합

Figma 우선 - Figma 정보로 덮어쓰기 (기존 자산은 참고용으로만)

기존 유지 - 기존 자산 기준, Figma에서 누락된 것만 추가

취소 - 작업 중단, 수동 검토 후 재시도

상세 충돌 해결: references/conflict.md

Step 2-3: 정보 수집 (병렬 처리)

병렬 처리 기준

레이어 depth가 3 이상이거나, 최상위 노드가 5개 이상일 경우 서브에이전트로 병렬 처리:

# 순차 처리 (작은 파일)
get_metadata(fileKey, nodeId) → 전체 분석

# 병렬 처리 (큰 파일) - Task 도구로 에이전트 병렬 실행
├─ Task(figma-metadata-agent, nodeId_1)   # 페이지 1 분석
├─ Task(figma-metadata-agent, nodeId_2)   # 페이지 2 분석
├─ Task(figma-token-agent, fileKey)       # 토큰 추출
└─ 결과 병합

병렬 처리용 에이전트

| 에이전트 | 역할 | 도구 | |---------|------|------| | figma-metadata-agent | 특정 nodeId의 메타데이터 추출 | get_metadata | | figma-token-agent | 전체 파일의 토큰 추출 | get_variable_defs |

에이전트 정의: agents/ 디렉토리 참조

추출 대상

| 카테고리 | 추출 항목 | MCP 도구 | 에이전트 | |---------|----------|----------|---------| | 토큰 | Color, Spacing, Typography, Radius, Shadow | get_variable_defs | figma-token-agent | | 컴포넌트 | 이름, 중복 개수, Description, Annotation | get_metadata | figma-metadata-agent | | 레이아웃 | Header, Footer, Sidebar, Grid 패턴 | get_metadata | figma-metadata-agent | | 패턴 | 반복되는 구조, 공통 프레임 | get_metadata | figma-metadata-agent |

상세 추출 방법: references/extraction.md

Step 4: 분석 기준

공통 컴포넌트 식별

동일/유사 이름의 컴포넌트를 그룹화하고 중복 개수를 집계:

| 컴포넌트 | 변형 | 중복 개수 | 비고 |
|---------|------|----------|------|
| Button | Primary, Secondary, Ghost | 47 | 공통화 권장 |
| Input | Text, Select, Checkbox | 23 | 공통화 권장 |
| Card | Default, Elevated | 15 | 공통화 권장 |
| Badge | - | 3 | 검토 필요 |

레이아웃 패턴 식별

| 패턴 | 구성 | 사용처 |
|------|------|--------|
| AppShell | Header + Sidebar + Main | 대시보드 |
| AuthLayout | Center + Card | 로그인/회원가입 |
| ListDetail | List + Detail Panel | 목록 상세 |

상세 분석 기준: references/analysis.md

Step 5: 출력 구조

생성되는 규칙 파일

.claude/rules/design-system/
├── AGENTS.md              # 진입점 - 규칙 개요
├── RULE.md                # 2단계 - 핵심 규칙 (<500줄)
└── references/            # 3단계 - 상세 문서
    ├── tokens.md          # 토큰 상세 (Color, Spacing, Typography)
    ├── components.md      # 공통 컴포넌트 목록 및 가이드
    ├── layouts.md         # 레이아웃 패턴
    └── annotations.md     # 디자이너 노트 및 Description

Progressive Disclosure 적용

| 단계 | 파일 | 내용 | |------|------|------| | 1단계 | AGENTS.md | 개요, 언제 참조해야 하는지 | | 2단계 | RULE.md | 핵심 규칙, 토큰 사용법, 금지 사항 | | 3단계 | references/* | 전체 토큰 목록, 컴포넌트 상세, 레이아웃 가이드 |

상세 출력 형식: references/output.md

MCP 설정 안내

MCP 호출 실패 시:

Figma MCP가 설정되지 않았습니다.

설정 방법:
1. Figma > Settings > Personal access tokens에서 토큰 생성
2. ~/.claude/mcp_settings.json에 추가:

{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@anthropic/figma-mcp"],
      "env": { "FIGMA_ACCESS_TOKEN": "your-token" }
    }
  }
}

3. Claude Code 재시작

사용 예시

# 기본 사용
/figma-design-rule-extractor

# URL 직접 전달
/figma-design-rule-extractor https://www.figma.com/file/ABC123/Design-System

# 특정 페이지만
/figma-design-rule-extractor https://www.figma.com/file/ABC123/Design-System?node-id=0:1

참조

추출 상세 - MCP 도구 사용법
분석 기준 - 컴포넌트/레이아웃 식별 기준
출력 형식 - 규칙 파일 템플릿
충돌 해결 - 기존 자산/규칙과의 충돌 처리

병렬 처리용 에이전트

figma-metadata-agent - 메타데이터 추출
figma-token-agent - 토큰 추출