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