html2figma — HTML 프로토타입 ⇄ Figma 편집 가능 클릭 가능 프로토타입
언제 사용하나
- 기존 HTML 휴대폰 프로토타입을 1:1로 Figma로 가져올 때: 편집 가능한 레이어 + 클릭 가능한 화면 전환 + 스크롤 가능 + 고정 레이어 고정.
- 아직 HTML 프로토타입이 없을 때: 먼저 HTML 프로토타입 명세에 따라 제작하고, 사용자 확인 후 Figma로 가져옴.
- Figma 프로토타입 문제 수정: 텍스트 겹침/줄바꿈 오류, 반응(Reaction) 손실, 고정 레이어가 긴 프레임 하단으로 이동, 스크롤 불가.
적용되지 않음: HTML 소스 없이 Figma 파일만 있는 순수 네이티브 연결; 데스크탑 정적 디자인 가져오기; 단순 Figma 조작 질문.
진입 3문 (건너뛰지 마세요)
- HTML 프로토타입이 있나요?
- 있음 → Phase 1부터 시작.
- 없음 → Phase 0 진행: 명세에 따라 HTML 프로토타입 제작 → 모든 화면 스크린샷 렌더링 → 사용자에게 확인 요청 → 승인 후 Figma로 이동. HTML은 이후 모든 지오메트리와 인터랙션의 기준이며, 확인 없이 가져오면 재작업 비용이 매우 높습니다.
- 어떤 것이 '고정 레이어'인가요?
독(Dock)으로 기본 가정하지 마세요. '고정 레이어 판정' 섹션에 따라 DOM/스크린샷을 조사합니다:
position:fixed, 또는 뷰포트 상하단에 고정된absolute위치,z-index가 콘텐츠보다 높고, 2개 이상의 화면에서 동일한 뷰포트 좌표에 반복적으로 나타나는 요소. 하단 독, 상단 네비게이션, 플로팅 액션 버튼(FAB), 플로팅 토스트, 맨 위로 가기 버튼, 모달 핸들 등이 해당됩니다. 판단이 어려우면 HTML 동작을 확인하고, HTML에도 없으면 사용자에게 먼저 물어보고 추측하지 마세요. - 전달 범위는? 세 가지 모두 필요: ① 픽셀 완벽 복원 (텍스트 겹침/줄바꿈/위치 오류 없음) ② 편집 가능 (Frame/Text/Vector/이미지 채우기) ③ 클릭 가능 (핫스팟 수량이 정확해야 하며, '대략'이 아니어야 함).
멘탈 모델 (시간을 절약하는 4가지)
- HTML이 유일한 기준입니다. Figma의 모든 변환은 HTML에서 의미를 찾을 수 있어야 합니다: 고정 높이 뷰포트,
overflow:hidden,position:fixed/absolute,closest('[data-goto]'). - 가져오기 ≠ 복원. 플러그인은 '전체 높이 긴 이미지 + 정적 레이어'를 제공하며, 뷰포트, 스크롤, 고정 레이어, 반응은 모두 후처리됩니다.
- 정량화할 수 있으면 그림을 보고 추측하지 마세요: 텍스트 겹침은 잉크 경계 상자(ink bounding box)로, 복원 정확도는 MAE(Mean Absolute Error)로, 반응은 개수 감사로, 스크롤/고정은 Present 스크린샷 시퀀스로 확인합니다.
- Figma 플러그인 API는 스크롤과 고정을 설정할 수 있습니다 (실제 테스트 완료):
frame.overflowDirection = 'VERTICAL'(유효한 값은NONE | VERTICAL | HORIZONTAL | BOTH;VERTICAL_SCROLLING등을 전달하면 validation error가 발생하므로 '지원 안 함'으로 오해하지 마세요). 고정 하위 레이어는numberOfFixedChildren = N으로 설정하며, 고정 레이어는 프레임의 앞쪽 N개 하위 레이어여야 합니다 (먼저insertChild(0, layer)로 배치). 프로토타입 패널은 최후의 보루이며, 기기 모델 등 UI-only 설정을 위한 곳입니다.
파이프라인 (각 단계별 독립 검증 가능)
Phase 0 — HTML 프로토타입 제작 (기존 HTML이 없을 때만)
references/html-prototype-spec.md 참조: 393×852 뷰포트, .phone/.screen/.scroll 구조, data-goto 핫스팟, 디자인 토큰, 인라인 SVG 아이콘, 폰트 자체 포함, clamp 규율.
완료 기준: 모든 화면 렌더링 가능, 오버플로우/텍스트 압박 없음, 핫스팟 완비; 전체 화면 스크린샷 + 인터랙션 설명 출력, 사용자에게 이미지 확인 요청, 승인 후 계속 진행.
Phase 1 — 프로토타입 검사
정확히 측정: 화면 수와 크기, 각 화면 콘텐츠 높이, -webkit-line-clamp 노드, 폰트 패밀리/굵기, data-goto 중복 제거 후 유효 핫스팟 수, 고정 레이어 목록 ('고정 레이어 판정' 섹션 참조).
산출물: boards.json, hotspots.json, clamp.json, persistent.json.
Phase 2 — Feed 구성 (캔버스 → 가져오기 가능한 단일 화면 스트림)
CSS/JS 주입 후 feed/index.html 직렬화:
- 캔버스 외부 요소 숨김 (상단 바/사이드 바/화면 레이블/그리드);
- UNCLIP: 고정 높이와
overflow:hidden제거하여 콘텐츠가 자연스럽게 펼쳐지도록 함 (이후 전체 높이로 레이어를 가져온 후 뷰포트로 다시 자름); - 줄임 전략 (먼저 네이티브 시도, 베이킹은 나중에): 가져오기 후 텍스트 레이어에
textTruncation='ENDING'+maxLines=N설정 가능 (loadFontAsync필수). 브라우저와 글자 단위로 일치하는 줄바꿈이 필요할 때만 Feed에서 clamp를 베이킹합니다 (알고리즘은 pipeline 참조). 줄임 처리를 전혀 하지 않으면 프레임 밖으로 텍스트가 압박되어 나옵니다; data-h2f-name으로 보드와 고정 레이어 명명; 폰트@font-face인라인/자체 포함.
Phase 3 — 폰트 정확한 일치 (줄바꿈 복원의 핵심)
프로토타입 실제 폰트를 서브셋화 + 이름 변경 및 통일된 접두사 추가 + 설치 (HKCU/시스템 폰트). Figma는 동일한 이름의 폰트를 찾아야 하며, 그렇지 않으면 대체로 인해 거짓 '줄바꿈 오류'가 발생합니다. 명령어와 이름 변경 스크립트는 pipeline 참조.
Phase 4 — 가져오기 및 보드 분할
상위 설치: git clone https://github.com/kevicebryan/open-htmltofigma.git, Figma 데스크탑 → Plugins → Development → Import plugin from manifest… (저장소 내 manifest.json 선택); 고정 commit/tag 사용, manifest id 충돌 시 변경. 플러그인이 iframe에서 feed를 실제 렌더링 → Frame/Text/Vector 직접 생성; 로컬 주입 스크립트가 자동으로 채우고 변환 (가져오기 전에 플러그인 뷰포트를 393×852로 설정하지 않으면 vh/미디어 쿼리가 기본 1440×1024로 해석됨). 가져오기 후 각 화면 Frame을 최상위 레이어로 승격, 가로로 정렬, NN id · 제목 형식으로 이름 지정, 루트 컨테이너 삭제. 가져오기는 어떤 반응도 생성하지 않으며, Phase 5에서 다시 작성해야 합니다. 플러그인 버전은 고정해야 합니다 (pipeline 참조).
Phase 5 — 인터랙션 (반응)
핫스팟을 면적 오름차순으로 순회; bbox ±2px 이내에서 가장 작은 비-TEXT 노드 찾기, 중심점으로 폴백; 노드가 반응을 지원하지 않으면 상위 요소로 이동; 이미 반응이 있는 경우는 상위로 이동하는 이유 (부모 핫스팟이 자신의 노드를 가짐)이며, 종료 조건이 아님; 자기 자신으로의 점프는 건너뜀. node.reactions 읽고, await setReactionsAsync()로 작성.
작성 후 동일한 히트+상위 이동 로직으로 재생, exp == ok && wrong == 0 확인; 수량 감사는 dangling == 0 요구.
Phase 6 — 뷰포트화 + 고정 레이어 배치
먼저 persistent.json을 사용하여 각 고정 레이어의 앵커 판정 (bottom/top/fab/none)과 근거를 나열한 후 작업; 확실하지 않은 것은 표시하여 사용자에게 질문하고, 기본적으로 모두 고정하지 마세요.
각 보드를 프로토타입 뷰포트 크기로 변경 (예: 393×852; .phone에서 실제 측정값을 읽고 하드코딩하지 마세요. Android에서는 360×800/412×915가 일반적), resize + clipsContent 설정, 고정 레이어를 콘텐츠 레이어에서 보드 루트로 이동, 뷰포트 앵커에 따라 배치:
- 하단 바:
y = 뷰포트 높이 - 높이; - 상단 바:
y = 0; - 우측 하단 FAB: HTML의
right/bottom값으로 환산; - 숨김 가능/자동 접이식 (스크롤 시 페이드 아웃되는 상단 바): 고정하지 말고 콘텐츠 흐름 의미를 유지.
고정과 스크롤은 직접 API를 사용할 수 있습니다 (본 프로젝트에서 실제 테스트 완료, Figma 데스크탑 버전):
board.insertChild(0, layer); // 고정 레이어는 하위 레이어 중 가장 앞에 위치해야 함
board.numberOfFixedChildren = 1; // 앞 N개 하위 레이어 = 고정 레이어
board.overflowDirection = 'VERTICAL';
UI의 Position = Fixed 및 Overflow = Vertical과 의미가 동일하므로 최후의 보루로 사용 가능. 반응을 유지하려면 보드를 다른 페이지로 복제하지 마세요: 페이지 간 setReactionsAsync는 실제 테스트 결과 모두 실패합니다. 먼저 전체 높이 보드를 ARCHIVE 페이지에 복제하여 보관한 후, 원래 위치에서 재구성합니다.
Phase 7 — 스크롤 + 고정 + 기기 모델
- 스크롤:
board.overflowDirection = 'VERTICAL'(열거형은NONE | VERTICAL | HORIZONTAL | BOTH만 가능); - 고정:
board.numberOfFixedChildren = N(고정 레이어 = 앞 N개 하위 레이어, Phase 6 참조); - UI 최후의 보루: 여러 보드를 선택 → Prototype →
Overflow = Vertical; 여러 고정 레이어 선택 →Position = Fixed (stay in place); - 기기 모델 (UI-only): 선택 해제 → 파일 레벨 Prototype 설정 → Device에서 프로토타입과 동일한 크기의 기기 선택 (예: iPhone 15 Pro = 393×852); 시작 화면에 Flow starting point 설정. 이유와 좌표 세부 사항은 figma-ui-and-automation 참조.
Phase 8 — 3단계 검증
- 픽셀: 2x 내보내기 vs 참조,
@dx,dy로 그림자 오버플로우 자르기 + ±2px 검색, MAE 3–10 정상; - 인터랙션: 반응 감사 + 재생 검증;
- 프레젠테이션: Present 3연속 스크린샷 (초기 / 스크롤 후 / 화면 전환 후), 고정 레이어가 항상 뷰포트 내에 있고 콘텐츠와 함께 이동하지 않는지 확인. 세부 사항과 임계값은 verification 참조.
고정 레이어 판정 (중요, 독만 인식하지 마세요)
판정 신호 (두 가지 이상 충족 시 후보):
| 신호 | 확인 방법 |
|---|---|
| CSS 위치 | position:fixed, 또는 absolute + bottom/top이 뷰포트 가장자리에 고정 |
| 계층 | z-index가 콘텐츠 레이어보다 높음; 스크롤 콘텐츠 위에 덮어씌워짐 |
| 화면 간 반복 | 동일한 선택자/동일한 뷰포트 좌표가 2개 이상의 화면에서 나타남 (하단 네비게이션, 상단 바가 가장 일반적) |
| 시각적 | 둥근 모서리 플로팅 바, 모르타르 유리, 그림자 플로팅 레이어, FAB, 토스트 |
| 동작 | HTML/JS에서 스크롤을 수신하여 show/hide 또는 색상 변경 수행 |
처리 결정:
- 항상 덮어쓰고, 화면 간 고정 (하단 탭 바, 상단 바) → Figma 뷰포트 내 고정 (
Fixed). - 덮어쓰기만 하고 고정은 아님 (FAB) → 뷰포트 레이어로 이동하여 고정.
- 콘텐츠와 함께 스크롤 (일반 카드, 인라인 버튼) → 콘텐츠 레이어에 남겨두고 고정하지 마세요.
- 스크롤 시 숨김/나타남 (auto-hide header) → Figma는 네이티브 인터랙션으로 전체 로직을 재현할 수 없음: '스크롤 따라 숨김'의 정적 의미를 우선 유지하거나, 여러 상태 화면으로 분할; Fixed로 잘못 설정하지 마세요. 판단이 어려우면 사용자에게 원하는 프레젠테이션 효과를 물어보세요.
- 오버레이/모달 핸들 → 일반적으로 오버레이 화면 자체에 속하므로 해당 화면의 콘텐츠로 처리하고, 화면 간 고정하지 마세요.
본 프로젝트 예시: 하단 독 14개 화면 각각 6개 핫스팟,
y = 852-72 = 780으로 이동 후 Fixed 설정; 동일한 공식이 상단 바/FAB에도 적용됨 — 먼저 의미를 판정한 후 좌표를 적용합니다.
빈번한 함정 (Top 14)
| # | 현상 | 근본 원인 / 대책 |
|---|---|---|
| 1 | 고정 레이어가 긴 이미지 하단에 있음 | 가져오기 UNCLIP으로 고정 높이 뷰포트가 펼쳐져 bottom:0이 콘텐츠 끝에 위치 → Phase 6 뷰포트화 |
| 2 | 스크롤 설정 시 validation error | 열거형 값 오타 (예: VERTICAL_SCROLLING) → VERTICAL 사용; 일반 FRAME에서 설정 가능하므로 '지원 안 함'으로 오해하지 마세요 |
| 3 | 고정 하위 레이어 설정했으나 효과 없음 | 고정 레이어는 프레임의 앞쪽 N개 하위 레이어여야 함: 먼저 insertChild(0, layer) 후 numberOfFixedChildren = N 설정 |
| 4 | 새 페이지로 복제 후 반응 모두 실패 | 페이지 간 setReactionsAsync가 거부됨 → 원래 위치에서 재구성하고, 보관은 별도 저장 |
| 5 | 텍스트가 아래쪽 레이블을 압박 | 먼저 네이티브 textTruncation='ENDING' + maxLines 시도; 여전히 일치하지 않으면 Feed에서 글자 단위 줄임 베이킹 |
| 6 | Figma 줄바꿈이 브라우저와 다름 | 폰트가 대체됨 → 서브셋화+이름 변경+설치 |
| 7 | 내보낸 이미지가 아트보드보다 크고 비교가 모두 틀림 | 내보내기에 그림자 오버플로우 포함 → @dx,dy로 자르기 |
| 8 | 합성 마우스 클릭/휠이 작동하지 않음 | webview가 필터링; 메뉴는 클릭 가능. 패널은 UIA/키보드 사용; 플레이어 스크롤은 PostMessage 휠 사용 |
| 9 | 두 번째 스크립트 클릭이 오버레이에서 빗나감 | 각 실행 시마다 포그라운드가 다시 활성화됨 → 열기+선택을 동일한 실행 내에서 수행 |
| 10 | 스크린샷 좌표가 어긋남 | DPI 인식 필요; 스크린샷 좌표 == 창 상대 좌표; UIA는 절대 물리 픽셀 |
| 11 | 플러그인이 다른 파일에서 실행됨 | Figma가 이전 탭을 복원하거나 Untitled를 잘못 열음 → 먼저 활성 탭 확인 |
| 12 | 잘라낸 이미지를 열 수 없음 | 정수 배율이 아닌 경우 소수점 크기 발생 → 출력 시 반올림 |
| 13 | 캔버스에 이상한 텍스트가 나타남 | 잘못된 붙여넣기로 TEXT 노드 생성 → 내용 정규식으로 정리 |
| 14 | 결과를 읽을 수 없음 | page.name 또는 로컬 HTTP 수집기를 사용하여 상태 읽기 |
플랫폼 및 호환성
- 이 스킬은 Agent Skills 명세 (SKILL.md + references/ + scripts/)를 따르며, ZCode, Claude Code 및 해당 명세를 구현하는 모든 에이전트에서 로드할 수 있습니다.
- 프로세스 설명은 가능한 일반적이지만, 가져오기 단계는 open-htmltofigma 개발 플러그인 및 Figma 데스크탑에 의존하며, 자동화 스크립트는 Windows를 대상으로 합니다; macOS/Linux는 AppleScript/
screencapture/xdotool등으로 대체하거나 문서에 따라 수동으로 작업합니다. - Figma 웹 버전은 로컬 개발 플러그인을 가져올 수 없습니다; 플러그인 관련 단계는 데스크탑 앱이 필요합니다 (웹 버전은 게시된 플러그인을 열 수 있음).
참조 및 스크립트
- references/html-prototype-spec.md — HTML 프로토타입이 없을 때 제작 명세 및 검증 체크리스트 ('먼저 사용자에게 보여주기' 게이트 포함).
- references/pipeline.md — feed/UNCLIP, clamp 알고리즘, 폰트, 가져오기/보드 분할, 반응, 뷰포트화 코드 골격.
- references/figma-ui-and-automation.md — API/UI 능력 매트릭스, 일괄 설정, 기기 모델, Windows 자동화 및 좌표 규칙.
- references/verification.md — MAE, 반응 감사/재생, Present 3연속, 실패 분류.
scripts/rename_font.py,scripts/install_font.ps1— 폰트 서브셋화/이름 변경 및 현재 사용자 설치 (제거 포함).scripts/figma_win.ps1,scripts/uia.ps1— Windows 보조 (클릭/호버/키/휠/스크린샷, UIA 열거/클릭/포커스).scripts/crop.mjs— 크로스 플랫폼 PNG 자르기 (정수 배율, 스크린샷 검토용).
작업 방식
- 코드를 변경하기 전에 '어느 줄을 왜 변경하는지' 설명하고, 한 번에 하나의 근본 원인을 해결합니다; 중간 산출물은 버전 번호를 포함한 새 파일 이름으로 저장합니다.
- '그럴듯해 보이는' 모든 것은 숫자 또는 스크린샷 증거가 필요합니다; '되어야 하는' 모든 것은 Present에서 실제 테스트해야 합니다.
- '복원 / 편집 가능 / 클릭 가능' 세 가지에만 집중하고, 파이프라인을 리팩토링하거나 종속성을 업그레이드하지 않습니다.