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.