# 변환 완료 블록 도서관

> 변환된 모든 블록의 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-process-products-2col](blocks/1171281210/index.html) | 181:2519 / Frame 1171281210 (file 9S6LsQyO6zlRxtiqZccOUM, page 29:373) | 3848×1388 | process-products-2col-banner-top | static | 2026-04-28 |
| [overseas-bim-numbered-list](blocks/1171281174/index.html) | 182:2810 / Frame 1171281174 (file 9S6LsQyO6zlRxtiqZccOUM, page 29:373) | 1728×657 | scene-with-numbered-list-4 | static | 2026-04-29 |
| [info-mgmt-what-how-when](blocks/1171281179/index.html) | 182:3024 / Frame 1171281179 (file 9S6LsQyO6zlRxtiqZccOUM, page 29:373) | 1207×861 | framework-3section-label-body | static | 2026-04-29 |
| [sw-reality-3emphasis](blocks/1171281209/index.html) | 145:8523 / Frame 1171281209 (file 9S6LsQyO6zlRxtiqZccOUM, page 29:373) | 1697×582 | bordered-3paragraphs-with-3emphasis-labels | static | 2026-04-29 |
| [bim-model-info-3category](blocks/1171281182/index.html) | 182:2523 / Frame 1171281182 (file 9S6LsQyO6zlRxtiqZccOUM, page 29:373) | 1248×1066 | cards-3-category-with-bim-process-diagram | static | 2026-04-30 |
| [dx-sw-3perspective-cards](blocks/1171281198/index.html) | 182:2766 / Frame 1171281198 (file 9S6LsQyO6zlRxtiqZccOUM, page 29:373) | 2734×910 | dx-banner-with-3perspective-cards | static | 2026-04-30 |

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

