On Android, a site's installed home-screen icon shows up shrunken inside a white circle rather than filling the shape. Which part of a web app manifest's `icons` entries controls that, and how do you author the asset?

## The two icon contracts Android's adaptive-icon system does not draw the icon you supply directly. It composites it into a shape that varies by device and launcher — a circle here, a squircle there, a rounded square elsewhere. That means the platform has to know something you have not told it: is your image already designed to fill the shape, or is it a standalone mark that needs framing? The manifest answers that per icon entry, via `purpose`. ```json "icons": [ { "src": "/icon-192.png", "sizes": "192x192", "type": "image/png" }, { "src": "/icon-512.png", "sizes": "512x512", "type": "image/png" }, { "src": "/icon-maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" } ] ``` - **`"any"`** (the default when `purpose` is absent) — a conventional icon. The platform will not crop it, so to fit it into an adaptive shape it scales it down and places it on a background plate. That plate is usually white or a system colour, which is precisely the reported symptom. - **`"maskable"`** — the asset is full-bleed and expects to be cropped. The platform applies its mask directly, and the icon fills the shape. - **`"monochrome"`** — a third defined value: a single-colour silhouette the platform may tint for themed-icon surfaces. Alpha carries the shape; colour is discarded. ## The safe zone A maskable icon is authored to a specific geometry. The guarantee the format gives you is a **safe zone**: a circle centred on the icon whose diameter is 80% of the icon's width. Anything inside that circle survives every mask; anything outside it may be cropped by some device's shape. So the authoring rules are: - **Bleed the background to all four edges.** No transparency at the corners — after cropping to a circle, transparent corners are invisible anyway, but on a mask that keeps more of the square they show as holes. - **Keep the mark inside the 80% circle.** In practice the logo occupies rather less than that, because a mark that exactly touches the safe-zone boundary looks cramped on the tighter masks. - **Design at 512×512** and export a PNG. One large maskable asset is normally enough; the platform downscales. The classic mistake is taking the existing padded 512 icon — mark centred with generous transparent margin — and just adding `"purpose": "maskable"`. Now the platform crops instead of padding, but the asset was already padded, so the visible mark ends up tiny inside the shape. The failure is the mirror image of the original bug, and it is why maskable normally means a *separate* asset. ## Why keep an `"any"` entry too `purpose` accepts a space-separated list, so `"purpose": "any maskable"` is legal and claims the asset works for both. Resist it unless the asset genuinely is designed for both, which is rare — an image that crops well is over-padded when used un-cropped, and vice versa. The robust arrangement is separate entries: a normal `any` icon for surfaces that frame it themselves (install prompts, app lists, some desktop launchers) and a dedicated `maskable` one for adaptive home-screen shapes. Browsers select per surface from the array, the same way icon links form a candidate set — declaring both means every surface has a correctly designed option. ## Diagnosing it The reported symptom is diagnostic on its own: **shrunken mark on a solid plate** means the platform decided it must frame your icon, i.e. no maskable entry matched. The opposite symptom — **the logo's edges cut off**, or a full-bleed image with its wordmark clipped — means a maskable entry exists but its content strays outside the safe zone. Check the manifest that is actually served, not the source file: a build step that rewrites icon paths and drops unknown members is a real way for `purpose` to vanish between the repo and production. And remember that changing the manifest does not restyle an already-installed shortcut on most platforms; verify with a fresh install. ## Scope note This is squarely an authoring-and-markup question — what the manifest declares and how the asset is drawn. iOS takes its home-screen icon from `<link rel="apple-touch-icon">` and applies its own rounding to an opaque square, so the maskable mechanism does not apply there; that asset is designed separately.