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.
• 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.