# 변환 절차 (10 STEP)

Figma 프레임 1개를 HTML+template으로 변환할 때 매번 동일하게 따르는 운영 핸드북.

> **원칙: 같은 세션에서 여러 프레임 연속 작업 OK.** 컨텍스트가 무거워지면 `/compact` 로 정리하고 계속 진행. 핵심 결정/규칙/산출물은 모두 파일에 박혀있어 compact 후에도 보존됨. 이렇게 해야 누적 학습(R13 등 sub-pattern)이 즉시 적용됨. CLAUDE.md 원칙 7 참조.

> **원칙: 1 프레임 변환 = 1:1 reference + 템플릿 동시 작성.** 1번째 등장이라도 templates_staging/{pattern}.html.j2 + meta.yaml + example.yaml 까지 작성한다. 정적 HTML만 두는 것은 work-creating-work. 사용자가 final 검수 후 design_agent/templates/ 로 직접 프로모션.

---

## STEP 0 — 준비

### 0-A. 에이전트: blocks_index.md 한 번 읽기 (필수)

새 세션은 메모리가 없다. 패턴 발견 트리거(2번째 등장)가 작동하려면 **세션 시작 직후** [blocks_index.md](blocks_index.md)를 한 번 통으로 읽어야 한다.

```
Read figma_to_html_agent/blocks_index.md
```

확인할 것:
- "변환 완료 (현행 방법론)" 섹션의 패턴 목록
- "패턴 카탈로그" 섹션의 등록 패턴 (등장 횟수)
- "templates_staging 대기열" 의 진행 중 패턴

### 0-B. 사용자: 프레임 선택

1. Figma desktop에서 변환할 프레임을 **선택** (클릭) 한다
2. 에이전트에게 "이 프레임 변환해줘"라고 알린다 (프레임 ID/이름 명시 권장)

### 0-C. 에이전트: 패턴 비교

STEP 1~3로 metadata + screenshot 받은 직후, 0-A에서 본 인덱스와 비교:

- 비슷한 구조 발견 → "이거 X 패턴과 비슷합니다. 두 번째 등장이면 templates_staging/ 로 Jinja2 추출 진행할까요?" 사용자에게 확인
- 비슷한 게 없음 → 일반 STEP 4 이하 진행

**확인사항:**
- Figma desktop 앱이 활성 탭에 올바른 파일이 떠 있는가
- `.mcp.json`에 figma-desktop SSE 서버가 등록돼있는가 (`http://127.0.0.1:3845/sse`)

---

## STEP 1~3 — 데이터 수집 (병렬)

세 도구를 **단일 메시지에 multiple tool_use 블록**으로 동시 호출한다 (도구 호출 단위 병렬). 순차 호출하면 같은 노드 ID를 두 번 추출하느라 토큰만 낭비됨.

```
[single message, multiple tool_use blocks]
1. mcp__figma-desktop__get_metadata        nodeId="" (현재 선택 노드)
2. mcp__figma-desktop__get_design_context  nodeId="" (현재 선택 노드)
3. mcp__figma-desktop__get_screenshot      nodeId="" (현재 선택 노드)
```

**주의:** nodeId를 비우면 현재 선택 노드를 사용하므로 metadata 응답을 기다릴 필요 없음. 셋 다 동시에 갈 수 있다.

| 도구 | 얻는 것 | 사용처 |
|------|--------|-------|
| get_metadata | 모든 leaf 노드의 `id, type, name, x, y, width, height` (XML) | bottom-up 플래튼 |
| get_design_context | gradient/filter/font/color (React+Tailwind 코드) | CSS 변환 |
| get_screenshot | Figma가 렌더한 PNG | STEP 8 사람 눈 검증 |

**주의:**
- get_metadata 응답이 100KB+ 면 frame이 너무 커서 자르지 않은 상태. 사용자에게 더 작은 단위 선택 요청
- get_design_context는 응답이 매우 크므로 한 프레임당 1회만 호출

---

## STEP 4 — 자산 정리 (block-tests/assets/shared/ 캐시)

design_context에서 `localhost:3845/assets/{hash}.png|svg` 패턴의 자산 URL 추출.

각 자산에 대해:
1. URL 끝의 hash를 파일명으로 사용
2. `block-tests/assets/shared/{hash}.{ext}` 가 **이미 있으면 다운로드 스킵**
3. 없으면 curl로 다운로드

```bash
cd block-tests/assets/shared
for url in $URLS; do
  hash=$(basename "$url")
  [ -f "$hash" ] || curl -sSo "$hash" "$url"
done
```

HTML에서 참조 시:
```html
<img src="assets/shared/{hash}.png">
```

(`block-tests/{slug}.html` 기준으로 상대 경로 `assets/shared/`)