#### 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** |
| process-products-2col-banner-top | 좌(Process)/우(Products) 2 컬럼 + 상단 둥근 헤더 배너 (좌측 180° rotate, 둥근 모서리가 가운데로 mirror). 각 컬럼에 3 섹션. 좌측 첫 섹션은 AS-IS/TO-BE 좌우 비교 + 가운데 화살표 PNG | 1 | bim-process-products-2col | (1번째 등장, staging 미작성 — 사용자 검토 후 결정) |
| scene-with-numbered-list-4 | 좌(헤더 pill + scene 이미지 + 글로브 오버레이) / 우(수직 화살표 체인 + 번호 배지 N개 + 텍스트 버블). cardinality 4 고정 | 1 | overseas-bim-numbered-list | (1번째 등장, staging 미작성 — 사용자 검토 후 결정) |
| framework-3section-label-body | 헤더 (icon + 다중 폰트 그라디언트 텍스트) + 3 행. 각 행 = 좌 브라운 라벨 (rounded-right, 한글+영문 yellow) / 우 흰 카드 (border, 우측 장식 이미지) + 본문 불릿 (35px + 40px Bold #CC5200 강조) | 1 | info-mgmt-what-how-when | (1번째 등장, staging 미작성 — 사용자 검토 후 결정) |
| bordered-3paragraphs-with-3emphasis-labels | 외곽 두꺼운 빨간 테두리 (10px #9C0E0E, rounded 20) + 상단 타이틀 pill (외곽 위 걸침) + 우측 핑크→흰 그라디언트 BG. 좌 본문 N단 (▶ 화살표 불릿 + 30px text + 30px Bold #CC5200 인라인 강조) / 우 강조 라벨 N개 (60px Black, bg-clip-text gradient red→#711E1E) | 1 | sw-reality-3emphasis | (1번째 등장, staging 미작성 — 사용자 검토 후 결정) |
| cards-3-category-with-bim-process-diagram | 1171281179의 framework-3section-label-body 패턴 + 하단 BIM 모델/공사 Process 연계 원형 다이어그램 (좌 BIM wireframe 원, 중앙 X-shape decoration, 우 paper/document 원, 모두 PNG 합성). 라벨 텍스트는 45px Bold gradient bg-clip-text (#276853 → #B65320) | 1 | bim-model-info-3category | (1번째 등장, staging 미작성 — 사용자 검토 후 결정) |
| dx-banner-with-3perspective-cards | 상단 다크 그린 배너 (인라인 #90FA33 강조 텍스트 90px Bold) + 좌측 DX를 위한 S/W 원형 (PNG, 텍스트 baked-in) + 우측 3 카드 (orange/green 톤, 헤더 BG + 외곽 frame + bottom decor 모두 PNG, 본문 37px Medium + ▶ 화살표 9개) | 1 | dx-sw-3perspective-cards | (1번째 등장, staging 미작성 — 사용자 검토 후 결정) |

## 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번호 부여하여 정식 등록 + 두 변환물 모두 동일 구조 사용 확인

---

## 프로모션 완료

> 8개 블록 모두 `templates/blocks/new/`로 프로모션 완료 (2026-04-13).
> 이미지 33개 `templates/blocks/svg/`로 통합. catalog.yaml 등록 완료.

---

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

> 매 변환에서 발견되는 재사용 가능한 디자인 원칙. 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, 템플릿화 시 제거 -->` 명시.

### I-7. 콘텐츠 주도형 블록 구조 (R17/R18/R19)

**상황:** 블록의 텍스트 분량이 바뀔 때 (블릿 추가/삭제, 문장 길이 변화) 레이아웃이 유연하게 대응해야 함.

**잘못된 접근 (실제 발생):**
- 모든 요소를 absolute + 고정 top/left로 배치 → 텍스트 겹침
- overflow:hidden으로 겹침 숨기기 → 텍스트 잘림 (더 나쁨)
- 고정 height로 제한 → 빈 공간 또는 잘림

**올바른 접근 (1171281194에서 검증):**
1. `.inner`는 `zoom: S` (transform:scale 대신, R19)
2. section.row들은 flex column 컨테이너 안에서 자연 flow (R17)
3. row 내부: pill-area(flex:none) + body-area(flex:1) 구조
4. pill의 crop variant와 label position은 분리 (R18)
5. pill-area는 margin:-border_width로 row border 외곽까지 확장
6. 장식(두루마리, 배경)은 콘텐츠를 따름 — 텍스트가 늘면 같이 내려감

**seam-based alignment (진행 중):**
- pill 이미지의 곡선→직선 전환점(seam)을 측정
- 라벨은 seam 기준 flat area 안에 배치
- 현재: designer-tuned fallback / 장기: computed anchor
- 메타데이터: `blocks/{id}/pill_seam_meta.md`에 기록

**적용:** 1171281194 (issues-paired-rows) — 첫 적용, 2단계 완성

---

## 기존 블록 구조 개선 현황

> R17/R18/R19 적용 상태. "absolute"는 기존 고정 좌표 방식, "flex"는 콘텐츠 주도형.

| 프레임 | 패턴 | 현재 구조 | 필요 작업 |
|--------|------|----------|----------|
| 1171281189 | cycle-3way-intersect | absolute | R17 적용 (원형 배치라 flex 전환 범위 검토 필요) |
| 1171281190 | prerequisites-3col | absolute | R17 적용 (3열 내부 flow화), R19 zoom 전환 |
| 1171281191 | cards-3col-persona | absolute | R17 적용 (bullet list는 이미 R13 flex), R19 |
| 1171281193 | quadrant-2x2-issues | absolute | R17 적용 (사분면 내부 flow화), bullet inside 적용 |
| 1171281195 | compare-vs-rows | absolute | R17 적용 (12행 비교표 flow화), bullet inside 적용 |
| **1171281194** | **issues-paired-rows** | **flex 2단계 ✓** | **완료 (R17/R18/R19 적용)** |
| 1171281202 | split-panel-numbered | absolute | R17 적용, z-index 수정 완료, R19 |
| 1171281180 | stacked-arrow-list | absolute | R17 적용 (pill 행 flow화), R19 |
| 1171281204 | compare-table-3col | absolute | R17 적용 (표 행 flow화), R19 |
| 1171281203 | compare-table-2col | absolute | R17 적용 (표 행 flow화), R19 |

---

## 발견된 공통 자산 (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 | prerequisites-3col | **promoted** → [block](../../templates/blocks/new/prerequisites-3col.html) + [catalog](../../templates/catalog.yaml) | 2026-04-13. legacy HTML 기반 블록화. 순수 CSS (이미지 없음). |