If you've ever pinned a web app to your Android home screen only to see your beautiful logo shrunk into a tiny, sad postage stamp inside a white circle, you've encountered the 'white box of shame.' This happens because Android uses adaptive icons, which can be circles, squares, or squircles depending on the device theme. If you don't provide a maskable icon favicon, the system forces your icon into a safe container, usually making it look amateurish.

In 2026, users expect web apps to feel indistinguishable from native ones. Look at Spotify or Slack; their icons fill the entire shape perfectly, regardless of whether the user has a Samsung, Pixel, or OnePlus. They achieve this by using the maskable purpose in their web app manifest. We're going to fix your icon today so it looks just as polished.

Prerequisites for a Professional Setup

Before touching any code, you need a source image. I strongly recommend starting with a 512x512 pixel PNG. While you might be tempted to use an SVG (which we love for standard tabs — see our SVG favicon guide), the Android manifest still handles PNGs most reliably for home screen placement. Your image should have a solid background color; transparency is actually the enemy here because the OS will fill it with whatever it wants.

Step 1: The 80% Safe Zone Rule

The biggest mistake developers make is putting important design elements right at the edges. A maskable icon is essentially a 'bleed' image. The system will mask (cut) the edges to fit a circle or a squircle. To ensure your logo doesn't get decapitated, you must keep all critical content within the inner 80% of the image. Imagine a circle in the middle of your square; if your logo fits in that circle, you're safe.

Step 2: Generate Your Assets

You don't need to manually crop five different sizes. You can use Mzu favicondl to ensure your base image is correctly formatted, but for the specific 'maskable' metadata, you need to ensure the file itself has enough padding. (I usually just add a 10% margin of the background color around my logo in Figma before exporting). If you're unsure about your current icon's health, check out our favicon audit guide to see how it renders across platforms.

Step 3: Update Your manifest.json

This is where the magic happens. You need to tell the browser that this specific icon is designed to be masked. Without the 'purpose': 'maskable' attribute, the browser treats it like a regular icon and adds that dreaded padding. Here is the exact structure you need in your manifest.json:

{
  'name': 'My Pro App',
  'icons': [
    {
      'src': '/icons/icon-192x192.png',
      'sizes': '192x192',
      'type': 'image/png',
      'purpose': 'any'
    },
    {
      'src': '/icons/maskable-512x512.png',
      'sizes': '512x512',
      'type': 'image/png',
      'purpose': 'maskable'
    }
  ]
}

Notice the 'purpose': 'any' for the smaller icon. This allows the browser to use it for non-masked contexts, like the task switcher. The 'maskable' entry is what Android will grab for the home screen. If you're working in a specific framework, our Next.js favicon guide covers how to integrate this into modern metadata files.

Step 4: Verification with DevTools

Don't just deploy and hope for the best. Open your site in Chrome on your desktop, hit F12, and go to the Application tab. On the left, click Manifest. Scroll down to the icons section and look for the 'Show only the minimum safe area for maskable icons' checkbox. If your logo stays fully visible when that circle appears, you've nailed it. If it gets cut off, go back to Figma and shrink your logo a bit more.

Common Pitfalls to Avoid

The most frequent face-palm moment is using a transparent background for a maskable icon. When the OS masks a transparent PNG, it often fills the background with a default grey or white that clashes with your brand. Always use a solid background color that matches your brand identity. Also, don't forget to link your manifest in your HTML <head> using <link rel='manifest' href='/manifest.json'>. It sounds obvious, but it's the first thing we check when an icon isn't showing up.

Another tip: don't overcomplicate the design. A favicon is tiny. If you have a complex logo, use a simplified version for the maskable icon. We talk more about this in our favicon vs logo comparison. Your goal is recognition, not showing off high-resolution gradients that nobody can see on a 2-inch screen.

Setting up a maskable icon favicon is one of those small 'quality of life' improvements that separates the hobbyists from the pros. It takes ten minutes but ensures your brand looks solid on the millions of Android devices out there. If you've finished this and realized your desktop icon is still a mess, head over to Mzu favicondl to generate a clean set of standard icons to match your new mobile ones.