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-process-products-2col	181:2519 / Frame 1171281210 (file 9S6LsQyO6zlRxtiqZccOUM, page 29:373)	3848×1388	process-products-2col-banner-top	static	2026-04-28
overseas-bim-numbered-list	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	182:3024 / Frame 1171281179 (file 9S6LsQyO6zlRxtiqZccOUM, page 29:373)	1207×861	framework-3section-label-body	static	2026-04-29
sw-reality-3emphasis	145:8523 / Frame 1171281209 (file 9S6LsQyO6zlRxtiqZccOUM, page 29:373)	1697×582	bordered-3paragraphs-with-3emphasis-labels	static	2026-04-29
bim-model-info-3category	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	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	45:15 / Frame 1171281190	prerequisites-3col	promoted → block + catalog	2026-04-13. legacy HTML 기반 블록화. 순수 CSS (이미지 없음).