Sprites de símbolos SVG: preserve IDs, viewBoxes e cores

Um sprite de símbolos SVG armazena definições nomeadas de ícones em um arquivo SVG. Cada ícone visível usa um elemento <use> para referenciar a definição necessária. O empacotamento só funciona se o ID do fragmento, o sistema de coordenadas e as regras de pintura forem preservados ao passar dos arquivos individuais.

Comece com dois ícones antes de combinar uma pasta inteira. Neste passo a passo, uma folha usa um espaço de coordenadas quadrado e uma seta para a direita usa um largo. A folha aparecerá em duas cores sem duplicar seu traçado. A seta manterá suas proporções, em vez de ser forçada a caber na tela da folha.

Se seus ícones originais ainda precisam de formas, margens ou peso óptico consistentes, conclua primeiro o fluxo de preparação de kits de interface SVG. Um sprite organiza a arte; ele não a repara.

Crie duas definições nomeadas de símbolos

Salve este exemplo original como sprite.svg:

<svg xmlns="http://www.w3.org/2000/svg">
  <symbol id="pv-leaf" viewBox="0 0 24 24">
    <path fill="currentColor"
      d="M5 19C2 10 9 4 20 4C20 15 14 22 5 19Z"/>
  </symbol>
  <symbol id="pv-arrow" viewBox="0 0 32 16">
    <path fill="currentColor"
      d="M2 5H21V1L30 8L21 15V11H2Z"/>
  </symbol>
</svg>

O nome da folha é pv-leaf; o da seta é pv-arrow. Esses são os identificadores que a página solicitará. A MDN descreve symbol como uma definição reutilizável de gráficos instanciada por use. Um arquivo contendo apenas símbolos pode parecer vazio quando aberto sozinho porque as definições não são renderizadas diretamente.

Mantenha o viewBox junto da arte que ele descreve. Aqui, a folha usa 0 0 24 24, e a seta usa 0 0 32 16. Esses números definem limites de coordenadas, não um tamanho obrigatório de exibição. Alterar os limites da seta para 24 por 24 sem ajustar sua geometria não é normalização. Consulte a referência de viewBox da MDN para o mapeamento entre coordenadas e área de visualização.

Para uma família existente de ícones, mantenha a grade acordada. As formas diferentes daqui demonstram outro ponto: o empacotamento deve preservar o sistema de coordenadas já aprovado. Se uma seta deve seguir a extremidade de uma linha ou curva, use marcadores SVG para pontas de seta personalizadas alinhadas para definir seu ponto de anexação e direção.

Referencie o sprite em uma página

Coloque sprite.svg, sua página HTML e icons.css no mesmo diretório servido. Comece com uma prévia HTTP de mesma origem para que uma restrição de arquivo local ou outro servidor não esconda um erro básico de referência.

Adicione estas regras a icons.css e carregue essa folha de estilos na página:

.icon {
  display: inline-block;
  width: 1.5rem;
  height: 1.5rem;
  vertical-align: middle;
}
.icon-wide {
  width: 3rem;
}
.garden-button {
  display: inline-flex;
  align-items: center;
  gap: 0.5rem;
  color: #167d8d;
}

Depois, adicione estas instâncias ao body do HTML:

<button class="garden-button" type="button">
  <svg class="icon" aria-hidden="true" focusable="false">
    <use href="./sprite.svg#pv-leaf"></use>
  </svg>
  Garden
</button>
 
<svg class="icon icon-wide" role="img" aria-label="Right direction"
  style="color: #233b63">
  <use href="./sprite.svg#pv-arrow"></use>
</svg>

A parte antes de # localiza o arquivo; a parte depois seleciona o símbolo. O atributo moderno é href. A referência de use da MDN documenta referências externas e alerta que navegadores podem recusar carregamentos entre origens. Não suponha que mover um sprite que funciona para uma CDN é uma troca direta; teste o local real de entrega.

