166 lines
6.8 KiB
Markdown
166 lines
6.8 KiB
Markdown
# Figma → HTML Agent
|
||
|
||
Figma 디자인 프레임을 **수학적으로 정확하게** HTML/CSS로 변환하고, design_agent의 **블록 라이브러리**로 축적하는 독립 에이전트.
|
||
|
||
---
|
||
|
||
## 이 에이전트는 뭘 하는가?
|
||
|
||
1. Figma 파일에서 프레임을 선택하면
|
||
2. MCP(Figma Dev Mode)로 구조/스타일/스크린샷을 가져와서
|
||
3. 수학적 계산(scale, gradient 변환, shadow 등)으로 1:1 HTML/CSS를 만들고
|
||
4. AI가 재디자인할 수 있는 블록(순수 CSS + Jinja2 슬롯)으로 변환하여
|
||
5. design_agent의 블록 라이브러리(`templates/blocks/`)에 편입한다
|
||
|
||
**핵심:** AI redesigner가 색상/크기/구조를 조정할 수 있도록, 장식 요소는 **CSS로 구현**하고 이미지는 crop/곡선/일러스트/사진만 남긴다.
|
||
|
||
---
|
||
|
||
## 폴더 구조
|
||
|
||
```
|
||
figma_to_html_agent/
|
||
├── README.md ← 이 파일 (사용법)
|
||
├── CLAUDE.md ← 에이전트 명세 (11개 원칙)
|
||
├── PROCESS.md ← 10단계 변환 절차 핸드북
|
||
├── MATH.md ← 수학 공식 (§1~9)
|
||
├── RULES.md ← CSS 보정 규칙 (R1~R16)
|
||
├── PROCESS-CONTROL.md ← 작업 규율 (찍어맞추기 금지 등)
|
||
├── blocks_index.md ← 변환 완료 도서관 + 디자인 인사이트
|
||
│
|
||
├── scripts/
|
||
│ └── gradient_math.py ← SVG → CSS gradient 수학 변환 도구
|
||
│
|
||
├── block-tests/ ← 1:1 HTML 변환물 (원본 검증용)
|
||
│ ├── {slug}.html ← Figma 원본과 100% 동일한 정적 HTML
|
||
│ ├── {slug}_flat.md ← 플래튼/이상탐지/변형축 메모
|
||
│ └── assets/ ← 이미지 에셋
|
||
│ ├── shared/ ← 해시 기반 공유 캐시
|
||
│ └── frame_{id}/ ← 프레임 전용 (legacy)
|
||
│
|
||
└── templates_staging/ ← Jinja2 템플릿 초안 (legacy, 현재 미사용)
|
||
```
|
||
|
||
### 산출물 최종 위치 (design_agent 본체)
|
||
|
||
```
|
||
design_agent/
|
||
└── templates/
|
||
└── blocks/
|
||
├── new/ ← Figma 추출 블록 (8개)
|
||
├── svg/ ← 블록 공용 이미지 (33개)
|
||
├── slide-base.html ← 고정 슬라이드 배경 (16:9)
|
||
└── cards/, emphasis/, headers/, media/, visuals/, BEPs/, redesign/
|
||
```
|
||
|
||
---
|
||
|
||
## 사용법
|
||
|
||
### 사전 준비
|
||
|
||
1. **Figma Desktop** 앱에서 대상 파일을 열고 **Dev Mode** 활성화
|
||
2. `.mcp.json`에 Figma Desktop SSE 서버 등록 확인:
|
||
```json
|
||
{ "url": "http://127.0.0.1:3845/sse" }
|
||
```
|
||
3. Claude Code 세션 시작
|
||
|
||
### 변환 실행 (10단계)
|
||
|
||
```
|
||
STEP 0 에이전트가 blocks_index.md 읽기 → 기존 패턴 확인
|
||
STEP 1 get_metadata — 구조 + bbox (XML)
|
||
STEP 2 get_design_context — gradient/filter/font (React+Tailwind)
|
||
STEP 3 get_screenshot — Figma 원본 PNG (검증용)
|
||
STEP 4 자산 다운로드 — block-tests/assets/shared/ 캐시
|
||
STEP 5 flat.md 작성 — bottom-up 플래튼 + 이상탐지 + 변형축
|
||
STEP 6 gradient 수학 변환 — scripts/gradient_math.py
|
||
STEP 7 HTML 작성 — 순수 CSS 우선, transform: scale() 균일 축소
|
||
STEP 8 검증 — Figma 스크린샷과 비교
|
||
STEP 9 저장 — block-tests/{slug}.html + flat.md
|
||
STEP 10 인덱스 업데이트 — blocks_index.md 1줄 추가
|
||
```
|
||
|
||
**상세:** [PROCESS.md](PROCESS.md) 참조
|
||
|
||
### 블록 프로모션 (block-tests → templates/blocks/)
|
||
|
||
1:1 HTML이 검증되면:
|
||
|
||
1. **CSS 전환** — SVG/PNG 장식 요소를 CSS gradient/border-radius/shadow로 변환
|
||
- CSS 전환 대상: gradient bar, ribbon, pill, badge, 오버레이 등
|
||
- 이미지 유지 대상: crop/프레임 배치(R16), 곡선 아크, 아이콘, 일러스트, 실사 사진
|
||
2. **블록 작성** — `templates/blocks/new/{pattern}.html`
|
||
- flex layout, width: 100%, Jinja2 슬롯
|
||
- 수학적 계산 주석 (Figma px → scale → CSS 값)
|
||
- 이미지는 `svg/` 폴더에서 참조 (`{{ slot | default('svg/파일명') }}`)
|
||
3. **이미지 정리** — `templates/blocks/svg/`에 의미 있는 이름으로 저장
|
||
4. **catalog.yaml 등록** — content_structure, when, not_for 작성
|
||
5. **blocks_index.md 상태** — `staged` → `promoted` 업데이트
|
||
|
||
---
|
||
|
||
## 핵심 원칙 요약
|
||
|
||
| # | 원칙 | 설명 |
|
||
|---|------|------|
|
||
| 1 | 수학적 계산만 | Figma 좌표 → scale → CSS. 시행착오 px 조정 금지 |
|
||
| 2 | Bottom-up | leaf 노드부터 → 2개씩 묶기 → 계층 쌓기 |
|
||
| 3 | 순수 CSS 우선 | AI가 색상/크기 조정할 수 있게. SVG는 곡선/필터만 |
|
||
| 4 | 이미지 해석 금지 | gradient 방향은 데이터로. "보니까 ~인 것 같다" 금지 |
|
||
| 5 | 하드코딩 금지 | 결과물을 고치지 말고 프로세스를 고친다 |
|
||
| 6 | 전면 재작성 금지 | 80점에서 2개 고칠 때 구조를 갈아엎지 말 것 |
|
||
| 7 | 모든 슬롯 optional | 블록이 다양한 MDX에 매칭될 수 있게 |
|
||
|
||
**상세:** [CLAUDE.md](CLAUDE.md), [PROCESS-CONTROL.md](PROCESS-CONTROL.md), [RULES.md](RULES.md)
|
||
|
||
---
|
||
|
||
## 도구
|
||
|
||
| 도구 | 용도 |
|
||
|------|------|
|
||
| Figma MCP `get_metadata` | 프레임 구조 + 절대 좌표 (XML) |
|
||
| Figma MCP `get_design_context` | gradient/filter/font (React+Tailwind 코드) |
|
||
| Figma MCP `get_screenshot` | Figma 원본 PNG |
|
||
| `scripts/gradient_math.py` | SVG linearGradient → CSS linear-gradient 수학 변환 |
|
||
| Pillow | 이미지 픽셀 분석 (gradient 색상 추출, 이미지 해석 아님) |
|
||
|
||
---
|
||
|
||
## 수학 공식 요약
|
||
|
||
| 공식 | 용도 | 상세 |
|
||
|------|------|------|
|
||
| `S = 1280 / W_figma` | 균일 축소 scale | MATH.md §1 |
|
||
| `CSS_angle = 90 - Figma_angle` | gradient 각도 변환 | MATH.md §2 |
|
||
| SVG `<linearGradient>` → CSS | gradient stop % 변환 | gradient_math.py |
|
||
| `plus-darker → multiply` | blend mode 호환 | RULES.md R10 |
|
||
| bbox 비율 ≠ 텍스트 비율 → 회전 | rotation 감지 | RULES.md R11 |
|
||
|
||
---
|
||
|
||
## 현재 상태 (2026-04-13)
|
||
|
||
### 프로모션 완료 블록 (8개)
|
||
|
||
| 패턴 | 원본 프레임 | 블록 위치 |
|
||
|------|-----------|---------|
|
||
| statement-pill-highlight | 1171281207 | blocks/new/ |
|
||
| stacked-arrow-list | 1171281180 | blocks/new/ |
|
||
| split-panel-numbered | 1171281202 | blocks/new/ |
|
||
| issues-paired-rows | 1171281194 | blocks/new/ |
|
||
| compare-vs-rows | 1171281195 | blocks/new/ |
|
||
| quadrant-2x2-issues | 1171281193 | blocks/new/ |
|
||
| cards-3col-persona | 1171281191 | blocks/new/ |
|
||
| cycle-3way-intersect | 1171281211 | blocks/new/ |
|
||
|
||
### 공용 이미지 (templates/blocks/svg/, 33개)
|
||
|
||
화살표, 아크, 뱃지, 아이콘, 배경 텍스처, 사진 등. 블록에서 `svg/파일명`으로 참조.
|
||
|
||
### 고정 슬라이드 배경
|
||
|
||
`templates/blocks/slide-base.html` — 16:9 (1280×720), 상단 제목 + 구분선 + 본문 영역 + 하단 결론 pill.
|