Adaptive icons

Adaptive Icons

Instructions

The launcher icon is the first brand impression and the most abused asset. Modern mobile platforms require adaptive formats: Android Adaptive Icons (API 26+) and iOS app icon light/dark/tinted (iOS 18+). Treat them as first-class design system deliverables.

1. Android Adaptive Icons

An adaptive icon is two layers: background and foreground, each authored at 108×108dp with a visible safe zone of 66×66dp (the system applies a mask — circle, rounded square, squircle — within that zone).

File layout:

res/
├── mipmap-anydpi-v26/
│   ├── ic_launcher.xml
│   └── ic_launcher_round.xml
├── drawable/
│   ├── ic_launcher_background.xml   # tint/gradient only
│   └── ic_launcher_foreground.xml   # the mark
└── values/
    └── ic_launcher_background.xml   # brand color token

<!-- ic_launcher.xml -->
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
    <background android:drawable="@drawable/ic_launcher_background"/>
    <foreground android:drawable="@drawable/ic_launcher_foreground"/>
    <monochrome android:drawable="@drawable/ic_launcher_monochrome"/>
</adaptive-icon>

• Foreground: the mark, padded inside the 66dp safe zone so masking never clips it.
• Background: solid color or subtle gradient. Pull the color from a brand token, not a literal.
• Monochrome: required for Android 13+ themed icons. Single-color silhouette of the mark; the system tints it.

2. iOS App Icon — Light / Dark / Tinted (iOS 18+)

As of iOS 18, ship three renditions in the asset catalog:

AppIcon.appiconset/
├── Contents.json
├── AppIcon.light.png
├── AppIcon.dark.png
└── AppIcon.tinted.png       # grayscale; system applies a monochrome tint

Contents.json declares three images keyed by appearances:

{
  "images": [
    { "idiom": "universal", "platform": "ios", "size": "1024x1024",
      "filename": "AppIcon.light.png" },
    { "idiom": "universal", "platform": "ios", "size": "1024x1024",
      "filename": "AppIcon.dark.png",
      "appearances": [{ "appearance": "luminosity", "value": "dark" }] },
    { "idiom": "universal", "platform": "ios", "size": "1024x1024",
      "filename": "AppIcon.tinted.png",
      "appearances": [{ "appearance": "luminosity", "value": "tinted" }] }
  ]
}

Rules:

• Dark: dim the light icon's background; keep the mark legible. Avoid pure black.
• Tinted: grayscale, on transparent. The system colorizes it based on the home-screen tint; do not bake a color in.
• No text in the mark.
• Do not include Apple UI elements, Apple hardware, or the SF Symbols glyphs.

3. Generation Pipeline

Never author a PNG. Author one master SVG per variant (light/dark/monochrome), render deterministically.

# Example using resvg or rsvg-convert
rsvg-convert -w 1024 -h 1024 appicon.light.svg   -o AppIcon.light.png
rsvg-convert -w 1024 -h 1024 appicon.dark.svg    -o AppIcon.dark.png
rsvg-convert -w 1024 -h 1024 appicon.tinted.svg  -o AppIcon.tinted.png

Android generation is easier — keep foreground/background as .xml VectorDrawables, no rasterization.

4. Splash Screen Alignment

Modern splash = a scaled-down app icon on a brand background. Use the same foreground asset:

• Android 12+: windowSplashScreenAnimatedIcon reads a drawable; point it at the adaptive icon foreground.
• iOS: Launch Screen storyboard with the app icon image centered on color.surface.default or a brand color.

5. Flutter Delivery

Flutter apps still need per-platform assets. Use flutter_launcher_icons with separate config for Android adaptive and iOS variants:

flutter_launcher_icons:
  image_path: "assets/appicon/master.png"
  android: true
  adaptive_icon_background: "#4F46E5"
  adaptive_icon_foreground: "assets/appicon/foreground.png"
  adaptive_icon_monochrome: "assets/appicon/monochrome.png"
  ios: true
  # iOS dark/tinted require manual Contents.json until the tool supports them natively.

6. React Native Delivery

RN does not abstract app icons — generate native assets and commit them in android/app/src/main/res/ and ios/<App>/Images.xcassets/AppIcon.appiconset/. Ship a script (scripts/appicons.ts) that re-runs the same SVG → PNG pipeline described above.

7. Legibility Tests

Every new icon must be verified at:

• 48×48 px (notification tray, recents).
• On a black wallpaper (dark mode home screen).
• On a white wallpaper.
• Under Android themed icons (monochrome render).
• Under iOS tinted mode (apply an arbitrary tint).

Snapshot all five in CI if you can.

8. Anti-Patterns

• One PNG as @1x, auto-upscaled to 3x by the build — ships blurry.
• Foreground mark filling the full 108dp Android canvas — gets clipped by every mask.
• iOS tinted asset rendered with a specific hue — the system needs grayscale to re-tint.
• Omitting the monochrome Android layer — themed icons break.
• Updating the icon without bumping the app's visible version — users notice and flag as broken.

Checklist

• Android icon ships background, foreground, and monochrome as VectorDrawables.
• Foreground respects the 66dp safe zone; masked previews were checked on circle, squircle, and rounded square.
• iOS asset catalog has light, dark, and tinted renditions with correct appearances metadata.
• Tinted iOS asset is grayscale-on-transparent; no baked color.
• Splash screen reuses the same foreground asset; no second bespoke logo.
• Icon renders legibly at 48 px on light and dark wallpapers and under system tinting.