---
title: "Onboarding and first run"
description: "The minimum you may collect before the reader has seen anything of value, and how to defer everything else to the moment it earns its keep"
url: "https://opsinjs.pensievelabs.org/docs/patterns/onboarding-and-first-run"
source: "https://opsinjs.pensievelabs.org/docs/patterns/onboarding-and-first-run.md"
section: "Patterns"
kind: "pattern"
aliases: ["first run", "signup flow", "setup wizard", "minimum collection", "time to first value"]
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> Nothing is missing from this page. The data simply does not live in
> the prose.

Every question asked before the first moment of value is asked on credit, and health questions are expensive. Some frighten, some are private, and some need a piece of paper to answer.

## When to use it [#when-to-use-it]

Use it between the reader first opening the app and first seeing something about them. A setup bar with more than four steps is a warning sign. Use something else for:

* a returning reader with an empty screen: [Empty and first use](./empty-and-first-use.mdx), never a re-run of setup;
* a device permission: [Consent and permissions](./consent-and-permissions.mdx);
* a validated questionnaire, even one that runs first: [Forms](./forms.mdx);
* how to ask for one detail, such as a date of birth: [Ask users for…](./ask-users-for.mdx).

## How it works [#how-it-works]

1. **Scope first.** One screen says what the product does, and that it is not a medical device or a substitute for advice. Late disclosure reads as concealment.
2. **Gate every field.** Answer in writing: can the first useful screen render without this? If it can, ask on the surface that needs it, where the reader sees why.
3. **Ask one question at a time, with a reason.** "Why we ask: your age changes the range we compare your readings to."
4. **Name the consequence of every skip.** "Skip. We will show ranges for adults generally rather than for your age." Skipping still arrives at a usable screen.
5. **Show the first value.** The reader's own number comes back with no status, no range verdict and no reassurance, because a first reading is not a baseline.
6. **Defer the rest.** Consent comes when a feature needs it, profile fields when a calculation needs them, and an account when something must be kept or synced.

Nothing that arrives later blocks the first value, and nothing is timed or advances by itself.

| State               | Behaviour                                                                   |
| ------------------- | --------------------------------------------------------------------------- |
| Resumed             | Returns to the exact question with earlier answers intact                   |
| Skipped fields      | Recorded as skipped and re-asked later in context, never on the next launch |
| Declined everything | An honest screen, never a locked one with no exit                           |

<NotBuiltYet />

## Components [#components]

* [DisclaimerNote](../components/disclaimer-note.mdx): the scope statement, inside the orientation.
* [Field](../components/field.mdx) and [ReadingInput](../components/reading-input.mdx): one measurement or one choice, not a form.
* [Button](../components/button.mdx): continue, and a real "Skip for now".
* [Value](../components/value.mdx) and [CareCard](../components/care-card.mdx): the reader's own number, and a next step only if one is real.
* [EmptyState](../components/empty-state.mdx): the honest payoff when every input was skipped.
* [ConsentSheet](../components/consent-sheet.mdx): later, when a feature needs it.

## Example [#example]

<IframePreview kind="screen" name="onboarding-screen" />

The onboarding screen is still a specification, so its frame shows the not-built notice. The payoff step, which shows the reader's own number, is its only lifted surface.

## Content [#content]

Spend the reader's attention on scope and the next step, not on features. "Understand your heart" is a description. "Improve your heart health" is a health claim, and a reader remembers a claim made at first run. No status colour appears, because first run has no clinical state to grade.

## Accessibility [#accessibility]

* Each step has one heading, and focus moves to it on advance, never to the continue button.
* Progress is stated in text, such as "Step 2 of 4", not by dots alone.
* Back never destroys input (WCAG 2.2 SC 3.3.7), and no step has a time limit (SC 2.2.1).
* Sign-in needs no memory test (SC 3.3.8), so pasting a one-time code must work.
* Skip is a labelled, focusable control of at least 44pt that stays beside continue at 200% text.
