From 7a2615fb4b8b62c055a1c6fa7d1c0b825870b876 Mon Sep 17 00:00:00 2001
From: kyeongmin <b24009@hanmaceng.co.kr>
Date: Fri, 17 Apr 2026 12:02:51 +0900
Subject: [PATCH] =?UTF-8?q?=EA=B0=9C=EC=84=A0=20=EC=84=A4=EA=B3=84=20?=
 =?UTF-8?q?=EB=AC=B8=EC=84=9C=20=EC=B6=94=EA=B0=80:=20=ED=86=A0=ED=81=B0?=
 =?UTF-8?q?=20=EA=B8=B0=EB=B0=98=20=ED=86=B5=EC=9D=BC=20+=20=EB=B8=94?=
 =?UTF-8?q?=EB=A1=9D=20=EA=B5=AC=EC=A1=B0=20=EB=B6=80=ED=92=88=ED=99=94=20?=
 =?UTF-8?q?+=202=EA=B2=BD=EB=A1=9C=20=ED=8C=8C=EC=9D=B4=ED=94=84=EB=9D=BC?=
 =?UTF-8?q?=EC=9D=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 목표: MDX → BEPs 매칭 → 슬라이드 자동 생성
- 핵심 축: 표현 기준 통일, 블록 역할 재정의, direct-fit/recipe 2경로화
- 6단계 진행 계획: 토큰 → slide-base 분리 → 규칙 문서 → 폴더 정리 → 블록 전환 → 파이프라인 연결
- 역할 분리: figma_to_html_agent(원재료) / design_agent(조립 시스템)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 docs/architecture/IMPROVEMENT-PLAN.md | 157 ++++++++++++++++++++++++++
 1 file changed, 157 insertions(+)
 create mode 100644 docs/architecture/IMPROVEMENT-PLAN.md

