Maskable PWA Icons: How to Keep Your Logo From Getting Cropped

A square app icon does not necessarily appear as a square. Operating systems apply circles, squircles, rounded rectangles, and other masks so installed apps share a consistent launcher shape. If a PWA provides ordinary artwork with no adaptive safe area, the platform may shrink it onto a plate or crop off important edges.

The web app manifest solves this with the maskable icon purpose. A maskable asset is intentionally designed as a full-bleed square whose critical content survives any conforming mask.

Understand the guaranteed safe zone

The Web Application Manifest specification defines the maskable safe zone as a circle centered in the icon with a radius equal to two-fifths, or 40%, of the icon's smaller dimension. On a 512×512 icon, that circle has a 204.8-pixel radius and a 409.6-pixel diameter.

Everything essential—the recognizable symbol, important letterforms, and critical internal gaps—should fit inside that circle. Artwork outside it may be visible under a generous mask, but it is expendable. Use the outer region for background color, texture, or nonessential extension of the composition.

The safe zone is not a recommendation to draw a visible circle. It is a guarantee used while composing the square source. A rounded-square platform may reveal more than the circle; a circular mask will reveal approximately the guaranteed center.

Regular and maskable icons serve different jobs

A regular icon with purpose: "any" can preserve transparency and a custom silhouette. When a platform needs to fit it into a standardized shape, it may shrink the artwork and add a background. That can make the icon look smaller than neighboring installed apps.

A maskable icon usually has an opaque, full-bleed background and a symbol scaled to the safe zone. The platform can crop the full canvas without adding an awkward plate. If you simply label a transparent edge-to-edge logo as maskable, the crop may remove corners or lettering.

Prefer separate files:

• Regular 192×192 and 512×512 PNGs for general manifest use.
• Maskable 192×192 and 512×512 PNGs with a full-bleed background and safe composition.
• An optional monochrome asset designed as an alpha mask for surfaces that request it.

The artwork should remain recognizably related, but it does not need identical bounds. Responsive icon design is legitimate: simplify tiny details, enlarge the central symbol, and remove a wordmark that cannot survive launcher size.

Build the maskable source

Start with a square vector master at a convenient coordinate system such as 512×512 or 1024×1024. Add an opaque background that reaches every canvas edge. Place a safe-zone circle at the center with an 80% diameter, then fit the essential mark inside it.

Do not scale a horizontal company lockup until the words become microscopic. Use an approved symbol, monogram, or compact app mark. Increase small counters and remove fine strokes that collapse at 48 or 72 pixels. Test both a full-color version and a simplified form if the identity system supports one.

Export exact PNG sizes from the vector source. Avoid making a 192-pixel file by resizing an already rasterized 512-pixel export several times; generate each derivative from the clean master so the resampling path is controlled.

Declare both icon purposes

A practical manifest block looks like this:

{
  "name": "Example App",
  "short_name": "Example",
  "start_url": "/",
  "display": "standalone",
  "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/icon-maskable-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable"
    },
    {
      "src": "/icons/icon-maskable-512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

Paths are resolved relative to the manifest URL when they are not root-relative. Verify the final deployed path rather than only the source directory. Each response should return status 200 and the correct image content type. Content Security Policy can also affect whether the browser is allowed to fetch an icon, so include its origin in the document's image policy when needed.

Common maskable-icon failures

The logo touches the canvas edge. Corners or lettering disappear under circular and rounded masks. Move essential artwork into the safe circle and let only the background bleed.

The source has transparency around the plate. A maskable icon is most predictable with an opaque background filling the canvas. Transparent corners can expose an unexpected platform color.

The regular icon was replaced. A generously padded maskable composition can look too small on surfaces that do not crop it. Retain any icons for those contexts.

The wordmark is unreadable. Launcher icons are identification marks, not miniature headers. Use the symbol and let the app label carry the name.

The manifest describes the wrong dimensions. The sizes value should match the actual raster pixels. Renaming a 256×256 file to icon-512.png does not create a 512-pixel asset.

Test masks and real installs

Preview the source under a circle, a tight squircle, and several rounded rectangles. Look for clipped strokes, uneven optical centering, and backgrounds that reveal unintended seams. Then install the PWA on supported test devices. Inspect the launcher, task switcher, settings, install prompt, and any generated splash surface.

Browsers and operating systems choose icons for their own contexts, so a manifest that parses is only the beginning. Keep the vector master, regular files, maskable files, manifest, and a small validation note together. Your logo should look intentionally composed no matter which approved mask the platform applies.