IMPROVEMENT Phase A~D + Phase 2 전체 반영

## IMPROVEMENT (Phase A~D)
- A-1: 4단계 Sonnet 디자인 조정 (_adjust_design) — CSS 변수 cascade
- A-2: 5단계 HTML 전문 프롬프트 전달
- A-3: shrink/expand 하드코딩 제거 → Sonnet target_ratio 기반
- A-4: rewrite action 구현
- A-5: overflow: visible (area 레벨 텍스트 잘림 방지)
- A-6: object-fit cover → contain (이미지 crop 방지)
- A-7: table-layout: fixed
- A-8: container query 폰트 스케일링
- B-1: details-block 템플릿 신규 (CSS 변수만 사용)
- B-2: 인쇄 시 details 자동 펼침 JS
- B-3: catalog에 details-block 등록
- B-4/B-5: images[]/tables[] 상세 판단 + fallback 3곳 동기화
- B-8: fallback card-grid → topic-header + char_guide 제거
- C-1: CLAUDE.md gradient 원칙 완화
- C-3: border-radius 9개 파일 var(--radius) 통일
- C-4: box-shadow 2레벨 → 1레벨
- D-0: 이미지 경로 입력 UI + API base_path
- D-1: Pillow 의존성 + image_utils.py
- D-2~D-4: 이미지 비율/축소방지 프롬프트 전달
- D-5: HTML에 이미지 base64 삽입

## Phase 2 (다른 Claude 작업)
- P2-A: FAISS 블록 검색 (bge-m3, 46개 블록)
- P2-B: SVG N개 자동 배치 (svg_calculator.py)
- P2-C: Opus 블록 추천 (Kei API 경유)
- P2-D: 5단계 재검토 루프 강화 (MAX_REVIEW_ROUNDS=2)
- P2-E: details-block fallback 연동

## 버그 수정 (BF-8~10)
- BF-8: 컨테이너 예산 기반 블록 배치
- BF-9: grid와 Sonnet 역할 분리
- BF-10: catalog mtime 캐시 자동 갱신

## 블록 라이브러리
- 46개 블록 (6 카테고리), catalog/BLOCK_SLOTS/INDEX 동기화
- 구 블록 제거 (quote-block, card-grid, comparison)
- 13개 _legacy 블록 보존

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -217,59 +217,18 @@ reference 꼭지 있음 → sidebar-right
 
 ## 블록 타입 정의
 
-각 블록은 독립적인 CSS 컴포넌트로, 슬롯(교체 가능한 위치)을 가진다.
+6개 카테고리, 18개 블록 변형. **상세는 `templates/blocks/INDEX.md` 참조.**
 
-### 1. 비교 블록 (comparison)
-- 2단 병렬 레이아웃
-- 슬롯: 좌측 제목/내용, 우측 제목/내용
-- 용도: A vs B, 장단점, Before/After
+| 카테고리 | 블록 수 | 구현 방식 | 주요 블록 |
+|---------|--------|---------|---------|
+| headers/ | 2 | HTML/CSS | section-title-with-bg, topic-left-right |
+| cards/ | 3 | HTML/CSS | card-image-3col, card-text-grid, card-dark-overlay |
+| tables/ | 1 | HTML/CSS | compare-3col-badge |
+| visuals/ | 4 | **SVG** (수학적 좌표 계산) | venn-diagram, circle-gradient, compare-pill-pair, process-horizontal |
+| emphasis/ | 5 | HTML/CSS | quote-left-border, conclusion-accent-bar, comparison-2col, banner-gradient, quote-question |
+| media/ | 3 | HTML/CSS + 이미지 | image-row-2col, image-grid-2x2, image-side-text |
 
-### 2. 카드 그리드 (card-grid)
-- 2~4열 카드 배열
-- 슬롯: 카드별 아이콘/제목/설명/출처
-- 용도: 용어 정의, 개념 설명, 기능 나열
-
-### 3. 관계도 (relationship)
-- 벤 다이어그램 또는 트리 구조
-- 슬롯: 중심 요소, 하위 요소들, 관계 설명
-- 용도: 상위-하위 관계, 포함 관계, 기술 융합
-
-### 4. 프로세스 (process)
-- 가로 또는 세로 단계 흐름
-- 슬롯: 단계별 번호/제목/설명
-- 용도: 절차, 워크플로우, 파이프라인
-
-### 5. 타임라인 (timeline)
-- 시간 축 기반 배치
-- 슬롯: 날짜/제목/설명
-- 용도: 연혁, 로드맵, 일정
-
-### 6. 핵심 지표 (big-number)
-- 큰 숫자 + 보조 텍스트
-- 슬롯: 숫자, 단위, 설명
-- 용도: KPI, 통계, 성과 수치
-
-### 7. 강조 인용 (quote-block)
-- 배경색 + 좌측 라인 + 인용 텍스트
-- 슬롯: 인용 텍스트, 출처
-- 용도: 문제 제기, 핵심 메시지, 정의
-
-### 8. 결론 바 (conclusion-bar)
-- 하단 전체 폭 강조 영역
-- 슬롯: 핵심 한 줄
-- 용도: 슬라이드 결론, 요약 메시지
-
-### 9. 비교 테이블 (comparison-table)
-- 테이블 형식의 다항목 비교
-- 슬롯: 행/열 헤더, 셀 내용
-- 용도: 다차원 비교, 기능 매트릭스
-
-### 10. 이미지 블록 (image-block)
-- 이미지 + 캡션
-- 3가지 변형: 전체너비(image-full), 텍스트옆(image-side), 썸네일(image-thumb)
-- 슬롯: 이미지 경로, 캡션 텍스트, 이미지 크기 정보
-- 용도: 도표, 다이어그램, 근거 자료, 문서 참조
-- CSS: object-fit: contain (비율 유지, 잘리지 않음)
+각 블록은 독립적인 컴포넌트로 슬롯(교체 가능한 위치)을 가지며, `catalog.yaml`에 when/not_for/slots가 정의되어 있다.
 
 ---
 
