From a385ba08c0996e1d5178bbcb8fc27bd8b7cee7ae Mon Sep 17 00:00:00 2001 From: kyeongmin Date: Fri, 17 Apr 2026 14:01:24 +0900 Subject: [PATCH] =?UTF-8?q?README=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8:?= =?UTF-8?q?=20=ED=86=A0=ED=81=B0=20=EC=B2=B4=EA=B3=84,=20=ED=8F=B4?= =?UTF-8?q?=EB=8D=94=20=EA=B5=AC=EC=A1=B0,=20=EC=84=A4=EA=B3=84=20?= =?UTF-8?q?=EB=AC=B8=EC=84=9C,=20=EC=97=AD=ED=95=A0=20=EB=B6=84=EB=A6=AC?= =?UTF-8?q?=20=EB=B0=98=EC=98=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 토큰 기반 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) --- README.md | 129 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 116 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 94bb870..ff62a26 100644 --- a/README.md +++ b/README.md @@ -60,10 +60,10 @@ MDX 기반 콘텐츠를 분석하여 1280×720 슬라이드 HTML로 자동 변 - 중목차(##) 기준으로 영역 분할 3. BEPs 디자인 매칭 검토 - 3-1. 매칭 시 + 3-1. 매칭 시 (direct-fit) - 해당 디자인 선택 - zone 크기에 맞게 재구성 - 3-2. 미매칭 시 + 3-2. 미매칭 시 (recipe/composition) - 중목차에 대한 꼭지 정리 (AI) - 꼭지별 유사 디자인 선택 - 해당 중목차/소목차에 맞게 redesign @@ -85,6 +85,14 @@ MDX 기반 콘텐츠를 분석하여 1280×720 슬라이드 HTML로 자동 변 | 디자인 미매칭 | 코드 고정 렌더 1회 | redesign + 반복 조정 | | 빈 공간 처리 | 그냥 둠 | 자동 재분배 | | 검증 | overflow만 | 시각 품질까지 | +| 스타일 관리 | 블록마다 직접값 | 토큰 기반 통일 | +| 블록 역할 | 완성 HTML | 구조 부품 (스타일 분리) | + +### 실행 원칙 + +- **direct-fit 기준:** 구조, 슬롯, 시각 위계가 기존 블록과 거의 1:1로 대응될 때만 허용 +- **recipe-path 목적:** 미매칭 콘텐츠를 새로운 구조로 재정리하되, 기존 visual language를 최대한 상속 +- **fit 루프 우선순위:** 줄바꿈 → 간격 조정 → preview 축약 → 폰트 1단계 축소 --- @@ -96,7 +104,45 @@ MDX 기반 콘텐츠를 분석하여 1280×720 슬라이드 HTML로 자동 변 | **코드가 판단** | AI는 꼭지 추출만, 레이아웃/디자인 선택은 규칙 기반 | | **기존 디자인 재활용** | Figma에서 추출한 BEPs 블록을 우선 활용, 없으면 같은 스타일로 생성 | | **넘치면 분리** | 슬라이드에 안 들어가는 상세 내용은 첨부로 분리 (자세히보기) | -| **통일이 아닌 다양성** | 같은 구조라도 콘텐츠에 따라 다른 표현 가능 (recipe = 표현 범주) | +| **통일이 아닌 다양성** | 같은 구조라도 콘텐츠에 따라 다른 표현 가능 | + +--- + +## 토큰 기반 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) --- @@ -113,14 +159,30 @@ MDX 기반 콘텐츠를 분석하여 1280×720 슬라이드 HTML로 자동 변 | `src/space_allocator.py` | zone 크기/비율 계산 | | `src/pipeline_context.py` | 파이프라인 데이터 모델 (PopupItem 등) | -### 템플릿 / 카탈로그 +### 템플릿 -| 파일 | 역할 | +| 경로 | 역할 | |------|------| -| `templates/catalog.yaml` | BEPs 블록 목록 (when/slots/template) | -| `templates/blocks/slide-base.html` | 슬라이드 기본 틀 (1280×720) | -| `templates/blocks/new/` | Figma 추출 블록 (prerequisites-3col 등) | -| `templates/blocks/redesign/` | 재디자인 블록 (process-product-2col 등) | +| `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 ### 검증 @@ -141,11 +203,52 @@ MDX 기반 콘텐츠를 분석하여 1280×720 슬라이드 HTML로 자동 변 | `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. **3-2 입력→조정 반복 구현** — redesign 후 빈 공간/overflow 자동 재분배 -2. **검증 강화** — overflow뿐 아니라 정렬, 위계, 가독성까지 시각 품질 검증 -3. **BEPs 매칭 범위 확대** — 더 많은 Figma 블록 추출 및 catalog 등록 -4. **다양한 MDX 확장** — MDX 02, 03 이후 추가 문서 유형 검증 +### 진행 중 +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 이후 추가 문서 유형 검증