# Design Agent 구조 재정리를 위한 논의 요약 (2026-04-11)

> 이 문서는 figma_to_html_agent 세션에서 논의된 핵심 사항을 정리한 것.
> design_agent 총괄 AI에게 전달하여 전체 파이프라인 재구성에 참고하기 위한 브리핑.

---

## 1. Figma → HTML 변환 구조

### 1.1 전체 흐름

```
피그마 프레임 (디자인 원본)
    ↓  MCP 도구로 데이터 수집 (구조, 스타일, 스크린샷)
실측 기록부 (flat.md)
    ↓  그라데이션 수학 변환 + CSS 작성
블록 HTML (1:1 정적 변환물)
    ↓  Selenium 자동 검증
블록 라이브러리 등록 (catalog.yaml)
```

### 1.2 산출물 3종 세트

| 파일 | 역할 | 비유 |
|------|------|------|
| **flat.md** | 원본 피그마의 모든 요소 위치·크기·각도·폰트·색상 기록 | 현장 실측 기록부 |
| **{블록}.html** | HTML+CSS+이미지 참조. 실제 렌더되는 파일 | 표준 설계도면 |
| **catalog.yaml** | 블록 용도·조건·슬롯 메타 정보 | 건축 자재 카탈로그 |

### 1.3 AI vs 코드 역할 분담

| 구간 | 주체 | 오차 |
|------|------|------|
| 데이터 수집 (좌표, 색, 폰트) | **코드** (Figma MCP) | 0 |
| 그라데이션 좌표→각도 변환 | **코드** (gradient_math.py) | 0 |
| HTML 렌더링 | **코드** (Selenium) | 0 |
| 구조 해석, HTML 설계, 검증 판단 | **AI** | 존재 |

**핵심:** AI는 블록 템플릿을 **1회 설계**하는 데만 관여. 이후 런타임 사용은 **100% 코드** (Jinja2 + CSS).

---

## 2. 블록 선택 방식 — 결론: TF-IDF 직접 매칭

### 2.1 검토한 방식들

| 방식 | 적합성 | 이유 |
|------|--------|------|
| **FAISS (임베딩 벡터)** | ❌ 불필요 | 35개 블록에 오버스펙. 같은 도메인 텍스트는 벡터가 비슷해서 구분 어려움 |
| **RAG (LLM 판단)** | ❌ 불필요 | 입력이 이미 구조화(MDX)되어 있고 블록 수가 적어 AI 판단 불필요 |
| **BM25 + Kiwi** | ⚠️ 가능 | catalog 설명 품질에 의존. 설명이 잘 되어있으면 작동 |
| **구조 태그 매칭 (코드)** | ✅ 가능 | MDX 파싱 → item_count, relation_type → catalog 태그 비교 |
| **TF-IDF 직접 매칭** | ✅ **최적** | 디자인 안의 실제 텍스트와 MDX 텍스트를 직접 비교 |

### 2.2 TF-IDF 직접 매칭이 최적인 이유

**핵심 전제:** MDX 텍스트와 Figma 디자인 안의 텍스트가 **같은 원본 문서에서 나온 것**이라 핵심 키워드가 자연스럽게 겹침.

```
[1회성 사전 준비]
각 Figma 디자인(35개)에서 텍스트 추출 → 블록별 텍스트 저장

[매칭 실행]
MDX 텍스트 → TF-IDF로 35개 블록 텍스트와 유사도 계산 → 최고 점수 디자인 선택 → 텍스트 교체
```

**장점:**
- AI 비용 0원 (100% 코드)
- 결정론적 (같은 입력 → 같은 결과)
- 35개 전수 비교에 0.01초
- 디버깅 용이 ("이 단어들이 겹쳐서 선택됨" 즉시 설명 가능)
- catalog.yaml 설명 품질에 의존 안 함 (디자인 안의 실제 텍스트로 매칭)
- FAISS, RAG, 임베딩 모델 등 복잡한 인프라 불필요

**실증:** BM25 테스트에서 콘텐츠A(기술/사람/자연)→3열블록, 콘텐츠B(Process/Product)→2열블록 정확 매칭 확인.

### 2.3 이 방식이 성립하는 조건

1. 블록 수가 30~35개 수준 (소규모)
2. 각 디자인의 텍스트가 서로 충분히 다름 (같은 문서 내 다른 섹션)
3. MDX 콘텐츠가 Figma 디자인의 원본 텍스트와 동일 도메인
4. 매칭 후 "텍스트만 업데이트"하는 구조 (디자인 구조 자체는 변경 안 함)

**한계 시점:** 블록이 수백 개가 되거나, 완전히 새로운 도메인 콘텐츠가 들어오면 구조 분석(AI) 또는 임베딩 검색 추가 필요.

---

## 3. 전체 파이프라인 재정리 제안

### 3.1 현재 파이프라인 (복잡)

