Communitygithub.com

html2figma

Converta protótipos HTML de telefone em protótipos Figma editáveis, clicáveis e roláveis, ou crie primeiro o protótipo HTML para aprovação antes da importação.

O que é html2figma?

Esta skill, chamada html2figma, automatiza a conversão de protótipos HTML de dispositivos móveis em protótipos Figma totalmente editáveis, clicáveis e roláveis. Ela é ideal para desenvolvedores e designers que desejam transformar um HTML existente em um arquivo Figma interativo ou criar um protótipo HTML primeiro para garantir a aprovação do cliente antes da importação. A skill suporta múltiplas telas, camadas vetoriais, reações de navegação (ON_CLICK para NAVIGATE), modelos de dispositivo, detecção de camadas persistentes (como barras inferiores, barras superiores, FABs e toasts), rolagem real com camadas fixas e verificação de fidelidade de pixel. O processo é dividido em fases, desde a inspeção do protótipo HTML até a importação e configuração de interações e rolagem no Figma, utilizando uma combinação de análise de DOM, scripts de automação e a API do plugin Figma. É crucial seguir as regras de camadas persistentes e evitar erros comuns, como usar valores de enumeração incorretos para rolagem ou não posicionar camadas fixas corretamente na ordem dos filhos do frame.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

html2figma — HTML 原型 ⇄ Figma 可编辑可点击原型

Quando usar

  • Você já tem um protótipo HTML para celular e deseja importá-lo 1:1 para o Figma: camadas editáveis + telas clicáveis + rolagem + camadas persistentes fixas.
  • Você ainda não tem um protótipo HTML: crie-o seguindo a especificação de protótipo HTML, obtenha a aprovação do usuário e depois importe para o Figma.
  • Corrigir problemas em protótipos Figma: sobreposição/erros de quebra de linha de texto, perda de reações, camada persistente posicionada no final de um frame longo, rolagem que não funciona.

Não se aplica a: apenas arquivos Figma sem fonte HTML para conexão nativa; importação de designs estáticos para desktop; perguntas simples sobre como usar o Figma.

Três perguntas iniciais (não pule)

  1. Você tem um protótipo HTML?
    • Sim → comece pela Fase 1.
    • Não → siga a Fase 0: produza o protótipo HTML de acordo com a especificação → renderize todas as capturas de tela → pare e peça confirmação ao usuário → prossiga para o Figma somente após aprovação. O HTML é a base para toda geometria e interação subsequente; importar sem aprovação gera alto custo de retrabalho.
  2. Quais são as "camadas persistentes"? Não presuma que seja apenas uma dock. Verifique o DOM/capturas de tela de acordo com a seção §Determinação de camada persistente: position:fixed, ou posicionamento absoluto ancorado nas bordas superior/inferior da janela de visualização, com z-index maior que o conteúdo, que aparece repetidamente na mesma coordenada da janela de visualização em ≥2 telas. Pode ser uma dock inferior, navegação superior, botão flutuante FAB, toast, botão "voltar ao topo", alça de modal, etc. Se não tiver certeza, verifique o comportamento no HTML; se o HTML também não indicar, pergunte ao usuário, não adivinhe.
  3. Qual é o escopo de entrega? Todos os três itens são obrigatórios: ① Fidelidade de pixel (sem sobreposição/quebra de linha de texto, sem desalinhamento) ② Editável (Frame/Text/Vector/preenchimento de imagem) ③ Clicável (número de hotspots deve corresponder, não "aproximadamente").

Modelo mental (4 dicas que economizam horas)

  • O HTML é a única referência. Cada modificação no Figma deve ter um significado semântico correspondente no HTML: altura fixa da janela de visualização, overflow:hidden, position:fixed/absolute, closest('[data-goto]').
  • Importar ≠ restaurar. O plugin gera uma "imagem longa de altura total + camadas estáticas"; janela de visualização, rolagem, camadas fixas e reações são pós-processadas.
  • Se puder quantificar, não adivinhe pela imagem: sobreposição de texto usa caixa delimitadora de tinta, fidelidade usa MAE, reações usam auditoria de quantidade, rolagem/fixa usam sequência de capturas de tela do Present.
  • A API do plugin Figma permite definir rolagem e fixação (testado na prática): frame.overflowDirection = 'VERTICAL' (valores permitidos: NONE | VERTICAL | HORIZONTAL | BOTH; passar VERTICAL_SCROLLING causa erro de validação, não interprete como "não suportado"). Camadas filhas fixas usam numberOfFixedChildren = N; as camadas fixas devem ser as primeiras N camadas filhas do frame (primeiro insertChild(0, layer)). O painel Prototype é a solução de fallback e o local para configurações puramente de UI, como modelos de dispositivo.

