Supporting Maskable and Monochrome Icons in TWAs

A critical step in transitioning a Web App into a premium Android application is refining its visual presentation on the device launcher. When a user installs your application from the Google Play Store, they expect the app icon to behave exactly like native icons. On modern Android versions, this requires handling two distinct display concepts: adaptive icons (which rely on maskable assets) and themed icons (which rely on monochromatic assets).

If you build a Trusted Web Activity (TWA) without defining these assets properly, Android may display your icon with a generic white border or fail to apply system-wide colour themes. This guide explains how to format, design, and configure your icons in the Web App Manifest to ensure your TWA looks professional across all Android variants.

The Core Mechanics of Adaptive Icons

Android uses adaptive icons to standardise the shapes of different launcher icons across various device manufacturers. One phone manufacturer might prefer circular icons, another might use rounded squares, and another might use squircles. Instead of forcing developers to provide dozens of custom shapes, Android uses an adaptive mask.

An adaptive icon consists of two main elements: a background layer and a foreground layer. The system applies a mask over these layers to produce the desired shape. In the context of a Progressive Web App and a TWA, you supply this resource via the Web App Manifest by setting the purpose of an icon to maskable.

Defining the Safe Zone for Maskable Icons

When designing a maskable icon, you must ensure that all critical visual elements, such as brand logos or lettermarks, reside inside the designated safe zone. The safe zone is defined as a circle in the centre of the icon with a radius equal to 40% of the icon width.

The outer 10% on each edge of your icon design may be cropped away by the system mask depending on the device preferences. Therefore, you should never place text, branding, or key graphic detail near the outer boundary of your maskable asset.

Configuring the Web App Manifest for Icons

To tell the Android generation toolchain how to construct your app launcher assets, you must declare your icons inside the icons array of your Web App Manifest. You can define multiple purposes for an icon by separating them with a space, or create separate icon files for each purpose.

Below is a typical manifest configuration detailing both standard, maskable, and monochrome icon assets:

{ "name": "Premium Web Application", "short_name": "PremiumApp", "icons": [ { "src": "/icons/icon-192.png", "sizes": "192x192", "type": "image/png", "purpose": "any" }, { "src": "/icons/icon-maskable-512.png", "sizes": "512x512", "type": "image/png", "purpose": "maskable" }, { "src": "/icons/icon-monochrome-512.png", "sizes": "512x512", "type": "image/png", "purpose": "monochrome" } ] }

The value any tells the browser that the icon can be used on plain backgrounds, such as bookmark menus or task switchers. The value maskable notifies the Android generation process that this icon has been built with an integrated background and a 40% safe zone. The value monochrome is used for Android themed icons.

Supporting Monochrome and Themed Icons on Android

Starting with Android 13, users can toggle a system-wide themed icons preference. When enabled, all supporting app launcher icons are tinted using a colour scheme generated from the user's active wallpaper. This helps create a cohesive visual style across the system launcher.

To support this feature, your TWA must define a monochromatic icon. If your manifest contains an icon with the purpose monochrome, the Android compilation tool will convert this asset into an adaptive vector or highly compressed monochromatic layer. The operating system then dynamically applies the active user theme color to the solid shapes of your asset, while leaving the transparent areas empty.

Designing Monochrome Assets

Monochromatic icons require a different design approach compared to standard colourful brand icons. Keep the following rules in mind:

• Use absolute transparency for the background layer.
• Use a single, solid color (typically solid black) for the foreground shape.
• Avoid using color gradients, shadows, or semi-transparent opacities.
• Ensure the core shapes are bold and clear enough to remain readable at small launcher scales.

Icon Specification Requirements

The following table outlines the technical specifications for each icon type to ensure optimal rendering during the conversion process from a Web App Manifest to an Android package.

Testing and Verifying Your Assets

Before compiling your final signed APK or Google Play ready AAB, you should verify that your manifest configuration and icon assets are completely valid. This helps avoid visual defects, such as a squashed logo or a white ring clipping your icon.

Using Chrome DevTools for Icon Verification

You can inspect your maskable assets directly within your desktop web browser. Open your PWA in Google Chrome, activate the developer inspector panel, and navigate to the Application tab. Under the Manifest menu, scroll down to the Icons section.

Chrome displays a helper checkbox named Show only the minimum safe area for maskable icons. Activating this option overlays a circular mask on top of your assets, allowing you to instantly verify whether your brand mark is clipped or if it sits safely inside the boundary.

Validating Android Manifest Output

When PWAtoApp processes your Web App Manifest, the generator parses these entries to generate native Android resources. The maskable icon is used to generate the adaptive foreground and background configurations, and the monochrome icon is assigned as the template resource for the modern launcher. Testing your generated package on an emulator running a modern Android version is highly recommended to ensure the themed icon transitions correctly when you alter your device theme or background wallpaper.