@@ -365,10 +324,10 @@ Pretendard 폰트 크기별 참고값 (1회 측정, 상수 저장):
 - 정보 계층을 시각적으로 명확히 표현
 
 ### DON'T (하지 않는 것)
-- 그라데이션 배경 금지
+- HTML/CSS 블록의 배경 그라데이션 금지 (**SVG 시각화 블록, 디자인 의도가 명확한 블록(배너, 오버레이, 콜아웃 등)은 허용**)
 - CSS 애니메이션/트랜지션 금지
 - 호버 효과 금지
-- 그림자(box-shadow) 최소화 (1개 레벨만)
+- 그림자(box-shadow) 최소화 (1개 레벨만. SVG filter는 예외)
 - 다크 테마 금지 (요청하지 않는 한)
 - 둥근 모서리 과다 사용 금지 (border-radius 최대 8px)
 - 텍스트를 자르지 않는다 (디자인이 텍스트에 맞춘다)
@@ -425,24 +384,93 @@ Pretendard 폰트 크기별 참고값 (1회 측정, 상수 저장):
 
 ---
 
-## 교본 (레퍼런스) 관리
+## 블록 라이브러리
+
+### 핵심 원칙: 변형 기반 선택
+하나의 블록 유형에 **여러 변형(variation)**이 존재하고, 디자인 팀장이 콘텐츠 성격에 맞는 변형을 **검색하여 선택**한다.
+
+```
+콘텐츠 분석 → "이 꼭지는 좌:질문 우:설명 구조다"
+    ↓
+블록 라이브러리 검색 → headers/ 카테고리에서 후보 3~4개 반환
+    ↓
+팀장이 선택 → topic-left-right.html
+```
+
+### 카테고리 구조 (6개, 18개 블록)
+
+```
+templates/blocks/
+├── INDEX.md                           ← 전체 인덱스 + 추가 예정 목록
+├── headers/ (2개)                     ← 타이틀, 꼭지 헤더
+│   ├── section-title-with-bg.html        배경 이미지 + 영문/한글 타이틀
+│   └── topic-left-right.html             좌:파란 제목 + 우:설명
+├── cards/ (3개)                       ← 카드 계열 (정보 나열)
+│   ├── card-image-3col.html              상단 이미지 + 하단 텍스트 3열
+│   ├── card-text-grid.html               텍스트만 카드 2~4열
+│   └── card-dark-overlay.html            다크 이미지 배경 + 흰 텍스트 오버레이
+├── tables/ (1개)                      ← 표/비교 계열
+│   └── compare-3col-badge.html           A|VS배지|B 3단 비교
+├── visuals/ (4개)                     ← 시각 요소 — **SVG로 제작**
+│   ├── circle-gradient.html              파란 그라데이션 원 + 텍스트
+│   ├── compare-pill-pair.html            둥근 테두리 박스 2개 + VS
+│   ├── venn-diagram.html                 벤 다이어그램 (**SVG premium, 수학적 계산**)
+│   └── process-horizontal.html           가로 단계 흐름
+├── emphasis/ (5개)                    ← 강조 (인용, 결론)
+│   ├── quote-left-border.html            좌측 라인 + 인용
+│   ├── conclusion-accent-bar.html        좌측 파란 라인 + 밝은 배경 결론
+│   ├── comparison-2col.html              2단 병렬 비교
+│   ├── banner-gradient.html              파란 그라데이션 전체 너비 배너
+│   └── quote-question.html               질문형 강조 박스
+└── media/ (3개)                       ← 이미지/미디어
+    ├── image-row-2col.html               이미지 2장 나란히
+    ├── image-grid-2x2.html               이미지 4장 2x2 격자
+    └── image-side-text.html              좌:이미지 우:텍스트+불릿
+```
+
+### 시각화 방식 (Phase 1 확정)
+
+**블록 유형별 구현 방식:**
+
+| 블록 유형 | 구현 방식 | 이유 |
+|----------|---------|------|
+| 텍스트 블록 (카드, 비교, 표, 인용, 결론) | **HTML/CSS** | Jinja2 템플릿으로 조립 |
+| 시각화 다이어그램 (관계도, 프로세스, 순환도) | **SVG** | 좌표 정확 + 그라데이션/글로우 가능 + 개수 자동 대응 |
+| 실사 이미지 (시공 사진, 3D 렌더링) | **Figma export 또는 원본 이미지** | CSS/SVG로 재현 불가 |
+| 배경 텍스처 (보케, 분위기) | **Gemini API 이미지 생성** | 실사 배경 전용 |
+
+**SVG 시각화 원칙 (검증 완료):**
+- SVG 안에 `<text>` 포함 → 원 좌표와 텍스트 좌표가 같은 공간 → **위치 100% 정확**
+- `radialGradient`, `linearGradient` → 고급 그라데이션
+- `filter: feGaussianBlur`, `feDropShadow` → 글로우/그림자
+- 하이라이트 오버레이 → 구체(3D) 느낌
+- 수학적 계산 (`cos/sin`) → N개 원소 자동 배치 (`360/N` 간격) — **Phase 2 구현 예정. 현재는 3개 고정 SVG**
+
+**AI 이미지 생성은 시각화에 사용하지 않는다:**
+- AI 생성 이미지는 원 위치가 매번 달라 텍스트 위치를 맞출 수 없음 (검증 완료)
+- AI 이미지는 **실사 배경 텍스처** (보케, 헥사곤, 분위기)에만 사용
+
+### 변형 검색 (향후)
+변형이 수십~수백 개로 늘어나면:
+1. 각 블록 HTML의 구조/슬롯/용도를 임베딩
+2. FAISS 인덱스로 구축
+3. 콘텐츠 분석 결과를 쿼리 → 적절한 변형 3~4개 반환
+4. 팀장이 최종 선택
+
+현재 규모(13개)에서는 catalog.yaml만으로 충분. 40개 이상부터 FAISS 도입 검토.
 
 ### catalog.yaml
 - 디자인 팀장의 "메뉴판"
 - 각 블록의 id, 시각 설명, 언제 쓰는지(when), 슬롯 목록
 - Figma에서 디자인 추출 → 템플릿 변환 → catalog에 등록
