Ícones para PWA e zona segura — guia completo

Resposta rápida

O PWA Icon Generator exporta PNGs de 192 e 512 px e um manifest. Esses tamanhos são um ponto de partida do fluxo da ferramenta. A especificação do manifest não exige universalmente esse par de arquivos; ter ícones não torna um site uma PWA completa e instalável. A instalação também depende da página e da versão do navegador.

Tamanhos recomendados

A documentação de promoção de instalação do Chrome inclui 192 e 512 px, HTTPS e outras condições. Isso pertence ao fluxo do navegador, não é exigência universal da especificação do manifest. A instalação manual pode seguir critérios diferentes. Um original maior não resolve detalhes ilegíveis sozinho.

O que significam any e maskable

Use any para a arte padrão sem máscara. Use maskable para recortes do launcher, com fundo intencional e detalhes essenciais no círculo seguro. Um logo transparente esticado até as bordas não fica automaticamente adequado aos dois usos.

purpose: "any"

Arte padrão sem máscara. Transparência depende do desenho e do contexto, não é uma exigência geral.

purpose: "maskable"

Arte preparada para recortes, com fundo intencional e detalhes essenciais dentro do círculo seguro.

Por que evitar any maskable

O título preservado trata da escolha de arte, não de uma sintaxe inválida. A sintaxe é válida. Combine somente se a mesma arte funcionar com e sem máscara. Arquivos separados são uma recomendação de design para controlar as margens, não uma proibição da sintaxe.

Regra da zona segura de 80%

Em uma imagem de 512 px, o círculo tem centro (256, 256) e raio 204,8 px, com diâmetro de 409,6 px. Não é um quadrado seguro de 410 px. Os cantos de um quadrado de 409,6 px ficam a aproximadamente 289,6 px do centro, fora do raio seguro.

Um símbolo quadrado centralizado de cerca de 289 px cabe inteiro nesse círculo. É um exemplo conservador para arte quadrada, não uma regra para reduzir todas as formas ao mesmo tamanho. Confira textos, cantos e detalhes com a sobreposição circular.

Os 80% são o diâmetro do círculo, não uma garantia para os cantos de um quadrado. Veja a especificação.

Exemplo completo de manifest.json

O exemplo presume que os arquivos maskable estão em /icons/ e que você gerou os dois PNGs comuns separadamente. Cada URL deve apontar para um arquivo real.

