Docs/Branding/App Icons

App Icons

Customize PWA icons for your audio guide

AudioGuideKit is a Progressive Web App (PWA) that can be installed on mobile devices. When users add your tour to their home screen, they'll see your app icon—so make it count!

Default icons

AudioGuideKit includes a default headphones icon. You'll want to replace it with your own branding.

Icons are located in public/icons/ and the source SVG is public/favicon.svg.

Required icon sizes

The PWA manifest requires icons in multiple sizes:

FileSizePurpose
icon-72x72.png72×72Android legacy devices
icon-96x96.png96×96Android legacy devices
icon-128x128.png128×128Chrome Web Store
icon-144x144.png144×144Android legacy devices
icon-152x152.png152×152iOS devices
icon-192x192.png192×192Android / iOS
icon-384x384.png384×384Android splash screen
icon-512x512.png512×512Android maskable icon

Missing icons will prevent the PWA from installing properly on some devices.

Replacing icons

Option 1: Replace the SVG and regenerate (Recommended)

The easiest way is to replace the source SVG and regenerate all PNG sizes:

Create your icon

Design a square SVG icon (256×256 viewBox recommended). Keep it simple—it needs to be recognizable at 72px.

Replace the source

Replace public/favicon.svg with your design.

Generate PNGs

Run this command (requires ImageMagick):

cd public/icons
for size in 72 96 128 144 152 192 384 512; do
  magick -background none -density 300 ../favicon.svg \
    -resize ${size}x${size} icon-${size}x${size}.png
done

Install ImageMagick with brew install imagemagick (macOS) or apt install imagemagick (Linux).

Option 2: Use RealFaviconGenerator

For a web-based solution:

  1. Visit realfavicongenerator.net
  2. Upload your logo (512×512 or larger)
  3. Configure settings for each platform
  4. Download the package
  5. Extract files to public/icons/

Option 3: Use PWA Asset Generator

npx @vite-pwa/assets-generator --preset minimal public/favicon.svg

This automatically generates all required sizes.

Icon design guidelines

Keep it simple

Icons are tiny. Complex designs become unrecognizable blobs at 72px.

Use contrast

Test on both light and dark backgrounds. Your icon appears on home screens of all colors.

Respect the safe zone

For maskable icons (512×512), keep important content in the center 80%.

Avoid text

Text is illegible at small sizes. Use a symbol or logo mark instead.

Manifest configuration

Icons are configured in vite.config.ts under the PWA plugin. The default configuration:

manifest: {
  icons: [
    { src: '/icons/icon-72x72.png', sizes: '72x72', type: 'image/png' },
    { src: '/icons/icon-96x96.png', sizes: '96x96', type: 'image/png' },
    { src: '/icons/icon-128x128.png', sizes: '128x128', type: 'image/png' },
    { src: '/icons/icon-144x144.png', sizes: '144x144', type: 'image/png' },
    { src: '/icons/icon-152x152.png', sizes: '152x152', type: 'image/png' },
    { src: '/icons/icon-192x192.png', sizes: '192x192', type: 'image/png', purpose: 'any' },
    { src: '/icons/icon-384x384.png', sizes: '384x384', type: 'image/png' },
    { src: '/icons/icon-512x512.png', sizes: '512x512', type: 'image/png', purpose: 'maskable' }
  ]
}

The purpose: 'maskable' on the 512×512 icon tells Android to apply adaptive icon masking.

Testing your icons

Build the app

bun run build && bun run preview

Check the manifest

Open Chrome DevTools → Application → Manifest. Verify all icons load correctly.

Test installation

On a mobile device, visit your app and use "Add to Home Screen". Check that:

  • The icon appears correctly on the home screen
  • The splash screen shows your icon
  • The app switcher displays your icon

Troubleshooting

Icons not updating?

  • Clear the browser cache
  • Uninstall and reinstall the PWA
  • Service workers cache aggressively—you may need to increment the SW version

Icons look blurry?

  • Ensure source images are the correct size (not upscaled)
  • Use PNG format, not JPEG
  • Check that ImageMagick is using the -density 300 flag

Maskable icon looks wrong on Android?

  • The important content must be in the center 80%
  • Android applies different mask shapes (circle, squircle, etc.)
  • Test with Maskable.app before deploying