Compare commits
2
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 Kyeongmin
|
26319f6bd9 | ||
|
Kyeongmin
|
edfc3f29df |
@@ -1,134 +0,0 @@
|
||||
{
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(cmd /c \"npx -y figma-developer-mcp --help\")",
|
||||
"Bash(npx -y figma-developer-mcp --version)",
|
||||
"mcp__Framelink_Figma_MCP__get_figma_data",
|
||||
"mcp__Framelink_Figma_MCP__download_figma_images",
|
||||
"Bash(start \"\" \"d:/ad-hoc/kei/design_agent/figma_to_html_agent/block-tests/prerequisites-3col.html\")",
|
||||
"Bash(python -c \"from selenium import webdriver; print\\('selenium OK'\\)\")",
|
||||
"Bash(python -c ':*)",
|
||||
"Bash(python)",
|
||||
"Bash(start \"\" \"d:/ad-hoc/kei/design_agent/figma_to_html_agent/block-tests/bim-goal-circles.html\")",
|
||||
"Bash(start \"\" \"d:/ad-hoc/kei/design_agent/figma_to_html_agent/block-tests/bg-shapes-only.html\")",
|
||||
"Bash(start \"\" \"d:/ad-hoc/kei/design_agent/figma_to_html_agent/block-tests/bim-figma-devmode.html\")",
|
||||
"Bash(claude mcp:*)",
|
||||
"Bash(curl -sS -o /dev/null -w \"mcp endpoint: HTTP %{http_code}\\\\n\" http://127.0.0.1:3845/mcp)",
|
||||
"Bash(curl -sS -o /dev/null -w \"sse endpoint: HTTP %{http_code}\\\\n\" http://127.0.0.1:3845/sse)",
|
||||
"Bash(curl -sS -o /dev/null -w \"root: HTTP %{http_code}\\\\n\" http://127.0.0.1:3845/)",
|
||||
"Bash(curl -s -o NUL -w \"%{http_code}\" http://127.0.0.1:3845/mcp)",
|
||||
"Bash(curl -s -o /dev/null -w \"%{http_code}\" http://127.0.0.1:3845/sse --max-time 3)",
|
||||
"Bash(curl -s -o /dev/null -w \"%{http_code}\" http://127.0.0.1:3845/mcp --max-time 3)",
|
||||
"Bash(curl -s -X POST http://127.0.0.1:3845/mcp -H \"Content-Type: application/json\" -H \"Accept: application/json, text/event-stream\" -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2024-11-05\",\"capabilities\":{},\"clientInfo\":{\"name\":\"test\",\"version\":\"1.0\"}}}' --max-time 5)",
|
||||
"Bash(curl -v http://127.0.0.1:3845/mcp)",
|
||||
"Bash(curl -s -m 3 http://127.0.0.1:3845/sse)",
|
||||
"Bash(curl -s -m 3 -o /dev/null -w \"%{http_code}\\\\n\" http://127.0.0.1:3845/sse)",
|
||||
"mcp__figma-desktop__get_metadata",
|
||||
"mcp__figma-desktop__get_screenshot",
|
||||
"mcp__figma-desktop__get_design_context",
|
||||
"Bash(curl -sSo bg_texture.png \"http://localhost:3845/assets/849658071be46a26936e8666e3722b2dd548aee7.png\")",
|
||||
"Bash(curl -sSo arc_top.png \"http://localhost:3845/assets/f05ebf15a1125b6c5809f9ffa35b4e4e750687d3.png\")",
|
||||
"Bash(curl -sSo arc_side.png \"http://localhost:3845/assets/2f0f17507c681b7bc2fb109f3d4fafb9ff2f7ce0.png\")",
|
||||
"Bash(curl -sSo big_fill_productivity.svg \"http://localhost:3845/assets/21a89b8138bd47debcc6f12bb140ee63bbd9fdf2.svg\")",
|
||||
"Bash(curl -sSo big_ring_productivity.svg \"http://localhost:3845/assets/fbe84134d2e14bbf84b2c42516e9b85ffe6f7c1e.svg\")",
|
||||
"Bash(curl -sSo big_fill_safety.svg \"http://localhost:3845/assets/1f24875931dc3c36e2c841eaf5b94466fa035a48.svg\")",
|
||||
"Bash(curl -sSo big_ring_safety.svg \"http://localhost:3845/assets/c5aeccdfc884051848fc60f04abf2a9d367dd731.svg\")",
|
||||
"Bash(curl -sSo big_fill_trust.svg \"http://localhost:3845/assets/67ef527c29921d401d31032c02d6b3a0ae1d3050.svg\")",
|
||||
"Bash(curl -sSo acc_outer_speed.svg \"http://localhost:3845/assets/1391787caa4cb8241a1adadbb2c70aed3625e1b8.svg\")",
|
||||
"Bash(curl -sSo acc_inner_speed.svg \"http://localhost:3845/assets/eeb8e9bf8b1841215ae0253017512a7e4a6d5a95.svg\")",
|
||||
"Bash(curl -sSo acc_inner_profit.svg \"http://localhost:3845/assets/4885055cba20f72e83401be371fe74b9b43ec869.svg\")",
|
||||
"Bash(curl -sSo acc_outer_safety.svg \"http://localhost:3845/assets/688b5af1d813b16cd6410453e3d4d1f79c084222.svg\")",
|
||||
"Bash(curl -sSo acc_inner_safety.svg \"http://localhost:3845/assets/2fab268821fc763dbdff12e1dd65820dfa9b628e.svg\")",
|
||||
"Bash(ls block-tests/*.html block-tests/*.md)",
|
||||
"Bash(python scripts/gradient_math.py --test)",
|
||||
"Bash(python scripts/gradient_math.py --w 350 --h 350 --x1 110.833 --y1 18.2292 --x2 219.479 --y2 175 --stops \"0:#FDC69E,1:#E0782C\")",
|
||||
"Bash(python -c \"from scripts.gradient_math import svg_to_css; print\\(svg_to_css\\(W=350,H=350,x1=110.833,y1=18.2292,x2=219.479,y2=175,stops=[\\(0,'#FDC69E'\\),\\(1,'#E0782C'\\)]\\)\\)\")",
|
||||
"Bash(python render.py cards-3col-persona example)",
|
||||
"Bash(python render.py cards-3col-persona example-no-photos)",
|
||||
"Bash(python render.py cycle-3way-intersect example)",
|
||||
"WebFetch(domain:claude.com)",
|
||||
"WebFetch(domain:help.figma.com)",
|
||||
"Bash(curl -sSo \"527bd7809f4b2e5f3cd42f2e713ccbfb37537d82.png\" \"http://localhost:3845/assets/527bd7809f4b2e5f3cd42f2e713ccbfb37537d82.png\")",
|
||||
"Bash(ls \"d:/ad-hoc/kei/design_agent/figma_to_html_agent/block-tests/_renders/pill_flex_\"*)",
|
||||
"Bash(awk '/visual_diff:/{found=1} found && /^- id:/{print NR\": \"$0; found=0}' \"d:/ad-hoc/kei/design_agent/templates/catalog.yaml\")",
|
||||
"Bash(curl -s -o \"bg_slide_texture.png\" \"http://localhost:3845/assets/16a1b2ea5b64663a3ee44bfad24671a612952c29.png\")",
|
||||
"Bash(curl -s -o \"line_divider.svg\" \"http://localhost:3845/assets/01731a60f7d9d35816932c019149e301a3aae1a7.svg\")",
|
||||
"Bash(head -20 /d/ad-hoc/kei/design_agent/samples/mdx/01*.mdx)",
|
||||
"Bash(head -20 /d/ad-hoc/kei/design_agent/samples/mdx/02*.mdx)",
|
||||
"Bash(head -20 /d/ad-hoc/kei/design_agent/samples/mdx/03*.mdx)",
|
||||
"Bash(ls -la /d/ad-hoc/kei/design_agent/data/runs/20260413_*/)",
|
||||
"Bash(python -c \"from src.config import settings; print\\(f'API configured: {bool\\(settings.anthropic_api_key\\)}'\\)\")",
|
||||
"Bash(python run_test.py)",
|
||||
"Bash(curl -s -o /dev/null -w \"%{http_code}\" http://localhost:8000/health)",
|
||||
"Bash(curl -s -o /dev/null -w \"%{http_code}\" http://localhost:8000/)",
|
||||
"Read(//d/ad-hoc/kei/**)",
|
||||
"Bash(curl -s http://localhost:8000/docs)",
|
||||
"Bash(taskkill //F //IM python.exe)",
|
||||
"Bash(python assemble_mdx02_test.py)",
|
||||
"Bash(wc -c data/runs/20260407_*/final.html)",
|
||||
"Bash(curl -s -o /dev/null -w \"%{http_code}\" http://localhost:8000/docs)",
|
||||
"Bash(curl -s http://localhost:8080/docs -o /dev/null -w \"%{http_code}\")",
|
||||
"Bash(curl -s http://localhost:8001/docs -o /dev/null -w \"%{http_code}\")",
|
||||
"Bash(curl -s http://localhost:3000/ -o /dev/null -w \"%{http_code}\")",
|
||||
"Bash(python assemble_mdx02_v3.py)",
|
||||
"Bash(python assemble_mdx02_v4.py)",
|
||||
"Bash(python assemble_mdx02_v5.py)",
|
||||
"Bash(python assemble_mdx02_v6.py)",
|
||||
"Bash(python assemble_mdx02_v7.py)",
|
||||
"Bash(python assemble_mdx02_v8_3plans.py)",
|
||||
"Bash(python assemble_mdx02_v9.py)",
|
||||
"Bash(python build_plan1.py)",
|
||||
"Bash(python build_plan2.py)",
|
||||
"Bash(python build_plan3.py)",
|
||||
"Bash(python build_plan1_v2.py)",
|
||||
"Bash(python build_4plans_final.py)",
|
||||
"Bash(curl -s -o /dev/null -w \"%{http_code}\" http://127.0.0.1:8000/docs)",
|
||||
"Bash(uvicorn backend.main:app --port 8000)",
|
||||
"Bash(python final_plan1.py)",
|
||||
"Bash(python final_plan2.py)",
|
||||
"Bash(python build_all_4plans.py)",
|
||||
"Bash(python build_plan3_kei.py)",
|
||||
"Bash(python build_plan4_kei.py)",
|
||||
"Bash(python make_4plans.py)",
|
||||
"Bash(ls -la \"d:/ad-hoc/kei/design_agent/figma_to_html_agent/block-tests/html_render_final\"*)",
|
||||
"Bash(taskkill //PID 48540 //F)",
|
||||
"Bash(python make_mdx03.py)",
|
||||
"Bash(python run_mdx03_pipeline.py)",
|
||||
"Bash(powershell -Command \"Get-Process python -ErrorAction SilentlyContinue | Select-Object Id,StartTime\")",
|
||||
"Bash(grep \"class FontHierarchy\" src/*.py)",
|
||||
"Bash(ls -ltr /d/ad-hoc/kei/design_agent/data/runs/*/step_*_context.json)",
|
||||
"Bash(awk '{print $2}')",
|
||||
"Bash(stat /d/ad-hoc/kei/design_agent/data/runs/20260414_120225/stage_*_context.json)",
|
||||
"Bash(ls -la /d/ad-hoc/kei/design_agent/data/runs/20260414_120225/stage_*_context.json)",
|
||||
"Bash(awk '{print $6, $7, $8, $9}')",
|
||||
"Bash(ls -lt data/runs/20260414_120225/*_context.json)",
|
||||
"Bash(awk '{print $6,$7,$8,$9}')",
|
||||
"Bash(python -c \" import yaml with open\\('catalog.yaml'\\) as f: data = yaml.safe_load\\(f\\) blocks = data.get\\('blocks', []\\) for b in blocks: print\\(f\\\\\"{b['id']} | {b.get\\('category',''\\)} | items:{b.get\\('min_items','?'\\)}-{b.get\\('max_items','?'\\)}\\\\\"\\) \")",
|
||||
"Bash(python add_tags.py)",
|
||||
"Bash(python -c \"import src.block_reference; print\\('OK'\\)\")",
|
||||
"Bash(python -c \"import src.block_assembler; print\\('OK'\\)\")",
|
||||
"Bash(ls -t d:/ad-hoc/kei/design_agent/docs/history/PHASE-*.md d:/ad-hoc/kei/design_agent/docs/history/IMPROVEMENT-PHASE-*.md)",
|
||||
"Bash(python -c \"import src.pipeline_context; import src.kei_client; import src.pipeline; print\\('모든 import OK'\\)\")",
|
||||
"Bash(python -c \"import src.step_visualizer; import src.pipeline; print\\('OK'\\)\")",
|
||||
"Bash(python -c \"import src.pipeline; print\\('OK'\\)\")",
|
||||
"Bash(python -c \"import src.pipeline; import src.block_assembler; print\\('OK'\\)\")",
|
||||
"Bash(python -c \"import src.block_assembler; import src.pipeline; print\\('OK'\\)\")",
|
||||
"Bash(python -c \"import src.kei_client; print\\('OK'\\)\")",
|
||||
"Bash(python -c \"import src.pipeline; import src.block_assembler; import src.pipeline_context; print\\('OK'\\)\")",
|
||||
"Bash(python -c \"import src.pipeline; import src.validators; print\\('OK'\\)\")",
|
||||
"Bash(python -c \"import src.validators; print\\('OK'\\)\")",
|
||||
"Bash(python -c \"import src.validators; import src.pipeline; print\\('OK'\\)\")",
|
||||
"Bash(python -c \"import src.pipeline; import src.section_parser; import src.block_assembler; print\\('OK'\\)\")",
|
||||
"Bash(python -c \"import src.pipeline; import src.block_assembler; import src.section_parser; print\\('OK'\\)\")",
|
||||
"Bash(python -c \"import src.pipeline; import src.block_assembler; import src.space_allocator; import src.pipeline_context; print\\('OK'\\)\")",
|
||||
"Bash(grep -l \"pp2-grid-wrap\\\\|pp2\" templates/blocks/**/*.html)",
|
||||
"Bash(echo file:///D:/ad-hoc/kei/design_agent/data/runs/20260415_110323/final.html)",
|
||||
"Bash(python -c \"import src.block_reference; import src.section_parser; import src.pipeline; print\\('OK'\\)\")",
|
||||
"Bash(python -c \"import src.block_assembler; import src.section_parser; import src.pipeline; print\\('OK'\\)\")",
|
||||
"Bash(python -c \"import src.block_reference; import src.pipeline; import src.block_assembler; print\\('OK'\\)\")"
|
||||
],
|
||||
"additionalDirectories": [
|
||||
"d:\\ad-hoc\\kei\\design_agent\\templates\\blocks\\new"
|
||||
]
|
||||
}
|
||||
}
|
||||
@@ -1,8 +1,15 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"figma-desktop": {
|
||||
"type": "sse",
|
||||
"url": "http://127.0.0.1:3845/sse"
|
||||
"Framelink Figma MCP": {
|
||||
"command": "cmd",
|
||||
"args": [
|
||||
"/c",
|
||||
"npx",
|
||||
"-y",
|
||||
"figma-developer-mcp",
|
||||
"--figma-api-key=figd_s23TfSDL0hS97DIialy0R2P6QsoZQHfuGx1l_t-k",
|
||||
"--stdio"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,12 +1,4 @@
|
||||
# ⚠ DEPRECATED — 이 문서는 2026-03-27 기준 스냅샷입니다
|
||||
|
||||
> **최신 파이프라인 문서는 [`PIPELINE.md`](PIPELINE.md)를 참조하세요.**
|
||||
> 이 문서는 Type A/B 분기, B'/B'' 변형, Stage 1.7/1.8 등 현재 구조를 반영하지 않습니다.
|
||||
> 히스토리 참고용으로만 유지합니다.
|
||||
|
||||
---
|
||||
|
||||
# Design Agent 전체 구조 파악 리포트 (archived)
|
||||
# Design Agent 전체 구조 파악 리포트
|
||||
|
||||
**작성일:** 2026-03-27
|
||||
**목표:** design_agent의 아키텍처, 파이프라인, 코드 구조를 체계적으로 이해
|
||||
|
||||
@@ -12,89 +12,10 @@
|
||||
|
||||
---
|
||||
|
||||
## 위계 + 용어 (Phase Z 정리, 2026-04-28)
|
||||
|
||||
> 매칭 시스템 (V1~V4) 통합 설계 시 정리. 상세는 [`IMPROVEMENT-REDESIGN.md`](IMPROVEMENT-REDESIGN.md) 4 장 참조.
|
||||
>
|
||||
> Phase Z 사전 작업 — Frame Zone 적용 분류 [`docs/architecture/FRAME-INTEGRATION-MAP.md`](docs/architecture/FRAME-INTEGRATION-MAP.md), Frame / Style / Token 인벤토리 [`docs/architecture/PHASE-Z-FRAME-STYLE-INVENTORY.md`](docs/architecture/PHASE-Z-FRAME-STYLE-INVENTORY.md).
|
||||
|
||||
### 슬라이드 위계
|
||||
|
||||
```
|
||||
[ slide ] 1280×720 (전체 슬라이드)
|
||||
│
|
||||
├─ slide-title ← MDX 대목차 제목 (자동 매핑)
|
||||
├─ slide-divider (고정)
|
||||
│
|
||||
├─ slide-body ≈ 1200×590 (콘텐츠 영역 — `templates/blocks/slide-base.html`)
|
||||
│ │
|
||||
│ └─ 레이아웃 (8-preset layout vocabulary; legacy hint = Type A/B/B'/B'')
|
||||
│ │
|
||||
│ └─ Zone (top / bottom_l / bottom_r 등)
|
||||
│ │
|
||||
│ └─ 프레임 (Figma 디자인 단위)
|
||||
│
|
||||
└─ slide-footer ← MDX 대목차 결론 (자동 매핑)
|
||||
```
|
||||
|
||||
### 용어
|
||||
|
||||
| 용어 | 의미 |
|
||||
|---|---|
|
||||
| **슬라이드** | 1280×720 한 장 |
|
||||
| **slide-base** | 모든 슬라이드 공통 그릇 (배경 + 제목 + 구분선 + 결론 pill) — `templates/blocks/slide-base.html` |
|
||||
| **slide-body** | 본문 가용 영역 (≈ 1200×590) |
|
||||
| **레이아웃 (Layout)** | 8-preset layout vocabulary — slide-body 안 zone 분배 형태 (legacy hint = Type A/B/B'/B'') |
|
||||
| **Zone (영역)** | 레이아웃이 결정한 콘텐츠 구역 |
|
||||
| **Internal Region** | Zone 안의 placement / planning unit (Layer A) — content_object 를 배치하는 내부 영역 (SPEC v1 §2) |
|
||||
| **컨테이너 (Container)** | zone 의 px 명세 (코드 레벨) |
|
||||
| **프레임 (Frame)** | Figma 디자인 단위 (= 기존 "블록") — zone 안 |
|
||||
| **Frame Slot** | Frame 안의 declared placement slot (Layer B) — frame contract 가 선언하는 콘텐츠 placement target (SPEC v1 §3) |
|
||||
| **Layer A** | composition planning 의 zone-내 layer — content_object 를 Internal Region 으로 배치하는 단위 (SPEC v1 §1~§2) |
|
||||
| **Layer B** | frame contract 기반 frame-내 layer — 콘텐츠 매핑 대상인 Frame Slot 구조를 선언하는 단위 (SPEC v1 §3) |
|
||||
|
||||
### MDX → 슬라이드 매핑
|
||||
|
||||
| MDX 위치 | 슬라이드 위치 |
|
||||
|---|---|
|
||||
| `# 대목차 제목` | `slide-title` |
|
||||
| 본문 (`##` / `###`) | `slide-body` 안 (레이아웃 + zone + 프레임) |
|
||||
| `# 대목차 결론` | `slide-footer` |
|
||||
| `<details>` 팝업 | 슬라이드 위 별도 레이어 |
|
||||
|
||||
Layer A planning telemetry is active in trace-only mode; render path activation remains the next axis.
|
||||
|
||||
---
|
||||
|
||||
## 아키텍처 — Phase Z 흐름 (5 단계)
|
||||
|
||||
> 상세는 [`IMPROVEMENT-REDESIGN.md`](IMPROVEMENT-REDESIGN.md) 5 장 참조.
|
||||
|
||||
```
|
||||
STAGE 1) MDX 분석 + 레이아웃 매칭 (8-preset layout vocabulary; legacy = Type A/B/B'/B'')
|
||||
STAGE 2) Zone 별 텍스트 1차 배치
|
||||
STAGE 3) Zone 별 프레임 매칭 (V1~V4; B4 frame_selection evidence integration pending)
|
||||
├ 매칭 완벽 → 텍스트 업데이트
|
||||
├ 매칭 어정쩡 → 디자인 참고 재구성
|
||||
└ 매칭 안 됨 → 디자인 컨셉 바탕 재구성
|
||||
STAGE 4) 프레임 검토 + 컨테이너 조정 (5 차 Fallback)
|
||||
STAGE 5) HTML 조립 + 검증 + 출력
|
||||
```
|
||||
|
||||
핵심 원칙 :
|
||||
- **MDX 1 파일 = 슬라이드 1 장** (절대 분할 X)
|
||||
- **텍스트 원문 무손실 보존** (본문 미리보기 + 팝업 원문)
|
||||
- **자유 디자인 금지** (항상 Figma 프레임 DB 참고)
|
||||
- **불일치 시 레이아웃 회귀** (콘텐츠 줄이지 않고 그릇 변경)
|
||||
|
||||
---
|
||||
|
||||
## 아키텍처 (Phase Q 파이프라인 — 기존)
|
||||
## 아키텍처 (Phase Q 파이프라인)
|
||||
|
||||
> Phase P(다후보 렌더링 비교) 실행 결과 20/100점. 업계 조사(Beautiful.ai, Napkin.ai, VASCAR 등) 기반으로 Phase Q에서 재설계.
|
||||
> 핵심 전환: "계산 먼저, AI 판단 나중에, 렌더링은 검증만"
|
||||
>
|
||||
> ⚠️ Phase Z (매칭 시스템 통합) 진행 후 이 섹션의 일부는 새 흐름으로 대체될 예정.
|
||||
|
||||
```
|
||||
[1단계] Kei 실장 (Opus) — AI 사고
|
||||
@@ -144,48 +65,30 @@ reference 꼭지 있음 → sidebar-right
|
||||
나머지 → single-column
|
||||
```
|
||||
|
||||
### 역할 분리 (Phase Z)
|
||||
|
||||
> ⚠️ Phase R' 의 역할 분리 (AI 가 HTML 구조 직접 생성) 는 **Phase Z 에서 폐기**. 아래는 Phase Z 기준.
|
||||
### 역할 분리 (Phase R')
|
||||
|
||||
| 역할 | 담당 | 방식 | 하는 일 | 하지 않는 일 |
|
||||
|------|------|------|---------|------------|
|
||||
| Kei 실장 | Opus (Kei API) | AI | MDX 본문 분석 보조, 최종 검수 | HTML 생성, 레이아웃 계산 |
|
||||
| 레이아웃 결정 | 코드 | 룰 매칭 | MDX 콘텐츠 → 8-preset layout vocabulary 기반 slide/zone topology 선택 (legacy hint = Type A/B/B'/B'') | — |
|
||||
| 컨테이너 계산 | 코드 | 결정론적 | zone 별 px 확정 (`space_allocator`) | — |
|
||||
| 프레임 매칭 | 코드 (V1~V4; B4 frame_selection evidence integration pending) | 결정론적 | zone ↔ Figma 프레임 매칭 | — |
|
||||
| **콘텐츠 매핑** | **코드 + AI** | **하이브리드** | **zone 안 콘텐츠 / 텍스트를 프레임 슬롯에 배치 / 다듬기 / 변형** | **HTML 구조 생성 X** |
|
||||
| HTML 조립 | 코드 (Jinja2) | 결정론적 | `slide-base` + 프레임 + 슬롯 콘텐츠 합쳐서 final.html | AI 호출 X |
|
||||
| 검증 | 코드 + AI | Selenium + Vision | overflow 측정, 시각 품질 평가 | — |
|
||||
| Kei 실장 | Opus (Kei API) | AI | 꼭지 추출, 비중 판단, relation_type + expression_hint 부여, 최종 검수 | HTML 생성, 레이아웃 계산 |
|
||||
| 컨테이너 계산 | 코드 | 결정론적 | Kei 비중 → 역할별 컨테이너 px 확정 | AI 판단 불필요 |
|
||||
| 프리셋 선택 | 코드 | 규칙 | 실장의 role에 따라 프리셋 자동 선택 | AI 판단 불필요 |
|
||||
| **HTML 생성** | **AI (Kei API)** | **AI** | **콘텐츠 전달 의도에 맞는 HTML 구조를 직접 생성. 블록 CSS를 참고하되 구조는 AI가 결정.** | 블록 "선택" 안 함. 슬롯 "채우기" 안 함. |
|
||||
| 검증 | 코드 + AI | Selenium + 비전 모델 | overflow 측정, 시각 품질 평가 | |
|
||||
|
||||
### HTML 생성 원칙 (Phase Z)
|
||||
### HTML 생성 원칙 (Phase R')
|
||||
|
||||
```
|
||||
블록이 구조를 결정 (P=Q=R, 실패)
|
||||
콘텐츠가 구조를 결정 (R', 폐기 — AI 가 HTML 직접 생성하면 회귀 가능성 큼)
|
||||
→ slide-base + 프레임 DB 가 구조를 결정, AI 는 zone 안 콘텐츠만 (Phase Z)
|
||||
블록이 구조를 결정 (P=Q=R, 실패) → 콘텐츠가 구조를 결정 (R', 접근 C)
|
||||
```
|
||||
|
||||
**Phase Z 의 핵심 원칙**:
|
||||
- **HTML 구조** = `slide-base.html` + 코드 (Jinja2) 가 결정 (절대 AI 가 생성 X)
|
||||
- **AI 의 역할** = zone 안 콘텐츠 매핑 / 텍스트 다듬기 / 디자인 변형 (콘텐츠 단위)
|
||||
- **프레임 DB 참고 필수** — 자유 디자인 금지
|
||||
- **MDX 원문 무손실 보존** (본문 preview, 팝업에 원문)
|
||||
|
||||
⚠️ **Phase R' 회귀 방지**: AI 한테 "HTML 구조 만들어줘" 같은 호출 절대 X. AI 호출은 zone 안 콘텐츠 단위로만.
|
||||
- AI가 콘텐츠 전달 의도(expression_hint)에 맞는 HTML 구조를 직접 생성
|
||||
- 기존 38개 블록의 CSS(색상, 폰트, 배경, radius)를 **스타일 참고**로 활용
|
||||
- 블록을 **"선택"하지 않음**. topic 합침/분리, 포함 관계, 핵심 메시지 분리 가능
|
||||
- 디자인 토큰(CSS 변수)으로 품질 제약 + Selenium 측정 + 비전 모델 검증
|
||||
|
||||
---
|
||||
|
||||
## 핵심 프로세스 (구 Phase Q 기준 — Phase Z 에서 대체됨)
|
||||
|
||||
> ⚠️ **아래 흐름은 구 Phase Q 기준의 5 단계 (Kei 실장 → 디자인 팀장 → 텍스트 편집자 → 디자인 실무자 → 재검토). Phase Z 에서 대체됨.**
|
||||
>
|
||||
> **신규 흐름은 위 "아키텍처 — Phase Z 흐름 (5 단계)" 섹션 또는 [IMPROVEMENT-REDESIGN.md](IMPROVEMENT-REDESIGN.md) 5 장 따름.**
|
||||
>
|
||||
> ⚠️ **특히 Phase Z 와 충돌하므로 무시할 것**:
|
||||
> - "페이지 분리" → Phase Z: MDX 1 파일 = 슬라이드 1 장 (절대 분할 X)
|
||||
> - "텍스트 압축 / 요약" → Phase Z: MDX 원문 무손실 보존 (본문 preview, 팝업 원문)
|
||||
> - "AI 5 단계" → Phase Z: AI 호출은 zone 안 콘텐츠 단위로만 (HTML 구조 / 레이아웃 / 프리셋 결정 X)
|
||||
## 핵심 프로세스
|
||||
|
||||
```
|
||||
사용자 콘텐츠 입력 (텍스트/MDX 붙여넣기 또는 파일 업로드)
|
||||
|
||||
+189
@@ -0,0 +1,189 @@
|
||||
# Phase X: 템플릿 기반 동적 레이아웃
|
||||
|
||||
> 작성일: 2026-04-06
|
||||
> 상태: 계획 수립
|
||||
|
||||
---
|
||||
|
||||
## 배경
|
||||
|
||||
현재 파이프라인은 모든 MDX를 "배경/본심/첨부/결론" 4칸에 억지로 끼워넣는다.
|
||||
배경이 없는 콘텐츠도 배경을 만들어내고, 3분할이 적절한 콘텐츠도 2분할로 넣는다.
|
||||
Kei가 내용을 잘못 파악한 게 아니라, **"4칸을 채워라"는 지시가 잘못**된 것이다.
|
||||
|
||||
## 핵심 아이디어
|
||||
|
||||
**미리 정의된 레이아웃 템플릿 중 Kei가 콘텐츠에 맞는 것을 선택한다.**
|
||||
|
||||
- Kei가 자유롭게 구조를 만드는 것이 아님 (불안정)
|
||||
- 옵션을 주고 고르게 함 (안정적)
|
||||
- 하드코딩 아님 — 어떤 MDX가 와도 적절한 템플릿이 선택됨
|
||||
|
||||
## 고정 영역
|
||||
|
||||
모든 템플릿 공통:
|
||||
- **상단**: 슬라이드 제목 헤더 (항상 존재)
|
||||
- **하단**: 결론 footer (항상 존재)
|
||||
- **중간**: 템플릿에 따라 달라지는 영역
|
||||
|
||||
## 중간 영역 템플릿 옵션
|
||||
|
||||
### A. body + sidebar
|
||||
```
|
||||
┌──────────┬─────┐
|
||||
│ 본심1 │참조 │
|
||||
│ 본심2 │ │
|
||||
└──────────┴─────┘
|
||||
```
|
||||
적합: 참조자료(용어 정의 등)가 별도로 있는 콘텐츠
|
||||
예시: 01번 MDX (DX/BIM 용어 정립)
|
||||
|
||||
### B. 상단 wide + 하단 2분할
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ 강조/핵심 │
|
||||
├────────┬────────┤
|
||||
│ 항목1 │ 항목2 │
|
||||
└────────┴────────┘
|
||||
```
|
||||
적합: 핵심 1개 + 두 가지 측면 비교/설명
|
||||
예시: 03번 MDX (필수요건 + 과정혁신/결과변화)
|
||||
|
||||
### C. 상단 wide + 하단 3분할
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ 강조/핵심 │
|
||||
├─────┬─────┬─────┤
|
||||
│항목1│항목2│항목3 │
|
||||
└─────┴─────┴─────┘
|
||||
```
|
||||
적합: 핵심 1개 + 세 가지 항목 병렬
|
||||
예시: 02번 MDX (궁극적 목표 + 발주처/설계사/시공사)
|
||||
|
||||
### D. 2분할 (좌우 대등)
|
||||
```
|
||||
┌────────┬────────┐
|
||||
│ 항목1 │ 항목2 │
|
||||
│ │ │
|
||||
└────────┴────────┘
|
||||
```
|
||||
적합: 두 가지 비교/대비
|
||||
|
||||
### E. 단일 전체
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ │
|
||||
│ 본심 (전체) │
|
||||
│ │
|
||||
└─────────────────┘
|
||||
```
|
||||
적합: 하나의 흐름, 분할 불필요
|
||||
|
||||
### F. 상단 wide + 하단 2분할 + 보조 sidebar
|
||||
```
|
||||
┌─────────────┬───┐
|
||||
│ 강조/핵심 │참조│
|
||||
├──────┬──────┤ │
|
||||
│항목1 │항목2 │ │
|
||||
└──────┴──────┴───┘
|
||||
```
|
||||
적합: B + sidebar 조합
|
||||
|
||||
---
|
||||
|
||||
## 프로세스
|
||||
|
||||
```
|
||||
1. Kei가 MDX 원본을 읽고 내용 분석
|
||||
→ 핵심 메시지, 콘텐츠 구조 파악
|
||||
|
||||
2. Kei가 꼭지를 나눔 (개수와 역할명 자유)
|
||||
→ "핵심목표 1개, 주체별 기대효과 3개, 결론 1개"
|
||||
→ 역할명: 고정 4칸 아님. 콘텐츠에 맞는 이름 사용
|
||||
|
||||
3. Kei가 템플릿 선택
|
||||
→ "꼭지 구조를 보니 C템플릿이 맞다"
|
||||
→ 옵션 A~F 중 하나
|
||||
|
||||
4. Kei가 각 영역에 꼭지 배정 + weight
|
||||
→ 상단: 핵심목표(0.3)
|
||||
→ 하단좌: 발주처(0.2), 하단중: 설계사(0.2), 하단우: 시공사(0.2)
|
||||
→ footer: 결론(0.1)
|
||||
|
||||
5. 파이프라인이 템플릿대로 컨테이너 생성 → BEFORE
|
||||
|
||||
6. 콘텐츠 채움 → 측정 → 재배분 → FILLED → AFTER
|
||||
|
||||
7. 조립 → code_assembled / final
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 작업 리스트
|
||||
|
||||
### X-1: 템플릿 정의
|
||||
- 옵션 A~F의 구체적 컨테이너 구조 정의
|
||||
- 각 옵션의 zone 이름, 비율 계산 공식, 좌표 계산 로직
|
||||
- `src/design_director.py`에 `LAYOUT_TEMPLATES` 정의
|
||||
- 하드코딩 아님: 템플릿은 구조만 정의, 크기는 weight와 슬라이드 크기에서 동적 계산
|
||||
|
||||
### X-2: Kei 프롬프트 수정
|
||||
- `KEI_PROMPT`에 템플릿 A~F 옵션 제시
|
||||
- Kei가 콘텐츠를 보고 `layout: "C"` 선택
|
||||
- page_structure의 역할명이 자유 (배경/본심 고정 아님)
|
||||
- 각 역할에 zone 배정 (상단/하단좌/하단우 등)
|
||||
- 하드코딩 아님: Kei가 콘텐츠마다 다른 선택을 함
|
||||
|
||||
### X-3: space_allocator 템플릿 기반 컨테이너 생성
|
||||
- 선택된 템플릿에 따라 컨테이너 좌표/크기 생성
|
||||
- weight 비율로 각 영역 크기 결정
|
||||
- `select_preset()` → `build_layout_from_template()`
|
||||
- 하드코딩 아님: 템플릿 구조 + weight + 슬라이드 크기로 동적 계산
|
||||
|
||||
### X-4: block_assembler / assemble_stage2 동적 역할
|
||||
- `["배경", "본심", "첨부", "결론"]` 고정 루프 → `page_structure.keys()` 동적 루프
|
||||
- 좌표 계산은 X-3에서 생성한 컨테이너 정보 사용
|
||||
- 색상/폰트: 역할 수에 맞게 동적 배분
|
||||
- 하드코딩 아님: 역할 수가 3개든 5개든 동작
|
||||
|
||||
### X-5: 나머지 파일 동적화
|
||||
- step_visualizer: before/after 시각화에서 동적 역할 루프
|
||||
- fit_verifier: 4역할 고정 → 동적 역할
|
||||
- html_generator: Sonnet에게 동적 영역 수만큼 생성 요청
|
||||
- renderer: 동적 grid-template 생성
|
||||
- 하드코딩 아님: 모두 ctx.containers.keys() 기반
|
||||
|
||||
### X-6: 검증
|
||||
- 01번 MDX → A템플릿 → 기존과 동일하거나 더 나은 결과
|
||||
- 02번 MDX → C템플릿 → 상단 강조 + 하단 3분할
|
||||
- 03번 MDX → B템플릿 → 상단 요건 + 하단 2분할
|
||||
- 텍스트가 컨테이너 안에 있음
|
||||
- 공란 최소
|
||||
- 01번이 깨지면 롤백
|
||||
|
||||
---
|
||||
|
||||
## 주의사항
|
||||
|
||||
- 하드코딩 절대 금지: 특정 MDX에만 동작하는 코드 없음
|
||||
- 01번 보호: Phase X 전에 git commit 완료 (1f7579c). 깨지면 롤백
|
||||
- 점진적 진행: X-1 → X-2 후 Kei 응답 확인 → X-3~X-5 순차 진행
|
||||
- 각 단계마다 검증
|
||||
|
||||
---
|
||||
|
||||
## 관련 코드 (고정 역할 참조 현황)
|
||||
|
||||
| 파일 | 참조 수 | 수정 범위 |
|
||||
|------|---------|----------|
|
||||
| src/html_generator.py | 54건 | X-5 |
|
||||
| src/step_visualizer.py | 32건 | X-5 |
|
||||
| src/space_allocator.py | 26건 | X-3 |
|
||||
| scripts/assemble_stage2.py | 26건 | X-4 |
|
||||
| src/kei_client.py | 18건 | X-2 |
|
||||
| src/block_assembler.py | 17건 | X-4 |
|
||||
| src/fit_verifier.py | 16건 | X-5 |
|
||||
| src/pipeline.py | 15건 | X-3~X-5 |
|
||||
| src/renderer.py | 7건 | X-5 |
|
||||
| src/pipeline_context.py | 4건 | 필요 시 |
|
||||
| **합계** | **215건** | |
|
||||
-304
@@ -1,304 +0,0 @@
|
||||
# Design Agent 파이프라인 현황
|
||||
|
||||
> **최종 갱신:** 2026-04-13
|
||||
> **목적:** 새 세션의 AI가 이 문서만 읽으면 파이프라인 전체를 이해하고 작업할 수 있도록 한다.
|
||||
|
||||
---
|
||||
|
||||
## 1. 전체 흐름 요약
|
||||
|
||||
```
|
||||
MDX 입력
|
||||
↓
|
||||
[Stage 0] MDX 정규화 (코드)
|
||||
↓
|
||||
[Stage 1A] Kei 실장 — 꼭지 추출 (AI: Opus)
|
||||
→ layout_template: A 또는 B 선택
|
||||
↓
|
||||
[Stage 1B] 컨셉 구체화 (AI: Opus)
|
||||
→ relation_type, expression_hint, source_data
|
||||
↓
|
||||
[Stage 1B-ST] 구조화 텍스트 생성 (AI: Opus)
|
||||
→ structured_text per topic
|
||||
↓
|
||||
[Stage 1.5a] 컨테이너 계산 (코드: 결정론적)
|
||||
→ FontHierarchy, ContainerSpec, Preset
|
||||
↓
|
||||
[Stage 1.7] 블록 레퍼런스 선택 (코드 + AI 1회)
|
||||
→ relation_type → 카테고리 → 필터 → 블록 결정
|
||||
↓
|
||||
[Stage 1.8] 적합성 검증 + 보강 (코드 + Selenium + AI)
|
||||
→ overflow 감지 → Kei 에스컬레이션 → 재배분
|
||||
↓
|
||||
[Stage 1.5b] 디자인 예산 계산 (코드)
|
||||
↓
|
||||
[Stage 2] HTML 생성 (Type에 따라 다름)
|
||||
→ Type B/B'/B'': block_assembler (코드)
|
||||
→ Type A: Sonnet 재구성 (AI, 미완성)
|
||||
↓
|
||||
[Stage 3] 렌더링 조립 (Type A만, Jinja2)
|
||||
↓
|
||||
[Stage 4] 검증 (Selenium + Opus Vision)
|
||||
→ overflow 측정 + 스크린샷 품질 평가
|
||||
↓
|
||||
최종 HTML 출력 (data/runs/{id}/final.html)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 레이아웃 유형 (Type A / B / B' / B'')
|
||||
|
||||
### 2.1 Kei가 선택하는 유형: A와 B
|
||||
|
||||
Kei 프롬프트(`src/kei_client.py:34-46`)에서 A 또는 B를 선택한다.
|
||||
|
||||
| 유형 | 조건 | Zone 구조 |
|
||||
|------|------|-----------|
|
||||
| **Type A** | 참조자료(용어 정의, 부록 등)가 별도로 존재 | body(배경+본심) + sidebar(첨부) + footer(결론) |
|
||||
| **Type B** | 본문 흐름만. 배경/첨부가 없거나 억지로 만들어야 하면 | top + bottom_left + bottom_right + footer |
|
||||
|
||||
### 2.2 Type B 변형: B'과 B''
|
||||
|
||||
B'과 B''은 **Kei가 선택하지 않는다.** 특정 MDX 테스트 과정에서 하드코딩한 변형이다.
|
||||
|
||||
| 변형 | 생성 경위 | 차이점 | 코드 위치 |
|
||||
|------|----------|--------|----------|
|
||||
| **B** | 범용 | 상단(전체폭 텍스트+이미지) + 하단 2분할 + 결론 | `block_assembler.py:461` `_assemble_slide_html_type_b()` |
|
||||
| **B'** | 03번 MDX 테스트 중 생성 | 상단이 세로 카드 형태 + 하단에 표 렌더링 + 불릿 전용 | `block_assembler.py:885` `_assemble_slide_html_type_b_prime()` |
|
||||
| **B''** | B'에서 스타일 변형 | border/gradient 없음. 색상바+여백으로 구분 | `block_assembler_b2.py:9` `_assemble_slide_html_type_b_double_prime()` |
|
||||
|
||||
**분기 코드** (`block_assembler.py:370-378`):
|
||||
```python
|
||||
if ctx.analysis.layout_template == "B":
|
||||
return _assemble_slide_html_type_b(ctx, title_text)
|
||||
if ctx.analysis.layout_template == "B'":
|
||||
return _assemble_slide_html_type_b_prime(ctx, title_text)
|
||||
if ctx.analysis.layout_template == "B''":
|
||||
return _assemble_slide_html_type_b_double_prime(ctx, title_text)
|
||||
```
|
||||
|
||||
### 2.3 향후 방향
|
||||
|
||||
B'/B''은 **범용화가 필요하다.** 현재는 03번 콘텐츠 구조(카드형+표)를 B 조립 함수가 커버하지 못해서 만든 땜질이다. 궁극적으로는 B 하나로 다양한 콘텐츠 구조를 커버하거나, AI가 서브타입을 판단하게 해야 한다.
|
||||
|
||||
---
|
||||
|
||||
## 3. MDX 샘플 ↔ 유형 매핑
|
||||
|
||||
| MDX | 파일 | 콘텐츠 성격 | 선택 유형 | 상태 |
|
||||
|-----|------|-----------|----------|------|
|
||||
| **01번** | `samples/mdx/01. 건설산업 DX의 올바른 이해(0127).mdx` | 용어 혼용 문제 + 용어 정의(참조) | **Type A** | ⚠ Stage 2 미완성 (Sonnet 의존) |
|
||||
| **02번** | `samples/mdx/02. DX의 시행 목표 및 기대효과.mdx` | 본문 흐름 (3대 목표) | **Type B** | ✅ 동작 |
|
||||
| **03번** | `samples/mdx/03. DX 시행을 위한 필수 요건 및 혁신 방안.mdx` | 카드형 구조 + 표 + 불릿 | **Type B'** | ✅ 동작 (하드코딩) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 단계별 상세
|
||||
|
||||
### Stage 0: MDX 정규화
|
||||
- **파일:** `src/mdx_normalizer.py` → `normalize_mdx_content()`
|
||||
- **입력:** raw MDX 텍스트
|
||||
- **출력:** `NormalizedContent` (sections, images, tables 분리)
|
||||
|
||||
### Stage 1A: Kei 실장 — 꼭지 추출
|
||||
- **파일:** `src/kei_client.py` → `classify_content()`
|
||||
- **AI:** Opus (Kei API)
|
||||
- **입력:** 정규화된 텍스트
|
||||
- **출력:** `Analysis` (title, core_message, layout_template, total_pages, page_structure, topics)
|
||||
- **핵심 판단:**
|
||||
- 꼭지 5개 이내 추출
|
||||
- 각 꼭지에 purpose, layer, role, emphasis, direction 부여
|
||||
- layout_template = "A" 또는 "B" 선택
|
||||
- page_structure에 역할별 weight(비중) 배정
|
||||
|
||||
### Stage 1B: 컨셉 구체화
|
||||
- **파일:** `src/kei_client.py` → `refine_concepts()`
|
||||
- **AI:** Opus
|
||||
- **출력:** topics에 relation_type, expression_hint, source_data 추가
|
||||
|
||||
### Stage 1B-ST: 구조화 텍스트 생성
|
||||
- **파일:** `src/kei_client.py` → `generate_structured_text()`
|
||||
- **AI:** Opus
|
||||
- **출력:** topic별 structured_text (마크다운 형태)
|
||||
|
||||
### Stage 1.5a: 컨테이너 계산 (결정론적)
|
||||
- **파일:** `src/space_allocator.py`
|
||||
- **함수:**
|
||||
- Type A → `calculate_container_specs()`
|
||||
- Type B/B'/B'' → `build_containers_type_b()`
|
||||
- 공통 → `calculate_font_hierarchy()`, `select_preset()`
|
||||
- **입력:** page_structure의 weight, slide 크기(1280×720)
|
||||
- **출력:** 역할별 `ContainerSpec` (width_px, height_px, zone)
|
||||
- **로직:** weight × available_px = 각 zone px 확정
|
||||
|
||||
### Stage 1.7: 블록 레퍼런스 선택
|
||||
- **파일:** `src/block_reference.py` → `select_and_generate_references()`
|
||||
- **로직 (코드 결정론적 + AI 1회):**
|
||||
1. relation_type → 블록 카테고리 매핑
|
||||
2. expression_hint 키워드 매칭
|
||||
3. 컨테이너 크기 적합성 필터
|
||||
4. role/zone 제약 (sidebar → visuals/media 제외)
|
||||
5. catalog.yaml 존재 검증 (유령 블록 차단)
|
||||
6. 후보 2-3개 → Kei 1회 호출로 최종 선택
|
||||
- **출력:** 역할별 `BlockReference` (block_id, design_reference_html)
|
||||
|
||||
### Stage 1.8: 적합성 검증 + 보강
|
||||
- **파일:** `src/fit_verifier.py` → `calculate_fit()`
|
||||
- **로직:**
|
||||
1. 텍스트 분량 vs 할당 공간 계산
|
||||
2. Selenium으로 실제 높이 측정 (3회 루프)
|
||||
3. overflow 시 → Kei 에스컬레이션 (`call_kei_fit_escalation()`)
|
||||
- 팝업 분리 판단, zone 간 재배분
|
||||
4. 보강 제안: bold 키워드, 팝업 요약 등
|
||||
|
||||
### Stage 2: HTML 생성
|
||||
|
||||
**Type B/B'/B'' (코드 조립):**
|
||||
- **파일:** `src/block_assembler.py` → `assemble_slide_html()`
|
||||
- 역할별 `assemble_role_html()` 호출 → 블록 HTML 조립
|
||||
- structured_text + design_reference_html 결합
|
||||
- 이미지/팝업 embed
|
||||
- **즉시 완성 HTML 반환**
|
||||
|
||||
**Type A (AI 재구성, 미완성):**
|
||||
- **파일:** `src/content_verifier.py` → `generate_with_retry()`
|
||||
- Sonnet에 phase_t_context 전달 → CSS + 레이아웃 생성
|
||||
- **현재 검증 불완전**
|
||||
|
||||
### Stage 3: 렌더링 조립 (Type A만)
|
||||
- **파일:** `src/renderer.py` → `render_slide_from_html()`
|
||||
- Type B는 Stage 2에서 완전한 HTML이므로 스킵
|
||||
|
||||
### Stage 4: 검증
|
||||
- **파일:** `src/slide_measurer.py`
|
||||
- `measure_rendered_heights()` — Selenium 실측
|
||||
- `capture_slide_screenshot()` — 스크린샷 캡처
|
||||
- **파일:** `src/kei_client.py` → `vision_quality_gate()`
|
||||
- Opus 멀티모달: 스크린샷 보고 시각 품질 평가
|
||||
|
||||
---
|
||||
|
||||
## 5. 핵심 파일 맵
|
||||
|
||||
```
|
||||
src/
|
||||
├── main.py ← FastAPI 서버, POST /api/generate
|
||||
├── pipeline.py ← 파이프라인 오케스트레이터 (generate_slide)
|
||||
├── pipeline_context.py ← PipelineContext 데이터 클래스
|
||||
├── config.py ← 설정 (API key, 슬라이드 크기)
|
||||
│
|
||||
├── mdx_normalizer.py ← Stage 0: MDX → NormalizedContent
|
||||
├── kei_client.py ← Stage 1A/1B/1B-ST: Kei API 호출 + 프롬프트
|
||||
├── space_allocator.py ← Stage 1.5a: 컨테이너 px 계산
|
||||
├── block_reference.py ← Stage 1.7: 블록 선택 (relation_type 기반)
|
||||
├── fit_verifier.py ← Stage 1.8: 적합성 검증 + Selenium 루프
|
||||
├── block_assembler.py ← Stage 2: Type B/B' HTML 조립
|
||||
├── block_assembler_b2.py ← Stage 2: Type B'' HTML 조립
|
||||
├── content_verifier.py ← Stage 2: Type A HTML (Sonnet, 미완성)
|
||||
├── renderer.py ← Stage 3: Jinja2 렌더링 (Type A만)
|
||||
├── slide_measurer.py ← Stage 4: Selenium 측정 + 스크린샷
|
||||
├── validators.py ← Kei 응답 검증 (A/B별 구조 확인)
|
||||
│
|
||||
├── image_utils.py ← 이미지 크기 측정 + data URI 변환
|
||||
├── svg_calculator.py ← SVG 다이어그램 좌표 계산
|
||||
└── sse_utils.py ← SSE 스트리밍 유틸
|
||||
|
||||
templates/
|
||||
├── slide-base.html ← 슬라이드 기본 구조 (Jinja2, CSS Grid)
|
||||
├── catalog.yaml ← 블록 라이브러리 정의 (50+개)
|
||||
└── blocks/ ← 블록 HTML 템플릿
|
||||
├── headers/ (8개)
|
||||
├── cards/ (17개)
|
||||
├── emphasis/ (12개)
|
||||
├── tables/ (8개)
|
||||
├── visuals/ (6개)
|
||||
├── media/ (4개)
|
||||
└── BEPs/ (6개)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 데이터 흐름 (PipelineContext)
|
||||
|
||||
```
|
||||
PipelineContext:
|
||||
raw_content ← 원본 MDX
|
||||
normalized ← NormalizedContent (sections, images, tables)
|
||||
analysis ← Analysis (title, core_message, layout_template, page_structure, topics)
|
||||
topics ← list[Topic] (relation_type, expression_hint, structured_text 포함)
|
||||
page_structure ← PageStructure (roles → {topic_ids, weight, zone})
|
||||
containers ← dict[role → ContainerSpec(width_px, height_px)]
|
||||
font_hierarchy ← FontHierarchy (key_msg, core, bg, sidebar 폰트 크기)
|
||||
references ← dict[role → list[BlockReference]]
|
||||
sub_layouts ← dict[role → SubLayout]
|
||||
fit_result ← 역할별 fit_status, 재배분값
|
||||
enhancement_result ← bold_keywords, popup_summaries 등
|
||||
generated_html ← Stage 2 출력
|
||||
rendered_html ← Stage 3 출력 (완전 HTML)
|
||||
measurement ← Selenium 측정값
|
||||
quality_score ← 0-100
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 현재 구현 상태 (Phase Y-11~13, 2026-04-15)
|
||||
|
||||
> Phase Y: slide-base 기반 파이프라인 재설계. 상세: `docs/history/PHASE-Y-PLAN.md`
|
||||
|
||||
### 파이프라인 흐름 (현재)
|
||||
|
||||
```
|
||||
[Stage 0] MDX → normalized.sections (source of truth)
|
||||
[Stage 1A] Kei 꼭지 추출 (영역/zone 판단 안 함)
|
||||
[Phase Y] 코드: normalized → 대목차 추출 → group schema 분류 → 블록 매칭 → 영역 확정
|
||||
[Stage 1.5a] space_allocator: weight → zone px (% 기반)
|
||||
[Stage 1.7] block_reference: tag_match → schema_match → fallback 순서
|
||||
[Stage 1.8] assembler(measure_mode) → Selenium 측정 → fit 루프
|
||||
[Stage 2] assembler(slide-base + 블록) → final HTML
|
||||
[Stage 4] Selenium overflow + 비전 (-1 미평가)
|
||||
```
|
||||
|
||||
### MDX별 상태
|
||||
|
||||
| MDX | 상태 | 비고 |
|
||||
|-----|------|------|
|
||||
| **03** | ✅ 동작 | prerequisites-3col + pp2. 텍스트 누락 없음. 회귀 기준. |
|
||||
| **02** | ⚠ schema 1차 | top: parallel_3_with_image. bottom: 분류 정교화 필요. |
|
||||
| **01** | ⬜ 미착수 | Type A. 별도 작업. |
|
||||
|
||||
### 핵심 원칙 (확립됨)
|
||||
|
||||
- source of truth = normalized.sections (Stage 0)
|
||||
- 영역 = 코드가 결정 (Kei 아님). sub_titles 기반 + group schema.
|
||||
- 블록 CSS에 최종 고정값. slide_font_css는 공통 레이아웃 계약만.
|
||||
- zone = % 기반, block = height:100%.
|
||||
- 글씨 크기 고정. fit은 padding → 내용량 → font 1단계(responsive tier).
|
||||
- 기존 경로 삭제 금지. 새 schema 점진적 추가. MDX 03 회귀 기준.
|
||||
- 하드코딩 금지. 프로세스가 결과를 만드는 구조.
|
||||
|
||||
3. **블록 글씨 크기 하드코딩 (px 고정)**
|
||||
- 블록 CSS에 font-size가 Figma 원본 px로 고정
|
||||
- 컨테이너 크기에 따라 조정 불가 → overflow 원인
|
||||
- CSS 변수(`var(--block-font-heading)`)로 전환 → assembler가 zone 크기에 따라 계산
|
||||
|
||||
### 미해결 프로세스
|
||||
1. **overflow 시 font 조정 루프** — 재배분만으로 부족할 때 font/padding 줄이기 (Y-5)
|
||||
2. **Sonnet redesign 경로** — tag 매칭 실패 시 블록 단위 redesign → 저장 (Y-6)
|
||||
|
||||
---
|
||||
|
||||
## 8. 검증 계획
|
||||
|
||||
업데이트된 템플릿이 파이프라인에서 제대로 동작하는지 확인한다.
|
||||
|
||||
| MDX | 유형 | 검증 포인트 |
|
||||
|-----|------|-----------|
|
||||
| **01번** | Type A | 업데이트된 블록 + slide-base.html로 조립 정상 동작 |
|
||||
| **02번** | Type B | 업데이트된 블록 선택 + 조립 + overflow 없음 |
|
||||
| **03번** | Type B' | 카드/표 구조가 업데이트된 템플릿으로 정상 렌더링 |
|
||||
|
||||
### 검증 방법
|
||||
1. 각 MDX를 파이프라인에 투입
|
||||
2. 중간 산출물(step1_analysis.json 등) 확인 — 블록 선택이 의도대로인지
|
||||
3. 최종 HTML(final.html) 렌더링 — overflow, 시각 품질 확인
|
||||
4. 업데이트 전/후 비교
|
||||
@@ -393,36 +393,6 @@ P2-E (누락기능) ── 병렬 │
|
||||
|
||||
---
|
||||
|
||||
## Phase Y: MDX 외부 컴포넌트 인라인 삽입
|
||||
|
||||
> 근거: MDX에서 `import ... from '*.astro'`로 불러오는 외부 컴포넌트(표, 다이어그램 등)가 파이프라인에서 누락됨. import문은 제거되고 `<DxEffect />` 같은 태그는 사라져서 콘텐츠 손실 발생.
|
||||
|
||||
### Y-1: import문 파싱 — 컴포넌트명:파일경로 매핑
|
||||
- **파일:** `src/mdx_normalizer.py`
|
||||
- **내용:** `import Foo from '../../components/foo.astro'` → `{"Foo": 절대경로}` 매핑 추출
|
||||
- **의존성:** base_path (MDX 원본 파일 위치, pipeline.py에서 전달)
|
||||
- **완료 기준:** import문에서 컴포넌트명→절대경로 dict 반환
|
||||
|
||||
### Y-2: .astro 파일 파싱 — HTML + CSS 추출
|
||||
- **파일:** `src/mdx_normalizer.py`
|
||||
- **내용:** .astro 파일에서 `---` frontmatter 제거, HTML 본문 + `<style>` 블록 추출
|
||||
- **의존성:** Y-1
|
||||
- **완료 기준:** dx.astro → `<div class="table-wrapper">...</div>` + `<style>...</style>` 반환
|
||||
|
||||
### Y-3: 셀프클로징 태그 교체 — 인라인 삽입
|
||||
- **파일:** `src/mdx_normalizer.py`
|
||||
- **내용:** `<DxEffect />` 태그를 Y-2에서 추출한 HTML+CSS로 교체
|
||||
- **의존성:** Y-1, Y-2
|
||||
- **완료 기준:** MDX 정규화 결과에 외부 컴포넌트 HTML이 인라인으로 포함
|
||||
|
||||
### Y-4: Astro 특수 문법 정리
|
||||
- **파일:** `src/mdx_normalizer.py`
|
||||
- **내용:** Astro의 멀티라인 태그(`<td class="category-cell">텍스트</td>` 줄바꿈 패턴), `style="letter-spacing: -0.9px"` 등 인라인 스타일 정리
|
||||
- **의존성:** Y-2
|
||||
- **완료 기준:** 추출된 HTML이 브라우저에서 정상 렌더링
|
||||
|
||||
---
|
||||
|
||||
## 의존 관계
|
||||
|
||||
```
|
||||
|
||||
@@ -1,124 +1,303 @@
|
||||
# C.E.L. Slide Pipeline
|
||||
# Kei Design Agent
|
||||
|
||||
## 이 프로젝트는 무엇인가
|
||||
콘텐츠를 시각적으로 구조화된 슬라이드 HTML(1280×720px, 16:9)로 변환하는 AI 파이프라인.
|
||||
|
||||
MDX 기반 콘텐츠를 입력하면, 1280×720 슬라이드 HTML로 자동 변환하는 파이프라인입니다.
|
||||
## 개요
|
||||
|
||||
텍스트 콘텐츠를 넣으면, 구조를 분석하고 BEPs(Figma) 디자인을 매칭하여 슬라이드를 만들어줍니다.
|
||||
텍스트/MDX 콘텐츠를 입력하면:
|
||||
1. Kei 실장(Opus)이 정보 구조와 비중을 판단하고
|
||||
2. 코드가 컨테이너 크기를 계산하고
|
||||
3. 블록을 선택하고
|
||||
4. 콘텐츠-컨테이너 적합성을 검증하고
|
||||
5. AI(Sonnet)가 블록 디자인을 참고하여 HTML을 생성하고
|
||||
6. 코드가 슬라이드 프레임에 조립하고
|
||||
7. 측정+비전 모델로 검증합니다
|
||||
|
||||
---
|
||||
|
||||
## 어떻게 구성/구현되어 있는가
|
||||
|
||||
### 전체 흐름
|
||||
## 파이프라인 (10단계)
|
||||
|
||||
```
|
||||
MDX 입력 → 정규화 → 꼭지 추출(AI) → zone 구분 → BEPs 매칭 → 조립 → 검증 → 출력
|
||||
MDX 원본
|
||||
↓
|
||||
[Stage 0] MDX 정규화 (코드)
|
||||
↓
|
||||
[Stage 1A] 꼭지 추출 + 영역 배정 (Kei API / Opus)
|
||||
↓
|
||||
[Stage 1B] 컨셉 구체화 (Kei API / Opus)
|
||||
↓
|
||||
[Stage 1.5a] 컨테이너 초기 계산 (코드)
|
||||
↓
|
||||
[Stage 1.7] 블록 선택 (코드)
|
||||
↓
|
||||
[Stage 1.8] 적합성 검증 + 재배분 + 보강 (코드 + Kei 에스컬레이션)
|
||||
↓
|
||||
[Stage 1.5b] 디자인 예산 재계산 (코드)
|
||||
↓
|
||||
[Stage 2] HTML 생성 (영역별 개별 호출) (Claude Sonnet)
|
||||
↓
|
||||
[Stage 3] 렌더링 조립 + 후처리 (코드)
|
||||
↓
|
||||
[Stage 4] 측정 + 품질 검증 (Selenium + Opus Vision)
|
||||
↓
|
||||
검증 통과 시 → final.html 저장 + 팝업 분리 (파일 출력)
|
||||
```
|
||||
|
||||
### 구조
|
||||
|
||||
- **slide-base:** 1280×720 슬라이드 프레임. 대목차 + 구분선 + 본문 영역 + 핵심 인사이트(footer)
|
||||
- **zone:** 본문 영역 안에서 중목차(##) 기준으로 나뉘는 영역 (top/bottom 등)
|
||||
- **블록:** zone 안에 들어가는 디자인 단위. Figma에서 추출한 BEPs 디자인을 HTML/CSS로 변환한 것
|
||||
- **catalog:** 블록의 메타 정보 (구조, 슬롯, 매칭 조건)
|
||||
|
||||
### 주요 파일
|
||||
|
||||
| 파일 | 역할 |
|
||||
|------|------|
|
||||
| `src/pipeline.py` | 파이프라인 오케스트레이션 |
|
||||
| `src/section_parser.py` | 중목차 추출, 구조 분류 |
|
||||
| `src/block_reference.py` | BEPs 디자인 매칭 |
|
||||
| `src/block_assembler.py` | 슬라이드 HTML 조립 |
|
||||
| `templates/blocks/slide-base.html` | 슬라이드 프레임 |
|
||||
| `templates/catalog.yaml` | 블록 메타 정보 |
|
||||
|
||||
### 산출물
|
||||
|
||||
각 실행은 `data/runs/{run_id}/` 아래에 저장됩니다.
|
||||
|
||||
| 파일 | 내용 |
|
||||
|------|------|
|
||||
| `final.html` | 최종 슬라이드 |
|
||||
| `final_context.json` | 파이프라인 결과 데이터 |
|
||||
| `steps/*.html` | 단계별 디버그 보드 |
|
||||
| `첨부*_상세*.html` | popup 상세 내용 |
|
||||
※ Stage 4 이후의 파일 저장은 별도 Stage가 아닌 후처리입니다.
|
||||
|
||||
---
|
||||
|
||||
## 무슨 문제가 있는가
|
||||
## 단계별 상세
|
||||
|
||||
| 문제 | 설명 |
|
||||
### Stage 0: MDX 정규화
|
||||
|
||||
| 항목 | 내용 |
|
||||
|------|------|
|
||||
| **블록마다 스타일이 제각각** | 각 블록 HTML 안에 font-size, color, padding이 직접 박혀있어서, 같은 슬라이드 안에서 블록이 섞이면 위계가 안 맞음 |
|
||||
| **slide-base에 구조+스타일 혼재** | 프레임 HTML 안에 전체 CSS가 인라인으로 들어있어서 유지보수가 어려움 |
|
||||
| **블록이 완성 HTML** | 블록이 구조+스타일+값을 모두 포함하고 있어서, 재사용/조합이 안 됨 |
|
||||
| **매칭 안 되면 고정 렌더** | BEPs에 맞는 블록이 없을 때 코드가 1회 고정 렌더하고 끝. 반복 조정 없음 |
|
||||
| **빈 공간/overflow 방치** | 렌더 후 빈 공간이 있어도 조정 안 하고, overflow만 감지 |
|
||||
| **검증이 약함** | overflow 측정만 하고, 정렬/위계/가독성 같은 시각 품질은 미검증 |
|
||||
| **목적** | 원본 MDX에서 JSX/frontmatter를 제거하고, 섹션/팝업/이미지/테이블로 분리 |
|
||||
| **적용기술** | 코드 (`normalize_mdx_content()`) |
|
||||
| **인풋** | 원본 MDX 문자열 |
|
||||
| **아웃풋** | `normalized` — clean_text, title, sections[], popups[], images[], tables[] |
|
||||
| **연계** | → Stage 1A가 clean_text를 Kei에게 전달 |
|
||||
|
||||
### Stage 1A: 꼭지 추출 + 영역 배정
|
||||
|
||||
| 항목 | 내용 |
|
||||
|------|------|
|
||||
| **목적** | 콘텐츠에서 핵심 파트(꼭지)를 식별하고, 슬라이드의 어떤 영역(배경/본심/첨부/결론)에 배치할지 결정 |
|
||||
| **적용기술** | Kei API (`classify_content()`) |
|
||||
| **인풋** | normalized.clean_text |
|
||||
| **아웃풋** | `topics[]` (id, title, purpose, layer, relation_type, expression_hint), `page_structure` (role별 topic_ids, weight) |
|
||||
| **연계** | → Stage 1B가 각 꼭지를 구체화 |
|
||||
|
||||
### Stage 1B: 컨셉 구체화
|
||||
|
||||
| 항목 | 내용 |
|
||||
|------|------|
|
||||
| **목적** | 각 꼭지에 실제 원본 텍스트(source_data)와 요약(summary)을 매핑 |
|
||||
| **적용기술** | Kei API (`refine_concepts()`) |
|
||||
| **인풋** | topics + clean_text |
|
||||
| **아웃풋** | `topics` 업데이트 — source_data, summary 추가 |
|
||||
| **연계** | → Stage 1.5a가 텍스트 양을 기반으로 컨테이너 비율 계산 |
|
||||
|
||||
### Stage 1.5a: 컨테이너 초기 계산
|
||||
|
||||
| 항목 | 내용 |
|
||||
|------|------|
|
||||
| **목적** | 폰트 위계 확정 + 슬라이드 내 영역별 컨테이너 크기(px) 계산 + 프리셋 선택 |
|
||||
| **적용기술** | 코드 (`calculate_font_hierarchy()`, `calculate_dynamic_ratio()`, `calculate_container_specs()`) |
|
||||
| **인풋** | topics, page_structure (weight), preset |
|
||||
| **아웃풋** | `font_hierarchy` (key_msg/core/bg/sidebar px), `container_ratio` (71:29 등), `containers` (role별 width_px, height_px), `preset` |
|
||||
| **연계** | → Stage 1.7이 컨테이너 크기를 보고 블록 선택 |
|
||||
|
||||
### Stage 1.7: 블록 선택
|
||||
|
||||
| 항목 | 내용 |
|
||||
|------|------|
|
||||
| **목적** | 각 꼭지의 relation_type + expression_hint + 컨테이너 크기로 적합한 블록 결정. 같은 영역 꼭지들의 layer가 다르면 주종관계 판단 (블록 1개로 합침) |
|
||||
| **적용기술** | 코드 (`select_and_generate_references()`) — catalog.yaml 기반 결정론적 매칭 |
|
||||
| **인풋** | topics, containers, page_structure |
|
||||
| **아웃풋** | `references` — role별 block_id, variant, design_reference_html, topic_id, is_hierarchical, supporting_topic_ids |
|
||||
| **연계** | → Stage 1.8이 선택된 블록+콘텐츠가 컨테이너에 맞는지 검증 |
|
||||
|
||||
### Stage 1.8: 적합성 검증 + 재배분 + 보강 + 서브 컨테이너
|
||||
|
||||
| 항목 | 내용 |
|
||||
|------|------|
|
||||
| **목적** | 콘텐츠가 컨테이너에 들어가는지 검증 → 안 맞으면 재배분 → 여전히 안 되면 Kei 에스컬레이션 → 여유 공간에 보충 콘텐츠 → 서브 컨테이너 배치 계산 |
|
||||
| **적용기술** | 코드 (`calculate_fit()`, `redistribute()`, `analyze_enhancements()`, `apply_enhancements()`, `calculate_sub_layout()`) + Kei API (에스컬레이션 시 `call_kei_fit_escalation()`) |
|
||||
| **인풋** | topics, containers, references, font_hierarchy, normalized, core_message |
|
||||
| **아웃풋** | `containers` (재배분된 height_px), `fit_result` (role별 fit_status, redistribution), `enhancement_result` (V-7 subordinate_treatments, V-8 supplement_blocks, V-9 emphasis_blocks, V-10 bold_keywords, V-4 kei_decisions), `sub_layouts` (role별 서브 컨테이너 name/width/height, table_rows) |
|
||||
| **내부 흐름** | Step 1: 필요 높이 계산 → Step 2: 재배분 → Step 3: Kei 에스컬레이션 → Step 4-5: 보강 분석+적용 → Step 6: fit 재검증 → Step 7: 서브 컨테이너 배치 → Step 8: 확정 |
|
||||
| **연계** | → Stage 1.5b가 재배분된 크기로 디자인 예산 재계산, → Stage 2가 sub_layouts + enhancements를 프롬프트에 반영 |
|
||||
|
||||
### Stage 1.5b: 디자인 예산 재계산
|
||||
|
||||
| 항목 | 내용 |
|
||||
|------|------|
|
||||
| **목적** | 재배분된 컨테이너 크기 + 선택된 블록 schema 기준으로 영역별 가용 공간 계산 |
|
||||
| **적용기술** | 코드 (`calculate_design_budget()`) |
|
||||
| **인풋** | containers (재배분 후), references (블록 schema) |
|
||||
| **아웃풋** | `containers` 업데이트 — design_budget (available_height_px, available_width_px, fits) |
|
||||
| **연계** | → Stage 2가 design_budgets를 프롬프트에 포함 |
|
||||
|
||||
### Stage 2: HTML 생성 (영역별 개별 호출)
|
||||
|
||||
| 항목 | 내용 |
|
||||
|------|------|
|
||||
| **목적** | page_structure에 존재하는 각 역할(배경/본심/첨부/결론)의 HTML을 **영역별 개별 Sonnet 호출**로 생성. 블록 디자인을 참고하되 콘텐츠가 구조를 결정 (Phase R' 방식) |
|
||||
| **적용기술** | Claude Sonnet API — 영역당 1회 호출 (`build_area_prompt()` → `_call_claude()`) |
|
||||
| **인풋** | raw_content, topics, containers, font_hierarchy, references (design_reference_html), sub_layouts (서브 컨테이너 치수), enhancements (V-4~V-10 지시), design_budgets |
|
||||
| **호출 흐름** | Sonnet(배경) → bg_html, Sonnet(본심) → core_html, Sonnet(첨부) → sidebar_html, Sonnet(결론) → footer_html. 해당 역할에 꼭지가 없으면 스킵. body_html = bg_html + spacer + core_html |
|
||||
| **아웃풋** | `generated_html` — body_html, sidebar_html, footer_html |
|
||||
| **프롬프트에 포함되는 것** | 서브 컨테이너 레이아웃 제약, 디자인 레퍼런스 HTML (블록 CSS 참고), Kei 에스컬레이션 결정, 종속 꼭지 처리 지시, 보충 블록 지시, 강조 문장, bold 키워드, 폰트/컨테이너 크기 제약 |
|
||||
| **연계** | → Stage 3이 영역별 HTML을 슬라이드 프레임에 배치 |
|
||||
|
||||
### Stage 3: 렌더링 조립 + 후처리
|
||||
|
||||
| 항목 | 내용 |
|
||||
|------|------|
|
||||
| **목적** | 생성된 HTML 조각을 CSS Grid 슬라이드 프레임에 삽입 + 후처리 (폰트 캡핑, overflow 제거, sidebar width 조정, bold 변환) |
|
||||
| **적용기술** | 코드 (`render_slide_from_html()`) |
|
||||
| **인풋** | generated_html, preset (grid_areas, grid_columns), font_hierarchy, container_ratio |
|
||||
| **아웃풋** | `rendered_html` → `final.html` 파일 저장 |
|
||||
| **연계** | → Stage 4가 렌더링 결과를 측정+검증 |
|
||||
|
||||
### Stage 4: 품질 검증
|
||||
|
||||
| 항목 | 내용 |
|
||||
|------|------|
|
||||
| **목적** | Selenium으로 실제 브라우저 렌더링 후 overflow 측정 + Opus Vision으로 시각적 품질 평가 |
|
||||
| **적용기술** | Selenium (`measure_rendered_heights()`) + Claude Opus Vision (`vision_quality_gate()`) |
|
||||
| **인풋** | rendered_html |
|
||||
| **아웃풋** | `measurement` (zone별 clientHeight, scrollHeight, overflow, excess_px), `quality_score` |
|
||||
| **연계** | 파이프라인 완료. overflow 시 경고 포함하여 진행 |
|
||||
|
||||
---
|
||||
|
||||
## 어떻게 개선하려 하는가
|
||||
## 중간 산출물
|
||||
|
||||
핵심은 3가지입니다.
|
||||
파이프라인 실행마다 `data/runs/{timestamp}/`에 단계별 결과가 저장된다.
|
||||
|
||||
1. **블록을 구조 부품화** — 완성 HTML이 아니라, 구조만 담고 스타일은 토큰으로 분리
|
||||
2. **스타일을 토큰으로 통일** — 블록마다 제각각인 폰트/색/여백을 공통 기준으로
|
||||
3. **2경로 파이프라인** — 매칭되면 바로 쓰고(direct-fit), 안 되면 재구성(recipe)
|
||||
### JSON Context (Stage별 누적 상태)
|
||||
| 파일 | Stage | 내용 |
|
||||
|------|-------|------|
|
||||
| `stage_0_context.json` | 0 | normalized (섹션, 팝업, 이미지) |
|
||||
| `stage_1a_context.json` | 1A | topics, page_structure |
|
||||
| `stage_1b_context.json` | 1B | topics (source_data 추가) |
|
||||
| `stage_1_5a_context.json` | 1.5a | font_hierarchy, containers, ratio |
|
||||
| `stage_1_7_context.json` | 1.7 | references (블록 선택 결과) |
|
||||
| `stage_1_8_context.json` | 1.8 | fit_result, enhancements, sub_layouts |
|
||||
| `stage_1_5b_context.json` | 1.5b | containers (design_budget 추가) |
|
||||
| `stage_2_context.json` | 2 | generated_html |
|
||||
| `stage_3_context.json` | 3 | (rendered_html은 final.html로 별도 저장) |
|
||||
| `stage_4_context.json` | 4 | measurement, quality_score |
|
||||
| `final_context.json` | 최종 | 전체 context |
|
||||
|
||||
### AS-IS → TO-BE
|
||||
### HTML 시각화 (`steps/` 폴더)
|
||||
| 파일 | Stage | 내용 |
|
||||
|------|-------|------|
|
||||
| `stage_0.html` | 0 | 섹션/팝업/이미지 목록 |
|
||||
| `stage_1a.html` | 1A | 꼭지 테이블 (purpose, layer, 영역) |
|
||||
| `stage_1b.html` | 1B | 꼭지 + source_data + summary |
|
||||
| `stage_1_5a.html` | 1.5a | 빈 컨테이너 (1280×720) |
|
||||
| `stage_1_5a_content.html` | 1.5a | 컨테이너에 콘텐츠 배치 |
|
||||
| `stage_1_5b.html` | 1.5b | 디자인 예산 (available height/width) |
|
||||
| `stage_1_7.html` | 1.7 | 블록 선택 표시 |
|
||||
| `stage_1_8_fit_before.html` | 1.8 | 적합성 (재배분 전) |
|
||||
| `stage_1_8_fit_after.html` | 1.8 | 재배분 후 + 보강 |
|
||||
| `stage_1_8_blocks.html` | 1.8 | SLOT 구조 + 블록 디자인 + 주종관계 (1280×720) |
|
||||
| `stage_2.html` | 2 | 영역별 Sonnet 출력을 실제 렌더링 (역할별 개별 확인) |
|
||||
| `stage_3.html` | 3 | 영역을 합쳐 슬라이드 프레임에 배치한 결과 (1280×720 실제 렌더링) |
|
||||
| `stage_4.html` | 4 | 측정 결과 + 품질 점수 |
|
||||
|
||||
```
|
||||
AS-IS:
|
||||
AI가 먼저 꼭지를 추출하고
|
||||
→ 매칭 블록이 있으면 삽입, 없으면 코드가 1회 고정 렌더
|
||||
→ 빈 공간이 있어도 그냥 둠
|
||||
→ 블록마다 font-size, color가 직접 박혀있어서 섞이면 위계 안 맞음
|
||||
---
|
||||
|
||||
TO-BE:
|
||||
중목차 기준으로 zone을 먼저 나누고
|
||||
→ TF-IDF로 BEPs 매칭 시도
|
||||
→ 매칭되면 블록 삽입 + 크기 조절 (direct-fit)
|
||||
→ 안 되면 AI가 꼭지 정리 + 유사 디자인으로 redesign + 반복 조정 (recipe)
|
||||
→ 빈 공간/overflow를 자동 재분배
|
||||
→ 모든 블록이 토큰 기반이라 스타일 통일
|
||||
## 핵심 원칙
|
||||
|
||||
1. **콘텐츠가 구조를 결정** — 블록 CSS는 참고만. AI가 콘텐츠 전달 의도를 보고 HTML 구조 결정 (Phase R')
|
||||
2. **하드코딩 금지** — font-size 외 모든 수치는 동적 계산. 어떤 MDX가 들어와도 동일하게 동작
|
||||
3. **스크롤 절대 금지** — overflow:auto/scroll 어떤 영역에서도 불허
|
||||
4. **Kei API 필수** — fallback 없음. 성공할 때까지 무한 재시도
|
||||
5. **AI가 옵션 생성, Kei가 결정** — 공간 부족 시 하드코딩 대응이 아니라 Kei 판단 요청
|
||||
6. **계산 먼저, AI 판단 나중에, 렌더링은 검증만**
|
||||
7. **overflow 상태에서 출력 금지** — Vision 모델 품질 게이트 통과 필수
|
||||
|
||||
---
|
||||
|
||||
## 블록 라이브러리 (38개)
|
||||
|
||||
6개 카테고리, 38개 블록. 각 블록은 `catalog.yaml`에 용도(when), 금지(not_for), purpose_fit, schema(슬롯 정의)가 있음.
|
||||
|
||||
| 카테고리 | 개수 | 용도 |
|
||||
|---------|------|------|
|
||||
| **headers** | 5 | 타이틀, 꼭지 헤더 |
|
||||
| **cards** | 9 | 항목 나열, 카드 그리드 |
|
||||
| **tables** | 3 | 비교표, 데이터 테이블 |
|
||||
| **visuals** | 6 | SVG 다이어그램, 관계도 |
|
||||
| **emphasis** | 10 | 강조, 인용, 결론, 불릿 |
|
||||
| **media** | 5 | 이미지/사진 |
|
||||
|
||||
---
|
||||
|
||||
## 기술 스택
|
||||
|
||||
| 역할 | 도구 |
|
||||
|------|------|
|
||||
| 서버 | FastAPI + uvicorn (포트 8001) |
|
||||
| AI (Kei 실장/편집자) | Kei API → Opus (localhost:8000) |
|
||||
| AI (HTML 생성) | Anthropic API → Claude Sonnet |
|
||||
| AI (품질 검증) | Anthropic API → Claude Opus Vision |
|
||||
| 블록 검색 | FAISS + bge-m3 |
|
||||
| 템플릿 | Jinja2 (블록 디자인 레퍼런스용) |
|
||||
| 렌더링 | CSS Grid + 디자인 토큰 (1280×720) |
|
||||
| 렌더링 측정 | Selenium headless Chrome |
|
||||
| SVG 시각화 | svg_calculator.py (N개 동적 배치) |
|
||||
| 이미지 | Pillow (크기 측정) + base64 인라인 |
|
||||
| 폰트 | Pretendard Variable |
|
||||
| 공간 계산 | space_allocator.py + fit_verifier.py (결정론적) |
|
||||
|
||||
---
|
||||
|
||||
## 설치 및 실행
|
||||
|
||||
```bash
|
||||
# 설치
|
||||
cd design_agent
|
||||
pip install -e .
|
||||
|
||||
# FAISS 인덱스 빌드 (블록 추가/수정 시)
|
||||
python scripts/build_block_index.py
|
||||
|
||||
# .env 설정
|
||||
ANTHROPIC_API_KEY=sk-ant-...
|
||||
KEI_API_URL=http://localhost:8000
|
||||
LOG_LEVEL=DEBUG
|
||||
```
|
||||
|
||||
---
|
||||
```bash
|
||||
# 터미널 1: Kei API (필수)
|
||||
cd D:\ad-hoc\kei\persona_agent
|
||||
python -m uvicorn backend.main:app --host 127.0.0.1 --port 8000
|
||||
|
||||
## 현재 상태
|
||||
# 터미널 2: Design Agent
|
||||
cd D:\ad-hoc\kei\design_agent
|
||||
python -m uvicorn src.main:app --host 127.0.0.1 --port 8001 --reload
|
||||
```
|
||||
|
||||
| 대상 | 슬라이드 변환 | 파이프라인 자동화 |
|
||||
|------|-------------|----------------|
|
||||
| MDX 03 (3개 목표 + 비교표) | ✅ 완료 | ✅ 파이프라인 연결 |
|
||||
| MDX 02 (목표 + 프로세스 + 상세표) | ✅ 완료 | △ 파이프라인 연결, 시각 품질 개선 중 |
|
||||
| MDX 01 (Type A, sidebar 구조) | ✅ 완료 (개별) | 미연결 |
|
||||
| 토큰 기반 CSS 체계 | - | ✅ 정의 완료, slide-base 적용 |
|
||||
| Figma 블록 추출 | - | 진행 중 (`figma_to_html_agent/blocks/`) |
|
||||
접속: http://localhost:8001
|
||||
|
||||
---
|
||||
|
||||
## 다음 단계 방향
|
||||
## 개선 이력
|
||||
|
||||
| 순서 | 단계 | 내용 |
|
||||
|------|------|------|
|
||||
| 1 | 폴더 구조 정리 | structures/recipes/legacy 분리 |
|
||||
| 2 | 기존 블록 점진 전환 | 분류(direct-fit/recipe/rewrite) → 토큰 기반 전환 |
|
||||
| 3 | catalog 고도화 | 파일명 중심 → 속성 테이블 기반 매칭 |
|
||||
| 4 | 파이프라인 연결 | TF-IDF 매칭 + recipe/composition 경로 |
|
||||
| 5 | fit 루프 확장 | 빈 공간 재분배, preview 축약, 자동 조정 반복 |
|
||||
| 6 | 시각 품질 검증 | 정렬, 위계, 가독성 검증 강화 |
|
||||
|
||||
상세: [IMPROVEMENT-PLAN.md](docs/architecture/IMPROVEMENT-PLAN.md)
|
||||
| Phase | 내용 | 상태 |
|
||||
|-------|------|------|
|
||||
| A~D | 슬라이드 품질 핵심 | 완료 |
|
||||
| G~N | Kei API, 스토리라인, 정합성, 블록 선택, 비중, 측정 | 완료 |
|
||||
| O | 컨테이너 기반 레이아웃 | 완료 |
|
||||
| P | 다후보 렌더링 비교 | 완료 (20/100점 → 방향 전환) |
|
||||
| Q | 제약 기반 블록 선택 | 완료 |
|
||||
| R | 하이브리드 블록 (실패 — P=Q=R 동일 구조) | 실패 |
|
||||
| R' | 블록 CSS 참고 + AI 구조 결정 | 설계 확정 |
|
||||
| S | 검증 합격 프롬프트 + Claude HTML 생성 | 설계 확정 |
|
||||
| T | 11-Stage 파이프라인 + 디자인 레퍼런스 | 완료 (31/31 통과) |
|
||||
| V | 적합성 검증 + Kei 에스컬레이션 + 서브 컨테이너 | 완료 |
|
||||
| W | Stage 2 출력 품질 수정 (6건) | 진행 중 |
|
||||
|
||||
---
|
||||
|
||||
## 참고 문서
|
||||
## Kei Persona와의 관계
|
||||
|
||||
| 문서 | 내용 |
|
||||
|------|------|
|
||||
| [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) | 블록 작성 규칙 (에이전트 간 계약서) |
|
||||
```
|
||||
Kei Persona Agent (localhost:8000)
|
||||
├── Opus + RAG + 세션 컨텍스트
|
||||
├── 도메인 지식 (건설/DX/BIM)
|
||||
└── 대화/생성/피드백/실행 모드
|
||||
|
||||
Design Agent (localhost:8001, 이 프로젝트)
|
||||
├── 슬라이드 생성 전용
|
||||
├── Kei API로 꼭지 추출(1A) + 컨셉 구체화(1B) + 에스컬레이션(1.8) 호출
|
||||
├── Sonnet으로 HTML 생성(Stage 2)
|
||||
├── Opus Vision으로 품질 검증(Stage 4)
|
||||
└── 두 프로젝트는 독립. 코드 공유 없음. API 연동만.
|
||||
```
|
||||
|
||||
Binary file not shown.
@@ -0,0 +1,105 @@
|
||||
# 45개 블록 BLOCK_SLOTS — design_director.py에 반영 필요
|
||||
# 다른 쪽 작업 완료 후 교체
|
||||
|
||||
BLOCK_SLOTS = {
|
||||
# headers/
|
||||
"section-title-with-bg": {"required": ["title_ko"], "optional": ["title_en", "breadcrumb", "bg_image"]},
|
||||
"section-header-bar": {"required": ["title"], "optional": ["subtitle"]},
|
||||
"topic-left-right": {"required": ["title", "description"], "optional": []},
|
||||
"topic-center": {"required": ["title"], "optional": ["subtitle", "description"]},
|
||||
"topic-numbered": {"required": ["number", "title"], "optional": ["description", "color"]},
|
||||
# cards/
|
||||
"card-image-3col": {"required": ["cards"], "optional": []},
|
||||
"card-text-grid": {"required": ["cards"], "optional": []},
|
||||
"card-dark-overlay": {"required": ["cards"], "optional": []},
|
||||
"card-tag-image": {"required": ["cards"], "optional": []},
|
||||
"card-icon-desc": {"required": ["cards"], "optional": []},
|
||||
"card-compare-3col": {"required": ["cards"], "optional": []},
|
||||
"card-step-vertical": {"required": ["steps"], "optional": []},
|
||||
"card-image-round": {"required": ["cards"], "optional": []},
|
||||
"card-stat-number": {"required": ["stats"], "optional": []},
|
||||
"card-numbered": {"required": ["items"], "optional": []},
|
||||
# tables/
|
||||
"compare-3col-badge": {"required": ["headers", "rows"], "optional": []},
|
||||
"compare-2col-split": {"required": ["left_title", "right_title", "rows"], "optional": []},
|
||||
"table-simple-striped": {"required": ["headers", "rows"], "optional": []},
|
||||
# visuals/
|
||||
"venn-diagram": {"required": ["center_label", "items"], "optional": ["center_sub", "description"]},
|
||||
"circle-gradient": {"required": ["label"], "optional": ["sub_label"]},
|
||||
"compare-pill-pair": {"required": ["left_label", "right_label"], "optional": ["left_sub", "right_sub"]},
|
||||
"process-horizontal": {"required": ["steps"], "optional": []},
|
||||
"flow-arrow-horizontal": {"required": ["steps"], "optional": []},
|
||||
"keyword-circle-row": {"required": ["keywords"], "optional": []},
|
||||
"layer-diagram": {"required": ["layers"], "optional": ["title"]},
|
||||
"timeline-vertical": {"required": ["events"], "optional": []},
|
||||
"timeline-horizontal": {"required": ["events"], "optional": []},
|
||||
"pyramid-hierarchy": {"required": ["levels"], "optional": []},
|
||||
# emphasis/
|
||||
"quote-left-border": {"required": ["quote_text"], "optional": ["source"]},
|
||||
"quote-big-mark": {"required": ["quote_text"], "optional": ["source"]},
|
||||
"quote-question": {"required": ["question"], "optional": ["description"]},
|
||||
"conclusion-accent-bar": {"required": ["conclusion_text"], "optional": ["label"]},
|
||||
"comparison-2col": {"required": ["left_title", "left_content", "right_title", "right_content"], "optional": ["left_subtitle", "right_subtitle"]},
|
||||
"banner-gradient": {"required": ["text"], "optional": ["sub_text"]},
|
||||
"dark-bullet-list": {"required": ["bullets"], "optional": ["title"]},
|
||||
"highlight-strip": {"required": ["segments"], "optional": []},
|
||||
"callout-solution": {"required": ["title", "description"], "optional": ["icon", "source"]},
|
||||
"callout-warning": {"required": ["title", "description"], "optional": ["icon"]},
|
||||
"tab-label-row": {"required": ["tabs"], "optional": []},
|
||||
"divider-text": {"required": ["text"], "optional": []},
|
||||
# media/
|
||||
"image-row-2col": {"required": ["images"], "optional": []},
|
||||
"image-grid-2x2": {"required": ["images"], "optional": []},
|
||||
"image-side-text": {"required": ["image_src"], "optional": ["image_alt", "title", "description", "bullets"]},
|
||||
"image-full-caption": {"required": ["src"], "optional": ["alt", "caption"]},
|
||||
"image-before-after": {"required": ["before_src", "after_src"], "optional": ["before_label", "after_label", "caption"]},
|
||||
}
|
||||
|
||||
# _apply_defaults 용
|
||||
BLOCK_DEFAULTS = {
|
||||
"section-title-with-bg": {"title_ko": "(제목)"},
|
||||
"section-header-bar": {"title": "(섹션)"},
|
||||
"topic-left-right": {"title": "(소제목)", "description": ""},
|
||||
"topic-center": {"title": "(제목)"},
|
||||
"topic-numbered": {"number": "1", "title": "(단계)"},
|
||||
"card-image-3col": {"cards": []},
|
||||
"card-text-grid": {"cards": []},
|
||||
"card-dark-overlay": {"cards": []},
|
||||
"card-tag-image": {"cards": []},
|
||||
"card-icon-desc": {"cards": []},
|
||||
"card-compare-3col": {"cards": []},
|
||||
"card-step-vertical": {"steps": []},
|
||||
"card-image-round": {"cards": []},
|
||||
"card-stat-number": {"stats": []},
|
||||
"card-numbered": {"items": []},
|
||||
"compare-3col-badge": {"headers": [], "rows": []},
|
||||
"compare-2col-split": {"left_title": "A", "right_title": "B", "rows": []},
|
||||
"table-simple-striped": {"headers": [], "rows": []},
|
||||
"venn-diagram": {"center_label": "관계도", "items": [], "center_sub": "", "description": ""},
|
||||
"circle-gradient": {"label": "(라벨)"},
|
||||
"compare-pill-pair": {"left_label": "A", "right_label": "B"},
|
||||
"process-horizontal": {"steps": []},
|
||||
"flow-arrow-horizontal": {"steps": []},
|
||||
"keyword-circle-row": {"keywords": []},
|
||||
"layer-diagram": {"layers": []},
|
||||
"timeline-vertical": {"events": []},
|
||||
"timeline-horizontal": {"events": []},
|
||||
"pyramid-hierarchy": {"levels": []},
|
||||
"quote-left-border": {"quote_text": "(인용)"},
|
||||
"quote-big-mark": {"quote_text": "(인용)"},
|
||||
"quote-question": {"question": "(질문)"},
|
||||
"conclusion-accent-bar": {"conclusion_text": "(결론)"},
|
||||
"comparison-2col": {"left_title": "A", "left_content": "-", "right_title": "B", "right_content": "-"},
|
||||
"banner-gradient": {"text": "(배너)"},
|
||||
"dark-bullet-list": {"bullets": []},
|
||||
"highlight-strip": {"segments": []},
|
||||
"callout-solution": {"title": "(솔루션)", "description": ""},
|
||||
"callout-warning": {"title": "(경고)", "description": ""},
|
||||
"tab-label-row": {"tabs": []},
|
||||
"divider-text": {"text": "구분"},
|
||||
"image-row-2col": {"images": []},
|
||||
"image-grid-2x2": {"images": []},
|
||||
"image-side-text": {"image_src": ""},
|
||||
"image-full-caption": {"src": ""},
|
||||
"image-before-after": {"before_src": "", "after_src": ""},
|
||||
}
|
||||
@@ -1,162 +0,0 @@
|
||||
# 블록 작성 규칙
|
||||
|
||||
Figma 1:1 HTML을 재사용 가능한 블록으로 전환할 때, 이 규칙을 따른다.
|
||||
figma_to_html_agent와 design_agent 간의 **계약서**.
|
||||
|
||||
---
|
||||
|
||||
## 1. HTML 규칙
|
||||
|
||||
### 구조 스타일은 OK
|
||||
블록의 배치/정렬을 위한 CSS는 블록 안에 있어야 한다.
|
||||
```css
|
||||
/* OK */
|
||||
display: flex;
|
||||
grid-template-columns: repeat(3, 1fr);
|
||||
align-items: center;
|
||||
overflow: hidden;
|
||||
position: relative;
|
||||
```
|
||||
|
||||
### 직접값은 금지
|
||||
하드코딩된 폰트/색/여백은 블록 안에 넣지 않는다.
|
||||
```css
|
||||
/* NG */
|
||||
font-size: 11px;
|
||||
color: #475569;
|
||||
padding: 16px;
|
||||
|
||||
/* OK — 토큰 참조 */
|
||||
font-size: var(--font-body);
|
||||
color: var(--color-body);
|
||||
padding: var(--card-padding);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 클래스명 규칙
|
||||
|
||||
### 공통 클래스 (모든 블록에서 사용)
|
||||
| 클래스 | 용도 | 토큰 참조 |
|
||||
|--------|------|-----------|
|
||||
| `.zone-title` | 중목차 제목 | `--font-zone-title`, `--color-zone-title` |
|
||||
| `.sub-title` | 소목차 제목 | `--font-sub-title` |
|
||||
| `.bul` | 본문 블릿 (hanging indent) | `--font-body`, `--bullet-indent` |
|
||||
| `.body-text` | 본문 텍스트 | `--font-body`, `--color-body` |
|
||||
| `.caption` | 캡션/보조 | `--font-caption`, `--color-caption` |
|
||||
|
||||
### 블록 고유 클래스
|
||||
블록별 고유 요소는 블록 prefix를 붙인다.
|
||||
```
|
||||
.p3c-bar (prerequisites-3col의 gradient 바)
|
||||
.pp2-col (process-product-2col의 컬럼)
|
||||
.cid-card (card-icon-desc의 카드)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 슬롯 규칙
|
||||
|
||||
블록이 받아들이는 콘텐츠 슬롯. catalog에 명시.
|
||||
|
||||
| 슬롯 | 용도 | 예시 |
|
||||
|------|------|------|
|
||||
| `zone_title` | 중목차 제목 | "DX의 궁극적 목표" |
|
||||
| `sub_title` | 소목차 제목 | "안전과 품질" |
|
||||
| `body` | 본문 텍스트 | 설명 문장 |
|
||||
| `bullets` | 블릿 리스트 | D2: 항목들 |
|
||||
| `image` | 이미지 | 시각 앵커 |
|
||||
| `preview` | 상세 preview | 표 헤더+행 |
|
||||
| `detail_link` | 자세히보기 링크 | 첨부 파일 연결 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 토큰 참조 방법
|
||||
|
||||
### 토큰 파일 위치
|
||||
```
|
||||
templates/styles/tokens/
|
||||
├── typography.css ← 글자 위계
|
||||
├── spacing.css ← 여백/간격
|
||||
└── colors.css ← 색상
|
||||
```
|
||||
|
||||
### 사용법
|
||||
```css
|
||||
/* 블록 CSS에서 */
|
||||
.my-block-title {
|
||||
font-size: var(--font-sub-title);
|
||||
font-weight: var(--weight-sub-title);
|
||||
line-height: var(--lh-sub-title);
|
||||
color: var(--color-zone-title);
|
||||
margin-bottom: var(--heading-gap);
|
||||
}
|
||||
|
||||
.my-block-body {
|
||||
font-size: var(--font-body);
|
||||
color: var(--color-body);
|
||||
padding-left: var(--bullet-indent);
|
||||
text-indent: calc(var(--bullet-indent) * -1);
|
||||
}
|
||||
```
|
||||
|
||||
### 블록 의미색이 필요할 때
|
||||
공통 테마색으로 안 되는 역할색은 colors.css의 2층 의미색을 참조.
|
||||
```css
|
||||
/* 3열 비교의 열별 색상 */
|
||||
.col-1 .bar { background: linear-gradient(180deg, var(--color-col-1-from), var(--color-col-1-to)); }
|
||||
.col-2 .bar { background: linear-gradient(180deg, var(--color-col-2-from), var(--color-col-2-to)); }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 블록 HTML 예시
|
||||
|
||||
### 좋은 예
|
||||
```html
|
||||
<section class="block block-3col">
|
||||
<div class="col">
|
||||
<div class="sub-title">{{ col.title }}</div>
|
||||
<div class="bul">• {{ col.desc }}</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<style>
|
||||
.block-3col {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(3, 1fr);
|
||||
gap: var(--card-gap);
|
||||
}
|
||||
.block-3col .col {
|
||||
padding: var(--card-padding);
|
||||
background: var(--color-bg-subtle);
|
||||
border: 1px solid var(--color-border);
|
||||
border-radius: var(--card-radius);
|
||||
}
|
||||
</style>
|
||||
```
|
||||
|
||||
### 나쁜 예
|
||||
```html
|
||||
<!-- NG: 직접값 하드코딩 -->
|
||||
<div style="font-size:12px; color:#1e293b; padding:16px; background:#f8fafc; border-radius:6px;">
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 전환 체크리스트
|
||||
|
||||
Figma 1:1 HTML → 재사용 블록으로 전환할 때:
|
||||
|
||||
- [ ] font-size 직접값 → `var(--font-*)` 교체
|
||||
- [ ] color 직접값 → `var(--color-*)` 교체
|
||||
- [ ] padding/margin 직접값 → semantic spacing 또는 `var(--space-*)` 교체
|
||||
- 카드 내부: `var(--card-padding)`
|
||||
- 블릿 들여쓰기: `var(--bullet-indent)`
|
||||
- 소제목 아래: `var(--heading-gap)`
|
||||
- 일반 여백: `var(--space-sm)`, `var(--space-md)` 등
|
||||
- [ ] gap → `var(--card-gap)`, `var(--flex-gap)` 등
|
||||
- [ ] border-radius → `var(--card-radius)` 교체
|
||||
- [ ] 공통 클래스 사용 (`.bul`, `.sub-title` 등)
|
||||
- [ ] 블록 고유 요소에 prefix 클래스
|
||||
- [ ] catalog에 슬롯/구조/호환 정보 등록
|
||||
@@ -1,183 +0,0 @@
|
||||
# Frame Integration Map — 32 Figma Frame ↔ Phase Z Zone 통합 매핑
|
||||
|
||||
> **핵심 방향 (2026-04-28 정정)**
|
||||
>
|
||||
> Figma frame 은 슬라이드에 **원본 그대로 꽂는 게 아니라**, **디자인 레퍼런스 / 구조 패턴 / 슬롯 힌트**로 본다.
|
||||
> **최종 결과는 항상 현재 slide-body 의 Zone 안에 맞게 재구성한다.**
|
||||
>
|
||||
> - 원본이 full-slide 디자인이어도 → Zone 안 맞게 축약 / 재배치 / 슬롯화해서 사용
|
||||
> - 복합 슬라이드여도 → Zone 안에서는 일부 패턴만 참고해 재구성
|
||||
>
|
||||
> → 분류는 **"원본 크기"** 가 아니라 **"Zone 에 어떻게 적용할지"** 기준으로 한다.
|
||||
|
||||
---
|
||||
|
||||
## 라벨 정의
|
||||
|
||||
### Zone 적용 방식 (zone_application)
|
||||
|
||||
| 값 | 의미 |
|
||||
|---|---|
|
||||
| `zone_direct` | Zone 안에 거의 그대로 적용 가능 (구조 / 사이즈 변환 최소) |
|
||||
| `zone_adapt` | 구조는 맞지만 Zone 크기에 맞게 재구성 필요 |
|
||||
| `zone_extract` | 전체 frame 중 일부 패턴만 추출해서 Zone 에 사용 |
|
||||
| `reference_only` | 직접 구조로 쓰기보다 디자인 톤 / 아이디어만 참고 |
|
||||
| `reject` | Phase Z 에서 사용하지 않음 |
|
||||
|
||||
### Zone 적합성 (zone_fit)
|
||||
|
||||
| 값 | 의미 |
|
||||
|---|---|
|
||||
| `high` | Zone 에 바로 맞추기 쉬움 (단순 리스트 / 표 등) |
|
||||
| `medium` | 조정하면 가능 (3 단 카드 / 다이어그램 등) |
|
||||
| `low` | 많이 재구성해야 함 (복합 구조 / 분할 패널) |
|
||||
| `reference` | 참고용 |
|
||||
|
||||
### 검토 상태 (review_status)
|
||||
|
||||
| 값 | 의미 |
|
||||
|---|---|
|
||||
| `auto_estimated` | 코드가 layout 패턴으로 추정. 사용자 검토 필요 |
|
||||
| `user_confirmed` | 사용자 검토 후 확정 |
|
||||
| `needs_review` | 자동 추정에 의문 — 사람이 Figma 캔버스 직접 확인 필요 |
|
||||
|
||||
---
|
||||
|
||||
## 1차 — 32 Frame Zone 적용 분류
|
||||
|
||||
> ⚠️ **`legacy 스타일 출처(참고)` 컬럼 의미**
|
||||
>
|
||||
> 기존 `templates/blocks/` 는 **Phase Z 의 실제 조립 재료가 아님** (삭제 / 폐기 방향).
|
||||
> 이 컬럼은 **frame ↔ 블록 매핑이 아니라**, frame 의 디자인 / 시각 언어를 만들 때 참고할 수 있는 **스타일 출처** (색감, 여백, 폰트 위계, 표 스타일, 카드 스타일, pill / badge, SVG / CSS 구현 힌트) 만 가리킨다.
|
||||
>
|
||||
> Phase Z 의 실제 실행 기준은 **새 frame / zone catalog**.
|
||||
> 정밀화는 [`PHASE-Z-STYLE-SOURCES.md`](PHASE-Z-STYLE-SOURCES.md) (예정) 에서 별도 진행.
|
||||
|
||||
| Frame | Figma ID | 패턴 | Zone 적합성 | Zone 적용 방식 | 검토 상태 | legacy 스타일 출처(참고) | 비고 |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| **01** | `1171281172` | `circular-nodes-6` | `medium` | `zone_adapt` | `auto_estimated` | `templates/blocks/visuals/` (다이어그램) | S/W 개발 방향 순환도. 6 노드 — Zone 사이즈에 맞춰 시각 재구성 |
|
||||
| **02** | `1171281173` | `bullet-cards-4-plus-center` | `low` | `zone_extract` | `auto_estimated` | (복합 — 일부 패턴 추출) | 4 카드 + 중앙 강조. Zone 에서는 4 카드 부분만 추출하거나 중앙만 강조로 사용 |
|
||||
| **03** | `1171281174` | `list-numbered-4` | `high` | `zone_direct` | `auto_estimated` | `templates/blocks/cards/` 또는 list 류 | 4 항목 번호 리스트 — 단순 구조, Zone 직접 적용 |
|
||||
| **04** | `1171281175` | `quadrilateral-relations` | `medium` | `zone_extract` | `user_confirmed` | (관계도 — 기존 venn / cycle 로 부족 가능) | 4 actors + 관계도 + hierarchy 단계 결합된 복합형. 큰 Zone 에서는 zone_adapt 가능, 기본은 actor / hierarchy 패턴 추출 |
|
||||
| **05** | `1171281176` | `side-card-with-list` | `medium` | `zone_extract` | `auto_estimated` | (좌우 분할 — 일부 추출) | 좌측 카드 + 우측 리스트. Zone 안에서 좌·우 패턴 추출 |
|
||||
| **06** | `1171281177` | `full-page-map-banner` | `reference` | `reference_only` | `user_confirmed` | (콘텐츠 슬롯형 X — 참고용) | 지도 / 마커 / 현황 시각자료 중심. 일반 텍스트 Zone 구조로 직접 사용 X. 지도형 콘텐츠가 있을 때 디자인 참고 |
|
||||
| **07** | `1171281178` | `2col-paired-list` | `high` | `zone_adapt` | `auto_estimated` | `templates/blocks/tables/` 또는 페어드 | 2 컬럼 페어드 리스트 — Zone 사이즈 맞춰 표 재구성 |
|
||||
| **08** | `1171281179` | `3-section-framework` | `medium` | `zone_extract` | `auto_estimated` | (3 섹션 — 일부 추출) | 효율적 정보 관리 (What/How/When). 3 섹션 패턴 추출 |
|
||||
| **09** | `1171281180` | `list-stacked-vertical` | `high` | `zone_direct` | `auto_estimated` | `templates/blocks/cards/` 또는 list 류 | 5 항목 세로 리스트 — Zone 직접 적용 |
|
||||
| **10** | `1171281181` | `radial-diagram-5` | `medium` | `zone_adapt` | `auto_estimated` | `templates/blocks/visuals/` | 5 way 방사형 다이어그램 — Zone 시각 재구성 |
|
||||
| **11** | `1171281182` | `cards-3-category` | `medium` | `zone_extract` | `auto_estimated` | (3 카드 — 패턴 추출) | 시공단계 BIM 활용 — 3 카드 패턴 추출 |
|
||||
| **12** | `1171281189` | `cycle-3way-intersection` | `medium` | `zone_adapt` | `auto_estimated` | `templates/blocks/visuals/venn-diagram.html` | 3 way 벤다이어그램. Zone 사이즈 맞춰 SVG 재구성 |
|
||||
| **13** | `1171281190` | `3-column` | `medium` | `zone_extract` | `auto_estimated` | (3 단 — 패턴 추출) | 필수조건 (pillar 3). Zone 안에 3 단 패턴 추출. 02-2.2 매칭 실패 정답 frame (3차 대상) |
|
||||
| **14** | `1171281191` | `persona-3col` | `medium` | `zone_extract` | `auto_estimated` | `templates/blocks/cards/card-text-grid.html` (참고) | 주체별 기대효과. Zone 안에서 3 카드 패턴 추출 |
|
||||
| **15** | `1171281192` | `policy-4card-plus-list` | `low` | `zone_extract` | `auto_estimated` | (복합 — 일부 추출) | 4 카드 + 부속 리스트. Zone 안에서 4 카드만 추출하거나 리스트만 사용 |
|
||||
| **16** | `1171281193` | `quadrant-4` | `medium` | `zone_extract` | `auto_estimated` | (4 사분면 — 패턴 추출) | BIM 수행 이슈 4사분면. 4 사분면 패턴 추출 |
|
||||
| **17** | `1171281194` | `paired-rows-2x2` | `high` | `zone_adapt` | `auto_estimated` | `templates/blocks/tables/` | 2x2 페어드 행 — Zone 표 재구성 |
|
||||
| **18** | `1171281195` | `compare-rows` | `high` | `zone_adapt` | `auto_estimated` | `templates/blocks/tables/compare-3col-badge.html` (참고) | BIM·DX 비교. 매칭 시스템 검증된 대표 frame. Zone 안 표 재구성 |
|
||||
| **19** | `1171281197` | `cards-3-compare` | `medium` | `zone_extract` | `auto_estimated` | (3 단 비교 — 패턴 추출) | 설계방식 왜곡 — 3 비교 패턴 추출 |
|
||||
| **20** | `1171281198` | `cards-3-header` | `medium` | `zone_extract` | `auto_estimated` | (3 헤더형 — 패턴 추출) | DX 는 S/W 가 필수 — 3 헤더 패턴 추출 |
|
||||
| **21** | `1171281201` | `split-panel-diagram` | `low` | `zone_extract` | `auto_estimated` | (분할 패널 — 패턴 추출) | Solution Engn. S/W. 분할 패널 패턴 일부 추출 |
|
||||
| **22** | `1171281202` | `split-panel-numbered` | `low` | `zone_extract` | `auto_estimated` | (분할 패널 + 번호 — 패턴 추출) | Model 특화 Engn. S/W. 분할 + 번호 패턴 추출 |
|
||||
| **23** | `1171281203` | `table-2col` | `high` | `zone_adapt` | `auto_estimated` | `templates/blocks/tables/` | Application S/W 의 구분. **table family 중복 — variant 통합 검토** |
|
||||
| **24** | `1171281204` | `table-3col` | `high` | `zone_adapt` | `auto_estimated` | `templates/blocks/tables/` | Engn. S/W 구성과 특징. **table family 중복 — variant 통합 검토** |
|
||||
| **25** | `1171281205` | `left-categories-right-logos` | `medium` | `zone_extract` | `auto_estimated` | (좌우 분할 — 패턴 추출) | 상용 Engn. S/W. 좌우 분할 패턴 추출 |
|
||||
| **26** | `1171281206` | `cards-4-grid` | `medium` | `zone_extract` | `auto_estimated` | (4 카드 — 패턴 추출) | 상용 S/W 의존 4 대 문제. 4 카드 그리드 추출 |
|
||||
| **27** | `1171281208` | `central-split-synthesis` | `low` | `zone_extract` | `auto_estimated` | (중앙 합성 — 일부 추출) | 건설산업 고부가가치화. 중앙 + 양쪽 패턴 일부 추출 |
|
||||
| **28** | `1171281209` | `title-plus-3-emphasis` | `medium` | `zone_extract` | `auto_estimated` | (제목 + 3 강조 — 패턴 추출) | 현존 상용 S/W 의 현실. 제목 + 3 카드 패턴 추출 |
|
||||
| **29** | `1171281210` | `banner-top-2col-bottom` | `low` | `zone_extract` | `auto_estimated` | (banner + 2col 복합 — 패턴 추출) | Process/Product 혁신 (AS-IS/TO-BE). Zone 안에서 banner + 2col 패턴만 추출 |
|
||||
| **30** | `1171281211` | `table-3col` | `high` | `zone_adapt` | `auto_estimated` | `templates/blocks/tables/` | 산업별 현황. **table family 중복 — variant 통합 검토** |
|
||||
| **31** | `1171281212` | `table-3col` | `high` | `zone_adapt` | `auto_estimated` | `templates/blocks/tables/` | 산업별 특성과 발전방향. **table family 중복 — variant 통합 검토** |
|
||||
| **32** | `1171281213` | `central-5-goals` | `low` | `zone_extract` | `auto_estimated` | (5 목표 복합 — 일부 추출) | 정책 달성. 중앙 5 목표 패턴 일부 추출 |
|
||||
|
||||
---
|
||||
|
||||
## 자동 추정 룰
|
||||
|
||||
### layout 패턴 → Zone 적용 방식
|
||||
|
||||
| 패턴 / family | Zone 적용 방식 | Zone 적합성 | 근거 |
|
||||
|---|---|---|---|
|
||||
| `list-*` (단순 리스트) | `zone_direct` | `high` | 구조 단순 — Zone 안 그대로 |
|
||||
| `compare-rows` / `table-*col` / `paired-rows-*` (표 / 페어드) | `zone_adapt` | `high` | 표 구조 — Zone 사이즈 맞춰 재구성 |
|
||||
| `cycle-*` / `circular-*` / `radial-*` / `quadrilateral-*` (시각 다이어그램) | `zone_adapt` | `medium` | 시각 디자인 — Zone 사이즈 맞춰 SVG 재구성 |
|
||||
| `cards-3-*` / `persona-3col` / `3-column` / `cards-4-grid` / `quadrant-4` / `3-section-*` (3·4 단 카드 / 칼럼) | `zone_extract` | `medium` | 패턴 일부 추출 (카드 / 칼럼) |
|
||||
| `side-*` / `left-*-right-*` / `title-plus-*` (좌우 / 제목+카드) | `zone_extract` | `medium` | 부분 패턴 추출 |
|
||||
| `banner-top-*-bottom` / `bullet-cards-*-plus-center` / `policy-*-plus-list` (복합) | `zone_extract` | `low` | 복합 구조 — Zone 에서는 일부만 추출 |
|
||||
| `split-panel-*` / `central-*` (분할 / 중앙 합성) | `zone_extract` | `low` | 새 시각 패턴 — 일부 추출 |
|
||||
| `full-page-map-*` (지도 / 배너) | `reference_only` | `reference` | 콘텐츠 슬롯형 X — 디자인 참고만 |
|
||||
|
||||
---
|
||||
|
||||
## 분포 요약
|
||||
|
||||
### Zone 적용 방식
|
||||
|
||||
| 적용 방식 | 개수 | Frame |
|
||||
|---|---|---|
|
||||
| `zone_direct` | **2** | 03, 09 |
|
||||
| `zone_adapt` | **11** | 01, 04, 07, 10, 12, 17, 18, 23, 24, 30, 31 |
|
||||
| `zone_extract` | **18** | 02, 05, 08, 11, 13, 14, 15, 16, 19, 20, 21, 22, 25, 26, 27, 28, 29, 32 |
|
||||
| `reference_only` | **1** | 06 |
|
||||
| `reject` | **0** | — |
|
||||
|
||||
**합계 검증** : 2 + 11 + 18 + 1 + 0 = **32** ✓
|
||||
|
||||
### Zone 적합성
|
||||
|
||||
| 적합성 | 개수 | Frame |
|
||||
|---|---|---|
|
||||
| `high` | **9** | 03, 07, 09, 17, 18, 23, 24, 30, 31 |
|
||||
| `medium` | **15** | 01, 04, 05, 08, 10, 11, 12, 13, 14, 16, 19, 20, 25, 26, 28 |
|
||||
| `low` | **7** | 02, 15, 21, 22, 27, 29, 32 |
|
||||
| `reference` | **1** | 06 |
|
||||
|
||||
**합계 검증** : 9 + 15 + 7 + 1 = **32** ✓
|
||||
|
||||
### 검토 상태
|
||||
|
||||
| review_status | 개수 | Frame |
|
||||
|---|---|---|
|
||||
| `auto_estimated` | **30** | (04, 06 제외 모두) |
|
||||
| `needs_review` | **0** | (04, 06 사용자 확정 완료) |
|
||||
| `user_confirmed` | **2** | **04** (zone_extract 확정), **06** (reference_only 확정) |
|
||||
|
||||
---
|
||||
|
||||
## 핵심 메시지
|
||||
|
||||
> **모든 frame 은 최종적으로 Zone 에 맞게 들어간다.**
|
||||
> **원본이 full-slide 인지 아닌지는 참고 정보일 뿐, 최종 사용 단위는 Zone 이다.**
|
||||
>
|
||||
> - 사용자가 의미한 "needs_split" = 실제 의미는 `zone_extract` 또는 `zone_adapt`
|
||||
> - frame 은 디자인 레퍼런스 / 구조 패턴 / 슬롯 힌트
|
||||
> - Phase Z output 은 항상 Zone 에 맞는 재구성 결과
|
||||
|
||||
---
|
||||
|
||||
## 다음 단계
|
||||
|
||||
### ✅ 완료 (1 차)
|
||||
- 32 frame 자동 추정 표 작성
|
||||
- Frame 04, 06 사용자 확정 (`user_confirmed`)
|
||||
- 컬럼명 정정 : `legacy 대응 블록(참고, 미검증)` → `legacy 스타일 출처(참고)`
|
||||
|
||||
### ✅ 완료 (2 차, 2026-04-28) — Phase Z Frame Style Inventory 작성
|
||||
|
||||
산출물 : [`PHASE-Z-FRAME-STYLE-INVENTORY.md`](PHASE-Z-FRAME-STYLE-INVENTORY.md)
|
||||
|
||||
- Source Policy : 메인 (`figma_to_html_agent/blocks/` 32 frame) / 토큰 (`templates/styles/tokens/`) / legacy (`templates/blocks/structures/`)
|
||||
- Frame Inventory 32 행 (변환 14 + 미변환 18 보일러플레이트)
|
||||
- Token Inventory 18 행 (`covered` 7 / `gap_candidate` 5 / `hierarchy_mapping_only` 3 / `hold_recheck_after_conversion` 3)
|
||||
- Legacy Reference 6 행 (모두 `delete_after_extract` 후보)
|
||||
|
||||
> ⚠️ inventory = **추출 / 검증 단계**. 실제 token 파일 생성 / 변경 / catalog 설계 / templates/blocks 삭제 등 **실행은 별도 승인 단계**.
|
||||
|
||||
### 후속 작업
|
||||
- **3차** — Frame 14 anchor_sets 재라벨링 (02-2.2 매칭 실패 교정 — 매칭 성능 교정 작업, 별도 진행)
|
||||
- **추가** — table family (23/24/30/31) variant 통합 설계 (Phase Z catalog 작성 시)
|
||||
- **확정 처리** — 2 차 조사 결과 후 high confidence frame 부터 `user_confirmed` 일괄 처리
|
||||
|
||||
---
|
||||
|
||||
## 부록 — 제외 / 특수 항목
|
||||
|
||||
`1171281171` 은 `texts.md` 만 존재하고 `index.html` / `analysis.md` 가 없어 Phase Z frame / style inventory 메인 대상에서 제외한다. 정체는 미확인.
|
||||
@@ -1,157 +0,0 @@
|
||||
# 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단계) ↓
|
||||
블록화 시 이 규칙에 맞춰 전환
|
||||
```
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,285 +0,0 @@
|
||||
# Phase Z — composition planning schema plan (Layer A + Layer B)
|
||||
|
||||
**Status** : v1 plan (2026-04-30 refactor — SPEC v1 의 Layer A + Layer B 구조 반영). schema 작업 *범위 / 순서 / 완료 기준* 정의. 구현 X.
|
||||
**Anchor** : [`PHASE-Z-PIPELINE-STATUS-BOARD.md`](PHASE-Z-PIPELINE-STATUS-BOARD.md) 의 핵심 missing — Step 3 / 4 / 11 + Step 10 (부분).
|
||||
|
||||
> **v0 → v1 변경 요약**
|
||||
> - SPEC v1 의 renumbered section 으로 cross-reference 일관 갱신 (§1 / §2 신규 / §3 / §4 / §5 …)
|
||||
> - Step 4 의 schema 가 SPEC v1 §2 (Internal Region — Layer A) 로 *이미 정의됨* → 본 plan 에서는 *신규 작성* 이 아니라 *완성도 점검* 으로 전환
|
||||
> - Step 11 의 schema 가 SPEC v1 §4 (2-stage placement: Stage A → Stage B) 로 재정의됨에 따라 validation 기준 보강
|
||||
> - mechanical rename : `sub_zone` → `Frame Slot` (PLAN 본문). YAML 필드명 `sub_zones` 는 코드 reality 로 유지
|
||||
> - 4 step 범위 (Step 3 / 4 / 10-partial / 11) 그대로. Step 10 의 density envelope 제외 그대로
|
||||
> - implementation / MDX 실행 검증 / AI 호출 / 파일명 변경 / code marker 이름 결정 — *모두 제외 그대로*
|
||||
|
||||
---
|
||||
|
||||
## 0. 문서 역할 분리
|
||||
|
||||
| 문서 | 역할 |
|
||||
|---|---|
|
||||
| [`PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md`](PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md) (v1) | schema / contract *명세 자체* (authoritative) |
|
||||
| **본 문서 (`PHASE-Z-CONTENT-OBJECT-SUBZONE-PLAN.md`)** (v1) | 그 schema 작업을 *어떤 범위 / 순서 / 산출물 / validation 기준* 으로 진행할지 *계획* |
|
||||
|
||||
본 plan 은 SPEC 을 *대체하지 않음*. SPEC 의 어느 section 이 어느 step 의 schema 인지 *cross-reference + 완성도 점검* 까지가 본 plan 의 영역.
|
||||
|
||||
---
|
||||
|
||||
## 1. 목적
|
||||
|
||||
일반 MDX 1 파일이 *render 전 단계* 에서 typed content_object → Internal Region → Frame Slot 으로 결정 가능한 상태에 도달하도록, 다음 4 step 의 schema 정의를 *완결* 시킨다.
|
||||
|
||||
```
|
||||
Step 3. Content Object 추출
|
||||
Step 4. Section Internal Composition Planning (Layer A)
|
||||
Step 10. Frame Contract 의 accepted_content_types + Frame Slot 선언 (부분, Layer B)
|
||||
Step 11. Content Unit / Child Group → Internal Region → Frame Slot Mapping (2-stage)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 범위
|
||||
|
||||
### 2.1 포함
|
||||
|
||||
| Step | schema 항목 | SPEC v1 의 위치 |
|
||||
|---|---|---|
|
||||
| Step 3 | content_object base schema + 6 type 별 schema (text_block / table / transform_table / image / diagram / details) | SPEC v1 §1.1, §1.2 |
|
||||
| Step 3 | role 의미 (summary / detail / decorative / reference) | SPEC v1 §1.3 |
|
||||
| Step 4 | Internal Region entity schema (region_id / role / content_type / ratio_estimate / content_unit_ids / frame_match_strategy) | SPEC v1 §2.1 |
|
||||
| Step 4 | Universal Region Model (every zone = 1+ regions) | SPEC v1 §2.2 |
|
||||
| Step 4 | 3-way decision tree (whole / group / split) | SPEC v1 §2.3 |
|
||||
| Step 4 | region 비율 산정 (content type 별 size proxy) | SPEC v1 §2.4 |
|
||||
| Step 4 | region → frame / display 매칭 interface (frame_match / display_only) | SPEC v1 §2.6 |
|
||||
| Step 10 | frame contract 의 `accepted_content_types` 필드 schema | SPEC v1 §3.1 |
|
||||
| Step 10 | Frame Slot 선언 schema (YAML 필드명 `sub_zones` — 의미 = Frame Slot) | SPEC v1 §3.1 |
|
||||
| Step 10 | F13 / F29 / F16 의 Frame Slots 선언 예시 | SPEC v1 §3.2 |
|
||||
| Step 11 | placement algorithm 2-stage I/O schema | SPEC v1 §4.1 |
|
||||
| Step 11 | Stage A — content → Internal Region (Layer A 매핑) | SPEC v1 §4.2 |
|
||||
| Step 11 | Stage B — Internal Region content → Frame Slot (Layer B 매핑) | SPEC v1 §4.3 |
|
||||
| Step 11 | tie-break (Frame Slot 단위) | SPEC v1 §4.4 |
|
||||
| Step 11 | display_only region 처리 (frame 우회) | SPEC v1 §4.5 |
|
||||
| Step 11 | display_strategy schema (inline_full / inline_preview_with_details / details_only / dropped) | SPEC v1 §5.1, §5.5 |
|
||||
| Step 11 | display_strategy 의 region-level + slot-level 양쪽 적용 | SPEC v1 §5.3 |
|
||||
|
||||
### 2.2 Step 10 의 *부분 범위* 명시 (불변)
|
||||
|
||||
> 본 plan 에서 Step 10 은 **두 항목** 까지만 다룸 :
|
||||
> - `accepted_content_types`
|
||||
> - Frame Slot 선언 (YAML 필드명 `sub_zones`)
|
||||
>
|
||||
> 본 plan 에서 *다루지 않는* Step 10 항목 :
|
||||
> - `density envelope`
|
||||
>
|
||||
> `density envelope` 은 `frame_internal_fit_candidate` (Step 17 / Step 19 Gap) 와 연결된 *frame internal fit policy* 영역. 본 plan 에 넣으면 *공통 padding 축소 antipattern* (`feedback_phase_z_spacing_direction`) 과 섞일 risk 있어 *별 plan* 으로 분리.
|
||||
>
|
||||
> 따라서 본 plan 이 완료되어도 Step 10 전체가 ✅ 완료되는 것은 아니고 — `accepted_content_types` + Frame Slot 부분만 ✅ / density envelope 부분은 ❌ 잔존.
|
||||
|
||||
### 2.3 명시적 제외
|
||||
|
||||
- 구현 (extractor / planner / parser 코드 작성) — 본 plan 은 schema 까지
|
||||
- frame partial template 변경 (Frame Slot / region container marker 추가)
|
||||
- mapper / classifier 의 region / Frame Slot-aware 진화
|
||||
- details / popup runtime
|
||||
- backward flow 자동화 (telemetry → composition 재호출)
|
||||
- MDX 01 / 02 / 03 / 04 적용 검증
|
||||
- AI 호출 (plan 단계 자체 + plan 산출 schema 자체 모두)
|
||||
- code / module / HTML marker / attribute *이름 결정* (SPEC v1 와 동일 — implementation step 에서 결정)
|
||||
- 파일명 변경 (PLAN / SPEC 둘 다 — 향후 별 결정)
|
||||
- 다음 단계 우선순위 / A/B/C 선택지
|
||||
|
||||
---
|
||||
|
||||
## 3. 산출물
|
||||
|
||||
### 3.1 schema-side 산출물
|
||||
|
||||
본 plan 의 schema 작업이 완료되면, SPEC v1 가 다음 상태에 도달 :
|
||||
|
||||
| schema | 현재 SPEC v1 상태 | plan 종료 후 목표 상태 |
|
||||
|---|---|---|
|
||||
| content_object base + 6 type 별 schema | draft (SPEC v1 §1.1, §1.2) | completeness reviewed + gaps listed |
|
||||
| role 의미 4 종 | draft (SPEC v1 §1.3) | completeness reviewed + gaps listed |
|
||||
| Internal Region entity + Universal Region Model | draft (SPEC v1 §2.1, §2.2) | completeness reviewed + gaps listed |
|
||||
| 3-way decision tree | draft (SPEC v1 §2.3) | completeness reviewed + gaps listed |
|
||||
| region 비율 산정 | draft (SPEC v1 §2.4) | completeness reviewed + gaps listed |
|
||||
| region → frame / display 매칭 interface | draft (SPEC v1 §2.6) | completeness reviewed + gaps listed |
|
||||
| accepted_content_types + Frame Slot 선언 | draft (SPEC v1 §3.1, 3 frame 예시 §3.2) | completeness reviewed + gaps listed |
|
||||
| 2-stage placement (Stage A + Stage B I/O) | draft (SPEC v1 §4.1, §4.2, §4.3) | completeness reviewed + gaps listed |
|
||||
| tie-break + display_only region 처리 | draft (SPEC v1 §4.4, §4.5) | completeness reviewed + gaps listed |
|
||||
| display_strategy 4 종 + region/slot 양쪽 적용 | draft (SPEC v1 §5.1, §5.3, §5.5) | completeness reviewed + gaps listed |
|
||||
|
||||
### 3.2 plan-side 산출물
|
||||
|
||||
- 본 PLAN 문서 (v1) — schema 작업 범위 정의
|
||||
- 작업 결과로 SPEC v1 의 *추가 / 수정 부분* (edge case 보강 등 — substantive 신규 schema 가 아닌 점검 결과)
|
||||
- pipeline data flow 위치 표 (§5 참조)
|
||||
- schema validation 기준 표 (§6 참조)
|
||||
|
||||
---
|
||||
|
||||
## 4. SPEC ↔ PLAN cross-reference
|
||||
|
||||
본 plan 의 4 step 각각이 SPEC v1 의 어느 section 으로 매핑되는지 :
|
||||
|
||||
| Step | SPEC v1 section | plan 에서의 작업 |
|
||||
|---|---|---|
|
||||
| Step 3 | §1 (content_object schema) | *완성도 점검*. nested_list / sub-decomposition edge case (SPEC v1 §9.2 미해결 부분 — text_block 의 nested 구조를 sub_text_block 으로 sub-decompose vs Frame Slot cardinality aggregate 해석) |
|
||||
| Step 4 | §2 (Internal Region schema, Layer A) | *완성도 점검*. 3-way decision 의 boundary 케이스 / region 비율의 fallback / frame_match_strategy 가 unknown / ambiguous 일 때 거동 |
|
||||
| Step 10 (partial) | §3.1 (schema) + §3.2 (3 frame 예시) | *완성도 점검*. `density envelope` 미포함 명시 |
|
||||
| Step 11 | §4 (placement algorithm 2-stage) + §5 (display strategy) | *완성도 점검*. Stage A → Stage B *interface* 정합 (Stage A 의 frame_match_strategy 가 Stage B 의 입력으로 자연 호환) / backward flow 자동화 X 등 v1 한계 재확인 |
|
||||
|
||||
---
|
||||
|
||||
## 5. Pipeline data flow 위치
|
||||
|
||||
본 4 step 의 schema 가 *어디서 생성 / 누가 소비* 하는지.
|
||||
|
||||
```
|
||||
Step 1 MDX 업로드
|
||||
↓
|
||||
Step 2 MDX 정규화 (section / heading / raw_content 분리)
|
||||
↓
|
||||
├─→ Step 3. Content Object 추출
|
||||
│ INPUT : section.raw_content (markdown 문자열)
|
||||
│ OUTPUT : section.content_objects = [ContentObject ...]
|
||||
│ SCHEMA : SPEC v1 §1
|
||||
│ 소비자 : Step 4, Step 11
|
||||
│
|
||||
└─→ Step 4. Section Internal Composition Planning (Layer A)
|
||||
INPUT : section.content_objects (from Step 3) + section metadata + V4 evidence
|
||||
OUTPUT : zone.internal_regions = [
|
||||
{region_id, role, content_type, ratio_estimate,
|
||||
content_unit_ids, frame_match_strategy}, ...
|
||||
]
|
||||
SCHEMA : SPEC v1 §2 (entity / Universal Region Model / 3-way decision / 비율 / interface)
|
||||
소비자 : Step 6 (composition planning) / Step 8 (region ratio) /
|
||||
Step 9 (region-level frame match) / Step 11 (Stage A 결과)
|
||||
|
||||
Step 5 Matching Evidence 생성 (V4 top-k)
|
||||
Step 6 Composition Planning (Step 4 region 분할 결과 입력)
|
||||
Step 7 Slide-Level Layout Planning
|
||||
Step 8 Zone + Internal Region Ratio Planning (region 비율 = Step 4 산출)
|
||||
Step 9 Region-Level Frame / Display Selection (region 별 frame_match_strategy = Step 4 산출)
|
||||
↓
|
||||
└─→ Step 10 (partial). Frame Contract 확인
|
||||
INPUT : selected frame_id (region 별)
|
||||
OUTPUT : frame_contract.accepted_content_types
|
||||
+ frame_contract.sub_zones (= Frame Slots, Layer B)
|
||||
SCHEMA : SPEC v1 §3
|
||||
소비자 : Step 11 (Stage B)
|
||||
|
||||
↓
|
||||
└─→ Step 11. Content Unit / Child Group → Internal Region → Frame Slot Mapping (2-stage)
|
||||
INPUT : section.content_objects (from Step 3)
|
||||
+ zone.internal_regions (from Step 4)
|
||||
+ frame_contract.sub_zones (= Frame Slots) (from Step 10, frame_match region 만)
|
||||
Stage A : content → Internal Region (Step 4 의 region 분할 결과 소비)
|
||||
Stage B : Internal Region content → Frame Slot (frame_match region 만 진입)
|
||||
display_only region → display strategy 처리 (Stage B 우회)
|
||||
OUTPUT : placement = {
|
||||
internal_regions: [
|
||||
{..., slot_assignments[], overflow_buffer[], rejection[]}, ...
|
||||
]
|
||||
}
|
||||
SCHEMA : SPEC v1 §4 + §5
|
||||
소비자 : Step 12 (slot payload 생성, region + Frame Slot 단위 grouping)
|
||||
|
||||
Step 12 Slot Payload 생성
|
||||
Step 13 Render
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. schema validation 기준
|
||||
|
||||
> validation = *schema 자체의 구조 검증* 까지만. *실제 MDX 적용 검증 X* (sample budget rule).
|
||||
|
||||
### 6.1 Step 3 — content_object schema
|
||||
|
||||
- [ ] base schema 의 모든 필수 필드 (id, type, role, size_estimate, raw_payload, type_specific) 정의됨
|
||||
- [ ] 6 type 모두 type_specific schema 있음 (text_block / table / transform_table / image / diagram / details)
|
||||
- [ ] role 4 종 (summary / detail / decorative / reference) 정의됨
|
||||
- [ ] role 별 fallback 거동 (decorative drop / detail → details escalate / summary·reference rejection) 명시됨
|
||||
- [ ] *원문 raw_payload 보존* 룰이 schema 에 포함됨 (자름 / 변형 X)
|
||||
|
||||
### 6.2 Step 4 — Internal Region schema (Layer A)
|
||||
|
||||
- [ ] Internal Region entity 의 모든 필수 필드 (region_id, role, content_type, ratio_estimate, content_unit_ids, frame_match_strategy) 정의됨
|
||||
- [ ] Universal Region Model 명시 (every zone has 1+ regions / single-region for text-only / multi-region for mixed-content)
|
||||
- [ ] 3-way decision tree 의 3 분기 (whole-section frame match / child-section grouping / content-type split) 가 *결정론적 함수* 로 표현됨 (AI 판단 X)
|
||||
- [ ] 각 분기의 판단 기준 (cardinality / accepted_content_types / heading depth + content 구조) 명시됨
|
||||
- [ ] region 비율 산정의 size proxy (text_block: line_count / table: rows × line_height / transform_table: pair_count × pair_height / image: aspect_ratio / details: summary line_count) 정의됨
|
||||
- [ ] zone 내 region ratio 합 = 1.0 normalize 룰 명시됨
|
||||
- [ ] frame_match_strategy 의 두 kind (frame_match / display_only) 정의됨
|
||||
- [ ] display_only path 가 frame contract 없이 동작 가능함이 명시됨
|
||||
- [ ] decision 이 unknown / ambiguous 일 때의 fallback 명시됨
|
||||
|
||||
### 6.3 Step 10 (partial) — frame contract schema (Layer B 선언)
|
||||
|
||||
- [ ] `accepted_content_types` 필드 schema 정의됨 (list of type 이름)
|
||||
- [ ] `not_accepted` 필드 schema 정의됨 (디버그용)
|
||||
- [ ] Frame Slot 선언 schema 정의됨 (id / role / accepts / cardinality / partial_target_path) — YAML 필드명 `sub_zones`, 의미 = Frame Slot
|
||||
- [ ] cardinality 표현 방식 (`strict` 또는 `min`/`max`) 정의됨
|
||||
- [ ] F13 / F29 / F16 3 frame 의 Frame Slot declaration 예시 *완비*
|
||||
- [ ] *density envelope 미포함* 이 schema 위에 명시 주석으로 박혀 있음
|
||||
|
||||
### 6.4 Step 11 — placement (2-stage) + display_strategy schema
|
||||
|
||||
- [ ] placement algorithm 2-stage I/O schema 정의됨 (input + Stage A 출력 + Stage B 출력)
|
||||
- [ ] Stage A schema 정의됨 (content_object → Internal Region 매핑 결과 + frame_match_strategy 결정)
|
||||
- [ ] Stage B schema 정의됨 (Internal Region content → Frame Slot 매핑 결과 — frame_match region 만)
|
||||
- [ ] sorting / type 매칭 / cardinality 적용 / role 우선순위 / tie-break 의 결정론적 룰 (Stage B) 명시됨
|
||||
- [ ] display_only region path 의 display_strategy 매핑 정의됨 (image area / table preview / details button / diagram inline)
|
||||
- [ ] 6 type × 3 escalation (inline / preview+details / popup-only) 매트릭스 정의됨
|
||||
- [ ] display_strategy 4 종 (inline_full / inline_preview_with_details / details_only / dropped) 정의됨
|
||||
- [ ] display_strategy 가 *region-level + slot-level 둘 다* 적용됨이 명시됨
|
||||
- [ ] *AI 호출 X* + *원문 손실 금지* 룰이 schema 위에 명시됨
|
||||
- [ ] backward flow 자동화 X (v1 한계) 가 schema 위에 명시됨
|
||||
|
||||
### 6.5 통합 validation
|
||||
|
||||
- [ ] Step 3 → Step 4 의 type 호환 — content_object.type 이 Internal Region.content_type 으로 *결정론적* 매핑
|
||||
- [ ] Step 3 → Step 11 (Stage B) 의 type 호환 — Step 3 의 모든 type 이 어딘가 frame.accepted_content_types 에 등장 가능 (또는 명시적 reject) 또는 display_only path 로 처리 가능
|
||||
- [ ] Step 4 → Step 8 의 ratio 호환 — Internal Region.ratio_estimate 가 Step 8 의 region-level ratio 입력으로 호환
|
||||
- [ ] Step 4 → Step 9 의 frame_match_strategy 호환 — Step 9 의 region-level frame 매칭 입력으로 호환
|
||||
- [ ] Step 4 → Step 11 (Stage A) 의 region 분할 호환 — Stage A 가 Step 4 의 internal_regions 를 *재계산하지 않고 그대로 소비*
|
||||
- [ ] Step 10 의 cardinality 가 Step 11 Stage B 의 placement algorithm 이 소비 가능한 형태
|
||||
|
||||
---
|
||||
|
||||
## 7. AI 원칙
|
||||
|
||||
- 본 plan 작성 / schema 정의 단계 — **AI 호출 없음**
|
||||
- runtime AI = Step 12 의 *light_edit / restructure 의 content_object → Internal Region / Frame Slot proposal* 1 곳만
|
||||
- Step 0 (Figma → HTML 변환 등 사전 준비) 의 AI 사용은 *precondition phase* 로, runtime AI 가 아님
|
||||
|
||||
---
|
||||
|
||||
## 8. 금지
|
||||
|
||||
- 구현 금지 (extractor / planner / parser 코드 작성)
|
||||
- render 변경 금지
|
||||
- frame partial 변경 금지 (Frame Slot / region container marker 추가 미포함)
|
||||
- mapper / classifier 의 region / Frame Slot-aware 진화 금지
|
||||
- details / popup runtime 작성 금지
|
||||
- MDX 01 / 02 / 03 / 04 실행 금지
|
||||
- AI 호출 금지
|
||||
- code / module / HTML marker / attribute *이름 결정* 금지 (SPEC v1 와 동일 — implementation step 에서 결정)
|
||||
- 파일명 변경 금지
|
||||
- next step 추천 금지
|
||||
- 우선순위 결정 금지
|
||||
- A / B / C 선택지 제시 금지
|
||||
|
||||
---
|
||||
|
||||
## 9. 본 plan 의 보존 / 변경 정책
|
||||
|
||||
- 본 plan 은 *schema 작업 범위 + 완료 기준* 의 기준점. schema 작업 진행 중 새로운 edge case 발견 시 본 plan 의 6 절 (validation 기준) 에 *항목 추가* 형태로 갱신
|
||||
- *범위 확장* (예: Step 7 추가, density envelope 포함, code marker 이름 결정 포함) 은 사용자 명시 잠금 후에만
|
||||
- 본 plan 이 완료되면 STATUS-BOARD 의 :
|
||||
- Step 3 → ⚠ partial (schema 정의 완료, 구현 미완)
|
||||
- Step 4 → ⚠ partial (Layer A schema 정의 완료, 구현 미완)
|
||||
- Step 11 → ⚠ partial (2-stage schema 정의 완료, 구현 미완)
|
||||
- Step 10 → ⚠ partial (accepted_content_types + Frame Slot 부분 완료, density envelope 미포함 잔존)
|
||||
- SPEC 의 *추가 갱신* (edge case 보강 등) 은 본 plan 의 §3.1 목표 상태 (completeness reviewed + gaps listed) 의 자연 산출물
|
||||
@@ -1,849 +0,0 @@
|
||||
# Phase Z-2 — content composition planning spec (Layer A: Internal Region + Layer B: Frame Slot)
|
||||
|
||||
**Status** : v1 spec (2026-04-30 refactor — Layer A / Internal Region 추가 + Layer B / Frame Slot 명확화). 정의만. 구현은 별도 step (사용자 승인 후).
|
||||
|
||||
> **v0 → v1 변경 요약**
|
||||
> - Zone Internal Region (Layer A) 를 first-class entity 로 추가 (§2 신규)
|
||||
> - 기존 §2 ~ §8 → §3 ~ §9 로 renumber (v0 의 ## 9 다음 step → v1 의 ## 10)
|
||||
> - 기존 `sub_zone` 단어 = *Frame Slot (Layer B)* 의미로 일관 정리. *YAML 필드명 `sub_zones` 는 코드 reality 로 유지 — 의미만 명시*
|
||||
> - placement algorithm (§4) 을 *2-stage* (Stage A: content → Internal Region / Stage B: Internal Region content → Frame Slot) 로 재작성
|
||||
> - content_object schema (§1) / display strategy 어휘 (§5) / telemetry 구조 (§6) 는 *layer-agnostic 공유 개념* 으로 보호 — substantive 미변경
|
||||
> - code / module / HTML marker 이름은 *implementation step* 으로 defer
|
||||
|
||||
---
|
||||
|
||||
## §0. 목적 / 위치
|
||||
|
||||
본 spec 은 **render *전* composition planning layer** 의 정의. fit_classifier / overflow_router / zone_ratio_retry 같은 *post-render telemetry* 가 아니라, *애초에 content 를 어디에 어떻게 배치할지* 결정하는 *진짜 fit policy 의 중심*.
|
||||
|
||||
```
|
||||
1. PLANNING (composition) ← 본 spec 의 영역
|
||||
- section raw_content → content_object 정규화
|
||||
- Zone Internal Region (Layer A) 분할 — text/table/image/details 에 따라
|
||||
- frame contract → accepted_content_types + Frame Slot (Layer B) 선언
|
||||
- content_object → Internal Region → Frame Slot 배치 (compatibility 기반)
|
||||
- inline preview vs details/popup 표시 전략
|
||||
↓
|
||||
2. RENDER (Jinja2 + frame partial — Frame Slot aware)
|
||||
↓
|
||||
3. POST-RENDER TELEMETRY (A1~A4) ← 별 spec, 이미 구축됨
|
||||
- Selenium → fit_classifier → router → retry → failure_classifier → next_action
|
||||
- 1 단계 (본 spec 영역) 가 정밀하면 거의 trigger 안 됨
|
||||
- exception 케이스의 *진단 + 다음 capability 안내*
|
||||
```
|
||||
|
||||
### Layer 구분
|
||||
|
||||
```
|
||||
Slide → Zone → Internal Region → Frame → Frame Slot → Content
|
||||
──────────── ──────────
|
||||
Layer A Layer B
|
||||
```
|
||||
|
||||
- **Layer A — Zone Internal Region** : Zone *내부* 영역, frame *밖*. content type 기반 분할 (text region / table region / image region / details region). region 별 frame 또는 display strategy 선택.
|
||||
- **Layer B — Frame Slot** : frame *내부* 자리 (= F13 의 pillar_1, F29 의 process_column 등). frame 안에서 content unit 이 들어갈 곳.
|
||||
|
||||
Layer A 와 Layer B 는 *별개 entity* 가 아니라 *한 composition pipeline 의 두 sub-phase*. content_object schema / display strategy 어휘 / telemetry interface 는 *공유*.
|
||||
|
||||
### 본 spec 의 핵심 원칙
|
||||
|
||||
- *render 전* 결정. *render 후 retry* 가 아님
|
||||
- content_object 의 *type* 이 핵심 — text / table / image / diagram / details
|
||||
- Layer A 가 *region 분할* 결정 / Layer B 가 *region 안 Frame Slot 매핑* 결정
|
||||
- 매칭 안 되는 content 는 *details/popup 으로 escalate*. *원문 삭제 / 압축 X*
|
||||
- frame 의 *Frame Slot* 이 어떤 type 을 받을 수 있는지 *명시적으로 선언*
|
||||
|
||||
본 spec 은 *정의만*. 구현 우선순위는 별도 step (사용자 승인 후).
|
||||
|
||||
---
|
||||
|
||||
## §1. content_object 정규화 schema
|
||||
|
||||
> **layer-agnostic** — Layer A / Layer B 둘 다 사용. v0 → v1 refactor 시 *substantive 미변경*.
|
||||
|
||||
MDX section 의 `raw_content` (markdown 문자열) 를 *typed content_object list* 로 정규화.
|
||||
|
||||
### 1.1 base schema
|
||||
|
||||
```yaml
|
||||
section:
|
||||
section_id: str
|
||||
title: str
|
||||
content_objects:
|
||||
- id: str # section 내 unique
|
||||
type: str # text_block / table / image / diagram / details / transform_table
|
||||
role: str # summary / detail / decorative / reference
|
||||
size_estimate:
|
||||
line_count: int # text/details 의 경우
|
||||
rows: int # table 의 경우
|
||||
aspect_ratio: float # image/diagram 의 경우
|
||||
bytes: int # raw payload 크기 (heuristic용)
|
||||
raw_payload: str # 원본 (자름 / 변형 X)
|
||||
type_specific: {...} # 아래 type 별 schema
|
||||
```
|
||||
|
||||
### 1.2 type 별 schema
|
||||
|
||||
#### `text_block` — 자유 텍스트 / 불릿
|
||||
```yaml
|
||||
type: text_block
|
||||
type_specific:
|
||||
format: paragraph | bullet_list | nested_list
|
||||
bullet_count: int # 불릿이면
|
||||
max_indent_level: int
|
||||
has_emphasis: bool # **bold** 등 inline emphasis
|
||||
```
|
||||
|
||||
#### `table` — markdown 표
|
||||
```yaml
|
||||
type: table
|
||||
type_specific:
|
||||
rows: int # header 제외 데이터 row
|
||||
cols: int
|
||||
header_present: bool
|
||||
is_transform: bool # AS-IS / arrow / TO-BE 구조면 true → transform_table 으로 분류
|
||||
raw_md: str # 원본 markdown
|
||||
```
|
||||
|
||||
#### `transform_table` — AS-IS / TO-BE pair (`table` 의 specialization)
|
||||
```yaml
|
||||
type: transform_table
|
||||
type_specific:
|
||||
pair_count: int # 행 수 (각 행 = 1 transform pair)
|
||||
arrow_glyph: str # ➠ 등
|
||||
rows: [{from: str, arrow: str, to: str}]
|
||||
```
|
||||
|
||||
#### `image` — markdown / HTML 이미지
|
||||
```yaml
|
||||
type: image
|
||||
type_specific:
|
||||
src: str
|
||||
alt: str
|
||||
aspect_ratio: float | null # 알면 (asset metadata 에서)
|
||||
intrinsic_width_px: int | null
|
||||
intrinsic_height_px: int | null
|
||||
```
|
||||
|
||||
#### `diagram` — SVG / 도식
|
||||
```yaml
|
||||
type: diagram
|
||||
type_specific:
|
||||
source_type: svg_inline | svg_file | mermaid | other
|
||||
src: str | null
|
||||
```
|
||||
|
||||
#### `details` — `<details>/<summary>` 또는 ":::note[...]" 같은 명시 marker
|
||||
```yaml
|
||||
type: details
|
||||
type_specific:
|
||||
summary: str # 펼치기 전 보일 헤더
|
||||
body_raw: str # 펼친 후 content (자름 X)
|
||||
display_hint: button | inline_collapse | popup # MDX 가 hint 줄 수 있음
|
||||
```
|
||||
|
||||
### 1.3 role 의미
|
||||
|
||||
- `summary` — section 의 *핵심 메시지*. inline 으로 반드시 표시
|
||||
- `detail` — 보조 / 부연. 공간 부족 시 details 로 escalate 가능
|
||||
- `decorative` — 시각 보조 (배경 이미지 등). 공간 부족 시 *생략 가능*
|
||||
- `reference` — 출처 / footnote / 보충 자료
|
||||
|
||||
### 1.4 정규화 parser 위치
|
||||
|
||||
신규 module (이름 *implementation step 에서 결정* — defer) :
|
||||
- `extract_content_objects(section: MdxSection) -> list[ContentObject]`
|
||||
- markdown AST parser (예: mistune) 활용 또는 regex 기반 v0
|
||||
- 현재 `align_sections_to_v4_granularity` 다음 단계에 삽입
|
||||
|
||||
---
|
||||
|
||||
## §2. Zone Internal Region schema (Layer A — 신규)
|
||||
|
||||
본 section 은 **v1 신규**. Zone *내부* 영역 (frame *밖*) 의 entity 정의 + 3-way decision tree + region 비율 + region → frame/display interface.
|
||||
|
||||
### 2.1 Internal Region entity schema
|
||||
|
||||
```yaml
|
||||
zone:
|
||||
zone_id: str
|
||||
layout_position: str # top / bottom / left / right / ...
|
||||
internal_regions:
|
||||
- region_id: str # zone 내 unique
|
||||
role: str # primary / secondary / supporting / reference
|
||||
content_type: str # text / table / image / diagram / details / mixed
|
||||
ratio_estimate: float # 0.0 ~ 1.0 (zone 내 비율, 합 = 1.0)
|
||||
content_unit_ids: [str] # 이 region 에 배치된 content_object id 들 (Layer A → B 의 입력)
|
||||
frame_match_strategy: # region → frame/display 매칭 결과
|
||||
kind: str # frame_match | display_only
|
||||
frame_id: str | null # frame_match 이면 실제 frame
|
||||
display_strategy: str # inline_full | inline_preview_with_details | details_only | dropped
|
||||
```
|
||||
|
||||
### 2.2 Universal Region Model
|
||||
|
||||
```
|
||||
모든 Zone 은 1 개 이상의 Internal Region 을 가짐.
|
||||
|
||||
text-only zone = single-region zone (현 거동의 자연 표현)
|
||||
mixed-content zone = multi-region zone
|
||||
|
||||
각 Internal Region 은 *자기만의* frame match + display strategy 를 가질 수 있음.
|
||||
```
|
||||
|
||||
text-only section 도 *single-region zone* 으로 표현 (= 현 거동 보존). mixed-content (text + table / text + image / 등) 은 *multi-region zone* 으로 확장. region 이 *first-class entity* — special case 가 아님.
|
||||
|
||||
### 2.3 3-way decision tree
|
||||
|
||||
각 section 에 대해 *Internal Region 분할* 여부 결정 :
|
||||
|
||||
```
|
||||
section 전체 → 1 frame 매칭 가능?
|
||||
├ YES → whole-section frame match
|
||||
│ → single-region zone (region 1개, content_type=primary)
|
||||
│
|
||||
└ NO → child-section grouping 가능?
|
||||
├ YES → group merge → 1 frame 매칭
|
||||
│ → single-region zone (region 1개, content_type=primary)
|
||||
│
|
||||
└ NO → content-type split
|
||||
→ text region / table region / image region / details region
|
||||
→ region 비율 산정 (예: text 80% / table 20%)
|
||||
→ multi-region zone (region 2~N개)
|
||||
```
|
||||
|
||||
**판단 기준** :
|
||||
- *whole-section frame match* — section 전체와 frame contract 의 accepted_content_types 가 호환 + cardinality 가 맞는 경우
|
||||
- *child-section grouping* — sibling section 들이 같은 frame contract (예: F16 의 4-quadrant) 와 묶이는 경우. heading depth + content 구조 + frame cardinality 로 판단
|
||||
- *content-type split* — section 안에 *호환 안 되는 content type 조합* 이 있을 때 (text + table 처럼)
|
||||
|
||||
### 2.4 region 비율 산정
|
||||
|
||||
content type 별 *expected size* 기반 :
|
||||
|
||||
| content type | size proxy |
|
||||
|---|---|
|
||||
| `text_block` | line_count (text_block.size_estimate.line_count) |
|
||||
| `table` | rows × line_height_factor (rows × 1.2 ~ 1.5) |
|
||||
| `transform_table` | pair_count × pair_height |
|
||||
| `image` | aspect_ratio 기반 height (width 고정 시) |
|
||||
| `diagram` | aspect_ratio 기반 height |
|
||||
| `details` | summary line_count (펼치기 전) |
|
||||
|
||||
*zone 내 합 = 1.0* 으로 normalize. role 가중치 (primary > supporting) 는 v1 에서 균등 — *별 step refinement*.
|
||||
|
||||
### 2.5 Internal Region Layout / Topology Vocabulary
|
||||
|
||||
region 들의 *공간 배치 패턴* 어휘. multi-region zone 의 *방향 / 배치* 결정. ratio 와 content_type 만으로는 *어떻게 배치되는지* 가 결정 안 되므로 *vocabulary 단계* 가 명시적으로 필요.
|
||||
|
||||
#### 명명 style — slide-level vs region-level 의 *의도된 비대칭*
|
||||
|
||||
- **Slide-level 8 vocabulary** (Step 7) = *count-based* 명명 (`horizontal-2`, `top-1-bottom-2`). zone 의 *layout-driven* 성격 반영
|
||||
- **Region-level vocabulary** (본 §) = *descriptor-based* 명명 (`vertical-stack`, `main-support`). region 의 *content-type / role-driven* 성격 반영
|
||||
- 이 비대칭은 *의도된 것*. region count 가 작고 (1~4) content type / role 이 핵심 결정 기준이라 descriptor 가 더 의미 전달
|
||||
|
||||
#### v1 vocabulary (6 entry)
|
||||
|
||||
| region_layout_type | 의미 | 사용 조건 |
|
||||
|---|---|---|
|
||||
| `region-single` | 1 region 만 (zone 전체 = region 1개) | region count = 1 (single-region zone) |
|
||||
| `region-vertical-stack` | 위·아래 수직 stack | region count ≥ 2, content type 이 *순차적 흐름* (예: 본문 + supporting). default fallback |
|
||||
| `region-horizontal-split` | 좌·우 수평 분할 | region count = 2, content type 이 *대등 비교* 또는 *side-by-side 시각* (text + image, text + diagram 등) |
|
||||
| `region-main-support` | main region + supporting region (asymmetric ratio) | region count = 2, role = [primary, supporting], ratio asymmetric (예: 0.7 / 0.3) |
|
||||
| `region-preview-details` | inline preview region + details/popup region | details_presence = true, 또는 큰 content (table N ≥ 5, long text 등) |
|
||||
| `region-grid-2x2` | 2×2 grid (4 region) | region count = 4, content type 이 *대등 4 항목* |
|
||||
|
||||
#### deterministic decision rule
|
||||
|
||||
`region_layout_type` 은 AI 호출 X. 다음 *결정론적 함수* 로 도출 :
|
||||
|
||||
```
|
||||
입력 :
|
||||
- region_count : int
|
||||
- content_type_mix : list[str]
|
||||
- ratio_estimate : list[float]
|
||||
- role 분포 : list[str] (primary / supporting / ...)
|
||||
- details_presence : bool
|
||||
|
||||
결정 분기 (순차 적용, 첫 매칭 채택) :
|
||||
1. region_count == 1
|
||||
→ region-single
|
||||
|
||||
2. details_presence == true 또는 큰 content (table N ≥ 5 / long text 등)
|
||||
→ region-preview-details
|
||||
|
||||
3. region_count == 4 AND content_type_mix 가 *4 종 대등*
|
||||
→ region-grid-2x2
|
||||
|
||||
4. region_count == 2 AND role == [primary, supporting] AND ratio asymmetric (max / min ≥ 2)
|
||||
→ region-main-support
|
||||
|
||||
5. region_count == 2 AND content_type_mix 내 visual element (image / diagram) 포함
|
||||
→ region-horizontal-split
|
||||
|
||||
6. fallback (위 모든 분기 미매칭)
|
||||
→ region-vertical-stack
|
||||
```
|
||||
|
||||
#### 출력 schema
|
||||
|
||||
각 zone 의 `internal_regions` 컨테이너에 region_layout 필드 추가 :
|
||||
|
||||
```yaml
|
||||
zone:
|
||||
zone_id: str
|
||||
internal_regions: [...]
|
||||
region_layout:
|
||||
region_layout_type: str # 위 6 entry 중 하나
|
||||
region_order: [str] # region_id 의 배치 순서 (위→아래 / 좌→우 등)
|
||||
region_placement: str # vertical | horizontal | grid | main-side | stack
|
||||
```
|
||||
|
||||
#### 구현 위치 (예정)
|
||||
|
||||
신규 module (이름 *implementation step 에서 결정* — defer) :
|
||||
- input : `zone.internal_regions` (from §2.1, ratio + content_type 산정 후)
|
||||
- output : `zone.region_layout` (region_layout_type + order + placement)
|
||||
- 위치 : §2.4 region 비율 산정 *직후*, §2.6 region → frame / display interface *직전*
|
||||
- 결정 함수 deterministic — AI 호출 X
|
||||
|
||||
#### v1 vocabulary 의 한계 / 향후 확장 (참고)
|
||||
|
||||
- 현재 6 entry = v1 starting set. 추후 sample / frame DB 확장 시 vocabulary 추가 가능 (예: `region-vertical-3` / `region-horizontal-3` / `region-main-side-bottom` 등)
|
||||
- v1 fallback (`region-vertical-stack`) 이 매칭 안 되는 패턴 발견 시 별 step 으로 entry 추가
|
||||
|
||||
### 2.6 region → frame / display 매칭 interface
|
||||
|
||||
각 region 은 다음 중 하나 :
|
||||
- **frame_match** — region 의 content_type 에 호환되는 frame 선택. 매칭된 frame 의 contract 가 §3 의 입력. Stage B 진입
|
||||
- **display_only** — frame 없이 display strategy 로 처리 (image area 직접 / table preview / details button). frame contract 미사용. Stage B 우회
|
||||
|
||||
현재 *runtime contract-registered / verified* frame set (F13 / F29 / F16) 은 모두 text region 만 수용. image / table / details region 은 현재 *display_only* path.
|
||||
|
||||
### 2.7 구현 위치 (예정)
|
||||
|
||||
신규 module (이름 *implementation step 에서 결정* — defer) :
|
||||
- input : `section.content_objects` (from §1)
|
||||
- output : `zone.internal_regions` (with ratio + frame_match_strategy) + `zone.region_layout` (from §2.5)
|
||||
- 현재 composition planner 의 frame 매칭 *직전* 에 삽입
|
||||
- region 분할 / 비율 산정 / topology vocabulary 선택 / 매칭 기준 — 모두 deterministic rule 기반 (AI 호출 X)
|
||||
|
||||
---
|
||||
|
||||
## §3. frame contract 확장 — accepted_content_types + Frame Slot (Layer B)
|
||||
|
||||
> **v0 의 §2 → v1 의 §3 (renumber)**. *Layer B / Frame Slot* spec.
|
||||
|
||||
`templates/phase_z2/catalog/frame_contracts.yaml` 에 *2 개 신규 필드* 추가.
|
||||
|
||||
### 3.1 schema
|
||||
|
||||
```yaml
|
||||
<template_id>:
|
||||
... (기존 필드 그대로 — source_shape / cardinality / payload / visual_hints / ...)
|
||||
|
||||
# NEW : 이 frame 이 받을 수 있는 content type 들
|
||||
accepted_content_types:
|
||||
- text_block
|
||||
- transform_table
|
||||
- ...
|
||||
not_accepted: # 명시적 비호환 (디버그용)
|
||||
- image
|
||||
- diagram
|
||||
|
||||
# NEW : frame 내부 Frame Slot 선언
|
||||
# YAML field name = 'sub_zones' — 코드 / catalog reality 로 유지. 의미 = Frame Slot (Layer B).
|
||||
sub_zones:
|
||||
- id: str # Frame Slot 식별자
|
||||
role: main_text | supporting_visual | label | details_button | ...
|
||||
accepts: # 이 Frame Slot 이 받는 content_object type
|
||||
- text_block
|
||||
- transform_table
|
||||
cardinality: # Frame Slot 내 capacity
|
||||
strict: int # 정확히 N개
|
||||
# or
|
||||
min: int
|
||||
max: int
|
||||
partial_target_path: # frame partial template 에서 이 Frame Slot 의 위치
|
||||
# 예 : "f29b__cell--left.row-1" — partial 안 marker (attribute name *implementation step 에서 결정*)
|
||||
```
|
||||
|
||||
> **YAML field 이름** : 코드 / catalog reality 로 `sub_zones` 유지. 의미는 *Frame Slot* (= Layer B).
|
||||
|
||||
### 3.2 구체 예시 (현재 3 frame)
|
||||
|
||||
#### F13 — three_parallel_requirements
|
||||
```yaml
|
||||
three_parallel_requirements:
|
||||
...
|
||||
accepted_content_types: [text_block]
|
||||
sub_zones: # = Frame Slots (Layer B)
|
||||
- id: pillar_1
|
||||
role: main_text
|
||||
accepts: [text_block]
|
||||
cardinality: { strict: 1 }
|
||||
- id: pillar_2
|
||||
role: main_text
|
||||
accepts: [text_block]
|
||||
cardinality: { strict: 1 }
|
||||
- id: pillar_3
|
||||
role: main_text
|
||||
accepts: [text_block]
|
||||
cardinality: { strict: 1 }
|
||||
```
|
||||
|
||||
#### F29 — process_product_two_way
|
||||
```yaml
|
||||
process_product_two_way:
|
||||
...
|
||||
accepted_content_types: [text_block, transform_table]
|
||||
sub_zones: # = Frame Slots (Layer B)
|
||||
- id: process_column
|
||||
role: main_text
|
||||
accepts: [text_block, transform_table]
|
||||
cardinality: { strict: 3 } # 3 sections per column
|
||||
- id: product_column
|
||||
role: main_text
|
||||
accepts: [text_block] # product 쪽은 transform 안 받음 (현재 frame 의 시각적 구분)
|
||||
cardinality: { strict: 3 }
|
||||
```
|
||||
|
||||
#### F16 — bim_issues_quadrant_four
|
||||
```yaml
|
||||
bim_issues_quadrant_four:
|
||||
...
|
||||
accepted_content_types: [text_block]
|
||||
sub_zones: # = Frame Slots (Layer B)
|
||||
- id: quadrant_1
|
||||
role: main_text
|
||||
accepts: [text_block]
|
||||
cardinality: { strict: 1 }
|
||||
- id: quadrant_2
|
||||
role: main_text
|
||||
accepts: [text_block]
|
||||
cardinality: { strict: 1 }
|
||||
- id: quadrant_3
|
||||
role: main_text
|
||||
accepts: [text_block]
|
||||
cardinality: { strict: 1 }
|
||||
- id: quadrant_4
|
||||
role: main_text
|
||||
accepts: [text_block]
|
||||
cardinality: { strict: 1 }
|
||||
```
|
||||
|
||||
### 3.3 partial template 의 Frame Slot 마커
|
||||
|
||||
frame partial 의 HTML 에 Frame Slot 식별 marker 추가 — render 후 Selenium 이 Frame Slot 단위 측정 가능, A1~A4 의 정밀도 향상. *marker attribute name (예: `data-subzone` / `data-frame-slot` / 기타) 은 implementation step 에서 결정 — defer*.
|
||||
|
||||
---
|
||||
|
||||
## §4. placement algorithm — 2-stage (Layer A → Layer B)
|
||||
|
||||
> **v0 의 §3 → v1 의 §4 (renumber + 2-stage 재작성)**. *layer 순차 dependency*.
|
||||
|
||||
### 4.1 input / output
|
||||
|
||||
```
|
||||
input :
|
||||
section: { section_id, content_objects: [...] }
|
||||
zone: { zone_id, layout_position }
|
||||
available_frames: [...] # V4 top-k from Step 5
|
||||
|
||||
output :
|
||||
internal_regions: [
|
||||
{
|
||||
region_id, role, content_type, ratio_estimate,
|
||||
content_unit_ids: [...],
|
||||
frame_match_strategy: { kind, frame_id, display_strategy },
|
||||
# Stage B 결과 (frame_match region 만)
|
||||
slot_assignments: [
|
||||
{ content_object_id, frame_slot_id, display_strategy }
|
||||
],
|
||||
overflow_buffer: [...],
|
||||
rejection: [...]
|
||||
},
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
### 4.2 Stage A — content → Internal Region (Layer A)
|
||||
|
||||
> region 분할 결정 + content_object → region 배치.
|
||||
|
||||
```
|
||||
1. 3-way decision (§2.3) 적용
|
||||
- whole-section frame fit 가능 → single-region (Stage B 로 1 region)
|
||||
- child-grouping 가능 → group merge → single-region
|
||||
- content-type split 필요 → multi-region
|
||||
|
||||
2. multi-region 인 경우 :
|
||||
- content_object.type 별로 region 분류 (text region / table region / image region / ...)
|
||||
- 같은 region 안의 content_object 끼리 묶음
|
||||
- region 별 ratio 산정 (§2.4)
|
||||
|
||||
3. region 별 frame_match_strategy 결정 :
|
||||
- region.content_type 이 frame.accepted_content_types 에 매칭 가능 → frame_match
|
||||
- 매칭 frame 없음 → display_only (image / table / details path)
|
||||
|
||||
4. 결과 : zone.internal_regions = [region_1, region_2, ...]
|
||||
각 region 은 content_unit_ids + frame_match_strategy 를 가짐
|
||||
```
|
||||
|
||||
### 4.3 Stage B — Internal Region content → Frame Slot (Layer B)
|
||||
|
||||
> region 의 content 를 frame 의 Frame Slot 에 배치. *frame_match_strategy.kind == "frame_match"* 인 region 에만 적용.
|
||||
|
||||
각 frame_match region 에 대해 :
|
||||
|
||||
```
|
||||
1. content_object 정렬
|
||||
- role 기준 우선순위 : summary > reference > detail > decorative
|
||||
- 같은 role 내 raw_payload 등장 순서
|
||||
|
||||
2. content_object.type 이 frame.accepted_content_types 에 없는 것
|
||||
→ rejection 으로 분리. 본 frame 부적합 신호 (Stage A 의 frame_match_strategy 재검토 신호)
|
||||
|
||||
3. 남은 content_object 를 Frame Slot 들에 배치
|
||||
- 각 Frame Slot 을 순회 (frame contract 의 declaration 순서)
|
||||
- Frame Slot.accepts 에 매칭되는 content_object 들에서
|
||||
cardinality.strict 또는 max 수만큼 할당
|
||||
- role 우선순위 높은 것부터
|
||||
|
||||
4. 배치 안 된 content_object
|
||||
- role = decorative → 무조건 drop (생략)
|
||||
- role = detail → overflow_buffer 로 (details/popup 후보)
|
||||
- role = summary / reference → rejection (frame 부적합)
|
||||
|
||||
5. 결과 :
|
||||
- slot_assignments : 정확히 무엇이 어디로
|
||||
- overflow_buffer : details/popup 으로 escalate 할 candidate
|
||||
- rejection : 본 frame 으로는 표현 불가 — frame_reselect 신호
|
||||
```
|
||||
|
||||
### 4.4 매칭 충돌 / tie-break
|
||||
|
||||
Frame Slot 단위로 :
|
||||
|
||||
- 동일 Frame Slot 에 다수 content_object 후보 시 :
|
||||
- role 우선순위 (summary > reference > detail)
|
||||
- 동률 시 size_estimate 작은 것 우선 (fit 가능성 ↑)
|
||||
- 동일 content_object 가 여러 Frame Slot 에 매칭 가능 시 :
|
||||
- role 매칭 우선 (Frame Slot.role == content_object.role)
|
||||
- 그래도 동률이면 contract declaration 순서 (앞쪽 Frame Slot 우선)
|
||||
|
||||
### 4.5 display_only region 의 처리
|
||||
|
||||
`frame_match_strategy.kind == "display_only"` 인 region 은 Stage B 우회. 대신 :
|
||||
- image region → image area 직접 배치 (frame 없이, region 안에 직접 inline)
|
||||
- table region → table preview (rows ≤ N inline) + 자세히보기 (rows > N popup)
|
||||
- details region → details button + popup
|
||||
- diagram region → diagram inline
|
||||
|
||||
display strategy 어휘는 §5 와 동일 — region-level 적용.
|
||||
|
||||
### 4.6 구현 위치 (예정)
|
||||
|
||||
신규 module (이름 *implementation step 에서 결정* — defer) :
|
||||
- `plan_placement(section, zone, available_frames) -> Placement`
|
||||
- composition planner 의 frame 매칭 *직후*, slot_payload 생성 *직전*
|
||||
- Stage A → Stage B 순차 실행
|
||||
- 결과를 slot_payload 생성 단계에 전달
|
||||
|
||||
---
|
||||
|
||||
## §5. 표시 전략 — inline preview vs details / popup escalation
|
||||
|
||||
> **v0 의 §4 → v1 의 §5 (renumber)**. **layer-agnostic** — region-level (Stage A) + slot-level (Stage B) 둘 다 적용. *어휘 미변경*.
|
||||
|
||||
### 5.1 결정 기준 (per content_object type)
|
||||
|
||||
| type | inline 가능 조건 | preview + details 전환 | popup-only 전환 |
|
||||
|---|---|---|---|
|
||||
| `text_block` | line_count ≤ Frame Slot capacity | line_count > capacity AND role=detail | role=detail AND line_count >> capacity (예: 20+) |
|
||||
| `table` (rows N) | N ≤ 4 | 5 ≤ N ≤ 7 (preview 첫 N rows + details) | N ≥ 8 (popup-only) |
|
||||
| `transform_table` | rows ≤ frame 의 transform Frame Slot capacity (보통 3) | rows > capacity, 일부 inline | rows >> capacity |
|
||||
| `image` | aspect_ratio fit 가능 | 일부 frame 에서 inline + details 의 thumbnail | 거의 없음 (image 는 보통 inline 또는 drop) |
|
||||
| `diagram` | Frame Slot 호환 | preview thumbnail + popup full | popup-only |
|
||||
| `details` (already-marked) | inline 만 안 함 (정의상) | summary inline + body popup | summary + body popup |
|
||||
|
||||
### 5.2 *원문 손실 금지* 룰
|
||||
|
||||
- 표시 전략 결정은 *어디 보여줄지*. *content 자르지 / 압축 / 요약 X*
|
||||
- inline preview 도 *raw_payload 의 일부* 만 빌려옴. 나머지는 details 로
|
||||
- AI 호출 X — 모든 결정은 deterministic rule 기반
|
||||
|
||||
### 5.3 적용 layer
|
||||
|
||||
display strategy 어휘 (`inline_full` / `inline_preview_with_details` / `details_only` / `dropped`) 는 *동일* :
|
||||
- **region-level** (Stage A 의 display_only region) — image area / table preview / details button 등
|
||||
- **slot-level** (Stage B 의 frame_match region 안 Frame Slot 별 content) — Frame Slot 안 content 가 fit 안 되면 escalate
|
||||
|
||||
### 5.4 details / popup runtime
|
||||
|
||||
- frame partial 또는 region container 에 `<details>/<summary>` 또는 별 button + popup layer
|
||||
- 단순 v0 : `<details>` 내장 — 클릭으로 펼침
|
||||
- 향후 v1 : 별도 popup overlay (CLAUDE.md 의 자세히보기 원칙)
|
||||
|
||||
### 5.5 구현 위치 (예정)
|
||||
|
||||
placement planner (§4.6) 의 후속 단계 — 각 assignment / region 에 `display_strategy` 부착 :
|
||||
- `inline_full` — content 전체 inline
|
||||
- `inline_preview_with_details` — 일부 inline, 나머지 details
|
||||
- `details_only` — summary 만 inline, content 는 popup
|
||||
- `dropped` — decorative 가 공간 부족으로 생략
|
||||
|
||||
---
|
||||
|
||||
## §6. A1~A4 telemetry 와의 interface
|
||||
|
||||
> **v0 의 §5 → v1 의 §6 (renumber)**. *layer-agnostic*. *구조 미변경* — `sub_zone` 단어 mechanical rename + region-level metadata 추가.
|
||||
|
||||
본 composition layer 와 기존 telemetry layer (A1~A4) 가 *어떻게 흐르는지*.
|
||||
|
||||
### 6.1 forward flow (composition → render → telemetry)
|
||||
|
||||
```
|
||||
section
|
||||
↓ extract_content_objects
|
||||
content_objects
|
||||
↓ placement_planner (Stage A → Stage B)
|
||||
placement {
|
||||
internal_regions: [
|
||||
{
|
||||
region_id, content_type, ratio_estimate,
|
||||
slot_assignments: [{content_object_id, frame_slot_id, display_strategy}],
|
||||
overflow_buffer: [...],
|
||||
rejection: [...],
|
||||
}
|
||||
]
|
||||
}
|
||||
↓ slot_payload 생성 (region + Frame Slot 단위로 grouping)
|
||||
slot_payload (with region + Frame Slot metadata)
|
||||
↓ render (frame partial — Frame Slot aware + region container aware)
|
||||
HTML
|
||||
↓ Selenium check
|
||||
overflow signals
|
||||
↓ A1 fit_classifier
|
||||
categories
|
||||
↓ A2 router
|
||||
proposed_actions
|
||||
↓ A3 retry / A4 failure_classifier / next_action
|
||||
final_status
|
||||
```
|
||||
|
||||
### 6.2 telemetry 에 전달되는 새 metadata
|
||||
|
||||
각 zone 의 debug entry 에 추가 :
|
||||
```yaml
|
||||
zone:
|
||||
... (기존)
|
||||
internal_regions: # Layer A
|
||||
- region_id
|
||||
content_type
|
||||
ratio_estimate
|
||||
frame_match_strategy
|
||||
placement:
|
||||
slot_assignments: [...] # 이 zone 에 어떤 content_object 가 어디 Frame Slot 으로
|
||||
overflow_buffer: [...] # details 로 간 것
|
||||
rejection: [...] # frame 부적합 후보
|
||||
region_metrics: # Selenium 이 region 별로 측정 (Layer A)
|
||||
- region_id
|
||||
ch / sh / excess_y # region 단위 overflow
|
||||
frame_slot_metrics: # Selenium 이 Frame Slot 별로 측정 (Layer B, frame_match region 만)
|
||||
- frame_slot_id
|
||||
content_object_id
|
||||
ch / sh / excess_y # Frame Slot 단위 overflow
|
||||
```
|
||||
|
||||
### 6.3 backward flow (telemetry → composition)
|
||||
|
||||
A4 의 `next_proposed_action` 이 `frame_internal_fit_candidate` 또는 `frame_reselect` 일 때 :
|
||||
- composition layer 가 *재호출* 됨 (단, retry budget 별도)
|
||||
- 다른 frame 또는 다른 placement 시도
|
||||
|
||||
본 v1 에서는 *backward flow 자동화 X* (구현 단계). placement 가 정확히 되어 있으면 telemetry 거의 trigger X.
|
||||
|
||||
### 6.4 fit_classifier 의 *content_type aware* 진화
|
||||
|
||||
현재 fit_classifier 는 *className → semantic_content_type* 매핑. 본 spec 적용 후 :
|
||||
- Selenium 이 region marker / Frame Slot marker / content_object_id marker 를 읽음 (marker attribute name *implementation step 에서 결정* — defer)
|
||||
- classifier 는 *content_object 의 type* 을 직접 알 수 있음
|
||||
- 분류 정밀도 향상 (예: F29 의 frame_match region 안 Frame Slot 의 transform-block 이 transform_table content_object 임을 *직접* 알 수 있음 — 현재는 inner_content_signals 로 추론)
|
||||
|
||||
---
|
||||
|
||||
## §7. current code gap — 재사용 / 신규 분리
|
||||
|
||||
> **v0 의 §6 → v1 의 §7 (renumber)**. 신규 module 이름 *defer*.
|
||||
|
||||
### 7.1 이미 있는 것 (재사용)
|
||||
|
||||
- MDX parser : section 단위 (## / ### drilling)
|
||||
- align_sections_to_v4_granularity
|
||||
- composition planner (parent_merged_inferred 포함)
|
||||
- frame_contracts.yaml + builder/parser registry
|
||||
- mapper (catalog-driven slot_payload 생성)
|
||||
- Jinja2 render
|
||||
- 8-preset layout vocabulary
|
||||
- A1~A4 telemetry chain
|
||||
|
||||
### 7.2 신규 필요
|
||||
|
||||
| 항목 | 위치 | 비고 |
|
||||
|---|---|---|
|
||||
| **content_object 정규화** | 신규 module (이름 *defer*) | markdown AST 또는 regex 기반 v0 |
|
||||
| **Internal Region planner (Layer A)** | 신규 module (이름 *defer*) | 3-way decision + region 비율 + frame_match_strategy 결정 |
|
||||
| **frame_contracts.yaml** 의 `accepted_content_types` + `sub_zones` 필드 (= Frame Slot 선언) | catalog (기존 yaml 확장) | 3 frame (F13/F29/F16) 우선 |
|
||||
| **placement_planner (Layer A → Layer B)** | 신규 module (이름 *defer*) | Stage A: content → Internal Region / Stage B: region content → Frame Slot |
|
||||
| **display_strategy** 결정기 | placement_planner 내부 | inline_full / inline_preview_with_details / details_only / dropped |
|
||||
| **frame partial 에 Frame Slot 마커** | `templates/phase_z2/families/*.html` | marker attribute name *defer* |
|
||||
| **region container 마커** | `templates/phase_z2/slide_base.html` 또는 partial | region 단위 측정 marker, name *defer* |
|
||||
| **details/popup runtime** | partial template 또는 base slide | `<details>` 우선, 추후 popup overlay |
|
||||
| **fit_classifier 의 region / Frame Slot 인식** | `src/phase_z2_classifier.py` 확장 | inner_content_signals → region / Frame Slot 직접 read |
|
||||
| **mapper 의 region / Frame Slot-aware slot_payload** | `src/phase_z2_mapper.py` 확장 | builder 들이 region + Frame Slot 그룹핑 인식 |
|
||||
|
||||
### 7.3 정의 vs 구현 분리
|
||||
|
||||
본 spec 은 *정의만*. 구현 axis 는 별도 step :
|
||||
- B1. content_extractor (MDX → content_object 정규화)
|
||||
- B2. internal_region_planner (Layer A — 3-way decision + 비율 + frame_match_strategy)
|
||||
- B3. frame_contracts 의 accepted_content_types + sub_zones (= Frame Slot) 선언 (3 frame)
|
||||
- B4. placement_planner (Layer A → Layer B 통합)
|
||||
- B5. partial / region container marker 추가 + telemetry 연동 (이름 결정 포함)
|
||||
- B6. details/popup runtime
|
||||
|
||||
각 axis 는 *별도 step*. 한 axis 씩 사용자 승인 후 진행.
|
||||
|
||||
> **module / marker / attribute 이름** : 본 spec 에서 *defer*. implementation step 에서 결정.
|
||||
|
||||
---
|
||||
|
||||
## §8. 본 spec 의 활용
|
||||
|
||||
> **v0 의 §7 → v1 의 §8 (renumber)**.
|
||||
|
||||
### 8.1 composition layer 의 룰북
|
||||
|
||||
향후 frame 추가 / content_object 변경 / Layer A 재분할 / Frame Slot 매핑 변경 시 본 spec 의 schema 를 따름. *임의 매핑 / hack 차단*.
|
||||
|
||||
### 8.2 telemetry 와의 cross-check
|
||||
|
||||
A1~A4 의 분류 결과 (`structural_minor_overflow` 등) 가 본 spec 의 placement 결과와 *일치하는가* 확인 가능. 불일치 = composition planning 의 *예상치 못한 케이스* — 진단 자료.
|
||||
|
||||
### 8.3 미사용 sample (MDX 01 / 02) 진단
|
||||
|
||||
본 spec 적용 후 MDX 01/02 를 돌리면 :
|
||||
- 각 section 의 content_object 정규화 결과 visible
|
||||
- 각 zone 의 Internal Region 분할 결과 visible (single vs multi)
|
||||
- 어떤 content type 이 frame contract 에 없는지 (frame 추가 필요 신호)
|
||||
- placement 의 rejection 비율 (frame coverage gap)
|
||||
- overflow_buffer 의 details 후보 (popup runtime 필요 신호)
|
||||
- display_only region 비율 (현재 frame DB 의 Layer A 미커버 영역)
|
||||
|
||||
이 정보가 *generalization validation* 의 진짜 신호.
|
||||
|
||||
---
|
||||
|
||||
## §9. MDX 03 의 case 를 본 spec 으로 검증 (illustrative)
|
||||
|
||||
> **v0 의 §8 → v1 의 §9 (renumber)**. mechanical rename + 2-stage 표현.
|
||||
|
||||
> MDX 03 = sample. *fix 대상 X*. 본 spec 룰의 *예시 적용*.
|
||||
|
||||
### 9.1 03-1 의 content_object 정규화 (예상)
|
||||
|
||||
```yaml
|
||||
section_id: "03-1"
|
||||
title: "1. DX 시행을 위한 필수 요건"
|
||||
content_objects:
|
||||
- id: "03-1.text-1"
|
||||
type: text_block
|
||||
role: summary
|
||||
type_specific: { format: nested_list, bullet_count: 3 (top), nested_count: 7 }
|
||||
size_estimate: { line_count: ~12 }
|
||||
```
|
||||
|
||||
→ 1 content_object (text_block, role=summary).
|
||||
|
||||
### 9.2 03-1 의 Stage A → Stage B (F13 contract 적용)
|
||||
|
||||
**Stage A** :
|
||||
- 3-way decision : section 전체가 F13 (3 pillars) 의 child grouping 으로 매칭 → *whole-section frame match*
|
||||
- single-region zone, content_type=text, ratio=1.0
|
||||
- frame_match_strategy = { kind: "frame_match", frame_id: "F13" }
|
||||
|
||||
**Stage B** :
|
||||
- F13 sub_zones (= Frame Slots) : [pillar_1, pillar_2, pillar_3] (각 cardinality strict 1, accepts text_block)
|
||||
- text_block 1 개 → 3 Frame Slot 에 어떻게 배치?
|
||||
- 현재 mapper (`pillar_item` parser) 가 *implicit* 으로 top_bullet 3 개를 3 pillar 에 분배
|
||||
- 본 spec 적용 시 : text_block 의 nested 구조를 *3 sub_text_block* 으로 sub-decompose 하거나, Frame Slot cardinality 를 *aggregate (3)* 으로 해석할지 결정 필요
|
||||
- v1 단순화 : text_block 의 top-bullet 단위가 *implicit 한 sub-content_object* — 향후 explicit 화
|
||||
|
||||
### 9.3 03-2 의 case (transform_table 포함)
|
||||
|
||||
```yaml
|
||||
section_id: "03-2"
|
||||
content_objects:
|
||||
- id: "03-2.transform-1"
|
||||
type: transform_table
|
||||
role: summary
|
||||
type_specific: { pair_count: 3 }
|
||||
- id: "03-2.text-1"
|
||||
type: text_block
|
||||
role: detail
|
||||
type_specific: { bullet_count: 1 }
|
||||
- id: "03-2.text-2"
|
||||
type: text_block
|
||||
role: detail
|
||||
type_specific: { bullet_count: 1 }
|
||||
- id: "03-2.text-3"
|
||||
type: text_block
|
||||
role: detail
|
||||
type_specific: { bullet_count: 3 (large) }
|
||||
- ... (product 쪽도 4 개)
|
||||
```
|
||||
|
||||
**Stage A** :
|
||||
- 3-way decision : section 전체가 F29 (process/product 2-column structure) 와 매칭 → *whole-section frame match*
|
||||
- single-region zone, content_type=text+transform_table, ratio=1.0
|
||||
- frame_match_strategy = { kind: "frame_match", frame_id: "F29" }
|
||||
|
||||
**Stage B** :
|
||||
- F29 sub_zones (= Frame Slots) : [process_column (accepts: text_block + transform_table, cardinality 3), product_column (accepts: text_block, cardinality 3)]
|
||||
- process_column → transform_table + 2 text_block (3 개)
|
||||
- product_column → 3 text_block
|
||||
- 모두 inline_full 로 표시
|
||||
|
||||
이건 *현재 mapper (column_with_transform / column_plain) 가 implicit 으로 하는 것* — 본 spec 이 *explicit 하게 표현*.
|
||||
|
||||
### 9.4 03-2 의 cell row 1 (transform_table) 의 10 px overflow 재해석
|
||||
|
||||
placement 가 explicit 하게 되어도 transform_table 이 row 1 cell 에 *콘텐츠 height 131 vs 가용 121* 인 건 변하지 않음.
|
||||
|
||||
**그러나** :
|
||||
- placement 가 *transform_table 의 size_estimate* 를 미리 알면
|
||||
- frame contract 의 Frame Slot 이 *expected_height* 를 declare 하면
|
||||
- planning 단계에서 *"transform_table 이 row 1 Frame Slot 의 expected_height 초과한다"* 를 사전 감지 가능
|
||||
- 그 시점에서 display_strategy = `inline_preview_with_details` 로 자동 전환 (3 transforms 중 2 inline + "1 더 보기")
|
||||
- 또는 placement 가 *frame 부적합* 으로 판정 → frame_reselect 신호
|
||||
|
||||
즉 *본 spec 의 §4 placement algorithm 에 size_estimate 기반 fit pre-check* 가 들어가면 — A1~A4 telemetry 가 *trigger 안 되는 정상 path* 가 됨.
|
||||
|
||||
이게 본 spec 이 가리키는 *진짜 fit policy 의 자리*.
|
||||
|
||||
---
|
||||
|
||||
## 10. 다음 step (사용자 결정)
|
||||
|
||||
본 spec v1 정의 후 구현 axis 후보 :
|
||||
- B1. content_extractor (MDX → content_object 정규화)
|
||||
- B2. internal_region_planner (Layer A — 3-way decision + 비율 + frame_match_strategy)
|
||||
- B3. frame_contracts 에 accepted_content_types + sub_zones (= Frame Slot) 선언 (3 frame)
|
||||
- B4. placement_planner (Layer A → Layer B 통합)
|
||||
- B5. partial / region container marker 추가 + telemetry 연동 (이름 결정 포함)
|
||||
- B6. details/popup runtime
|
||||
|
||||
각 axis 는 *별도 step*. 사용자가 우선순위 결정.
|
||||
|
||||
본 spec 자체는 *implementation 0 단계의 정의*. 다음 step 은 사용자가 잠근 후 진행.
|
||||
@@ -1,220 +0,0 @@
|
||||
# Phase Z-2 — fit_classifier / overflow_router spec
|
||||
|
||||
**Status** : v0 spec (2026-04-29). 정의만. 구현은 별도 step (사용자 승인 후).
|
||||
|
||||
---
|
||||
|
||||
## 0. 목적 / 위치
|
||||
|
||||
자동 파이프라인이 Selenium 으로 *detect 한* overflow / clipping 을 *어떤 pipeline action 으로 routing 할지* 결정하는 layer 의 spec.
|
||||
|
||||
현재 파이프라인은 detection 까지 정상 작동 (Selenium + debug.json 으로 신호 캡처). 그러나 detection 결과를 받은 직후 `sys.exit(1)` 으로 abort — **detection 과 action 사이의 decision layer 가 비어 있음**.
|
||||
|
||||
```
|
||||
parse_mdx → align → composition (v0.2: capacity_fit) → render (Jinja2)
|
||||
↓
|
||||
Selenium visual_runtime_check ← 기존 (detection)
|
||||
↓
|
||||
🆕 fit_classifier ← 신규 (사실 분류)
|
||||
↓
|
||||
🆕 overflow_router ← 신규 (정책 결정)
|
||||
↓
|
||||
action :
|
||||
- zone_ratio_retry ← 신규 미구현
|
||||
- layout_adjust ← 신규 미구현
|
||||
- details_popup_escalation ← 신규 미구현 (CLAUDE.md 의 <details> 원칙 활성)
|
||||
- frame_reselect ← 신규 미구현 (V4 top-k 활용)
|
||||
- adapter_needed ← composition v0.1.1 partial
|
||||
- abort ← 기존 (현재 default)
|
||||
```
|
||||
|
||||
**핵심 원칙** : classifier = *사실 분류* (이 overflow 가 어떤 종류인가), router = *정책 결정* (그 종류면 무엇을 할 것인가). 두 layer 분리 — 같은 분류가 context (retry 횟수 등) 에 따라 다른 action 을 요구할 수 있음.
|
||||
|
||||
---
|
||||
|
||||
## 1. fit_classifier 입력 schema
|
||||
|
||||
### 1.1 detection-side (기존 — 이미 캡처됨)
|
||||
|
||||
| 입력 | 출처 | 비고 |
|
||||
|---|---|---|
|
||||
| `clipped_inner: [{class_name, excess_x, excess_y, scrollWidth/Height, clientWidth/Height}]` | `run_overflow_check` Selenium JS | ✅ |
|
||||
| zone 별 `overflowed`, `excess_y/x` | 같음 | ✅ |
|
||||
| slide / slide_body level overflow | 같음 | ✅ |
|
||||
|
||||
### 1.2 composition-side (기존 — composition v0.2)
|
||||
|
||||
| 입력 | 출처 | 비고 |
|
||||
|---|---|---|
|
||||
| `unit.frame_template_id` / `contract_id` | composition + pipeline | ✅ |
|
||||
| `capacity_fit` (item count, fit_status) | `mapper.compute_capacity_fit` | ✅ (v0.2) |
|
||||
| `content_truncated_count` (zone 별) | pipeline 의 mapper 호출 후 | ✅ (v0.1.1) |
|
||||
| zone size (`height_px`, `min_height_px`, `content_weight`) | `compute_zone_layout` | ✅ |
|
||||
|
||||
### 1.3 신규 입력 (이번 spec 에서 정의)
|
||||
|
||||
| 입력 | 비고 |
|
||||
|---|---|
|
||||
| `semantic_content_type` | className → 의미적 분류. §2 registry 참조 |
|
||||
| `line_equivalent` | excess_y / 해당 element 의 line-height (1 줄 단위로 환산) |
|
||||
| `structural_unit_drop_count` | structural_unit 중 *완전히 또는 부분적으로 잘린* 개수 |
|
||||
| `retry_budget_used` (router 의 상태) | 같은 slide 에 대해 router 가 이미 시도한 retry 횟수 |
|
||||
|
||||
---
|
||||
|
||||
## 2. className → semantic content_type registry
|
||||
|
||||
| className 패턴 | semantic type | 설명 |
|
||||
|---|---|---|
|
||||
| `transform-block`, `transform-block__*`, `transform-row*` | `structural_unit` | paired comparison (AS-IS/TO-BE 한 쌍이 의미 단위). 행 단위 자르면 의미 깨짐 |
|
||||
| `text-line`, `text-line--bullet`, `text-line--indent-*` | `text_flow` | 자유 wrap, 줄 단위 자르기 가능 |
|
||||
| `*table*`, native `<table>` | `tabular` | 행/열 단위 의미 — 행 잘리면 의미 손실 |
|
||||
| `f29b`, `f13b`, `f16b` (frame-family root) | `frame_internal` | frame 자체가 zone 안에 못 들어감 (zone level 문제) |
|
||||
| `*__cell`, `*__pillar`, `*__quadrant` 등 frame 내부 cell | `frame_internal_cell` | frame 내부 cell 단위 (cell 내부 content 가 cell 경계 초과) |
|
||||
| `*__title`, `*__section-title`, `*__banner`, `*__label` 등 | `frame_label` | 제목/라벨 단위 (text 와 비슷하지만 wrap 제약 있음) |
|
||||
| `<img>`, `<svg>`, `*-bg` 등 | `visual_asset` | 시각 자산 (cropping 가능) |
|
||||
| 매칭 안 됨 | `unknown` | classifier 가 보수적으로 처리 (가장 안전한 action 선택) |
|
||||
|
||||
본 registry 는 신규 module (예: `src/phase_z2_classifier.py`) 의 상수 또는 catalog yaml entry 로 구현.
|
||||
|
||||
---
|
||||
|
||||
## 3. fit_classifier 출력 taxonomy
|
||||
|
||||
### 3.1 카테고리 정의 (계산 가능한 룰)
|
||||
|
||||
| 카테고리 | 판정 룰 |
|
||||
|---|---|
|
||||
| `frame_capacity_mismatch` | composition 단계의 `capacity_fit.fit_status` ∈ {`strict_mismatch`, `exceeds_max`, `below_min`, `exceeds_truncate`}. → 이미 v0.2 가 잡고 있는 영역. 본 카테고리는 *post-render 검증 / 누락된 케이스 캐치* 용 |
|
||||
| `structural_major_overflow` | content_type = `structural_unit` 또는 `tabular` AND `structural_unit_drop_count` ≥ 1 (1 개 이상 *완전 단위* 잘림) |
|
||||
| `structural_minor_overflow` | content_type = `structural_unit` 또는 `tabular` AND `structural_unit_drop_count` < 1 (마지막 1 단위가 *부분만* 잘림, 즉 boundary spill) |
|
||||
| `tabular_overflow` | content_type = `tabular` (위와 별도 — 표는 행 1개라도 잘리면 popup) |
|
||||
| `layout_zone_mismatch` | content_type = `frame_internal` (frame root 자체 overflow) — zone 이 frame 을 못 담음 |
|
||||
| `moderate_overflow` | content_type ∈ {`text_flow`, `frame_label`} AND `line_equivalent` ∈ (1.5, 4] |
|
||||
| `minor_overflow` | content_type ∈ {`text_flow`, `frame_label`} AND `line_equivalent` ≤ 1.5 |
|
||||
| `hard_visual_fail` | 위 어디에도 매핑 안 됨 OR retry budget 소진 |
|
||||
|
||||
### 3.2 분류 우선순위 (위에서 아래로)
|
||||
|
||||
1. `frame_capacity_mismatch` (composition 결과 우선)
|
||||
2. `tabular_overflow` (표는 즉시 popup 영역)
|
||||
3. `structural_major_overflow` (1+ 완전 단위 잘림)
|
||||
4. `layout_zone_mismatch` (frame root level)
|
||||
5. `structural_minor_overflow` (boundary spill — 양 작음)
|
||||
6. `moderate_overflow`
|
||||
7. `minor_overflow`
|
||||
8. `hard_visual_fail` (fallback)
|
||||
|
||||
### 3.3 핵심 구분
|
||||
|
||||
- **structural_minor vs structural_major** : 부분만 잘렸나 (`< 1` unit) vs 완전 단위가 잘렸나 (`≥ 1` unit). 부분 잘림은 zone 을 조금 더 주면 fit 가능. 완전 단위 잘림은 의미 손실 — popup escalation.
|
||||
- **structural vs moderate vs minor** : content type 이 *구조적 의미 단위* 인지 여부. 같은 px 양이라도 text_flow 는 minor, structural_unit 은 structural_minor 이상.
|
||||
|
||||
---
|
||||
|
||||
## 4. overflow_router action mapping
|
||||
|
||||
| 카테고리 | action | retry budget | fallback (안 풀리면) |
|
||||
|---|---|---|---|
|
||||
| `minor_overflow` | `zone_ratio_retry` (양보 가능 zone 식별 → compute_zone_layout 재실행) | 1 | escalate → `moderate_overflow` 처리 |
|
||||
| `moderate_overflow` | `layout_adjust` (8-preset 중 다른 preset 검토 + zone ratio 재분배) | 1 | escalate → `structural_major_overflow` 처리 |
|
||||
| `structural_minor_overflow` | `zone_ratio_retry` (구조 자르지 않도록 zone 키움) | 1 | escalate → `structural_major_overflow` 처리 |
|
||||
| `structural_major_overflow` | `details_popup_escalation` (`<details>/<summary>` path) | N/A | popup 미구현 시 → `frame_reselect` → `adapter_needed` |
|
||||
| `tabular_overflow` | `details_popup_escalation` 또는 `frame_reselect` (table-friendly frame 후보) | N/A | 없으면 `adapter_needed` |
|
||||
| `frame_capacity_mismatch` | `frame_reselect` (V4 top-k rank 2+ 평가) | 1 | 없으면 `adapter_needed` |
|
||||
| `layout_zone_mismatch` | `layout_adjust` 또는 `zone_ratio_retry` | 1 | escalate → `frame_reselect` |
|
||||
| `hard_visual_fail` | `abort` (현재 sys.exit(1) 그대로) | — | — |
|
||||
|
||||
---
|
||||
|
||||
## 5. current code gap
|
||||
|
||||
### 5.1 이미 있어서 *재사용* 할 것
|
||||
|
||||
- detection (Selenium `run_overflow_check`) — clipped_inner / excess_y / className 모두 캡처
|
||||
- composition v0.2 의 `compute_capacity_fit` (item count level)
|
||||
- composition v0.1.1 의 `adapter_needed` catch (mapper FitError)
|
||||
- debug.json 의 `slide_status` / `zones` / `candidates_summary` (입력 자료원)
|
||||
- 8-preset layout vocabulary + `compute_zone_layout`
|
||||
|
||||
### 5.2 새로 만들어야 할 것
|
||||
|
||||
| 신규 항목 | 비고 |
|
||||
|---|---|
|
||||
| **content_type registry** (§2) | className → semantic type. classifier 의 핵심 입력 |
|
||||
| **`fit_classifier` 모듈** | §1 입력 → §3 카테고리 |
|
||||
| **`overflow_router` 모듈** | §4 카테고리 → action |
|
||||
| `zone_ratio_retry` action 구현 | compute_zone_layout 의 retry path |
|
||||
| `layout_adjust` action 구현 | preset 동적 변경 |
|
||||
| `details_popup_escalation` 구현 | `<details>/<summary>` runtime + slot_payload 분리 룰 (큰 작업) |
|
||||
| `frame_reselect` 구현 | V4 top-k 사용 (rank-2+ 평가) |
|
||||
|
||||
### 5.3 정의 vs 구현 분리
|
||||
|
||||
본 spec 은 **정의만**. 위 신규 항목 중 어느 axis 부터 구현할지는 *별도 step* 에서 사용자 승인 후. 한꺼번에 다 만들지 X.
|
||||
|
||||
---
|
||||
|
||||
## 6. 본 spec 의 활용 — *visual fix 결정의 검증 자료*
|
||||
|
||||
본 spec 은 *룰북*. 향후 overflow 발생 시 :
|
||||
|
||||
1. classifier 가 *어떤 카테고리* 인지 결정
|
||||
2. router 가 *어떤 action* 인지 결정
|
||||
3. action 이 *현재 구현되어 있나* 확인
|
||||
4. 미구현이면 → "본 spec 의 이 path 미구현이라 처리 불가" 로 명확히 보고
|
||||
|
||||
**중요 활용** : 누군가 (Claude 든 사람이든) "padding 줄여서 끼우자" 같은 fix axis 를 제시하면 — 이 fix 가 본 spec 의 어느 action 에도 매핑되지 않음 → **자동 반려**. 본 spec 을 검증 자료로 가지면 *symptom-silencing fix* 가 들어올 자리가 없어짐.
|
||||
|
||||
---
|
||||
|
||||
## 7. MDX 03 의 10px clipping 을 본 spec 으로 분류 (검증용 sample, fix 대상 X)
|
||||
|
||||
> MDX 03 = sample instance. spec 룰의 *작동 검증* 용 — fix 대상 아님.
|
||||
|
||||
### 측정값
|
||||
- excess_y = 10px (~0.6 줄, transform-row line-height 15.95px 기준)
|
||||
- clipped element className = `transform-block` 의 마지막 row (cell 내부)
|
||||
- semantic content_type = `structural_unit` (transform-row pair)
|
||||
- structural_unit_drop_count = 0.6 (1 개의 마지막 row 가 부분만 잘림 — 완전 단위 1 개가 아님)
|
||||
- composition `capacity_fit.fit_status` = `ok`
|
||||
|
||||
### 분류 적용 (§3.2 우선순위)
|
||||
|
||||
1. `frame_capacity_mismatch`? — capacity_fit ok → ✗
|
||||
2. `tabular_overflow`? — content_type 이 tabular 아님 → ✗
|
||||
3. `structural_major_overflow`? — drop_count `< 1` → ✗
|
||||
4. `layout_zone_mismatch`? — frame_internal 아님 → ✗
|
||||
5. `structural_minor_overflow`? — content_type = structural_unit AND drop_count `< 1` → **✓**
|
||||
|
||||
**카테고리 = `structural_minor_overflow`**
|
||||
|
||||
### Action mapping 적용 (§4)
|
||||
|
||||
→ `zone_ratio_retry` (구조 자르지 않도록 F29 zone 을 더 키움)
|
||||
|
||||
### 현재 구현 상태
|
||||
|
||||
→ `zone_ratio_retry` 는 **MISSING**. 따라서 본 spec 기준으로 MDX 03 은 *classifier 가 정상 작동하면 structural_minor_overflow 로 분류되고 zone_ratio_retry 로 routing 되어야 하는 case* 인데, *그 path 가 현재 미구현*. 따라서 정직한 상태는 `RENDERED_WITH_VISUAL_REGRESSION` 그대로 유지.
|
||||
|
||||
### 반례 검증 (이전 잘못된 fix)
|
||||
|
||||
이전에 시도했던 "transform-block padding 6→4 + transform-row padding 3→2" :
|
||||
- 본 spec 의 어떤 action 에도 매핑되지 X (`density_reduce` 같은 action 자체가 없음)
|
||||
- 따라서 본 spec 기준으로 **자동 반려되는 fix axis** — 들어올 자리 없음
|
||||
|
||||
이게 본 spec 이 *visual fix 결정의 검증 자료* 로 작동한다는 증거.
|
||||
|
||||
---
|
||||
|
||||
## 8. 다음 step (구현 우선순위 — 사용자 결정 영역)
|
||||
|
||||
본 spec 정의 후 구현 axis 후보 (사용자가 우선순위 결정):
|
||||
|
||||
- A. content_type registry + fit_classifier (분류 layer)
|
||||
- B. overflow_router (정책 layer)
|
||||
- C. `zone_ratio_retry` action (가장 자주 트리거될 action)
|
||||
- D. `details_popup_escalation` (큰 작업 — 새 path)
|
||||
- E. `frame_reselect` (V4 top-k 사용 layer)
|
||||
|
||||
각 axis 는 *별도 step* 으로 한 단위씩. 한꺼번에 묶지 X.
|
||||
@@ -1,229 +0,0 @@
|
||||
# Phase Z Frame Style Inventory
|
||||
|
||||
> Phase Z 가 계승할 **색감, 여백, 폰트 위계, 표 / 카드 / 다이어그램 스타일, pill / badge, SVG / CSS 구현 힌트** 를 추출하는 인벤토리.
|
||||
>
|
||||
> ⚠️ 이 문서는 **블록 매핑이 아니다.** Figma frame 은 디자인 레퍼런스 / 구조 패턴 / 슬롯 힌트로 본다 ([`FRAME-INTEGRATION-MAP.md`](FRAME-INTEGRATION-MAP.md) 참조).
|
||||
>
|
||||
> ⚠️ `Phase Z Target` 컬럼은 **결정이 아니라 후보**. 사용자 승인 후 프로모션 게이트에서 확정.
|
||||
|
||||
---
|
||||
|
||||
## 1. Source Policy
|
||||
|
||||
| 구분 | 위치 | 역할 |
|
||||
|---|---|---|
|
||||
| **메인 소스** | `figma_to_html_agent/blocks/{figma_id}/` | 32 frame (1171281171 제외) — Phase Z 스타일 추출의 1 차 출처 |
|
||||
| **토큰 소스** | `templates/styles/tokens/` | `colors.css` / `spacing.css` / `typography.css` — Phase Z 에서 계승 / 조정 |
|
||||
| **legacy 참고** | `templates/blocks/structures/` 등 | Phase Z 의 실제 조립 재료 X. 폐기 / 아카이브 방향. 스타일 / 시각 언어 참고만 |
|
||||
|
||||
추출 우선 순위 :
|
||||
|
||||
1. **변환 완료 frame** (`index.html` + `flat.md` 보유) — 실제 CSS 관찰 기반 스타일 추출
|
||||
2. **미변환 frame** — `Style Elements` / `Extracted Style Hints` / `Phase Z Target` 보류, 변환 완료 후 갱신
|
||||
3. **MCP / Figma 직접 조회 사용 X** — `figma_to_html_agent` 의 본업이므로 inventory 작성 단계에서 침범하지 않음
|
||||
|
||||
---
|
||||
|
||||
## 2. Frame Inventory — 컬럼 정의
|
||||
|
||||
| 컬럼 | 의미 |
|
||||
|---|---|
|
||||
| **Frame** | `FRAME-INTEGRATION-MAP.md` 의 row 번호 (01~32) |
|
||||
| **Figma ID** | `figma_to_html_agent/blocks/` 디렉토리 ID |
|
||||
| **Layout** | `layouts.yaml` controlled vocabulary |
|
||||
| **Style Elements** | frame 안에서 *관찰되는* 스타일 요소 (gradient bar, pill, table header, radial node, soft shadow 등) |
|
||||
| **Extracted Style Hints** | Phase Z 에 *계승할* 구체 힌트 (예 : "table header dark fill + white text", "card gap 12~16px") |
|
||||
| **Phase Z Target** | **후보** 위치 (예 : `tokens/colors.css`, `styles/frame-patterns/table.css`, `svg-helpers/`). 결정 X |
|
||||
| **Asset Notes** | 자산 의존도 / Phase Z 재사용 가능성 (예 : "타이틀 아이콘 PNG 1 개, conclusion box 는 CSS 변환 가능") |
|
||||
| **Notes** | cardinality / optional slot / 변형 축 / 기타 |
|
||||
|
||||
### 작성 룰
|
||||
|
||||
1. **관찰 가능한 값만 작성** — 변환 frame 의 셀은 `flat.md` + `index.html` 에 *실제 있는* 관찰값만 채운다. flat.md 깊이는 frame 마다 다를 수 있고, 빠진 항목 (예 : 변형 축 명시 없음) 은 채우지 않고 비운다. **다른 frame 깊이에 맞추기 위한 추론 / 추측 채움은 하지 않는다.**
|
||||
2. **Phase Z Target 후보는 가능한 한 family 단위로 수렴** — 같은 layout family (표 / 카드 / 다이어그램 / 리스트 / banner) 의 frame 들은 동일한 target 파일 후보를 가리키게 작성. variant 차이는 별도 target 으로 쪼개기보다 `Notes` 에 메타로 남긴다. 표기는 항상 `(후보)` 접미사 — "만들 파일" 이 아니라 "수렴 위치 후보" 로 읽히게.
|
||||
3. **scale / zoom 은 Notes 에 메타** — Figma 원본 폭이 1280 이 아닐 경우 `flat.md` 의 scale / zoom 값을 그대로 두 (raw px 는 원본 기준). Phase Z slide-body (≈1200×590) 에 적용 시 재계산이 필요하다는 사실을 `Notes` 에 한 줄 기록.
|
||||
4. **redescription 금지** — `analysis.md` 의 cardinality / slot / anchor / layout 설명, `FRAME-INTEGRATION-MAP.md` 의 비고 / 검토 상태를 Inventory 에 다시 베끼지 않는다. 같은 정보가 두 문서에 들어가면 drift 위험.
|
||||
|
||||
### 미변환 frame 의 셀 표기
|
||||
|
||||
- `Style Elements` : *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.*
|
||||
- `Extracted Style Hints` / `Asset Notes` / `Notes` : `—`
|
||||
- `Phase Z Target` : `TBD after conversion` (단, `reference_only` frame 은 `N/A — reference_only`)
|
||||
|
||||
---
|
||||
|
||||
## 3. Frame Inventory (32 행)
|
||||
|
||||
> 14 변환 완료 frame 은 `flat.md` + `index.html` 관찰 기반 스타일 추출.
|
||||
> 18 미변환 frame 은 보일러플레이트 일괄.
|
||||
> 작성 룰 #1~4 (위 섹션 2) 준수.
|
||||
|
||||
| Frame | Figma ID | Layout | Style Elements | Extracted Style Hints | Phase Z Target | Asset Notes | Notes |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| **01** | `1171281172` | `circular-nodes-6` | • 6 원형 노드 absolute 배치 (각 노드 = 배경 원 + 내부 아이콘 + 라벨)<br>• 모든 노드 / 연결선 / 중앙 / 배경 = 이미지 자산 (9 개) | • **2D 다이어그램 패턴** — 노드 좌표 절대 배치<br>• 자산 의존도 매우 큼 — 본 frame 의 시각 구성은 거의 이미지 | svg helpers (helper area 후보, 자산 의존 제한적) | 9 자산 (배경, 중앙, 노드 ×6, 연결선) — 모두 이미지 유지. Phase Z 재현 시 자산 풀 / placeholder 필요 | 원본 1579×981, scale 0.81064. 변형 축 명시 없음 (flat.md sparse) |
|
||||
| **02** | `1171281173` | `bullet-cards-4-plus-center` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **03** | `1171281174` | `list-numbered-4` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **04** | `1171281175` | `quadrilateral-relations` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **05** | `1171281176` | `side-card-with-list` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **06** | `1171281177` | `full-page-map-banner` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `N/A — reference_only` | — | — |
|
||||
| **07** | `1171281178` | `2col-paired-list` | • 좌 H/W 7 항목 + 우 S/W 6 항목 + 중앙 시스템 원 + 하단 ground 이미지<br>• 16 자산 (배경 / 패널 / 중앙 원 / 장식 아이콘 / 헤더 바 SVG) | • **2D 복합 시스템 구성도 패턴**<br>• 자산 의존도 매우 큼 — Phase Z 재구성 곤란 | `styles/frame-patterns/system-diagram.css` (후보, 자산 의존 제한적) | 16 자산 모두 이미지 유지. Phase Z 재현 시 자산 풀 필수 | 원본 2446×1943, scale 0.52331. 변형 축 명시 없음 (flat.md sparse) |
|
||||
| **08** | `1171281179` | `3-section-framework` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **09** | `1171281180` | `list-stacked-vertical` | • 5 pill 행 : `bg: rgba(255,255,255,0.5)`, `border-bottom: 3px solid {color}`, `radius: 30px`, `box-shadow: 2px 4px 5px rgba(0,0,0,0.5)`, `padding: 10px 20px`<br>• pill 색상 5 개 : `#fb5915` / `#e79000` / `#e9a804` / `#919f00` / `#0d6361`<br>• 다이아몬드 stacking : 넓→좁→좁→넓→넓 (좌측 indent 변화)<br>• 타이틀 바 : `#fbd5b9`, `radius: 5px`, shadow<br>• 좌측 아크 장식 SVG (이미지) + 화살표 SVG (`rotate(-90deg)`) | • **pill row + colored bottom border** : 핵심 패턴, 색만 갈아끼우면 N=3~7 동작<br>• **다이아몬드 stacking 패턴** : indent 차이로 시각 리듬<br>• translucent bg + colored border = 부드러운 카테고리 분리 | `styles/frame-patterns/pill-list.css` (후보) + `tokens/colors.css` 5 pill color palette (후보) | 좌측 아크 SVG / 화살표 SVG 2 개 — 이미지 유지. pill 본체는 CSS 변환 완료 | 변형 축 : `items[N=3~7]`, `stacking_pattern` (required), `arc_decoration` / `vertical_label` (optional). 원본 1153×592 (scale 1.11015 — 원본이 1280 보다 작음, zoom up 처리) |
|
||||
| **10** | `1171281181` | `radial-diagram-5` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **11** | `1171281182` | `cards-3-category` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **12** | `1171281189` | `cycle-3way-intersection` | • 메인 3 원 (350×350) : outer + inner SVG (Ellipse585~592) + 중앙 라벨 (50px Bold white, `text-shadow: #cc5200`)<br>• 액센트 6 원 (130.9 px) : 한자 라벨 (45px Bold white, 같은 text-shadow)<br>• 사이드 라벨 6 그룹 : 40px Bold + 30px Medium desc<br>• 영역별 heading color : 상단 `#cc5200` / 좌측 `#604f32` / 우측 `#124133`, desc 공통 `#525151`<br>• 장식 RECT : gradient 회전 + `mix-blend-mode: multiply`<br>• 타이틀 : 70px Bold gradient `#000→#883700` | • **3 원 교차 다이어그램** : main 3 + accent 6 으로 영역 표현<br>• **white text + colored text-shadow** : 깊이 부여 효과<br>• **영역별 hue 분리** (`#cc5200` / `#604f32` / `#124133`) — 시각 zone 구분<br>• bg_texture multiply blending — 부드러운 배경 강조<br>• 사이드 라벨 위계 : Bold heading + Medium desc | svg helpers (helper area 후보, 원 / 교차 영역) + `styles/frame-patterns/cycle.css` (후보) + `tokens/colors.css` 영역별 hue palette (후보) | 19 SVG (Ellipse585~603 outer/inner pairs) — 좌표 기반 SVG 재구성 가능. bg_texture PNG 1 개는 이미지 유지 | 변형 축 명시 없음 (메인 3 원 고정 가능성). 원본 2195×1195, scale 0.58312. 수학 : main 350px = 15.94% width / accent 130.9px = 5.96% width |
|
||||
| **13** | `1171281190` | `3-column` | • 3 컬럼 (각 690 원본) : 좌 BAR (152.5 px) gradient + 우 본문<br>• BAR gradient 3 가지 : 기술 `#0D78D0→#023056` / 사람 `#FF9A23→#CC5200` / 자연 `#39BE49→#23742C`<br>• 한자 (技術 / 人材 / 天地) : 50px Bold white on bar<br>• 헤딩 : 45px Bold gradient (top / bottom 별도 gradient 2 종)<br>• 본문 : 35px Medium `#3E3523`<br>• 세로 라벨 (rotate 90°) — 옵셔널 메타<br>• 테두리 : 실선 + 점선 SVG | • **3-pillar 카드 패턴** : 동등 카테고리 3 개 (예 : 기술/사람/자연)<br>• **gradient bar + 한자 + heading + body** 조합<br>• **컬럼별 hue rotation** (blue / orange / green) — 의미 차별화<br>• heading 도 gradient (단색 X) — 일관된 시각 언어 | `styles/frame-patterns/three-pillar.css` (후보) + `tokens/colors.css` 3 column gradient palette (후보) | 아이콘 PNG 1 개 + 테두리 SVG 4 개 (CSS border 변환 가능). 자산 의존 적음 | 변형 축 명시 없음 (3 pillar 고정 가능성 큼). 원본 2123×724, scale 0.60290. 수학 : 열 너비 416px / 바 92px after scale |
|
||||
| **14** | `1171281191` | `persona-3col` | • 3 컬럼 동일 사이즈 (833×1845 원본) + 각 컬럼 텍스처 BG 이미지<br>• 컬러 오버레이 (opacity 0.80) — 컬럼별 다른 색감 hue<br>• 하단 사진 3 개 : `border-radius: 49~50px`, opacity 0.70<br>• 상단 원형 뱃지 (3 개) : outer + inner 이미지 + 한글 라벨<br>• 라벨 색 hue rotation : 발주자 `#285B4A` / 시공자 `#445A2F` / 설계자 `#743002`<br>• 체크박스 불릿 아이콘 (이미지, 32×32)<br>• 불릿 텍스트 : 40px Medium `#000` | • **3 컬럼 persona / actor 카드 패턴** : 역할별 한 컬럼<br>• **컬럼별 hue rotation** : 같은 톤 안에서 색상만 다르게 (역할 구분)<br>• **타이틀을 원형 뱃지로 표현** — 컬럼 상단 절반 걸침 (overhang)<br>• **사진을 borderless 가 아니라 둥근 corner + opacity 처리** (텍스트 가독성 확보)<br>• **체크박스 불릿** — 토큰화 가능 (Phase Z list-marker 후보) | `styles/frame-patterns/persona-cards.css` (후보) + `tokens/colors.css` 컬럼별 actor hue palette (후보) + svg helpers 원형 뱃지 (helper area 후보) | 다수 이미지 자산 : BG texture (×3), overlay (×3), photo (×3), badge outer/inner (×6), 체크박스 (×20 동일). 사진은 컨텍스트 의존 → Phase Z 에서 placeholder / 사용자 제공 자산 필요. 체크박스는 SVG 단순 대체 가능 | 원본 2601×1927 (대형 frame), scale 0.49213 |
|
||||
| **15** | `1171281192` | `policy-4card-plus-list` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **16** | `1171281193` | `quadrant-4` | • 2×2 사분면 (각 1080×270 헤더/푸터바 + 본문)<br>• 헤더/푸터 bar (4 개) : brown gradient (좌측, `270deg, rgba(165,161,150,0.5)→#39321E`) / green gradient (우측, `270deg, rgba(41,107,85,0.5)→#032118`)<br>• Bar 라벨 : 60px Black white + `text-shadow: 0 0 4px #322c1e`<br>• 사분면 헤드라인 : red `#ff0000` 55px Bold (강조)<br>• 본문 : black 42px Regular, bullet list (`<ul><li>`, 텍스트 마커)<br>• 중앙 원 + 영문 인용 (white 55px Bold)<br>• 배경 텍스처 PNG (`border-radius: 50px`, ×4 동일) | • **2×2 quadrant 패턴** : 4 사분면에 헤드라인 + body 쌍 + 헤더/푸터 bar<br>• **bar 색 양극** (brown / green) — 좌·우 의미 구분<br>• **bar text 강한 시각 강조** : 60px Black + text-shadow<br>• **사분면 헤드라인 red** — 문제 / 이슈 강조 패턴<br>• 중앙 원 + 인용 — 결론 표현 (옵셔널)<br>• bullet — `<ul><li>` 텍스트 마커 (이미지 마커 X) | `styles/frame-patterns/quadrant.css` (후보) + `tokens/colors.css` bar gradient + 강조 red (후보) | 배경 텍스처 PNG (×4 동일) + 중앙 원 PNG + bar SVG (×4, CSS gradient 변환 가능). 배경 / 원만 이미지 유지 | 변형 축 : `quadrants[4]` (required, 고정), `bar_labels[4]` (required), `center_quote` / `center_image` / `bg_texture` (optional). 원본 2226×1766, scale 0.57503 |
|
||||
| **17** | `1171281194` | `paired-rows-2x2` | • 4 행 (각 좌 pill + 본문 + 분할선 + 우 pill + 본문)<br>• 행 배경 : `border: 3px #60A451`, `radius: 30px`, `bg: rgba(250,237,203,0.15)`<br>• 분할선 : `dashed 2px #60A451` (CSS)<br>• pill 이미지 (R16: 두루마리 곡선) — 좌측 `left:-45.3% width:145.3%` / 우측 `left:0 width:151.25%`<br>• pill 라벨 : 40px Bold white<br>• 본문 : 36px Medium `#0c271e`<br>• 행 교대 pill 회전 : 상행 정상 / 하행 `rotate(180deg)`<br>• 타이틀 : 70px Bold gradient `#CC5200→#883700` | • **paired-rows 패턴** : 좌 / 우 라벨 + body 페어, 분할선 중앙<br>• **두루마리 pill (R16)** : 이미지 기반 곡선 형상 — CSS 재구성 곤란<br>• **상/하 pill 회전 교대** = 시각 리듬<br>• translucent bg + colored border = visual containment<br>• dashed 분할선 = soft separation | `styles/frame-patterns/compare-paired.css` (후보, Frame 18 과 같은 family) + `tokens/colors.css` border / bg color (후보) | 타이틀 아이콘 PNG + 두루마리 pill PNG (R16 frame 배치, CSS 재구성 곤란) + 분할선 SVG (CSS 변환 가능) | 변형 축 : `rows[N=3~6]`, `pill_alternation` 상/하 교대 (required), `pill_image` (required), `bg_border_color: #60A451` (required). 원본 1857×1326, scale 0.68927. **compare-paired family — variant : `paired-rows` (pill alternation)** |
|
||||
| **18** | `1171281195` | `compare-rows` | • 타이틀 70px Bold gradient text (`#CC5200 → #883700`) + 아이콘<br>• 서브헤더 pill bar : `linear-gradient(270deg, #285B4A → #4A4026)`, `border-radius: 50px`<br>• 중앙 카테고리 뱃지 12 개 : 같은 gradient (alpha 0.64~0.8), `border-radius: 10px`<br>• 좌·우 텍스트 색 양극 : `#5C3714` (BIM 측, 갈색계) ↔ `#285B4A` (DX 측, 청록계), 40px Bold<br>• 결론 박스 : `#FAEDCB` + `mix-blend-mode: multiply`<br>• 결론 강조 텍스트 : `#AE3607` 55px Bold | • **다행 비교표 패턴** : 좌 (BIM/AS-IS) ↔ 중앙 카테고리 라벨 ↔ 우 (DX/TO-BE) 의 3 컬럼 페어드<br>• **양극 색 표현** : 좌·우를 명도·색상이 다른 두 hue 로 분리 (대비 의도)<br>• **gradient 재사용** : title gradient + bar/badge gradient 가 동일 팔레트 (저채도 그린 + 다크 brown) 변주<br>• **결론 처리** : multiply blending + accent color 로 강조 | `styles/frame-patterns/compare-paired.css` (후보, Frame 17 과 같은 family) + `tokens/colors.css` 의 `--g-title` / `--c-as-is` / `--c-to-be` (후보) + `styles/blocks/conclusion.css` multiply blend (후보) | 타이틀 아이콘 PNG 1 개 (이미지 유지) + 화살표 SVG 1 개 (`rotate(180deg)`, 이미지 유지) + 결론 박스 SVG → CSS 변환 완료 (자산 불필요) | 변형 축 : `rows[N=8~15]` (required), `title` (required), `conclusion` / `arrow_decoration` (optional). 원본 1868×1908, scale 0.68524. **compare-paired family — variant : `vs-center-badge` (좌·우 텍스트 + 중앙 카테고리 라벨 컬럼)** |
|
||||
| **19** | `1171281197` | `cards-3-compare` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **20** | `1171281198` | `cards-3-header` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **21** | `1171281201` | `split-panel-diagram` | • 좌 다이어그램 이미지 + 우 4 번호 항목 + 하단 결론 바<br>• 14 자산 (다이어그램 요소 / 번호 뱃지 / 행 바 / 화살표 / 결론 바) — 모두 이미지 유지 | • **split-panel 패턴** (이미지-기반 다이어그램 + 번호 리스트)<br>• 자산 의존 큼 — Phase Z 재구성 시 다이어그램 이미지 제공 필요 | `styles/frame-patterns/split-panel.css` (후보, Frame 22 와 같은 family) | 14 자산 모두 이미지 유지. 다이어그램 이미지 = 핵심 자산 | 변형 축 : `right_items[N=3~6]`, `conclusion_text` (optional). 원본 1889×824, scale 0.67761. flat.md sparse |
|
||||
| **22** | `1171281202` | `split-panel-numbered` | • 좌 패널 : 배경 IMG + 카테고리 텍스트 (40px Bold white, text-shadow) + detail (35px Medium black)<br>• 우 패널 : 5 행 (번호 뱃지 IMG + 행 바 IMG + 텍스트 45px Medium `#11231d` + 화살표 IMG `rotate(180deg)`)<br>• 중앙 연결 : 세로 괄호 IMG + 커넥터 IMG<br>• 행 바 (×5 동일 이미지)<br>• 번호 뱃지 (5 개 별개 이미지)<br>• 타이틀 : 70px/50px gradient | • **split-panel + numbered list 패턴** : 좌 카테고리 패널 + 우 번호 항목 페어<br>• 카테고리 텍스트 = text-shadow + white (배경 위 가독성)<br>• 번호 뱃지 + 행 바 + 화살표 = 단위 리스트 행 컴포넌트<br>• 중앙 괄호 / 커넥터 = 좌 ↔ 우 연결 시각화 | `styles/frame-patterns/split-panel.css` (후보, Frame 21 과 같은 family) | 15 자산 (좌측 BG, 타이틀 장식, 구분선 ×3, 세로 괄호, 커넥터, 행 바 ×5 동일, 뱃지 ×5 별개, 화살표 ×5 동일, 타이틀 아이콘) — 모두 이미지 유지 | 변형 축 : `left_categories[N=2~5]`, `right_items[N=3~8]` (required), `bg_image` (required), `bracket_image` (optional). 원본 1863×834, scale 0.68707 |
|
||||
| **23** | `1171281203` | `table-2col` | • 열 헤더 bar (3 개) : `#589e8d` (구분/좌) / `#ef7a26` (우), 40px Bold white<br>• 행 배경 교대 : white / `rgba(253,198,158,0.16)`<br>• 강조 키워드 : `#a14101` Bold inline<br>• 본문 : black 40px Medium<br>• 그리드 라인 : 모두 CSS border<br>• 배경 텍스처 PNG (상단 / 하단 분할) | • **compare-table 패턴** (구분 컬럼 + N 열 비교)<br>• **헤더 bar 색상 양극** (`#589e8d` 청록 / `#ef7a26` 오렌지) — 의미 구분<br>• **행 alternating bg** = readability<br>• **강조 키워드 inline color** (`#a14101`) — 표 셀 안 강조 | `styles/frame-patterns/compare-table.css` (후보, Frame 24 와 같은 family) + `tokens/colors.css` 헤더 bar palette (후보) | 배경 PNG 2 개 + 아이콘 PNG + line SVG ×5 (모두 CSS border 변환). 배경 PNG 만 이미지 유지 | 변형 축 : `columns[2]`, `rows[N=3~7]` (required), `header_colors[2]` (required), `bg_images[2]` (optional). 원본 1924×2014, scale 0.66527. **table family — Frame 24 / 30 / 31 과 column 수 / 행 수만 다름, variant 통합 후보** |
|
||||
| **24** | `1171281204` | `table-3col` | • 열 헤더 bar (4 개) : `#589e8d` (구분/상용) / `rgba(62,53,35,0.9)` (3rd) / `#ef7a26` (전용), 40px Bold white<br>• 행 배경 교대 : white / `rgba(253,198,158,0.16)`<br>• 강조 키워드 : `#a14101` Bold inline<br>• 본문 : black 35px Medium<br>• 그리드 라인 : 모두 CSS border<br>• 행 라벨 (좌측 열) : 35px Bold | • **compare-table 패턴** (Frame 23 의 3-column variant — 같은 family)<br>• **헤더 색상 3-way** (`#589e8d` / 다크 brown / `#ef7a26`) — Frame 23 의 2-way 확장<br>• **행 라벨 좌측 열** = 행 그룹 식별자 (예 : 개념 / 개발주체 / 성과품 / 사용) | `styles/frame-patterns/compare-table.css` (후보, Frame 23 과 같은 family — variant: `columns[N=2~4]`) + `tokens/colors.css` 헤더 bar palette 확장 (후보) | 아이콘 PNG + line SVG ×8 (전부 CSS border 변환). 자산 의존 거의 없음 | 변형 축 : `columns[N=2~4]`, `rows[N=3~6]` (required), `header_colors[N]` (required), `highlight_color` (optional, default `#a14101`). 원본 1869×1926, scale 0.68511. **table family — Frame 23 / 30 / 31 과 variant 통합 후보** |
|
||||
| **25** | `1171281205` | `left-categories-right-logos` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **26** | `1171281206` | `cards-4-grid` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **27** | `1171281208` | `central-split-synthesis` | • 좌 (생산성 향상) + 우 (디지털 전환) + 중앙 원 (건설산업의 고부가가치화)<br>• 상단 헤더 bar / 하단 결론 bar (SVG `rotate(180deg)`)<br>• 2D 배치 (중앙 원 좌 / 우 영역 겹침) → absolute + zoom | • **split-center 패턴** : 좌 / 우 / 중앙 3-area 합성<br>• 중앙 원 = 좌·우 영역에 걸침 (overhang) — 결론 표현 방식 | `styles/frame-patterns/split-center.css` (후보) | 변환 완료 (preview.png 존재). 자산 상세 미기록 (flat.md sparse) | 원본 1697×914, scale 0.75427. flat.md sparse — 추가 관찰 필요 |
|
||||
| **28** | `1171281209` | `title-plus-3-emphasis` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **29** | `1171281210` | `banner-top-2col-bottom` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **30** | `1171281211` | `table-3col` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **31** | `1171281212` | `table-3col` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
| **32** | `1171281213` | `central-5-goals` | *미변환 — 스타일 추출 보류. analysis.md 기준 layout / slot 존재만 확인.* | — | `TBD after conversion` | — | — |
|
||||
|
||||
---
|
||||
|
||||
## 4. Token Inventory
|
||||
|
||||
> 14 변환 frame 에서 관찰된 값과 기존 `templates/styles/tokens/` 의 매칭 검증.
|
||||
>
|
||||
> ⚠️ **본 inventory 는 신규 발굴표가 아니라 *기존 token 검증 + gap 발견 + 보류* 정리표**.
|
||||
> ⚠️ 추출 / 검증만. 실제 token 파일 생성 / 변경 / 폐기는 별도 승인 단계.
|
||||
|
||||
### 작성 룰 (최종 6 개)
|
||||
|
||||
1. **2+ frame 에서 반복 관찰된 값만 행 승격**.
|
||||
2. **1 frame 에서만 관찰된 값은 Token Inventory 에 올리지 않음** — 해당 Frame Inventory 의 `Notes` 에 "관찰 보류 (single-frame)" 로만 남김.
|
||||
3. **패턴 / 기법은 token 이 아니라 family CSS / variant 영역** — `mix-blend-mode`, R16 pill 곡선, hue rotation, badge overhang, pill alternation 등.
|
||||
4. **타이포 / 스페이싱은 값 직접 매칭이 아니라 위계 매핑** — figma raw px (frame 1280 폭 기준) ↔ slide-body token (slide-body 스케일) 은 스케일이 다르므로 위계만.
|
||||
5. **gradient 는 from / to pair 단위 한 행**.
|
||||
6. **`covered` 는 hex 정확 일치일 때만** — 부분 일치 / 변형은 `gap_candidate` 또는 Notes 에 별도 표기.
|
||||
|
||||
### 명명 컨벤션 (가벼운 가이드)
|
||||
|
||||
신규 token 후보에만 적용. 기존 token (`--color-*`, `--font-*`, `--space-*`, `--card-*`) 은 그대로 사용.
|
||||
|
||||
- `--c-*` color
|
||||
- `--g-*` gradient
|
||||
- `--fs-*` font-size
|
||||
- `--sp-*` spacing
|
||||
- `--r-*` radius
|
||||
- `--sh-*` shadow
|
||||
|
||||
### 컬럼 정의
|
||||
|
||||
| 컬럼 | 의미 |
|
||||
|---|---|
|
||||
| **Token Category** | color / gradient / typography / spacing / radius / shadow |
|
||||
| **Existing Token** | `templates/styles/tokens/{file}` 의 token 명. 없으면 `—` |
|
||||
| **Covered Frame Observations** | frame 번호 + 짧은 컨텍스트 라벨만 (값 X). status 에 따라 의미 다름 (아래 참조) |
|
||||
| **Gap / Candidate** | 신규 token 후보 (이름 + 값 + `(후보)`). 기존 token 검증인 행은 `—` |
|
||||
| **Status** | `covered` / `gap_candidate` / `hierarchy_mapping_only` / `hold_recheck_after_conversion` |
|
||||
| **Notes** | family CSS cross-reference + 변형 메타 + scale 경계 등 |
|
||||
|
||||
### `Covered Frame Observations` 셀의 Status 별 의미
|
||||
|
||||
| Status | `Covered Frame Observations` 의 의미 |
|
||||
|---|---|
|
||||
| `covered` | 이 token 이 *cover 한* frame 들 (hex 정확 일치) |
|
||||
| `gap_candidate` | 이 후보가 *target 으로 하는* frame 들 (2+ frame 에서 동일 값 관찰) |
|
||||
| `hierarchy_mapping_only` | 이 위계 매핑이 *적용 가능한* frame 들 (값 직접 매칭 X) |
|
||||
| `hold_recheck_after_conversion` | 현재 cover 한 frame 없음 (`—`). 14 converted 기준 미관찰 — 전체 변환 후 재검증 |
|
||||
|
||||
### Token Inventory — 18 행
|
||||
|
||||
| Token Category | Existing Token | Covered Frame Observations | Gap / Candidate | Status | Notes |
|
||||
|---|---|---|---|---|---|
|
||||
| gradient | `--color-block-title-from` / `--color-block-title-to` (`#CC5200` / `#883700`) | F17, F18 (frame inner title) | — | `covered` | compare-paired family 의 title gradient slot. F12, F13 의 title 은 `from` 이 `#000` 으로 변형 — 별도 행 (`gap_candidate`) 처리 |
|
||||
| gradient | `--color-col-1-from` / `--color-col-1-to` (`#0D78D0` / `#023056`) | F13 (기술 bar — blue tone) | — | `covered` | three-pillar.css 의 column 1. 1 frame 매칭이지만 token 자체가 frame 값을 정확 흡수 |
|
||||
| gradient | `--color-col-2-from` / `--color-col-2-to` (`#FF9A23` / `#CC5200`) | F13 (사람 bar — orange tone) | — | `covered` | three-pillar.css 의 column 2. `#CC5200` 는 title gradient `from` 과 같은 hex 이지만 의미 다름 (column-2 끝값) |
|
||||
| gradient | `--color-col-3-from` / `--color-col-3-to` (`#39BE49` / `#23742C`) | F13 (자연 bar — green tone) | — | `covered` | three-pillar.css 의 column 3 |
|
||||
| color | `--color-compare-left` (`#5c3714`) | F18 (BIM / AS-IS 측 텍스트) | — | `covered` | compare-paired.css 의 좌측 / AS-IS 색 |
|
||||
| color | `--color-compare-right` (`#285b4a`) | F14 (발주자 라벨), F18 (DX / TO-BE 측 텍스트) | — | `covered` | compare-paired.css 의 우측 / TO-BE + persona-cards.css 의 actor 색. F14, F18 모두 hex 정확 일치 (대소문자 제외) — 의미 다르지만 token 재사용 가능 |
|
||||
| color | `--color-compare-badge` (`#ae3607`) | F18 (결론 강조 / VS 뱃지) | — | `covered` | compare-paired.css 의 결론 / VS 뱃지 강조색 |
|
||||
| gradient | — | F12, F13 (title — `#000` → `#883700`) | `--g-title-dark: linear-gradient(#000, #883700)` (후보) | `gap_candidate` | title gradient 변종 (`from` 이 `#000`). `--color-block-title-to` 와 끝값 공유 — 신규 token 으로 묶을지 / variant 처리할지 검토. 영향 family : 미정 (cycle.css / three-pillar.css) |
|
||||
| color | — | F23, F24 (table 헤더 좌 / 구분 — 청록 톤) | `--c-table-header-cyan: #589e8d` (후보) | `gap_candidate` | compare-table.css 의 좌측 / 구분 헤더. 기존 `--color-table-header-bg: #64748b` (회색) 과 다른 톤 — 회색 헤더 token 은 `hold` 행 참조 |
|
||||
| color | — | F23, F24 (table 헤더 우 / 전용 — 오렌지 톤) | `--c-table-header-orange: #ef7a26` (후보) | `gap_candidate` | compare-table.css 의 우측 헤더 |
|
||||
| color | — | F23, F24 (table 행 강조 키워드) | `--c-table-highlight: #a14101` (후보) | `gap_candidate` | compare-table.css 의 inline 강조색 |
|
||||
| color | — | F23, F24 (table 행 교대 배경) | `--c-table-row-alt: rgba(253,198,158,0.16)` (후보) | `gap_candidate` | compare-table.css 의 alternating row bg. white / `--c-table-row-alt` 교대 |
|
||||
| typography | `--font-slide-title` (22px) / `--font-zone-title` (13px) / `--font-sub-title` (12px) | F12, F13, F17, F18 (frame inner title — raw 70px Bold) | — | `hierarchy_mapping_only` | frame raw 70px 는 figma 1280 폭 기준 — slide-body 스케일과 다름. **위계 매핑만**. frame inner title 이 slide-body 안에서 어느 위계 (`--font-zone-title` / `--font-sub-title`) 로 매핑될지는 catalog 설계 단계 결정 |
|
||||
| typography | `--font-body` (11px) | F12, F13, F16, F17, F18, F22, F23, F24 (본문 — raw 35~42px Medium) | — | `hierarchy_mapping_only` | frame raw 35~42px 는 figma 1280 폭 기준. slide-body 안에서는 `--font-body` 위계 적용 |
|
||||
| spacing / radius | `--space-md` / `--space-lg` / `--card-radius` 등 | F09 (pill `radius: 30px`), F16 (배경 `radius: 50px`), F17 (행 `radius: 30px`), F18 (badge `radius: 10px`, pill `radius: 50px`), F23/F24 (셀 padding) | — | `hierarchy_mapping_only` | frame raw radius / gap / padding 은 figma 폭 기준. slide-body 안에서는 위계 매핑 + 재산정 필요 |
|
||||
| color | `--color-dark-card-1` (`#1a365d`) / `-2` (`#1e3a2f`) / `-3` (`#3b1f2b`) / `-title` (`#fbbf24`) / `-body` (`#e2e8f0`) | — | — | `hold_recheck_after_conversion` | 다크 카드 시각 시스템 5 token. 14 converted 기준 미관찰. 전체 32 frame 변환 후 재검증 (특히 미변환 zone_extract 18 개) |
|
||||
| color | `--color-pill-bg` (`#1e293b`) / `--color-pill-text` (`#ffffff`) | — | — | `hold_recheck_after_conversion` | 다크 pill 스타일. F09 pill (translucent + colored border) / F18 badge (gradient) 와 다른 톤. 14 converted 기준 미관찰 — 전체 변환 후 재검증 |
|
||||
| color | `--color-table-header-bg` (`#64748b`) / `--color-table-header-text` (`#ffffff`) | — | — | `hold_recheck_after_conversion` | 회색계 표 헤더. F23 / F24 의 colored 헤더 (`#589e8d` / `#ef7a26`) 와 다른 톤. 14 converted 기준 미관찰. 향후 회색 헤더 frame 등장 시 재검증 |
|
||||
|
||||
---
|
||||
|
||||
## 5. Legacy Reference
|
||||
|
||||
- legacy structures 6 개는 runtime 재사용 후보 X
|
||||
- frame 변환본 (`figma_to_html_agent/blocks/`) 이 우선 source
|
||||
- disposition 분류 목적은 archive / delete 판단
|
||||
- Phase Z catalog / runtime 설계 근거로 **직접 사용 X**
|
||||
|
||||
### 발견 — 6 파일 모두 frame 변환본의 *slide-body 스케일 재구현*
|
||||
|
||||
각 legacy file 의 헤더 주석에 `Source: figma_to_html_agent/blocks/{figma_id}` 명시 (확인). figma 변환 (raw 1280 폭, 40~70px 폰트) → slide-body 스케일 (`var(--font-sub-title)` 12px, `var(--space-sm)` 8px 등 token 적용) 재구현 시도. 즉 *figma 변환과 별개의 legacy* 가 아니라, *figma 변환에서 파생된 slide-body 스케일 시도*.
|
||||
|
||||
→ Phase Z runtime 은 frame catalog + family CSS 로 rebuild 예정. legacy structures 는 *변환 검증 증거 / 토큰 매핑 참고* 외 직접 사용 X.
|
||||
|
||||
### `Phase Z Disposition` 값
|
||||
|
||||
- `archive` — 보존 (스타일 / 토큰 매핑 증거 가치)
|
||||
- `delete_after_extract` — Style Note 추출 후 삭제
|
||||
- `hold_until_catalog_ready` — Phase Z catalog 안정화 전까지 유지
|
||||
|
||||
### Legacy Reference — 6 행
|
||||
|
||||
| Legacy File | Current Role | Phase Z Disposition | Style Note | Notes |
|
||||
|---|---|---|---|---|
|
||||
| `compare-table-2col.html` | F23 (`1171281203`) 의 slide-body 스케일 재구현. 표 헤더 colored / 행 교대 bg / 강조 inline color | `delete_after_extract` (후보) | inline hex (`#589e8d` / `#ef7a26` / `#a14101` / `rgba(253,198,158,0.16)`) 가 Token Inventory 의 `gap_candidate` 4 행과 정확 일치 | `compare-table.css` family 의 first reference 가치 |
|
||||
| `compare-table-3col.html` | F24 (`1171281204`) 의 3-column variant slide-body 재구현 | `delete_after_extract` (후보) | F23 과 같은 hex + 추가 `rgba(62,53,35,0.9)` (column 2 어두운 brown 헤더). 단일 frame 관찰값 — Token Inventory 비승격 (룰 #2) | `compare-table.css` family variant — F23 과 통합 후보 |
|
||||
| `compare-vs-rows.html` | F18 (`1171281195`) 의 slide-body 재구현 | `delete_after_extract` (후보) | `var(--color-compare-left)` / `var(--color-compare-right)` 기존 token 활용 — covered token 검증 증거 | `compare-paired.css` family |
|
||||
| `issues-paired-rows.html` | F17 (`1171281194`) 의 slide-body 재구현 | `delete_after_extract` (후보) | `--color-row-border: #60A451` inline 정의 — F17 단일 frame 관찰값, Token Inventory 비승격 (룰 #2). family CSS variant 처리 검토 | `compare-paired.css` family |
|
||||
| `prerequisites-3col.html` | F13 (`1171281190`) 의 slide-body 재구현 | `delete_after_extract` (후보) | `--color-col-N-{from,to}` 기존 token 활용 가능 — covered token 검증 증거 | `three-pillar.css` family |
|
||||
| `stacked-arrow-list.html` | F09 (`1171281180`) 의 slide-body 재구현 | `delete_after_extract` (후보) | 타이틀 바 `#fbd5b9` / 텍스트 `#144838` inline — F09 단일 frame 관찰값, Token Inventory 비승격 (룰 #2) | `pill-list.css` family |
|
||||
|
||||
---
|
||||
|
||||
## 6. 진행 단계
|
||||
|
||||
| 단계 | 상태 |
|
||||
|---|---|
|
||||
| 33 frame ↔ Integration Map 32 행 대조 | ✅ 완료 (`FRAME-INTEGRATION-MAP.md` row 21~28 ID 정정 반영) |
|
||||
| Inventory 골격 + 샘플 5 행 (이 문서) | ✅ 본 단계 |
|
||||
| 사용자 검토 | ⬜ |
|
||||
| Frame Inventory 27 행 일괄 확장 (32 frame 완성) | ⬜ |
|
||||
| Token Inventory 본격 작성 | ⬜ |
|
||||
| Legacy Reference 본격 작성 | ⬜ |
|
||||
| Phase Z catalog / runtime template 설계 | ⬜ (별도 단계) |
|
||||
| 사용자 승인 → `templates/blocks/` 신규 구조 교체 (프로모션 게이트) | ⬜ (별도 단계) |
|
||||
|
||||
### 샘플 5 검증 포인트
|
||||
|
||||
| 검증 항목 | 결과 |
|
||||
|---|---|
|
||||
| 변환 / 미변환 frame 이 같은 양식에 들어가는가 | ✅ — 미변환은 `Style Elements` 셀 1 개에 통일 보일러플레이트, 나머지 4 셀은 `—` (`Phase Z Target` 만 `TBD after conversion` 또는 `N/A — reference_only`) |
|
||||
| `Style Elements` 와 `Extracted Style Hints` 의 구분이 명확한가 | ✅ (Frame 18, 14) — 관찰 사실 (CSS 값 / 픽셀) vs 계승 의도 (패턴 / 의미) |
|
||||
| `Phase Z Target` 후보 표현이 통일되는가 | ✅ — 변환 frame 은 "(후보)" 명시, 미변환은 `TBD after conversion`, reference_only 는 `N/A — reference_only` |
|
||||
| 미변환 frame 이 `analysis.md` 내용을 redescribe 하지 않는가 | ✅ — 보일러플레이트 1 행 외 어떤 redescription 도 없음 |
|
||||
| 변환 frame 의 `Notes` 가 스타일 계승에 의미 있는 메타만 담는가 | ⚠️ 샘플은 적정. 32 행 확장 시 단순 출처 (Scale 값, "대표 frame" 등) 는 추가로 정리 필요 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 부록 — 제외 / 특수 항목
|
||||
|
||||
`figma_to_html_agent/blocks/` 의 33 개 디렉토리 중 `1171281171` 은 본 인벤토리 메인 32 frame 에서 제외한다 (`texts.md` 만 존재, `index.html` / `analysis.md` 없음, 정체 미확인). 상세는 [`FRAME-INTEGRATION-MAP.md` 부록](FRAME-INTEGRATION-MAP.md#부록--제외--특수-항목) 참조.
|
||||
@@ -1,206 +0,0 @@
|
||||
# Phase Z 매칭 아키텍처 — 원칙 anchor
|
||||
|
||||
> 22-step pipeline 의 *매칭 layer* (Step 5/6/7 + B-axis Step 9/10/11) 를 다루는 *원칙 anchor* doc.
|
||||
>
|
||||
> 본 문서는 *새 디자인 생성* 이 아니라 *기존 코드 / 과거 docs / 관찰 사례 / session 인사이트* 를 근거로 한 *forward improvement consolidation*.
|
||||
>
|
||||
> 관련 anchors :
|
||||
> - `docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md` (D1, 22-step pipeline)
|
||||
> - `docs/architecture/PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md` (D2, Layer A/B SPEC)
|
||||
> - `docs/architecture/PHASE-Z-CONTENT-OBJECT-SUBZONE-PLAN.md` (D3, schema completion plan)
|
||||
> - `docs/architecture/PHASE-Z-PIPELINE-STATUS-BOARD.md` (D4, 현재 status)
|
||||
|
||||
|
||||
## §0. 본 문서의 작성 방법론 (P0)
|
||||
|
||||
**evidence-based forward improvement** — 매번 *4 source* 를 거쳐 도출 :
|
||||
|
||||
1. 과거 docs (D1 / D2 / D3 / D4) — *원래 의도*
|
||||
2. 현재 코드 (`src/phase_z2_*.py` / `templates/phase_z2/catalog/frame_contracts.yaml`) — *실제 동작*
|
||||
3. 관찰된 혼선 / 실패 사례 — *경험적 evidence*
|
||||
4. session 인사이트 — *최근 정리된 mental model*
|
||||
|
||||
이걸 *관찰 → 혼선 → 도출 원칙 → 개선 방향* form 으로 표면화. *과거 회귀* 가 아니라 *과거를 근거로 한 개선*. *감으로 결정* / *가장 쉬운 선택* 금지.
|
||||
|
||||
|
||||
## §1. 현재 코드 상태 (관찰)
|
||||
|
||||
### 1.1 매칭 단위 — `CompositionUnit`
|
||||
|
||||
매칭의 *atomic unit* 은 section 이 아니라 `CompositionUnit`. `src/phase_z2_composition.py` 의 `collect_candidates` 가 *3 종 candidate type* 을 동시 생성 :
|
||||
|
||||
- `single` — `src/phase_z2_composition.py:230-243` (1 section 단독)
|
||||
- `parent_merged` — `src/phase_z2_composition.py:260-273` (parent 자체가 V4 매칭, children 묶음)
|
||||
- `parent_merged_inferred` — `src/phase_z2_composition.py:352-368` (children rep_match 기반 inferred merge)
|
||||
|
||||
각 candidate 는 `source_section_ids[]` + `merge_type` (line 232 / 262 / 354) 로 *어떤 section 들을 어떻게 묶었는지* 표현.
|
||||
|
||||
### 1.2 frame 선택 — render path authority = V4 rank-1
|
||||
|
||||
현재 render path 의 `frame_template_id` 는 composition planner 의 *V4 rank-1* 기반 :
|
||||
- `lookup_v4_match()` in `src/phase_z2_pipeline.py` (D1:212 명시) — rank-1 만 반환
|
||||
- composition planner 가 V4 결과로 candidate 생성
|
||||
|
||||
B4 (`src/phase_z2_placement_planner.py:90-107` 의 `_select_frame`) 도 frame selection 을 *수행* 하지만 *trace-only* — render path authority 는 V4 rank-1.
|
||||
|
||||
V4 = `top-k` 선언만 됐고 *rank-1 사용* 만 활성. D4 의 ⚠ partial.
|
||||
|
||||
### 1.3 binding — `phase_z2_mapper.map_with_contract` (Layer 1)
|
||||
|
||||
`src/phase_z2_mapper.py:584-609` 의 `map_with_contract(section, contract)` 는 contract 에서 *오직* 두 field 만 read :
|
||||
- `contract["source_shape"]` (split 규칙)
|
||||
- `contract["payload"]["builder"]` (named PAYLOAD_BUILDERS dispatch)
|
||||
|
||||
`accepted_content_types` / `sub_zones` 등 Layer 2 field 는 *접근 X*. 즉 mapper 는 *Layer 1 binder* 로 격리.
|
||||
|
||||
### 1.4 placement — `phase_z2_placement_planner` (Layer 2 reader, trace-only)
|
||||
|
||||
`src/phase_z2_placement_planner.py` :
|
||||
- `_select_frame` (90-107) — `accepted_content_types ⊇ content_type_set` cover + declaration order first
|
||||
- `_assign_region_to_sub_zone` (113-151) — `sub_zones` 의 narrowest-accepts first
|
||||
- `plan_placement` (157+) — Stage A (B2 internal regions) + Stage B (region ↔ sub_zone) 통합
|
||||
|
||||
B4 는 *Layer 2 reader* 이지만 `src/phase_z2_pipeline.py:1060-1145` 에서 *trace-only* 로만 호출. render path (slot_payload 생성) 미연결. D4:78-83 의 *render path placement_trace 미사용* 과 일치.
|
||||
|
||||
### 1.5 capacity / fit — classifier (post-render telemetry)
|
||||
|
||||
`src/phase_z2_classifier.py` 의 `classify_visual_runtime_check` — *render 후* visual measurement 기반 fit 판정. *Architectural reframe* (D2:16-33 의 PLANNING / RENDER / POST-RENDER 3-layer) : A1~A4 = *post-render telemetry layer*. *덜 중요* 가 아니라 *위치가 다름*. 매칭 결정 자체에는 직접 입력 X (현재).
|
||||
|
||||
|
||||
## §2. 확인된 혼선 (resolution)
|
||||
|
||||
### 2.1 Sub-zone 용어 4-방향 충돌 → 4-tier 분리 (P5'')
|
||||
|
||||
session 안 누적 혼선 :
|
||||
- D1 의 "Zone (top / bottom_l / bottom_r 등)"
|
||||
- composition.py 의 child unit 분리 (single / parent_merged 등)
|
||||
- yaml 의 `sub_zones` field
|
||||
- 사용자 mental model 의 "### split"
|
||||
|
||||
→ *4 tier 별 명칭 lock* :
|
||||
|
||||
| Tier | 명칭 | 위치 | 정체 |
|
||||
|---|---|---|---|
|
||||
| 1 | **Layout** | slide-level | slide-body 안 zone topology (8-preset vocabulary) |
|
||||
| 2 | **Zone** | layout 안 | 콘텐츠 구역 (top / bottom_l / bottom_r 등). 1 frame 매칭 단위 |
|
||||
| 3 | **Split Zone (Child Unit)** | zone 안 | composition planner 가 만든 child unit (parent_merged 의 분리 단위) |
|
||||
| 4 | **Frame Slot** | frame 안 | yaml 의 `sub_zones` = Layer B placement target. region 매칭 대상 |
|
||||
|
||||
이후 본 문서 / 후속 doc 은 *위 명칭 어휘* 만 사용. yaml field `sub_zones` 는 *기존 이름 유지하되 의미 = Frame Slot* 으로 lock (mechanical rename 은 D3 plan).
|
||||
|
||||
### 2.2 composition tie-break ≠ Frame Slot tie-break
|
||||
|
||||
scope-lock 단계에서 *D2:524-533 의 tie-break* 을 *composition tie-break evidence* 로 잘못 분류. 실제로는 :
|
||||
- D2:524-533 = *Frame Slot 단위* tie-break (Stage B 안, frame 이미 선택된 후)
|
||||
- composition tie-break = `composition.py:433-441` (sort + greedy + coverage)
|
||||
|
||||
두 layer 가 다름. P7 evidence 는 *composition layer* 만, *Frame Slot layer* 는 별개 location.
|
||||
|
||||
### 2.3 "Layer 2 미사용" framing 오류
|
||||
|
||||
scope-lock 초안의 *"mapper 가 Layer 2 를 consume 안 함"* framing 은 암묵적으로 *mapper 가 Layer 2 reader 가 돼야 한다* 의 fix direction 함의. 실제 architectural intent :
|
||||
- mapper = Layer 1 binder (의도된 격리)
|
||||
- B4 = Layer 2 reader (의도된 분리)
|
||||
|
||||
*문제* 는 *Layer 2 unconsumed* 가 아니라 *B4 의 Layer 2 read 가 trace-only 라 render path 까지 안 닿음*. *bridge* 가 답이지 *mapper 확장* 이 아님.
|
||||
|
||||
### 2.4 Step 4/5/9 분리 미완
|
||||
|
||||
현재 구현은 D1 이 의도한 *Step 4 → Step 5 → Step 9* 분리가 완성되지 않음 :
|
||||
- Step 4 (composition planning input — section_layout_signature / content_object 구조) = *partial/dormant* (D4:73 의 ⚠ partial transition)
|
||||
- Step 5 evidence 와 Step 9 final selection = *conflate* (D1:255)
|
||||
|
||||
D1:185 가 명시적으로 *Step 4 가 frame matching 보다 먼저 와야 함* 을 지적.
|
||||
|
||||
|
||||
## §3. 도출된 원칙
|
||||
|
||||
### P1 : 매칭 단위 = `CompositionUnit` (section 아님)
|
||||
|
||||
- *근거* : `composition.py:230-243` (single) / `:260-273` (parent_merged) / `:352-368` (parent_merged_inferred). 각 line `:232` / `:262` / `:354` 가 `merge_type` signal
|
||||
- *함의* : *MDX section* 을 1:1 zone 매칭 단위로 가정하는 코드 / doc 는 모두 *추상화 누락*. *CompositionUnit* 으로 통일.
|
||||
|
||||
### P3 : frame 선택 / content binding *layer 분리*
|
||||
|
||||
- *근거* : 현재 코드의 *de facto* 분리 (mapper §1.3 + placement_planner §1.4)
|
||||
- *원칙* : frame *선택* (어떤 frame 을 쓸지) 과 content *binding* (선택된 frame 에 콘텐츠를 어떻게 채울지) 는 *별개 axis*. 함께 결정하면 search space 가 곱셈으로 폭발 + 실패 격리 불가.
|
||||
- *함의* : 어떤 axis 가 frame 을 *결정* 하는지 + 어떤 axis 가 *binding* 하는지 *명시적 분리* — 한 module 이 둘 다 하면 회귀 위험.
|
||||
|
||||
### P5'' : 4-tier terminology lock
|
||||
|
||||
§2.1 표 그대로. *후속 doc / commit message / 코드 docstring* 모두 4-tier 어휘만 사용.
|
||||
|
||||
### P7 : candidate-based composition (sequential A/B 아님)
|
||||
|
||||
- *근거* :
|
||||
- 원리 : `docs/architecture/PHASE-Z-PIPELINE-OVERVIEW.md:216-218` ("child 따로 / sibling 묶기 / parent 단위" + scoring inputs)
|
||||
- 구현 : `composition.py:230-243` / `:260-273` / `:352-368` (3 candidate type 동시 생성)
|
||||
- 선택 : `composition.py:433-441` (`(score desc, source_section_ids count desc)` + greedy covered skip)
|
||||
- *원칙* : composition 은 "## → fail → ### split → re-merge" sequential 이 아니라 *3 candidate type 을 동시 생성 → score + coverage tie-break* 의 *parallel evaluation*.
|
||||
- D2:524-533 은 *Frame Slot tie-break (Stage B)* 로 본 P7 evidence 와 *별도 layer*.
|
||||
|
||||
### P8 : staged migration — frame 선택 authority + binding 진화 분리
|
||||
|
||||
#### P8-a (near-term)
|
||||
|
||||
- *목표* : frame selection authority 정리 (V4 rank-1 단독 → B4 informant 또는 B4-mediated 의 *어떤 형태*)
|
||||
- *유지* : mapper binding channel (PAYLOAD_BUILDERS) — 현재 working channel 안전
|
||||
- *open* : B4 결과를 render path frame selection 에 *어떻게 반영* 할지의 bridge 형태 → §5 의 Q-V4B4 / Q-LB 에서 별도 scope-lock
|
||||
|
||||
#### P8-b (longer-term, *지금 결정 X*)
|
||||
|
||||
- region / Frame Slot-aware slot_payload 진화
|
||||
- PLACEMENT_PAYLOAD_BUILDERS 등 별도 namespace 가능성
|
||||
- *DC2 Open question (Q-LB) 해결 후* 결정. 본 문서 시점에서는 *deferred*.
|
||||
|
||||
|
||||
## §4. 코드 변경 결정 지점
|
||||
|
||||
### DC1 : Step 4/5/9 분리 미완
|
||||
|
||||
- *현 상태* : D1 의도한 Step 4 → Step 5 → Step 9 분리가 완성되지 않음. Step 4 (composition planning input — section_layout_signature / content_object 구조) 는 *partial/dormant* (D4:73 의 ⚠ partial), Step 5 evidence 와 Step 9 final selection 은 *conflate* (D1:255).
|
||||
- *결정 지점* :
|
||||
- Step 4 가 frame matching *전* 에 composition candidate 평가 input 으로 흘러야 (D1:185 명시적 지적)
|
||||
- Step 5 evidence layer 와 Step 9 final selection layer 의 *명시적 분리* 필요
|
||||
- *영향 module* : `src/phase_z2_pipeline.py` orchestrator + `src/phase_z2_composition.py` (input 확장)
|
||||
|
||||
### DC2-a : `phase_z2_mapper` = Layer 1 working channel
|
||||
|
||||
- *현 상태* : `src/phase_z2_mapper.py:584-609` 가 `source_shape` + `payload.builder` 만 read. *현재 render path 의 유일 working channel*.
|
||||
- *결정 지점* : *Layer 1 격리 유지*. mapper 에 Layer 2 read 를 추가하는 방향은 *반대* — 실제 의도는 별 axis (DC2-b + Open question Q-LB).
|
||||
|
||||
### DC2-b : `phase_z2_placement_planner` = Layer 2 reader, render path 미연결
|
||||
|
||||
- *현 상태* : `src/phase_z2_placement_planner.py:90-107` (accepted_content_types) + `:113-151` (sub_zones) — Layer 2 read 활성. 그러나 `src/phase_z2_pipeline.py:1060-1145` 에서 *trace-only*. final render 미연결.
|
||||
- *결정 지점* : Layer 2 read 결과를 render path 에 *어떻게 합류시킬지* 의 bridge 결정 — §5 의 Q-LB 에서 별도 scope-lock.
|
||||
|
||||
### DC3 : Internal Region runtime — trace-only partial
|
||||
|
||||
- *현 상태* : SPEC v1 (D2) 가 Internal Region (Layer A) / Frame Slot (Layer B) 의 layered placement 정의. Layer A runtime 은 *trace-only partial* — `src/phase_z2_placement_planner.py:157+` 의 `plan_placement` 가 Stage A 호출 (`:192-197` 의 `plan_internal_regions` call) 수행하지만, 결과가 render path 미합류. *부재* 가 아니라 *render path authority 미연결*. D4:73 의 ⚠ partial 분류와 일치.
|
||||
- *결정 지점* : Layer A planning telemetry 활성 단계 → render path 합류 단계의 *separate axis*. P8-b 와 연관 (slot_payload 진화 이전 단계).
|
||||
|
||||
|
||||
## §5. open scope-lock questions
|
||||
|
||||
본 axis 범위 *밖* 의 deferred 결정. 후속 axis 에서 각각 별도로 lock.
|
||||
|
||||
### Q-FW : 4 filter score weight / threshold
|
||||
- F1 frame internal fit / F2 child frame divergence / F3 content type-structure match / F4 content loss risk 의 *score weight* 와 *auto vs review threshold* 결정 필요.
|
||||
|
||||
### Q-CO : candidate priority tie-break
|
||||
- composition.py:433 의 `(score, source_section_ids count)` 외에 *추가 axis* (cardinality_fit / hierarchy_coherence / density) 도입 시점.
|
||||
|
||||
### Q-RT : review / adapter_needed threshold
|
||||
- W1/W2/W3 신호 + auto_selectable=False candidate 의 review surface 정책.
|
||||
|
||||
### Q-V4B4 : V4 → B4 frame selection authority transition timing
|
||||
- P8-a 의 *언제* — V4 단독 / B4 informant / B4-mediated 의 단계.
|
||||
|
||||
### Q-LB : Layer 1 ↔ Layer 2 bridge architecture
|
||||
- DC2-b 의 *어떻게* — mapper direct consume / B4-mediated integration / 별도 translator. Q-V4B4 와 연관되나 *별개 layer* (frame 선택 timing vs Layer 2 → render path bridge 구조).
|
||||
|
||||
### Q-CE : catalog extension surface
|
||||
- frame_contracts.yaml 에 신규 frame 추가 시 *어떤 layer 부터 채워야 self-consistent* 인지의 declarative form.
|
||||
|
||||
### Q-DT : decision trace 표준 form
|
||||
- composition / placement / fit_classification 의 trace 통합 schema. 현재 각각 다른 dict 구조.
|
||||
@@ -1,472 +0,0 @@
|
||||
# Phase Z — master pipeline overview
|
||||
|
||||
**Status** : 마스터 reference (2026-04-30 잠금). 본 문서 = *워크플로우 전체 도면*. 향후 모든 작업은 *이 22-step 도면의 어느 위치에 속하는지* 먼저 self-locate 해야 함.
|
||||
|
||||
**용도** :
|
||||
- 새 작업 시작 시 — "지금 하는 게 22-step 중 어느 step 인가" 식별
|
||||
- 새 spec / memory rule 추가 시 — "어느 step 의 어느 의사결정에 적용되는가" 매핑
|
||||
- 새 sample / 새 frame 추가 시 — "어디서 막힐 가능성이 높은가" 사전 예측
|
||||
|
||||
**본 문서가 *하지 않는* 것** :
|
||||
- 새 구현 제안 X
|
||||
- next step 추천 X
|
||||
- 우선순위 결정 X
|
||||
- A/B/C 선택지 X
|
||||
- specific MDX sample 분석 X
|
||||
|
||||
본 문서는 *기준점*. 의사결정은 별도 step 에서.
|
||||
|
||||
---
|
||||
|
||||
## 3-block 구조
|
||||
|
||||
전체 22 step 은 다음 3 block 으로 grouping :
|
||||
|
||||
| Block | Step 범위 | 역할 |
|
||||
|---|---|---|
|
||||
| **A. PRE-RENDER PLANNING** | 0 — 12 | render *전* 모든 결정 — *slide-level zone 분배* + *zone-internal region 분배* + frame / slot 매핑. *진짜 fit policy 의 중심* |
|
||||
| **B. RENDER** | 13 | Jinja2 + frame partial → final.html |
|
||||
| **C. POST-RENDER TELEMETRY / EXCEPTION HANDLING** | 14 — 22 | render 결과 검증 + 분류 + routing + status. *exception 처리 layer* |
|
||||
|
||||
**중요** : 진짜 fit policy 의 자리는 A block (composition planning). C block (telemetry) 은 *exception 처리 + 진단 안내* layer. 둘 다 필요하지만 *위치가 다름*.
|
||||
|
||||
---
|
||||
|
||||
## 위계 + 용어 (entity hierarchy)
|
||||
|
||||
본 파이프라인은 다음 entity 위계 위에서 동작 :
|
||||
|
||||
> **Lock phrase (canonical)** : `Slide → Zone → Internal Region → Frame → Frame Slot → Content`
|
||||
|
||||
```
|
||||
Slide
|
||||
└─ Zone (slide-level layout 이 만든 큰 영역)
|
||||
└─ Internal Region (zone *내부* 영역, frame *밖*)
|
||||
└─ Frame (Figma design 단위)
|
||||
└─ Frame Slot (frame *내부* 자리)
|
||||
└─ Content unit (text / table / image / details / ...)
|
||||
```
|
||||
|
||||
### Universal Region Model
|
||||
|
||||
> **Lock phrase (canonical)** :
|
||||
> `Every Zone has 1+ Internal Regions.`
|
||||
> `text-only zone = single-region.`
|
||||
> `mixed-content zone = multi-region.`
|
||||
|
||||
```
|
||||
모든 Zone 은 1 개 이상의 Internal Region 을 가짐.
|
||||
|
||||
text-only zone = single-region zone (현 거동의 자연 표현)
|
||||
mixed-content zone = multi-region zone
|
||||
|
||||
각 Internal Region 은 *자기만의* :
|
||||
- frame match
|
||||
- display strategy (inline / preview+details / popup-only / dropped)
|
||||
을 가질 수 있음.
|
||||
```
|
||||
|
||||
text-only section 도 *single-region zone* 으로 표현 (= 현 거동 보존). mixed-content (text + table / text + image / 등) 은 *multi-region zone* 으로 확장. region 이 *first-class entity* — special case 가 아님.
|
||||
|
||||
### 용어 표
|
||||
|
||||
| 용어 | 의미 | 위치 |
|
||||
|---|---|---|
|
||||
| **Slide** | 1280×720 한 장 | 최상위 |
|
||||
| **Zone** | slide-level layout 이 만든 큰 영역 (top / bottom / left / right 등) | Slide 안 |
|
||||
| **Internal Region** | Zone *내부* 영역, frame *밖*. content type 기반 분할 (text region / table region / image region / details region) | Zone 안 |
|
||||
| **Frame** | Figma design 단위 (= F13 / F29 / F16 등) | Internal Region 안 |
|
||||
| **Frame Slot** | frame *내부* 자리 (= pillar_1 / quadrant_1 / process_column 등) | Frame 안 |
|
||||
| **Content unit** | MDX section 안의 typed 콘텐츠 조각 (text_block / table / image / details / ...) | Frame Slot 에 배치 |
|
||||
|
||||
> **주의** : `PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md` 의 `sub_zones` (YAML 필드명) 은 본 표의 *Frame Slot (Layer B)* 의미로 정의되어 있음. 본 표의 *Internal Region (Layer A)* 는 SPEC v1 §2 에 정의됨.
|
||||
|
||||
---
|
||||
|
||||
## Operating Principles / Hard Locks
|
||||
|
||||
본 섹션 = *anchor / index*. 각 원칙의 상세 정의 / 적용 룰 / 예외 처리는 *referenced source* 에 있음. drift 방지를 위해 OVERVIEW 는 *짧은 anchor* 로만 둠.
|
||||
|
||||
### 1. MDX mapping convention
|
||||
|
||||
| MDX | 슬라이드 |
|
||||
|---|---|
|
||||
| `# 대목차 제목` | `slide-title` |
|
||||
| `# 대목차 결론` / note | `slide-footer` |
|
||||
| `##` / `###` 본문 | `slide-body` 안 (layout + zone + region + frame + slot) |
|
||||
| `<details>` | 별도 details layer |
|
||||
|
||||
> 참조 : `CLAUDE.md` 의 *MDX → 슬라이드 매핑* 표
|
||||
|
||||
### 2. 자유 디자인 금지
|
||||
|
||||
Figma frame DB / catalog / frame contract 기반으로만 디자인 결정. *임의 HTML / CSS 디자인 생성 X*. AI 가 frame 자체 / layout 자체 / 새 디자인 패턴을 *생성하지 않음*.
|
||||
|
||||
> 참조 : `CLAUDE.md` 디자인 원칙 + `feedback_no_hardcoding` + `feedback_blocks_must_be_css`
|
||||
|
||||
### 3. 원문 무손실
|
||||
|
||||
MDX 원문 *삭제 / 요약 / 압축 금지*. AI 호출이 normal path 에서 콘텐츠를 *재작성하지 않음*. 원문은 본문 preview 또는 details/popup 어딘가에 *반드시* 보존.
|
||||
|
||||
> 참조 : `feedback_ai_isolation_contract` + `PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md` §5.2
|
||||
|
||||
### 4. 그릇 변경 원칙 (positive form)
|
||||
|
||||
콘텐츠가 안 맞을 때 *콘텐츠를 줄이지 않음*. 대신 *그릇* (layout / zone / internal region / frame / display strategy) 을 변경하여 수용. 공통 CSS / padding / tolerance 임의 축소는 *그릇 변경* 이 아님 → 금지.
|
||||
|
||||
> 참조 : `feedback_phase_z_spacing_direction`
|
||||
|
||||
### 5. preview / details 원칙
|
||||
|
||||
inline preview = 원문의 *일부* 만 빌려 보여주는 것. 원문은 details / popup 에 *반드시* 보존. preview 자체가 원문을 대체하지 않음.
|
||||
|
||||
> 참조 : `PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md` §5.1 / §5.5
|
||||
|
||||
---
|
||||
|
||||
## Heritage / Current State (참고)
|
||||
|
||||
본 섹션 = 시간 따라 변할 수 있는 *history / state* 기록. *원칙* 아님. frame DB 확장 / vocabulary 진화 시 mechanical 갱신.
|
||||
|
||||
### 1. Type A / B / B' / B'' → 8-layout vocabulary 진화
|
||||
|
||||
기존 *Type A / B / B' / B''* 의 4 preset 은 사라진 게 아니라 **8-layout vocabulary** (single / horizontal-2 / vertical-2 / top-1-bottom-2 / top-2-bottom-1 / left-1-right-2 / left-2-right-1 / grid-2x2) 로 *일반화* 된 *전신*. Step 7 의 8 vocabulary 는 이 진화의 결과.
|
||||
|
||||
### 2. 현재 runtime-verified frame set 은 text-frame 중심
|
||||
|
||||
현재 *runtime contract-registered / verified* frame set = `F13` (three_parallel_requirements) / `F29` (process_product_two_way) / `F16` (bim_issues_quadrant_four) — *모두 text 전용 성격*. `figma_to_html_agent/blocks` 의 전체 frame inventory 가 image / table / mixed frame 을 얼마나 포함하는지는 *전수 audit 전까지 미확정*. 따라서 현재 runtime 기준 :
|
||||
|
||||
- *text region* → frame 매칭 (현 거동)
|
||||
- *image region* / *table region* / *details region* → 현재 contract-registered frame set 안에서는 frame 매칭 근거가 부족하므로 *display strategy* 로 처리 (image area 직접 배치 / table preview / details button 등)
|
||||
|
||||
**Step 9 의 region 단위 매칭은 현재 *runtime-verified frame set 기준으로 text region 만 frame 매칭 가능*** 함을 인지. 전체 frame inventory audit 또는 contract 등록 상태가 바뀌면 본 항목은 갱신 대상.
|
||||
|
||||
---
|
||||
|
||||
## 22-step 상세
|
||||
|
||||
각 step 의 형식 :
|
||||
> **Step N. 이름** — purpose (1-2 줄)
|
||||
> **Status** : ✅ implemented / ⚠ partial / ❌ missing
|
||||
> **Code 위치** : (해당 시)
|
||||
> **Gap** : (해당 시)
|
||||
|
||||
### Block A — PRE-RENDER PLANNING
|
||||
|
||||
#### Step 0. 사전 준비
|
||||
파이프라인 가동 전 준비되어 있어야 하는 정적 자료들. catalog / contract / matching data / template / asset.
|
||||
|
||||
- **포함** : Figma/BEP frame → HTML 변환물 / frame catalog / frame contract / V4 matching data + ontology / slide-base template / render assets
|
||||
- **frame contract 필수 필드** : frame_id, template_id, accepted_content_types, slots, sub_zones, capacity, visual_hints, asset paths
|
||||
- **Status** : ⚠ partial
|
||||
- **Code 위치** : `templates/phase_z2/catalog/frame_contracts.yaml` / `tests/matching/v4_full32_result.yaml` / `templates/phase_z2/slide_base.html` / `templates/phase_z2/families/*.html` / `figma_to_html_agent/blocks/`
|
||||
- **Gap** : `accepted_content_types` 와 `sub_zones` 필드 contract 에 미선언. *visual_hints* 는 일부만 (min_height_px). *density envelope* 미선언.
|
||||
|
||||
#### Step 1. MDX 업로드
|
||||
사용자 MDX 파일 입력. 목표 : *MDX 1 → 자동 슬라이드 1 장*.
|
||||
|
||||
- **Status** : ✅ implemented
|
||||
- **Code 위치** : `src/phase_z2_pipeline.py` 의 CLI entry (`run_phase_z2_mvp1(mdx_path, run_id)`)
|
||||
|
||||
#### Step 2. MDX 정규화
|
||||
업로드된 MDX 를 파이프라인 표준 구조로 변환. frontmatter 분리 / slide title / heading tree / section id / 대중소 목차 관계 / note·footer·details 분리 / **raw content 보존**.
|
||||
|
||||
- **Status** : ⚠ partial
|
||||
- **Code 위치** : `parse_mdx()` (frontmatter, ## sections, footer 추출) + `align_sections_to_v4_granularity()` (### drilling)
|
||||
- **Gap** : heading tree 자체는 미생성 (현재 flat list). note / details 분리 미완. 대중소 목차 관계도 implicit. 정규화 결과가 *단순 문자열 + section_id* 수준 — heading tree 가 있는 *정규화 MDX 모델* 이 아직 아님.
|
||||
|
||||
#### Step 3. Content Object 추출
|
||||
각 section 의 raw content 를 type 별 객체로 분해. text_block / bullet_list / numbered_list / table / image / diagram / jsx_block / note / details / long_original. *MDX 원문 보존, AI 요약 X*.
|
||||
|
||||
- **Status** : ❌ missing
|
||||
- **Cross-reference** : `docs/architecture/PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md` §1 (content_object 정규화 schema)
|
||||
|
||||
#### Step 4. Section Internal Composition Planning
|
||||
각 section 을 어떻게 다룰지 결정 — *whole-section 단일 frame 매칭* / *child-section grouping* / *content-type split* 의 3-way decision. split 인 경우 *Internal Region* 들로 분해 + region 비율 산정. **이 단계가 frame matching 보다 *먼저* 와야 함**.
|
||||
|
||||
- **3-way decision** :
|
||||
```
|
||||
section 전체 → 1 frame 매칭 가능?
|
||||
├ YES → whole-section frame match (single-region zone)
|
||||
└ NO → child-section grouping 가능?
|
||||
├ YES → group merge → 1 frame 매칭 (single-region zone)
|
||||
└ NO → content-type split
|
||||
→ text region / table region / image region / details region
|
||||
→ region 비율 산정 (예: text 80% / table 20%)
|
||||
→ multi-region zone
|
||||
```
|
||||
- **출력** :
|
||||
- `section_layout_signature` = text_only / text_plus_table / text_plus_image / table_heavy / image_with_caption / mixed_visual_text / details_heavy
|
||||
- `composition_decision` = whole / group / split
|
||||
- `internal_regions` (split 인 경우) = [{region_id, role, content_type, ratio_estimate}, ...]
|
||||
- **Status** : ❌ missing
|
||||
- **Cross-reference** : `docs/architecture/PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md` §2 (Internal Region schema, Layer A — entity / Universal Region Model / 3-way decision tree / 비율 산정 / topology vocabulary / region → frame·display interface). §1 의 content_object size_estimate / role 도 입력 자료.
|
||||
|
||||
#### Step 5. Matching Evidence 생성
|
||||
정규화된 section + layout need 기반으로 V4 매칭 evidence 수집. *최종 선택이 아니라 후보 evidence*.
|
||||
|
||||
- **대상** : 소목차 section / 중목차 parent / 필요 시 sibling group 후보
|
||||
- **V4 출력** : top-k frame candidates (frame_id, template_id, confidence, label, axes score)
|
||||
- **Label** : use_as_is / light_edit / restructure / reject
|
||||
- **Status** : ⚠ partial
|
||||
- **Code 위치** : `lookup_v4_match()` in `phase_z2_pipeline.py`
|
||||
- **Gap** : 현재 *rank-1 만* 반환. top-k 사용 안 됨. sibling group 후보도 없음.
|
||||
|
||||
#### Step 6. Composition Planning
|
||||
어떤 MDX 덩어리를 하나의 *slide-level zone unit* 으로 볼지 결정. child 따로 / sibling 묶기 / parent 단위.
|
||||
|
||||
- **판단 기준** : heading 관계 / content_object 구조 / section_layout_signature / V4 top-k evidence / frame compatibility / capacity fit / content density
|
||||
- **Status** : ⚠ partial
|
||||
- **Code 위치** : `src/phase_z2_composition.py` (`plan_composition`, `parent_merged_inferred`, `capacity_fit` integration)
|
||||
- **Gap** : section_layout_signature / content_object 구조 input 부재 (step 3, 4 가 없어서). frame compatibility 도 rank-1 매칭만 활용.
|
||||
|
||||
#### Step 7. Slide-Level Layout Planning
|
||||
composition unit 개수와 성격을 보고 slide 전체 layout 선택. *기존 Type A/B/B'/B'' 의 후속 — 8-vocabulary 로 명시화*.
|
||||
|
||||
- **8 layout vocabulary** : single, horizontal-2, vertical-2, top-1-bottom-2, top-2-bottom-1, left-1-right-2, left-2-right-1, grid-2x2
|
||||
- **Status** : ⚠ partial
|
||||
- **Code 위치** : `src/phase_z2_composition.py` 의 `select_layout_preset()` + `LAYOUT_PRESETS`
|
||||
- **Gap** : 현재 *count-based 만* (1→single, 2→horizontal-2, 3→top-1-bottom-2, 4→grid-2x2). "성격" (content_object 분포 / section_layout_signature) 미반영. 8 preset 중 horizontal-2 + single 만 실제 검증됨.
|
||||
|
||||
#### Step 8. Zone + Internal Region Ratio Planning
|
||||
선택된 layout 안에서 각 zone 의 크기 / 비율 결정 + 각 zone *내부의* Internal Region 비율 결정. *두 단계 ratio* 산정 (zone-level + region-level). *50/50 고정 X*. *slide-base / title / divider / footer / gap 임의 축소 금지*.
|
||||
|
||||
- **두 단계 ratio** :
|
||||
- zone-level : layout 의 각 zone 크기 (slide-body 안 분배)
|
||||
- region-level : 각 zone 안 Internal Region 비율 (single-region 이면 100%, multi-region 이면 Step 4 의 ratio_estimate)
|
||||
- **기준** : composition unit 중요도 / content_object 분량 / text·table·image 비중 / frame aspect / capacity / min·max zone / region 별 content type
|
||||
- **Status** : ⚠ partial
|
||||
- **Code 위치** : `compute_zone_layout()` (min_height + content_weight 분배) + `build_layout_css()` in `phase_z2_pipeline.py`
|
||||
- **Gap** : horizontal-2 만 zone-level dynamic. 나머지 7 preset 은 fr-default. **region-level ratio 미구현** (Internal Region 자체가 Step 4 부재로 입력 X). content_object 분량 기반 정밀화 미반영.
|
||||
|
||||
#### Step 9. Region-Level Frame / Display Selection
|
||||
각 *Internal Region* 에 들어갈 frame 또는 display strategy 확정. step 5 evidence 위에 composition / layout / region 제약 반영해 *최종* 선택. *unit of analysis = region*. single-region zone 은 자연스럽게 zone 1:1 frame 선택과 같음.
|
||||
|
||||
- **region 별 처리** :
|
||||
- text region → text frame 매칭 (현 runtime-verified contract set 기준 F13 / F29 / F16 등)
|
||||
- table region → table preview / details / table frame
|
||||
- image region → image area / image frame
|
||||
- details region → details / popup 전용 region
|
||||
- **Label 처리** (region 단위) :
|
||||
- use_as_is → deterministic slot mapping
|
||||
- light_edit → 같은 frame contract 유지, minor adaptation 가능
|
||||
- restructure → frame 후보 유지하되 content-to-slot 재배치 proposal 필요
|
||||
- reject → 자동 적용 X
|
||||
- **Status** : ⚠ partial — *step 5 와 분리되지 않음 + region-level 미구현 (zone 단위 만)*
|
||||
- **Code 위치** : `plan_composition()` 이 V4 rank-1 즉시 선택 (step 5 와 conflate, zone 단위)
|
||||
- **Gap** : top-k 활용 / composition 제약 반영한 final 단계가 없음. *region-level 매칭 부재* (현재 zone 단위만). restructure label 은 현재 *filter* (선택 X). MVP1_ALLOWED_STATUSES = {matched_zone, adapt_matched_zone} 만 통과.
|
||||
|
||||
#### Step 10. Frame Contract 확인
|
||||
선택된 frame 의 contract 읽어서 accepted_content_types / slots / sub_zones / cardinality / capacity / visual_hints / density envelope / asset 확인.
|
||||
|
||||
- **Status** : ⚠ partial
|
||||
- **Code 위치** : `get_contract()` + `frame_contracts.yaml` (F13/F29/F16)
|
||||
- **Gap** : `accepted_content_types` 미선언. `sub_zones` 미선언. `density envelope` 미선언.
|
||||
- **Cross-reference** : `docs/architecture/PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md` §3 (frame contract + Frame Slot, Layer B)
|
||||
|
||||
#### Step 11. Content Unit / Child Group → Internal Region → Frame Slot Mapping
|
||||
각 zone 안에서 *Internal Region 별로* content unit 또는 child group 을 배치 → 그 region 의 frame 내부 *Frame Slot* 에 매핑. 표 작으면 inline / 크면 preview + 자세히보기 / image aspect 유지 / 긴 원문 details / text capacity 내.
|
||||
|
||||
- **2 단계 매핑** :
|
||||
- Layer A : content unit / child group → Internal Region (Step 4 의 region 분할 결과 소비)
|
||||
- Layer B : Internal Region 안 → Frame Slot (frame contract 의 sub_zone 선언 소비)
|
||||
- **Status** : ❌ missing
|
||||
- **Cross-reference** : `docs/architecture/PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md` §4 (placement algorithm 2-stage: Stage A → Stage B) + §5 (display strategy). *해당 SPEC 의 `sub_zones` (YAML 필드명) = Frame Slot (Layer B). Internal Region (Layer A) 는 §2 에 정의됨.*
|
||||
|
||||
#### Step 12. Slot Payload 생성
|
||||
frame partial 에 주입할 데이터 생성. *deterministic mapper* 가 기본. *AI 는 normal path 에 없음*.
|
||||
|
||||
- **AI 가능 위치 (제한적)** : light_edit / restructure 에서 content_object → slot 배치 proposal 필요 시
|
||||
- **AI 금지** : MDX 원문 요약·삭제 / HTML·CSS 직접 생성 / 새 디자인 임의 / layout·frame 임의 선택
|
||||
- **Status** : ✅ implemented (deterministic 부분)
|
||||
- **Code 위치** : `src/phase_z2_mapper.py` (`map_with_contract`, PAYLOAD_BUILDERS, ITEM_PARSERS)
|
||||
- **Gap** : restructure label 의 AI proposal path 미구현 (현재 restructure 는 filter). content_object → sub_zone 매핑이 step 11 부재로 *implicit*.
|
||||
|
||||
### Block B — RENDER
|
||||
|
||||
#### Step 13. Render
|
||||
Jinja2 로 HTML 생성. **고정** : slide-base / slide size / title / divider / footer / slide-body. **가변** : layout / zone ratio / frame partial / slot payload / assets.
|
||||
|
||||
- **산출** : final.html / assets/ / debug.json / preview.png
|
||||
- **Status** : ✅ implemented
|
||||
- **Code 위치** : `render_slide()` in `phase_z2_pipeline.py` + `templates/phase_z2/slide_base.html` + `templates/phase_z2/families/*.html`
|
||||
|
||||
### Block C — POST-RENDER TELEMETRY / EXCEPTION HANDLING
|
||||
|
||||
> 본 block 의 핵심 — *A block (planning) 이 정밀하면 거의 trigger 안 일어남*. 이상적으로 대기 상태. exception 케이스의 *진단 + 다음 capability 안내*.
|
||||
|
||||
#### Step 14. Selenium Visual Runtime Check
|
||||
브라우저 렌더링 기준 실제 결과 검사. slide size / zone overflow / frame internal clipping / text·table·image clipping / content truncation.
|
||||
|
||||
- **Status** : ⚠ partial
|
||||
- **Code 위치** : `run_overflow_check()` in `phase_z2_pipeline.py`
|
||||
- **Gap** : 현재 *text / structural element overflow* 만 검사. image aspect mismatch / table clipping / under-fill 검사 미구현. clipped_inner 의 inner_content_signals 는 추가됨 (A1 step).
|
||||
|
||||
#### Step 15. Fit Classification
|
||||
visual fail 발생 시 원인 분류.
|
||||
|
||||
- **카테고리** : minor_overflow / structural_minor_overflow / structural_major_overflow / tabular_overflow / image_aspect_mismatch / frame_capacity_mismatch / layout_zone_mismatch / hard_visual_fail
|
||||
- **Status** : ✅ implemented (text / structural 도메인)
|
||||
- **Code 위치** : `src/phase_z2_classifier.py` (`classify_visual_runtime_check`, `CONTENT_TYPE_PATTERNS`)
|
||||
- **Cross-reference** : `docs/architecture/PHASE-Z-FIT-CLASSIFIER-ROUTER-SPEC.md` §1 / §2 / §3
|
||||
- **Gap** : image_aspect_mismatch / tabular_overflow 분류는 정의됐지만 *실제 trigger 가 step 14 의 검사 부재로 일어나지 않음*.
|
||||
|
||||
#### Step 16. Overflow Router
|
||||
fit classification 결과를 action 후보로 매핑.
|
||||
|
||||
- **매핑 예** : structural_minor_overflow → zone_ratio_retry / tabular_overflow → details_popup_candidate / image_aspect_mismatch → image_fit_candidate / frame_capacity_mismatch → frame_internal_fit_candidate
|
||||
- **Status** : ✅ implemented
|
||||
- **Code 위치** : `src/phase_z2_router.py` (`route_fit_classification`, `ACTION_BY_CATEGORY`)
|
||||
- **Cross-reference** : `docs/architecture/PHASE-Z-FIT-CLASSIFIER-ROUTER-SPEC.md` §4
|
||||
|
||||
#### Step 17. Implemented Action 실행
|
||||
구현된 action 만 실행. retry budget 제한 / 성공시만 final.html promote / 실패 candidate 는 final.html 아님 / 공통 CSS·padding·tolerance 변경 X / MDX 내용 삭제·요약 X.
|
||||
|
||||
- **Status** : ⚠ partial
|
||||
- **Implemented** : `zone_ratio_retry` (A3)
|
||||
- **Code 위치** : `src/phase_z2_retry.py` (`plan_zone_ratio_retry`, `apply_retry_to_layout_css`) + `_attempt_zone_ratio_retry` orchestrator in `phase_z2_pipeline.py`
|
||||
- **Missing actions** : `layout_adjust` / `frame_reselect` / `details_popup_escalation` / `image_fit_candidate` / `frame_internal_fit_candidate`
|
||||
- **Note (사용자 잠금)** : `frame_internal_fit_candidate` 가 *허용할 수 있는 내부 sub-mechanism* (density envelope / line rhythm / internal grid row / text block allocation 등) 은 *frame contract 가 declare 한 envelope 안* 에서만 동작하는 *내부 영역*. **별도 action label 로 등재하지 않음** — `density_adjust_candidate` 같은 이름은 *공통 CSS/padding 축소 antipattern* 을 초대할 위험이 있어 *unified label `frame_internal_fit_candidate` 하나* 로 묶음.
|
||||
|
||||
#### Step 18. Failure Classification
|
||||
action 실패 시 원인 분류.
|
||||
|
||||
- **Failure types** : donor_slack_insufficient / no_donor_candidates / rerender_still_fails / not_attempted
|
||||
- **Status** : ✅ implemented
|
||||
- **Code 위치** : `src/phase_z2_failure_router.py` (`classify_retry_failure`, `FAILURE_TYPE_DESCRIPTIONS`)
|
||||
|
||||
#### Step 19. Next Action Proposal
|
||||
실패 원인 + 원래 overflow severity *함께* 보고 다음 후보 기록. failure_type 단독 X. **overflow_category + line_equivalent + failure_type 의 결합**으로 결정.
|
||||
|
||||
- **예시 (severity-aware)** :
|
||||
- structural_minor_overflow + donor_slack_insufficient → frame_internal_fit_candidate
|
||||
- structural_major_overflow + * → details_popup_candidate
|
||||
- tabular_overflow + * → table_preview_or_details_candidate
|
||||
- frame mismatch → frame_reselect_candidate
|
||||
- **Status** : ⚠ partial
|
||||
- **Code 위치** : `src/phase_z2_failure_router.py` (`route_retry_failure`, `NEXT_ACTION_BY_FAILURE`)
|
||||
- **Gap** : 현재 *failure_type 단독* mapping (1-차원). severity (overflow_category × line_equivalent) 와의 *2-차원* mapping 미구현. `frame_internal_fit_candidate` 의 *execution contract / internal envelope* 미정의 (label 자체는 router/failure routing 에 등장하지만 *실제로 어떻게 동작하는지 + frame contract 가 declare 할 envelope 의 형식* 은 미정).
|
||||
|
||||
#### Step 20. Slide Status 결정
|
||||
final.html 존재 ≠ PASS. 정확한 상태 분류.
|
||||
|
||||
- **Status enum** : PASS / RENDERED_WITH_VISUAL_REGRESSION / PARTIAL_COVERAGE / ABORTED
|
||||
- **판단** : 모든 section coverage + visual ok → PASS / visual fail 있음 → RENDERED_WITH_VISUAL_REGRESSION / 일부 section 만 렌더 → PARTIAL_COVERAGE / 필수 단계 실패 → ABORTED
|
||||
- **Status** : ✅ implemented
|
||||
- **Code 위치** : `compute_slide_status()` in `phase_z2_pipeline.py`
|
||||
|
||||
#### Step 21. Debug / Trace 기록
|
||||
전체 의사결정을 debug.json 에 기록. 정규화 MDX / content_objects / section_layout_signature / V4 evidence / composition_units / layout / zone sizes / frames / contracts / sub_zone mapping / slot_payload / render result / visual check / fit classification / router decision / action trace / failure classification / next action proposal / slide_status.
|
||||
|
||||
- **Status** : ⚠ partial
|
||||
- **Code 위치** : `write_debug_json()` in `phase_z2_pipeline.py`
|
||||
- **Gap** : content_objects / section_layout_signature / sub_zone mapping 항목은 step 3, 4, 11 부재로 미기록. *region-level telemetry* (region count / region ratios / region-level frame matching / region-level display strategy) 도 Internal Region (Layer A) 부재로 미기록. 그 외 항목은 모두 기록됨.
|
||||
|
||||
#### Step 22. 사용자 확인 / Export
|
||||
사용자가 결과 확인. 현재 목표 = MDX → 자동 슬라이드 1 장 → status / debug. 향후 = layout 재선택 UI / top3 frame 선택 UI / zone 이동 / HTML 다운 / Gitea push.
|
||||
|
||||
- **Status** : ❌ missing (UI 영역 — 현재 범위 외)
|
||||
- **Code 위치** : 없음 (CLI 만)
|
||||
|
||||
---
|
||||
|
||||
## Status matrix 요약
|
||||
|
||||
| Block | Step | Status |
|
||||
|---|---|---|
|
||||
| A | 0. 사전 준비 | ⚠ partial |
|
||||
| A | 1. MDX 업로드 | ✅ |
|
||||
| A | 2. MDX 정규화 | ⚠ partial |
|
||||
| A | 3. Content Object 추출 | ❌ |
|
||||
| A | 4. Section Internal Composition Planning | ❌ |
|
||||
| A | 5. Matching Evidence | ⚠ partial (rank-1 only) |
|
||||
| A | 6. Composition Planning | ⚠ partial |
|
||||
| A | 7. Slide-Level Layout Planning | ⚠ partial (count-based) |
|
||||
| A | 8. Zone + Internal Region Ratio Planning | ⚠ partial (zone-level horizontal-2 만 dynamic, region-level 미구현) |
|
||||
| A | 9. Region-Level Frame / Display Selection | ⚠ merged with step 5 + region-level 미구현 |
|
||||
| A | 10. Frame Contract 확인 | ⚠ partial (no sub_zones) |
|
||||
| A | 11. Content Unit / Child Group → Internal Region → Frame Slot Mapping | ❌ |
|
||||
| A | 12. Slot Payload 생성 | ✅ (deterministic) |
|
||||
| B | 13. Render | ✅ |
|
||||
| C | 14. Selenium Visual Runtime Check | ⚠ partial (text/structural only) |
|
||||
| C | 15. Fit Classification | ✅ |
|
||||
| C | 16. Overflow Router | ✅ |
|
||||
| C | 17. Implemented Action 실행 | ⚠ partial (zone_ratio_retry only) |
|
||||
| C | 18. Failure Classification | ✅ |
|
||||
| C | 19. Next Action Proposal | ⚠ partial (1-D mapping) |
|
||||
| C | 20. Slide Status 결정 | ✅ |
|
||||
| C | 21. Debug / Trace 기록 | ⚠ partial (planning trace 누락) |
|
||||
| C | 22. 사용자 확인 / Export | ❌ (UI 미구현) |
|
||||
|
||||
**핵심 gap 위치 (❌ 표시)** :
|
||||
- Step 3 — Content Object 추출
|
||||
- Step 4 — Section Internal Composition Planning (3-way decision + Internal Region 분할)
|
||||
- Step 11 — Content Unit / Child Group → Internal Region → Frame Slot Mapping
|
||||
- Step 22 — 사용자 UI
|
||||
|
||||
**부분 구현 위치 (⚠) 의 주요 결손** :
|
||||
- Step 5 — top-k 미사용
|
||||
- Step 8 — region-level ratio 미구현 (zone-level horizontal-2 만 dynamic)
|
||||
- Step 9 — Step 5 와 conflate + region-level 매칭 부재
|
||||
- Step 10 — sub_zones 미선언 (frame contract / Layer B)
|
||||
- Step 14 — image / table 검사 부재
|
||||
- Step 17 — `zone_ratio_retry` 외 action 모두 미구현
|
||||
- Step 19 — severity-aware 2-차원 매핑 미구현
|
||||
- Step 21 — planning trace 누락 (step 3, 4, 11 부재 종속) + region-level telemetry 미기록 (Layer A 부재 종속)
|
||||
|
||||
---
|
||||
|
||||
## 기존 spec 문서 cross-reference
|
||||
|
||||
| Spec 문서 | 다루는 step |
|
||||
|---|---|
|
||||
| `docs/architecture/PHASE-Z-CATALOG-RUNTIME-DESIGN.md` | Step 0 (catalog 룰), Step 10 (frame contract), Step 12 (mapper) |
|
||||
| `docs/architecture/PHASE-Z-FRAME-STYLE-INVENTORY.md` | Step 0 (frame inventory) |
|
||||
| `docs/architecture/FRAME-INTEGRATION-MAP.md` | Step 0 (frame inventory) |
|
||||
| `docs/architecture/PHASE-Z-FIT-CLASSIFIER-ROUTER-SPEC.md` | Step 14, 15, 16, 17, 18, 19 |
|
||||
| `docs/architecture/PHASE-Z-CONTENT-OBJECT-SUBZONE-SPEC.md` | Step 3 (§1), Step 4 (§2 Internal Region / Layer A), Step 10 (§3 frame contract + Frame Slot / Layer B), Step 11 (§4 placement 2-stage + §5 display strategy). *해당 SPEC 의 `sub_zones` (YAML 필드명) = Frame Slot (Layer B). Internal Region (Layer A) 는 §2 에 정의됨.* |
|
||||
|
||||
## Memory feedback rules cross-reference
|
||||
|
||||
| Memory rule | 적용 step / 의사결정 |
|
||||
|---|---|
|
||||
| `feedback_one_step_per_turn` | 모든 step (작업 분할 discipline) |
|
||||
| `feedback_no_hardcoding` | 모든 step (특히 9, 11, 12, 17) |
|
||||
| `feedback_ai_role_separation` | Step 12 (AI 위치 제한) |
|
||||
| `feedback_ai_isolation_contract` | Step 12 (normal path AI 금지) |
|
||||
| `feedback_phase_z_spacing_direction` | Step 17 (CSS 공통 spacing 변경 금지) |
|
||||
| `feedback_artifact_status_naming` | Step 20 (slide_status enum) |
|
||||
| `feedback_auto_pipeline_first` | Block C 전체 (review/UI 개념 끼우지 말 것) |
|
||||
| `feedback_sample_budget` | Step 1 (미사용 sample 분리 보존) |
|
||||
| `feedback_detail_quality` | 모든 step (self-check) |
|
||||
| `feedback_blocks_must_be_css` | Step 13 (frame partial CSS 원칙) |
|
||||
| `feedback_recipe_variety` | Step 7, 9 (vocabulary 표현 범주) |
|
||||
| `feedback_absolute_paths` | 보고 / 문서 작성 시 |
|
||||
| `feedback_html_preview_whitebg` | Step 13 (slide-base 배경) |
|
||||
| `feedback_figma_*` | Step 0 (figma frame 변환 / asset 작업) |
|
||||
|
||||
---
|
||||
|
||||
## How to use this document
|
||||
|
||||
새 작업 시작 시 :
|
||||
1. *어느 step* 의 작업인지 식별
|
||||
2. 그 step 의 *Status* 확인 (✅ / ⚠ / ❌)
|
||||
3. 해당 step 의 cross-reference 된 spec 문서 / memory rule 확인
|
||||
4. 작업 결과가 *다른 step 에 영향* 주는지 확인 (block A 변경 → block C 의 trace 자동 변동)
|
||||
|
||||
새 spec 문서 추가 시 :
|
||||
- 본 문서의 *cross-reference 표* 에 등록 (어느 step 영역인지)
|
||||
|
||||
새 memory rule 추가 시 :
|
||||
- 본 문서의 *Memory feedback rules cross-reference* 표에 등록 (어느 step 의 의사결정인지)
|
||||
|
||||
작업 도중 — *어느 step 에 속하는지 모르는 작업이 들어오면* — 본 22-step 도면에 매핑이 안 된다는 것 자체가 *작업이 over-scoped 되었거나 새 step 정의가 필요* 하다는 신호.
|
||||
|
||||
---
|
||||
|
||||
## 본 문서의 보존 / 변경 정책
|
||||
|
||||
- 본 문서는 *기준점*. 가벼운 정정 / status 갱신은 진행 가능 (예: ❌ → ⚠ → ✅ 변동)
|
||||
- *22 step 의 추가 / 제거 / 순서 변경* 은 사용자 명시 잠금 후에만
|
||||
- 본 문서의 *3-block 구조* 는 architectural reframe lock 의 직접 반영. 변경 시 reframe 자체를 다시 봄
|
||||
@@ -1,158 +0,0 @@
|
||||
# Phase Z — pipeline status board
|
||||
|
||||
**Snapshot date** : 2026-05-04 (B1~B5 + trace-only runtime 연결 closure 반영 — Layer A telemetry first activation)
|
||||
**역할** : 현재 위치표 / grading snapshot. *지도 본문* 은 [`PHASE-Z-PIPELINE-OVERVIEW.md`](PHASE-Z-PIPELINE-OVERVIEW.md).
|
||||
|
||||
| 문서 | 역할 | 변동 |
|
||||
|---|---|---|
|
||||
| `PHASE-Z-PIPELINE-OVERVIEW.md` | 고정 지도 (22-step 도면) | 거의 안 바뀜 |
|
||||
| `PHASE-Z-PIPELINE-STATUS-BOARD.md` | 현재 진행 snapshot | 자주 갱신 |
|
||||
|
||||
본 문서가 *하지 않는* 것 :
|
||||
- 새 구현 제안 X
|
||||
- next step 추천 X
|
||||
- 우선순위 결정 X
|
||||
- A/B/C 선택지 X
|
||||
- MDX03 / MDX04 추가 분석 X
|
||||
- 코드 변경 X
|
||||
- OVERVIEW 구조 수정 X
|
||||
|
||||
---
|
||||
|
||||
## 1. Counting rule
|
||||
|
||||
```
|
||||
Step 0 = precondition (파이프라인 가동 전 사전 준비)
|
||||
Step 1~22 = runtime pipeline ("22-step pipeline" = 이 범위)
|
||||
총 항목 수 = 23 (Step 0 + Step 1~22)
|
||||
명명 = "22-step" (runtime 기준)
|
||||
```
|
||||
|
||||
Step 0 은 본체가 아닌 *준비 조건*. Step 1 (MDX 업로드) 부터가 runtime entry.
|
||||
|
||||
---
|
||||
|
||||
## 2. 22-step status board
|
||||
|
||||
| Block | Step | 이름 | Status |
|
||||
|---|---|---|---|
|
||||
| — | 0 | 사전 준비 (catalog / contract / V4 / template / asset) | ⚠ partial |
|
||||
| A | 1 | MDX 업로드 | ✅ |
|
||||
| A | 2 | MDX 정규화 | ⚠ partial |
|
||||
| A | 3 | Content Object 추출 | ⚠ partial (B1 v0 dormant module + trace-only runtime 호출, render path 미연결) |
|
||||
| A | 4 | Section Internal Composition Planning | ⚠ partial (B2 v0 dormant module + trace-only runtime 호출, render path 미연결) |
|
||||
| A | 5 | Matching Evidence 생성 | ⚠ partial (rank-1 only) |
|
||||
| A | 6 | Composition Planning | ⚠ partial |
|
||||
| A | 7 | Slide-Level Layout Planning | ⚠ partial (count-based) |
|
||||
| A | 8 | Zone + Internal Region Ratio Planning | ⚠ partial (zone-level horizontal-2 만 dynamic, region-level 은 B2 안 partial) |
|
||||
| A | 9 | Region-Level Frame / Display Selection | ⚠ partial (B4 가 catalog cover + declaration order 로 frame 선택 분담 / V4 evidence 미통합 / Step 5 와 conflate 잔존) |
|
||||
| A | 10 | Frame Contract 확인 | ⚠ partial (B3 의 accepted_content_types + sub_zones 선언 추가 — B4 만 읽음, mapper 미읽음 / density envelope 별 axis) |
|
||||
| A | 11 | Content Unit / Child Group → Internal Region → Frame Slot Mapping | ⚠ partial (B4 v0 dormant 2-stage + region 1:1 sub_zone + narrowest first + trace-only runtime 호출, render path 미연결) |
|
||||
| A | 12 | Slot Payload 생성 | ✅ (deterministic) |
|
||||
| B | 13 | Render | ✅ |
|
||||
| C | 14 | Selenium Visual Runtime Check | ⚠ partial (text/structural overflow + B5 frame_slot_metrics F29 만 / image / table 검사 부재) |
|
||||
| C | 15 | Fit Classification (A1) | ✅ |
|
||||
| C | 16 | Overflow Router (A2) | ✅ |
|
||||
| C | 17 | Implemented Action 실행 (A3) | ⚠ partial (zone_ratio_retry only) |
|
||||
| C | 18 | Failure Classification (A4-1) | ✅ |
|
||||
| C | 19 | Next Action Proposal (A4-2) | ⚠ partial (1-D mapping) |
|
||||
| C | 20 | Slide Status 결정 | ✅ |
|
||||
| C | 21 | Debug / Trace 기록 | ⚠ partial (placement_trace per-zone 기록 + frame_slot_metrics F29 기록 — render path 활성화 X / region marker partial 미주입) |
|
||||
| C | 22 | 사용자 확인 / Export | ⚠ future (UI 영역 — 현재 범위 외) |
|
||||
|
||||
범례 :
|
||||
- ✅ implemented
|
||||
- ⚠ partial
|
||||
- ❌ missing
|
||||
- ⚠ future (현 범위 외 — 후속)
|
||||
|
||||
---
|
||||
|
||||
## 3. 핵심 missing (전이 후)
|
||||
|
||||
이전 Step 3 / 4 / 11 = ❌ missing → **본 session 작업으로 ⚠ partial 로 전이**.
|
||||
|
||||
**현재 *남은* gap** :
|
||||
|
||||
```
|
||||
1. render path 의 placement_trace 활용 X
|
||||
- B4 PlacementPlan 이 trace-only — render_slide() / mapper 가 미사용
|
||||
- region-id / content_unit-id marker 가 partial template 에 미주입 (B5 후속 axis)
|
||||
|
||||
2. B4 frame_selection 의 V4 evidence 미통합
|
||||
- B4 v0 = catalog declaration order 만 (cover + first-match)
|
||||
- composition_planner 의 V4 rank-1 와 *cross-axis 비교 자료* 만 — 통합 미완
|
||||
|
||||
3. region-level / Frame Slot-level partial 측정
|
||||
- B5 v0 frame_slot_metrics = F29 1 partial 만
|
||||
- F13 / F16 marker 미적용
|
||||
|
||||
4. 그 외 잔존
|
||||
- rules 2~5 (region-preview-details / region-grid-2x2 / region-main-support /
|
||||
region-horizontal-split) 의 algorithm 미구현 (SPEC v1 §2.5 deferred)
|
||||
- frame contract 의 density envelope 미선언
|
||||
- tabular_overflow / image_aspect_mismatch 검사 부재 (Step 14)
|
||||
- layout_adjust / frame_reselect / details_popup_escalation / image_fit /
|
||||
frame_internal_fit_candidate (Step 17 missing actions) 미구현
|
||||
```
|
||||
|
||||
**Cross-cutting Layer A — 진전 단계 정리** :
|
||||
|
||||
| 단계 | 상태 |
|
||||
|---|---|
|
||||
| (a) OVERVIEW reframe (Layer A first-class lock + Universal Region Model) | ✓ |
|
||||
| (b) SPEC v1 schema (Internal Region §2 + topology vocabulary §2.5 + 2-stage placement §4) | ✓ |
|
||||
| (c) PLAN v1 (cross-ref sync) | ✓ |
|
||||
| (d) B1 v0 ContentObject extractor (dormant) | ✓ |
|
||||
| (e) B2 v0 InternalRegion planner (dormant) | ✓ |
|
||||
| (f) B3 frame_contracts.yaml extension (dormant catalog 면) | ✓ |
|
||||
| (g) B4 v0 placement planner (dormant) | ✓ |
|
||||
| (h) B5 v0 Frame Slot telemetry markers (F29 만) | ✓ |
|
||||
| (i) trace-only runtime 연결 (B1→B2→B4 real data 첫 호출 / debug.json placement_trace) | ✓ |
|
||||
| (j) **render path 활성화 (region marker partial 주입 / B4 → mapper 통합 / V4 evidence 통합)** | **❌ pending** |
|
||||
|
||||
= (a)~(i) 완료 + (j) 가 *남은 핵심 axis* (B5 후속 / runtime 통합).
|
||||
|
||||
**Step 22** 는 별도 범주 (UI 영역 — 현재 자동 파이프라인 범위 외).
|
||||
|
||||
---
|
||||
|
||||
## 4. 구조 적절성 검토 (brief)
|
||||
|
||||
> snapshot — 22-step *재구성 / 합치기 / 쪼개기 제안 X*. OVERVIEW 영역.
|
||||
|
||||
- **3-block 구조 (A 계획 / B 렌더 / C 사후 telemetry) 적절**. 위계 추가 (Zone Internal Region) 후에도 block 경계는 변동 없음
|
||||
- **Step 3~4 가 Step 5 보다 앞** 인 순서 적절. content_object 와 internal composition decision (3-way) 이 frame matching 의 입력이어야 함
|
||||
- **Step 5 (evidence 생성) 와 Step 9 (final frame / display 선택) 가 분리** 된 구조 적절. 현재 conflate 된 건 구현 결손이지 도면 결손 아님. Step 9 의 unit of analysis = *region* 으로 reframe (OVERVIEW)
|
||||
- **A1~A4 는 post-render telemetry layer**. 진짜 fit policy 의 자리는 Block A (composition planning, region 분할 포함). C block 은 *exception 처리 + 진단 안내*
|
||||
- **Universal Region Model 적용 후에도 step numbering 보존** : Layer A 도입은 step 추가가 아니라 Step 4 / 8 / 9 / 11 의 *granularity unit shift* 로 흡수됨. step 0 ~ 22 그대로
|
||||
- **Layer A trace-only runtime 활성화 = boolean 차원 X** : B1~B4 가 *real MDX runtime 위에서 호출* 되나 *render path 미대체*. debug.json 의 placement_trace = *진단 telemetry only* — final.html / canonical SHA 미영향. *render 활성화* 는 별 axis (B5 후속)
|
||||
|
||||
---
|
||||
|
||||
## 5. AI 사용 위치 (runtime 기준)
|
||||
|
||||
```
|
||||
runtime AI = Step 12 의 light_edit / restructure 1 곳만
|
||||
├ 입력 : content_object + frame contract + Internal Region 배치 + Frame Slot 명세
|
||||
├ 출력 : content → Internal Region / Frame Slot proposal
|
||||
└ 금지 : MDX 원문 요약·삭제 / HTML·CSS 직접 생성 / layout·zone·region·frame 임의 선택
|
||||
```
|
||||
|
||||
Step 0 (사전 준비) 의 Figma → HTML 변환은 *precondition phase 의 작업* — runtime AI 아님.
|
||||
|
||||
다른 step 에서의 AI 호출은 본 도면 안에 *없음*.
|
||||
|
||||
---
|
||||
|
||||
## 6. 현재 병목 (한 줄)
|
||||
|
||||
> 현재 Phase Z 의 *Layer A pre-render planning* (Step 3 / 4 / 11) 은 본 session 작업으로 ❌ → ⚠ partial 전이 (B1/B2/B4 dormant module + trace-only runtime 호출). *Layer A telemetry 의 first activation* — debug.json 의 placement_trace per-zone + frame_slot_metrics F29 partial 기록. 단 **render path 활성화는 미완** : B4 PlacementPlan 이 mapper output 을 *대체하지 않고* trace-only / region-id / content_unit_id marker 가 partial template 에 *미주입* / B4 frame_selection 이 V4 evidence *미통합*. 핵심 다음 axis = **(B5 후속) render path 의 placement_trace 활용 + region marker runtime activation + V4 통합**. *runtime contract-registered / verified frame set 이 text-frame 중심* 한계는 잔존 (frame inventory audit / refinement 별 axis).
|
||||
|
||||
---
|
||||
|
||||
## 사용 방법
|
||||
|
||||
- 새 작업 들어오면 → 본 board 의 *어느 step* 의 status 를 바꾸는 작업인지 식별
|
||||
- 작업이 *Step 매핑이 안 되면* → over-scoped 또는 새 step 정의 필요 (OVERVIEW 영역)
|
||||
- ✅ → ⚠ → ❌ status 전이 / 갱신 시 → 본 board 만 수정. OVERVIEW 는 step 추가/제거/순서 변경 시에만
|
||||
@@ -1,69 +0,0 @@
|
||||
# Typography Tokens — 초안 v1
|
||||
|
||||
## Global Hierarchy Tokens
|
||||
|
||||
슬라이드 전체의 공통 글자 위계. 모든 블록이 이 기준을 따른다.
|
||||
|
||||
| 위계 | 토큰명 | font-size | font-weight | line-height | 용도 |
|
||||
|------|--------|-----------|-------------|-------------|------|
|
||||
| 대목차 | `--font-slide-title` | 22px | 700 | 1.4 | 슬라이드 상단 제목 |
|
||||
| 중목차 | `--font-zone-title` | 13px | 700 | 1.4 | zone 제목 (## 대목차 하위) |
|
||||
| 소목차 | `--font-sub-title` | 12px | 700 | 1.45 | 블록 내 소제목, 카드 제목 |
|
||||
| 본문 | `--font-body` | 11px | 400~500 | 1.55 | 블릿, 설명 텍스트 |
|
||||
| 캡션 | `--font-caption` | 10px | 400 | 1.4 | 각주, 출처, 보조 텍스트 |
|
||||
| footer | `--font-footer` | 20px | 700 | 1.2 | 핵심 인사이트 pill |
|
||||
|
||||
---
|
||||
|
||||
## Component Semantic Token 후보
|
||||
|
||||
위계 6종으로 안 덮이는 역할. 가까운 위계에서 기본값을 가져오되, 필요시 override.
|
||||
|
||||
| 역할 | 기반 위계 | 예상 override | 비고 |
|
||||
|------|-----------|---------------|------|
|
||||
| body-strong (본문 강조) | 본문 (11px) | weight: 600~700 | 본문 heading, 인라인 강조 |
|
||||
| detail-link (자세히보기) | 캡션 (10px) | weight: 500, color: muted | 링크 텍스트 |
|
||||
| pill-label | 소목차 (12px) | weight: 700, color: white | pill/badge 안 라벨 |
|
||||
| table-header | 소목차 (12px) | weight: 700, color: white, bg: dark | 표 헤더 셀 |
|
||||
| table-cell | 본문 (11px) | - | 표 데이터 셀 |
|
||||
| compare-badge | 소목차 (12px) | weight: 700 | 비교 블록 VS 뱃지 |
|
||||
| callout | 소목차 (12px) | weight: 700, color: accent | 강조 인용 |
|
||||
| overline | 캡션 (10px) | weight: 600, letter-spacing | 상단 라벨 |
|
||||
|
||||
---
|
||||
|
||||
## Source
|
||||
|
||||
현재 코드에서 추출한 실제 사용값 기준.
|
||||
|
||||
| 출처 | 대목차 | 중목차 | 소목차 | 본문 | 캡션 | footer |
|
||||
|------|--------|--------|--------|------|------|--------|
|
||||
| slide-base.html | 22px | - | - | - | - | 20px |
|
||||
| block_assembler.py zone title | - | 13px | - | - | - | - |
|
||||
| block_assembler.py direct render | - | - | 12px | 11px | - | - |
|
||||
| block_assembler.py .bul | - | - | - | 11px | - | - |
|
||||
| FontHierarchy (legacy) | - | - | key_msg 14 | core 12 | sidebar 10 | - |
|
||||
|
||||
---
|
||||
|
||||
## FontHierarchy 매핑 (보조 체계)
|
||||
|
||||
기존 FontHierarchy는 역할 기반이므로, 위계 기반으로 매핑하여 보조로 유지.
|
||||
|
||||
| FontHierarchy | 위계 매핑 | 비고 |
|
||||
|---------------|-----------|------|
|
||||
| key_msg (14px) | 소목차~중목차 사이 | 강조 메시지용, component token 후보 |
|
||||
| core (12px) | 소목차 | 기본 블록 제목급 |
|
||||
| bg (11px) | 본문 | 배경/보조 텍스트 |
|
||||
| sidebar (10px) | 캡션 | 사이드바/첨부 |
|
||||
|
||||
---
|
||||
|
||||
## 상태
|
||||
|
||||
- [x] inventory 수집 완료
|
||||
- [x] global hierarchy v1 초안
|
||||
- [x] component token 후보 분리
|
||||
- [ ] typography.css 파일 작성
|
||||
- [ ] spacing tokens 정의
|
||||
- [ ] color tokens 정의 (공통 + 의미색)
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 936 KiB |
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user