Figma-to-HTML/CLAUDE.md

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. 프로모션은 사용자 승인 후 진행 — 1:1 HTML 검증 완료 후, 사용자 승인을 받아 templates/blocks/new/에 블록을 생성하고 templates/blocks/svg/에 이미지를 정리한다. catalog.yaml 등록과 blocks_index.md 업데이트까지 에이전트가 수행한다. 단, 사용자 승인 없이 프로모션하지 않는다.
10. 시맨틱 우선, Figma 평면 레이어 그대로 옮기지 말 것 — Figma의 평면 레이어 구조는 디자인 도구의 한계일 뿐, 의미 구조가 아니다. 마커+텍스트는 list item, 카드 묶음은 column unit, 등 시맨틱하게 재그룹핑하여 작성한다. RULES.md R13 (Custom-marker bullet list) 참조. 새로 발견되는 sub-pattern은 blocks_index.md "디자인 인사이트" 섹션에 누적한다.
11. 모든 슬롯은 기본 optional — 1:1 단계에서 모든 슬롯이 채워져 있다고 해서 "이 블록은 필수" 로 해석하지 않는다. 같은 블록이 사진 없는/짧은/긴 mdx에 모두 매칭되어야 한다는 가정으로 설계한다.

변환 프로세스 (10단계)

전체 절차는 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/ 로 이전 + 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 — 1:1 변환 결과
• block-tests/{slug}_flat.md — 플래튼/이상 탐지/변형 축 메모
• assets/shared/... — 공유 자산 캐시
• blocks_index.md 한 줄 추가

출력 (프로모션, 사용자 승인 후):

• templates/blocks/new/{pattern}.html — AI가 재디자인 가능한 블록 (CSS + Jinja2)
• templates/blocks/svg/{name}.png/svg — 블록 공용 이미지
• templates/catalog.yaml — 블록 등록 (content_structure, when, not_for)
• blocks_index.md 상태 → promoted

폴더 구조

figma_to_html_agent/                ← 에이전트 작업 영역 (staging)
├── CLAUDE.md                       ← 이 파일 (에이전트 명세)
├── PROCESS.md                      ← 10단계 운영 절차 (변환 핸드북)
├── MATH.md                         ← 수학 공식 레퍼런스
├── RULES.md                        ← CSS 보정 규칙 (R1~R16)
├── PROCESS-CONTROL.md              ← "찍어맞추기 금지" 규칙
├── README.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 추상화 (legacy, 현재 미사용)

────────────────────────────────────────────────────────
프로모션 (사용자 승인 후 에이전트가 실행)
────────────────────────────────────────────────────────

design_agent/templates/
├── blocks/
│   ├── new/                        ← Figma 추출 블록 (에이전트가 작성)
│   ├── svg/                        ← 블록 공용 이미지 (에이전트가 정리)
│   ├── slide-base.html             ← 고정 슬라이드 배경
│   └── cards/, emphasis/, ...      ← 기존 블록
└── catalog.yaml                    ← 블록 등록 (에이전트가 업데이트)

중요: 프로모션(블록 생성, 이미지 정리, catalog 등록)은 사용자가 1:1 HTML을 검증하고 승인한 후에만 진행한다. 사용자 승인 없이 templates/ 를 수정하지 않는다.

금지 사항

• 시행착오 px 조정 (1씩 늘려보기 등)
• 사용자에게 "맞나요?" 반복 질문 (스스로 검증)
• line-height 등 CSS 속성을 감으로 보정 (폰트 메트릭에서 수학적 도출)
• 흰 텍스트 스트로크 (-webkit-text-stroke: white) 사용
• 블록 배경을 검정으로 표시 (미리보기는 항상 흰색 배경)
• 이미지 해석으로 gradient 방향 판단 (멀티모달 금지, 데이터로만 판단 — PROCESS-CONTROL.md 참조)
• 한 번에 여러 값 동시 수정 (gradient 각도와 border-radius 동시 변경 금지)
• 장식 요소를 이미지 슬롯(img src)으로 넣기 — gradient bar, ribbon, pill, badge, 오버레이 등은 CSS로 구현. AI가 색상/크기를 조정할 수 없는 이미지 의존 블록은 쓸 수 없다
• 사용자 승인 없이 templates/ 수정 — 프로모션은 사용자 승인 후에만
• 여러 프레임을 한 세션에 변환 (1세션 1프레임 원칙)
• plus-darker 블렌드 사용 (Safari 전용 → multiply로 교체, RULES.md R10)
• Figma 인벤토리/지문/군집 같은 사전 분류 (work-creating-work, 패턴은 bottom-up으로 발견)
• design_agent/templates/ 직접 수정 (프로모션 게이트는 사용자 전용. 에이전트는 staging까지만)
• 사용자에게 "templates/ 에 옮겨드릴까요?" 같은 제안 (월권. 사용자가 알아서 함)