Skip to content

ADR-0060: Onboarding shows step progress, offers Back, and pins the primary action

  • Status: Accepted
  • Date: 2026-10-17
  • Deciders: maintainers
  • Related: ADR-0044, ADR-0058

Context

Onboarding signalled progress with a bare LinearProgressIndicator and no step count, so assistive tech and sighted users could not tell which of the four steps they were on. There was no in-app Back — only the system gesture — and each step placed its primary button inline at the end of its own column, so at 200% text or a short landscape window the button could be pushed out of reach below the fold while the welcome mark sat in low-contrast white on a pale primaryContainer circle.

Decision

Onboarding uses one shared step frame and an explicit step/Back contract.

  • Every step renders a localized Step N of 4 label above the progress bar, so the current step and total are in the accessibility tree on each step.
  • Steps after consent show a Back action (an icon button with the localized "Back" label) in the header. Back decrements the step, keeps every entered choice (consent, location toggle, bank selection), never rewinds below the consent step, never completes onboarding and never touches Android permissions. System/predictive Back follows the same contract: after consent a BackHandler routes it through the wizard's Back, while on the consent step it is left to the activity so the user can leave a wizard they have not opted into.
  • Each step body is the single scrollable middle; the primary action sits in a shared bottom area that is always laid out (navigation-bar inset aware). The banks step keeps its own scrolling list inside that middle.
  • The welcome mark uses the launcher receipt icon tinted onPrimaryContainer on the primaryContainer circle, keeping icon and surface in one tonal pair in light and dark.

Consequences

  • Progress, Back and the primary action are consistent across all four steps and reachable on 320 dp / 200% text and in short landscape windows.
  • Back only moves the wizard cursor; the persisted settings and Android permission state are untouched, so stepping back cannot un-grant or grant anything.
  • The steps share one frame instead of four ad-hoc columns, so a later step inherits the same placement rules.

Verification

OnboardingContentTest asserts the localized step count on every step, Back's presence after the first step and its callback, and that the primary action stays inside the viewport at 320/411 dp, 100/200% text and landscape. OnboardingBackContractTest proves Back restores the previous step, keeps consent and bank selections, is a no-op on the first step, and never sets the finishing flag.