# 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` | **이 문서**. 테스트 결과, 인사이트, 다음 세션 이어갈 지점 | 신규 |