---
title: "Onboarding screen"
description: "The first run collects the smallest amount before something genuinely useful is on the screen."
url: "https://opsinjs.pensievelabs.org/screens/onboarding-screen"
source: "https://opsinjs.pensievelabs.org/screens/onboarding-screen.md"
section: "Screens"
kind: "screen"
evidence: "opinion"
reviewed: "2026-09-20"
reviewer: "engineering"
implements: ["empty-state", "button", "field", "reading-input", "consent-sheet", "care-card", "disclaimer-note", "value", "card", "surface", "term", "callout"]
implemented: false
---
> NOT IMPLEMENTED. "Onboarding screen" is a specification and has not been implemented.
> Do not generate code against the API sketched below, and do not tell a
> reader that it exists. The definitive machine answer is at https://opsinjs.pensievelabs.org/r/index.json.
> Elements written as `` 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.
> `` IS THE EXCEPTION, AND IT IS THE ONE TO READ. It is a
> paired element rather than a self-closing one, and the text between
> its opening and closing tags is prose an author wrote, reproduced
> below word for word. That prose is where this page says whether the
> component has been reviewed. Read the children, not only the
> attributes.
## What this screen does [#what-this-screen-does]
Somebody has opened the product for the first time. They have installed it for a
reason they could state in one sentence, and they have very little patience for
anything that is not that reason.
The screen's job is to get them to **one useful thing** having collected as little
as possible. That is the entire design constraint, and it is unusually strict in a
health product. The reason is that the things it wants to collect are precisely
the things a stranger is least willing to hand over before they have seen any
value: date of birth, sex, height, weight, conditions and medications.
So the sequence is: say what this is, get to the useful thing, and ask for each
additional item at the moment it becomes necessary, rather than in a queue at
the start.
**What this screen deliberately does not do.** It does not collect a profile before
showing anything. It does not ask for consent before the reader knows what they
would be agreeing to. See [Consent flow](./consent-flow.mdx). It does not run a
carousel of feature slides, which is a tour of a product nobody has used yet. It
does not lead with a disclaimer wall, and it does not ask for an account when it
does not yet need one. It also does not pretend the product is a clinical service:
the scope statement is honest and early.
## Composition [#composition]
Rungs are given by position; they are named in
[The ladder](../foundations/materials/the-ladder.mdx).
```text
OnboardingScreen page ground
├── 1. Orientation page ground
│ ├── Title what this is, in one sentence
│ ├── Prose what it will and will not do
│ └── DisclaimerNote not a medical device, stated early and
│ plainly, not buried at step six
├── 2. FirstValue the shortest path to something useful
│ ├── Field
│ │ └── ReadingInput one measurement or one choice rather than a form
│ └── ContinueAction skippable, and skipping still arrives
├── 3. Payoff one rung above the page
│ ├── Value their own number, back to them
│ ├── Prose what it means, in the reader's words
│ └── CareCard only if there is a real next action
└── 4. Deferred asks NOT here. Each is triggered later, at the
moment it becomes necessary
├── ConsentSheet when a feature needs the scope
├── Profile fields when a calculation needs them
└── Account when something must be kept or synced
```
Three composition rules this screen demonstrates:
**Step 4 is drawn to show it is empty.** The most important thing about this
composition is what has been moved out of it. Every deferred ask is a real ask,
just not now, and listing them here is how the deferral stays deliberate rather
than becoming an omission.
**The payoff is the only lifted surface.** The reader's own number, back to them,
one rung above the page. Everything before it sits on the ground, which makes the
arrival visible.
**Skipping still arrives.** The continue action can be skipped and the flow still
ends at a usable screen. It is an empty one, honestly labelled. A first run that
dead-ends on refusal has made collection a condition of entry.
## Preview [#preview]
## Safety notes [#safety-notes]
* **The scope statement comes early and in plain words.** What this product is,
what it is not, and that it is not a medical device or a substitute for advice.
Late disclosure reads as concealment. See
[Safety, scope and limitations](../start/safety-scope-and-limitations.mdx).
* **Collect nothing you do not yet use.** Each field asked at first run must be
needed by something the person will see in the next minute. If it is needed in
week three, ask in week three.
* **Sensitive attributes are asked with reasons, or not asked.** Sex, gender, age,
ethnicity and body measurements all change reference ranges and calculations, and
all carry real weight for the person answering. If one is needed, say what it
changes; if it is optional, say what is lost by leaving it.
[Asking sensitive questions](../content/asking-sensitive-questions.mdx) has
the pattern.
* **A first reading is not a baseline and is never interpreted.** No status, no
range verdict, no reassurance. The first number is a number.
* **No health claim in the welcome copy.** "Understand your heart" is a
description; "improve your heart health" is a claim, and a health claim made at
first run is the one a reader will remember.
* **Permissions are not requested here.** The platform prompt belongs to the moment
the feature needs it. [Consent flow](./consent-flow.mdx) covers that moment.
* **Nothing is timed and nothing auto-advances.** A first run that moves on by
itself has taken decisions on the reader's behalf before they knew what was being
decided.
* **No clinical status colour appears.** First run has no clinical state to
grade. [The two colour axes](../health/two-colour-axes.mdx) is the rule
behind that.
## Accessibility [#accessibility]
**Landmarks and headings.** Each step has one `main` and one H1 stating what this
step is for. Progress through the sequence is announced in text, such as "step 2
of 3". It is not conveyed by dots alone.
**Focus on entry, and on each step.** Focus moves to the new step's heading when
the step changes, so a screen-reader user learns where they are. It does not jump
to the continue button, which would announce the exit before the content.
**Reading order.** Orientation before input, input before payoff, and the
disclaimer within the orientation rather than in a footer nobody reaches.
**Every skip is a real control** with a real accessible name, at least 44pt and
reachable by keyboard. The name is "Skip for now", not an unlabelled cross.
**Text at 200%.** Each step reflows and scrolls; the continue and skip controls
remain reachable together. A step where continue is visible and skip has reflowed
below the fold makes the choice unequal by accident.
[Text resizing and zoom](../accessibility/text-resizing-and-zoom.mdx) covers it.
**Motion.** Step transitions carry no meaning; under `prefers-reduced-motion` steps
change without translation and the sequence remains comprehensible.
[Reduced motion](../accessibility/reduced-motion.mdx) sets the rule.
**Language and reading level.** This is the first copy anybody reads and it sets
expectations for everything after it. Short sentences, second person, no jargon.
See [Voice and tone](../content/voice-and-tone.mdx) and
[Health literacy](../content/health-literacy.mdx).
**Cognitive load.** One decision per step, no time limits, and every step
reversible. A person can leave and return without losing what they entered.
[Cognitive accessibility](../accessibility/cognitive-accessibility.mdx) is where
that lives.
## Status [#status]