C.E.L_Slide_test2/docs/architecture/IMPROVEMENT-PLAN.md

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단계) ↓
         블록화 시 이 규칙에 맞춰 전환