Communitygithub.com

html2figma

HTML 휴대폰 프로토타입을 편집 가능하고, 클릭 가능하며, 스크롤 가능한 Figma 프로토타입으로 변환합니다. 또는 HTML 프로토타입을 먼저 제작하여 서명을 받은 후 가져올 수 있습니다. 다중 화면 보드, 벡터 레이어, ON_CLICK → NAVIGATE 반응, 기기 모델, 고정 레이어 감지(하단 탭 바, 상단 바, FAB, 토스트, 독뿐만 아님), 실제 스크롤링 및 고정 레이어, 픽셀 단위 정밀도 검증을 지원합니다.

html2figma란 무엇인가요?

html2figma는 HTML로 작성된 모바일 프로토타입을 Figma에서 완전히 편집 가능하고 인터랙티브한 프로토타입으로 변환하는 전문 기술입니다. 이 기술은 HTML 프로토타입을 Figma 프로토타입으로 전환하거나, 클릭 가능한 화면 전환, 고정된 하단 내비게이션 또는 지속적인 바, 휴대폰 기기 프레임, 화면별 정밀도 확인, 또는 인터랙티브 HTML 프로토타입을 Figma 파일로 제공해야 할 때 사용됩니다. 또한 긴 프레임 아래로 떨어진 독(Dock), 작동하지 않는 스크롤, 손실된 반응, 또는 글꼴 대체로 인한 줄바꿈 문제를 디버깅하는 데에도 유용합니다. 이 기술은 HTML 소스 없이 순수 Figma 프로토타입 와이어링, 데스크탑 정적 디자인 가져오기, 또는 Figma 사용법에 대한 일회성 질문에는 사용되지 않습니다. html2figma는 SKILL.md 사양을 따르며, Phase 0(HTML 프로토타입 제작)부터 Phase 8(픽셀, 인터랙션, 프레젠테이션 검증)까지의 파이프라인을 통해 HTML을 유일한 기준으로 삼아 Figma 레이어, 벡터, 텍스트, 반응을 정확하게 재현합니다. 또한 open-htmltofigma 개발 플러그인과 Figma 데스크탑 앱을 활용하여 실제 스크롤, 고정 레이어, 기기 모델을 설정합니다. Windows 자동화 스크립트를 기본으로 지원하며, macOS/Linux는 AppleScript/screencapture/xdotool 등으로 대체 가능합니다.

지원 대상✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ilovemajiaqi/html2figma/tree/HEAD

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

html2figma — HTML 프로토타입 ⇄ Figma 편집 가능 클릭 가능 프로토타입

언제 사용하나

  • 기존 HTML 휴대폰 프로토타입을 1:1로 Figma로 가져올 때: 편집 가능한 레이어 + 클릭 가능한 화면 전환 + 스크롤 가능 + 고정 레이어 고정.
  • 아직 HTML 프로토타입이 없을 때: 먼저 HTML 프로토타입 명세에 따라 제작하고, 사용자 확인 후 Figma로 가져옴.
  • Figma 프로토타입 문제 수정: 텍스트 겹침/줄바꿈 오류, 반응(Reaction) 손실, 고정 레이어가 긴 프레임 하단으로 이동, 스크롤 불가.

적용되지 않음: HTML 소스 없이 Figma 파일만 있는 순수 네이티브 연결; 데스크탑 정적 디자인 가져오기; 단순 Figma 조작 질문.

진입 3문 (건너뛰지 마세요)

  1. HTML 프로토타입이 있나요?
    • 있음 → Phase 1부터 시작.
    • 없음 → Phase 0 진행: 명세에 따라 HTML 프로토타입 제작 → 모든 화면 스크린샷 렌더링 → 사용자에게 확인 요청 → 승인 후 Figma로 이동. HTML은 이후 모든 지오메트리와 인터랙션의 기준이며, 확인 없이 가져오면 재작업 비용이 매우 높습니다.
  2. 어떤 것이 '고정 레이어'인가요? 독(Dock)으로 기본 가정하지 마세요. '고정 레이어 판정' 섹션에 따라 DOM/스크린샷을 조사합니다: position:fixed, 또는 뷰포트 상하단에 고정된 absolute 위치, z-index가 콘텐츠보다 높고, 2개 이상의 화면에서 동일한 뷰포트 좌표에 반복적으로 나타나는 요소. 하단 독, 상단 네비게이션, 플로팅 액션 버튼(FAB), 플로팅 토스트, 맨 위로 가기 버튼, 모달 핸들 등이 해당됩니다. 판단이 어려우면 HTML 동작을 확인하고, HTML에도 없으면 사용자에게 먼저 물어보고 추측하지 마세요.
  3. 전달 범위는? 세 가지 모두 필요: ① 픽셀 완벽 복원 (텍스트 겹침/줄바꿈/위치 오류 없음) ② 편집 가능 (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단계 검증

  1. 픽셀: 2x 내보내기 vs 참조, @dx,dy로 그림자 오버플로우 자르기 + ±2px 검색, MAE 3–10 정상;
  2. 인터랙션: 반응 감사 + 재생 검증;
  3. 프레젠테이션: 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에서 글자 단위 줄임 베이킹
6Figma 줄바꿈이 브라우저와 다름폰트가 대체됨 → 서브셋화+이름 변경+설치
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에서 실제 테스트해야 합니다.
  • '복원 / 편집 가능 / 클릭 가능' 세 가지에만 집중하고, 파이프라인을 리팩토링하거나 종속성을 업그레이드하지 않습니다.

관련 스킬