PWA icon requirements are not unified across browsers, despite manifest guidance

Why PWA Icons Still Differ by Platform

The Web App Manifest specification defines icon fields clearly: src, sizes, type, and purpose. In practice, every browser platform interprets these differently, and iOS Safari largely ignores the manifest entirely for installable icons.

MDN's manifest documentation explains the standard format, but platform-specific behavior means you cannot rely on a single icon declaration to work everywhere.

What the Manifest Standard Actually Covers

Required Icon Fields

{
  "icons": [
    {
      "src": "/icons/icon-192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "any"
    },
    {
      "src": "/icons/icon-512-maskable.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable"
    }
  ]
}

According to MDN:

• src: Path to the icon image (required)
• sizes: Icon dimensions as widthxheight (for raster images)
• type: MIME type like image/png or image/webp
• purpose: How the icon should be used (any, maskable, or any maskable)

Purpose Values Matter

• any: Standard icon use. The browser may crop or pad.
• maskable: Designed for safe-zone masking on Android. The browser will fit your icon into a shape (circle, rounded square, etc.) without cutting off critical visual elements.

Android Chrome Requirements

Core Sizes

MDN notes that Android Chrome typically expects at least:

• 192×192px for adaptive launcher icons
• 512×512px for Play Store listings and high-density displays

Maskable Icons

Android devices apply adaptive icons with shapes. A purpose: "maskable" icon should have a safe zone:

{
  "src": "/icons/icon-512-maskable.png",
  "sizes": "512x512",
  "type": "image/png",
  "purpose": "maskable"
}

Best practice for maskable:

• Center your logo within roughly 66.7% of the canvas
• Ensure no critical elements touch edges (they may be cropped)
• Test the safe zone using Chrome DevTools's "App manifest" validation

What Fails

• Missing 512×512px size: Chrome may fail installability checks
• Missing maskable version: Android often crops standard icons awkwardly on non-square shapes

iOS Safari's Manifest-Major Exception

Safari on iOS does not use the manifest for "Add to Home Screen" icons. Instead, it relies on:

<link rel="apple-touch-icon" sizes="180x180" href="/icons/apple-touch-icon-180.png">
<meta name="apple-mobile-web-app-capable" content="yes">
<meta name="apple-mobile-web-app-status-bar-style" content="black-translucent">
<meta name="apple-mobile-web-app-title" content="My App">

iOS Icon Size Reality

• 180×180px is the current standard (Retina devices use this for the home screen)
• Historically used 57×57, 72×72, 114×114, 144×144 (now deprecated)
• Safari ignores maskable purpose; it simply creates rounded squares

What Safari Breaks

• Splash screen behavior: Safari autogenerates a splash using your apple-touch-icon and the background color from your page. It does not respect manifest screenshots for native-style splash.
• Landscape splash support: Safari stretches portrait splashes to fit landscape mode; there's no manifest宣告 workaround.

Microsoft Edge Behavior

Edge (Chromium-based) follows Chrome's icon requirements closely but has platform-specific nuances:

• Windows taskbar icons: Prefer larger sizes (96×96px or higher) for clear rendering
• Start menu tiles: Can use tile-specific metadata if you want Windows-style branding
• Rating badge: For Xbox/Windows Store distributions, you may need additional assets with transparency

Edge respects the maskable purpose for adaptive icons on Windows 11's rounded layout.

Firefox Position

Firefox for Android supports automatic add-to-homescreen (A2HS) and uses the manifest's icon set:

• 192×192px minimum for installability
• Maskable support: Firefox can respect maskable purpose but may not apply adaptive shapes as aggressively as Chrome
• Desktop Firefox: Icon appears in the address bar and bookmarks menu; manifest largely affects mobile installs

Cross-Browser Icon Checklist

Minimum Set for Universal Coverage

| Size | Purpose | Android | iOS | Edge | Firefox | |------|---------|---------|-----|------|---------| | 192×192px | any | ✅ Required | ❌ Use apple-touch-icon | ✅ | ✅ Required | | 512×512px | any | ✅ Recommended | ❌ | ✅ | ✅ Recommended | | 512×512px | maskable | ✅ Strongly recommended | ❌ | ✅ | Optional | | 180×180px | apple-touch-icon | ✅ May fallback | ✅ Required | ❌ | ❌ | | 384×384px | any | Optional (HiDPI) | ❌ | Optional | Optional | | 1024×1024px | any | Play Store metadata | ❌ | Optional | ❌ |

Format Recommendations

| Format | Pros | Cons | Coverage | |--------|------|------|----------| | PNG | Universal support, good quality | Larger file size | 100% | | WebP | Smaller files, good quality | Older Safari may not support in manifest | Modern browsers | | SVG | Resolution-independent | Not supported in manifest by most platforms | Limited (use for inline/favicons) |

Safe bet: Stick to PNG for manifest icons. Use WebP for performance where you're confident of browser support.

Common Pitfalls

1. Missing the apple-touch-icon Link

Manifest alone won't install correctly on iOS.

2. Wrong Aspect Ratio

• Icons should be square (1:1). Non-square icons may be rejected or poorly cropped.
• Some platforms scale icons non-uniformly if you provide non-square sizes.

3. No Maskable Version on Android

Users on non-square icon shapes (Android 13+ devices) see poorly cropped icons without a maskable declaration.

4. Unoptimized Asset Sizes

Large icons (1024×1024px) in the manifest trigger slower downloads and may fail on metered connections. Reference large files in store listings, not the manifest.

5. Ignoring Background Color

Your manifest's background_color matters for splash screen generation on some platforms:

{
  "background_color": "#FF6B00"
}

Practical Implementation

Icon Generator Tools

• Maskable.app: Tests safe zones for maskable icons
• PWA Asset Generator (GitHub): Generates all required sizes from a source SVG/PNG
• Progressier PWA Tool: Offers manifest and icon generation guidance

Verification Steps

- Verify icon appears correctly in Chrome's install prompt - Check maskable safe zone in the preview

1. Chrome DevTools → Application → Manifest → Click "Add to home screen"

- Verify the 180×180px apple-touch-icon appears - Check splash screen generation

1. Safari → Share → Add to Home Screen (iOS)

- Verify icon renders clearly at scale

1. Edge → App installed → Taskbar check

- Confirm install prompt shows the correct icon

1. Firefox Android → Menu → "Add to Home Screen"

For PWA Marketplaces

If distributing through PWABuilder or app stores:

• Play Store: Maskable 512×512px icon + store-specific promotional graphics
• App Store: Requires full iOS app store icon suite (not PWA-relevant unless you wrap in TWA)
• Windows: Optional tile badge templates
• Samsung Internet: May request additional icon sizes for Galaxy Store

Standardization Gap

The W3C manifest provides a standard, but platform implementations differ meaningfully:

• Safari's legacy apple-touch-icon still dominates iOS installs
• Adaptive icon shapes (Android's Safe Zones) don't have manifest-level targeting
• Splash screens remain platform-specific (auto vs. declarative)

Workaround: Provide both manifest and apple-touch-icon metadata, generate maskable versions, and test on real devices.

Next Steps

1. Audit your current icon set against this checklist
2. Generate missing maskable and apple-touch-icon versions
3. Test install prompts on Chrome (Android), Safari (iOS), Edge, and Firefox
4. Add icon size monitoring to your build pipeline
5. Document platform-specific expectations for your team

Ignore a single size at your peril. Browsers forgive mistakes, but users notice poorly scaled, cropped, or missing icons—especially when competitors optimize for every platform.