# 변환 완료 블록 도서관

> 변환된 모든 블록의 1줄 요약 + 변형 가능 축. **새 변환 시작 전 (PROCESS.md STEP 0-A) 이 파일을 먼저 읽어** 지난 패턴과 비교한다.
>
> 패턴이 **2번째** 등장하는 순간 → `templates_staging/` 에 Jinja2 추출. 그 다음 사용자가 검수 후 design_agent 본체로 프로모션.

---

## 사용 방법

```
새 프레임 변환 시작:
  STEP 0-A. 이 파일 읽기 (필수)
       ↓
  STEP 0-C. 첫 metadata/screenshot 후 비교
       ↓
  비슷한 구조 발견 → 두 번째 → templates_staging/ 로 Jinja2 추출
  비슷한 구조 없음 → 일반 변환 → 새 행 추가
```

## 컬럼 의미

| 컬럼 | 의미 |
|------|------|
| slug | block-tests/{slug}.html 파일명 |
| frame | Figma 노드 ID + 이름 |
| size | 원본 W×H px |
| pattern | 구조적 패턴 (사이클/비교/카드/표/...) |
| 변형 축 | 템플릿화 시 파라미터가 될 것들 (1줄) |
| 상태 | static / staged / promoted |
| date | 변환 날짜 |

**상태 의미:**
- `static`: block-tests/ 정적 변환물만 존재 (Stage 1)
- `staged`: templates_staging/ 에 Jinja2 템플릿 작성됨 (Stage 2, 사용자 검수 대기)
- `promoted`: 사용자가 design_agent/templates/ 본체로 이전 + catalog.yaml 등록 완료

---

## 변환 완료 (현행 방법론)

| slug | frame | size | pattern | 상태 | date |
|------|-------|------|---------|------|------|
| [bim-goals-3circles](block-tests/bim-goals-3circles.html) | 66:310 / Frame 1171281211 | 2062×957 | cycle-3way-intersect | **promoted** → [block](../../templates/blocks/new/cycle-3way-intersect.html) + [catalog](../../templates/catalog.yaml) | 2026-04-13 |
| [bim-3roles-cards](block-tests/bim-3roles-cards.html) | 45:16 / Frame 1171281191 | 2601×1927 | cards-3col-persona | **promoted** → [block](../../templates/blocks/new/cards-3col-persona.html) + [catalog](../../templates/catalog.yaml) | 2026-04-13 |
| [bim-future-statement](block-tests/bim-future-statement.html) | 51:170 / Frame 1171281207 | 3547×163 | statement-pill-highlight | **promoted** → [block](../../templates/blocks/new/statement-pill-highlight.html) + [catalog](../../templates/catalog.yaml) | 2026-04-13 |
| [bim-vs-dx-table](block-tests/bim-vs-dx-table.html) | 45:20 / Frame 1171281195 | 1868×1908 | compare-vs-rows | **promoted** → [block](../../templates/blocks/new/compare-vs-rows.html) + [catalog](../../templates/catalog.yaml) | 2026-04-13 |
| [bim-issues-quadrant](block-tests/bim-issues-quadrant.html) | 45:18 / Frame 1171281193 | 2226×1766 | quadrant-2x2-issues | **promoted** → [block](../../templates/blocks/new/quadrant-2x2-issues.html) + [catalog](../../templates/catalog.yaml) | 2026-04-13 |
| [bim-issues-paired](block-tests/bim-issues-paired.html) | 45:19 / Frame 1171281194 | 1857×1326 | issues-paired-rows | **promoted** → [block](../../templates/blocks/new/issues-paired-rows.html) + [catalog](../../templates/catalog.yaml) | 2026-04-13 |
| [bim-info-products](block-tests/bim-info-products.html) | 45:5 / Frame 1171281180 | 1153×592 | stacked-arrow-list | **promoted** → [block](../../templates/blocks/new/stacked-arrow-list.html) + [catalog](../../templates/catalog.yaml) | 2026-04-13 |
| [bim-sw-overview](block-tests/bim-sw-overview.html) | 45:27 / Frame 1171281202 | 1863×834 | split-panel-numbered | **promoted** → [block](../../templates/blocks/new/split-panel-numbered.html) + [catalog](../../templates/catalog.yaml) | 2026-04-13 |