diff --git a/docs/architecture/IMPROVEMENT-PLAN.md b/docs/architecture/IMPROVEMENT-PLAN.md
new file mode 100644
index 0000000..5b7d5df
--- /dev/null
+++ b/docs/architecture/IMPROVEMENT-PLAN.md
@@ -0,0 +1,157 @@
+# C.E.L. Slide Pipeline — 개선 설계
+
+## 목표
+
+**MDX 콘텐츠를 넣으면, 중목차/소목차 기준으로 BEPs 디자인과 매칭하여 슬라이드를 자동 생성한다.**
+
+현재는 블록마다 스타일이 제각각이고, 매칭/조립/크기 조정이 불완전하여 수작업 보정이 필요한 상태. 이를 토큰 기반 통일 + 블록 구조 부품화 + 파이프라인 2경로화로 개선한다.
+
+---
+
+## 개선 방향
+
+| 현재 문제 | 개선 방향 |
+|-----------|-----------|
+| 블록마다 폰트/색/여백이 직접 박혀있어 통일 안 됨 | 토큰으로 공통 기준 확정, 블록은 변수 참조 |
+| slide-base에 구조+스타일이 섞여있음 | 프레임(HTML)과 스타일(CSS) 분리 |
+| 블록이 완성 HTML이라 재사용/조합이 어려움 | 블록 = 구조 부품, 스타일은 테마로 분리 |
+| 블록 매칭이 파일명/tag 중심 | 속성 테이블(catalog) 기반 매칭 |
+| 크기 조정이 1회 렌더로 끝남 | 입력→조정 반복 (빈 공간/overflow 자동 재분배) |
+| 검증이 overflow만 | 시각 품질까지 검증 (정렬, 위계, 가독성) |
+
+---
+
+## 핵심 축 3개
+
+### 1. 표현 기준 통일
+
+typography, spacing, colors, layout을 토큰으로 확정하여 모든 블록이 이 공통 기준을 따르게 한다.
+
+### 2. 블록의 역할 재정의
+
+블록 = 완성 HTML이 아니라 **구조 부품**. 구조 스타일(flex, grid)은 블록에, 직접값(font-size, color)은 토큰으로 분리한다.
+
+### 3. 파이프라인 2경로화
+
+- **direct-fit:** BEPs 매칭 → 블록 삽입 + 크기 조절
+- **recipe/composition:** 미매칭 → 꼭지 정리 → redesign + 반복 조정
+
+---
+
+## 실행 원칙
+
+**direct-fit 기준:**
+direct-fit은 구조, 슬롯, 시각 위계가 기존 블록과 거의 1:1로 대응될 때만 허용한다.
+
+**recipe-path 목적:**
+recipe/composition 경로는 미매칭 콘텐츠를 새로운 구조로 재정리하되, 기존 visual language를 최대한 상속한다.
+
+**fit 루프 우선순위:**
+fit 조정은 줄바꿈 → 간격 조정 → preview 축약 → 폰트 1단계 축소 순으로 수행한다.
+
+---
+
+## 진행 계획
+
+### 1단계: 토큰 기준 확정
+
+**목표:** 모든 블록이 따라야 할 공통 기준표 확정
+
+| 토큰 | 내용 |
+|------|------|
+| typography | 대목차/중목차/소목차/본문/캡션/footer 크기·굵기·줄간격 |
+| spacing | padding/gap/indent/margin |
+| colors 1층 | 공통 테마색 (title, body, border, card-bg, accent) |
+| colors 2층 | 블록 의미색 (compare-left/right, role-a/b, pill-left/right) |
+| layout | slide-base 위치값 (body-top, body-height, footer-bottom) |
+
+### 2단계: slide-base CSS 분리
+
+**목표:** slide-base를 프레임 전용으로 얇게
+
+- HTML에서 `<style>` 추출 → 외부 CSS
+- 직접값 → 토큰 변수로 교체
+- slide-base = 대목차 + divider + body container + footer만 책임
+
+### 3단계: 블록 작성 규칙 문서
+
+**목표:** 블록화 시 참조할 기준 제공 (두 에이전트 간 계약서)
+
+- 구조 스타일 OK (display:flex, grid, align-items, overflow)
+- 직접값 금지 (hardcoded font-size/color/padding)
+- 값은 토큰 참조 (`var(--font-body)`)
+- 클래스명 규칙 (`.zone-title`, `.bul` 등)
+- 슬롯 규칙 (zone_title, sub_title, body, bullets, image 등)
+
+### 4단계: 폴더 구조 정리
+
+**목표:** 프레임/구조/스타일/메타/자산 분리
+
+```
+templates/
+├── base/           ← 프레임 (slide-base)
+├── blocks/
+│   ├── structures/ ← 구조 부품 (토큰 기반)
+│   ├── recipes/    ← 조합형 구조
+│   └── legacy/     ← 기존 블록 (점진 전환)
+├── styles/
+│   ├── tokens/     ← 공통 기준값
+│   ├── themes/     ← 톤 변형 (light/dark/formal)
+│   ├── base/       ← slide-base CSS
+│   └── blocks/     ← 블록별 CSS
+├── assets/         ← 이미지/SVG/텍스처
+└── catalog/        ← 속성 테이블 (blocks/recipes/rules)
+```
+
+### 5단계: 기존 블록 점진 전환
+
+**목표:** Figma 1:1 HTML → 토큰 기반 재사용 블록으로 전환
+
+**5-1. 블록 분류 먼저**
+
+| 분류 | 의미 | 전환 순서 |
+|------|------|-----------|
+| direct-fit candidate | 바로 사용 가능 | 먼저 (토큰 교체만) |
+| recipe component candidate | 조합용 부품 | 다음 |
+| rewrite required | 구조부터 다시 | 마지막 |
+
+**5-2. 분류 결과에 따라 전환**
+- `figma_to_html_agent/blocks/` 완료물을
+- 토큰 기준에 맞춰 `templates/blocks/structures/`로
+- 한 번에 다 뜯지 않고 점진적으로
+
+### 6단계: 파이프라인 연결
+
+**목표:** TO-BE 프로세스 완성
+
+- TF-IDF 기반 **direct-fit block 매칭**
+- 미매칭 시 **recipe/composition 경로 전환**
+- 토큰 기반 resize
+- 입력→조정 반복 (fit 루프 확장)
+- 시각 품질 검증 강화
+
+**Source of Truth:**
+
+| 기준 | 위치 |
+|------|------|
+| 구조 판정 | `normalized.sections` |
+| 블록 매칭 | `catalog/blocks.yaml` |
+| 스타일 기준 | `styles/tokens/` + `styles/themes/` |
+
+---
+
+## 역할 분리 (동시 진행)
+
+```
+figma_to_html_agent (원재료)     design_agent (조립 시스템)
+─────────────────────          ──────────────────────
+"이 블록은 무엇인가"              "이 블록을 언제 쓸까"
+구조 유형 발견                    토큰 기준 확정
+슬롯 정의                        catalog 필드 설계
+자산 메타                        direct-fit vs recipe 규칙
+seam/crop/anchor                 theme/token 적용
+                                 fit/validation
+
+         ↓ 접점: 블록 작성 규칙 문서 (3단계) ↓
+         블록화 시 이 규칙에 맞춰 전환
+```