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

Inclua pelo menos PNGs de 192×192 e 512×512 no manifest.json. Para melhorar o recorte nos launchers Android, prepare também uma versão maskable de 512×512 e, se possível, de 192×192.

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

Os dois tamanhos formam a base de compatibilidade mais segura. O de 192×192 atende contextos menores, enquanto o de 512×512 é usado em telas de maior densidade e outras apresentações da aplicação.

Qual é a zona segura de um ícone maskable?

É o círculo central cujo raio corresponde a 40% da largura da imagem. Na prática, mantenha logo, texto e detalhes essenciais dentro dos 80% centrais, deixando cerca de 10% de margem em cada lado.

Devo usar purpose: "any maskable" no manifest?

Evite combinar os dois valores na mesma imagem. Um ícone maskable contém margem para o recorte e pode parecer pequeno quando usado como ícone comum. Declare arquivos separados com purpose: 'any' e purpose: 'maskable'.

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

Confira o link para o manifest, os caminhos das imagens, os tamanhos declarados e possíveis respostas 404. Depois de corrigir a configuração, remova a instalação anterior e instale novamente pelo Chrome.

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

Adicione ao manifest.json uma entrada separada com purpose: 'maskable'. A declaração resolve a verificação de configuração, mas você ainda precisa conferir visualmente se a imagem respeita a zona segura.

Posso usar SVG como ícone de PWA?

O suporte não é uniforme em todos os contextos de instalação. Use PNG em 192×192 e 512×512 como base e, se quiser, acrescente o SVG como opção complementar.

Qual deve ser o peso de cada arquivo?

Mantenha os arquivos tão leves quanto possível sem perder nitidez. Como referência prática, tente ficar abaixo de 100 KB por PNG e confirme o resultado visual depois da compressão.

Ícones de PWA podem ter transparência?

Ícones comuns com purpose: 'any' podem ser transparentes. As versões maskable devem ter fundo opaco até as bordas para evitar áreas cinzas ou brancas inesperadas depois do recorte.

Como testar um ícone maskable?

Use a visualização de ícones no painel Application do Chrome DevTools e confira a área segura mínima. Depois, teste a instalação em aparelhos ou launchers com formatos de recorte diferentes.

2025/08/28

Ícones para PWA e zona segura — guia completo

Referência prática de tamanhos 192×192 e 512×512, zona segura de 80%, ícones maskable e configuração do manifest.json.

Resposta rápida

Uma PWA deve incluir no manifest.json pelo menos dois PNGs: 192×192 e 512×512. Para Android, adicione uma versão maskable de 512×512 e mantenha todos os elementos importantes dentro da zona segura central de 80%.

Não reutilize o mesmo arquivo com purpose: "any maskable". Prepare uma imagem comum, que pode aproveitar todo o canvas, e outra maskable, com fundo opaco e margem para o recorte.

Tamanhos recomendados

Tamanho	Prioridade	`purpose`	Uso comum
192×192	Essencial	`any`	Instalação e tela inicial em tamanhos menores
512×512	Essencial	`any`	Telas de maior densidade e apresentação da aplicação
192×192 maskable	Recomendado	`maskable`	Launchers Android em contextos menores
512×512 maskable	Muito recomendado	`maskable`	Recortes adaptativos em alta densidade
144×144, 168×168, 384×384	Opcional	`any`	Densidades específicas quando o projeto exigir
1024×1024	Opcional	`any`	Material de alta resolução e usos futuros

Conjunto mínimo prático: 192×192 comum, 512×512 comum e 512×512 maskable.

O que significam `any` e `maskable`

`purpose: "any"`

O navegador usa a imagem como ela foi criada.
A transparência é preservada.
O desenho pode ocupar uma área maior do canvas.
Funciona como alternativa quando não há versão maskable.

`purpose: "maskable"`

O sistema recorta a imagem no formato adotado pelo launcher.
O arquivo precisa ter fundo opaco até as bordas.
Logo, texto e detalhes importantes devem permanecer dentro da zona segura.
O resultado pode aparecer como círculo, squircle, quadrado arredondado ou outro formato.

Por que evitar `any maskable`

Um ícone maskable inclui margem para sobreviver aos recortes. Se o mesmo arquivo for usado como ícone comum, essa margem continua visível e o logo pode parecer menor do que os ícones ao redor. Por isso, web.dev recomenda declarar entradas separadas.

Regra da zona segura de 80%

