kyeongmin
51548fdc41
figma_to_html_agent/: - Figma MCP 기반 블록 추출 에이전트 (CLAUDE.md, PLAN.md, PROCESS.md 등) - block-tests/: Figma→HTML 변환 결과물 (bim-3roles-cards 등) - templates_staging/: Jinja2 템플릿 + meta.yaml + example.yaml - figma-analysis/, figma-assets/: Figma 분석 데이터 + 에셋 - scripts/: gradient_math.py 등 유틸리티 설정: - .mcp.json: Figma MCP 서버 연결 설정 - .claude/settings.json: Claude Code 프로젝트 설정 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
124 lines
8.3 KiB
Markdown
124 lines
8.3 KiB
Markdown
# Figma → HTML Agent
|
||
|
||
Figma 프레임을 **수학적으로 정확하게** HTML/CSS로 변환하고, 변환물을 **재사용 가능한 블록 라이브러리**로 축적하는 에이전트.
|
||
|
||
## 목적
|
||
|
||
사용자가 Figma 파일에서 프레임을 선택하면:
|
||
1. 그 프레임을 16:9 슬라이드(1280×720) 안의 HTML 블록으로 100% 동일하게 변환한다
|
||
2. 변환물의 "변형 가능 축"을 기록한다 (원 개수, 색상, 라벨 등)
|
||
3. 같은 패턴이 반복되면 Jinja2 템플릿으로 추상화하여 design_agent의 블록 라이브러리에 편입한다
|
||
|
||
## 핵심 원칙 (절대 어기지 않음)
|
||
|
||
1. **수학적 계산만 허용** — 시행착오 px 조정 금지. Figma 좌표 → 스케일 → CSS 값 수학적 도출
|
||
2. **Bottom-up 프로세스** — leaf 노드 플래튼 → 2개씩 묶기 → 계층 쌓기. top-down하면 누락
|
||
3. **이상 탐지 필수** — 모든 노드에 bbox 비율 검사, 회전 감지, 중복 감지 수행
|
||
4. **AI가 먼저 발견** — 디테일(1px, 1° 차이)을 사용자 피드백 전에 AI가 스스로 찾음
|
||
5. **하드코딩 금지** — 결과물을 수동으로 고치지 말고 프로세스를 고친다
|
||
6. **AI 역할 분담** — AI는 분류(고르기)만, 구성(만들기)은 코드. LLM은 px을 못 본다
|
||
7. **컨텍스트 관리는 compact로** — 한 세션에서 여러 프레임을 연속 작업할 수 있다. 컨텍스트가 무거워지면 `/compact` 로 핵심만 요약하고 계속 진행. 이유: 핵심 결정/구조/규칙은 모두 파일(CLAUDE.md, PROCESS.md, RULES.md, blocks_index.md, 산출물)에 박혀있어 compact 후에도 보존됨. 손실되는 건 시행착오/디버깅 과정 뿐이며, 이건 잃어도 OK. 매 프레임마다 새 세션을 강제하면 누적 학습이 silo되어 R13 같은 sub-pattern 발견의 즉시 적용이 불가능해짐.
|
||
8. **순수 CSS 우선, SVG는 곡선/필터에만** — 동적 재구성 위해 가능한 한 HTML div + linear-gradient 사용
|
||
9. **프로모션 게이트는 사용자 전용** — 에이전트는 절대 `design_agent/templates/` 에 직접 쓰지 않는다. 모든 작업은 `figma_to_html_agent/` 안에서 끝나며, 본체 라이브러리 이전은 사용자 수동 검수 후 사용자 본인이 수행한다.
|
||
10. **시맨틱 우선, Figma 평면 레이어 그대로 옮기지 말 것** — Figma의 평면 레이어 구조는 디자인 도구의 한계일 뿐, 의미 구조가 아니다. 마커+텍스트는 list item, 카드 묶음은 column unit, 등 시맨틱하게 재그룹핑하여 작성한다. RULES.md R13 (Custom-marker bullet list) 참조. 새로 발견되는 sub-pattern은 [blocks_index.md](blocks_index.md) "디자인 인사이트" 섹션에 누적한다.
|
||
11. **모든 슬롯은 기본 optional** — 1:1 단계에서 모든 슬롯이 채워져 있다고 해서 "이 블록은 필수" 로 해석하지 않는다. 같은 블록이 사진 없는/짧은/긴 mdx에 모두 매칭되어야 한다는 가정으로 설계한다.
|
||
|
||
## 변환 프로세스 (10단계)
|
||
|
||
전체 절차는 [PROCESS.md](PROCESS.md) 참조.
|
||
|
||
```
|
||
0-A. 에이전트: blocks_index.md 한 번 읽기 (지난 변환 패턴 확인)
|
||
0-B. 사용자: Figma에서 프레임 선택
|
||
1. get_metadata ← 구조 + bbox
|
||
2. get_design_context ← gradient/filter/text 정보
|
||
3. get_screenshot ← Figma 원본 (검증 비교용)
|
||
4. 자산 → block-tests/assets/shared/{hash} 캐시
|
||
5. flat.md 작성 ← bottom-up + 이상 탐지 + 변형 축 메모
|
||
6. 그라데이션 수학 변환 ← scripts/gradient_math.py 호출
|
||
7. HTML 작성 ← 순수 CSS 우선, transform: scale() 균일 축소
|
||
8. Selenium 스크린샷 ← Figma 프리뷰와 사람 눈 비교
|
||
9. block-tests/{slug}.html + flat.md 저장
|
||
10. blocks_index.md 1줄 업데이트
|
||
```
|
||
|
||
**패턴 발견 트리거:** 동일 구조의 프레임이 **2번째** 등장하는 순간 → `templates_staging/{pattern_id}.html.j2` 로 Jinja2화. 이게 staging 종착점.
|
||
|
||
**프로모션 게이트:** staging까지가 에이전트 책임. 그 다음은 사용자가 직접 검수하고 [design_agent/templates/blocks/](../templates/blocks/) 로 이전 + [catalog.yaml](../templates/catalog.yaml) 등록. **에이전트는 design_agent/templates/ 를 절대 건드리지 않는다.**
|
||
|
||
## 도구
|
||
|
||
| 도구 | 용도 |
|
||
|------|------|
|
||
| Figma MCP `get_metadata` | 프레임 구조 + 절대 좌표 |
|
||
| Figma MCP `get_design_context` | gradient/filter/font 등 stylable 데이터 |
|
||
| Figma MCP `get_screenshot` | Figma 원본 PNG (눈 검증용) |
|
||
| `scripts/gradient_math.py` | SVG `<linearGradient>` → CSS `linear-gradient(...)` 수학 변환 |
|
||
| Selenium (headless Chrome) | HTML 렌더링 + 검증 스크린샷 |
|
||
| Pillow | 스크린샷 자르기/비교 |
|
||
|
||
## 입출력
|
||
|
||
**입력:** Figma 파일 + 노드 ID (또는 현재 선택 노드)
|
||
**출력:**
|
||
- `block-tests/{slug}.html` — 변환 결과
|
||
- `block-tests/{slug}_flat.md` — 플래튼/이상 탐지/변형 축 메모
|
||
- `assets/shared/...` — 공유 자산 캐시
|
||
- `blocks_index.md` 한 줄 추가
|
||
|
||
## 폴더 구조
|
||
|
||
```
|
||
figma_to_html_agent/ ← 에이전트 작업 영역 (staging)
|
||
├── CLAUDE.md ← 이 파일 (에이전트 명세)
|
||
├── PROCESS.md ← 10단계 운영 절차 (변환 핸드북)
|
||
├── MATH.md ← 수학 공식 레퍼런스
|
||
├── RULES.md ← CSS 보정 규칙 (R1~R12)
|
||
├── PROCESS-CONTROL.md ← "찍어맞추기 금지" 규칙
|
||
├── PLAN.md ← 현재 진행 현황
|
||
├── blocks_index.md ← 변환 완료 도서관
|
||
│
|
||
├── scripts/
|
||
│ ├── __init__.py ← 빈 파일 (패키지 인식용)
|
||
│ └── gradient_math.py ← SVG→CSS 그라데이션 변환 함수
|
||
│
|
||
├── block-tests/ ← Stage 1: 정적 1:1 변환물
|
||
│ ├── {slug}.html
|
||
│ ├── {slug}_flat.md
|
||
│ ├── _renders/ ← Selenium 검증 스크린샷
|
||
│ └── assets/
|
||
│ ├── shared/ ← 해시 기반 자산 캐시 (재사용)
|
||
│ └── frame_{id}/ ← 프레임 전용 자산 (legacy)
|
||
│
|
||
└── templates_staging/ ← Stage 2: Jinja2 추상화
|
||
├── {pattern_id}.html.j2
|
||
└── {pattern_id}.meta.yaml ← when/slots/min_size_px 초안
|
||
|
||
────────────────────────────────────────────────────────
|
||
🚧 프로모션 게이트 (사용자 수동 작업) 🚧
|
||
────────────────────────────────────────────────────────
|
||
|
||
design_agent/ ← 본체 라이브러리 (에이전트 접근 금지)
|
||
└── templates/
|
||
├── blocks/{category}/
|
||
│ └── {pattern_id}.html.j2 ← 사용자가 staging에서 이전
|
||
└── catalog.yaml ← 사용자가 when/slots 등록
|
||
```
|
||
|
||
**중요:** 에이전트는 위 구분선 아래(`design_agent/templates/`)를 **절대 수정하지 않는다.** 그 영역은 사용자가 staging 결과물을 검수한 뒤 본인이 직접 프로모션한다.
|
||
|
||
## 금지 사항
|
||
|
||
- 시행착오 px 조정 (1씩 늘려보기 등)
|
||
- 사용자에게 "맞나요?" 반복 질문 (스스로 검증)
|
||
- line-height 등 CSS 속성을 감으로 보정 (폰트 메트릭에서 수학적 도출)
|
||
- 흰 텍스트 스트로크 (`-webkit-text-stroke: white`) 사용
|
||
- 블록 배경을 검정으로 표시 (미리보기는 항상 흰색 배경)
|
||
- **이미지 해석으로 gradient 방향 판단** (멀티모달 금지, 데이터로만 판단 — PROCESS-CONTROL.md 참조)
|
||
- **한 번에 여러 값 동시 수정** (gradient 각도와 border-radius 동시 변경 금지)
|
||
- **여러 프레임을 한 세션에 변환** (1세션 1프레임 원칙)
|
||
- **plus-darker 블렌드 사용** (Safari 전용 → multiply로 교체, RULES.md R10)
|
||
- **Figma 인벤토리/지문/군집 같은 사전 분류** (work-creating-work, 패턴은 bottom-up으로 발견)
|
||
- **`design_agent/templates/` 직접 수정** (프로모션 게이트는 사용자 전용. 에이전트는 staging까지만)
|
||
- **사용자에게 "templates/ 에 옮겨드릴까요?" 같은 제안** (월권. 사용자가 알아서 함)
|