### 변형 축 + 슬롯 옵션 (각 변환물 상세)

#### bim-goals-3circles
```
circles[3] (required)
  ├─ label (required)
  ├─ gradient_from / gradient_to (required)
  └─ accents[N=0~3] (optional)
       └─ char (한자/문자) + color
side_labels[N=0~12] (optional)  ← 라벨 없는 mdx도 가능
arcs[3] (optional, 곡선 PNG)
deco_gradient (optional)
bg_texture (optional)
```
Sub-patterns: 없음 (특수 패턴, 재사용성 낮음)

#### bim-3roles-cards
```
columns[N=2~4] (required)
  ├─ role_label (required, 2-line: ["역할", "목표"])
  ├─ role_color (required)
  ├─ badge (required)
  │   ├─ outer_image (required)
  │   └─ inner_image (required)
  ├─ bg_image (required)
  ├─ overlay_image (required)
  ├─ bullet_items[N=1~12] (required, 한 줄당 1개 sentence)
  └─ bottom_photo (optional)  ← 사진 없는 mdx도 이 블록 매칭 가능
```
Sub-patterns: **bullet-list-with-marker (R13)** — 각 컬럼의 bullet_items 영역

---

## 패턴 카탈로그 (전체 블록 단위)

| pattern_id | 설명 | 등장 횟수 | 변환물 | 템플릿화 |
|-----------|------|---------|--------|---------|
| cycle-3way-intersect | 3개 큰 원이 교차하며 사이드 라벨 + 한자 액센트 | 1 | bim-goals-3circles | **✓ templates_staging/cycle-3way-intersect.html.j2** (1 example 검증) |
| cards-3col-persona | N stakeholder 세로 카드 (BG 사진 + 오버레이 + 원형 뱃지 + bullet list + optional 하단 사진) | 1 | bim-3roles-cards | **✓ templates_staging/cards-3col-persona.html.j2** (2 examples 검증: 사진 있음/없음) |
| statement-pill-highlight | 단일 line 메시지 banner. pill 모양 + optional bg image + inline highlighted span | 1 | bim-future-statement | **✓ templates_staging/statement-pill-highlight.html.j2** |
| compare-vs-rows | N개 카테고리 비교 표. 각 행 = 좌(A) \| 중앙(라벨) \| 우(B). + 헤더 + 메인 pill + optional 결론 박스 | 1 | bim-vs-dx-table | **✓ templates_staging/compare-vs-rows.html.j2** |
| quadrant-2x2-issues | 2×2 카테고리 그리드 (issue/diagnosis). 각 카테고리에 N개의 (red headline + bullet body). + optional 가운데 인용구 원 | 1 | bim-issues-quadrant | **✓ templates_staging/quadrant-2x2-issues.html.j2** |
| issues-paired-rows | N개 행, 각 행 = 좌/우 이슈 (라벨 pill + 본문), 가운데 구분선, pill 위치 교차 | 1 | bim-issues-paired | **✓ templates_staging/issues-paired-rows.html.j2** |
| stacked-arrow-list | N개 항목 계단식 리스트 (rounded pill + 색상 border + 화살표 마커 + optional 좌측 arc 장식) | 1 | bim-info-products | **✓ templates_staging/stacked-arrow-list.html.j2** |
| split-panel-numbered | 좌: 카테고리별 리스트 (BG + 헤더) / 우: 번호 badge + 설명 N개 | 1 | bim-sw-overview | **✓ templates_staging/split-panel-numbered.html.j2** |

## Sub-pattern 카탈로그 (atomic 재사용 단위)

블록 안에 들어있는 작은 재사용 가능 패턴. 여러 다른 블록에서 반복 등장 가능.

| sub_pattern_id | RULES.md | 설명 | 등장 횟수 | 발견 위치 |
|---------------|---------|------|---------|---------|
| bullet-list-with-marker | **R13** | 각 텍스트 앞에 장식 마커(체크박스/점/화살표/숫자/PNG) + flex pair 구조 | 1 | cards-3col-persona의 컬럼 본문 |
| (다른 sub-pattern은 발견 시 추가) | | | | |

