A launcher icon can look perfect in a square design export and lose half its personality inside a circle. That is not the launcher being careless—it is the contract. Android owns the outer shape. We provide layers with enough breathing room, and the system composes, masks, animates, and sometimes recolors them.

What makes an icon adaptive

  • Foreground layer: the brand mark or artwork that can move independently for launcher effects.

  • Background layer: a full-bleed color or drawable behind the foreground.

  • Monochrome layer: a single silhouette the system can tint for themed icons.

  • OEM/launcher mask: circle, squircle, rounded rectangle, or another consistent system shape applied at display time.

  • Legacy fallback: density-specific icon assets for Android 7.1/API 25 and lower or surfaces that do not use the adaptive resource.

  • Store listing icon: a separate 512 × 512 Google Play asset with its own processing rules.

The geometry that prevents clipping

  • Design each adaptive layer on a 108 × 108 dp canvas.

  • Keep the important logo within the centered 66 × 66 dp safe zone that masks do not clip.

  • Android currently recommends a logo at least 48 × 48 dp and no larger than 66 × 66 dp.

  • The outer 18 dp on each side exists for masking and visual effects such as parallax/pulsing.

  • Let background artwork reach every canvas edge; transparent gaps can reveal unintended launcher treatment.

  • Do not bake a mask or outer drop shadow into the layer boundary.

Prepare three intentional assets

Foreground

  • Use a vector when the artwork can be represented reliably; vectors scale cleanly and reduce density variants.

  • Keep critical letters, faces, and brand details inside the safe zone.

  • Use transparency around the mark, but avoid delicate details that vanish at launcher size.

  • Avoid a pre-rendered outer shadow/mask; launcher effects need layer freedom.

  • Check high-contrast edges in light, dark, and tinted environments.

Background

  • Use a solid color resource for simple backgrounds or a full-bleed drawable for intentional artwork.

  • Fill all 108 × 108 dp so motion and alternate masks never expose empty pixels.

  • Choose contrast that keeps the foreground legible at small sizes.

  • Avoid embedding the foreground logo again in the background.

  • Test gradients and bitmaps for banding, scaling, and compression artifacts.

Monochrome

  • Provide a single-color silhouette; the launcher supplies the actual tint.

  • Preserve recognizability without relying on brand color, gradients, or internal shading.

  • Keep it in the same safe zone and optical balance as the color mark.

  • A separate simplified drawable is often better than reusing a complex color foreground.

  • Android 13/API 33 introduced themed icons; current Android documentation also notes automatic theming behavior starting with Android 16 QPR 2 when an app omits its own layer, but a designed monochrome asset gives you control.

Generate icons with Image Asset Studio

  1. Open the Android view in the Project tool window.

  2. Right-click the application module’s res folder and select New → Image Asset.

  3. Choose Launcher Icons (Adaptive and Legacy).

  4. On Foreground Layer, select Image, Clip Art, or Text and choose the source asset.

  5. Scale and position it while watching circle, squircle, rounded-square, square, full-bleed, legacy, and store previews.

  6. Set the Background Layer to a color or image that fills the canvas.

  7. Configure the monochrome/themed layer offered by the current Studio version and preview wallpaper/system UI modes.

  8. Keep a stable resource name such as ic_launcher; choose the intended source set (main, debug, release, or another variant).

  9. Review the generated-file summary, resolve intentional overwrites, and select Finish.

  10. Inspect the actual resource tree and manifest instead of assuming generation completed correctly.

Understand the generated resource tree

app/src/main/res (representative)text
res/
├── drawable/ic_launcher_background.xml
├── drawable/ic_launcher_foreground.xml
├── drawable/ic_launcher_monochrome.xml
├── mipmap-anydpi-v26/ic_launcher.xml
├── mipmap-anydpi-v26/ic_launcher_round.xml
├── mipmap-anydpi-v33/ic_launcher.xml        # when version-qualified separately
├── mipmap-anydpi-v33/ic_launcher_round.xml  # when version-qualified separately
├── mipmap-hdpi/ic_launcher.webp
├── mipmap-mdpi/ic_launcher.webp
├── mipmap-xhdpi/ic_launcher.webp
├── mipmap-xxhdpi/ic_launcher.webp
└── mipmap-xxxhdpi/ic_launcher.webp

