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