**효과:**
- 동일 자산이 여러 프레임에서 등장해도 한 번만 다운로드 (해시 파일명이라 자동 dedup)
- 후속 프레임 변환 시간 단축
- 토큰 절약 (이미 있는지 확인만)

**프레임 매핑 메모:** `block-tests/{slug}_assets.txt`에 사용한 hash 목록 + 의미 라벨 기록 → 추후 재추출 시 빠른 매핑

```
# bim-goals-3circles_assets.txt
84965807....png   bg_texture
f05ebf15....png   arc_top
2f0f1750....png   arc_side
```

**legacy:** 이전에 다운로드한 자산이 `block-tests/assets/frame_{id}/` 에 있다면 그대로 두되, 새 변환부터는 `shared/` 만 사용한다.

---

## STEP 5 — flat.md 작성 (분석 + 이상 탐지)

`block-tests/{slug}_flat.md` 파일 생성. 다음 섹션을 반드시 포함:

### 섹션 1. 메타
```markdown
# Frame {ID} — {이름}

> 원본: {W} × {H} px (node {ID})
> Scale: × {S} → {1280} × {H×S} px
> 슬라이드 16:9 안 배치
```

### 섹션 2. 계층 경로 (bottom-up)

모든 leaf 노드를 들여쓰기 트리로 표현. 그룹별 누적 offset 표시.

```
Frame {root} ({W}×{H})
├─ Group "X" (offset → 누적)
│   ├─ TEXT "..." (abs_x, abs_y) {w}×{h}
│   └─ ...
```

### 섹션 3. 이상 탐지 결과

| 검사 | 결과 |
|------|------|
| 회전 단일문자 (bbox 가로 > 세로 × 1.5) | 발견 노드 ID 또는 "없음" |
| 좁은 박스 세로 텍스트 (width < fontSize × 0.8) | ... |
| 중복 노드 (동일 좌표 + 동일 내용) | ... |
| Vector 좌표 metadata vs design_context 불일치 | ... (있으면 어느 쪽 신뢰) |

### 섹션 4. 변형 가능 축 메모 + 슬롯 옵션

이 블록을 템플릿화한다면 무엇이 파라미터가 될지 1~5줄로. **각 슬롯이 required인지 optional인지 표시**:

```markdown
## 변형 가능 축
- columns[N=2~4] (required)
  - badge (required)
  - bullet_items[1~12] (required)
  - bg_image (required)
  - bottom_photo (optional)  ← 사진 없는 mdx도 이 블록 매칭 가능
- color_palette[N] (required, N과 일치)
```

이 메모가 STEP 10의 `blocks_index.md` 요약 + 향후 templates_staging meta.yaml 의 초안.

### 섹션 5. Sub-pattern 식별 (재사용 가능한 atomic 단위)

이 블록 안에 **다른 블록과 공유 가능한 sub-pattern**이 있는가? RULES.md R13~ 참조.

```markdown
## Sub-patterns
- `bullet-list-with-marker` (R13) — 각 텍스트 앞에 장식 마커
  - 위치: 각 컬럼 본문 영역
  - 마커: checkbox PNG
  - 적용 구조: .bullet-list / .bullet-row / .bullet-icon / .bullet-text
```

Sub-pattern을 **즉시 RULES.md에 등록할 필요는 없다**. 동일 sub-pattern이 2번째 등장하면 그때 R번호 부여해서 정식 등록.

---

## STEP 6 — 그라데이션 수학 변환

각 SVG `<linearGradient>` 데이터를 [scripts/gradient_math.py](scripts/gradient_math.py)로 CSS로 변환.

```bash
python scripts/gradient_math.py \
  --w 350 --h 350 \
  --x1 110.833 --y1 18.2292 --x2 219.479 --y2 175 \
  --stops "0:#FDC69E,1:#E0782C"
```

출력:
```
linear-gradient(145.28deg, #FDC69E 16.04%, #E0782C 55.20%)
```

수학 원리는 [MATH.md §2 참조](MATH.md).

**여러 그라데이션을 한 번에 변환할 땐 Python 인라인 스크립트 사용:**

```python
import sys, os
# scripts/ 디렉토리를 sys.path에 명시 추가 (작업 디렉토리 무관)
sys.path.insert(0, os.path.join('figma_to_html_agent', 'scripts'))
from gradient_math import svg_to_css

svg_to_css(W=350, H=350, x1=110.833, y1=18.2292, x2=219.479, y2=175,
           stops=[(0, '#FDC69E'), (1, '#E0782C')])
```

**작업 디렉토리가 `figma_to_html_agent/` 인 경우:**
```python
import sys; sys.path.insert(0, 'scripts')
from gradient_math import svg_to_css
```

**또는 정식 패키지로 사용** (`scripts/__init__.py` 가 있으므로):
```python
# 작업 디렉토리가 figma_to_html_agent/ 일 때
from scripts.gradient_math import svg_to_css
```

