17.6 Section 17: Progressive Disclosure & UX Philosophy

First-run coachmark tour

A short, glowing walkthrough of the viewfinder right after the onboarding wizard.

Where to find it

Runs automatically once after onboarding, gated on camera-ready. Resets only if app data is cleared.

Summary

After the onboarding wizard dismisses and the viewfinder finishes loading, an eight-step coachmark tour dims the screen, draws a pulsing green ring around one control at a time, and shows a tooltip explaining what it does. Exposure rings, Metering mode, Composition grid, Lens filters, Tools, Shot logs, Settings, and finally the METER button so the user can take their first reading right after the tour ends. On that last step, tapping the spotlight itself fires the meter and dismisses the tour in one go. Skip or Finish both stamp a completion flag so the tour never runs twice.

How it works

When it runs

Right after the onboarding wizard finishes or is skipped, and only once the camera preview has loaded so every spotlight has a real control to anchor to. Cold-launch after that never re-triggers the tour. Wiping app data is the only way to see it again.

What it covers

Eight quick stops, one tap of Next between each. The shutter and aperture rings (where you dial in exposure). The Metering mode icon (spot, multi-spot, centre-weighted, matrix, auto-zones). The Composition grid icon (thirds, golden spiral, framing overlays). The Lens filter icon (yellow, red, ND, polarizer; the meter compensates for EV loss). The Tools icon (sun and moon, equipment, zone system, expired film compensation). The Shot logs icon (every reading saves, exportable to CSV). The Settings icon (theme, calibration, profiles). And finally the METER button. Tapping the spotlight on that last step fires the meter and ends the tour at the same time.

How it looks

The rest of the screen dims to a soft scrim with a feathered hole around the highlighted control. A pulsing primary-green ring rides the spotlight so the eye keeps landing back on it. The tooltip card slides in from above or below depending on which half of the screen the target is in, so the spotlight is never covered.

Why this exists

The viewfinder is intentionally dense after the wizard sets up your defaults. A new user can take a reading immediately, but Tools / Layers / Settings hide behind small icons that are easy to miss. A 30-second tour points at each one so the depth is discoverable without forcing the user to read a manual or hunt through screens.

Implementation notes (for developers)

CoachmarkOverlay (ui/coachmark/) is rendered as a sibling of ViewfinderScreen in MainActivity above the wizard dialog, but only when ViewfinderViewModel.tourVisible is true. Visibility is gated on AppMeta.tourCompletedAtMs == 0L AND cameraState == Ready: both wizard handlers queue _tourPending=true after stamping the wizard, and the existing cameraState collector flips _tourVisible the moment Ready emits. Targets register their boundsInWindow via the Modifier.coachmarkTarget(viewModel, CoachmarkTarget) extension (ui/coachmark/Coachmark.kt). Spotlight is a single drawRect with a Brush.radialGradient that goes Transparent in the center, scrim color at the edge so the rest of the screen dims while the target stays clear. Pulsing primary-green ring driven by rememberInfiniteTransition (same idiom as the welcome iris). Tooltip card flips above or below the target based on screen half. animateRectAsState-equivalent spring animation slides the spotlight between targets when Next is tapped. Final step lands on the METER button so the very next thing the user does is take their first reading. MIGRATION_65_66 backfills tourCompletedAtMs for existing users so upgraders never see the tour.