Perché le icone spariscono quando importi una pagina web in Figma

Arriva tutto tranne le icone. Scatole vuote, quadrati neri, o rettangolini dove c'erano le frecce. Le cause sono quattro, e quale ti è capitata decide se è riparabile.

Porti una pagina in Figma e arriva tutto tranne le icone. Dove c'erano le frecce, la lente e i piccoli segni di link esterno ci sono quadrati vuoti, macchie nere, o niente.

Non è un bug solo. Sul web le icone si disegnano in quattro modi completamente diversi, e ognuno si rompe a modo suo. Sapere quale hai davanti ti dice se è riparabile e come.

I quattro tipi e il modo in cui ciascuno fallisce

1. SVG inline

Il caso facile. L'icona è scritta direttamente nell'HTML come elemento <svg> con i suoi path dentro. Qualsiasi convertitore che legga il DOM vede la geometria e può consegnare un vettore a Figma.

Quando fallisce di solito è perché il convertitore ha appiattito qualcosa: un riferimento <use> a un simbolo definito altrove, un filter CSS, o un riempimento currentColor che resta senza colore una volta uscito dalla sua cascata.

2. Sprite SVG

Un file contiene tutte le icone come <symbol>, e in ogni punto in cui compare un'icona c'è solo un riferimento.

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

Efficiente sul web, invisibile a un convertitore ingenuo. L'elemento nel DOM non contiene path. Letto alla lettera dà un <svg> vuoto, ed è per questo che gli sprite arrivano così spesso come scatole bianche della misura giusta.

Risolverli significa seguire il riferimento, scaricare il file degli sprite, trovare il simbolo tramite id e inserire la geometria. E se lo sprite sta su un'altra origine, quella richiesta deve prima essere permessa.

3. Font di icone

L'icona è un carattere in un font. Font Awesome, Material Icons e qualsiasi font di icone interno funzionano così: un elemento con una classe, uno pseudo-elemento ::before e una proprietà content con un codepoint dell'area a uso privato di Unicode.

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

Vanno storte due cose. Primo, l'icona vive in uno pseudo-elemento, che non sta nel DOM: puoi percorrere l'albero quanto vuoi, non c'è. Secondo, se un convertitore riesce comunque a catturarla come testo, arriva in Figma come il carattere letterale, e senza il font di icone installato Figma disegna quello che ha di ripiego: una casella vuota, o un glifo qualsiasi.

Da qui viene il sintomo classico della pagina importata piena di rettangolini al posto delle icone.

4. Icone con maschera CSS

Merita un paragrafo a sé perché sta diventando comune e fallisce in un modo che sembra riuscita. L'elemento non ha alcun contenuto: ha un colore di sfondo e una maschera.

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

La forma sta nell'immagine di maschera, il colore sta sull'elemento. Un convertitore che legge lo sfondo ottiene un rettangolo pieno del colore dell'icona. Ecco perché queste arrivano come quadrati neri o colorati invece che come niente: il colore è giusto e la forma è sparita.

I siti di documentazione basati su VitePress usano molto questo schema. È così che ci siamo imbattuti nel problema: qualcuno ci ha segnalato che su un sito di doc ogni icona era stata importata come un quadrato nero.

Perché i convertitori le perdono

Perché coprire tutti e quattro significa fare quattro cose diverse, e tre di queste richiedono più che leggere il DOM.

• Gli sprite richiedono di scaricare il file referenziato e di estrarne il simbolo.
• I font di icone richiedono di leggere gli stili dello pseudo-elemento, risolvere il codepoint e disegnare il glifo come vettore invece di passarlo come testo.
• Le icone con maschera richiedono di scaricare l'immagine di maschera e applicare il colore dell'elemento alla forma risultante, non a un rettangolo.

Un convertitore che si limita a percorrere il DOM e copiare ciò che trova risolve il primo caso e fallisce in silenzio sugli altri. È il comportamento comune, non l'eccezione.

Come capire in che caso sei

Apri la pagina, tasto destro sull'icona, ispeziona. Trenta secondi bastano.

Cosa fa Snapture con ciascuno

Tutti e quattro sono gestiti, e conviene essere precisi, perché «supportiamo le icone» lo dice qualsiasi strumento.

• L'SVG inline passa come geometria vettoriale. Quando un SVG è così complesso che l'importatore di Figma andrebbe in crisi — maschere annidate, filtri, foreignObject — viene rasterizzato. È un peggioramento deliberato, non un fallimento silenzioso.
• Gli sprite si risolvono seguendo il riferimento <use>, scaricando lo sprite e inserendo la geometria del simbolo referenziato con la viewBox corretta.
• I font di icone vengono rilevati leggendo il content calcolato dello pseudo-elemento, e il glifo viene disegnato come forma invece di finire in Figma come carattere. Il risultato non dipende dal fatto che tu abbia il font installato.
• Le icone con maschera CSS si risolvono scaricando l'immagine di maschera e applicando il colore dell'elemento stesso alla forma ottenuta, così l'icona arriva nel suo colore vero e non come rettangolo pieno.

Nella misurazione pubblicata sulla pagina delle misure, la home di Linear ha prodotto 215 nodi vettoriali e quella di Stripe 153. Quasi tutto quel lavoro è sulle icone, ed è lì che si decide la differenza tra un file modificabile e un file bucato.

Se in un file le icone sono già rotte

Per un quadrato nero rasterizzato non c'è riparazione; l'informazione sulla forma non è mai entrata nel file. Reimporta con uno strumento che risolva il tuo caso.

L'unica eccezione sono i font di icone. Se sono entrate come caratteri di testo e hai il font in locale, Figma le disegnerà correttamente sul tuo computer, ma si romperanno per chiunque apra il file senza quel font. Conviene comunque reimportare, invece di consegnare un file che funziona solo da te.

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