Pipeline (cada fase pode ser verificada independentemente)

Fase 0 — Criar protótipo HTML (somente se não houver HTML existente)

Siga references/html-prototype-spec.md: janela de visualização 393×852, estrutura .phone/.screen/.scroll, hotspots data-goto, tokens de design, ícones SVG inline, fontes auto-contidas, disciplina de clamp. Critérios de conclusão: todas as telas podem ser renderizadas, sem overflow/sobreposição de texto, hotspots completos; produza capturas de tela em tela cheia + instruções de interação, peça ao usuário para confirmar visualmente e prossiga somente após aprovação.

Fase 1 — Inspeção do protótipo

Meça com precisão: número de telas e dimensões, altura do conteúdo de cada tela, nós com -webkit-line-clamp, famílias/pesos de fonte, número de hotspots data-goto deduplicados, lista de camadas persistentes (consulte §Determinação de camada persistente). Saída: boards.json, hotspots.json, clamp.json, persistent.json.

Fase 2 — Construção do feed (tela → fluxo de tela única importável)

Após injetar CSS/JS, serialize feed/index.html:

  • Oculte a estrutura da tela (barra superior/barra lateral/rótulos de tela/grid);
  • UNCLIP: remova altura fixa e overflow:hidden para permitir que o conteúdo se expanda naturalmente (posteriormente, as camadas são obtidas pela altura total e cortadas de volta para a janela de visualização);
  • Estratégia de truncamento (tente nativo primeiro, considere "baking" depois): após a importação, defina textTruncation='ENDING' + maxLines=N nas camadas de texto (deve chamar loadFontAsync antes). Faça o baking do clamp no feed somente quando for necessário alinhamento caractere por caractere com o navegador (algoritmo em pipeline). Não fazer truncamento resultará em texto pressionando além da borda;
  • Nomeie frames e camadas persistentes com data-h2f-name; incorpore/auto-contenha @font-face para fontes.

Fase 3 — Correspondência precisa de fontes (chave para restaurar quebras de linha)

Faça subset das fontes reais do protótipo + renomeie com prefixo unificado + instale (HKCU/fontes do sistema). O Figma deve corresponder exatamente ao mesmo nome de fonte, caso contrário, a substituição criará "erros de quebra de linha" falsos. Comandos e scripts de renomeação estão no pipeline.

Fase 4 — Importação e separação de frames

Instalação upstream: git clone https://github.com/kevicebryan/open-htmltofigma.git, Figma desktop → Plugins → Development → Import plugin from manifest… (selecione manifest.json no repositório); fixe commit/tag; se houver conflito de id do manifest, altere-o. O plugin renderiza o feed em iframe → cria diretamente Frame/Text/Vector; script de injeção local preenche automaticamente e converte (antes da importação, defina a janela de visualização do plugin para 393×852, caso contrário vh/media queries serão resolvidas com base no padrão 1440×1024). Após importar, eleve cada Frame de tela para o nível superior, organize horizontalmente, nomeie NN id · título, remova contêiner raiz. O importador não cria nenhuma reação, devendo ser reescrito na Fase 5; a versão do plugin deve ser fixada (consulte pipeline).

Fase 5 — Interações (reactions)

Itere sobre os hotspots em ordem crescente de área; a bbox ±2 atinge o nó mínimo que não seja TEXT, com fallback para o ponto central; se o nó não suportar reação, suba pelos ancestrais; uma reação existente é motivo para continuar subindo (o hotspot pai monta seu próprio nó), não um critério de parada; ignore auto-navegação. Leia node.reactions, escreva await setReactionsAsync(). Após escrever, reproduza usando a mesma lógica de acerto+subida; exp == ok && wrong == 0; auditoria de quantidade requer dangling == 0.

Fase 6 — Ajuste da janela de visualização + posicionamento de camada persistente

