C.E.L_Slide_test2/figma_to_html_agent/FIGMA-CONVERSION-REVIEW.md

Figma → HTML 변환 프로세스 리뷰

2026-04-08~09 테스트 세션 결과. 기존 FIGMA-EXTRACTION.md / FIGMA-DESIGN-LANGUAGE.md는 그대로 유지.

---

1. 테스트 경과

1.1 테스트 대상

순서	프레임	노드수	성격	결과
1	Frame 1171281214 (37:231)	~15	단일 카드 (H/W 탭+라벨+본문)	부분 성공 (둥근 모서리 누락)
2	Frame 1171281215 (39:239)	149	시스템 구성 (H/W 7항목 + 중앙원 + S/W 6항목)	부분 성공 (색상 차이 다수 누락)
3	Frame 1171280278 (17:3403)	43	실제 디자인 (사진, 3D지형, 자유배치)	미시도 (구조 분석 한계)

1.2 발견된 누락 사항 (시간순)

#	누락	원인	Figma 필드
1	평행사변형 우측 상단 Bezier curve	vectorNetwork.vertices만 봄, fillGeometry.path의 C 명령어 미확인	fillGeometry[].path
2	그라디언트 바 우측 pill-shape	cornerRadius 단일값만 체크	rectangleCornerRadii (예: [0,40,40,0])
3	S/W 그라디언트 바 색상 (크림→주황)	H/W 바 색상을 S/W에도 일괄 적용	fills[].gradientStops — 인스턴스별 확인 필요
4	S/W 아이콘 색상 (주황 vs H/W 올리브)	같은 imageRef라고 동일 취급	fills[].filters (tint, highlights, shadows)
5	텍스트 위치 오류, 겹침	149노드를 플랫하게 absolute 배치	트리 계층 무시가 근본 원인

---

2. 근본 원인 분석

2.1 작업 방식의 문제

현재 방식:
  curl API → 3.6MB JSON 덤프 → 임시 Python 스크립트로 파싱
  → 필요해 보이는 필드만 선택적으로 읽음
  → 좌표를 눈으로 읽고 HTML에 하드코딩
  → 사용자 지적 → 수정 → 또 지적 → 또 수정...

문제:
  1. 임시 스크립트가 매번 다르고, 추출 범위가 일정하지 않음
  2. "중요해 보이는" 필드만 골라 읽으니 형상/필터/개별반지름 등을 놓침
  3. 같은 패턴 반복 요소의 속성 차이를 대조하지 않음
  4. 트리 계층을 무시하고 플랫하게 절대좌표 배치
  5. 전체를 한번에 만들어서 오류 발견이 늦음

2.2 "배치 우선" 편향

AI의 파싱 우선순위 (잘못됨):
  1. 어디에 있나 (x, y, width, height)     ← 먼저 봄
  2. 무슨 색이나 (fills, color)             ← 그다음
  3. 무슨 글자나 (characters, fontSize)     ← 그다음
  4. 어떤 모양이나 (path, cornerRadius)     ← 마지막... 놓침
  5. 인스턴스 간 차이 (filters, gradient)   ← 아예 안 봄

디자인에서는 4, 5가 핵심임

---

3. FIGMA-EXTRACTION.md 보강 필요 사항

기존 MD는 유지. 아래 항목들은 방향 확정 후 반영.

3.1 섹션 2.4 "추출해야 하는 핵심 데이터" 추가 필드

추가 필드	용도
rectangleCornerRadii	꼭짓점별 다른 반지름 (예: [0,40,40,0] = 우측만 둥글게)
fillGeometry[].path	SVG path에 C/Q 곡선 명령어가 있으면 직선이 아닌 형상
arcData	호/부채꼴 형상
fills[].filters	같은 이미지라도 노드별 필터(tint, highlights, shadows)로 색상 변경

3.2 워크플로우 개선 방향 (미확정)

소분 → 단계적 조립:

한번에 전체를 만들지 않는다.

트리 leaf부터 올라감:
  → leaf 변환 (개별 확인)
  → 부모 그룹으로 조립
  → 다음 레벨로 조립
  → 최종 프레임

각 단계에서 반드시:
  - 같은 패턴의 인스턴스끼리 속성 대조
  - 이미지 노드의 filters 확인
  - 텍스트 겹침 없는지 좌표 간격 확인

단, Figma 트리가 깔끔한 건 사용자가 수작업으로 정리했기 때문. 원본 Figma는 자동 이름 + 의미 없는 중첩이 겹겹이 있는 상태. → AI가 뒤죽박죽인 구조를 정확히 읽으려면 Figma MCP 활용이 필수.

---

4. 다음 세션에서 이어갈 것

4.1 Figma MCP 테스트

• 작업 디렉토리를 D:\ad-hoc\kei\design_agent\로 열어야 .mcp.json의 Figma MCP가 인식됨
• 현재 세션은 D:\에서 열려서 MCP 미인식
• API 키는 업데이트 완료: figd_-eLtFZz5itRec7N60iJFB1njw1nKH8T_X_PM205T

4.2 테스트 대상

Figma URL: https://www.figma.com/design/9S6LsQyO6zlRxtiqZccOUM/Untitled?node-id=18-8204
대상: Frame 1171281172
목표: MCP로 구조를 읽고 → HTML로 변환 → 정확도 확인

4.3 검증 포인트

• MCP가 트리 구조를 계층적으로 탐색할 수 있는지
• 노드별 시각 속성 (fills, filters, gradientStops, cornerRadii 등)을 빠짐없이 읽는지
• 읽은 결과를 기반으로 소분→조립 방식으로 HTML 변환이 가능한지

4.4 성공 기준

MCP 기반으로 변환했을 때, 사용자가 지적하기 전에 다음을 스스로 잡아낼 수 있어야 함:

• 둥근 모서리 / 곡선 형상
• 인스턴스별 색상 차이 (그라디언트, 필터)
• 텍스트 겹침 / 위치 오류

---

5. 사용자가 공유한 참고 자료

자료	URL	비고
Figma→HTML 플러그인	https://www.figma.com/community/plugin/1421932899298722297	Convert Figma Design to HTML CSS
Hubannero 플러그인	https://www.figma.com/community/plugin/1527963216001787676	Figma to HTML/MP4/GIFs
GitHub Copilot MCP	https://github.com/webmaxru/figma-to-webpage-github-copilot-mcp	Figma→Webpage via MCP
SKT UX MCP	https://github.com/banil-la/figma-mcp-skt-ux	Figma MCP for UX
MCP Market	https://mcpmarket.com/ko/server/figma-to-ai-html-converter	Figma→AI HTML Converter
LobeHub Skills	https://lobehub.com/skills/skill.md	Skill definitions

---

6. 기존 MD와의 관계

문서	역할	상태
FIGMA-DESIGN-LANGUAGE.md	디자인 토큰, 색상, 타이포, 레이아웃 패턴	유지 (변경 없음)
FIGMA-EXTRACTION.md	추출 워크플로우, 수학적 계산, 체크리스트	유지 (보강 예정, 미반영)
FIGMA-CONVERSION-REVIEW.md	이 문서. 테스트 결과, 인사이트, 다음 세션 이어갈 지점	신규