Therapy recommendation
Every other output in this system is information to think with. This one is an instruction to change the body, entered by the person it will change, without a clinician present. It carries the highest per-event hazard of anything documented here.
Overview
A decision-support tool that is wrong produces a clinician who disagrees with it. A dosing tool that is wrong produces a dose. The gap between those two sentences is the entire subject of this page, and it is why almost every convenience that is correct elsewhere in this system is wrong here.
Pre-filling a field saves a clinician three seconds and is good practice on most forms. On a dose field it converts an act of judgement into an act of confirmation, performed by someone whose blood sugar is 3.1 mmol/L and who is reading at a level well below their usual one — see Lay & patient-facing design.
No therapy-affecting value is ever pre-filled, pre-selected, or committed in a single gesture. The recommendation, the limit that constrained it, the inputs it assumed and the way to stop all live on one surface — and the stop is reachable without reading anything.
Nothing pre-filled
A recommendation is shown; it is never already entered. Accepting it is a deliberate act distinguishable from tapping through.
Bounded by construction
Values outside the safety envelope are refused, not warned about. A warning that can be dismissed is a limit that does not exist.
Always a way to stop
Stopping is available from every screen, needs no reading, and never asks the person to justify it.
Anatomy
Suggested dose
4 units is suggested for this meal.
| Worked out from | |
|---|---|
| Glucose now | 7.8 mmol/L, steady |
| Carbohydrate you entered | 45 g |
| Insulin still active | 1.2 units from 11:40 |
| Your ratio | 1 unit per 12 g |
Empty until you set it. The most you can give at once is 8 units.
"Use 4 units" fills the field; it does not give the dose. Two deliberate actions, one of which is the one the person would have taken anyway — and the stop is the last thing on the card, always in the same place. Try typing 12, or holding the + key past 8: the field refuses and names the limit, rather than warning you and accepting it anyway.
| Part | Rule |
|---|---|
| The recommendation | Stated in words and figures, at the top. It is a suggestion, and the wording says so. |
| The assumptions | Required. Every input the calculation used, with its age. A person who entered 45 g when they meant 4.5 g can only catch it here. |
| Active therapy | What is already on board. Stacking doses is a common and dangerous error, and the interface is the only thing that can show it. |
| The entry field | Empty. Not zero, not the recommendation, not the last dose. |
| The bound | The maximum, stated before the person types, in the same units. See below. |
| The stop | Present on every screen, in the same position, large, and never disabled. |
Why nothing is pre-filled
A pre-filled dose is accepted at a rate close to one. That is not carelessness; it is what pre-filling is for, and it works exactly as designed on every other kind of form.
- An accepted default is not a decision. If the calculation is wrong, a pre-filled field guarantees the error is delivered.
- A single gesture cannot be interrupted. The gap between filling and confirming is where a person notices the carbohydrate entry was wrong.
- Convenience is still designed for — "Use 4 units" is one tap and fills the field. What it does not do is also commit it.
- Zero is not empty. A field pre-set to
0invites incrementing from an arbitrary starting point; empty forces an intention. - Never remember the last dose. Yesterday's dinner is not today's.
- Confirmation states the consequence, not the action: "Give 4 units now" rather than "OK".
The safety envelope
A value outside the safe range is not accepted. It does not produce a dismissible warning, an "are you sure?", or a confirmation with the word override in it. Every one of those is a limit that a frightened or impaired person will pass through, and the population that passes through them is exactly the population the limit exists for.
Where a clinician has set a wider bound for this individual, the wider bound is the envelope. The device does not offer a way to exceed the envelope it was given.
The device gives less than it calculated, and says that it did. Silently delivering a constrained amount teaches the person a limit exists only when they eventually notice the numbers do not add up.
- The bound is visible before entry, not discovered on submission.
- A binding limit is announced with what was calculated, what was given, and who set the limit.
- Never act on stale inputs. A recommendation computed from a forty-minute-old glucose reading is withheld, not caveated — see Unattended operation.
- Refuse on missing inputs. An assumed carbohydrate value is a fabricated one.
- Bounds are set by a clinician, not by the person dosing, and changing them is a configuration act with its own record — see Safety configuration.
Which mode am I in
Where the device also acts on its own between decisions, a second hazard appears that has nothing to do with arithmetic: the person does not know who is in control. Mode confusion is the classic automation failure, and it is a design problem rather than a training one.
The device is adjusting your background insulin by itself. You still enter doses for meals.
- The mode is stated continuously, in plain words, not by an icon or a colour.
- Every mode change is announced — including the ones the device made itself, which are the ones the person cannot otherwise know about.
- Automatic exit is an alarm, not a notification. Dropping out of automation overnight changes what the person must do, and it happened while they were asleep.
- Never silently re-enter automation. Resuming is the person's decision; a device that switches itself back on has made the mode unknowable.
- Reversion to manual is one action, from anywhere, and never requires a reason.
- The mode is stated on every screen that shows a dose, because "did the device already handle this?" is the question a dose decision depends on.
The stop
The most important control in the product is the one that makes it do nothing. It is designed for a person who is frightened, possibly wrong about why, and not reading.
| Property | Requirement |
|---|---|
| Position | The same place on every screen. Motor memory is the only thing that works under panic. |
| Reading | Reachable without reading anything. Its label is a verb and a noun. |
| Availability | Never disabled, never behind a menu, never requiring sign-in. |
| Confirmation | At most one, stating the consequence plainly — and biased toward stopping. A mis-tapped stop is recoverable; a mis-tapped dose is not. |
| Justification | Never requested. Not before, not after. |
| Aftermath | What is happening now that it has stopped, and what the person should do instead. Stopping is not the end of the interaction. |
States
| State | Rendering |
|---|---|
| Recommendation available | Suggestion, assumptions, active therapy, empty field, bound, stop. |
| Inputs stale or missing | No recommendation. What is missing and how to supply it. Never a hedged suggestion. |
| Limit binding | Constrained value, calculated value, and who set the limit. |
| Dose in progress | Progress shown with the amount, and stoppable mid-delivery, with the amount already delivered stated. |
| Delivery failed or partial | Exactly how much was delivered, stated first. Ambiguity here causes a second dose. |
| Stopped | Unambiguous, persistent, with what is happening instead and how to resume. |
Who holds each rule
This is the pattern where a wrong number reaches a body, and it is also the one where the package holds the most: the numeric input was rebuilt around exactly these rules. What it cannot hold is anything about time, mode or what happens after the number is entered.
| Rule | Held by | Where |
|---|---|---|
| Zero is not empty | Numeric input | value is number | null and null is never rendered as 0. A rate of zero and an unset rate are opposite instructions.Asserted: NumericInput: empty stays empty and is never coerced to zero |
| Out-of-envelope values refused, not warned | Numeric input | With kind="setting" a value outside the envelope is never committed. It stays on screen as typed with the refusal beside it.Asserted: NumericInput: an out-of-envelope setting is not committed |
| Units are in the accessible name of the value | Numeric input | unit is required and sits with the number, so a bare figure is never shown.Asserted: AX tree: a numeric field's unit is in its accessible name |
| What is on screen is what was typed | Numeric input | The draft is held apart from the committed value. This control used to turn 1.5 into 15. Asserted: NumericInput: typing a decimal produces the decimal |
| Pressing decrease never raises the dose | Numeric input | The steppers act on the committed value. With 40 committed and 250 typed and refused, Decrease committed the ceiling — a decrease that more than doubled the setting, found by driving the control in a browser. It now steps down from 40. Asserted: NumericInput: decrease never raises the committed value |
| Nothing is rewritten when the field is left | Numeric input | No clamping on blur. 250 used to become 99 with nothing said. Asserted: NumericInput: a refused entry stays on screen as typed |
| Targets are at least 44 px on this entire path | Button | The touch floor is the default size. The smaller tiers exist and are opt-ins; on a therapy path, do not opt in. Asserted: Button: the documented sizes exist and default to the touch floor |
| Filling and committing are separate actions | Button | A commit is a button, and a pending button refuses a second activation while it names what it is waiting for. Asserted: Button: pending names what it is waiting for |
| Mode is text, never colour or an icon alone | Status chip | A chip cannot be rendered without its word, and there is no icon set. Asserted: StatusChip: the state is a word, not only a colour |
| A single gesture cannot be interrupted — so a confirmation is not a single gesture | Dialog | The destructive confirm is disabled for a short arming delay, so a press already in flight cannot land on it. Asserted: Dialog: confirmation is disarmed on appearance, then arms |
| Reversion is always one action, and it comes first | Dialog | cancel is required and precedes confirm in reading order.Asserted: Dialog: cancel precedes confirm in reading order |
| Never remember the last dose | The implementer | Whether the field opens empty or pre-filled is what you pass as value. The component accepts null; it cannot stop you passing yesterday. |
| No pre-filled or pre-selected therapy value | The implementer | Same row, wider: nothing in a controlled input can refuse an initial value. |
| Confirmation states the consequence | The implementer | description is a string you write. “Give 6 units — glucose 7.8 at 14:26” and “Confirm dose?” are both expressible. |
| Never act on stale inputs; refuse on missing inputs | The implementer | The component does not know what a glucose is or how old it is. The withholding is your calculation's. |
| Assumed inputs displayed with their age | The implementer | Key–value can render an age you pass as provenance; it does not compute one. |
| Bounds are set by a clinician, not by the person dosing | The implementer | Who may change min and max is a permissions question — see Safety configuration. |
| The mode is stated continuously, and every mode change is announced | The implementer | There is no mode component. A chip can show a mode; keeping one on every screen and announcing transitions is your application's. |
| Automatic exit is an alarm, not a notification | The implementer | Raising an alarm condition is your alarm system's. The banner will render it; nothing here decides that an exit from automation qualifies. |
| Never silently re-enter automation | The implementer | State machine logic, entirely yours. |
| The stop is the last element in reading order on every screen | The implementer | Layout. Nothing here places a control; nothing here can notice it is missing. |
| Stop is always available, one action, no justification | The implementer | Whether a stop exists on a given screen is whether you put one there. |
| Never a drag or a long-press | The implementer | There is no slider in this package, which removes the commonest drag. It cannot remove one you add. |
| Partial delivery states the amount delivered | The implementer | The delivered amount is device state; the renderer shows what it is told. |
| No timed dismissal anywhere | The implementer | The dialog has no timeout. The toast queue does, by design, which is why nothing on a therapy path may be a toast — and only you can keep it off one. |
A pattern page has no component underneath it, so a rule stated here is held by whoever builds against it unless a component already holds it. Of these 24 rules, 10 are held by a component this package ships, and 14 are the implementer’s. Ten of these are held by components, which is more than any other pattern here. The fourteen that are not include every rule about mode, time and the stop — the ones that decide whether a pump keeps running after the person walks away.
Do's and don'ts
Empty until the person sets it. Accepting the suggestion is a separate, deliberate act.
Pre-filled. If the carbohydrate entry was wrong by a factor of ten, this dose is delivered without anyone having decided anything.
Suggested dose reduced to 6 units. The calculation suggested 7.5. Your maximum is 6, set by your diabetes team.
The limit bound, and the device said so. The person learns the envelope exists before an emergency teaches them.
Suggested dose: 6 units
Silently constrained. The arithmetic no longer matches the inputs, and the person will eventually notice and stop trusting the calculation.
No suggestion right now. Your glucose reading is 41 minutes old. Check your sensor, or dose from a finger-prick test.
Withheld rather than caveated, with a route to acting safely anyway.
Suggested: 4 units (based on an older reading)
A dose computed from data that no longer describes the person, with the caveat in the smallest text on the screen.
Automatic insulin stopped at 03:22 — the sensor stopped reporting. You are dosing manually. Not restarted automatically.
A mode change the device made itself, alarmed rather than notified, with the current state stated plainly.
(mode icon changes from filled to outline)
A mode change conveyed by a glyph, overnight, to a sleeping person. In the morning they will dose as though automation is still running.
Same place on every screen, large, a verb and a noun, never disabled. Usable without reading the rest of the page.
Settings → Therapy → Automation → Suspend delivery → confirm → give a reason
Five steps and an interrogation between a frightened person and stopping. They will remove the pump instead, which is worse and unrecorded.
Accessibility
- The dose field is a text input with two named step buttons —
“Increase Dose by 0.5 units” — and its permitted range in the
field’s description, so the bound is available non-visually. Never
type="number": its scroll-wheel behaviour changes a dose silently — see Numeric input. - Not a spinbutton, and not steppable by arrow. This page described a
spinbutton with
aria-valuenowfor a long time and the component has never had one, deliberately:role="spinbutton"promises arrow-key stepping, and an arrow pressed while the caret sits in a dose field changes the dose without the prescriber looking at it. That is the scroll-wheel hazard one key over — see Numeric input. - An empty field is empty. No value is asserted on it at all. Announcing
0would announce the very thing this pattern exists to prevent — that the field already holds a dose. - Units are in the accessible name of the value, never only in adjacent text. "Four units", not "four".
- Confirmation states the consequence in its accessible name — "Give 4 units now" — because "Confirm" announced alone is meaningless.
- The stop is the last element in reading order on every screen and also reachable by a single, documented shortcut where the platform allows.
- Targets ≥ 44 px on this entire path, well above the 24 px minimum (SC 2.5.8). Tremor and impaired coordination are ordinary here.
- No timed dismissal anywhere (SC 2.2.1). A recommendation waits.
- Mode is text, never colour or an icon alone — see Colour.
- Never a drag or a long-press to commit a dose. Gestural commits are unreliable for users with motor impairment and undiscoverable under stress.
Outcomes of use
What this contributes to, in the terms of Usability & context of use. These are attributes believed to contribute to an outcome; the outcome itself is settled by observing real use in a specified context, not by this page.
- Effectiveness — the dose given is the dose intended, computed from inputs that were correct and current. Dose error rate is the measure, and it is the whole point.
- Efficiency — this pattern deliberately spends the user's time. Two actions instead of one, several times a day, for years. That cost is real and is accepted because the error it prevents is not recoverable.
- Satisfaction — confidence in an automation you can stop. Trust in a system that acts on your body is almost entirely trust that it will stop when you say so, and it is spent instantly the first time stopping is hard.
Clinical safety notes
Trace these in your risk file (ISO 14971) and usability engineering file (IEC 62366-1). Each bullet says what checks it: a component that holds the rule, a test in your verification file, deployment configuration, post-market surveillance, or a design review where no test can see it. A control checked by nothing is a sentence.
- No pre-filled or pre-selected therapy value. (held by Numeric input) Mitigates: a miscalculated dose delivered by confirmation reflex.
- Filling and committing are separate actions. (held by Button) Mitigates: a single gesture that cannot be interrupted by noticing an error.
- Assumed inputs displayed with their age. (a test in your verification file) Mitigates: a dose computed from a mis-entered carbohydrate value or a stale reading.
- Active therapy on board displayed. (a test in your verification file) Mitigates: dose stacking.
- Out-of-envelope values refused, not warned. (held by Numeric input) Mitigates: a dismissible limit being dismissed by the population it protects.
- Binding limits announced with the calculated value. (a test in your verification file) Mitigates: silent constraint eroding trust in the calculation.
- Recommendation withheld on stale or missing inputs. (a test in your verification file) Mitigates: acting on data that no longer describes the person.
- Mode stated continuously; automatic exit alarmed. (held by Status chip) Mitigates: mode confusion, and dosing as though automation is running when it is not.
- Never silently re-enters automation. (a test in your verification file) Mitigates: an unknowable control state.
- Stop always available, one action, no justification. (a test in your verification file) Mitigates: a person physically removing the device because stopping it was harder.
- Partial delivery states the amount delivered. (a test in your verification file) Mitigates: a second dose given because the first was ambiguous.
Related
- Unattended operation & degraded modes — why a stale reading withholds a recommendation.
- Proxy & carer access — why a remote carer cannot dose.
- Lay & patient-facing design — the register, the numerals, and the impaired-user assumption.
- Numeric input — the control this is built from, and its own safety rules.
- Safety configuration — where the envelope is set, and by whom.
- SteadyLine — the reference application.