# Phase Z Catalog / Runtime Design

> **본 문서는 Phase Z-1 사전 작업의 마지막 설계 산출물이며, Phase Z-2 본격 구현 (catalog / runtime / matching 통합) 의 입력 문서다.**
>
> ⚠️ 본 문서는 **1 차 — skeleton + 책임 영역 정의**. 각 영역은 "무엇을 결정하는가 / 무엇을 결정하지 않는가" 까지만. 세부 설계는 단계적 추가.
> ⚠️ 본 문서 = **설계 책임 정리**. 코드 / 파일 변경 / 기존 자산 삭제 X.

---

## 1. 문서 위치 / 목적

본 문서는 design_agent 의 Phase Z 흐름에서 **catalog (frame ↔ Zone 매핑) + runtime (Jinja2 template + AI 경계) 의 책임 분리** 를 정의한다.

**위치 (Phase Z-1 사전 작업 산출물 흐름)** :

1. [`FRAME-INTEGRATION-MAP.md`](FRAME-INTEGRATION-MAP.md) — 32 frame Zone 적용 분류
2. [`PHASE-Z-FRAME-STYLE-INVENTORY.md`](PHASE-Z-FRAME-STYLE-INVENTORY.md) — 32 frame + 18 token + 6 legacy
3. **본 문서** — 위 두 인벤토리 + IMPROVEMENT-REDESIGN.md 5 단계 흐름 → catalog / runtime 책임 정리

→ Phase Z-2 본격 구현의 *입력 문서*. 본 문서는 코드 / 파일 변경을 *지시하지 않음*.

**목적** :