Primeiro, use persistent.json para listar a determinação de âncora de cada camada persistente (bottom/top/fab/none) e a justificativa; depois, comece a trabalhar; sinalize itens incertos e pergunte ao usuário, não fixe tudo por padrão. Localmente, redimensione cada frame para o tamanho da janela de visualização do protótipo (ex.: 393×852; leia de .phone na prática, não codifique; Android comum: 360×800/412×915), use resize + clipsContent, eleve a camada persistente da camada de conteúdo para a raiz do frame, posicione de acordo com a âncora da janela de visualização:

  • Barra inferior: y = altura da janela de visualização - altura;
  • Barra superior: y = 0;
  • FAB no canto inferior direito: converta right/bottom do HTML;
  • Classes ocultáveis/recolhíveis automaticamente (barra superior que desaparece ao rolar): não fixe, mantenha a semântica de fluxo de conteúdo.

Fixar e rolar pode ser feito diretamente pela API (testado neste projeto, Figma desktop):

board.insertChild(0, layer);        // Camadas fixas devem estar no início da lista de filhos
board.numberOfFixedChildren = 1;    // As primeiras N camadas filhas = camadas fixas
board.overflowDirection = 'VERTICAL';

O painel UI com Position = Fixed e Overflow = Vertical tem a mesma semântica e pode ser usado como fallback. Para preservar reações, não clone o frame para outra página: setReactionsAsync entre páginas falha completamente na prática. Primeiro, clone o frame de altura total para a página ARCHIVE como backup e, em seguida, reconstrua localmente.

Fase 7 — Rolagem + fixação + modelo de dispositivo

  • Rolagem: board.overflowDirection = 'VERTICAL' (enumeração apenas NONE | VERTICAL | HORIZONTAL | BOTH);
  • Fixação: board.numberOfFixedChildren = N (camadas fixas = primeiras N camadas filhas, consulte Fase 6);
  • Fallback da UI: selecione vários frames → Prototype → Overflow = Vertical; selecione várias camadas persistentes → Position = Fixed (stay in place);
  • Modelo de dispositivo (somente UI): desmarque seleção → configuração de Prototype em nível de arquivo → Device selecione o dispositivo do mesmo tamanho do protótipo (ex.: iPhone 15 Pro = 393×852); defina Flow starting point para a tela inicial. Detalhes e coordenadas em figma-ui-and-automation.

Fase 8 — Verificação em três camadas

  1. Pixel: exportação 2x vs referência, corte sombras estouradas por @dx,dy + busca de ±2px, MAE 3–10 é normal;
  2. Interação: auditoria de reação + validação de reprodução;
  3. Apresentação: três capturas de tela do Present (inicial / após rolagem / após navegação entre telas), confirme que as camadas persistentes estão sempre dentro da janela de visualização e não se movem com o conteúdo. Detalhes e limites em verification.

Determinação de camada persistente (importante, não se limite a dock)

Sinais de determinação (qualquer dois itens indicam candidato):

SinalComo verificar
Posicionamento CSSposition:fixed, ou absolute + bottom/top colado à borda da janela de visualização
Camadaz-index maior que a camada de conteúdo; sobreposto ao conteúdo rolável
Repetição entre telasMesmo seletor/mesma coordenada de janela de visualização aparece em ≥2 telas (navegação inferior, barra superior são mais comuns)
VisualBarra flutuante com cantos arredondados, vidro fosco, sombra flutuante, FAB, toast
ComportamentoHTML/JS escuta rolagem para mostrar/esconder ou mudar de cor

Decisão de tratamento:

  • Sempre sobreposto, persistente entre telas (barra de abas inferior, barra superior) → Fixo dentro da janela de visualização do Figma (Fixed).
  • Apenas sobreposto, não aderente ao topo (FAB) → Também eleve para a camada de janela de visualização e fixe.
  • Rola com o conteúdo (cartões comuns, botões inline) → Mantenha na camada de conteúdo, não fixe.
  • Esconde/aparece ao rolar (header com ocultação automática) → O Figma não pode replicar completamente a lógica com interações nativas: priorize manter a semântica estática de "rolagem seguida/ocultação" ou divida em telas de estado; não fixe erroneamente. Se não tiver certeza, pergunte ao usuário qual efeito de apresentação deseja.
  • Overlay/alça de modal → Geralmente pertence à própria tela do modal, trate como conteúdo dessa tela, não fixe entre telas.

Exemplo do projeto: dock inferior com 6 hotspots em 14 telas, eleve para y = 852-72 = 780 e defina como Fixed; a mesma fórmula se aplica a barra superior/FAB—primeiro determine a semântica, depois aplique as coordenadas.

