kyeongmin
a385ba08c0
- 토큰 기반 CSS 체계 섹션 추가 (2층 구조, 글자 위계, 블록 작성 규칙) - 스타일 폴더 구조 명시 (tokens/themes/base/blocks) - 실행 원칙 추가 (direct-fit, recipe-path, fit 루프) - Source of Truth 명시 - 설계 문서 링크 (IMPROVEMENT-PLAN, TOKENS-v1, BLOCK-RULES) - 역할 분리 (figma_to_html_agent / design_agent) - 향후 개선 방향을 진행 중/다음 단계로 분리 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
255 lines
8.5 KiB
Markdown
255 lines
8.5 KiB
Markdown
# 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](docs/architecture/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](docs/architecture/IMPROVEMENT-PLAN.md) | 개선 설계 (목표/방향/6단계 계획) |
|
||
| [TOKENS-v1.md](docs/architecture/TOKENS-v1.md) | 토큰 위계 기준표 초안 |
|
||
| [BLOCK-RULES.md](docs/architecture/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 이후 추가 문서 유형 검증
|