-- **Figma 작업 완료 후 연동 예정**
+- 블록 추가 시 반드시 catalog에도 등록 (미등록 = 팀장이 모름)
 
-### 저장 위치
-```
-design_agent/
-├── templates/
-│   ├── catalog.yaml          ← AI용 블록 메뉴판 (Figma 작업 후)
-│   ├── slide-base.html       ← 슬라이드 베이스
-│   └── blocks/               ← 블록 템플릿
-├── samples/                  ← 완성 슬라이드 샘플
-└── docs/                     ← 조사 자료
-```
+### Figma 에셋
+Figma에서 추출한 이미지 에셋은 `docs/figma-assets/`에 저장:
+- 배경 이미지 (bg_header.png 등)
+- 3D 렌더링 이미지 (card_img_design.png 등)
+- 시각화 에셋 (mountain_viz.png 등)
+- 블록에서 `src="{{ image_path }}"`로 참조
 
 ---
 
@@ -451,13 +479,17 @@ design_agent/
 | 역할 | 도구 | 비고 |
 |------|------|------|
 | 서버 | FastAPI + uvicorn | 포트 8001 |
-| 템플릿 | Jinja2 | 블록 조합 |
-| 렌더링 | CSS Grid + 디자인 토큰 | 16:9 고정 |
+| 템플릿 | Jinja2 | 카테고리별 블록 조합 |
+| 렌더링 | CSS Grid + 디자인 토큰 | 슬라이드(16:9) + 웹(세로 스크롤) |
 | 폰트 | Pretendard Variable | word-break: keep-all |
 | AI | Anthropic API (Sonnet) | 5단계 모두 |
 | 이미지 크기 | Pillow Image.open().size | 헤더만 읽음 |
+| 시각화 | SVG (radialGradient, filter, 수학적 좌표 계산) | 다이어그램/관계도 |
+| 실사 배경 | Gemini API | 배경 텍스처 전용 (시각화에는 사용 금지) |
 | 자세히보기 | `<details>/<summary>` | HTML 내장 |
-| 출력 | HTML 다운로드 | |
+| Figma 연동 | Figma REST API + Framelink MCP | 에셋 추출, 디자인 토큰 |
+| 변형 검색 | FAISS (향후) | 블록 40개+ 시 도입 |
+| 출력 | HTML 다운로드 / .astro (Starlight) | |
 
 ---