A especificação define a zona mínima como um círculo central com raio equivalente a 40% da largura do ícone. Uma forma simples de aplicar a regra é manter o conteúdo essencial dentro dos 80% centrais, deixando aproximadamente 10% de margem em cada lado.

Imagem completa:       512 × 512 px
Área central de 80%:   cerca de 410 × 410 px
Margem por lado:       cerca de 51 px
Zona garantida:        círculo com raio de 205 px

Dentro da zona segura: símbolo, letras e detalhes indispensáveis.
No anel externo: apenas fundo ou elementos que podem ser cortados.

O preview do launcher deve ser tratado como simulação. O arquivo exportado continua quadrado; quem aplica a máscara final é o sistema operacional.

Exemplo completo de `manifest.json`

{
  "name": "Your PWA Name",
  "short_name": "YourPWA",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "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-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    },
    {
      "src": "/icons/maskable-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

No HTML, aponte para o arquivo:

<link rel="manifest" href="/manifest.json">
<meta name="theme-color" content="#000000">

Os caminhos são relativos à URL do manifest. Abra cada endereço diretamente no navegador para confirmar que não retorna 404.

Como criar a versão maskable

Comece com um canvas quadrado de 512×512.
Preencha toda a imagem com uma cor de fundo opaca.
Centralize o símbolo dentro da zona segura de 80%.
Evite texto pequeno e linhas finas.
Visualize círculo, squircle, quadrado arredondado e gota.
Exporte em PNG e confira se o arquivo continua opaco até as bordas.

Uma imagem transparente pode ser usada como fonte, desde que o gerador a componha sobre um fundo opaco antes da exportação maskable.

Como testar

Chrome DevTools

Abra a PWA no Chrome.
Acesse DevTools → Application → Manifest.
Confira os ícones detectados e os caminhos carregados.
Ative a opção que mostra apenas a área segura mínima dos ícones maskable.
Confirme se nenhuma parte essencial desaparece.

Teste em aparelhos

Instale a PWA em mais de um dispositivo ou launcher. Compare pelo menos um recorte circular e um squircle ou quadrado arredondado. A cor final, a máscara e alguns efeitos visuais são definidos pelo sistema.

Erros frequentes

O manifest não possui ícone maskable

Causa: nenhuma entrada usa purpose: "maskable".

Correção: adicione uma entrada separada. A validação do manifest não confirma a qualidade visual da imagem, portanto confira a zona segura depois.

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

Verifique, nesta ordem:

se o HTML possui <link rel="manifest">;
se o manifest abre sem erro;
se os caminhos dos ícones retornam imagens;
se sizes, type e purpose correspondem aos arquivos;
se a instalação antiga foi removida antes do novo teste.

Aparece um fundo branco ou cinza

Causa: a versão maskable contém pixels transparentes.

Correção: gere novamente o arquivo com um fundo opaco que combine com a marca. A versão any pode continuar transparente.

O logo parece pequeno demais

Causa: o arquivo com margem de segurança está sendo usado também como ícone any.

Correção: use arquivos diferentes para os dois propósitos.

Observações por plataforma

Android

Launchers compatíveis usam a versão maskable e aplicam a própria forma. O resultado final pode variar conforme aparelho, launcher, papel de parede e tema.

iOS

O Safari usa apple-touch-icon quando ele é declarado. Para uma cobertura previsível, forneça também um PNG de 180×180:

<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png">

O Apple Touch Icon e o ícone maskable têm requisitos diferentes. Não presuma que um único arquivo dará o melhor resultado nos dois sistemas.

Windows e macOS

O Windows costuma usar a versão any em atalhos e na barra de tarefas. Versões atuais do macOS podem aproveitar um ícone maskable quando disponível e recorrer ao any como alternativa.

Checklist final

PNGs comuns de 192×192 e 512×512
PNG maskable de 512×512, com fundo opaco
Conteúdo essencial dentro da zona segura
Entradas any e maskable separadas
Caminhos testados sem 404
Manifest ligado no head
Teste no DevTools e em aparelhos reais

Ferramentas relacionadas

Gerador de ícones PWA — cria os tamanhos, o manifest e as versões maskable com prévia da zona segura.
Gerador de ícones maskable — ajuste fino do fundo, da escala e dos recortes do launcher.
Gerador de ícones de app — exporta pacotes para iOS e Android a partir da mesma imagem.

All Posts(inglês)