Names and formats can vary

  • Image Asset Studio output depends on its version, input type, min SDK, selected source set, and project template.

  • mipmap-anydpi-v26 selects the adaptive XML on API 26+, while older systems use density fallbacks.

  • A separate -v33 definition can add the monochrome layer while the v26 definition remains a color-only fallback.

  • Current tooling may generate PNG, WebP, vector, or color resources; judge the resource-selection contract, not this exact extension list.

  • Do not hand-create duplicate resources in another source set without understanding Android’s qualifier precedence.

Manual adaptive icon XML for API 26+

res/mipmap-anydpi-v26/ic_launcher.xmlxml
<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
    <background android:drawable="@color/ic_launcher_background" />
    <foreground android:drawable="@drawable/ic_launcher_foreground" />
</adaptive-icon>

Two color layers form the base icon

  • The API-qualified directory prevents pre-26 devices from trying to inflate adaptive-icon.

  • The background points to a full-bleed color; it may also reference an appropriate drawable.

  • The foreground references transparent logo artwork sized for the 108 dp canvas and 66 dp safe zone.

  • Resource names—not filenames with extensions—are used in XML references.

  • Create the round counterpart only when your manifest/product design genuinely needs a separate resource.

Add the monochrome layer for API 33+

res/mipmap-anydpi-v33/ic_launcher.xmlxml
<?xml version="1.0" encoding="utf-8"?>
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
    <background android:drawable="@color/ic_launcher_background" />
    <foreground android:drawable="@drawable/ic_launcher_foreground" />
    <monochrome android:drawable="@drawable/ic_launcher_monochrome" />
</adaptive-icon>

The system, not the drawable, chooses the tint

  • The -v33 resource replaces the same-named v26 XML on API 33+ and includes all three layers.

  • The monochrome drawable should describe shape/opacity rather than hard-code the final wallpaper-derived color.

  • Keep background and foreground in the v33 copy; resource replacement is whole-file, not an XML merge.

  • Mirror the change in ic_launcher_round.xml if roundIcon uses a separate name.

  • Prefer Studio-generated structure when available; it tracks current tool/platform conventions and avoids qualifier mistakes.

Point the manifest to mipmap resources

app/src/main/AndroidManifest.xmlxml
<application
    android:icon="@mipmap/ic_launcher"
    android:roundIcon="@mipmap/ic_launcher_round"
    android:label="@string/app_name"
    ... >
</application>

Manifest references drive launcher selection

  • Launcher icons belong under mipmap so density/resource handling can preserve them appropriately.

  • android:icon is the primary application icon reference.

  • android:roundIcon is optional; most apps only need android:icon because launchers mask adaptive icons.

  • Every build variant/flavor may overlay these resources, so inspect the merged manifest for the release variant.

  • Do not confuse the application icon with notification small icons, shortcuts, or the Play listing asset.

Adaptive icons and Jetpack Compose

Compose does not change the launcher icon resource contract. The launcher reads your application manifest and Android resources before any composable UI exists. You can use Compose throughout the app and still generate/manage the icon through Image Asset Studio and res/mipmap-* exactly as a Views-based app does.

Keep the Google Play icon separate

  • Google Play currently requires a 512 × 512 px, 32-bit PNG, sRGB asset no larger than 1024 KB.

  • Upload a full square; Google Play dynamically applies the rounded mask and outer shadow.

  • Do not pre-round corners or add an outer drop shadow to the store asset.

  • The Play asset is not the adaptive XML installed in the APK/AAB, even when both derive from the same brand source.

  • Do not include ranking, price, deals, Play-program badges, or misleading promotional text.

  • Review the current Play specification at every release because store requirements can change independently from Android launcher resources.

Do not reuse a notification icon

  • Launcher icons are layered, colorful brand surfaces.

  • Android notification small icons follow different silhouette/alpha and display rules.

  • Using the launcher asset as a notification small icon commonly produces a white square/blob or unreadable result.

  • Generate a dedicated notification asset and test status bar, shade, dark/light themes, and OEM skins.

  • Large notification icons and shortcut icons have their own APIs and presentation constraints.

Build and inspect the packaged result

terminal (safe)bash
./gradlew :app:clean :app:assembleDebug
 
$ANDROID_HOME/build-tools/<version>/aapt2 dump resources   app/build/outputs/apk/debug/app-debug.apk | grep -A 20 ic_launcher