**Sub-pattern 등록 규칙:**
- 1번째 발견: blocks_index.md에만 메모 (여기 표에 추가)
- 2번째 발견: RULES.md에 R번호 부여하여 정식 등록 + 두 변환물 모두 동일 구조 사용 확인

---

## templates_staging 대기열

> 2번째 등장한 패턴이 여기에 들어옴. 사용자 검수 후 design_agent 본체로 프로모션.

(아직 없음)

---

## 디자인 인사이트 (변환 중 발견된 원칙)

> 매 변환에서 발견되는 재사용 가능한 디자인 원칙. RULES.md에 박힌 기술 규칙과 별개로, "이런 상황에서는 이렇게 접근한다" 류의 사고 원칙.

### I-1. 마커 + 텍스트 = 시맨틱 list (R13 sub-pattern)

**상황:** Figma에서 체크박스 PNG / 점 / 화살표 / 숫자 등이 텍스트 앞에 있을 때.

**잘못된 접근 (피해야 함):**
- Figma의 평면 레이어 그대로 → 마커들을 별도 absolute 요소로 흩뿌림
- 텍스트와 마커가 분리된 상태로 동기화 시도
- 각 텍스트의 wrap 여부를 마커 위치에 반영 시도 (cascade 깨짐)

**올바른 접근:**
- 마커 + 텍스트 = **하나의 시맨틱 list item** 으로 묶음 (`.bullet-row` 또는 `<li>`)
- flex row 구조: icon + text
- 마커는 CSS marker 역할 (장식, 텍스트와 align)
- list 컨테이너는 `flex-direction: column`
- 텍스트 길이가 row 높이 결정 → 다음 row 자동 시프트
- **모든 픽셀 위치 절대 배치 금지**

**적용:** RULES.md R13 참조.

### I-2. 평행 컬럼은 동일 top/bottom

**상황:** 3개 이상의 평행 컬럼 (e.g., 발주자/시공자/설계자 카드)

**원칙:** 모든 컬럼이 **동일한 top + 동일한 height + 동일한 bottom**. 컬럼별 콘텐츠 양에 따라 **내부 spacing이 자동 분배**되도록.

**구현:**
- 컨테이너 height = 가장 긴 컬럼의 자연 콘텐츠 합 (or zone 입력)
- `justify-content: space-between` 으로 내부 균등 분포
- 적은 콘텐츠 컬럼은 더 넓은 spacing
- 많은 콘텐츠 컬럼은 더 좁은 spacing

**적용:** cards-3col-persona (1171281191)

### I-3. Optional 슬롯으로 콘텐츠 변형 흡수

**상황:** 같은 블록을 사진 있는/없는 mdx 모두에 적용해야 함

**원칙:** 슬롯에 `required: false` 표시. 템플릿 단계에서 `{% if slot %}...{% endif %}`로 처리. 블록 height는 auto 또는 max(used slots).

**핵심:** 1:1 단계의 변환물에 모든 슬롯이 채워져 있다고 해서 "이 블록은 필수" 라고 해석하면 안 됨. 슬롯은 기본 optional 가정.

### I-5. 절대 "쉬운 방식으로 전면 재작성" 하지 말 것

**상황:** 80점짜리 결과물에서 2가지 문제를 고쳐야 할 때.

**잘못된 접근 (실제 발생):**
- 기존 absolute 구조를 flex/grid로 **전면 재작성** → pill 크기/위치/비율 전부 망가짐 → 65점으로 하락
- "flex가 텍스트 겹침을 자동으로 해결할 것" 이라는 기대로 구조를 갈아엎음
- 결과: 기존에 맞던 것(pill 크기, 박스 border 위 걸침, 이미지 비율)이 전부 깨짐

**올바른 접근:**
- **기존 구조 유지 + 문제 2가지만 정확히 수정**
- 구조를 바꾸면 이전에 맞춘 수십 가지가 다시 깨짐
- 보완이 안 되면 **그 방식 자체를 오답노트로 두고 다른 방식으로 접근**
- 점점 나빠지면 **즉시 멈추고 마지막 OK 상태로 복원**

**원칙:**
- 80점 → 90점을 만들 때, 20%를 고치려다 80%를 깨뜨리지 말 것
- "조금 보완하려고 가장 쉬운 방식(전면 재작성)"은 **절대 금지**
- 구조 변경이 필요하면 **사전에 영향 범위를 분석**하고 사용자 확인 후 진행

