C.E.L_Slide_test2/figma_to_html_agent/DISCUSSION-SUMMARY-20260411.md

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 업데이트할 것인가?