tooldura

For a decade an iOS project carried seventeen images: 40, 58, 60, 80, 87, 120, 152, 167, 180 and the rest, each one slotted into AppIcon.appiconset by device and scale factor. Xcode 14 ended that. A project built with it can declare a single 1024-pixel universal image, and the asset catalog compiler produces every smaller size during the build.

The difference lives in Contents.json. A single-size catalog has one entry with "idiom": "universal" and "platform": "ios" and no scale key at all. A legacy catalog has one entry per device and scale, each naming its own file. They are not interchangeable: dropping a single-size Contents.json into a project whose entries are still per-device leaves Xcode looking for images that are no longer listed, and the build fails on a missing app icon rather than falling back.

So the first thing to check before generating anything is which of the two your project has. Open ios/YourApp/Images.xcassets/AppIcon.appiconset and count the files. One image means single-size; a folder full of them means the ladder, and you either keep it or migrate the whole thing deliberately.

Android 8 replaced the flat launcher icon with the adaptive icon, and the model is genuinely different rather than a new size. You supply a background and a foreground, each a square drawable 108dp on a side. The launcher supplies the mask — a circle on stock Pixel, a squircle on Samsung, a rounded square elsewhere — and applies it to a 72dp viewport in the middle of your layers.

That leaves 18dp of your artwork outside the visible area on every side, and it is not padding you get to use. It is the room the system moves the layers through: on a home screen scroll the two layers shift against each other by a few dp to produce a parallax effect, and when you open the app they scale up out of the mask. Anything drawn in that border exists only to fill the gap during those animations.

Google's guidance narrows it further. The 72dp viewport is a square, but a circular mask inscribed in it cuts the corners off, so the region guaranteed to survive every mask is a circle 66dp across. In practice that means the foreground artwork should span roughly two thirds of the 108dp layer, not fill it.

An adaptive icon needs a declaration, and it lives in res/mipmap-anydpi-v26/ic_launcher.xml. The -v26 suffix is the whole trick: Android 8 is API 26, so devices from that version up read the XML and older ones never see it, falling through to the PNG of the same name in the density folders. One project, two icon systems, no code.

The XML itself is three lines — a background and a foreground drawable, and since Android 13 an optional monochrome one. The background is almost always a colour rather than an image, declared as @color/ic_launcher_background and defined in res/values/ic_launcher_background.xml. Android Studio's own asset tool writes it to that separate file rather than into colors.xml, which is worth matching so a regenerated icon does not collide with your theme colours.

There is a second XML, ic_launcher_round.xml, with identical contents. It exists because android:roundIcon was added in Android 7.1, one version before adaptive icons, for launchers that wanted a circular icon and had no way to mask a square one. On any device new enough to read the adaptive XML the two resolve to the same thing, and it stays in the project for the year of devices between the two releases.

Android 13 added themed icons: the launcher takes a monochrome layer from your adaptive icon and recolours it to match the wallpaper. Where an app supplies one, the home screen looks coherent; where it does not, that app keeps its full-colour icon and stands out as the one that was not updated.

The layer is a silhouette. The system ignores the colours in it entirely and paints the shape in whatever tone the theme calls for, which means the only information it carries is the alpha channel. That is also why it cannot be derived from an arbitrary logo: if your source is a JPEG, a screenshot, or a PNG with a filled background, its alpha channel is a solid rectangle, and a solid rectangle is what the launcher will draw.

So a monochrome layer is worth generating from a transparent SVG or PNG, where the silhouette is the mark itself, and worth skipping otherwise. Skipping is safe: Android falls back to the normal adaptive icon, which looks like every app that has not adopted themed icons yet.

iOS 18 added dark and tinted appearances of the app icon, keyed off the home screen's own setting rather than the system theme. An app that supplies only the default icon still works — iOS derives something automatically — but the derived version is a guess, and it shows on artwork with a light background, which comes back as a bright tile on a dark home screen.

Both variants attach to the asset catalog as appearance-keyed entries: an appearances array with "appearance": "luminosity" and a value of dark or tinted, alongside the default entry for the same 1024 size. Because they hang off the universal single-size entry, they are only available in a single-size catalog. There is no way to attach an appearance to a per-device ladder.

The two variants have different rules. A dark icon may keep transparency, since the system composites it over its own dark surface, and Apple's advice is to darken the background rather than the mark. A tinted icon must be greyscale: iOS applies the colour, so anything left in the artwork fights the tint it is given.

An Expo project does not carry native folders unless you have run prebuild, so there is nowhere to put an asset catalog. Instead app.json names a handful of images and the build generates the platform sets from them.

The fields worth filling are icon, which is the 1024 square used for iOS and the stores, and android.adaptiveIcon, which takes a foregroundImage and a backgroundColor — the same two layers as a bare project, expressed as JSON. From SDK 52, ios.icon can be an object with light, dark and tinted keys instead of a single path, which is how the iOS 18 appearances are declared without touching Xcode.

The images still have to be framed correctly. Expo resizes them, it does not recompose them, so a foreground image that fills its square is cropped by the launcher exactly as it would be in a bare project. The 66 percent rule applies unchanged.

An app icon is seen at roughly 60 by 60 points on a phone, in a grid of twenty others, by someone who is not reading it so much as recognising it. That is a different problem from a logo on a website.

What works is a single shape and two or three colours. What fails is a wordmark, an outline, a gradient with subtle stops, and anything with a thin stroke — at 60 points a one-pixel line is below the threshold where anti-aliasing can keep it crisp, and it turns into grey haze. If your brand mark is a horizontal lockup, the icon is the symbol from it, not the lockup shrunk.

The second constraint is the mask you do not control. On Android your artwork will appear as a circle on one phone and a rounded square on another, so a composition anchored to the corners falls apart on half of them. Centre the mark, keep it inside the safe circle, and check it against all four masks before shipping rather than against the one your own phone uses.