# Onboarding illustrations — the decided direction

```
Status: Current
Owner: _null
Last reviewed: 2026-08-18
Governs: docs/design/dist/** — the onboarding illustration set and what it is for
Review trigger: Any illustration added or replaced here; the onboarding artwork
                in issue #29 landing in the app
```

> **References, not shipping assets.** Nothing in this folder goes in the APK.
> These are the decided direction for onboarding, drawn from
> [`../BRAND_GUIDE.md`](../BRAND_GUIDE.md) §22's master prompt. The vectors that
> eventually ship are drawn *from* these.

Seven illustrations in a matched light/dark pair, named for the composables they
replace in
[`../../../core/designsystem/src/main/kotlin/dev/privacyllc/period/designsystem/art/Illustrations.kt`](../../../core/designsystem/src/main/kotlin/dev/privacyllc/period/designsystem/art/Illustrations.kt):

| File stem | Onboarding step | Composable |
| --- | --- | --- |
| `01_WelcomeIllustration` | 1 Welcome | `WelcomeIllustration` |
| `02_LastPeriodIllustration` | 2 Last period start | *new* |
| `03_PeriodEndIllustration` | 3 Period end | *new* |
| `04_LearningIllustration` | 4 Previous history | `LearningIllustration` |
| `05_PrivacyIllustration` | 5 Privacy promise | `PrivacyIllustration` |
| `06_NotificationPrivacyIllustration` | 6 Reminder privacy | *new* |
| `07_ForecastIllustration` | 7 First forecast | *new* |

Each stem exists as `Light/<stem>_light.webp` and `Dark/<stem>_dark.webp`, at
**identical dimensions per card**, so a theme switch swaps the image without
moving the layout.

## What these got right, and why it is worth not undoing

Each of these was a correction during review, and every one of them would be easy
to reintroduce by regenerating carelessly:

- **No text of any kind is painted into the pixels.** The app renders all seven
  titles and subtitles itself through `Heading(...)` in `OnboardingScreen.kt`.
  Art carrying its own title prints every heading twice, cannot be translated,
  cannot scale with the user's font size, and is invisible to TalkBack.
- **No step-number badge.** `LearningIllustration` is not only onboarding step 4
  — it is also the Insights empty state, where a "4" means nothing. Baked numbers
  also freeze the running order, and this flow has already changed shape once. A
  step indicator, if wanted, belongs in live UI where TalkBack can read it.
- **`07_Forecast` shows a calendar and a cycle arc, and names no fields.** An
  earlier draft drew a forecast panel listing *Fertile window* and *Ovulation*,
  which the real first-forecast screen deliberately does not show — on a fresh
  install it reports confidence Low and Today reads "Not enough history to
  estimate". A later draft named the correct fields but painted *Confidence —
  Low* permanently, which is wrong for anyone with a settled cycle. Naming
  nothing is the only version that cannot contradict the live forecast.
- **The dark set is a real dark composition**, not the light one dimmed — the
  midnight-plum ground `BRAND_GUIDE.md` §22 specifies.

## Still to do before anything ships

Tracked as **#29**, which stays open until the app renders these:

1. Redraw as Compose vector paths behind the existing replaceable names, taking
   colour from theme tokens rather than shipping two raster sets.
2. Add the light/dark preview pair per step, per [`../README.md`](../README.md).
3. Reconcile step copy — `PRODUCT_PLAN.md` owns the screen wording.

`EmptyStateIllustration`, the Today "nothing logged yet" state, has no card here.
Onboarding would otherwise ship real art while Today keeps a placeholder visible
in the same session.

## Format

WebP at the delivered resolution — 204 KB for all fourteen, against 3.4 MB as
PNG, and the same format [`../../data/img/`](../../data/img/) uses for the marks
privacyllc.dev renders. The delivery `.zip` archives are deliberately not
tracked; see [`.gitignore`](.gitignore).