adaptive-icons

name	adaptive-icons
description	Android adaptive icons and iOS app icon light/dark/tinted modes. Use this when creating or revising app launcher 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.