Kyeongmin/C.E.L_Slide_test2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add remaining samples, tooling, and local project assets

Browse Source
This commit is contained in:
이경민
2026-04-15 18:02:17 +09:00
parent 05d43a7999
commit 1ff6c6cbb2
862 changed files with 18979 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
figma_to_html_agent/.gitignore vendored Normal file
View File

@@ -0,0 +1,29 @@
# Legacy / 임시 파일
block_index.faiss
block_metadata.json
figma_beps_full.json
figma_center_elements.json
figma_center_full.json
figma_frames.json
figma-analysis/
figma-assets/
figma-screenshots/
figma_ref/
previews/
FIGMA-COMPONENT-EXTRACTION-PLAN.md
FIGMA-CONVERSION-REVIEW.md
FIGMA-DESIGN-LANGUAGE.md
FIGMA-EXTRACTION.md
INSIGHT-GRADIENT.md
PHASE-FIGMA-BLOCKS.md
PLAN.md
RESEARCH.md
# Selenium 렌더 결과 / 비교 스크린샷
block-tests/_renders/
block-tests/*.png
# Python
__pycache__/
*.pyc
scripts/__pycache__/

38
figma_to_html_agent/CLAUDE.md
View File

@@ -19,7 +19,7 @@ Figma 프레임을 **수학적으로 정확하게** HTML/CSS로 변환하고,
6. **AI 역할 분담** — AI는 분류(고르기)만, 구성(만들기)은 코드. LLM은 px을 못 본다
7. **컨텍스트 관리는 compact로** — 한 세션에서 여러 프레임을 연속 작업할 수 있다. 컨텍스트가 무거워지면 `/compact` 로 핵심만 요약하고 계속 진행. 이유: 핵심 결정/구조/규칙은 모두 파일(CLAUDE.md, PROCESS.md, RULES.md, blocks_index.md, 산출물)에 박혀있어 compact 후에도 보존됨. 손실되는 건 시행착오/디버깅 과정 뿐이며, 이건 잃어도 OK. 매 프레임마다 새 세션을 강제하면 누적 학습이 silo되어 R13 같은 sub-pattern 발견의 즉시 적용이 불가능해짐.
8. **순수 CSS 우선, SVG는 곡선/필터에만** — 동적 재구성 위해 가능한 한 HTML div + linear-gradient 사용
9. **프로모션 게이트는 사용자 전용** — 에이전트는 절대 `design_agent/templates/` 에 직접 쓰지 않는다. 모든 작업은 `figma_to_html_agent/` 안에서 끝나며, 본체 라이브러리 이전은 사용자 수동 검수 후 사용자 본인이 수행한다.
9. **프로모션은 사용자 승인 후 진행** — 1:1 HTML 검증 완료 후, 사용자 승인을 받아 `templates/blocks/new/`에 블록을 생성하고 `templates/blocks/svg/`에 이미지를 정리한다. catalog.yaml 등록과 blocks_index.md 업데이트까지 에이전트가 수행한다. 단, 사용자 승인 없이 프로모션하지 않는다.
10. **시맨틱 우선, Figma 평면 레이어 그대로 옮기지 말 것** — Figma의 평면 레이어 구조는 디자인 도구의 한계일 뿐, 의미 구조가 아니다. 마커+텍스트는 list item, 카드 묶음은 column unit, 등 시맨틱하게 재그룹핑하여 작성한다. RULES.md R13 (Custom-marker bullet list) 참조. 새로 발견되는 sub-pattern은 [blocks_index.md](blocks_index.md) "디자인 인사이트" 섹션에 누적한다.
11. **모든 슬롯은 기본 optional** — 1:1 단계에서 모든 슬롯이 채워져 있다고 해서 "이 블록은 필수" 로 해석하지 않는다. 같은 블록이 사진 없는/짧은/긴 mdx에 모두 매칭되어야 한다는 가정으로 설계한다.
@@ -60,12 +60,18 @@ Figma 프레임을 **수학적으로 정확하게** HTML/CSS로 변환하고,
## 입출력
**입력:** Figma 파일 + 노드 ID (또는 현재 선택 노드)
**출력:**
- `block-tests/{slug}.html` — 변환 결과
**출력 (변환):**
- `block-tests/{slug}.html` — 1:1 변환 결과
- `block-tests/{slug}_flat.md` — 플래튼/이상 탐지/변형 축 메모
- `assets/shared/...` — 공유 자산 캐시
- `blocks_index.md` 한 줄 추가
**출력 (프로모션, 사용자 승인 후):**
- `templates/blocks/new/{pattern}.html` — AI가 재디자인 가능한 블록 (CSS + Jinja2)
- `templates/blocks/svg/{name}.png/svg` — 블록 공용 이미지
- `templates/catalog.yaml` — 블록 등록 (content_structure, when, not_for)
- `blocks_index.md` 상태 → promoted
## 폴더 구조
```
@@ -73,9 +79,9 @@ figma_to_html_agent/ ← 에이전트 작업 영역 (staging)
├── CLAUDE.md ← 이 파일 (에이전트 명세)
├── PROCESS.md ← 10단계 운영 절차 (변환 핸드북)
├── MATH.md ← 수학 공식 레퍼런스
├── RULES.md ← CSS 보정 규칙 (R1~R12)
├── RULES.md ← CSS 보정 규칙 (R1~R16)
├── PROCESS-CONTROL.md ← "찍어맞추기 금지" 규칙
├── PLAN.md ← 현재 진행 현황
├── README.md ← 사용법 가이드
├── blocks_index.md ← 변환 완료 도서관
│
├── scripts/
@@ -90,22 +96,22 @@ figma_to_html_agent/ ← 에이전트 작업 영역 (staging)
│ ├── shared/ ← 해시 기반 자산 캐시 (재사용)
│ └── frame_{id}/ ← 프레임 전용 자산 (legacy)
│
└── templates_staging/ ← Stage 2: Jinja2 추상화
├── {pattern_id}.html.j2
└── {pattern_id}.meta.yaml ← when/slots/min_size_px 초안
└── templates_staging/ ← Stage 2: Jinja2 추상화 (legacy, 현재 미사용)
────────────────────────────────────────────────────────
🚧 프로모션 게이트 (사용자 수동 작업) 🚧
프로모션 (사용자 승인 후 에이전트가 실행)
────────────────────────────────────────────────────────
design_agent/ ← 본체 라이브러리 (에이전트 접근 금지)
└── templates/
├── blocks/{category}/
│ └── {pattern_id}.html.j2 ← 사용자가 staging에서 이전
└── catalog.yaml ← 사용자가 when/slots 등록
design_agent/templates/
├── blocks/
│ ├── new/ ← Figma 추출 블록 (에이전트가 작성)
│ ├── svg/ ← 블록 공용 이미지 (에이전트가 정리)
│ ├── slide-base.html ← 고정 슬라이드 배경
│ └── cards/, emphasis/, ... ← 기존 블록
└── catalog.yaml ← 블록 등록 (에이전트가 업데이트)
```
**중요:** 에이전트는 위 구분선 아래(`design_agent/templates/`)를 **절대 수정하지 않는다.** 그 영역은 사용자가 staging 결과물을 검수한 뒤 본인이 직접 프로모션한다.
**중요:** 프로모션(블록 생성, 이미지 정리, catalog 등록)은 사용자가 1:1 HTML을 검증하고 승인한 후에만 진행한다. 사용자 승인 없이 templates/ 를 수정하지 않는다.
## 금지 사항
@@ -116,6 +122,8 @@ design_agent/ ← 본체 라이브러리 (에이전트 접
- 블록 배경을 검정으로 표시 (미리보기는 항상 흰색 배경)
- **이미지 해석으로 gradient 방향 판단** (멀티모달 금지, 데이터로만 판단 — PROCESS-CONTROL.md 참조)
- **한 번에 여러 값 동시 수정** (gradient 각도와 border-radius 동시 변경 금지)
- **장식 요소를 이미지 슬롯(img src)으로 넣기** — gradient bar, ribbon, pill, badge, 오버레이 등은 CSS로 구현. AI가 색상/크기를 조정할 수 없는 이미지 의존 블록은 쓸 수 없다
- **사용자 승인 없이 templates/ 수정** — 프로모션은 사용자 승인 후에만
- **여러 프레임을 한 세션에 변환** (1세션 1프레임 원칙)
- **plus-darker 블렌드 사용** (Safari 전용 → multiply로 교체, RULES.md R10)
- **Figma 인벤토리/지문/군집 같은 사전 분류** (work-creating-work, 패턴은 bottom-up으로 발견)

165
figma_to_html_agent/README.md Normal file
View File

@@ -0,0 +1,165 @@
# Figma → HTML Agent
Figma 디자인 프레임을 **수학적으로 정확하게** HTML/CSS로 변환하고, design_agent의 **블록 라이브러리**로 축적하는 독립 에이전트.
---
## 이 에이전트는 뭘 하는가?
1. Figma 파일에서 프레임을 선택하면
2. MCP(Figma Dev Mode)로 구조/스타일/스크린샷을 가져와서
3. 수학적 계산(scale, gradient 변환, shadow 등)으로 1:1 HTML/CSS를 만들고
4. AI가 재디자인할 수 있는 블록(순수 CSS + Jinja2 슬롯)으로 변환하여
5. design_agent의 블록 라이브러리(`templates/blocks/`)에 편입한다
**핵심:** AI redesigner가 색상/크기/구조를 조정할 수 있도록, 장식 요소는 **CSS로 구현**하고 이미지는 crop/곡선/일러스트/사진만 남긴다.
---
## 폴더 구조
```
figma_to_html_agent/
├── README.md ← 이 파일 (사용법)
├── CLAUDE.md ← 에이전트 명세 (11개 원칙)
├── PROCESS.md ← 10단계 변환 절차 핸드북
├── MATH.md ← 수학 공식 (§1~9)
├── RULES.md ← CSS 보정 규칙 (R1~R16)
├── PROCESS-CONTROL.md ← 작업 규율 (찍어맞추기 금지 등)
├── blocks_index.md ← 변환 완료 도서관 + 디자인 인사이트
│
├── scripts/
│ └── gradient_math.py ← SVG → CSS gradient 수학 변환 도구
│
├── block-tests/ ← 1:1 HTML 변환물 (원본 검증용)
│ ├── {slug}.html ← Figma 원본과 100% 동일한 정적 HTML
│ ├── {slug}_flat.md ← 플래튼/이상탐지/변형축 메모
│ └── assets/ ← 이미지 에셋
│ ├── shared/ ← 해시 기반 공유 캐시
│ └── frame_{id}/ ← 프레임 전용 (legacy)
│
└── templates_staging/ ← Jinja2 템플릿 초안 (legacy, 현재 미사용)
```
### 산출물 최종 위치 (design_agent 본체)
```
design_agent/
└── templates/
└── blocks/
├── new/ ← Figma 추출 블록 (8개)
├── svg/ ← 블록 공용 이미지 (33개)
├── slide-base.html ← 고정 슬라이드 배경 (16:9)
└── cards/, emphasis/, headers/, media/, visuals/, BEPs/, redesign/
```
---
## 사용법
### 사전 준비
1. **Figma Desktop** 앱에서 대상 파일을 열고 **Dev Mode** 활성화
2. `.mcp.json`에 Figma Desktop SSE 서버 등록 확인:
```json
{ "url": "http://127.0.0.1:3845/sse" }
```
3. Claude Code 세션 시작
### 변환 실행 (10단계)
```
STEP 0 에이전트가 blocks_index.md 읽기 → 기존 패턴 확인
STEP 1 get_metadata — 구조 + bbox (XML)
STEP 2 get_design_context — gradient/filter/font (React+Tailwind)
STEP 3 get_screenshot — Figma 원본 PNG (검증용)
STEP 4 자산 다운로드 — block-tests/assets/shared/ 캐시
STEP 5 flat.md 작성 — bottom-up 플래튼 + 이상탐지 + 변형축
STEP 6 gradient 수학 변환 — scripts/gradient_math.py
STEP 7 HTML 작성 — 순수 CSS 우선, transform: scale() 균일 축소
STEP 8 검증 — Figma 스크린샷과 비교
STEP 9 저장 — block-tests/{slug}.html + flat.md
STEP 10 인덱스 업데이트 — blocks_index.md 1줄 추가
```
**상세:** [PROCESS.md](PROCESS.md) 참조
### 블록 프로모션 (block-tests → templates/blocks/)
1:1 HTML이 검증되면:
1. **CSS 전환** — SVG/PNG 장식 요소를 CSS gradient/border-radius/shadow로 변환
- CSS 전환 대상: gradient bar, ribbon, pill, badge, 오버레이 등
- 이미지 유지 대상: crop/프레임 배치(R16), 곡선 아크, 아이콘, 일러스트, 실사 사진
2. **블록 작성** — `templates/blocks/new/{pattern}.html`
- flex layout, width: 100%, Jinja2 슬롯
- 수학적 계산 주석 (Figma px → scale → CSS 값)
- 이미지는 `svg/` 폴더에서 참조 (`{{ slot | default('svg/파일명') }}`)
3. **이미지 정리** — `templates/blocks/svg/`에 의미 있는 이름으로 저장
4. **catalog.yaml 등록** — content_structure, when, not_for 작성
5. **blocks_index.md 상태** — `staged` → `promoted` 업데이트
---
## 핵심 원칙 요약
| # | 원칙 | 설명 |
|---|------|------|
| 1 | 수학적 계산만 | Figma 좌표 → scale → CSS. 시행착오 px 조정 금지 |
| 2 | Bottom-up | leaf 노드부터 → 2개씩 묶기 → 계층 쌓기 |
| 3 | 순수 CSS 우선 | AI가 색상/크기 조정할 수 있게. SVG는 곡선/필터만 |
| 4 | 이미지 해석 금지 | gradient 방향은 데이터로. "보니까 ~인 것 같다" 금지 |
| 5 | 하드코딩 금지 | 결과물을 고치지 말고 프로세스를 고친다 |
| 6 | 전면 재작성 금지 | 80점에서 2개 고칠 때 구조를 갈아엎지 말 것 |
| 7 | 모든 슬롯 optional | 블록이 다양한 MDX에 매칭될 수 있게 |
**상세:** [CLAUDE.md](CLAUDE.md), [PROCESS-CONTROL.md](PROCESS-CONTROL.md), [RULES.md](RULES.md)
---
## 도구
| 도구 | 용도 |
|------|------|
| Figma MCP `get_metadata` | 프레임 구조 + 절대 좌표 (XML) |
| Figma MCP `get_design_context` | gradient/filter/font (React+Tailwind 코드) |
| Figma MCP `get_screenshot` | Figma 원본 PNG |
| `scripts/gradient_math.py` | SVG linearGradient → CSS linear-gradient 수학 변환 |
| Pillow | 이미지 픽셀 분석 (gradient 색상 추출, 이미지 해석 아님) |
---
## 수학 공식 요약
| 공식 | 용도 | 상세 |
|------|------|------|
| `S = 1280 / W_figma` | 균일 축소 scale | MATH.md §1 |
| `CSS_angle = 90 - Figma_angle` | gradient 각도 변환 | MATH.md §2 |
| SVG `<linearGradient>` → CSS | gradient stop % 변환 | gradient_math.py |
| `plus-darker → multiply` | blend mode 호환 | RULES.md R10 |
| bbox 비율 ≠ 텍스트 비율 → 회전 | rotation 감지 | RULES.md R11 |
---
## 현재 상태 (2026-04-13)
### 프로모션 완료 블록 (8개)
| 패턴 | 원본 프레임 | 블록 위치 |
|------|-----------|---------|
| statement-pill-highlight | 1171281207 | blocks/new/ |
| stacked-arrow-list | 1171281180 | blocks/new/ |
| split-panel-numbered | 1171281202 | blocks/new/ |
| issues-paired-rows | 1171281194 | blocks/new/ |
| compare-vs-rows | 1171281195 | blocks/new/ |
| quadrant-2x2-issues | 1171281193 | blocks/new/ |
| cards-3col-persona | 1171281191 | blocks/new/ |
| cycle-3way-intersect | 1171281211 | blocks/new/ |
### 공용 이미지 (templates/blocks/svg/, 33개)
화살표, 아크, 뱃지, 아이콘, 배경 텍스처, 사진 등. 블록에서 `svg/파일명`으로 참조.
### 고정 슬라이드 배경
`templates/blocks/slide-base.html` — 16:9 (1280×720), 상단 제목 + 구분선 + 본문 영역 + 하단 결론 pill.

9
figma_to_html_agent/blocks_index.md
View File

@@ -111,11 +111,10 @@ Sub-patterns: **bullet-list-with-marker (R13)** — 각 컬럼의 bullet_items
---
## templates_staging 대기열
## 프로모션 완료
> 2번째 등장한 패턴이 여기에 들어옴. 사용자 검수 후 design_agent 본체로 프로모션.
(아직 없음)
> 8개 블록 모두 `templates/blocks/new/`로 프로모션 완료 (2026-04-13).
> 이미지 33개 `templates/blocks/svg/`로 통합. catalog.yaml 등록 완료.
---
@@ -252,4 +251,4 @@ Sub-patterns: **bullet-list-with-marker (R13)** — 각 컬럼의 bullet_items
| 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 처리. |
| [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 (이미지 없음). |