```
MDX → Kei 실장(AI) 구조분석 → catalog 태그 매칭(코드) → 블록 선택
    → Kei 편집자(AI) 텍스트 편집 → Jinja2 렌더(코드) → 슬라이드
```

### 3.2 단순화된 파이프라인 (제안)

```
MDX → TF-IDF 매칭(코드) → 디자인 선택 → 텍스트 교체(코드) → 슬라이드
```

**AI가 필요한 시점:**
- 매칭 결과가 애매할 때 (점수 차이가 미미한 후보 2~3개 중 선택)
- 텍스트가 디자인 공간에 안 맞을 때 (요약/편집 필요)
- 새로운 패턴의 디자인이 필요할 때 (블록 신규 제작)

**AI가 불필요한 시점:**
- 디자인 선택 (TF-IDF 매칭)
- 텍스트 삽입 (Jinja2 치환)
- 렌더링 (CSS + 브라우저)

### 3.3 블록 선택에서 AI 개입 최소화 구조

```
MDX 텍스트
      ↓
[코드] TF-IDF 매칭 → 후보 1~3개 + 점수
      ↓
점수 차이 크면 (예: 1위가 2위보다 2배 이상) → 코드가 자동 확정
점수 차이 작으면 → AI가 후보 중 최종 선택 (최소 개입)
      ↓
[코드] 텍스트 교체 + 렌더
```

---

## 4. Figma MCP 관련 발견 사항

### 4.1 MCP 2종류

| MCP | 제공자 | 장단점 |
|-----|-------|--------|
| Framelink Figma MCP | 커뮤니티 (REST API) | rotation/blend mode 미제공 |
| Figma Desktop Dev Mode MCP | Figma 공식 (로컬 SSE) | rotation/blend/정확한 CSS 모두 제공 |

**결론:** Figma Desktop Dev Mode MCP (`127.0.0.1:3845/sse`)가 정답. Framelink MCP는 rotation 등 핵심 정보 부재로 한계.

### 4.2 Figma Dev Mode HTML 직접 활용

Figma Dev Mode에서 프레임 전체를 HTML 코드로 export 가능:
- transform: rotate() 포함
- background-blend-mode 포함
- 모든 좌표/크기/색상 포함
- 이 HTML을 기반으로 scale 조정 후 직접 사용 가능

### 4.3 MCP 한계 (확인됨)

- rotation 속성 미제공 (Framelink MCP)
- dimensions가 bounding box (회전 포함된 크기) — 원본 크기와 다를 수 있음
- gradient 각도: Figma 좌표계 vs CSS 좌표계 차이 → 수학 변환 필요

---

## 5. CSS 구현 원칙

### 5.1 왜 SVG가 아닌 CSS인가

| 이유 | 설명 |
|------|------|
| **한글 텍스트** | CSS는 자동 줄바꿈·어절 처리. SVG `<text>`는 수작업 줄바꿈 |
| **레이아웃** | CSS flex/grid/aspect-ratio. SVG는 레이아웃 시스템 없음 |
| **혼합 콘텐츠** | 도형+이미지+텍스트 섞기. HTML이 자연스러움 |
| **템플릿화** | Jinja2 변수 치환이 CSS에서 자연스러움 |
| **예외** | 곡선 아크, 복잡한 필터 → SVG/PNG 유지 |

### 5.2 그라데이션 수학 변환

- SVG: 좌표 기반 (x1, y1, x2, y2)
- CSS: 각도 기반 (Xdeg)
- 변환: `atan2(y2-y1, x2-x1)` → `scripts/gradient_math.py`
- 회전+그라데이션 합성: 래퍼 구조(`transform: rotate()`)로 분리해서 수학 합성 회피

### 5.3 회전 처리

- 도형 자체를 회전하지 않고, **래퍼(wrapper) 컨테이너를 회전**
- border-radius와 gradient가 같이 돌아감
- Figma Dev Mode가 자동으로 이 래퍼 구조를 생성해줌

---

## 6. 핵심 결론

1. **블록 선택은 TF-IDF 직접 매칭으로 충분** — RAG/FAISS 불필요
2. **AI는 "블록 템플릿 1회 제작"에만 관여** — 런타임은 100% 코드
3. **Figma Desktop Dev Mode MCP가 정답** — Framelink MCP는 한계
4. **CSS 우선, SVG는 곡선만** — 한글 텍스트 처리와 템플릿화 때문
5. **복잡한 구조(RAG/임베딩/구조분석)보다 단순한 구조(TF-IDF+코드)가 현재 규모에 최적**

---

## 7. 산출물 구조 확정 (프레임당 4종)

### 7.1 프레임별 산출물