No tamanho padrão de fonte raiz do navegador, essas regras dão à folha uma caixa de 24 por 24 pixels CSS e à seta uma de 48 por 24. Os tamanhos usam rem, então outro tamanho de fonte raiz os altera. Compare os ícones dentro do componente real e também em uma prévia ampliada: uma caixa correta ainda pode conter arte com margens excessivas.

O botão acima demonstra a apresentação e a nomeação do ícone. Adicione o manipulador de ação do próprio aplicativo ao usá-lo em um produto.

Escolha a regra de pintura antes de combinar arquivos

Os dois traçados do exemplo usam explicitamente fill="currentColor". Isso permite que uma instância consumidora use o color do CSS ao redor: o botão fornece verde-azulado, e a seta fornece azul-marinho. A referência de color explica que currentColor pode fornecer o valor usado por preenchimentos e contornos.

Para a segunda aparição da folha, use a mesma referência pv-leaf e altere o color da instância para coral. Não duplique o traçado apenas para criar outra cor de tema.

Não substitua todos os preenchimentos de um logo multicolorido por currentColor. Isso descarta a paleta por definição. Se o arquivo já muda de cor antes do empacotamento em sprite, use o guia de solução de problemas de cor SVG para isolar esse problema anterior.

Evite também construir uma API de sprite com base em seletores arbitrários da página alcançando traçados referenciados. A MDN observa limitações de estilo para conteúdo clonado em use. Coloque o comportamento de pintura pretendido na arte original e teste o consumidor.

Evite IDs duplicados dentro da arte

Nomes únicos de símbolos são necessários, mas um SVG exportado pode conter mais IDs dentro dele: gradientes, máscaras, traçados de recorte ou outras definições referenciadas. A MDN exige que cada id SVG seja único dentro de sua árvore de nós. Dois arquivos antes separados podem violar essa regra quando combinados.

Por exemplo, suponha que uma exportação de folha e uma de emblema contenham um gradiente chamado paint0. Adicione um prefixo ao ID do gradiente da folha e à referência correspondente em conjunto:

