halkyon/docs/adr/0031-the-apps-icons.md

ADR 0031: The apps' icons, one family

• Status: decided 28 Oct 2026, by the developer (D1–D4 below). Built the same day for Learn, Todo and Train by one tool, tool/app_icons.py (as What follows proposed, the developer agreeing); Meditate's comes with Meditate. D5 (2 Nov 2026) changes D2's gradients: each icon ends in its app's backdrop colour; D6 puts Learn's icon in place of the kingfisher inside the app; D7 gives Train the dumbbell, Meditate the sprout; D8 (7 Nov 2026) changes D1's white tile to the apps' dark background, the gradients lifted; D9 (9 Nov 2026) has Android and iOS colour the icons by the system's theme, macOS later; D10 (9 Nov 2026) returns to D1's white tile, D8's dark one undone; D11 (12 Nov 2026) puts the kingfisher, in each app's colours, on the launch screens, where D6 had put the icon; D12 (12 Nov 2026) makes the kingfisher, in its own colours, Learn's icon (Halkyon's, ADR 0045, D14), in place of D5's graduation cap.
• Builds on: ADR 0030, D12 (Train's icon is Lucide's bike).

Context

Halkyon's apps had no family. Learn's icon is the kingfisher, Halkyon's emblem (a picture, halkyon_learn_flutter/assets/icon/halkyon_icon.png); Todo's is Lucide's list-checks, its strokes drawn with Pillow in cobalt fading into sky (apps/todo/tool/app_icons.py). On 28 Oct, choosing Train's, the developer asked for "a fading of the colors, like in the icons of Proton's services", whose blog post (proton.me/blog/new-visual-universe) says: "Every icon starts with the Proton purple and then fades into the service color", so that the icons read as one family.

