Figma Design Rule Extractor

Figma MCP를 활용하여 디자인 시스템을 분석하고,

.claude/rules/design-system/

핵심 원칙

실행 워크플로우

┌─────────────────────────────────────────────────────────────┐
│  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: 사용자 정보 수집 & 충돌 감지

필수 질문

typescript

css

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/

  (이전 추출본)

어떻게 처리할까요?

1. 참조하여 병합 - 기존 자산과 Figma 정보를 비교하여 통합
2. Figma 우선 - Figma 정보로 덮어쓰기 (기존 자산은 참고용으로만)
3. 기존 유지 - 기존 자산 기준, Figma에서 누락된 것만 추가
4. 취소 - 작업 중단, 수동 검토 후 재시도

상세 충돌 해결: 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

get_metadata

figma-token-agent

get_variable_defs

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

추출 대상

get_variable_defs

get_metadata

get_metadata

get_metadata

상세 추출 방법: 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 적용

상세 출력 형식: 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 - 토큰 추출