⚠️ **금지: 함수 코드를 인라인 Python에 복사 붙여넣기**. 한 번 만든 `gradient_math.py`를 항상 import해서 쓴다. 복사하면 버그 수정 시 여러 곳을 동시에 고쳐야 하고 수식이 미세하게 어긋날 위험.

---

## STEP 7 — HTML 작성

### 7-A. 기본 구조

```html
<div class="slide">             <!-- 1280×720 흰색 -->
  <div class="block">           <!-- 1280 × (H×S) -->
    <div class="inner">         <!-- 원본 W×H, transform: scale(S) -->
      ... 모든 요소 (Figma 원본 좌표 사용) ...
    </div>
  </div>
</div>
```

```css
.inner {
  position: absolute;
  left: 0; top: 0;
  width: {W}px; height: {H}px;
  transform: scale({S});
  transform-origin: top left;
}
```

**왜 transform: scale을 쓰는가:** 모든 위치/크기/폰트/그림자/스트로크가 한 번의 transform으로 균일하게 축소됨. 매 값을 수동으로 ×S 곱하는 것보다 안전하고 검증 가능. ([MATH.md §1](MATH.md))

### 7-B. 요소 변환 우선순위

| 요소 종류 | 구현 방법 | 이유 |
|---------|---------|-----|
| 원/사각형 + gradient + blend | **HTML div** + `border-radius` + `linear-gradient` + `mix-blend-mode: multiply` | 동적 재구성 위해 |
| Stroke (경계선) | `border: Npx solid color` + `box-sizing: border-box` | gradient와 함께 사용 가능 |
| Drop shadow blur | `box-shadow: 0 0 {2×stdDev}px {color}` | SVG feGaussianBlur 근사 |
| 곡선 (아크, 비원형) | **SVG `<path>`** 또는 미리 export된 PNG | CSS 불가능 |
| 텍스트 | HTML `<div>` 절대 배치 | 선택 가능, 접근성 |
| 실사 이미지 | `<img>` PNG | 재현 불가 |
| 회전된 도형 | 래퍼 div + `transform: rotate()` ([INSIGHT-GRADIENT.md](INSIGHT-GRADIENT.md)) | gradient 동시 회전 |

### 7-C. 보정 규칙

[RULES.md](RULES.md) R1~R16 모두 적용:
- R1: descender padding-bottom
- R2~R3: 회전/세로 텍스트
- R4: 그라데이션 텍스트
- R5: 다중 fills
- R6: 중복 노드
- R7: 흰 배경
- R8: 스케일 팩터
- R9: 순수 CSS 우선
- R10: blend mode 호환
- R11: stroke 정렬 (inside/outside)
- R12: viewBox padding

---

## STEP 8 — Selenium 렌더링 + 사람 눈 검증

```python
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from PIL import Image
import os, time

# _renders/ 폴더 없으면 생성
os.makedirs('block-tests/_renders', exist_ok=True)

opts = Options()
opts.add_argument('--headless=new')
opts.add_argument('--hide-scrollbars')
opts.add_argument('--force-device-scale-factor=1')
opts.add_argument('--window-size=1600,900')
d = webdriver.Chrome(options=opts)

p = os.path.abspath('block-tests/{slug}.html').replace('\\','/')
d.get('file:///' + p)
time.sleep(1.5)
d.save_screenshot('block-tests/_renders/{slug}_full.png')

r = d.execute_script(
  'const r=document.querySelector(".slide").getBoundingClientRect();'
  'return [r.x,r.y,r.width,r.height];'
)
Image.open('block-tests/_renders/{slug}_full.png').crop(
  (int(r[0]), int(r[1]), int(r[0]+r[2]), int(r[1]+r[3]))
).save('block-tests/_renders/{slug}.png')
d.quit()
```

**검증 방식:**
- 자동 픽셀 diff는 하지 않음 (font 렌더 차이로 노이즈만 많음)
- Figma `get_screenshot` 응답과 Selenium 결과를 **사람 눈**으로 비교
- 차이 발견 시 STEP 5~7로 돌아가서 원인 파악 (값 수정 금지)

---

## STEP 9 — 결과물 저장

```
block-tests/
├── {slug}.html              ← 변환물
├── {slug}_flat.md           ← 플래튼/이상/변형 축 메모
└── _renders/
    └── {slug}.png           ← 검증 스크린샷
```

`{slug}` 명명 규칙: 의미 기반 kebab-case (예: `bim-goals-3circles`, `cards-3col-icon`).
프레임 ID는 metadata로 추적 가능하므로 파일명에 넣지 않음.

---

## STEP 10 — blocks_index.md 1줄 업데이트

`blocks_index.md` 끝에 한 줄 추가:

```markdown
| {slug} | {프레임 ID} | {1줄 변형 축 요약} | {날짜} |
```

이 인덱스가 패턴 발견의 단서가 된다. 다음 변환 시작 전에 이 인덱스를 한 번 훑어서 "이미 비슷한 거 했나?" 확인.

---

## 패턴 → 템플릿화 (1번째부터 즉시)

**규칙: 1번째 등장부터 templates_staging 작성. 정적 HTML만 두는 것 금지.**

| 등장 횟수 | 처리 |
|---------|------|
| **1번째** | `block-tests/{slug}.html` (1:1 reference) + `templates_staging/{pattern_id}.html.j2` (Jinja2 + meta.yaml + example.yaml) **함께 작성** |
| 2번째 | 기존 staging 템플릿이 새 데이터로 잘 렌더되는지 확인. 안 되면 템플릿 수정. example 추가. |
| 3번째 이후 | 동일 |

**왜 1번째부터 템플릿화하나?**
- 변환의 목적은 **블록 라이브러리 구축**, 단순 HTML 복제가 아님
- 1:1 단계에서 발견한 인사이트(R13 등)를 즉시 템플릿에 반영해야 잊지 않음
- 사용자가 검수할 때 "이게 블록으로 어떻게 작동할지" 즉시 확인 가능
- 2번째 등장을 기다리면 사용자 수동 복제 작업이 누적됨 (work-creating-work)

**Stage 2 산출물:**
```
templates_staging/
├── {pattern_id}.html.j2     ← Jinja2 템플릿 본체
└── {pattern_id}.meta.yaml   ← when / slots / min_size_px / 변형 축 초안
```

여기까지가 **에이전트 책임의 끝.**

---

## 🚧 프로모션 게이트 (사용자 전용)

> 이 게이트 이후 작업은 **에이전트가 절대 수행하지 않는다.** 모든 design_agent/templates/ 변경은 사용자 본인이 직접 한다.

### 사용자가 수행할 작업

1. **검수**: `templates_staging/{pattern_id}.html.j2` 를 다양한 파라미터로 렌더 테스트
2. **품질 게이트 통과 확인**:
   - [ ] 1:1 변환물과 시각적으로 동일한가
   - [ ] 슬롯 파라미터를 바꿔도 깨지지 않는가 (원 4개, 라벨 0개 등 극단 케이스)
   - [ ] meta.yaml의 when/slots가 design_agent의 다른 블록과 충돌 없는가
3. **이동**: `templates_staging/{pattern_id}.html.j2` → `design_agent/templates/blocks/{category}/`
4. **등록**: `design_agent/templates/catalog.yaml` 에 when/slots/min_size_px 추가
5. **상태 업데이트**: `blocks_index.md` 의 해당 행 상태 → `promoted`

### 에이전트의 역할

- staging 작성까지만
- 사용자 요청 없이 `design_agent/templates/` 를 절대 읽거나 쓰지 않음
- "templates/ 에 옮겨드릴까요?" 같은 제안 금지 (월권)
- 사용자가 명시적으로 "이 staging 결과 검토해줘"라고 요청하면 → staging 폴더 내에서만 검토

---

## 안티 패턴 (하지 말 것)

| ❌ 하지 말 것 | 이유 |
|------------|-----|
| 사전에 인벤토리/지문/군집 단계 | work-creating-work, 패턴은 변환하면서 발견됨 |
| 1번째 등장은 정적 HTML로만 두기 (templates_staging 미작성) | work-creating-work, 인사이트 잊혀짐. 1번째부터 템플릿 작성 |
| 컨텍스트 차면 강제 새 세션 | compact 사용. 핵심 결정은 모두 파일에 박혀있어 손실 없음 |
| Figma 데이터 안 보고 멀티모달 이미지로 추측 | 미묘한 alpha/blend에서 틀림 |
| "여기 1px 어색하니 다른 곳도 같이 바꾸자" | 사용자 피드백만 정확히 반영 |
| 같은 자산을 매번 새로 다운로드 | `block-tests/assets/shared/` 캐시 활용 |
| 그라데이션 각도/색을 눈대중으로 | gradient_math.py로 수학 도출 |
| gradient_math.py 함수 코드 인라인 복사 | import만 한다. 복사하면 수식 어긋남 |
| 세션 시작에 blocks_index.md 안 읽음 | 패턴 발견 트리거 영영 작동 안 함 |
| `design_agent/templates/` 직접 수정 | 프로모션은 사용자 전용. 에이전트는 staging까지만 |
| "templates/ 옮겨드릴까요?" 제안 | 월권. 사용자가 알아서 함 |
| `prerequisites-3col.html` 을 신규 변환 레퍼런스로 사용 | 구 방법론 (R8/R9 미적용). legacy 표시됨 |