Drawn and compared on 28 Oct (the previews in the session's scratchpad): fading from cobalt straight into one other colour looks, in the developer's words, "bland and odd", cobalt into sky "like everything is completely blue", and cobalt straight into an orange turns grey-brown halfway, as blue and orange are opposite colours. A gradient passing through a colour between them (violet or sky) stays bright.

Decisions (28 Oct 2026, the developer's)

• D1 Every app's icon is a Lucide glyph on white, fading from cobalt through a colour between into the app's own, top left to bottom right across Lucide's 24-unit box, at Lucide's stroke width (2), the white tile's corners rounded by the platforms as today. Cobalt is what the family shares, as Proton's purple; the end colours lie apart on the colour wheel, so the icons are told apart small, the shapes doing the rest (Learn's and Train's are related, as are Todo's and Meditate's; the developer kept them so).

• D2 The four:

  App	Glyph	Gradient
  Learn	graduation-cap	cobalt #3C57E5 → violet #8E4FD6 → strawberry #EC3E7C
  Todo	list-todo	cobalt #3C57E5 → pacific #179FD9 → fern #3CBB3A
  Train	bike	cobalt #3C57E5 → violet #8E4FD6 → strawberry #EC3E7C → carrot #F78400
  Meditate	circle-dot	cobalt #3C57E5 → pacific #179FD9 → reef #1DA583

  The stops are evenly spaced. Cobalt is the icon's brighter cobalt Todo's icon uses, not the palette's (#273EB2); violet is no palette colour (between cobalt and strawberry); the others are halkyon_ui's palette's.

• D3 Learn's icon becomes the graduation cap; the kingfisher stays Halkyon's emblem, in the logo and the wordmark, and as the icon of the F-Droid repository, which is all of Halkyon's apps' (the developer's, 28 Oct: tool/release/fdroid/halkyon.png). Installed Learn apps change their icon once, when the new one is built, as do F-Droid's listing and the snap's.

• D4 Meditate's glyph is circle-dot (the developer's, over flower-2, recommended, wind, sprout, leaf and flower): a point to rest the eyes on.

What follows (the agent's proposals, to be put to the developer when built)

• One icon tool for every app at the repository's root, each app naming its glyph and stops, instead of a script per app: Lucide's glyphs have arcs and curves (bike's wheels, graduation-cap), which Todo's tool, drawing straight strokes with Pillow, can't draw. librsvg through PyGObject and pycairo (Ubuntu's python3-gi, gir1.2-rsvg-2.0, python3-cairo) renders them exactly; the previews were drawn so.
• Lucide's licence (ISC) beside each icon and in each app's licence list, as Todo's is.

Changed 2 Nov 2026: each icon ends in its app's backdrop (the developer's)

Trying Todo on 2 Nov, the developer found its icon, cobalt through pacific into fern, confusing beside its strawberry screens (ADR 0033, D3; D10 had kept the icon). Of the four, only Train's icon ended in its backdrop's colour (carrot); Learn's ended in strawberry, now Todo's, and at launcher size Todo's and Meditate's looked alike, as did Learn's and Train's. Compared as swatches the same day.

• D5 Every icon fades from cobalt into its app's backdrop colour, the colour its screens wash down from (ScreenColor), through a colour between as D1 has it. The backdrops stay: Learn cobalt, Todo strawberry, Train carrot, Meditate fern (the developer's, 2 Nov, over reef: a green). So:

  App	Glyph	Gradient
  Learn	graduation-cap	cobalt #3C57E5 → enzian #5252CC → purple #8080FF
  Todo	list-todo	cobalt #3C57E5 → violet #8E4FD6 → strawberry #EC3E7C
  Train	dumbbell (D7)	cobalt #3C57E5 → violet #8E4FD6 → strawberry #EC3E7C → carrot #F78400
  Meditate	sprout (D7)	cobalt #3C57E5 → pacific #179FD9 → fern #3CBB3A

  Todo takes Learn's gradient, Meditate Todo's; Train's stays. Learn's backdrop is cobalt, the family's start, so its icon stays in the blues, ending in purple (the agent's recommendation, over cobalt → pacific → reef, which looked like Meditate's at launcher size): its end colour lies furthest from the others' (strawberry, carrot, fern). The pairs D1 kept change: Todo's and Train's are related now, Learn's and Meditate's stand apart. Installed apps change their icon with their next release, as D3 says.

• D6 Learn shows its own icon inside the app (the developer's, 2 Nov 2026): atop the navigation rail, on the launch screen and on halkyon_app's screens (the first start, signing in, the account switcher), where D3 had left the kingfisher, as Todo and Train show theirs. The kingfisher (halkyon_learn_flutter/assets/icon/halkyon_icon.png, removed) stays Halkyon's emblem where D3 put it otherwise: the F-Droid repository's icon (tool/release/fdroid/halkyon.png).

• D7 Train's glyph is Lucide's dumbbell, Meditate's sprout (the developer's, 2 Nov 2026), over D12's bike (ADR 0030) and D4's circle-dot: Train is more than riding (runs, rows and strength, ADR 0030), and the sprout fits Meditate's fern. The dumbbell lies from top right to bottom left, across the gradient, so the carrot it ends in shows less than on the bike.

• D8 Every icon's tile is the apps' dark background, #131520, its gradient lifted 30 % towards white (the developer's, 7 Nov 2026, on the recommendation among four dark tiles shown side by side, over D1's white): halkyon_ui's dark surface, so the icon, the launch screen and the apps in dark mode are one surface. On that tile D5's colours as they are sink in where they start (cobalt reaches about 2.5 : 1 against it); each stop mixed 30 % towards white keeps its hue and holds the darkest of them above 4.5 : 1 (cobalt 5.7, enzian 5.6), so the glyphs read at launcher size on any wallpaper. The other tiles shown: the gradients unchanged, a tile fading from the dark theme's cobalt container into near-black, and black, which vanishes on dark wallpapers. The palette stays D5's, Proton's label colours; tool/app_icons.py holds the tile and the lift (TILE, LIFT), and the apps' pubspecs give Android's adaptive background and iOS's the tile's colour. Inside the apps (D6) the icon is the dark tile in light mode too, as on the launcher. Installed apps change their icon with their next release.

• D9 The systems colour the icons by their theme where they can (the developer's, 9 Nov 2026: "Android + iOS now, macOS on a Mac"). Each icon gives the variants the systems take, all from the same glyph at the same place, which tool/app_icons.py draws into the app's build/icons/ and flutter_launcher_icons (v0.14.4) writes into the projects:

  • Android (13 and later, Themed icons): the adaptive icon's monochrome layer (adaptive_icon_monochrome, drawable-*/ic_launcher_monochrome.png, at the foreground's inset of 16 %), the glyph in white on transparency, which the launcher tints from the wallpaper's colours. Launchers without themed icons, or with them off, show D8's icon as before.
  • iOS (18 and later): a dark icon (image_path_ios_dark_transparent), the glyph in its gradient on transparency, which iOS sets on its own dark background, and a tinted one (image_path_ios_tinted_grayscale), the glyph in white on black, which iOS colours in the tint chosen. The asset catalogue holds them as the dark and tinted appearances beside D8's icon, which light mode keeps; iOS before 18 reads only that one.
  • macOS (26, Tahoe) colours icons only from an Icon Composer file (.icon), which flutter_launcher_icons doesn't write and only Xcode 26 on a Mac makes; macOS's icon stays D8's until then, in every look macOS gives it. Done on a Mac: the glyph as an SVG layer over the tile's colour in Icon Composer, the .icon file in the app's macos/Runner/, named by ASSETCATALOG_COMPILER_APPICON_NAME. Linux and Windows have no such theming; their icons stay D8's.

  No new image is committed but what the projects hold: the variants are made from the glyph and D5's gradients each time, so a change of glyph or colour reaches them too. Installed apps change their icon with their next release.

• D10 Every icon's tile is white again, as D1 had it (the developer's, 9 Nov 2026: "Please return to the icons with white background"), D8's dark tile undone: the gradients are D5's as they are, unlifted (cobalt holds about 5.7 : 1 against white), the apps' pubspecs give Android's adaptive background and iOS's white, and the icon inside the apps (D6) is the white tile. D9's variants stay: Android's monochrome layer and iOS's tinted icon are white glyphs as before, and iOS's dark icon, which iOS sets on its own dark background, keeps D8's lift of 30 % towards white (DARK_LIFT in tool/app_icons.py), so cobalt keeps above 4.5 : 1 there.