Erros frequentes (Top 14)

#FenômenoCausa raiz / Contra-medida
1Camada persistente no final da imagem longaUNCLIP expande a janela de visualização de altura fixa, bottom:0 cai no final do conteúdo → Fase 6 ajuste de janela de visualização
2Erro de validação ao definir rolagemValor de enumeração errado (ex.: VERTICAL_SCROLLING) → use VERTICAL; FRAME comum pode escrever, não interprete como não suportado
3Camada filha fixa definida mas não funcionouCamada fixa deve ser a primeira N camada filha do frame: primeiro insertChild(0, layer) e depois defina numberOfFixedChildren = N
4Reação falha após clonagem para nova páginasetReactionsAsync entre páginas é rejeitado → reconstrua localmente, salve backup em outro lugar
5Texto pressiona rótulo abaixoPrimeiro tente textTruncation='ENDING' + maxLines nativo; se ainda inconsistente, faça baking de truncamento caractere por caractere no feed
6Quebra de linha no Figma diferente do navegadorFonte substituída → faça subset + renomeie + instale
7Imagem exportada maior que o frame, comparação totalmente erradaExportação inclui sombras estouradas → corte por @dx,dy
8Clique/rolagem simulada com mouse ineficazWebview filtra; menu é clicável. Painel use UIA/teclado; player use PostMessage para rolagem
9Clique de script no overlay falha na segunda vezCada execução re-foca → abra + selecione na mesma execução
10Coordenadas de captura de tela deslocadasConsciência de DPI; coordenada da captura == coordenada relativa da janela; UIA é pixel físico absoluto
11Plugin executado em outro arquivoFigma restaura aba antiga/abre Untitled → confirme a aba ativa primeiro
12Imagem cortada não abreEscala não inteira produz dimensões fracionárias → arredonde a saída
13Texto estranho aparecendo na telaColagem acidental gera nós TEXT → limpe por regex de conteúdo
14Resultado não pode ser lidoUse page.name ou coletor HTTP local para leitura de estado

Plataforma e compatibilidade

  • Esta skill segue a especificação Agent Skills (SKILL.md + references/ + scripts/), podendo ser carregada por ZCode, Claude Code e qualquer agente que implemente essa especificação.
  • A descrição do fluxo é intencionalmente genérica, mas a etapa de importação depende do plugin de desenvolvimento open-htmltofigma e do Figma desktop; scripts de automação são voltados para Windows; macOS/Linux usam AppleScript/screencapture/xdotool ou equivalentes, ou siga a documentação para operação manual.
  • Figma web não pode importar plugin de desenvolvimento local; etapas relacionadas ao plugin requerem desktop (a versão web pode abrir plugins publicados).

Referências e scripts

  • references/html-prototype-spec.md — Especificação de criação e checklist de aceitação para quando não há protótipo HTML (incluindo controle de acesso "mostre primeiro ao usuário").
  • references/pipeline.md — Esqueleto de código para feed/UNCLIP, algoritmo de clamp, fontes, importação e separação de frames, reações e ajuste de janela de visualização.
  • references/figma-ui-and-automation.md — Matriz de capacidades API/UI, configuração em lote, modelo de dispositivo, automação Windows e regras de coordenadas.
  • references/verification.md — MAE, auditoria/reprodução de reação, três capturas do Present, triagem de falhas.
  • scripts/rename_font.py, scripts/install_font.ps1 — Subset de fontes/renomeação e instalação para o usuário atual (incluindo desinstalação).
  • scripts/figma_win.ps1, scripts/uia.ps1 — Auxiliares Windows (clique/hover/tecla/rolagem/captura de tela, UIA enumeração/clique/foco).
  • scripts/crop.mjs — Corte de PNG multiplataforma (escala inteira, para revisão de captura de tela).

Modo de trabalho

  • Antes de modificar o código, explique "qual linha alterar e por quê", uma causa raiz por vez; os artefatos intermediários devem ter nome de arquivo com versão.
  • Cada "parece correto" deve ter evidência numérica ou de captura de tela; cada "deveria funcionar" deve ser testado no Present.
  • Concentre-se apenas nas três coisas: "restauração / editável / clicável"; não refatore o pipeline desnecessariamente nem atualize dependências.

Habilidades Relacionadas