PWA manifest icons and maskable safe zones explained

The icons listed in site.webmanifest are not tab icons. They are used when the site leaves the browser: the launcher entry after installation, the splash screen while the app boots, the card in the task switcher, the install dialog, and in some systems the app list and the share sheet. A page with a perfect favicon and no manifest icons will install with a generic placeholder.

Each entry carries src, sizes, type and purpose. Browsers pick by size: 192 px is the classic launcher size on Android, 512 px is used for splash screens and high-density displays, and Chrome will refuse to treat a site as installable if neither is available. Two entries is the practical minimum; a third and fourth appear once you add maskable versions.

Sizes in the manifest are declarations, not instructions. If you claim 512x512 and ship a 128 px file, the system will scale your 128 px image up and the result will look exactly as bad as that sounds. Generate the real pixels.

purpose tells the system how it may treat the image. any means the icon is used as-is, on whatever background the platform provides — this is the default and the reason unmarked icons end up inside a white circle: the launcher has no permission to crop, so it pads instead. maskable means the image is full bleed and the system may crop it to any shape it likes. monochrome means the image is a silhouette the system may recolour, used for badges and notifications.

A single entry can declare several purposes, and this is the trap. purpose: any maskable tells the system the same file is fine both ways, so your full-bleed artwork — which has a coloured background all the way to the edge — will also be used in places that expect a padded, transparent icon, like some desktop task bars. Keep two separate entries pointing at two separate files instead.

The rule of thumb: any icons keep their own padding and may be transparent; maskable icons have no padding, must be opaque to the edge, and keep their content well inside the middle. They are different pictures, not different labels for the same picture.

The maskable specification defines a safe zone: a circle centred on the icon with a diameter of 80% of the icon width. Anything inside that circle is guaranteed to survive every mask a platform applies; anything outside it may be cropped. On a 512 px icon that circle is 410 px across, leaving a 51 px ring on each side that you should treat as decoration only.

If your artwork is square — a monogram, a boxed glyph, most logos — the circle is stricter than it sounds. The largest square that fits entirely inside a circle of 80% diameter is about 56.5% of the icon width, because the square's diagonal, not its side, has to fit. That is why a maskable icon looks smaller than you expect: on 512 px the square artwork box is roughly 290 px.

Round artwork can be more generous and fill the whole 80% circle. Either way, the background has to run to all four edges: the mask cuts from the outside in, and a transparent corner becomes a visibly transparent notch on a launcher that uses a rounded-square mask.

Android's adaptive icon system lets the device manufacturer choose the shape: a circle on stock Pixel launchers, a squircle on several Samsung builds, a rounded square or a teardrop elsewhere. The same installed app therefore has a different silhouette on two phones sitting side by side, and your icon file has to look deliberate under all of them.

Launchers may also animate the icon — parallax when you swipe the home screen, a slight zoom when the app opens. Those effects move the artwork inside the mask by a few percent, which is another reason the safe zone exists and another reason not to push a wordmark to the edge.

When no maskable icon is provided, Chrome does not crop your any icon. It centres it on a white circle, scales it down and adds a shadow so it reads as an app. That fallback is safe but visually obvious — it is the look of an icon set that was never finished.

Safari has supported web app manifests for home-screen apps since iOS 16.4, but apple-touch-icon.png is still the file iOS looks for first, and the one older systems understand at all. Ship it regardless of how complete your manifest is.

iOS has no notion of maskable purpose. It applies one fixed squircle mask to every home-screen icon and does not support transparency; transparent pixels are composited onto black. In practice that means the Apple icon is a third variant — square, opaque, with your own comfortable padding — and not a copy of either manifest file.

Because iOS rounds for you, an Apple icon with pre-rounded corners ends up with a visible double curve at the edges. Draw the artwork square and let the system cut the shape.

The fastest check is in Chrome DevTools: the Application panel lists the parsed manifest, shows each icon it found and offers a maskable preview that applies a circular mask to the entry. If the preview clips your logo, so will a real launcher. Lighthouse's installability audit will also tell you when a maskable icon is missing entirely.

A preview with the safe circle drawn over the artwork — the kind IconBatcher shows next to the three common mask shapes — answers the question the panel cannot: not whether the icon survives one mask, but how much room is left before the next one bites. Toggle it while you adjust padding and you will find the right scale in seconds.

Finish with a real install on a real device. Install the app, look at the launcher, open the task switcher, and check the splash screen colour against your manifest background_color — a mismatched splash is the second most common thing people notice after a cropped logo.