• D11 The launch screens show the kingfisher in each app's colours (the developer's, 12 Nov 2026, from a redesign another session drew: the kingfisher on the dark tile with the app's glyph in a badge, proposed for the launchers too). On the launchers the badge's glyph can't be read at 48 dp, the four icons differ by a tint alone, the badge reaches beyond Android's safe zone and stands where Android shows a work profile's, so the launchers keep D10's glyphs; the launch screen, where the bird stands large and the wordmark beneath names the app, takes it, without a badge. The drawing is the commissioned one (tool/kingfisher.svg, unchanged), its own white tile left out, cut to the bird and drawn by tool/app_icons.py into each app's assets/icon/halkyon_<app>_kingfisher.png (480 pixels, shown at 160): its warm parts, orange and rust, in the last two of the app's colours (Learn enzian and purple, Todo violet and strawberry, Train strawberry and carrot, Meditate pacific and fern), its accents in the second last lifted 30 % towards white, its cobalt every app's. halkyon_ui's LaunchScreen takes it as emblem, unrounded, in place of D6's icon, which stays atop the rail and on halkyon_app's screens. Android's own splash before it still shows the launcher's icon. Over the redesign's dark tile (D10 undid D8's) and over leaving the kingfisher to the F-Droid repository and the website alone.

• D12 Halkyon's icon is the kingfisher in its own colours (ADR 0045, D14, the developer's choice of 12 Nov 2026, as the learning app takes the name Halkyon and the bird is its namesake): Learn's launcher icon and its launch screen show the commissioned drawing as drawn, cobalt back and orange belly, the launcher's on D10's white tile, in place of D5's graduation cap and D11's recolouring. The bird's square takes 47 % of the icon (BIRD in tool/app_icons.py), less than a glyph's 60 % (D3): its beak reaches into the corner, and so it stays inside the 66 dp circle of the 108 that Android keeps on every launcher's shape. The themed variants (D9) are its outline: Android's monochrome layer and iOS's tinted icon the bird's shape in white, iOS's dark icon the bird itself. Lucide's notice leaves Learn's licence list, as its icon no longer is Lucide's (the icons inside the app bring the package's own). Todo, Train and Meditate keep their glyphs, and their launch screens D11's bird in their colours, Todo's until Myrmex has its ant (ADR 0045, D3).