O que é um ícone maskable
Quando alguém instala um web app, o launcher mostra o ícone no formato próprio dele: um círculo num celular, um quadrado arredondado ou uma gota em outro. Como um ícone comum, com fundo transparente, é encaixado nesse formato fica a critério da plataforma. Um ícone maskable é feito para ser cortado: ele preenche o quadrado inteiro com o próprio fundo, então qualquer formato que o launcher recorte resulta num ícone completo e colorido.
O web app manifest marca essa diferença com o membro purpose de cada ícone. A especificação do W3C lista três finalidades, any, maskable e monochrome, e um ícone sem purpose conta como any.
A zona segura: um círculo com raio de 40%
A especificação define onde a arte fica a salvo de qualquer máscara: "um círculo com centro no centro do ícone e raio de 2/5 (40%) do tamanho do ícone". Num ícone de 512 px, isso é um círculo centralizado de 410 px de diâmetro. O MDN descreve a mesma zona como um círculo cujo diâmetro é 80% do ícone, e o web.dev avisa que a borda externa, cerca de 10% de cada lado, pode ser cortada.
A imagem mostra o ícone maskable do pacote de exemplo abaixo. A primeira cópia tem a zona segura desenhada; as outras três são o mesmo arquivo sob uma máscara circular, uma de quadrado arredondado e uma de gota. Como a marca fica dentro do círculo, nenhuma máscara a corta, e só o fundo muda de formato.
O gerador de favicon encaixa a própria arte dentro do círculo, e não a caixa que a delimita, descontando a margem que você escolher. Por isso, uma marca redonda pode preencher quase toda a zona segura, enquanto uma foto quadrada fica menor, porque os cantos dela também precisam caber no círculo.
Purpose any ou maskable: por que dois arquivos
Um ícone pode declarar "purpose": "any maskable", e o artigo do web.dev sobre o manifest usa essa forma. Já o próprio artigo do web.dev sobre ícones maskable desaconselha isso: um ícone com margem para a máscara fica pequeno demais onde é exibido sem máscara. As fontes discordam, e dois arquivos evitam esse meio-termo. O ícone any mantém a transparência e a arte preenche o quadrado; o ícone maskable tem o fundo de ponta a ponta e a arte dentro da zona segura.
| Purpose | Fundo | Arte | Onde aparece |
|---|---|---|---|
any |
Transparente | Preenche o quadrado, descontada a margem | Em qualquer lugar onde o ícone aparece sem corte |
maskable |
A sua cor de fundo, de ponta a ponta | Dentro do círculo de 40% | Launchers que cortam ícones num formato |
Um manifest com os dois tipos
Este é o site.webmanifest do pacote de exemplo. Os caminhos dos ícones são relativos: a especificação resolve o src, assim como o start_url, a partir do URL do próprio manifest, então os ícones funcionam em qualquer pasta, desde que fiquem ao lado do manifest.
{
"name": "png2svg.art",
"short_name": "png2svg",
"icons": [
{
"src": "icon-192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "any"
},
{
"src": "icon-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "any"
},
{
"src": "icon-maskable-192.png",
"sizes": "192x192",
"type": "image/png",
"purpose": "maskable"
},
{
"src": "icon-maskable-512.png",
"sizes": "512x512",
"type": "image/png",
"purpose": "maskable"
}
],
"theme_color": "#0a2d8f",
"background_color": "#e8efff",
"display": "standalone",
"start_url": "/"
}
Inclua o link em todas as páginas com <link rel="manifest" href="/site.webmanifest">. A especificação define .webmanifest como a extensão registrada e recomenda servir o arquivo como application/manifest+json, embora qualquer tipo JSON seja aceito.
Os tamanhos não são aleatórios. O guia de instalabilidade do MDN, atualizado em setembro de 2026, diz que, entre outras condições, os navegadores Chromium só instalam um web app quando o manifest tem um nome ou nome curto, um start_url, um modo display e ícones de 192 e 512 px, e o site é servido por HTTPS. O Safari funciona de outro jeito: a equipe do WebKit escreveu, sobre o Safari 26, que não há requisitos de instalabilidade e que os ícones do manifest são usados quando o site os define. O MDN também sugere partir de uma arte de pelo menos 1.024 px de lado; um bitmap pequeno ampliado para 512 px não ganha detalhes.
Como testar um ícone maskable
No Chrome, abra o DevTools, vá em Application → Manifest e marque Show only the minimum safe area for maskable icons (com o DevTools em português, esses rótulos aparecem traduzidos). A seção de ícones passa a mostrar cada ícone maskable cortado na zona segura: se algo importante sumir ali, um launcher também pode cortar. A documentação do Chrome descreve essa opção. O web.dev também indica o Maskable.app, um site de terceiros onde você pode ver a prévia de um ícone sob várias máscaras. O teste final é o app instalado num celular de verdade.
Um exemplo real para baixar
Os ícones acima saem de uma execução do gerador de favicon com a marca deste próprio site (um SVG do nosso repositório, não o envio de ninguém), com margem de 8% e fundo #e8efff. São exatamente os arquivos que a ferramenta gera. Baixe o pacote de exemplo (ZIP) para ver cada arquivo com o README. Para o lado da aba do navegador do mesmo pacote, leia Favicon SVG, PNG ou ICO.