Packaging checks catch source-set surprises

  • The Gradle task rebuilds the selected debug APK; it does not validate the Play listing asset.

  • Replace <version> with the installed build-tools directory or invoke the equivalent tool path for your environment.

  • The resource dump helps confirm qualifiers and references packaged into the APK.

  • A successful build does not prove optical quality, mask safety, or launcher caching behavior.

  • Inspect the release bundle/APK as well because release source sets, shrinking, and manifest overlays can differ.

Test matrix that catches real failures

  • API 25 or your oldest supported legacy device/emulator: density fallback appears correctly.

  • API 26+: adaptive icon displays under circle, squircle, rounded-square, and OEM masks.

  • API 33+: themed icons enabled/disabled, light/dark wallpaper palettes, and supported launcher.

  • Current Android 16/QPR launcher behavior with your explicit monochrome layer.

  • Home screen, app drawer, Settings app list, Recents/overview, share surfaces, and shortcuts.

  • Small/large screen densities and at least one non-Pixel/OEM launcher.

  • LTR/RTL and different display/font scales where labels/layout around icons matter.

  • Fresh install, upgrade over the prior release, uninstall/reinstall, and launcher restart/cache refresh.

Why the logo is cropped

  • Important artwork extends beyond the 66 × 66 dp safe zone.

  • The input already contains a circular/rounded mask or shadow.

  • Image Asset Studio scaling placed the visible mark too close to an edge.

  • Foreground and background were flattened into one bitmap.

  • The launcher uses a mask you did not preview.

  • Fix the source geometry; adding random transparent padding can make other masks look undersized.

Why the icon looks tiny

  • The source file contains invisible padding around the logo.

  • A pre-shaped legacy icon was placed as the adaptive foreground.

  • The foreground was scaled down twice: once in design export and again in Image Asset Studio.

  • The brand mark uses an overly conservative safe zone rather than optical sizing within the allowed bounds.

  • Open the raw source with transparency visible, remove unintended canvas padding, then preview every mask again.

Why themed mode looks blank or muddy

  • No monochrome layer is packaged for API 33+ or the wrong resource name/qualifier wins.

  • The monochrome drawable relies on color/gradients instead of a clear alpha silhouette.

  • Foreground details collapse when reduced to a single tinted shape.

  • The launcher does not support themed icons or the user has not enabled them.

  • An explicit layer may still need redesign even when newer Android can synthesize a themed result for missing artwork.

  • Inspect the packaged XML, preview multiple system palettes, and simplify the silhouette.

Why an old icon remains after install

  • Some launchers cache icons aggressively; remove/re-add the shortcut or restart the launcher/device.

  • The installed build variant may override ic_launcher in another source set.

  • The manifest may reference another resource name or product flavor.

  • Incremental deployment may not represent a clean install; uninstall/reinstall during diagnosis.

  • A pinned shortcut can retain its own icon independently from the application icon.

  • Do not change production resource names casually just to defeat a local cache.

Common design mistakes

  • Putting text or fine detail that becomes illegible at launcher scale.

  • Using transparent background edges that reveal a halo during motion.

  • Embedding the foreground in both layers, producing a ghost/double logo.

  • Hard-coding themed-icon color rather than supplying a monochrome shape.

  • Treating roundIcon as a universal requirement and maintaining divergent branding unnecessarily.

  • Shipping only emulator screenshots instead of inspecting the generated/packaged resources.

  • Assuming the 512 px Play icon automatically becomes a correct installed adaptive icon.

Release checklist

  • 108 dp foreground/background/monochrome sources preserved in the design system.

  • Critical mark inside 66 dp safe zone, optically balanced across masks.

  • No baked outer mask or boundary shadow.

  • Image Asset Studio output reviewed, including legacy and relevant API-qualified XML.

  • Manifest and merged release manifest point to intended mipmap names.

  • Explicit monochrome layer tested with themed icons.

  • Legacy, adaptive, notification, shortcut, splash-screen, and Play assets treated as distinct surfaces.

  • Debug and release packages inspected; upgrade and clean-install behavior tested.

  • Play listing PNG passes current size, format, color-space, filesize, shape, shadow, and policy requirements.

  • Brand/design and Android engineering owners approve real-device screenshots.

Primary references