Por que os ícones somem quando você importa uma página web para o Figma

Chega tudo menos os ícones. Caixas vazias, quadrados pretos ou retangulozinhos onde estavam as setas. São quatro causas, e qual delas é a sua decide se dá para consertar.

Você leva uma página para o Figma e chega tudo menos os ícones. Onde estavam as setinhas, a lupa e os indicadores de link externo, há quadrados vazios, manchas pretas ou nada.

Não é um bug só. Na web, ícones são desenhados de quatro maneiras completamente diferentes, e cada uma quebra de um jeito. Saber qual você tem na frente diz se dá para consertar e como.

Os quatro tipos e como cada um falha

1. SVG inline

O caso fácil. O ícone está escrito direto no HTML como um elemento <svg> com os paths ali dentro. Qualquer conversor que leia o DOM enxerga a geometria e entrega um vetor para o Figma.

Quando falha, geralmente é porque o conversor achatou alguma coisa: uma referência <use> a um símbolo definido em outro lugar, um filter de CSS, ou um preenchimento currentColor que fica sem cor ao sair da cascata.

2. Sprites SVG

Um arquivo guarda todos os ícones como <symbol>, e cada lugar onde um ícone aparece contém apenas uma referência.

<svg class="icon"><use href="/icons.svg#chevron-down" /></svg>

Eficiente na web, invisível para um conversor ingênuo. O elemento no DOM não tem paths. Lido ao pé da letra, sai um <svg> vazio, e é por isso que sprites chegam tantas vezes como caixas em branco do tamanho certo.

Resolver significa seguir a referência, buscar o arquivo de sprites, achar o símbolo pelo id e embutir a geometria. E se o sprite estiver em outra origem, essa busca precisa antes ser permitida.

3. Fontes de ícones

O ícone é um caractere numa fonte. Font Awesome, Material Icons e qualquer fonte de ícones interna funcionam assim: um elemento com uma classe, um pseudo-elemento ::before e uma propriedade content com um codepoint da área de uso privado do Unicode.

.fa-search::before { content: "\f002"; }

Duas coisas dão errado. Primeiro, o ícone mora num pseudo-elemento, que não está no DOM: por mais que você percorra a árvore de elementos, ele não aparece. Segundo, se um conversor até capturar como texto, ele chega no Figma como o caractere literal, e sem a fonte de ícones instalada o Figma desenha o que tiver de reserva: uma caixa vazia ou um glifo qualquer.

Daí vem o sintoma clássico de uma página importada cheia de retangulozinhos onde deveriam estar os ícones.

4. Ícones com máscara CSS

Merece um tópico próprio porque vem se tornando comum e falha de um jeito que parece sucesso. O elemento não tem conteúdo nenhum; tem uma cor de fundo e uma máscara.

.icon {
  background-color: currentColor;
  -webkit-mask-image: url(/icons/search.svg);
  mask-size: contain;
}

A forma mora na imagem de máscara e a cor mora no elemento. Um conversor que lê o fundo obtém um retângulo sólido na cor do ícone. Por isso esses chegam como quadrados pretos ou coloridos em vez de nada: a cor está certa e a forma sumiu.

Sites de documentação feitos com VitePress usam bastante esse padrão. Foi assim que topamos com isso: alguém avisou que num site de doc todos os ícones tinham sido importados como quadrados pretos.

Por que os conversores perdem esses casos

Porque cobrir os quatro significa fazer quatro coisas diferentes, e três delas exigem mais do que ler o DOM.

• Sprites exigem buscar o arquivo referenciado e extrair o símbolo.
• Fontes de ícones exigem ler os estilos do pseudo-elemento, resolver o codepoint e desenhar o glifo como vetor em vez de repassá-lo como texto.
• Ícones com máscara exigem buscar a imagem de máscara e aplicar a cor do elemento à forma resultante, não a um retângulo.

Um conversor que só percorre o DOM e copia o que encontra acerta o primeiro caso e falha em silêncio nos outros. É o comportamento comum, não a exceção.

Como saber qual é o seu caso

Abra a página, clique com o botão direito no ícone, inspecionar. Trinta segundos resolvem.

O que o Snapture faz com cada um

Os quatro são tratados, e vale ser específico, porque «damos suporte a ícones» toda ferramenta diz.

• SVG inline passa como geometria vetorial. Quando um SVG é complexo a ponto de o importador do Figma engasgar — máscaras aninhadas, filtros, foreignObject — ele é rasterizado. É uma degradação deliberada, não uma falha silenciosa.
• Sprites são resolvidos seguindo a referência <use>, buscando o sprite e embutindo a geometria do símbolo referenciado com a viewBox correta.
• Fontes de ícones são detectadas lendo o content computado do pseudo-elemento, e o glifo é desenhado como forma em vez de ir para o Figma como caractere. O resultado não depende de você ter a fonte instalada.
• Ícones com máscara CSS são resolvidos buscando a imagem de máscara e aplicando a cor do próprio elemento à forma resultante, então o ícone chega na cor real e não como retângulo preenchido.

Na medição publicada na página de medições, a home do Linear produziu 215 nós vetoriais e a da Stripe 153. Quase tudo isso é trabalho de ícone, e é aí que se decide a diferença entre um arquivo editável e um arquivo furado.

Se os ícones já estão quebrados num arquivo

Não há conserto para um quadrado preto rasterizado; a informação da forma nunca entrou no arquivo. Reimporte com uma ferramenta que resolva o seu caso.

A única exceção são as fontes de ícones. Se entraram como caracteres de texto e você tem a fonte instalada, o Figma vai desenhar certo na sua máquina — mas quebra para qualquer um que abrir sem essa fonte. Vale reimportar mesmo assim, em vez de entregar um arquivo que só funciona com você.

English · 한국어 · 日本語 · 简体中文 · 繁體中文 · Español · Português · Français · Deutsch · Русский · Italiano · Bahasa Indonesia