---
name: mobile-launcher-icon
description: Generate, replace, or ship a mobile app launcher / store icon correctly — respect the Android adaptive-icon safe zone (the OS crops the outer 18dp), build full-bleed layers, and VERIFY the masked result on the real device home screen, never on a self-made preview. Fires on any app icon, adaptive icon, ic_launcher, Play/App Store icon, or "the icon looks cut off / wrong" task.
---

# Mobile launcher / store icon — do it right, verify on the device

Fires on: generating or replacing an app launcher icon, an Android **adaptive icon** (`ic_launcher` / `ic_launcher_foreground` / `ic_launcher_background`), an iOS app icon, Play Store / App Store icon assets, or any "the icon is clipped / cut off / looks broken / doesn't show" report.

> **The trap this skill exists to prevent (real, 2026-06-18):** I sized an Android adaptive icon's art to fill the whole tile, checked a flat masked PNG **I generated myself**, and it looked perfect — but on the device home screen the logo's edges were **clipped by the OS safe-zone crop**. The preview was a proxy that didn't model the crop. The fix is always two parts: **(1) keep the logo in the safe zone, (2) verify the masked result on the real device home screen.**

---

## 1. Know the geometry BEFORE generating anything

### Android adaptive icon (API 26+, the common case)
- Both layers are **108dp × 108dp**. The OS shows only the **inner 72dp viewport** and **crops the outer 18dp on every edge**. The guaranteed-visible **safe zone for the logo is the central 66dp circle** (≈ **264px** at xxxhdpi / 4×, in a 432px layer).
- **Background layer:** **full-bleed, opaque, NO transparency** — the OS supplies the mask. The mask shape is launcher-dependent (circle, squircle, rounded-square, teardrop), so the background must fill the whole tile.
- **Foreground layer:** the **logo only**, sized to sit **inside the 66dp / 264px safe circle**, centered, transparent everywhere else.
- **NEVER size the logo to fill the full 108dp tile.** It *will* be clipped on the home screen even though it looks fine unmasked. If you have a "complete" circular icon (gradient + logo baked together), it is NOT a drop-in background — its logo is almost certainly past the safe zone. Shrink it (logo ≤ ~84% → safe) or split logo/background.
- **Density layer sizes (108dp):** mdpi 108, hdpi 162, xhdpi 216, xxhdpi 324, xxxhdpi 432 px. Generate every density.
- Files: `res/mipmap-anydpi-v26/ic_launcher.xml` (references `@mipmap/ic_launcher_foreground` + `_background`), plus `ic_launcher_foreground.png` / `ic_launcher_background.png` in each `mipmap-*` density. Manifest `android:icon="@mipmap/ic_launcher"`.

### iOS app icon
- **Full-bleed square, fully OPAQUE — NO alpha channel.** App Store Connect / the asset compiler **reject any transparency**; flatten before export. A stray alpha channel is the #1 iOS icon rejection.
- **NO pre-rounded corners, NO drop shadow, NO gloss.** The OS applies its own **superellipse (squircle) mask**; pre-rounding double-rounds and looks wrong, baked shadows clash.
- **No Android-style 18dp safe-zone crop** — the full square shows (rounded). BUT the squircle rounding eats the corners, and **dark / tinted appearance variants** can nibble the edge, so keep key art ~**8–10% off the absolute edge**, centered.
- **Source format:**
  - Modern Xcode asset catalog: a **single 1024×1024** master is enough (Xcode downscales the rest) — don't hand-author the old size matrix unless the project still uses one.
  - **Icon Composer `.icon`** (iOS 18+ / iOS 26 Liquid Glass): a layered bundle supporting **light / dark / tinted** variants + glass depth. If the project ships a `.icon`, edit/replace THAT, and **wire it via the `.pbxproj` `ASSETCATALOG`/icon setting — do NOT drag-drop it into Xcode** (drag-drop has silently failed to update on this project before). Provide light + dark + tinted layers, not just the default.
- **Store icon:** App Store marketing icon is **1024 × 1024, no alpha** (same asset, no transparency).

### iOS verification (parallel to the Android device check)
- Install on a **real device or simulator**, look at the **Springboard / home screen** rounded render — not just the 1024 square.
- If the icon uses light/dark/tinted variants, **check each appearance mode** (Settings → home-screen tint), since a logo that reads on the default can vanish when tinted.
- **Simulator-on-an-XDR-display caveat:** a washed-out live simulator on a reference-mode XDR is an **EDR/reference-mode artifact, not the icon** — trust the captured screenshot over the live washed-out window.
- "Icon won't update on the sim" = clear DerivedData + reinstall + kickstart SpringBoard (don't conclude the asset is wrong).

### Store listing icons (separate from the launcher icon)
- **Play Store:** 512 × 512, 32-bit PNG. **App Store:** 1024 × 1024, no alpha. These do not replace the launcher icon — ship both.

---

## 2. Build it

- Foreground = logo, scaled so its bounding box fits inside the **264px safe circle**, centered, transparent margin out to 432.
- Background = full-bleed opaque brand fill (gradient/color), all densities.
- If reusing a "complete" circular icon: shrink the whole disc to **~0.84 of the frame** so its logo lands inside the safe zone, on a matching full-bleed background so the corners are never transparent.

---

## 3. VERIFY on the real device — this step is non-negotiable

A flat masked composite **you generated** does **not** model the adaptive safe-zone crop, launcher parallax, or the device's actual mask shape. It will lie. So:

1. Install on the **real device** (`adb install -r`; uninstall first only if signatures differ).
2. Force the launcher to reload its icon cache: `adb shell am force-stop com.google.android.apps.nexuslauncher` then `input keyevent KEYCODE_HOME`.
3. Put the icon on the **home screen** (or read it from the drawer), screenshot, and **zoom in** (crop via the `uiautomator` bounds of the icon, scale 3×, then Read the image with vision).
4. Confirm, eyes-on: **(a) no edge of the logo is clipped, (b) it's centered, (c) clear margin on all sides**, (d) the mask shape renders the brand fill to the edge (no transparent gaps under a squircle).
5. If clipped → the logo is past the safe zone → shrink and repeat. Never ship on a "looks right in my preview."

For iOS, verify the rounded icon on the real Springboard / a device build, not just the 1024 square.

---

## 4. House-rule ties

- This is a specific case of **"Verify on a REAL device before any 'it's good'"** and **"a self-generated preview is a proxy, not verification."** Icon/mask/adaptive-layer output is exactly where a proxy preview diverges from the device.
- Memory: `feedback-verify-on-real-device`, `feedback-drive-ui-by-confirmed-targets`. Project icon facts (<private-health-app> # sanitized): the brand mark is the HL monogram on a green→magenta gradient; Figma Play-asset kit lives at file `9c5RTOb60NEANaXOh388qV` page `119-1871`.
