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)
- 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.
- 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, comz-indexmaior 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. - 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; passarVERTICAL_SCROLLINGcausa erro de validação, não interprete como "não suportado"). Camadas filhas fixas usamnumberOfFixedChildren = N; as camadas fixas devem ser as primeiras N camadas filhas do frame (primeiroinsertChild(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:hiddenpara 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=Nnas camadas de texto (deve chamarloadFontAsyncantes). 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-facepara 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/bottomdo 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 apenasNONE | 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
- Pixel: exportação 2x vs referência, corte sombras estouradas por
@dx,dy+ busca de ±2px, MAE 3–10 é normal; - Interação: auditoria de reação + validação de reprodução;
- 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):
| Sinal | Como verificar |
|---|---|
| Posicionamento CSS | position:fixed, ou absolute + bottom/top colado à borda da janela de visualização |
| Camada | z-index maior que a camada de conteúdo; sobreposto ao conteúdo rolável |
| Repetição entre telas | Mesmo seletor/mesma coordenada de janela de visualização aparece em ≥2 telas (navegação inferior, barra superior são mais comuns) |
| Visual | Barra flutuante com cantos arredondados, vidro fosco, sombra flutuante, FAB, toast |
| Comportamento | HTML/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 = 780e 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ômeno | Causa raiz / Contra-medida |
|---|---|---|
| 1 | Camada persistente no final da imagem longa | UNCLIP 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 |
| 2 | Erro de validação ao definir rolagem | Valor de enumeração errado (ex.: VERTICAL_SCROLLING) → use VERTICAL; FRAME comum pode escrever, não interprete como não suportado |
| 3 | Camada filha fixa definida mas não funcionou | Camada fixa deve ser a primeira N camada filha do frame: primeiro insertChild(0, layer) e depois defina numberOfFixedChildren = N |
| 4 | Reação falha após clonagem para nova página | setReactionsAsync entre páginas é rejeitado → reconstrua localmente, salve backup em outro lugar |
| 5 | Texto pressiona rótulo abaixo | Primeiro tente textTruncation='ENDING' + maxLines nativo; se ainda inconsistente, faça baking de truncamento caractere por caractere no feed |
| 6 | Quebra de linha no Figma diferente do navegador | Fonte substituída → faça subset + renomeie + instale |
| 7 | Imagem exportada maior que o frame, comparação totalmente errada | Exportação inclui sombras estouradas → corte por @dx,dy |
| 8 | Clique/rolagem simulada com mouse ineficaz | Webview filtra; menu é clicável. Painel use UIA/teclado; player use PostMessage para rolagem |
| 9 | Clique de script no overlay falha na segunda vez | Cada execução re-foca → abra + selecione na mesma execução |
| 10 | Coordenadas de captura de tela deslocadas | Consciência de DPI; coordenada da captura == coordenada relativa da janela; UIA é pixel físico absoluto |
| 11 | Plugin executado em outro arquivo | Figma restaura aba antiga/abre Untitled → confirme a aba ativa primeiro |
| 12 | Imagem cortada não abre | Escala não inteira produz dimensões fracionárias → arredonde a saída |
| 13 | Texto estranho aparecendo na tela | Colagem acidental gera nós TEXT → limpe por regex de conteúdo |
| 14 | Resultado não pode ser lido | Use 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/xdotoolou 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.