{
  "name": "Example app",
  "short_name": "Example",
  "start_url": "/",
  "display": "standalone",
  "icons": [
    { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" },
    { "src": "/icons/icon-512.png", "sizes": "512x512", "type": "image/png", "purpose": "any" },
    { "src": "/icons/maskable-icon-192x192.png", "sizes": "192x192", "type": "image/png", "purpose": "maskable" },
    { "src": "/icons/maskable-icon-512x512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }
  ]
}

<link rel="manifest" href="/site.webmanifest">

A sintaxe do manifest permite purpose: "any maskable". Separar as imagens é uma recomendação de design: a margem maskable pode deixar o ícone pequeno quando exibido sem máscara. Não é uma proibição de sintaxe.

Como criar a versão maskable

Baixe o SVG original, abra o Maskable Icon Generator e escolha margem de 25%, escala de 100% e fundo #ffffff. A arte ocupará metade da largura da tela e caberá no círculo. Compare com o ZIP realmente exportado.

Não incorpore um recorte redondo ao PNG: o launcher aplica a própria forma. Um fundo sólido evita o preenchimento inesperado de áreas transparentes.

Como testar

Confira primeiro os arquivos publicados; ícone de aba e ícone instalado são verificações distintas.

Chrome DevTools

Na página publicada, abra Application → Manifest no Chrome. Confira o manifest, as imagens carregadas, dimensões e erros reais; ative a prévia da área maskable quando disponível. Veja o guia PWA do DevTools. Registre a versão do navegador em vez de depender de um nome antigo do Lighthouse.

Teste em aparelhos

Instale em um celular atendido pelo projeto e confira os contextos com e sem recorte. Favicon de aba é outra verificação. Antes de remover e reinstalar o app, considere dados locais e login; reinstalação é um diagnóstico, não uma estratégia geral de atualização.

Erros frequentes

Registre o diagnóstico, a versão do navegador e a URL pública antes de refazer o desenho.

O manifest não possui ícone maskable

Confira o diagnóstico e a versão do navegador. Verifique purpose maskable, uma imagem acessível e a arte no círculo. Um aviso específico do Lighthouse pode não existir em outras versões.

O ícone não aparece depois da instalação

Confira o manifest da página de início, as imagens, dimensões, subdiretório, redirecionamentos e autenticação. Depois investigue critérios de instalação e cache ou app já instalado.

Aparece um fundo branco ou cinza

Confira transparência, purpose selecionado e recorte. Use fundo opaco intencional no maskable e confira o launcher real.

O logo parece pequeno demais

Confira se a arte maskable com margem também está sendo usada sem máscara. Separe uma versão padrão mais cheia quando necessário.

Observações por plataforma

Teste o navegador e o caminho de instalação usados pelo projeto.

Android

Compare mais de um recorte simulado e confira um launcher real. O manifest PWA não é o pacote nativo com primeiro plano e fundo adaptativos. Para apps nativos, consulte o guia Android.

iOS

Confira o ícone do site na tela inicial nas versões atendidas. O link apple-touch-icon é uma opção separada, descrita no guia arquivado de Web Clip da Apple. A ferramenta Apple Touch gera PNG opaco de 180 px. Não aplique a regra maskable de PWA como requisito de assets iOS nativos.

Windows e macOS

Instale no navegador usado pelo projeto e confira a área de trabalho, a barra de tarefas ou o Dock. Esses locais podem usar outros recortes. Ter ícones no manifest não exige antigas declarações de blocos msapplication-* em todo site moderno.

Checklist final

Guarde o original, abra a menor imagem, confira todas as URLs, revise o círculo e teste em aparelhos relevantes. Separe as artes padrão e maskable e publique manifest e arquivos juntos. Essas verificações ajudam na implementação, sem garantir instalação ou exibição em todas as plataformas.

Quais tamanhos devo usar para os ícones de uma PWA?

Comece com PNGs de 192×192 e 512×512 para este fluxo. O Chrome lista o par na promoção de instalação; a especificação do manifest não o impõe a toda instalação. Prepare arte maskable separada quando necessário.

Preciso mesmo dos arquivos de 192×192 e 512×512?

Manter os dois é uma base prática e atende esse critério de promoção do Chrome. As regras podem variar por navegador e instalação manual; os arquivos sozinhos não completam uma PWA instalável.

Qual é a zona segura de um ícone maskable?

A zona segura é um círculo central com raio de 40% da menor dimensão. Os 80% são o diâmetro, não um quadrado seguro; confira os cantos e detalhes na sobreposição circular.

Devo usar purpose: "any maskable" no manifest?

A sintaxe é válida. Combine somente se a mesma arte funcionar com e sem máscara. Arquivos separados são uma recomendação de design para controlar as margens, não uma proibição da sintaxe.

Por que o ícone da PWA não aparece no Chrome para Android?

Confira o manifest da página de início, as imagens, dimensões, subdiretório, redirecionamentos e autenticação. Depois investigue critérios de instalação e cache ou app já instalado.

Como corrigir o aviso de que o manifest não possui ícone maskable?

Confira o diagnóstico e a versão do navegador. Verifique purpose maskable, uma imagem acessível e a arte no círculo. Um aviso específico do Lighthouse pode não existir em outras versões.

Posso usar SVG como ícone de PWA?

Depende do navegador e do contexto. Mantenha PNG onde precisar de raster e teste SVG na instalação real; exibir SVG dentro da página não comprova suporte no launcher.

Qual deve ser o peso de cada arquivo?

Reduza o arquivo preservando contornos e texto e meça a entrega na conexão de destino. Não há um limite universal de 100 KB; quantização não equivale a compressão sem perdas.

Ícones de PWA podem ter transparência?

A versão padrão pode usar transparência conforme o desenho. Para maskable, prefira um fundo opaco intencional para evitar preenchimento inesperado depois do recorte.

Como testar um ícone maskable?

Confira Application → Manifest no Chrome DevTools, quando disponível, e depois aparelhos ou launchers atendidos. A simulação de formas não certifica todas as telas.

Ferramentas relacionadas

A geometria e os valores de purpose estão na especificação Web App Manifest. O guia maskable do web.dev explica a arte separada e a inspeção no DevTools. Recursos adaptativos de apps Android usam outro fluxo: veja Android Adaptive Icons. Envie correções pela página Sobre e contato.