A shared launcher-icon generator for the Flutter apps

How five apps stopped shipping the stock Flutter icon — and why the interesting part is a measurement, not a drawing.

testsAndMisc 27f44ca · adoption commits in dufs-cloud 18a18a4, screen-locker 135545a, wake-alarm 64c25e6, diet-guard f6abf80, todo 0be0706

1. Background — what was there before

Five Flutter apps live across these repos: a file-server client (dufs_client), a gym tracker (workout_app), an alarm companion (wake_alarm_sync), a diet logger (diet_guard_app) and a notes app (todo). Each was scaffolded with flutter create, and none of them had ever been given an icon. That means every one of them shipped the identical stock Flutter artwork — five indistinguishable tiles on the same home screen.

What a Flutter project gives you by default

A fresh Android project contains only legacy icons: one PNG per density bucket, at android/app/src/main/res/mipmap-{m,h,xh,xxh,xxxh}dpi/ic_launcher.png. Nothing else. In particular there was no mipmap-anydpi-v26/ic_launcher.xml in any of the five repos — verified before starting.

That file matters more than its obscure name suggests. Since Android 8, launchers prefer an adaptive icon: instead of one flat bitmap, you supply a background layer and a foreground layer, and the launcher composites them and applies its own mask — a circle on one device, a squircle on another, a teardrop on a third. Without that XML the system falls back to the legacy PNG and just crops it into a shape, which is why untouched Flutter apps look slightly wrong on modern launchers. Android 13 added a third optional layer, <monochrome>, which the system recolours to match the user's wallpaper-derived theme.

The constraint nobody tells you about

An adaptive icon's layers are larger than the visible result. The launcher is only guaranteed to show roughly the inner 66% of the canvas; everything outside that can be masked away, and how much is device-dependent. So art that looks perfect at full size can lose a corner on a real phone.

Why not just draw five icons?

Because "five icons" is a snapshot, and the sixth app is always coming. Hand-drawn one-offs drift: a slightly different stroke weight here, a different background there, and within a year there is no family left. The change therefore defines the family once, in code, and lets each app contribute only two things: an accent colour and a glyph.

2. Intuition — measure, then translate

The design rule is simple to state:

Stating it is easy. Making it true is where the interesting problem lives, and it is not a drawing problem — it is a measurement problem.

The problem: glyphs are not the same shape

Consider two glyphs drawn by hand on the same 1024×1024 canvas. A barbell is wide and short. A cloud-with-arrow is narrow and tall, and the author naturally drew the cloud near the top because that is where clouds go. Both are "roughly centred" in the sense that the author eyeballed them — but their ink sits at different heights. Put the finished icons in a launcher row and they visibly fail to line up.

The naive fix is to nudge coordinates by hand until it looks right. That works for five glyphs and collapses at the sixth, and it silently rots the moment anyone edits a path.

The fix: let the renderer find the ink

Instead, the glyph is rendered on its own on a transparent canvas, and the bounding box of the actual non-transparent pixels is measured. The offset from that box's centre to the canvas centre is then applied as a translation. The author never positions anything; they only decide the shape.

Two details make this work rather than merely sound clever:

• It measures rendered ink, not path geometry. A stroked line has no area as a path, but 72px of width once drawn, plus round caps that extend past the endpoints. Rasterising first means all of that is included automatically.
• It only ever translates — never scales. This is the load-bearing restriction. Scaling a fragment to "fit" would scale its stroke too, so a small glyph scaled up would render a fatter line than its neighbours, and the single shared stroke weight — the thing that makes the icons feel like a family — would quietly break. Translation is the only transform that preserves it.

Play with it

The widget below runs that pipeline step by step on the real glyph data from glyphs.py. Pick a glyph, then step through: draw it as authored, measure its ink box, compute the offset, apply it. Watch the safe-box verdict change as you go.

Three things are worth noticing while you play:

• The corrections on the shipped glyphs are small. Barbell and clock need none at all; cloud-down shifts 6px and checklist 8px. That is the honest result, and it is the kind of misalignment that is invisible in isolation, obvious in a row of five, and impossible to hold by hand across future edits. The careless draft option shows what happens with genuinely sloppy placement — that one is illustrative, not a committed glyph.
• The ink box is bigger than the paths. Select the barbell: the box starts left of x=268, the leftmost path coordinate, because 36px of stroke half-width plus a round cap is real ink. This is precisely why the pipeline measures a rasterised image instead of reading path geometry.
• Centring cannot rescue an oversized glyph. The last option is the cloud as first drawn: 646px tall against a 560px budget. It fails the safe-box check no matter where you put it, and the real fix was to redraw it smaller. The widget reports it as over by 32×85px; the actual tool reported 33×86px.

Three layers out, not one

Once a glyph is centred, three separate images are written from the same fragment. They differ only in what is drawn behind and in what colour:

And on Linux, none of this applies