O fragmento ainda precisa apontar para a definição pretendida. Os exemplos de fill da MDN mostram essa relação entre um ID de gradiente e url(#...). Dê ao emblema seu próprio prefixo, em vez de fazer as duas referências apontarem para o gradiente da folha.

Nosso exemplo de dois traçados não tem definições aninhadas, o que o torna uma primeira verificação útil. Para uma exportação real, inventarie todos os IDs e referências locais antes de combinar arquivos. Depois que qualquer otimizador ou gerador for executado, repita esse inventário no sprite entregue. Renomear apenas o símbolo externo não resolve IDs internos duplicados.

Nomeie cada instância visível em seu contexto

A folha ao lado da palavra visível “Garden” repete uma informação que o botão já fornece. Seu SVG usa aria-hidden="true", deixando o texto do botão fornecer seu nome. Mantenha esse atributo no SVG decorativo, não no botão interativo. As orientações de aria-hidden da MDN abordam conteúdo decorativo e alertam contra esconder elementos que podem receber foco.

A seta independente tem outro papel: ela comunica direção sem texto próximo. Seu SVG externo usa role="img" e aria-label="Right direction", seguindo as orientações da MDN para nomear uma imagem SVG incorporada.

Decida o rótulo no ponto de uso. Uma folha reutilizável pode significar “Jardim”, “À base de plantas” ou apenas decoração em interfaces diferentes. Teste o nome acessível do componente final com as ferramentas de inspeção de acessibilidade do navegador e a tecnologia assistiva de destino; um símbolo reutilizável sozinho não estabelece esse contexto.

Confira o sprite entregue, não apenas os arquivos de origem

Conferimos este exemplo original em uma página de teste no navegador de mesma origem. A folha foi renderizada em verde-azulado e coral, a seta larga manteve sua forma e um fragmento deliberadamente ausente produziu uma caixa de ícone vazia. A árvore de acessibilidade do navegador expôs o botão Garden e a seta nomeada. Essa é uma verificação deste exemplo, não uma certificação entre navegadores ou leitores de tela.

Use o mesmo pequeno conjunto de verificações após o empacotamento:

1. Arquivo: confirme que a página carrega o sprite pretendido pela URL final.
2. Fragmento: compare cada fragmento de href com o ID do símbolo entregue, incluindo maiúsculas e minúsculas.
3. Limites: compare o componente pequeno e a arte ampliada em busca de recorte, margens e proporção.
4. Pintura: renderize um ícone de uma cor em duas cores de tema e inspecione separadamente qualquer arte com cores fixas.
5. Referências internas: confira se referências prefixadas de pintura, máscara e recorte ainda são resolvidas após a otimização.
6. Significado: inspecione o nome de cada componente interativo e o rótulo de cada imagem independente significativa.

Se o arquivo carrega, mas uma instância está vazia, confira o fragmento antes de alterar a geometria. Se a mesma arte também está vazia como SVG comum, siga as verificações mais amplas de SVG em branco. Se ela parece pixelada quando ampliada, inspecione se há uma imagem raster incorporada antes de supor que o sprite causou o problema.

Quando o único arquivo original é um ícone PNG

Se um ícone simples existe apenas como PNG, converta esse PNG para SVG com o PerfectVector antes de empacotá-lo. Inspecione a silhueta, os vazados e as regiões de cor resultantes em relação à imagem original e aprove seus limites de coordenadas e sua regra de pintura. Por fim, dê à arte aprovada IDs estáveis e adicione-a ao sprite. A conversão fornece arte vetorial; ela não escolhe seus nomes de símbolos, semântica de componentes nem arquitetura de entrega.

Se um SVG original limpo existe, use-o. Vetorizá-lo novamente introduz outra etapa de recuperação de formas sem resolver uma referência quebrada de fragmento. Consulte os guias de edição e preparação de SVG quando o problema restante está na arte, e não no empacotamento.

Perguntas frequentes

Por que meu sprite SVG está vazio quando o abro diretamente? Um sprite que contém apenas definições symbol não exibe diretamente esses símbolos. Teste-o por uma instância SVG use com o caminho de arquivo e o ID de fragmento corretos antes de tratar o documento vazio como arte danificada.

Todos os símbolos precisam do mesmo viewBox? Não. Preserve cada sistema aprovado de coordenadas ao empacotar. Ícones que compartilham uma grade de sistema de design podem usar limites iguais, mas um símbolo largo não se torna um ícone quadrado apenas por alterar os números de seu viewBox.

Por que mudar a cor da página não recolore meu ícone? Confira a regra de pintura da arte original. Um preenchimento fixo é diferente de um traçado criado com currentColor. Preserve a arte multicolorida intencional e escolha explicitamente quais preenchimentos ou contornos devem herdar a cor da instância.

Posso colocar o sprite em outro domínio? Não suponha que uma referência use externa funcionará entre origens. Comece com um exemplo de mesma origem e teste o servidor real e os navegadores de destino antes de alterar a entrega. Um exemplo local bem-sucedido não comprova suporte entre origens.

Fontes

1. MDN — symbol — Definições reutilizáveis e renderização indireta.
2. MDN — use — Fragmentos externos, limites de estilo e restrições de origem.
3. MDN — viewBox — Relação entre limites de coordenadas e área de visualização.
4. MDN — color — currentColor como entrada para pintura SVG.
5. MDN — id — Unicidade de identificadores na árvore do documento.
6. MDN — fill — Referências a servidores de pintura, como URLs de gradientes.
7. MDN — aria-hidden — Conteúdo decorativo e cuidados com elementos que podem receber foco.
8. MDN — papel img — Um SVG externo rotulado para uma imagem significativa.

Comece com dois ícones aprovados e teste seus nomes, limites e cores no componente real. Se uma imagem original existe apenas como imagem raster adequada, recupere seus traçados SVG, inspecione a arte e adicione o resultado aceito ao sprite.