Figma Design Rule Extractor

---
name: figma-design-rule-extractor
description: |
  Figma 디자인 시스템을 분석하여 .claude/rules/design-system/ 규칙 파일을 생성합니다.
  디자인 토큰, 공통 컴포넌트, 레이아웃 패턴, 타이포그래피, 간격 체계 등
  자체 디자인 시스템 구성에 필요한 모든 정보를 추출하고 규칙화합니다.
  Figma 디자인 규칙 추출, 디자인 시스템 문서화, design-system rule 생성 시 사용하세요.
license: MIT
metadata:
  author: hanssem
  version: "4.0.0"
  category: design-system
allowed-tools: Bash Read Write Edit Glob
---

# 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` 등 |

### 프로젝트 내 기존 자산 감지

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

```bash
# 토큰 관련
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](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/](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](references/extraction.md)

---

## Step 4: 분석 기준

### 공통 컴포넌트 식별

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

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

### 레이아웃 패턴 식별

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

상세 분석 기준: [references/analysis.md](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](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 재시작
```

---

## 사용 예시

```bash
# 기본 사용
/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
```

---

## 참조

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

### 병렬 처리용 에이전트

- [figma-metadata-agent](agents/figma-metadata-agent.md) - 메타데이터 추출
- [figma-token-agent](agents/figma-token-agent.md) - 토큰 추출