```
figma_to_html_agent/
├── CLAUDE.md, PROCESS.md, RULES.md ...  ← 프로세스 문서
├── scripts/gradient_math.py              ← 수학 변환
├── blocks_index.md                       ← 변환 완료 인덱스
│
├── block-tests/                          ← 프레임별 산출물
│   ├── {slug}.html                       ← ① HTML 블록
│   ├── {slug}_flat.md                    ← ② 노드별 실측 기록
│   └── {slug}_texts.md                   ← ③ 텍스트만 모은 목록 (TF-IDF용, 신규)
│
└── texts_index/                          ← TF-IDF 매칭 인덱스 (신규)
    └── (35개 프레임 텍스트 인덱스)
```

- ①②는 기존 프로세스
- ③은 신규: 프레임 안의 **모든 텍스트를 빠짐없이** 추출해서 별도 목록으로 저장
- texts_index/는 ③들을 모아 TF-IDF 인덱스로 구축

### 7.2 ③ texts.md가 필요한 이유

현재 flat.md의 문제:
- 텍스트가 노드 계층 설명 안에 **산발적으로 흩어져** 있음
- 일부 노드는 텍스트 내용이 **생략**됨 (예: `17:1941 ~ 17:1952 (12개)`)
- TF-IDF 매칭용으로 쓰려면 프레임별 **텍스트만 모은 깨끗한 목록** 필요

### 7.3 산출물의 사용처

```
① {slug}.html      → templates/에 프로모션 (블록 렌더링용)
② {slug}_flat.md   → yaml 메타 정보 + HTML 제작 근거
③ {slug}_texts.md  → TF-IDF 인덱스 (블록 자동 선택용)
```

---

## 8. TF-IDF 선택 근거 (왜 다른 유사도 방법이 아닌가)

### 8.1 매칭 신호 = "단어 겹침"

MDX와 Figma 텍스트는 같은 원본 문서에서 나온 것이라 **같은 단어가 직접 겹침**.
의미 추론이 아니라 단어 일치가 매칭 근거.

### 8.2 IDF의 역할

```
"건설" → 35개 프레임 전부에 등장 → IDF 낮음 → 구분 못 함
"3D모델" → 3개 프레임에만 → IDF 높음 → 구분 가능
"Copy&Paste" → 1개 프레임에만 → IDF 매우 높음 → 확정적
```

"모든 프레임에 나오는 흔한 단어는 무시, 특정 프레임에만 나오는 희귀 단어는 강조"

### 8.3 다른 방법이 안 맞는 이유

| 방법 | 문제 |
|------|------|
| FAISS/임베딩 | 같은 도메인 단어를 **뭉개서** 프레임 구분 못 함. "병렬"≈"교차"로 취급 |
| RAG | 35개에 AI 판단은 오버스펙. 비용 발생 |
| Jaccard | 단어 희귀성 무시. "건설"이든 "Copy&Paste"든 동일 1점 |
| Word2Vec/BERT | 의미 유사도는 불필요 (단어가 직접 겹치므로). 한국어 도메인 모델 품질 불확실 |
| BM25 | 가능하지만 35개 수준에서 TF-IDF와 차이 없음. TF-IDF가 더 단순 |

---

## 9. 정리 완료 현황 (2026-04-16)

### 9.1 templates/ (완료)

```
templates/
├── blocks/
│   └── slide-base.html    ← 유일하게 남긴 것
└── catalog.yaml           ← 초기화
```

기존 104개 파일 삭제 완료.

### 9.2 figma_to_html_agent/ (완료)

```
figma_to_html_agent/
├── CLAUDE.md, PROCESS.md, MATH.md, RULES.md, PROCESS-CONTROL.md, README.md
├── DISCUSSION-SUMMARY-20260411.md
├── INSIGHT-GRADIENT.md
├── blocks_index.md
└── scripts/gradient_math.py
```

구 파일(FIGMA-EXTRACTION.md, block_index.faiss, figma_beps_full.json, block-tests/, figma-analysis/ 등) 전부 삭제 완료.

### 9.3 다음 단계

깨끗한 상태에서 35개 프레임을 1개씩 재추출:
1. Figma Desktop MCP 또는 Dev Mode HTML로 데이터 수집
2. 프레임당 3종 산출물 생성 (html + flat.md + texts.md)
3. texts_index/ 에 TF-IDF 인덱스 누적
4. templates/에 프로모션 (사용자 승인 후)

---

## 10. design_agent 총괄에게 전달할 질문/제안

1. **Phase Q 블록 선택 단계**를 TF-IDF 직접 매칭으로 단순화할 수 있는가?
2. **Kei 실장의 "구조 분석" 역할**이 TF-IDF 매칭으로 대체 가능한 범위는?
3. **catalog.yaml의 content_structure/when/not_for 필드**를 유지하되, 1차 매칭은 TF-IDF로 하고 AI는 fallback으로만 쓰는 구조가 합리적인가?
4. **Figma Desktop Dev Mode MCP**를 PROCESS.md STEP 1~3에 공식 반영할 것인가?
5. **산출물 3종 → 4종 (texts.md 추가)** 으로 PROCESS.md 업데이트할 것인가?