- frame inventory + style inventory 가 catalog 어디에서 책임지는지 정의
- AI 가 *건드리지 않는* 영역 명시 (Phase R' 회귀 방지)
- 코드 구현 시 어떤 책임이 어디 살아야 하는지 사전 합의

---

## 2. 입력 문서

| 문서 | 본 설계가 받는 입력 |
|---|---|
| [`IMPROVEMENT-REDESIGN.md`](../../IMPROVEMENT-REDESIGN.md) | Phase Z 5 단계 흐름, 위계 + 용어, 절대 룰 (텍스트 무손실 / MDX 1 = 슬라이드 1 / 자유 디자인 금지 / 불일치 시 레이아웃 회귀) |
| [`FRAME-INTEGRATION-MAP.md`](FRAME-INTEGRATION-MAP.md) | 32 frame Zone 적용 분류 (`zone_direct` / `zone_adapt` / `zone_extract` / `reference_only`), 검토 상태, 분포 |
| [`PHASE-Z-FRAME-STYLE-INVENTORY.md`](PHASE-Z-FRAME-STYLE-INVENTORY.md) | Frame Inventory 32 행 (변환 14 + 미변환 18) + Token Inventory 18 행 (covered / gap_candidate / hierarchy_mapping_only / hold_recheck_after_conversion) + Legacy Reference 6 행 |

---

## 3. 핵심 원칙 (Phase Z 준수)

| 원칙 | 의미 |
|---|---|
| **final unit = Zone** | 슬라이드의 최종 조립 단위는 Zone. frame 은 절대 슬라이드에 직접 안 꽂힘 |
| **frame = reference / pattern / slot hint** | frame 은 디자인 레퍼런스 / 구조 패턴 / 슬롯 힌트만. 원본 그대로 사용 X |
| **AI = zone content only** | AI 호출은 zone 안 콘텐츠 매핑 / 텍스트 다듬기 / 디자인 변형 단위로만 |
| **HTML / Jinja2 = code only** | HTML 구조 / 레이아웃 / 프리셋 결정 / 새 frame 결정은 코드만 (AI 호출 X) |
| **legacy blocks runtime reuse X** | 기존 `templates/blocks/structures/` 6 파일은 runtime 재사용 후보 X. 스타일 / 토큰 매핑 참고만 |

---

## 4. 책임 영역 (8 영역)

각 영역의 **무엇을 결정하는가 / 무엇을 결정하지 않는가** 만 본 1 차에서 정의. 세부 설계는 다음 차수.

### 4.1 Zone Catalog

**결정함** :
- frame ↔ Zone 매핑 룰 (어느 frame 이 어느 Zone 에 들어갈 수 있는가)
- 레이아웃 프리셋 (Type A / B / B' / B'') 별 Zone 구성
- 매칭 분기 (완벽 / 어정쩡 / 안 됨) 의 Zone 단위 의사결정
- `zone_application` (`zone_direct/adapt/extract/reference_only`) 의 catalog 안 표현

**결정 안 함** :
- 실제 frame 의 시각 스타일 (→ 4.2 Family CSS)
- HTML 구조 (→ 4.3 Jinja2 Runtime Templates)
- AI 호출 시점 / 입력 (→ 4.4 AI Boundary)

### 4.2 Family CSS

**결정함** :
- frame family 별 시각 / 스타일 규칙 정의
   - 후보 family (Frame Inventory 의 Phase Z Target 컬럼 기반) : `compare-paired.css` / `compare-table.css` / `pill-list.css` / `three-pillar.css` / `persona-cards.css` / `quadrant.css` / `split-panel.css` / `split-center.css` 등
- variant 분기 (예 : `compare-paired.css` 의 `paired-rows` vs `vs-center-badge`)
- token (color / gradient) 사용 + 신규 token 후보 흡수 / 기각

**결정 안 함** :
- HTML 마크업 자체 (→ 4.3)
- frame ↔ Zone 매핑 (→ 4.1)
- 텍스트 콘텐츠 (→ 4.4)

### 4.3 Jinja2 Runtime Templates

**결정함** :
- HTML 구조 (slide-base + body + zone slot + frame slot 의 마크업 골격)
- 슬롯 의미 매핑 (frame slot ↔ MDX 콘텐츠)
- 검증 (overflow / 시각 품질) hook 위치
- 본문 preview ↔ 팝업 원문 분리 위치 (텍스트 무손실 보존)

**결정 안 함** :
- 시각 스타일 (→ 4.2)
- frame 선택 (→ 4.1)
- AI 호출 (→ 4.4)

### 4.4 AI Boundary

**결정함** :
- AI 호출 **허용** 범위 — zone 안 콘텐츠 매핑 / 텍스트 다듬기 / 슬롯 의미 미세 조정
- AI 호출 **금지** 범위 — HTML 구조 / 레이아웃 / 프리셋 결정 / 새 frame 결정 (Phase R' 회귀 방지)
- AI 입력 / 출력 형식 (zone 단위 컨텍스트만, 슬라이드 전체 X)

**결정 안 함** :
- AI 모델 / 프롬프트 자체 (구현 단계)
- AI 호출 횟수 / 캐싱 (구현 단계)

### 4.5 Token Resolution

**결정함** :
- frame raw px (figma 1280 폭 기준) ↔ slide-body 스케일 (1200×590) 매핑 룰
- `hierarchy_mapping_only` 행 (Token Inventory) 이 catalog 어디에서 적용되는가
- 신규 token (`gap_candidate`) 채택 / 기각 의사결정 위치
- `hold_recheck_after_conversion` token 의 재검증 시점

**결정 안 함** :
- token 값 자체 (→ Style Inventory 영역)
- token 파일 생성 / 변경 (구현 단계, 사용자 승인 후)

### 4.6 Asset Policy

**결정함** :
- 자산 의존도 큰 frame (F01 9 자산 / F07 16 자산 / F14 사진 / F22 15 자산 등) 의 처리 정책
- placeholder / 사용자 제공 / SVG 변환 / 이미지 유지 분기 룰
- `reference_only` frame (F06) 의 자산 정책 (직접 적용 X)

**결정 안 함** :
- 실제 자산 파일 / 경로 (구현 단계)
- placeholder 의 시각 디자인 (구현 단계)

### 4.7 Variant Model

**결정함** :
- family 안 variant 의 표현 방식 후보 (CSS class modifier / data attribute / template parameter 등)
- variant ↔ frame 매핑 룰 (`compare-paired.css` 의 `paired-rows` ↔ Frame 17 / `vs-center-badge` ↔ Frame 18 등)
- variant 충돌 시 의사결정 (예 : 같은 zone 에 두 variant 가능 시)

**결정 안 함** :
- 구체 CSS 구현 (→ 4.2)
- variant 추가 / 폐기 (구현 단계)

### 4.8 Fallback Behavior

**결정함** :
- 5 차 Fallback (코드 → AI 콘텐츠 조정 → 단일 프리셋 강제) 의 catalog 단위 책임
- 매칭 실패 시 zone 단위 동작
- AI 콘텐츠 조정 (4 차) 의 입력 / 출력 경계 (frame / zone / container 유지, 콘텐츠만 조정)
- 레이아웃 회귀 (불일치 시 그릇 변경) 의 catalog 단위 트리거

**결정 안 함** :
- AI 호출 자체 (→ 4.4)
- HTML 재구성 (→ 4.3)

---

## 5. 비범위

본 문서는 **설계 책임 정의** 만. 다음은 본 문서 비범위 :

- ❌ 코드 구현 (Phase Z-2 이후)
- ❌ 기존 `templates/blocks/` 삭제 (사용자 승인 후 별도 단계)
- ❌ `templates/styles/frame-patterns/` 신규 파일 생성 (사용자 승인 후)
- ❌ `templates/styles/tokens/` 의 `gap_candidate` token 추가 (사용자 승인 후)
- ❌ legacy structures 6 파일 삭제 (사용자 승인 후)
- ❌ AI 모델 / 프롬프트 / 호출 횟수 결정
- ❌ Style Inventory 의 추가 항목 작성 (별도 작업)

---

## 6. 단계적 작성 계획

| 차수 | 작성 내용 | 상태 |
|---|---|---|
| 1 차 | skeleton + 책임 영역 정의 | ✅ |
| 2 차 | Zone Catalog 본격 — frame ↔ Zone 매핑 / 프리셋 / 매칭 분기 (본 문서 § 7) | ✅ |
| 3 차 | Family CSS 본격 — Area 후보 / variant 참조 / token 참조 / asset 표시 (본 문서 § 8) | ✅ |
| 4 차 | Jinja2 Runtime Templates 본격 — 입력 계약 / 조립 위계 / status 인터페이스 / AI 진입 (본 문서 § 9) | ✅ |
| 5a 차 | AI Boundary 본격 — 호출 단위 / 허용 입출력 / 금지 출력 (본 문서 § 10) | ✅ |
| 5b 차 | Token Resolution 본격 — 4 status 처리 룰 / scale 위계 매핑 / 보류 원칙 (본 문서 § 11) | ✅ |
| 5c 차 | Asset Policy 본격 — 의존도 / 자산 유형 / 5 상태 라벨 / asset_meta (본 문서 § 12) | ✅ |
| 5d 차 | Variant Model 본격 — 표현 방식 선택 / family 별 variant 관리 / 추가-분리-폐기 기준 (본 문서 § 13) | ✅ |
| 5e 차 | Fallback Behavior 본격 — status 진입 후 동작 / 5 차 Fallback / AI 경계 / 레이아웃 회귀 (본 문서 § 14) | ✅ |
| 6 차 | 통합 검증 + Phase Z-2 구현 진입 결정 (본 문서 § 15) | ✅ 검증 완료, 구현 착수 별도 승인 |

각 차수마다 user 검토 후 다음 진입. **6 차 완료 = 현재 위치** (1~5e 본격 설계 + 통합 검증 모두 완료). Phase Z-2 구현 착수는 *별도 사용자 승인* 후.

---

## 7. Zone Catalog — 2 차 본격 설계

> ⚠️ 본 섹션은 **Zone Catalog 책임 영역만** 다룬다. Family CSS / Jinja2 / Fallback 실제 동작 / AI 호출 등 다른 영역 침범 X.
> ⚠️ Frame Inventory / FRAME-INTEGRATION-MAP.md 의 표 / 통계는 다시 베끼지 않음 — 링크 참조 + catalog 안에서 어떻게 *소비* 되는지만.

### 7.1 Zone Catalog 의 역할

Zone Catalog 는 다음을 책임진다 :

1. **레이아웃 프리셋 ↔ MDX 콘텐츠** 결정 — Type A / B / B' / B'' 중 어느 프리셋이 본 MDX 에 적합한가
2. **Zone 슬롯 ↔ frame** 매핑 — 각 Zone 에 어느 frame 후보가 들어갈 수 있나
3. **catalog status 라벨 부여** — `zone_application × confidence` 매트릭스 결과 (§ 7.4)

받는 입력 :
- `FRAME-INTEGRATION-MAP.md` — 32 frame 의 `zone_application` 라벨
- 매칭 시스템 (V1~V4, `tests/matching/`) — frame ↔ MDX confidence 점수

출력 :
- 본 MDX 에 대한 *Zone 별 catalog status 라벨*
- 후속 영역 (Family CSS / Fallback / AI) 으로 전달되는 신호

→ **Zone Catalog 는 라벨 부여까지만**. 라벨 후 실제 적용은 Family CSS / Fallback Behavior / AI Boundary 영역.

### 7.2 레이아웃 프리셋 + Zone 타입

Phase Z 위계의 두 레벨을 분리해서 정의한다.

#### 7.2-1 레이아웃 프리셋 후보

slide-body (≈ 1200×590) 를 어떻게 나누는가. 프리셋 4 종 (IMPROVEMENT-REDESIGN.md 참조) :

| Preset | 분배 형태 | 적합한 콘텐츠 신호 |
|---|---|---|
| `Type A` | sidebar-right (`title / body / sidebar`) | reference 꼭지 1+ |
| `Type B` | top + bottom (단일 강조 + 보조) | hero-detail 류 |
| `Type B'` | two-column (좌·우 대등) | 비교 류 |
| `Type B''` | three-section (3 영역 분할) | 3 카테고리 / 3 단계 |

→ **catalog 가 결정** — MDX 콘텐츠 신호 ↔ 프리셋 선택. 결정 룰의 구체화는 추가 차수.

→ **결정 안 함** — 프리셋 안의 시각 디자인 (Family CSS), 프리셋 내부 HTML 구조 (Jinja2).

#### 7.2-2 Zone 타입 후보

각 프리셋이 만들어낸 *슬롯의 역할* 후보. 슬롯 위치 ↔ 콘텐츠 role.

| Zone slot 위치 (예) | 받을 수 있는 콘텐츠 role 후보 |
|---|---|
| `top` | summary / overview / key-insight / table-header |
| `bottom_l` / `bottom_r` | detail / compare-side / supporting |
| `sidebar` | reference / quote / supporting-list |
| `body` (single) | full-pattern / hero-detail / compare-rows |

→ **catalog 가 결정** — 어느 Zone 슬롯이 어느 콘텐츠 role 을 받을지.

→ **결정 안 함** — 슬롯 안 시각 디자인, 슬롯 안 frame 의 stylization.

### 7.3 frame zone_application 과 catalog 의 관계

`FRAME-INTEGRATION-MAP.md` 의 4 라벨 (`zone_direct / zone_adapt / zone_extract / reference_only`) 을 catalog 가 어떻게 *소비* 하는가 :

| zone_application | catalog 의 소비 방식 |
|---|---|
| `zone_direct` | frame 구조 그대로 zone 슬롯에 매핑. catalog 는 슬롯 사이즈만 통과 |
| `zone_adapt` | frame 구조 동일, 사이즈 / 비율 재조정 hint 와 함께 후속 영역 (Family CSS) 에 전달 |
| `zone_extract` | frame 의 일부 패턴만 (예 : 3-column 만 추출) hint 와 함께 후속 영역에 전달 |
| `reference_only` | runtime 적용 X — `not_runtime_candidate` 라벨링. 디자인 톤 참고만 |

→ 4 라벨의 *분류 자체* 는 FRAME-INTEGRATION-MAP.md 가 결정. catalog 는 *소비 방식* 만 책임.

### 7.4 catalog status 라벨 — `zone_application × confidence` 매트릭스

본 catalog 의 *핵심 출력*. 두 축은 **직교** :

- `zone_application` = frame 자체의 Zone 적용 방식 (frame 의 *고유 속성*)
- `confidence` = 특정 MDX 콘텐츠 ↔ frame 매칭 품질 (콘텐츠 ↔ frame *상호작용*)

매트릭스 (4 × 3 = 12 셀, 6 라벨) :

| | `high` | `medium` | `low` |
|---|---|---|---|
| `zone_direct` | `matched_zone` | `review_required` | `fallback_candidate` |
| `zone_adapt` | `adapt_matched_zone` | `review_required` | `fallback_candidate` |
| `zone_extract` | `extract_matched_zone` | `review_required` | `fallback_candidate` |
| `reference_only` | `not_runtime_candidate` | `not_runtime_candidate` | `not_runtime_candidate` |

> **원칙 — `medium` confidence 는 자동 확정하지 않는다.**
>
> Zone 적용 방식이 `zone_direct`, `zone_adapt`, `zone_extract` 중 무엇이든,
> confidence 가 `medium` 이면 `review_required` 로 보낸다.

이유 : Phase Z 절대 룰 *"불일치 시 레이아웃 회귀 — 콘텐츠 줄이지 않고 그릇 변경"* 과 정합. 자동화가 과감해지는 것 방지.

각 라벨의 의미 :

| 라벨 | 의미 |
|---|---|
| `matched_zone` | `zone_direct` × `high`. 즉시 적용 후보 |
| `adapt_matched_zone` | `zone_adapt` × `high`. 사이즈 재조정 적용 후보 |
| `extract_matched_zone` | `zone_extract` × `high`. 일부 패턴 추출 적용 후보 |
| `review_required` | 모든 `medium`. 사람 / 후속 단계 검토 필요 |
| `fallback_candidate` | `zone_direct/adapt/extract` × `low`. fallback 진입 |
| `not_runtime_candidate` | `reference_only` × any. 디자인 톤 참고만 |

> `fallback_candidate` 는 fallback 동작을 실행한다는 뜻이 아니라, Fallback Behavior 설계로 넘길 **후보 상태** 를 의미한다.

→ **catalog 는 라벨 부여까지만**. 라벨 후의 실제 동작은 Fallback Behavior / AI Boundary / Family CSS 영역.

### 7.5 Zone Catalog 가 결정하지 않는 것

Skeleton § 4.1 의 "결정 안 함" 확장 + 본 2 차에서 추가 명확화 :

- ❌ frame 의 시각 / 스타일 (→ Family CSS, 미작성)
- ❌ HTML 구조 / 슬롯 마크업 (→ Jinja2 Runtime Templates, 미작성)
- ❌ AI 호출 시점 / 입력 형식 (→ AI Boundary, 미작성)
- ❌ `fallback_candidate` 진입 후 실제 동작 (→ Fallback Behavior, 미작성)
- ❌ `review_required` 진입 후 처리 흐름 (→ AI Boundary 또는 Fallback Behavior, 미작성)
- ❌ `not_runtime_candidate` frame 의 디자인 톤 적용 방식 (→ Asset Policy 또는 Style Inventory)
- ❌ variant 표현 방식 (→ Variant Model, 미작성)
- ❌ token 선택 / 적용 (→ Token Resolution, 미작성)
- ❌ confidence 임계값 자체 (예 : 몇 % 이상이 `high` 인가) — 매칭 시스템 (V1~V4) 의 책임. catalog 는 라벨화된 confidence 만 받음

---

### 7 차수 자체 점검 (작성 후)

- ✅ Zone Catalog 영역만 다룸 (Family CSS / Jinja2 / Fallback 실제 동작 / AI 호출 침범 X)
- ✅ Frame Inventory 32 행 표 redescription 0 — 링크 참조만
- ✅ FRAME-INTEGRATION-MAP.md 분포 통계 redescription 0
- ✅ 직교 축 (`zone_application` ⊥ `confidence`) 명시
- ✅ "medium 자동 확정 X" 원칙 prominent callout
- ✅ Skeleton § 4.1 의 "결정 안 함" 8 항목 § 7.5 에서 확장
- ✅ catalog 가 *결정함* 까지만, 결정 후 동작은 후속 영역 명시

---

## 8. Family CSS — 3 차 본격 설계

> ⚠️ **룰 1** — 본 섹션은 **Family CSS 관점에서 variant / token / asset 을 어떻게 *참조* 하는지만** 다룬다. Variant Model 자체, Token Resolution 자체, Asset Policy 자체는 후속 dedicated 영역 (§ 4.5 / 4.6 / 4.7) 에서 결정.
>
> ⚠️ **룰 2** — Family CSS 는 *frame 별 CSS 가 아니라* **family 단위 CSS** 다. frame 차이는 variant / meta 로 표현한다.

### 8.1 Family CSS 의 역할

Family CSS 는 다음을 책임진다 :

1. **family 단위 시각 / 스타일 규칙** 정의 — 같은 family 안 frame 들의 공통 패턴
2. **variant 슬롯 노출** — frame 차이를 family 안 variant 로 받아낼 수 있는 hook
3. **token / asset 참조 인터페이스** — Token Inventory / Asset Policy 의 *소비자*

받는 입력 :
- Frame Inventory 의 `Phase Z Target` 컬럼 (family 후보)
- Token Inventory 의 4 status (covered / gap_candidate / hierarchy_mapping_only / hold)
- Frame Inventory 의 `Asset Notes` (자산 의존도)
- Zone Catalog (§ 7) 의 status 라벨 (matched_zone / adapt_matched_zone / extract_matched_zone — Family CSS 적용 후보 신호)

→ **Family CSS 는 family 단위 패턴 정의까지만**. variant 모델 자체 / token 채택 / asset 정책은 후속 영역.

### 8.2 Family CSS Area 후보 (11)

본 섹션의 **centerpiece**. Frame Inventory 의 `Phase Z Target` 컬럼을 family 단위로 수렴한 결과.

| Family CSS Area 후보 | 흡수 frame | 변형 축 (variant 후보) | asset 의존도 | Notes |
|---|---|---|---|---|
| `compare-paired.css` (후보) | F17, F18 | `paired-rows` (F17) / `vs-center-badge` (F18) | mid | F17 R16 두루마리 pill 이미지 의존. F18 의 center badge 컬럼이 variant 키 |
| `compare-table.css` (후보) | F23, F24 (+ F30, F31 미변환 통합 후보) | `columns[N=2~4]` / `header_style` / `row_density` | low | line 은 CSS border 변환 가능. 30/31 변환 후 variant range 확정 |
| `split-panel.css` (후보) | F21, F22 | `right_items[N=3~8]` / `left_categories[N=2~5]` / `bracket_image` (optional) | high | 14~15 자산 (배경 / 뱃지 / 화살표 / 행 바). Phase Z 재현 시 자산 풀 필수 |
| `persona-cards.css` (후보) | F14 | `actor_count[3]` / `actor_hue_palette` / `photo_required` | high | 사진 ×3 필수 (placeholder / 사용자 자산), badge outer/inner ×6, 체크박스 ×20 |
| `three-pillar.css` (후보) | F13 | `pillars[3]` (현재 고정) / `column_hue_palette` | low | 아이콘 PNG 1, 테두리 SVG 4 → CSS 변환 가능 |
| `quadrant.css` (후보) | F16 | `quadrants[4]` (고정) / `bar_style` / `center_quote` (optional) | mid | 배경 텍스처 PNG ×4 동일, bar SVG → CSS gradient 변환 가능 |
| `pill-list.css` (후보) | F09 | `items[N=3~7]` / `stacking_pattern` / `arc_decoration` (optional) | low | 아크 SVG / 화살표 SVG 만 이미지 유지. pill 본체 CSS |
| `cycle.css` (후보) + svg helpers (helper area 후보) | F12 | `main_circles[3]` (현재 고정) / `accent_circles[6]` | mid | 19 SVG (Ellipse) — 좌표 기반 SVG 재구성 가능. bg_texture PNG 1 |
| `split-center.css` (후보) | F27 | (sparse data — 추가 관찰 후 확정) | mid | flat.md sparse. variant range 후속 차수에서 |
| `system-diagram.css` (후보) | F07 | (sparse data — 추가 관찰 후 확정) | very high | 16 자산. 자산 풀 필수 |
| (asset-heavy / reference-like family 후보) | F01 | (variant 미정 — pure CSS family 아님) | very high | 9 자산 모두 이미지. CSS 패턴이라기보다 *asset slot 컴포넌트*. family 분류 자체 검토 후보 |

**주의** :
- Family CSS Area 후보 = 결정 X. 실제 파일 생성 / 이름은 사용자 승인 후.
- 11 개 → 최종 family 수는 더 줄 수 있음 (특히 sparse data F07 / F27 / F01 은 추가 검증 후 통합 / 분리 결정).
- F01 은 *pure CSS family 아님* — 별도 분류 필요할 수 있음 (asset-heavy / reference-like family).

→ FRAME-INTEGRATION-MAP.md 의 frame 별 분류는 redescribe 안 함. 본 표는 **family 수렴 결과** 만.

### 8.3 variant 참조 방식

Family CSS 는 frame 차이를 variant 로 받아낸다. variant 의 **표현 방식 후보** :

| 후보 방식 | 예시 | 적합한 케이스 |
|---|---|---|
| **CSS class modifier** | `.compare-paired.--vs-center-badge` | 시각 / 구조가 크게 다른 variant (F17 vs F18 의 pill alternation vs center badge) |
| **Data attribute** | `[data-variant="paired-rows"]` | 마크업은 같고 styling 만 분기 |
| **Template parameter** | Jinja2 `{{ variant }}` 변수 + family CSS 의 조건부 selector | 슬롯 수 / cardinality 차이 (예 : `columns[N=2~4]`) |
| **Variant family 자체 분기** | `compare-table--2col.css` / `compare-table--3col.css` (별도 entry) | columns 차이가 너무 클 때 (현재 시점에서는 over-split, 비추천) |

**Family CSS 가 결정함** : variant 별로 *어느 표현 방식* 을 채택하는가 (참조 인터페이스만)

**Family CSS 가 결정하지 않음** : variant 자체의 분류 / 추가 / 폐기 (→ § 4.7 Variant Model, 5 차)

→ 본 차수에서는 표현 방식 후보 4 개 나열까지만. 어느 family 가 어느 방식을 쓸지의 결정은 5 차 Variant Model.

### 8.4 token 참조 방식

Family CSS 가 Token Inventory 의 4 status 를 어떻게 *참조* 하는가 :

| Token Inventory status | Family CSS 의 참조 방식 |
|---|---|
| `covered` | 기존 token 그대로 `var(--color-block-title-from)` 등 사용. 신규 정의 X |
| `gap_candidate` | **참조 placeholder 사용** — `var(--c-table-header-cyan)` (후보) 식으로 *후보 이름* 표기. 실제 token 추가 / 채택은 § 4.5 Token Resolution 의 결정 |
| `hierarchy_mapping_only` | frame raw px (figma 1280 폭) 직접 사용 X. slide-body 위계 토큰 (`--font-zone-title` / `--font-sub-title` 등) 참조 + zoom / scale 메타는 § 4.5 의 결정 |
| `hold_recheck_after_conversion` | Family CSS 에서 사용 X. 폐기 단정 X (32 frame 변환 후 재검증) |

**Family CSS 가 결정함** : 어느 token 을 어느 슬롯에 쓰는가 (참조 매핑)

**Family CSS 가 결정하지 않음** : token 자체의 추가 / 변경 / 폐기 (→ § 4.5 Token Resolution, 5 차)

> Token Inventory 의 4 status 표는 [`PHASE-Z-FRAME-STYLE-INVENTORY.md`](PHASE-Z-FRAME-STYLE-INVENTORY.md) 참조. 본 섹션에서 redescribe X.

### 8.5 asset 의존 표시 방식

asset-heavy family 의 self-policy 표시. § 8.2 의 `asset 의존도` 컬럼이 이미 분류 (low / mid / high / very high). Family CSS 는 이 분류를 self-meta 로 표시.

| 의존도 | Family CSS 의 표시 방식 (후보) |
|---|---|
| `low` | meta 표시 불필요 |
| `mid` | family 헤더 주석에 `asset-dependency: mid` + 자산 항목 명시 (예 : SVG 아이콘 / 이미지 1~3 개) |
| `high` | family 헤더 주석에 `asset-dependency: high` + placeholder 정책 명시 (예 : "사진 ×3 — 사용자 제공 자산 필요") |
| `very high` | family 헤더 주석에 `asset-dependency: very high` + **runtime 적용 시 자산 풀 / placeholder 필수** 경고 |

특수 케이스 : F01 같은 asset-heavy / reference-like family 는 **pure CSS family 가 아님** 명시. family 분류 자체가 asset slot 컴포넌트 / reference 후보 임을 self-meta 로.

**Family CSS 가 결정함** : 의존도 self-meta 표시 형식 (참조 인터페이스)

**Family CSS 가 결정하지 않음** : asset placeholder 의 실제 디자인 / 자산 풀 / 사용자 제공 정책 (→ § 4.6 Asset Policy, 5 차)

### 8.6 Family CSS 가 결정하지 않는 것

Skeleton § 4.2 의 "결정 안 함" 확장 + 본 3 차에서 추가 명확화 :

- ❌ HTML 마크업 자체 (→ Jinja2 Runtime Templates, 미작성)
- ❌ frame ↔ Zone 매핑 (→ Zone Catalog, § 7 작성됨)
- ❌ 텍스트 콘텐츠 / AI 호출 (→ AI Boundary, 미작성)
- ❌ variant 모델 자체 (분류 / 추가 / 폐기) — 본 § 8.3 에서는 *참조 표현 방식* 후보만 (→ § 4.7 Variant Model, 5 차)
- ❌ token 자체 (값 / 추가 / 변경 / 폐기) — 본 § 8.4 에서는 *참조 방식* 만 (→ § 4.5 Token Resolution, 5 차)
- ❌ asset 정책 자체 (placeholder 디자인 / 자산 풀 / 사용자 제공 룰) — 본 § 8.5 에서는 *self-meta 표시* 만 (→ § 4.6 Asset Policy, 5 차)
- ❌ frame 별 CSS — Family CSS 는 family 단위 (룰 2 재확인)
- ❌ 실제 CSS 파일 생성 / 이름 확정 / 위치 — 사용자 승인 후 별도 단계
- ❌ legacy `templates/blocks/structures/` 6 파일 삭제 — 사용자 승인 후

---

### 8 차수 자체 점검 (작성 후)

- ✅ Family CSS 영역만 다룸 (Variant Model 자체 / Token Resolution 자체 / Asset Policy 자체 / Jinja2 / AI 침범 X)
- ✅ Frame Inventory `Phase Z Target` 컬럼 redescription 0 — family 수렴 결과만
- ✅ Token Inventory 4 status 표 redescription 0 — 링크 참조만
- ✅ FRAME-INTEGRATION-MAP.md 분류 redescription 0
- ✅ 룰 1 (참조하는지만 다룸) + 룰 2 (frame 별 X / family 단위) 섹션 머리에 명시
- ✅ family 후보 11 개 centerpiece (자산 의존도 분류 포함)
- ✅ F01 asset-heavy / reference-like family 별도 분류 명시
- ✅ Skeleton § 4.2 의 "결정 안 함" 8.6 에서 확장 + 5 차 dedicated 영역 cross-reference

---

## 9. Jinja2 Runtime Templates — 4 차 본격 설계

> ⚠️ **룰 1** — Jinja2 는 HTML 구조를 조립한다. AI 는 Jinja2 구조를 만들지 않는다. AI 출력은 이미 정해진 zone slot 안의 콘텐츠 값으로만 들어온다.
>
> ⚠️ **룰 2** — Jinja2 는 *조립 실행자* 다. status label 결정 / variant 채택 결정 / fallback 정책은 다른 영역에서 받은 결정. Jinja2 는 그 결정을 받아 *조립* 만 한다.

### 9.1 Jinja2 Runtime Templates 의 역할

Jinja2 는 다음을 책임진다 :

1. **HTML 구조 조립** — slide-base → slide-body → layout preset → zone → family partial 의 마크업 조합
2. **슬롯 배치** — zone slot 위치에 family partial / 콘텐츠 삽입
3. **검증 hook 위치** — overflow 측정 / 시각 품질 평가 fixture 위치
4. **본문 preview ↔ 팝업 원문 분리** — 텍스트 무손실 보존 (Phase Z 절대 룰)

받는 입력 :
- Zone Catalog (§ 7) : `layout_preset`, zone status label
- Family CSS (§ 8) : family partial 식별자, variant
- AI 출력 : zone 단위 콘텐츠
- MDX 원문 : preview / popup 분리용

→ Jinja2 = **조립 실행자**. 받은 결정을 마크업으로 직조하기만.

### 9.2 입력 데이터 계약

Jinja2 가 받는 입력의 *필드 shape* :

| 필드 | 출처 | shape / 예시 |
|---|---|---|
| `slide_meta` | MDX 분석 (Stage 1) | `{ chapter_title, conclusion, footer_text }` |
| `layout_preset` | Zone Catalog (§ 7.2-1) | `Type A` / `Type B` / `Type B'` / `Type B''` |
| `zones[]` | Zone Catalog (§ 7) | `[{ zone_id, slot_position, status_label, frame_id, content }, ...]` |
| `zone.content` | AI 출력 (zone 단위) + MDX 원문 | `{ preview_text, popup_full, slot_payload }` |
| `family_meta` | Family CSS (§ 8) | `{ family_id, variant, asset_dependency }` |

**Jinja2 가 결정함** : 위 입력 shape 를 *수신* 하고 *마크업* 으로 변환.

**Jinja2 가 결정하지 않음** : 필드 값 자체 (각 출처 영역의 결정), 새 필드 추가 / 변경.

### 9.3 조립 위계

Phase Z 위계가 Jinja2 안에서 어떻게 표현되는가 :

```
slide-base (existing template)
  ├─ slide-title          ← MDX 대목차 자동 매핑
  ├─ slide-divider        (고정)
  ├─ slide-body (≈ 1200×590)
  │    └─ layout preset (Type A / B / B' / B'')
  │         └─ zones[]   (preset 별 slot 정의)
  │              └─ family partial (family CSS 영역)
  │                   └─ slot content (AI 출력 + MDX 원문)
  └─ slide-footer         ← MDX 대목차 결론 자동 매핑
```

**Jinja2 가 결정함** :
- 위계 각 단계의 wrapper / container 마크업
- preset → zones 분배 메커니즘 (preset-specific Jinja2 partial)
- zone → family partial 임베딩 위치
- preview ↔ popup 분리 마크업 위치

**Jinja2 가 결정하지 않음** :
- preset 선택 (→ Zone Catalog § 7.2-1)
- zone slot 의 콘텐츠 role 매핑 (→ Zone Catalog § 7.2-2)
- family partial 의 시각 / 스타일 (→ Family CSS § 8)
- frame 별 차이 (→ family variant, § 8.3)

### 9.4 Zone Catalog status label → 조립 인터페이스

§ 7.4 의 6 status label 을 Jinja2 가 어떻게 *받아* 조립하는가. **정책 결정 X, 조립 인터페이스만**.

| Status label | Jinja2 의 조립 인터페이스 |
|---|---|
| `matched_zone` | family partial 렌더 대상. 입력 shape 그대로 마크업 조립 |
| `adapt_matched_zone` | family partial 렌더 대상 (adapt hint 를 `family_meta` 로 전달, 실제 스타일 처리는 Family CSS) |
| `extract_matched_zone` | family partial 렌더 대상 (extract hint 를 `family_meta` 로 전달) |
| `review_required` | preview / review payload 로 분리 마크업, 검토 marker 부착 |
| `fallback_candidate` | **Jinja2 직접 렌더 대상 아님** — Fallback Behavior 로 위임 |
| `not_runtime_candidate` | **런타임 family partial 렌더 대상 아님** — 디자인 톤 참고만 (Asset Policy / Style Inventory) |

> 본 표는 *Jinja2 의 조립 인터페이스* 만 정의한다. 실제 fallback 동작 / review 처리 흐름 / not_runtime 의 디자인 톤 적용은 § 4.6 / § 4.8 의 영역.

### 9.5 AI 출력의 Jinja2 진입 위치

AI 출력은 **`zone.content` 의 sub-필드** (§ 9.2) 로만 들어온다.

| 진입 허용 필드 | 의미 |
|---|---|
| `zone.content.preview_text` | zone slot 본문 preview (AI 가 다듬은 짧은 표시 텍스트) |
| `zone.content.popup_full` | 팝업 / `<details>` / 별도 레이어 원문 (MDX 무손실) |
| `zone.content.slot_payload` | family partial 의 슬롯별 콘텐츠 (예 : `{ title, body, items[] }`) |

**진입 금지 영역** (Phase R' 회귀 방지) :

- ❌ HTML 구조 자체 (slide-base / slide-body / preset / zone / family partial 의 wrapper)
- ❌ class 명 / data attribute / id
- ❌ Jinja2 template (`{% %}` / `{{ }}` 매크로)
- ❌ family 선택 / variant 선택 / preset 선택
- ❌ 새 frame 결정 / catalog status label 결정

> AI 가 출력할 수 있는 것은 *콘텐츠 값* 만. 구조 / 스타일 / 매핑은 모두 코드의 영역.
>
> 이 경계가 무너지면 Phase R' 의 "AI 가 HTML 구조 직접 생성" 회귀로 빠진다. **Jinja2 의 입력 계약 (§ 9.2) 이 이 경계의 강제 메커니즘**.

### 9.6 Jinja2 가 결정하지 않는 것

Skeleton § 4.3 의 "결정 안 함" 확장 + 본 4 차 추가 :

- ❌ frame 시각 / 스타일 (→ Family CSS § 8)
- ❌ frame ↔ Zone 매핑 / preset 선택 / status label 부여 (→ Zone Catalog § 7)
- ❌ AI 모델 / 프롬프트 / 호출 횟수 (→ AI Boundary § 4.4, 5 차)
- ❌ token 자체 (→ Token Resolution § 4.5, 5 차)
- ❌ asset 정책 자체 (→ Asset Policy § 4.6, 5 차)
- ❌ variant 모델 자체 (→ Variant Model § 4.7, 5 차)
- ❌ fallback 실제 동작 (→ Fallback Behavior § 4.8, 5 차)
- ❌ review_required 진입 후 검토 흐름 (→ AI Boundary 또는 Fallback Behavior, 5 차)
- ❌ 실제 Jinja2 파일 생성 / 마크업 코드 작성 — 사용자 승인 후 별도 단계
- ❌ CSS class / id naming 확정 — 구현 단계

---

### 9 차수 자체 점검 (작성 후)

- ✅ Jinja2 영역만 다룸 (정책 결정 / Family CSS / AI 영역 / Fallback 동작 침범 X)
- ✅ Frame Inventory / Token Inventory / Section 7~8 표 redescription 0
- ✅ 룰 1 (HTML 조립 / AI 는 zone slot 콘텐츠만) + 룰 2 (조립 실행자 / 정책 결정자 X) 섹션 머리 명시
- ✅ § 9.2 입력 데이터 계약 필드 shape 5 개 명시
- ✅ § 9.4 status label *조립 인터페이스* 까지만, 정책 결정 X (fallback 동작 / review 흐름은 후속 영역)
- ✅ § 9.5 AI 진입 허용 / 금지 명시 — Phase R' 회귀 방지 메커니즘
- ✅ § 9.6 boundary 10 항목 + 5 차 dedicated 영역 cross-reference

---

## 10. AI Boundary — 5a 본격 설계

> ⚠️ **룰 1 — AI 호출 단위는 zone 안 콘텐츠다.**
>
> 슬라이드 전체 / 레이아웃 / 프리셋 / family 선택 / 새 frame 결정 / status label 결정은 AI 의 영역이 아니다.

> ⚠️ **룰 2 — AI 출력은 `zone.content.*` 의 콘텐츠 값만이다.**
>
> HTML / CSS / class / Jinja2 / 구조 결정은 AI 출력에 포함하지 않는다.

### 10.1 AI Boundary 의 역할

AI Boundary 는 다음을 책임진다 :

1. **AI 호출 단위 정의** — 한 호출 = 하나의 zone 안 콘텐츠 scope
2. **허용 입력 / 출력 형식 정의** — AI 가 받는 것 / 만드는 것의 contract
3. **금지 영역 정의** — AI 가 만들지 말아야 할 것 (Phase R' 회귀 방지)
4. **Jinja2 입력 계약 (§ 9.2) 과의 정합** — `zone.content.*` 필드와 cross-reference

받는 입력 :
- Zone Catalog (§ 7) : zone 정보 (zone_id, slot_position, frame_id, status_label)
- Family CSS (§ 8) : family meta (family_id, variant, asset_dependency)
- MDX 원문 : 해당 zone 에 속하는 부분

→ AI Boundary = **AI 의 활동 반경 정의**. 모델 / 프롬프트 / 호출 빈도는 본 차수 X.

### 10.2 AI 호출 단위 — zone content only (scope)

한 AI 호출 = **하나의 zone 안 콘텐츠** 단위.

| scope 단위 | 허용 / 금지 |
|---|---|
| 한 zone 안 콘텐츠 | ✅ AI 호출 단위 |
| 슬라이드 전체 | ❌ |
| 레이아웃 / 프리셋 결정 | ❌ |
| family / variant 선택 | ❌ |
| 새 frame 발굴 / 결정 | ❌ |
| status label 부여 | ❌ |

→ 한 슬라이드 = N 개 zone = 최대 N 회 AI 호출 (zone 별 1 회 단위). 호출 횟수 / 빈도 / 시점은 본 차수 X (파이프라인 / Fallback 영역).

### 10.3 허용 입력 / 허용 출력

#### 허용 입력 (AI 가 받는 것)

| 필드 | 의미 |
|---|---|
| `zone_meta` | `{ zone_id, slot_position, status_label, frame_id }` |
| `family_meta` | `{ family_id, variant, asset_dependency }` |
| `mdx_excerpt` | 해당 zone 에 속하는 MDX 원문 |
| `style_hint` | family 의 스타일 힌트 (예 : "title 위계", "body 위계") — Family CSS 영역에서 전달 |
| `layout_meta` | `{ preset_id, neighbor_zones }` — 이웃 zone 컨텍스트 (선택) |

#### 허용 출력 (AI 가 만드는 것 — `zone.content.*`)

| 필드 | 의미 |
|---|---|
| `zone.content.preview_text` | zone slot 본문 preview (짧은 표시 텍스트) |
| `zone.content.popup_full` | 팝업 / `<details>` 원문 (MDX 무손실 또는 AI 가 재구성한 무손실 버전) |
| `zone.content.slot_payload` | family partial 슬롯별 콘텐츠 (예 : `{ title, body, items[] }`) |

→ 출력 3 필드 모두 § 9.2 의 `zone.content.*` 안에 들어간다.

### 10.4 금지 출력

AI 가 출력에 포함하면 안 되는 것 :

- ❌ HTML 구조 (`<div>`, `<section>`, `<table>` 등 wrapper / container 마크업)
- ❌ CSS class 명 / id / data attribute
- ❌ Jinja2 template 매크로 (`{% %}` / `{{ }}`)
- ❌ family 선택 / variant 선택 / preset 선택
- ❌ 새 frame 결정 / catalog status label 결정
- ❌ token 추가 / 변경 / 폐기 결정
- ❌ asset placeholder 디자인
- ❌ fallback 정책 / review 정책

> 이 금지 출력 영역이 무너지면 **Phase R' 회귀** (AI 가 HTML 구조 직접 생성) 로 빠진다. § 9.5 의 *진입 위치 차단* + § 10.4 의 *금지 출력 명시* 가 두 면 차단 메커니즘.

### 10.5 Jinja2 입력 계약 (§ 9.2) 과의 연결

AI 출력은 Jinja2 입력 계약의 **`zone.content` 필드** 로 들어간다. 입력 계약 안에서 *AI 영역 ↔ 다른 영역* 이 완전 분리됨 :

| Jinja2 입력 계약 필드 (§ 9.2) | 출처 영역 | AI 가 만드는가 |
|---|---|---|
| `zone.content.preview_text` | AI Boundary | ✅ |
| `zone.content.popup_full` | AI Boundary | ✅ |
| `zone.content.slot_payload` | AI Boundary | ✅ |
| `slide_meta` | MDX 분석 (Stage 1) | ❌ |
| `layout_preset` | Zone Catalog (§ 7) | ❌ |
| `zones[]` 자체 / `zone_id` / `status_label` | Zone Catalog (§ 7) | ❌ |
| `family_meta` | Family CSS (§ 8) | ❌ |

→ **Jinja2 입력 계약 자체가 boundary 강제 메커니즘**. AI 가 잘못된 영역에 출력해도 입력 계약 단계에서 reject 가능 (구현 단계 결정).

### 10.6 AI Boundary 가 결정하지 않는 것

Skeleton § 4.4 의 "결정 안 함" 확장 + 본 5a 추가 :

- ❌ 구체 프롬프트 / 모델 (구현 영역)
- ❌ 호출 비용 / 토큰 사용량 / 응답 시간 (구현 영역)
- ❌ **AI 호출 시점 / 빈도** — AI Boundary 는 *호출 시 무엇을 받고 무엇을 만드는가* 까지만, *언제 부르는가* 는 파이프라인 / Fallback Behavior 영역
- ❌ fallback 실제 실행 절차 (→ Fallback Behavior § 4.8, 5e)
- ❌ review_required 의 검토 흐름 (→ Fallback Behavior 또는 파이프라인)
- ❌ token 자체 (값 / 추가 / 변경 / 폐기) (→ Token Resolution § 4.5, 5b)
- ❌ asset 정책 자체 (→ Asset Policy § 4.6, 5c)
- ❌ variant 모델 자체 (→ Variant Model § 4.7, 5d)
- ❌ HTML 구조 / Jinja2 마크업 (→ Jinja2 § 9, Phase R' 회귀 방지)
- ❌ AI 응답 검증 / 재호출 정책 (구현 영역)

---

### 5a 차수 자체 점검 (작성 후)

- ✅ AI Boundary 영역만 다룸 (Token / Asset / Variant / Fallback / Jinja2 / Zone Catalog 침범 X)
- ✅ Frame Inventory / Token Inventory / Section 7~9 표 redescription 0
- ✅ 룰 1 (호출 단위 = zone) + 룰 2 (출력 = `zone.content.*` 콘텐츠 값만) 섹션 머리 명시
- ✅ § 10.4 금지 출력 + § 9.5 금지 진입 = 두 면 Phase R' 회귀 차단
- ✅ § 10.5 가 § 9.2 입력 계약과의 cross-reference 명시 (AI ↔ 다른 영역 분리)
- ✅ § 10.6 에 "AI 호출 시점 / 빈도" 비범위 명시 (Fallback / 파이프라인 정책 침범 차단)
- ✅ Skeleton § 4.4 의 "결정 안 함" 10 항목으로 확장

---

## 11. Token Resolution — 5b 본격 설계

> ⚠️ **룰 1 — Token Resolution 은 token 적용 판단을 정의하지만 token 파일을 수정하지 않는다.**
>
> `covered`, `gap_candidate`, `hierarchy_mapping_only`, `hold_recheck_after_conversion` 은 모두 *설계 상태* 이며 *구현 결정* 이 아니다.

> ⚠️ **룰 2 — frame raw px 는 slide-body token 값과 직접 매칭하지 않는다.**
>
> typography / spacing / radius 는 *위계 매핑* 만 수행하고, 실제 값은 slide-body scale 에서 재산정한다.

### 11.1 Token Resolution 의 역할

Token Resolution 은 다음을 책임진다 :

1. **4 status 적용 판단 룰** — Token Inventory 의 4 status (covered / gap_candidate / hierarchy_mapping_only / hold_recheck_after_conversion) 별 적용 가능성 판단
2. **frame raw px ↔ slide-body scale 위계 매핑 룰** — figma 1280 폭 기준 raw px 와 slide-body 1200×590 토큰 스케일 사이의 매핑 원칙
3. **추가 / 변경 / 폐기 보류 원칙** — token 파일 수정은 본 차수 X
4. **family CSS 와의 참조 인터페이스** (§ 8.4 cross-reference)

받는 입력 :
- Token Inventory 18 행 ([`PHASE-Z-FRAME-STYLE-INVENTORY.md`](PHASE-Z-FRAME-STYLE-INVENTORY.md))
- Frame Inventory 의 Style Elements 관찰값
- 기존 `templates/styles/tokens/` 3 파일 (colors / spacing / typography)

→ Token Resolution = **token 적용 판단 정의**. 실제 token 파일 수정 / 신규 추가 / 폐기는 본 차수 X.

### 11.2 Token Inventory 4 status 처리 룰

| Status | Token Resolution 판단 룰 |
|---|---|
| `covered` | 기존 token 정확 hex 일치 검증된 상태. family CSS / runtime 에서 *as-is 참조*. 변경 / 추가 결정 X |
| `gap_candidate` | **working name 후보** 로만 유지. 이름 자체 (`--c-table-header-cyan` 등) 도 *아직 확정 X*. 실제 token 추가 / 채택 / 명명은 Phase Z-2 구현 단계 사용자 승인 후 |
| `hierarchy_mapping_only` | typography / spacing / radius 는 raw px 직접 매칭 X. *위계만* 보고 slide-body scale 에서 재산정 (§ 11.3) |
| `hold_recheck_after_conversion` | 미사용 / 폐기 단정 X. 18 미변환 frame 변환 후 *재검증* |

→ 본 표는 4 status 의 *적용 판단* 까지만. token 자체의 값 / 이름 / 추가 / 변경 / 폐기는 본 차수 X.

### 11.3 frame raw px ↔ slide-body scale 위계 매핑

scale 차이 :

| 출처 | scale | 예시 값 |
|---|---|---|
| frame raw px | figma 1280 폭 기준 (zoom 0.49 ~ 1.11 다양) | title 70px / body 35~42px / radius 5~50px |
| slide-body 토큰 | slide-body 1200×590 스케일 | `--font-zone-title` 13px / `--font-body` 11px / `--card-radius` 6px |

위계 매핑 룰 (typography 예시) :

| frame raw 위계 | slide-body 위계 매핑 (후보) |
|---|---|
| frame title (raw 70px Bold + gradient) | `--font-zone-title` (13px) 또는 `--font-sub-title` (12px) — 위계 매칭 |
| frame heading (raw 45~55px Bold) | `--font-sub-title` 위계 |
| frame body (raw 35~42px Medium) | `--font-body` (11px) 위계 |
| frame caption (raw 30px) | `--font-caption` (10px) 위계 |

→ **위계 매핑 룰만** 본 차수에서 결정. *실제 px 값 매핑* 은 slide-body scale 재산정 영역 (구현 단계).

같은 룰이 spacing / radius 에도 적용 :
- frame raw radius 5 / 30 / 50px ↔ slide-body `--card-radius` 위계
- frame raw gap 8 / 12 / 25px ↔ slide-body `--space-*` 위계

### 11.4 family CSS 와의 참조 인터페이스 (§ 8.4 cross-reference)

§ 8.4 가 결정함 : family CSS 의 token 참조 *syntax* (`var(--color-block-title-from)` 형태)
§ 11.4 가 결정함 : family CSS 가 어느 token 을 *어떤 조건으로* 참조 가능한가의 판단

| Status | family CSS 참조 가능성 |
|---|---|
| `covered` | ✅ 즉시 참조 가능 |
| `gap_candidate` | △ working name 후보로 참조 (token 자체 미정 — 구현 단계 reject 가능) |
| `hierarchy_mapping_only` | ✅ 위계 매칭으로 참조 (raw px 직접 사용 X) |
| `hold_recheck_after_conversion` | ❌ 참조 X |

→ 참조 *syntax* 는 § 8.4. 본 표는 Token Resolution 의 *판단 perspective* 만.

### 11.5 추가 / 변경 / 폐기 보류 원칙

| 행위 | 본 차수 결정 | 위임 |
|---|---|---|
| 신규 token 추가 | ❌ X | Phase Z-2 구현 진입 시 사용자 승인 |
| working name 확정 (`--c-*` 등) | ❌ X | 사용자 승인 영역 |
| 기존 token 값 변경 | ❌ X (covered 는 frame 정확 일치, 변경 사유 없음) | — |
| hold token 폐기 | ❌ X | 32 frame 전체 변환 후 재검증 |
| 명명 컨벤션 (`--c-` / `--g-` / `--fs-` 등) 확정 | ❌ X | working 단계, 사용자 승인 후 최종 |

→ Phase Z 절대 룰 *"기존 templates 삭제 / 교체 실행 X"* + *"새 token / css 파일 생성 X"* 와 정합.

### 11.6 Token Resolution 이 결정하지 않는 것

Skeleton § 4.5 의 "결정 안 함" 확장 + 본 5b 추가 :

- ❌ token 값 자체 (→ Style Inventory / Frame 관찰값)
- ❌ token 파일 생성 / 수정 / 삭제 (구현 영역)
- ❌ 신규 token 이름 최종 확정 (사용자 승인 영역)
- ❌ slide-body scale 재산정의 구체 px 값 (구현 영역)
- ❌ confidence 임계값 (→ 매칭 시스템 V1~V4)
- ❌ family CSS 의 token 참조 *syntax* (→ § 8.4)
- ❌ asset 정책 자체 (→ Asset Policy § 4.6, 5c)
- ❌ variant 모델 자체 (→ Variant Model § 4.7, 5d)
- ❌ AI 호출 자체 (→ AI Boundary § 4.4 / § 10)
- ❌ HTML / CSS / Jinja2 마크업 (→ § 8 / § 9)

---

### 5b 차수 자체 점검 (작성 후)

- ✅ Token Resolution 영역만 다룸 (Style Inventory / 구현 / family CSS syntax / Asset / Variant / AI 침범 X)
- ✅ Token Inventory 18 행 redescription 0 — 4 status *처리 룰* 만
- ✅ § 8.4 의 표 redescription 0 — *참조 가능성 판단* perspective 만
- ✅ 룰 1 (token 파일 수정 X / 4 status = 설계 상태) + 룰 2 (raw px ≠ slide-body, 위계 매핑만) 섹션 머리 명시
- ✅ § 11.2 에 working name 후보 표현 (gap_candidate 이름 미확정)
- ✅ § 11.3 에 위계 매핑 룰만, 실제 값은 구현 영역
- ✅ § 11.5 추가 / 변경 / 폐기 / 명명 / 컨벤션 5 행위 모두 보류 원칙
- ✅ § 11.6 boundary 10 항목 + 5c~5e dedicated 영역 cross-reference

---

## 12. Asset Policy — 5c 본격 설계

> ⚠️ **룰 1 — Asset Policy 는 자산 처리 기준을 정의하지만 자산을 생성하지 않는다.**
>
> 이미지 / SVG / texture / icon / placeholder 는 모두 *설계 상태* 이며, 실제 파일 생성은 구현 단계.

> ⚠️ **룰 2 — 자산 의존 family 는 metadata 로 표시하고, Jinja2 / Family CSS 는 그 metadata 를 참조한다.**
>
> Asset Policy 는 자산 필요 여부와 처리 분기를 정의한다. 렌더 구조나 CSS 구현은 다른 영역의 책임.

> ⚠️ **룰 3 — Asset Policy 는 생성 도구를 결정하지 않는다.**
>
> Gemini / imagegen / Figma export / 사용자 제공 중 무엇을 쓸지는 *구현 단계* 결정.

### 12.1 Asset Policy 의 역할

Asset Policy 는 다음을 책임진다 :

1. **자산 의존도 등급 처리 룰** — `low` / `mid` / `high` / `very high` 정책 해석
2. **자산 유형 분기** — 사진 / texture / icon / 다이어그램 SVG / 장식 5 분류
3. **자산 상태 라벨** — `placeholder_allowed` / `user_asset_required` / `asset_optional` / `convertible_to_css_or_svg` / `reference_only`
4. **`asset_meta` 정의** — Jinja2 / Family CSS 가 받을 metadata 형식
5. **추가 / 변경 / 폐기 / 도구 보류 원칙** — 자산 파일 생성 / 도구 선택은 본 차수 X

받는 입력 :
- Frame Inventory `Asset Notes` 컬럼 (자산 항목 / 의존도 관찰값)
- Family CSS § 8.5 의 의존도 self-meta 표시 (`low` / `mid` / `high` / `very high`)

→ Asset Policy = **자산 처리 기준 정의**. 자산 생성 / 도구 / placeholder 디자인은 본 차수 X.

### 12.2 자산 의존도 등급 처리 룰

§ 8.5 와의 perspective 분리 :
- § 8.5 = Family CSS 가 *어떻게 self-meta 를 표시* 하는가 (형식)
- § 12.2 = 각 등급이 *정책적으로 어떻게 해석* 되는가 (의미)

| 등급 | 정책 해석 | 처리 룰 |
|---|---|---|
| `low` | 자산 거의 X. CSS 변환으로 충분 | 별도 정책 불필요. `asset_meta` 불필요 |
| `mid` | 일부 자산 (1~3 개) 이미지 유지 가능 | `asset_meta` 에 자산 항목 + 상태 라벨 표시 |
| `high` | 다수 자산 (10+ 또는 사진). 정책 분기 필수 | `asset_meta` 에 상태 라벨 + 자산 별 처리 분기. `user_asset_required` 가능성 큼 |
| `very high` | 자산이 family 의 핵심 | `asset_meta` 에 상태 라벨 + family 자체의 `reference_only` / asset-heavy 표시 검토 |

Frame Inventory 에서 `high` / `very high` family : `split-panel` (F21/F22) / `persona-cards` (F14) / `system-diagram` (F07) / F01 (reference-like) — 자세한 자산 목록은 [`PHASE-Z-FRAME-STYLE-INVENTORY.md`](PHASE-Z-FRAME-STYLE-INVENTORY.md) 의 `Asset Notes` 참조 (redescription X).

### 12.3 자산 유형 분기

각 family 의 자산을 5 유형으로 분류 :

| 자산 유형 | 특징 | 처리 후보 |
|---|---|---|
| **사진** (사람 / 시공 / 풍경) | 시각 의미 핵심, 재현 / 대체 곤란 | `user_asset_required` 우선 |
| **texture** (배경) | 분위기 / 톤 표현 | `placeholder_allowed` / `convertible_to_css_or_svg` / *생성 가능성* (도구 미정) |
| **icon** (단순 그래픽) | 단순 형태, 의미 핵심 | `convertible_to_css_or_svg` (SVG 인라인 가능성) |
| **다이어그램 SVG** (좌표 기반) | 수학 재구성 가능 | `convertible_to_css_or_svg` (코드 재구성 가능성) |
| **장식** (아크 / 화살표 / 구분선) | 단순 형태, 옵셔널 | `asset_optional` / `convertible_to_css_or_svg` |

→ "생성 가능성" 표현 까지만. 실제 도구 선택 (Gemini / imagegen / Figma export / 사용자 제공) 은 룰 3 에 따라 본 차수 X.

### 12.4 자산 상태 라벨 (5 후보) — centerpiece

본 섹션의 핵심. 각 자산 슬롯이 어떤 처리 정책을 갖는지 라벨링.

| 라벨 | 의미 | 적용 케이스 후보 |
|---|---|---|
| `placeholder_allowed` | placeholder 로 대체 가능 (의미 보존 영향 적음) | texture / 일부 장식 |
| `user_asset_required` | 사용자 제공 필수 (placeholder 불가) | 사진 (시공 / 인물) — 의미 보존 핵심. **5 라벨 중 유일한 의무** |
| `asset_optional` | 자산 없이 렌더 가능 | 장식 (아크 / 화살표) |
| `convertible_to_css_or_svg` | 코드 변환 가능 (자산 불필요) | icon / 다이어그램 SVG / 단순 장식 |
| `reference_only` | runtime 적용 X. 디자인 톤 참고만 | F06 (지도) / F01 (image-heavy reference) family |

자산 유형 × 상태 라벨 직교 매트릭스 (가능성 표) :

| 자산 유형 \ 상태 | `placeholder_allowed` | `user_asset_required` | `asset_optional` | `convertible_to_css_or_svg` | `reference_only` |
|---|---|---|---|---|---|
| 사진 | ❌ | ✅ | ❌ | ❌ | △ (reference-like family 만) |
| texture | ✅ | △ | △ | ✅ | ❌ |
| icon | △ | ❌ | △ | ✅ | ❌ |
| 다이어그램 SVG | ❌ | ❌ | ❌ | ✅ | △ |
| 장식 | ✅ | ❌ | ✅ | ✅ | ❌ |

→ 같은 유형이라도 family / 의도에 따라 라벨이 다를 수 있음. **라벨 부여 자체는 family 별로 결정 (Phase Z-2 구현 진입 시 사용자 승인)**.

### 12.5 `asset_meta` 정의 + Jinja2 / Family CSS 참조 인터페이스

Asset Policy 가 정의하는 metadata 형식 :

| 필드 | shape | 의미 |
|---|---|---|
| `family_id` | string | 어느 family 의 자산인가 |
| `dependency_level` | `low` / `mid` / `high` / `very_high` | 의존도 등급 |
| `assets[]` | `[{ slot_id, asset_type, status_label, hint }, ...]` | family 안 자산 슬롯 목록 |
| `assets[].asset_type` | `photo` / `texture` / `icon` / `diagram_svg` / `decoration` | 자산 유형 (5 분류) |
| `assets[].status_label` | 5 상태 라벨 중 하나 | 처리 정책 |
| `assets[].hint` | string (optional) | 자산 의미 / 위치 hint (placeholder 디자인 시 참고) |

Jinja2 / Family CSS 가 받는 방식 :
- Jinja2 (§ 9.2 입력 계약) 의 `family_meta.asset_dependency` 가 본 `asset_meta.dependency_level` 로 채워짐
- Family CSS (§ 8.5 self-meta) 가 `asset_meta` 의 `dependency_level` + `assets[].status_label` 참조

→ `asset_meta` *정의* 는 본 § 12.5. 실제 *참조 syntax* 는 § 8.5 / § 9.2 (perspective 분리).

### 12.6 Asset Policy 가 결정하지 않는 것

Skeleton § 4.6 의 "결정 안 함" 확장 + 본 5c 추가 :

- ❌ 실제 자산 파일 생성 / 다운로드 / 변환 (구현 영역)
- ❌ **생성 도구 선택** (Gemini / imagegen / Figma export / 사용자 제공) — 룰 3
- ❌ placeholder 의 시각 디자인 자체 (구현 영역)
- ❌ SVG 코드 작성 (구현 영역)
- ❌ 사용자 자산 수집 UX / workflow (구현 영역)
- ❌ asset_meta 의 어느 family 의 어느 슬롯이 어느 라벨인지 *최종 부여* (사용자 승인 영역)
- ❌ token 자체 (→ Token Resolution § 4.5 / § 11)
- ❌ variant 모델 자체 (→ Variant Model § 4.7, 5d)
- ❌ HTML / CSS / Jinja2 syntax (→ § 8 / § 9)
- ❌ AI 호출 (→ AI Boundary § 4.4 / § 10)

---

### 5c 차수 자체 점검 (작성 후)

- ✅ Asset Policy 영역만 다룸 (Token / Variant / Fallback / Jinja2 / Family CSS syntax / AI 침범 X)
- ✅ Frame Inventory `Asset Notes` redescription 0 — 자세한 자산 목록 링크 참조
- ✅ § 8.5 의 self-meta 표시 redescription 0 — *정책 해석* perspective 만
- ✅ § 9.2 의 family_meta redescription 0 — asset_meta 정의 + cross-reference
- ✅ 룰 1 + 룰 2 + 룰 3 (생성 도구 결정 X) 섹션 머리 명시
- ✅ § 12.4 5 상태 라벨 centerpiece (`placeholder_allowed` / `user_asset_required` / `asset_optional` / `convertible_to_css_or_svg` / `reference_only`)
- ✅ `_required` 는 `user_asset_required` 만 (의무 / 정책 상태 분리)
- ✅ § 12.3 자산 유형 5 분류 + § 12.4 직교 매트릭스
- ✅ "생성 가능성" 표현 까지만 (도구 결정 X)
- ✅ § 12.6 boundary 10 항목 + 5d~5e dedicated 영역 cross-reference

---

## 13. Variant Model — 5d 본격 설계

> ⚠️ **룰 1 — Variant Model 은 frame 차이를 family 안에서 표현하는 기준을 정의한다.**
>
> frame 별 CSS 를 만들기 위한 장치가 아니라, *family 단위 수렴을 유지* 하기 위한 장치다.

> ⚠️ **룰 2 — variant 선택은 코드 / catalog 의 결정이다.**
>
> AI 는 variant 를 선택하거나 새 variant 를 만들지 않는다.

### 13.1 Variant Model 의 역할

Variant Model 은 다음을 책임진다 :

1. **variant 가 필요한 경우 / 불필요한 경우 판단 기준** — § 8.3 의 4 표현 방식 후보를 *언제* 사용할지
2. **표현 방식 선택 기준** — class modifier / data attribute / template parameter / variant family 중 어느 것을 어느 케이스에 적용할지의 criteria
3. **family 별 variant 후보 관리 정책** — § 8.2 의 11 family 별 variant 축을 *어떻게 관리* 할지
4. **family 분리 vs variant 흡수의 경계 기준** — 시각 / 구조 차이가 클 때 어느 쪽으로 가는지

받는 입력 :
- Family CSS § 8.3 — 4 표현 방식 후보 (class modifier / data attribute / template parameter / variant family)
- Family CSS § 8.2 — 11 family 후보 + 각 variant 축 1 차 정리
- Frame Inventory `Notes` 의 variant meta (예 : F17 의 `paired-rows`, F18 의 `vs-center-badge`)

→ Variant Model = **variant 의 *선택 기준 / 관리 정책* 정의**. 실제 class 이름 / parameter 이름 / CSS 구현은 본 차수 X.

### 13.2 variant 가 필요한 경우 (판단 기준)

variant 는 *family 를 유지하기 위한 장치* 다. 다음 케이스 별 적합한 처리 :

| 케이스 | 적합한 처리 |
|---|---|
| 같은 family, **시각 / 구조 차이 작음** | variant (class modifier 등) — § 8.3 의 4 표현 방식 후보 중 |
| 같은 family, **cardinality 차이만** (예 : `columns[N=2~4]`) | template parameter |
| 같은 family, **asset 차이만** | asset_meta 분기 (§ 12.5) — variant 영역 X |
| **시각 / 구조 차이 큼** | **별도 family 분리** (variant 로 우겨 넣지 X) |
| 사용 안 되는 variant | 폐기 보류 — 32 frame 전체 변환 후 재검증 (§ 13.5) |

> 🔒 **핵심 원칙** — variant 는 family 를 *유지* 하기 위한 장치이며, family 를 **억지로** 유지하기 위한 장치는 아니다.
>
> frame 차이가 family 의 시각 정체성을 깨뜨릴 정도면 variant 가 아니라 *별도 family 분리* 후보. § 13.5 의 분리 기준 참조.

### 13.3 4 표현 방식 선택 기준 (§ 8.3 cross-reference)

§ 8.3 = Family CSS perspective 에서 4 후보 표현 방식 정의. 본 § 13.3 = *어느 경우 어느 방식을 선택* 할지의 criteria.

| 표현 방식 (§ 8.3 참조) | 적합 criteria | 적합하지 않은 criteria |
|---|---|---|
| **CSS class modifier** | 시각 / 구조 차이가 family 안 변형 (예 : F17 `paired-rows` ↔ F18 `vs-center-badge`) | cardinality 차이만 / asset 차이만 |
| **Data attribute** | 마크업 같고 styling 만 분기 / runtime 동적 변경 가능성 | 시각 차이가 크고 구조까지 다른 경우 |
| **Template parameter** | cardinality 차이 (예 : `columns[N=2~4]`, `items[N=3~7]`) / 슬롯 수 변화 | 시각 디자인 차이 |
| **Variant family** (별도 entry) | 차이가 너무 커 한 family 안 일관 표현 어려운 경우 | 차이 작음 (over-split 위험) |

→ 본 표는 *criteria* 만. 어느 family 가 어느 방식을 채택할지 *결정* 은 § 8.3 (Family CSS perspective) + 사용자 승인. § 8.3 의 표 redescription 0.

### 13.4 family 별 variant 후보 (관리 perspective)

§ 8.2 = Family CSS perspective 에서 11 family 후보 + 각 variant 축 1 차 정리. 본 § 13.4 = *Variant Model 측 관리 후보* perspective.

| Family CSS Area | 1 차 variant 축 (§ 8.2 참조) | Variant Model 관리 후보 |
|---|---|---|
| `compare-paired.css` | `paired-rows` (F17) / `vs-center-badge` (F18) | **CSS class modifier** 적합 (시각 / 구조 차이 family 안 변형) |
| `compare-table.css` | `columns[N=2~4]` / `header_style` / `row_density` | **template parameter** 적합 (cardinality 차이) |
| `split-panel.css` | `right_items[N=3~8]` / `left_categories[N=2~5]` / `bracket_image` | **template parameter** 적합 |
| `persona-cards.css` | `actor_count[3]` / `actor_hue_palette` / `photo_required` | F14 단일 frame, *추가 frame 변환 후 재검증* |
| `three-pillar.css` | `pillars[3]` (현재 고정) / `column_hue_palette` | F13 단일 frame, *추가 frame 변환 후 재검증* |
| `quadrant.css` | `quadrants[4]` (고정) / `bar_style` / `center_quote` | F16 단일 frame, *추가 frame 변환 후 재검증* |
| `pill-list.css` | `items[N=3~7]` / `stacking_pattern` / `arc_decoration` | F09 단일 frame, *추가 frame 변환 후 재검증* |
| `cycle.css` | `main_circles[3]` / `accent_circles[6]` | F12 단일 frame, *추가 frame 변환 후 재검증* |
| `split-center.css` | (sparse data) | F27, *추가 관찰 후 확정* |
| `system-diagram.css` | (sparse data) | F07, *추가 관찰 후 확정* |
| `(asset-heavy / reference-like)` | F01 — pure CSS family X | **variant 영역 X** (→ asset_meta 영역, § 12.5) |

→ § 8.2 의 11 family 표 redescription 0. *관리 perspective* 만 (어느 표현 방식이 적합한가 + 단일 frame family 의 재검증 필요성).

### 13.5 추가 / 분리 / 폐기 기준

| 행위 | 기준 | 본 차수 결정 |
|---|---|---|
| **variant 추가** | 같은 family 안 frame 추가 시 (예 : 18 미변환 frame 변환 후) — 기존 variant 흡수 가능 vs 새 variant 필요 | 기준만 정의, 실제 추가는 사용자 승인 |
| **family 분리** | variant 가 family 의 시각 정체성을 깨뜨리는 수준일 때 — variant 흡수 보다 family 분리 후보 (§ 13.2 핵심 원칙) | 기준만 정의, 실제 분리는 사용자 승인 |
| **variant 폐기** | 32 frame 전체 변환 후 사용 안 되는 variant 발견 시 | 폐기 보류, 재검증 후 결정 |

→ Phase Z 절대 룰 *"기존 templates 삭제 / 교체 실행 X"* + *"새 family CSS 파일 생성 X"* 와 정합.

### 13.6 Variant Model 이 결정하지 않는 것

Skeleton § 4.7 의 "결정 안 함" 확장 + 본 5d 추가 :

- ❌ 실제 class / data attribute / parameter 이름 (구현 영역)
- ❌ family 분리 / 통합 *최종 결정* (사용자 승인 영역)
- ❌ variant CSS / Jinja2 구현 (→ Family CSS § 8 / Jinja2 § 9 의 *구현*)
- ❌ AI 가 variant 선택 / 추가 / 변경 (Phase R' 회귀 방지 — 룰 2)
- ❌ Jinja2 parameter 이름 (구현 영역)
- ❌ token 자체 (→ Token Resolution § 4.5 / § 11)
- ❌ asset 자체 (→ Asset Policy § 4.6 / § 12)
- ❌ fallback 정책 (→ Fallback Behavior § 4.8, 5e)
- ❌ HTML / CSS / Jinja2 syntax (→ § 8 / § 9)

---

### 5d 차수 자체 점검 (작성 후)

- ✅ Variant Model 영역만 다룸 (Token / Asset / Fallback / Jinja2 / Family CSS 구현 / AI 침범 X)
- ✅ § 8.3 의 4 표현 방식 후보 표 redescription 0 — *selection criteria* perspective 만
- ✅ § 8.2 의 11 family 표 redescription 0 — *관리 perspective* 만
- ✅ Frame Inventory `Notes` variant meta redescription 0 — cross-reference 만
- ✅ 룰 1 (frame 별 CSS X / family 수렴 장치) + 룰 2 (variant 선택은 코드/catalog, AI X) 섹션 머리 명시
- ✅ § 13.2 핵심 원칙 callout — "family 를 억지로 유지하기 위한 장치 X"
- ✅ § 13.5 추가 / 분리 / 폐기 모두 사용자 승인 영역
- ✅ § 13.6 boundary 9 항목 + 5e dedicated 영역 cross-reference

---

## 14. Fallback Behavior — 5e 본격 설계

> ⚠️ **룰 1 — Fallback Behavior 는 Zone Catalog status 라벨 진입 후의 *동작 정책* 이다.**
>
> status 결정 자체는 § 7 의 책임, 본 § 14 는 *진입 후 동작* 만 다룬다.

> ⚠️ **룰 2 — fallback 중 AI 호출은 *zone content 조정 AI* 다.**
>
> 레이아웃 / family / variant / status 결정은 AI 영역이 아니다.

> ⚠️ **룰 3 — 레이아웃 회귀는 Zone Catalog status 변경으로만 트리거한다.**
>
> AI / Jinja2 가 직접 레이아웃을 변경하지 않는다.

### 14.1 Fallback Behavior 의 역할

Fallback Behavior 는 다음을 책임진다 :

1. **Zone Catalog status 라벨 진입 후의 동작 정책** — `fallback_candidate`, `review_required` 가 어떻게 처리되는가
2. **5 차 Fallback 단계의 catalog / runtime 책임** — IMPROVEMENT-REDESIGN.md 의 fallback 흐름 안에서 본 설계가 넘겨야 할 상태와 경계
3. **fallback 중 AI 호출 boundary** — § 10 의 룰을 fallback context 에서 재확인
4. **레이아웃 회귀 트리거** — Phase Z 절대 룰 ("콘텐츠 줄이지 X, 그릇 변경") 의 catalog 단위 메커니즘

받는 입력 :
- Zone Catalog (§ 7.4) 의 6 status 라벨 (특히 `fallback_candidate`, `review_required`)
- IMPROVEMENT-REDESIGN.md 의 5 차 Fallback 흐름

→ Fallback Behavior = **status 진입 후 동작 정책 정의**. status 결정 / AI 호출 자체 / HTML 조립 / 레이아웃 결정은 본 차수 X.

### 14.2 fallback_candidate 진입 후 동작

`fallback_candidate` (§ 7.4 매트릭스의 low confidence cells) 진입 후의 catalog 단위 동작 :

| 동작 | catalog / runtime 책임 |
|---|---|
| zone 단위로 Fallback Behavior 흐름 진입 | catalog 가 status 부여, fallback 단계는 IMPROVEMENT-REDESIGN.md 5 차 따름 (§ 14.4) |
| 다른 family / 다른 frame 후보 검색 | catalog 의 재매칭 룰 (구체 알고리즘은 매칭 시스템 V1~V4 영역) |
| 레이아웃 회귀 트리거 검토 | § 14.6 의 절차 |
| AI 호출 (4 차 fallback 에서) | § 14.5 의 boundary 적용 |

> 🔒 **`fallback_candidate` 는 AI 에게 레이아웃을 묻는 신호가 아니다.**
>
> AI 호출이 fallback 흐름 중 발생하더라도, AI 의 활동 반경은 *zone content 조정* 까지만. 레이아웃 / family / variant / status / 새 frame 결정은 모두 코드 / catalog 영역.

### 14.3 review_required 진입 후 동작

`review_required` (§ 7.4 의 모든 medium confidence cells) 진입 후 :

| 동작 | catalog / runtime 책임 |
|---|---|
| review payload 분리 + marker 부착 | runtime (Jinja2 § 9.4) |
| 사용자 검토 큐 진입 | 파이프라인 / 구현 영역 (catalog 책임 X) |
| 검토 결과 반영 | 사용자 결정 → catalog 가 status 변경 (예 : `matched_zone` 으로 승격 또는 `fallback_candidate` 로 강등) |

→ review 흐름 자체는 파이프라인 / 구현 영역. catalog 는 status 변경 인터페이스만 제공.

### 14.4 5 차 Fallback 단계 (cross-reference)

5 차 Fallback 단계 (1 차~5 차) 흐름은 [`IMPROVEMENT-REDESIGN.md`](../../IMPROVEMENT-REDESIGN.md) 의 fallback 흐름 따른다.

본 문서는 그 흐름 안에서 catalog / runtime 이 *넘겨야 할 상태와 금지 경계* 를 정의한다 :

- 1~3 차 fallback (코드만) — catalog 가 재매칭 / status 재부여
- 4 차 fallback (AI 콘텐츠 조정) — § 14.5 의 AI 호출 boundary 적용
- 5 차 fallback (단일 프리셋 강제) — § 14.6 의 레이아웃 회귀 절차

→ 5 차 단계의 *구체 알고리즘 / 임계값 / 호출 횟수* 는 IMPROVEMENT-REDESIGN.md + 구현 영역 (redescription X).

### 14.5 fallback 중 AI 호출 — § 10 룰 재확인

4 차 fallback (AI 콘텐츠 조정) 에서 AI 호출 발생 시, § 10 의 룰이 *그대로* 적용 :

- ✅ AI 입력 (§ 10.3) : `zone_meta`, `family_meta`, `mdx_excerpt`, `style_hint`, `layout_meta`
- ✅ AI 출력 (§ 10.3) : `zone.content.preview_text`, `zone.content.popup_full`, `zone.content.slot_payload`
- ❌ AI 출력 금지 (§ 10.4) : HTML / class / Jinja2 / family / variant / preset / 새 frame / status

> 🔒 **재확인 — fallback context 에서도 AI 의 호출 단위는 *zone 안 콘텐츠* 만.**
>
> *fallback_candidate 진입* 자체는 AI 호출 트리거가 아니다. AI 호출은 4 차 fallback 의 *콘텐츠 조정* 단계에서만 발생하며, 그때도 § 10 의 룰 (룰 1·2 + § 10.4) + § 9 의 룰 (룰 1·2 + § 9.5) = **5 면 차단** 그대로 작동.

### 14.6 레이아웃 회귀 — Zone Catalog 트리거

Phase Z 절대 룰 *"불일치 시 레이아웃 회귀 — 콘텐츠 줄이지 X, 그릇 변경"* 의 catalog 단위 메커니즘 :

| 단계 | 책임 |
|---|---|
| 회귀 트리거 감지 | catalog (§ 7) — status 분포 모니터링 (예 : 모든 zone 이 `fallback_candidate` / `review_required` 일 때) |
| 다른 layout preset 후보 검색 | catalog (§ 7.2-1 의 4 프리셋 중) |
| preset 변경 → zone 재구성 | catalog 가 새 preset 의 zone 구성 결정 (§ 7.2-2), runtime 이 재조립 (§ 9) |
| AI 호출 (있다면) | § 14.5 의 boundary — *콘텐츠 조정* 까지만, 새 layout 결정 X |

> 🔒 **원칙 — 레이아웃 회귀는 그릇 변경이다.**
>
> 콘텐츠, 텍스트, MDX 원문을 줄이지 않는다.
> AI 가 새 layout 을 만들지 않는다.
> 4 프리셋 `Type A / B / B' / B''` 안에서 다른 그릇을 선택한다.

### 14.7 Fallback Behavior 가 결정하지 않는 것

Skeleton § 4.8 의 "결정 안 함" 확장 + 본 5e 추가 :

- ❌ Zone Catalog status 라벨 *부여 자체* (→ § 7.4)
- ❌ AI 호출 자체 / AI 모델 / 프롬프트 / 호출 빈도 (→ § 4.4 / § 10 + 구현 영역)
- ❌ Jinja2 의 status 별 조립 인터페이스 (→ § 9.4)
- ❌ Family CSS 의 fallback 스타일링 (→ § 8 / § 4.2)
- ❌ token 자체 (→ § 11)
- ❌ asset 자체 (→ § 12)
- ❌ variant 자체 (→ § 13)
- ❌ 5 차 Fallback 의 구체 알고리즘 / 임계값 / 호출 횟수 (→ IMPROVEMENT-REDESIGN.md + 구현 영역)
- ❌ review 흐름의 사용자 검토 UX / 큐 메커니즘 (→ 파이프라인 / 구현 영역)
- ❌ 새 layout preset 추가 / 폐기 — 4 프리셋 안에서만 분기 (자유 디자인 금지)

---

### 5e 차수 자체 점검 (작성 후)

- ✅ Fallback Behavior 영역만 다룸 (status 부여 / AI 호출 자체 / Jinja2 조립 / Family CSS / token / asset / variant 침범 X)
- ✅ § 7.4 6 status 매트릭스 redescription 0 — *진입 후 동작* perspective 만
- ✅ § 9.4 status 별 조립 인터페이스 redescription 0
- ✅ § 10 AI Boundary 룰 redescription 0 — fallback context 의 *재확인* 만
- ✅ IMPROVEMENT-REDESIGN.md 5 차 Fallback 흐름 redescription 0 — § 14.4 짧은 cross-reference + 책임 perspective
- ✅ 룰 1 (status 진입 후 동작) + 룰 2 (AI = zone content 조정) + 룰 3 (레이아웃 회귀 = catalog 트리거) 섹션 머리 명시
- ✅ § 14.2 callout — "`fallback_candidate` 는 AI 에게 레이아웃 묻는 신호 X"
- ✅ § 14.5 callout — fallback context 에서도 AI = zone 콘텐츠만
- ✅ § 14.6 callout — "레이아웃 회귀는 그릇 변경" (Phase Z 절대 룰 prominent)
- ✅ § 14.7 boundary 10 항목 + 모든 dedicated 영역 cross-reference

---

## 15. 통합 검증 — 6 차

> 본 섹션은 1~5e 차수 결과의 *검증* 만 다룬다. 새 설계 없음, 기존 결정의 무결성 + Phase Z-2 진입 준비 판단만.
> 발견된 이슈는 § 15.4, Phase Z-2 진입 준비 판정은 § 15.5.

### 15.1 검증 방법

검증 도구 :

- **grep** — 패턴 기반 무결성 / 표현 위반 탐지 (cross-reference, AI 결정 표현, legacy 재사용 표현 등)
- **의미 검토** — boundary 충돌 / 톤 / 후보 vs 확정 구분 (grep 만으로 잡히지 않는 경계 표현)

검증 항목 (8 개) :

| 항목 | 내용 | 도구 |
|---|---|---|
| 0 | cross-reference 무결성 | grep + 매칭 |
| 1 | 8 책임 영역 boundary 충돌 없음 | 의미 검토 |
| 2 | AI 가 layout / preset / family / variant / HTML 결정 표현 없음 | grep + 의미 |
| 3 | Type A / B / B' / B'' 선택이 코드 / catalog 책임으로 일관 | grep + 의미 |
| 4 | fallback 이 AI layout 요청처럼 읽히지 않음 | 의미 검토 |
| 5 | token / asset / variant *후보* 가 구현 확정처럼 읽히지 않음 | grep + 의미 |
| 6 | legacy `templates/blocks` runtime 재사용처럼 읽히는 표현 없음 | grep + 의미 |
| 7 | Phase Z-2 구현 전 보류 항목이 명확함 | grep + 의미 |

사전 분기 룰 (§ 15.2 결과에 따른 § 15.3 진행 방식) :

| broken 수 | 처리 |
|---|---|
| 0 개 | 그대로 § 15.3 진행 |
| 1~2 개 | 즉시 수정 → § 15.3 진행, § 15.4 에 "non-blocker, 수정 완료" 기록 |
| 3~4 개 | 수정 후 진행, § 15.5 에 "minor drift 발견 / 수정" 명시 |
| 5 개+ | § 15.3 은 현재 상태로만 수행, § 15.5 에 "기준선 흔들림" 명시 |

severity 라벨 (§ 15.4) :

| 라벨 | 의미 |
|---|---|
| `blocker` | Phase Z-2 진입 전 반드시 해결 |
| `non-blocker` | Phase Z-2 진입 가능, 후속 정리 |

### 15.2 cross-reference 무결성

문서 내 § 패턴 매칭 결과 :

- **참조 추출** — § 4.1 ~ 4.8, § 7 / 7.1 / 7.2-1 / 7.2-2 / 7.3 / 7.4 / 7.5, § 8 ~ 14 의 모든 `N.M` 패턴 (50+ 회 인용)
- **실제 섹션 매칭** — 모든 인용이 실제 섹션 (`##` / `###` / `####`) 으로 해석됨. § 7.2-1 / 7.2-2 (sub-subsection) 도 실제 `####` 헤딩 존재 (line 214 / 229)
- **broken 수** — **0 개**

→ § 15.1 분기 룰의 "0 개" 케이스. 그대로 § 15.3 진행.

### 15.3 7 항목 검증 결과

| 항목 | 결과 | 근거 (대표 line) |
|---|---|---|
| 1. 8 영역 boundary 충돌 없음 | ✅ PASS | 각 영역의 "X 가 결정하지 않는 것" 섹션 (§ 7.5 / 8.6 / 9.6 / 10.6 / 11.6 / 12.6 / 13.6 / 14.7) 이 다른 영역 dedicated section 으로 cross-reference. 침범 표현 0. |
| 2. AI 가 layout / preset / family / variant / HTML 결정 표현 없음 | ✅ PASS | line 47, 99, 552, 587, 617, 659, 1049, 1111, 1147 — 모두 *금지* 또는 *Phase R' 회귀 방지* 맥락. 결정 표현 0. |
| 3. Type A / B / B' / B'' = 코드 / catalog 책임 일관 | ✅ PASS | line 47 ("코드만"), 196 ("catalog 가 결정"), 225, 480, 587, 617, 1158, 1181 — 모두 catalog 또는 "AI X" 로 일관. |
| 4. fallback ≠ AI layout 요청 | ✅ PASS | line 291, 1111 (🔒), 1147 (🔒), 1149, 1162 (🔒) — 명시적 callout. fallback_candidate 진입 ≠ AI 호출 트리거 명시. |
| 5. token / asset / variant *후보* ≠ 구현 확정 | ✅ PASS | "후보" 59 회 사용, 모두 working name / 후보 상태. line 737 ("아직 확정 X"), 785, 904, 993, 1038, 1066 — "Phase Z-2 구현 진입 시 사용자 승인" 패턴. |
| 6. legacy `templates/blocks` runtime 재사용 표현 없음 | ✅ PASS | line 48 ("legacy blocks runtime reuse X ... 참고만"), 159 / 162 / 433 — 삭제 보류 + runtime 재사용 X 명시. |
| 7. Phase Z-2 보류 항목 명확 | ✅ PASS | line 3, 20, 158, 181, 737, 785, 904 + "(구현 영역)" 태그 17 회 — Phase Z-2 입력 문서 위치 명확, 보류 항목 sweep 가능. |

→ **7 항목 모두 PASS**.

### 15.4 발견된 이슈

| 이슈 | severity | 처리 |
|---|---|---|
| (없음) | — | — |

→ blocker / non-blocker 모두 0 건. 검증 결과 깨끗.

### 15.5 Phase Z-2 진입 준비 상태

| 항목 | 상태 |
|---|---|
| 1~5e 차수 본격 설계 | ✅ 완료 |
| cross-reference 무결성 | ✅ broken 0 (§ 15.2) |
| 7 항목 boundary / 회귀 방지 | ✅ 7/7 PASS (§ 15.3) |
| 발견된 issue | ✅ 0 건 (§ 15.4) |
| Phase Z-2 입력 문서 위치 | ✅ 명확 (§ 1 / § 6) |

**판정** : Phase Z-2 진입 *기준선 (설계 baseline)* 준비됨.

> 🔒 **Phase Z-2 진입 준비는 *구현 시작 승인이 아니다*. 구현 착수는 별도 사용자 승인 후 진행한다.**

---

## 16. Phase Z-2 MVP-1 scaffold 허용 규칙

> 본 섹션은 § 15 통합 검증 완료 후 추가된 *구현 규칙*. Phase Z-2 MVP-1 이 HTML 출력을 위해 필요한 *실행 껍데기 (scaffold)* 의 허용 범위 + 종료 조건 명시.
> *예외* 가 아닌 *원칙 안의 허용 규칙* — legacy 재사용 X / 정식 family 확정 X 는 그대로 유지.

### 16.1 배경 — 왜 필요한가

Phase Z-2 MVP-1 은 :
- legacy `templates/blocks/structures/*` runtime 재사용 X (§ 1, line 48)
- 신규 token / asset / variant / Family CSS *확정* 보류 (§ 11.5 / 12.5 / 13.5)

→ 실제 HTML 렌더링을 위해서는 *얇은 실행 껍데기* 가 필요. 이를 *원칙 안의 허용 규칙* 으로 정의한다.

### 16.2 핵심 경계

| 항목 | 상태 |
|---|---|
| legacy runtime 재사용 | ❌ 금지 (기존 룰 유지) |
| 정식 Family CSS *확정* | ❌ 보류 (§ 11.5 / 12.5 / 13.5 유지) |
| MVP 출력용 scaffold | ✅ 허용 (본 § 16 의 룰 내) |

### 16.3 scaffold 허용 룰

| 룰 | 내용 |
|---|---|
| 위치 | `templates/phase_z2/` (별도 디렉토리. 기존 `templates/blocks/` 와 분리) |
| 마커 | 각 scaffold 파일 상단에 1 줄 주석 필수 :<br>`<!-- Phase Z-2 MVP-1 scaffold — MVP-2 이후 정식 Family CSS partial 로 대체. legacy structures/* 는 stylization 참고만. -->` |
| 토큰 | 기존 token 만 참조. 신규 token 추가 X |
| 자산 | 기존 asset 만. 신규 asset 추가 X |
| variant | § 8.2 의 11 family 후보 안에서만. 신규 variant 추가 X |
| legacy 파일 import | ❌ 금지. legacy `templates/blocks/structures/*.html` 는 *stylization 참고만*, 직접 import / include / extend X |
| 시각 디자인 도출 | frame 메타 + Figma 좌표 + 기존 token 으로 *수학적 도출*. legacy 시각 모방 우회 금지 |

### 16.4 종료 조건

scaffold 의 수명 = *MVP-1 ~ MVP-2 직전* :

- **MVP-1** : scaffold 로 HTML 출력
- **MVP-2** : 정식 Family CSS partial 로 *대체*. `templates/phase_z2/` 디렉토리 삭제 또는 정식 위치로 이동
- **종료 조건** : MVP-2 entry 시 본 § 16 의 scaffold 룰 *무효화*

> 🔒 **scaffold 는 *실행 껍데기* 이지 *디자인 확정* 이 아니다.** MVP-2 에서 정식 Family CSS partial 로 대체하지 않으면 scaffold 가 *영구화* 되는 위험. MVP-2 진입 시 — *§ 16 무효화 + scaffold 삭제 + Family CSS 확정* = **3 동시 조건**.

### 16.5 cross-reference

- § 1 line 48 — legacy runtime reuse X (유지)
- § 8 — Family CSS 정식 확정 보류 (유지)
- § 11.5 / 12.5 / 13.5 — 신규 token / asset / variant 보류 (유지)
- § 15.5 — Phase Z-2 진입 준비 상태 (본 § 16 은 진입 후 *구현 시* 적용)
- § 17 — MVP-1 결과 (mvp1_test5: visual fidelity FAIL) 에 따른 *방향 전환*. scaffold polish 중단, frame-derived partial promotion 으로 진화

---

## 17. Frame-derived Partial Promotion — MVP-1.5+

> 본 섹션은 § 16 *scaffold 허용 룰* 의 **방향 전환**. MVP-1 progression (mvp1_test2 ~ mvp1_test5) 에서 발견된 사실 — *scaffold 가 V4 매칭한 frame 의 실제 변환물을 대체하지 못함* — 에 따른 진화. scaffold polish 는 중단, frame-derived partial promotion 으로 전환.

### 17.1 배경 — MVP-1 progression (교훈 보존)

| run_id | 결과 | 교훈 |
|---|---|---|
| mvp1_test2 | data chain 동작, raw dump 발견 | mapper output 이 slot 모양이어야 함 (raw section dump X) |
| mvp1_test3 | data PASS, visual FAIL (overflow + slide-base contract 미충족) | "기술 chain PASS ≠ MVP PASS". 시각 게이트 필수 |
| mvp1_test4 | overflow check PASS, 내부 clipping 미검출 | `overflow:hidden` 은 안전장치. 진짜 게이트는 Selenium *내부 clipping* 검출 |
| mvp1_test5 | runtime PASS, **visual fidelity FAIL** | **scaffold polish 한계** — V4 가 고른 frame 의 *실제 변환물* 을 runtime 이 안 쓰면 visual fidelity 못 나옴 |

→ **방향 전환** : scaffold polish 중단. **frame-derived partial promotion** 으로 진화.

### 17.2 § 16 scaffold vs § 17 promotion

| 항목 | § 16 scaffold | § 17 frame-derived partial |
|---|---|---|
| 출처 | 코드에서 직접 작성 (token + 색 추정) | `figma_to_html_agent/blocks/{id}/index.html` (1:1 Figma 변환물) |
| 시각 fidelity | 근사 | Figma 와 1:1 (정확한 색 / 비율 / 구조) |
| Templating | `{{ slot_payload.* }}` | `{{ slot_payload.* }}` (동일) |
| 위치 | `templates/phase_z2/frames/` | `templates/phase_z2/families/` |
| 사용 범위 | *frame 미변환 시 임시* — 변환 완료 시 즉시 § 17 partial 로 대체 | *변환 완료된 frame* 에 대한 정식 runtime partial |

### 17.3 Promotion 규칙

| 룰 | 내용 |
|---|---|
| Source | `figma_to_html_agent/blocks/{frame_id}/index.html` (1:1 변환물 *필수*) |
| Target | `templates/phase_z2/families/{template_id}.html` |
| 변환 방식 | **templating** — index.html 의 *구조 / CSS / 색 / 비율* 유지, 텍스트만 `{{ slot_payload.* }}` 로 치환 |
| 단순 복사 | ❌ 금지 — runtime 에서 V4 매칭한 콘텐츠 못 받음 |
| 1:1 변환물 없는 frame | 변환 먼저 (figma_to_html_agent 영역, *별도 작업 + 사용자 승인 필수*) |
| 마커 | partial 파일 상단에 :<br>`<!-- Phase Z-2 frame-derived partial — derived from figma_to_html_agent/blocks/{id}/index.html. MVP-2 family CSS 확정 시 대체. -->` |

### 17.4 § 16 scaffold 와의 관계

- § 16 scaffold = *frame 미변환 시 임시 처리* 로만 허용 (변환물 없는 frame)
- 변환 완료 시 즉시 § 17 partial 로 대체. scaffold 는 폐기
- legacy `templates/blocks/structures/` runtime 재사용 X 는 **그대로 유지** (§ 1 line 48)

### 17.5 종료 조건

partial 의 수명 = *MVP-1.5 ~ MVP-2 직전*. MVP-2 에서 정식 Family CSS 확정 시 :
- partial 위치 (`templates/phase_z2/families/`) → 정식 family CSS 위치로 이동 / 통합
- § 17 룰 무효화

> 🔒 **partial = *frame-derived 정확한 산출물* 이지만 *family CSS 확정* 은 아니다.** MVP-2 에서 정식 family 로 통합하지 않으면 partial 이 *영구화* 되는 위험. § 16 scaffold 와 동일한 lifecycle 관리 필요.

### 17.6 cross-reference

- § 16 — scaffold 허용 룰 (MVP-1 한정, 미변환 frame 임시 처리)
- § 8 — Family CSS 정식 확정 (MVP-2 종료 시점)
- § 11.5 / 12.5 / 13.5 — 신규 token / asset / variant 보류 (유지)

---