C.E.L_Slide_test2/README.md

C.E.L. Slide Pipeline

MDX 기반 콘텐츠를 분석하여 1280×720 슬라이드 HTML로 자동 변환하는 파이프라인입니다.

한 줄 요약

텍스트 콘텐츠를 넣으면, 코드가 구조를 분석하고 디자인을 입혀서 슬라이드로 만들어줍니다.

---

현재 프로세스 (AS-IS)

1. MDX 입력
   - MDX 파일 읽기
   - 정규화 (제목/본문/이미지/표/핵심요약 분리)

2. 꼭지 추출 (AI)
   - 중목차별 핵심 주제 파악
   - 각 꼭지의 성격 분류

3. zone 구분 (코드)
   - 중목차(##) 기준으로 영역 분할 (top/bottom)
   - 콘텐츠 양 기준으로 비중(weight) 산출

4. BEPs 디자인 매칭 (코드)
   - catalog에서 tag/schema 기준으로 블록 검색
   - 매칭되면 → 해당 블록에 콘텐츠 삽입
   - 미매칭이면 → 기존 스타일 따라 코드가 고정 렌더 (1회)

5. 조립 (코드)
   - slide-base(1280×720)에 zone별 배치
   - 상세 내용은 첨부 파일로 분리

6. 검증
   - overflow 측정 (Selenium)
   - 구조 검증 (본문 visible, 링크 수)

7. 출력
   - final.html + 첨부 HTML

현재 수준

대상	상태
MDX 03 (3개 목표 + 비교표)	✅ 정상 동작
MDX 02 (목표 + 프로세스 + 상세표)	△ 구조 동작, 시각 품질 보정 중

---

개선 프로세스 (TO-BE)

1. MDX 입력
   - MDX 파일 읽기
   - 정규화 (제목/본문/이미지/표/핵심요약 분리)

2. zone 구분 (코드)
   - 중목차(##) 기준으로 영역 분할

3. BEPs 디자인 매칭 검토
   3-1. 매칭 시 (direct-fit)
        - 해당 디자인 선택
        - zone 크기에 맞게 재구성
   3-2. 미매칭 시 (recipe/composition)
        - 중목차에 대한 꼭지 정리 (AI)
        - 꼭지별 유사 디자인 선택
        - 해당 중목차/소목차에 맞게 redesign
        - 입력 → 조정 반복 (빈 공간/overflow 자동 조절)

4. 검증
   - overflow / 빈 공간 측정
   - 시각 품질 검증 (정렬, 위계, 가독성)

5. 출력
   - final.html + 첨부 HTML

AS-IS → TO-BE 핵심 차이

항목	AS-IS	TO-BE
꼭지 추출 시점	zone 구분 전에 항상 실행	미매칭 시에만 (3-2)
디자인 미매칭	코드 고정 렌더 1회	redesign + 반복 조정
빈 공간 처리	그냥 둠	자동 재분배
검증	overflow만	시각 품질까지
스타일 관리	블록마다 직접값	토큰 기반 통일
블록 역할	완성 HTML	구조 부품 (스타일 분리)

실행 원칙

• direct-fit 기준: 구조, 슬롯, 시각 위계가 기존 블록과 거의 1:1로 대응될 때만 허용
• recipe-path 목적: 미매칭 콘텐츠를 새로운 구조로 재정리하되, 기존 visual language를 최대한 상속
• fit 루프 우선순위: 줄바꿈 → 간격 조정 → preview 축약 → 폰트 1단계 축소

---

핵심 원칙

원칙	설명
콘텐츠가 기준	디자인이 콘텐츠에 맞춤 (콘텐츠를 디자인에 맞추지 않음)
코드가 판단	AI는 꼭지 추출만, 레이아웃/디자인 선택은 규칙 기반
기존 디자인 재활용	Figma에서 추출한 BEPs 블록을 우선 활용, 없으면 같은 스타일로 생성
넘치면 분리	슬라이드에 안 들어가는 상세 내용은 첨부로 분리 (자세히보기)
통일이 아닌 다양성	같은 구조라도 콘텐츠에 따라 다른 표현 가능

---

토큰 기반 CSS 체계

블록마다 스타일이 제각각인 문제를 해결하기 위해, 공통 기준값을 토큰으로 관리합니다.

2층 구조

1층: Global Hierarchy Tokens (모든 블록 공통)
  typography — 대목차/중목차/소목차/본문/캡션/footer
  spacing    — padding/gap/indent/margin
  colors     — 제목/본문/배경/보더/강조

2층: Component Semantic Tokens (블록 역할별)
  body-strong, detail-link, pill-label,
  table-header, compare-badge, callout 등

글자 위계 (typography)

위계	토큰	font-size	font-weight
대목차	--font-slide-title	22px	700
중목차	--font-zone-title	13px	700
소목차	--font-sub-title	12px	700
본문	--font-body	11px	500
캡션	--font-caption	10px	400
footer	--font-footer	20px	700

블록 작성 규칙

• 구조 스타일 OK: display:flex, grid, align-items, overflow
• 직접값 금지: font-size: 11px, color: #475569 직접 박지 않음
• 토큰 참조: font-size: var(--font-body), color: var(--color-body)

상세: BLOCK-RULES.md

---

프로젝트 구조

파이프라인 핵심

파일	역할
src/pipeline.py	전체 파이프라인 오케스트레이션
src/section_parser.py	중목차 추출, schema 분류, subsection typing
src/block_reference.py	BEPs 디자인 매칭 (catalog 검색)
src/block_assembler.py	슬라이드 HTML 조립, recipe executor, direct render
src/space_allocator.py	zone 크기/비율 계산
src/pipeline_context.py	파이프라인 데이터 모델 (PopupItem 등)

템플릿

경로	역할
templates/blocks/slide-base.html	슬라이드 프레임 (구조만, 스타일은 외부 CSS)
templates/blocks/new/	Figma 추출 블록
templates/blocks/redesign/	재디자인 블록
templates/catalog.yaml	BEPs 블록 메타 (when/slots/template)

스타일 (토큰 기반)

templates/styles/
├── tokens/
│   ├── typography.css   ← 글자 위계 (35변수)
│   ├── spacing.css      ← 여백/간격 (28변수)
│   └── colors.css       ← 색상 2층 (41변수)
├── themes/              ← 톤 변형 (light/dark/formal) — 예정
├── base/
│   └── slide-base.css   ← slide-base 스타일 (토큰 참조, 직접값 0)
└── blocks/              ← 블록별 CSS — 예정

CSS 로딩 순서: tokens → base → blocks → themes

검증

파일	역할
src/slide_measurer.py	Selenium overflow 측정
src/step_visualizer.py	단계별 디버그 보드 생성
src/validators.py	구조 검증

산출물

각 실행은 data/runs/{run_id}/ 아래에 저장됩니다.

파일	내용
final.html	최종 슬라이드
final_context.json	전체 파이프라인 결과 데이터
steps/*.html	단계별 디버그 보드
첨부*_상세*.html	popup 상세 내용

설계 문서

문서	내용
IMPROVEMENT-PLAN.md	개선 설계 (목표/방향/6단계 계획)
TOKENS-v1.md	토큰 위계 기준표 초안
BLOCK-RULES.md	블록 작성 규칙 (에이전트 간 계약서)

---

Source of Truth

기준	위치
구조 판정	normalized.sections
블록 매칭	catalog/blocks.yaml (예정, 현재 catalog.yaml)
스타일 기준	styles/tokens/ + styles/themes/

---

역할 분리 (동시 진행)

figma_to_html_agent (원재료)     design_agent (조립 시스템)
─────────────────────          ──────────────────────
"이 블록은 무엇인가"              "이 블록을 언제 쓸까"
구조 유형 발견                    토큰 기준 확정
슬롯 정의                        catalog 필드 설계
자산 메타                        direct-fit vs recipe 규칙
seam/crop/anchor                 theme/token 적용
                                 fit/validation

         ↓ 접점: 블록 작성 규칙 문서 (BLOCK-RULES.md) ↓
         블록화 시 이 규칙에 맞춰 전환

---

향후 개선 방향

진행 중

1. 토큰 기반 CSS 체계 — typography/spacing/colors 확정, slide-base 분리 완료
2. Figma 블록 추출 — figma_to_html_agent/blocks/에서 1:1 변환 진행 중

다음 단계

3. 폴더 구조 정리 — structures/recipes/legacy 분리
4. 기존 블록 점진 전환 — 분류(direct-fit/recipe/rewrite) → 토큰 기반 전환
5. 파이프라인 연결 — TF-IDF 매칭 + fit 루프 확장 + 시각 품질 검증
6. 다양한 MDX 확장 — MDX 02, 03 이후 추가 문서 유형 검증