C.E.L_Slide_test2/figma_to_html_agent

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 서버 등록 확인:

   { "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 참조

블록 프로모션 (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, PROCESS-CONTROL.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.