**적용:** bim-issues-paired.html — absolute(80점) → flex(65점) 하락 사건

### I-6. 이미지 프레임 배치 — overflow:hidden으로 부분 표시 (R16)

**상황:** 원본 이미지에 양 끝 다 디자인 요소가 있고, Figma에서 한쪽만 보여주는 경우.

**핵심:** 이미지를 프레임보다 크게 넣고, overflow:hidden으로 한쪽을 숨김. **crop이 아니라 위치 조절.**

**잘못된 접근:**
- `width: 100%; object-fit: fill` → 이미지 찌그러져 양쪽 다 보임
- `scaleX(-1)` 임의 추가 → Figma에 없는 변환
- Figma 값 무시하고 추측으로 CSS 작성

**올바른 접근:**
- Figma가 준 `left`, `width` 값 **그대로** 적용
- `overflow: hidden`이 프레임 밖 부분을 숨김
- rotate(180) 적용된 하단 요소는 **이미지 배치를 상단과 반대로**

**적용:** RULES.md R16 참조. issues-paired-rows (1171281194)에서 발견.

### I-4. 1:1 단계의 임시 보정 vs 영구 결정

**임시 보정 (템플릿화 시 제거):**
- `letter-spacing` 측정값 → 자연 wrap에 맡김
- 명시적 `<br>` → 자연 wrap에 맡김
- 수동 `class="compact"` → 텍스트 길이 자동 판정
- 고정 `top/width/height` px → CSS 변수 + zone 기반

**영구 결정 (그대로 유지):**
- flex 구조, 시맨틱 markup, CSS 변수 기반 계산
- justify-content 분배 전략
- icon margin-top calc 공식

**구분 표시:** 임시 보정은 HTML 코멘트로 `<!-- TEMP: 1:1 fidelity, 템플릿화 시 제거 -->` 명시.

---

## 발견된 공통 자산 (block-tests/assets/shared/)

해시 파일명을 키로 한 dedup 캐시. 여러 프레임에서 같은 자산이 등장하면 자동 재사용.

| hash | 첫 출처 프레임 | 의미 라벨 |
|------|-------------|---------|
| 4a17cd1d... | 1171281191 | column_bg_texture (3컬럼 BG, 동일 src ×3) |
| e837f870... | 1171281191 | overlay_left (좌 컬럼 컬러 오버레이) |
| 755384bd... | 1171281191 | overlay_mid |
| 5577732e... | 1171281191 | overlay_right |
| 77f31997... | 1171281191 | badge_outer_owner |
| e64c967d... | 1171281191 | badge_inner_owner |
| 1550ec75... | 1171281191 | badge_outer_builder |
| 85beaf9d... | 1171281191 | badge_inner_builder |
| 9ac089fa... | 1171281191 | badge_outer_designer |
| 4b534ccf... | 1171281191 | badge_inner_designer |
| 6896d5c2... | 1171281191 | checkbox_icon (재사용 ×20) |
| d2c070f2... | 1171281191 | bottom_photo_left |
| 2a6a58e7... | 1171281191 | bottom_photo_mid |
| 39113493... | 1171281191 | bottom_photo_right |

(1171281211 자산은 legacy 위치 `block-tests/assets/frame_1171281211/` 에 있음. shared/ 는 1171281191 부터 사용 시작)

---

## 🗂 구 방법론 변환물 (legacy, 참조 금지)

> 아래 변환물은 **현행 방법론(R8/R9) 도입 이전**의 결과물입니다. 패턴이 비슷해 보여도 **레퍼런스로 베끼지 마십시오**. 동일 패턴 재등장 시에는 신규 방법론으로 처음부터 변환하여 위 "변환 완료" 섹션에 등록합니다.

| slug | frame | pattern | 위반 사항 | 처리 |
|------|-------|---------|--------|------|
| [prerequisites-3col](block-tests/prerequisites-3col.html) | 45:15 / Frame 1171281190 | 3-column-comparison (legacy) | R8 위반 (수동 ×0.60290 곱셈, transform: scale 미사용), R9 미적용 (gradient text만, div 패턴 없음) | 재변환 권장. 동일 패턴 등장 시 신규 변환물 작성 후 이 행은 archive 처리. |