C.E.L_Slide_test2/figma_to_html_agent/blocks_index.md

변환 완료 블록 도서관

변환된 모든 블록의 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	66:310 / Frame 1171281211	2062×957	cycle-3way-intersect	promoted → block + catalog	2026-04-13
bim-3roles-cards	45:16 / Frame 1171281191	2601×1927	cards-3col-persona	promoted → block + catalog	2026-04-13
bim-future-statement	51:170 / Frame 1171281207	3547×163	statement-pill-highlight	promoted → block + catalog	2026-04-13
bim-vs-dx-table	45:20 / Frame 1171281195	1868×1908	compare-vs-rows	promoted → block + catalog	2026-04-13
bim-issues-quadrant	45:18 / Frame 1171281193	2226×1766	quadrant-2x2-issues	promoted → block + catalog	2026-04-13
bim-issues-paired	45:19 / Frame 1171281194	1857×1326	issues-paired-rows	promoted → block + catalog	2026-04-13
bim-info-products	45:5 / Frame 1171281180	1153×592	stacked-arrow-list	promoted → block + catalog	2026-04-13
bim-sw-overview	45:27 / Frame 1171281202	1863×834	split-panel-numbered	promoted → block + catalog	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	45:15 / Frame 1171281190	3-column-comparison (legacy)	R8 위반 (수동 ×0.60290 곱셈, transform: scale 미사용), R9 미적용 (gradient text만, div 패턴 없음)	재변환 권장. 동일 패턴 등장 시 신규 변환물 작성 후 이 행은 archive 처리.