Two of the apps also build for Linux desktop, and there the whole Android mechanism is irrelevant — flutter_launcher_icons does not touch Linux at all. More surprisingly, Flutter's GTK runner never sets a window icon of its own: the generated my_application.cc sets a title and a default size and stops there, so the window inherits a generic placeholder.

GTK's idiomatic answer is not "point at a PNG file" but "name an icon and let the theme resolve it". So the runner asks for an icon by name, and a small install script puts PNGs under that name into the user's hicolor icon theme:

3. Code — a walkthrough by concern

The new package is python_pkg/app_icons/. Rather than walk the files alphabetically, here are the four concerns it separates.

Concern 1: the family, defined once

style.py holds every number that makes the icons a set. Changing anything here restyles all five apps at once, which is the point:

CANVAS: Final[int] = 1024
BACKGROUND: Final[str] = "#1B1D21"

# Android masks an adaptive icon down to roughly the inner 66% of the canvas.
SAFE_BOX: Final[int] = 560

# Glyph negative space must stay at or above STROKE_WIDTH / 2, otherwise
# adjacent strokes merge into a blob when scaled down to launcher size.
STROKE_WIDTH: Final[int] = 72
MIN_NEGATIVE_SPACE: Final[float] = STROKE_WIDTH / 2

That last constant encodes a mistake made during the work. The first fork glyph had its tines exactly 72px apart — one full stroke width — so the gaps between them closed to zero and the shape rendered as a solid blob. The rule is now written down next to the number that causes it.

Concern 2: measuring and drawing

render.py is where the centring lives. build_svg assembles a document by wrapping the glyph fragment in a group that carries the shared attributes plus the computed translation:

f'<g fill="none" stroke="{accent}" stroke-width="{style.STROKE_WIDTH}" '
f'stroke-linecap="round" stroke-linejoin="round" '
f'transform="translate({dx:g},{dy:g})">'

Because the shared attributes live on the wrapper, a glyph fragment is just paths — it inherits colour and weight and cannot accidentally disagree with the family. A fragment that genuinely needs something else (the filled cutlery silhouette) overrides locally and uses an {{ACCENT}} placeholder for its colour.

Then the measurement itself. Note that it renders, measures, and returns a translation — it never touches scale:

def centre_offset(glyph: Glyph, accent: str) -> tuple[float, float]:
    probe = build_svg(glyph, accent, with_background=False)
    with tempfile.TemporaryDirectory() as tmp:
        png = Path(tmp) / "probe.png"
        rasterise(probe, png, style.CANVAS)
        width, height, x, y = _ink_bbox(png)
    if width == 0 or height == 0:
        raise EmptyGlyphError(glyph.name)
    return style.CENTRE - (x + width / 2), style.CENTRE - (y + height / 2)

The probe is drawn without the background — a charcoal rectangle would fill the canvas and every measurement would return the canvas itself. _ink_bbox shells out to ImageMagick's -trim and parses the resulting geometry.

The sibling function safe_box_overflow reuses the same measurement for a different question — not "where is the ink" but "is there too much of it":

return max(0, width - style.SAFE_BOX), max(0, height - style.SAFE_BOX)

This is what turned an invisible problem into a visible one. On the first real run it reported three overflows, the worst being the cloud at 86px too tall. None of them were apparent at full size; all three would have been clipped on a phone.

Concern 3: the registry, and a checkout that lied

apps.py maps each app to its repo, accent and glyph. The accents are not invented — each is the app's own theme seed, so the launcher icon matches the app's UI:

The registry entry for dufs_client carries a warning comment, and it is worth explaining why:

key="dufs_client",
# The live app: ~/dufs_client is a stale, remote-less checkout that
# was superseded when dufs-cloud absorbed it (see testsAndMisc
# CLAUDE.md). Same package name, so it is easy to icon the wrong one.
repo=_HOME / "src/dufs-cloud" / "app",

There were two checkouts with the same name:, the same applicationId, and the same directory layout. Only one had a git remote and recent commits. The first pass targeted the wrong one — and because it also built and installed an APK from there, the phone briefly received a five-week-old build of a live app. The stale checkout has since been deleted; the comment exists so the trap cannot be re-entered.

Concern 4: handing off to the platform

generate.py writes the three layers, then delegates the fiddly part:

_LAYERS = (
    ("icon", True, None),                    # field + glyph
    ("icon_foreground", False, None),        # glyph only, transparent
    ("icon_monochrome", False, style.MONOCHROME),  # glyph only, white
)

Each layer is written as both SVG source and a 1024px PNG, so a build machine never needs rsvg-convert. flutter_launcher_icons then expands the PNGs into every density bucket and — the part worth outsourcing — writes the mipmap-anydpi-v26/ic_launcher.xml descriptor with all three layers wired up. Hand-rolling that for five apps is exactly the sort of repetitive work that goes wrong quietly.

4. Quiz

Five questions on the reasoning behind the change. Click an option to check it. Score: 0 / 0