`
counts it.
Nothing here is typed twice. If a row is wrong the catalogue is wrong, and editing this
page cannot fix it. `scripts/assert-ia.mts` fails the build when a catalogue id is missing
the page it should have, when a page claims an id the catalogue does not know, or when two
pages claim the same alias.
---
# Accordion
Source: https://opsinjs.pensievelabs.org/components/accordion
Markdown: https://opsinjs.pensievelabs.org/components/accordion.md
Section: Components · kind: component · status: shipped · also known as: disclosure, expander, collapsible
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"When can I reach the team?"** The reader's own question, short enough to
scan against its siblings.
**A "More" panel holding "Call your clinician if this reading keeps rising."**
An instruction the reader may never open.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA in a source pass and a rendered pass.** It is
author-run, not independent, and clinical review is pending. The rendered pass
(axe, target size, focus visible, 320px reflow) was clean.
**One defect was fixed.** The trigger's focus ring was drawn outside the trigger,
where the root's `overflow-hidden` clipped it (2.4.7). It now renders inside,
whole on every straight edge, with a small notch still clipped at the first and
last sections' outer corners, a known residual.
* Base UI renders each header as an `h3` with a `button`, wires `aria-expanded`
and `aria-controls` between trigger and panel, and hides the chevron with
`aria-hidden`, so a reader relies on `aria-expanded`, not the glyph.
* The chevron's turn uses `--opsin-duration-fast`, collapsed under
`prefers-reduced-motion`. A closed panel is unmounted, leaving the tab order.
**Still unmeasured.** The rendered pass does not compute contrast, so every pair
against the card surface is unmeasured, not known-failing. That no must-see
content may sit in a closed panel stays a docs contract the wrapper cannot
enforce.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Contact your clinic before your next appointment. This reading is outside the range they
asked us to tell you about.
```
## When to use it [#when-to-use-it]
An `urgent` banner must never be the only place a serious message appears, and never
dismissible without an acknowledgement the product records.
## Anatomy [#anatomy]
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Ada Vance", with her photo, or "AV" when there is none.** One field feeds the alt text and the initials.
**A generic silhouette used for everyone, with no name behind it.** A nameless circle identifies nobody.
## Accessibility [#accessibility]
**Checked by `pnpm run check:a11y` on every commit.** Every colour is a role
token, no type size is in `px`, and no banned word appears anywhere.
**Audited against WCAG 2.2 AA**, in a source pass over the component code and a
rendered pass with axe-core, target-size, focus-visible and reflow checks. The audit
is author-run, not an independent review, and clinical review is still pending.
The audit found one defect worth fixing: a picture with a missing or blank name
rendered with an empty `alt`, so a screen reader announced nothing while a sighted
reader still saw a face. The picture tier now requires a usable name too, so a
nameless avatar falls through to the neutral person glyph instead, matching the
fallback chain this page already promises.
* The avatar takes no focus and is not a tab stop. Inside a button or a link, that
control owns the focus and the name.
* With a fallback showing, the root is `role="img"` with the name as `aria-label`,
and the initials or glyph are `aria-hidden`.
* With a picture showing, the image's own `alt` carries the name and the root stays a
plain container, so the name is announced once.
* An empty name warns in development, draws the person glyph and leaves the circle
unlabelled, because the component cannot invent a label.
**Left open by the audit.** Contrast of the initials and the glyph on the muted fill
comes from shared role tokens, not a literal colour here; the rendered pass found no
violation, but no ContrastReport data exists yet for this pair. Initials are still
taken by code point rather than grapheme cluster, so a combining mark can be lost, as
the notice above already states.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Messages
3
```
## When to use it [#when-to-use-it]
**"3" with `srLabel="3 unread"`** names the count for a screen reader and
stays quiet chrome.
**A red badge reading "High" beside a reading** tells a clinical level by
colour alone. That is a StatusPill.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA**, in a source pass and a rendered pass. The
audit is author-run, not an independent review, and clinical review is still
pending.
The source pass found one real defect and fixed it: `srLabel` set `aria-label`
on a bare `span`, whose implicit role is generic and does not reliably carry
an author-supplied name to assistive technology, so a caller's count risked
being silently dropped in favour of the visible digit. The badge now pairs
`aria-label` with `role="img"` whenever `srLabel` is a non-empty string, the
same pairing already used on [Avatar](./avatar.mdx). Nothing else about the
markup, the props or the rendered output changed.
**Checked by `pnpm run check:a11y` on every commit.** The badge draws only the
neutral chrome roles, carries no `data-status`, and sets its text at the
`caption1` semantic step rather than a `px` size.
**Argued from the source, not measured.**
* `srLabel=""` sets `aria-hidden`, so a count already spoken beside the badge is
not read twice.
* `srLabel` with text sets `aria-label` and `role="img"` together, so a bare
count is named reliably rather than risking a lone number.
* Nothing takes focus, answers a key or animates, so there is no keyboard
contract and nothing for `prefers-reduced-motion` to reduce.
* At 200% text and under a wider text-spacing override the chip grows with the
text rather than clipping it, because nothing fixes its height or hides its
overflow.
**Residual, disclosed rather than fixed.** No contrast pair in either weight
has been measured against real token values, so the numbers below are
whatever the generator has produced so far. Nothing in the component checks
that a caller's `srLabel` textually contains the visible content, so a caller
who ignores the guidance in Content guidelines could still write a disjoint
label; that stays a documented usage contract rather than enforced behaviour.
Whether a screen reader speaks a labelled badge usefully in the flow of its
host still has not been listened to, only reasoned about from the roles.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Where are you noticing something?"** with regions named "Chest" and "Left arm" says where, and nothing more.
**A region relabelled "Chest pain" or "Fracture"** presents a symptom or a diagnosis as though the reader confirmed it.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA, in a source pass and a rendered pass.** This audit
is author-run. It is not an independent review, and a clinical review is still
pending. `pnpm run check:a11y` runs on every commit: every colour is a role token,
no type size is in `px`, and no banned word appears anywhere.
**What the audit fixed.** The region markers are `rem`-sized so they grow with the
reader's text size, but the figure box was pinned in `px`. At 200% text the markers
outgrew the fixed box and collided, which lost the ability to tap them separately
under 1.4.4 and 1.4.10. The box now scales in `rem` in lockstep with the markers, so
the spacing ratio holds at every text size and the default view is unchanged.
**What the audit confirmed.**
* A real `button` per region, named by its label, with `aria-pressed` for its
state. The map is a group named by `label`.
* Selected is a muted fill, a hairline and a tick, and unselected shows a plus.
The difference survives greyscale, and `aria-pressed` is the carrier.
* Each marker meets the 44 by 44 floor on both axes, carried in `rem`.
* Left and right are the subject's own sides, so the `left-arm` marker sits on the
viewer's right, matching clinical convention.
**What a reader should still know.** The Front and Back captions render as ``
rather than headings, a deliberate choice so the component does not hardcode a
heading level into a host document of unknown depth; each figure still carries a
named `role="group"`. Screen-reader output across VoiceOver, NVDA and TalkBack, the
nine-stop tab sequence, and forced colours are not gated, and the paired checkbox
list stays the primary path for readers who cannot point at a target.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Save reading
```
## When to use it [#when-to-use-it]
**"Save reading"** names the outcome and survives being read out of context.
**"Submit"** on a screen with three of them tells a screen reader user nothing.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA in a source pass and a rendered pass. The audit is
author-run, not an independent review, and clinical review is still pending. The
rendered pass on the isolated view was clean, with no axe, target-size, focus-visible
or reflow failure. The source met every check, so the audit changed nothing.
It confirmed the load-bearing behaviour: a real `button` with the platform role and
keys, the visible label as the accessible name with the icon `aria-hidden`, `busy`
handled through `aria-busy` and `aria-disabled` so the control keeps its tab stop,
and the outline focus ring that never shifts layout.
**Residual items to know.** No live region is mounted, by design: `busy` reaches the
tree on the focused control as `aria-busy` plus `aria-disabled`, and `busyLabel`
carries a word there, but with no `busyLabel` it is not otherwise announced. Because
the ring is an outline with offset, an ancestor set to clip can hide it. `Button.Target` raises the hit area to the 44px floor under the SC 2.5.8
inline exception, so a project without the product stylesheet owes
`--opsin-target-separation`. In dark mode the quiet and primary labels clear the
WCAG 4.5:1 floor but fall under the stricter APCA figure, which sits outside WCAG
2.2 AA and belongs to the theme token layer.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
This average does not include days when you did not wear the device.
```
## When to use it [#when-to-use-it]
**"This average does not include days when you did not wear the device."** A specific, checkable limitation.
**"Important: your data may be incomplete."** Warning register, no specifics, nothing the reader can do.
## Accessibility [#accessibility]
This component was audited against WCAG 2.2 AA in a source pass and a rendered pass on `/view/base/base-lyra/component/callout`. The audit is author-run and is not an independent review. Clinical review is still pending.
**What the audit found.** Nothing in the source needed to change. It is a server component with no interactive elements, so the keyboard, focus and control criteria do not apply; `role="note"` gives it a start and end boundary, and a title supplies the accessible name through `aria-label`. It paints no colour from either axis and carries no clinical status, so greyscale and `forced-colors` take away nothing. Type sizes and colours are role tokens, the icon is sized in em, and the body reflows at 200% through `min-w-0` and `wrap-break-word` rather than scrolling.
**What a reader should still know.** The variant glyph is `aria-hidden`, so the note, tip and caveat distinction reaches sighted readers alone. This is deliberate: announcing the glyph name would not convey the sense either, so the copy is required to carry it, and both examples do. The title renders as styled text rather than an `h1` to `h6`, because the component cannot know its nesting level, but it stays exposed to assistive technology as the accessible name. The four contrast pairs this component paints are not yet measured, and the report below says so rather than printing numbers nobody produced.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Recent readings} />
Card content
```
## When to use it [#when-to-use-it]
**"Recent readings"** as a card title, with the readings inside it.
**"Recent readings and upcoming appointments"** in one card. The boundary
then tells the reader nothing.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA across a source pass and a rendered pass. The audit
is author-run, not an independent review, and clinical review is still pending.
**Checked by `pnpm run check:a11y` on every commit.** Every colour is a role
token, no type size is in `px`, and no banned word appears.
**What the audit changed.** The link card's `focus-visible` ring used a
hardcoded 2px outline instead of the house tokens. It now reads
`--opsin-border-focus` and `--opsin-border-focus-offset`, so a product
raising those gets a wider ring here; the default stays 2px. The rendered
pass found no axe violation and no 320px reflow.
**What it left standing.** A link card is one anchor, so its accessible name is
all its text at once, a verbosity to weigh before putting `href` on a long
card. The resting chevron is `aria-hidden`, backed by the title underline and
anchor as redundant cues. A card otherwise takes no role or name
unless it is a link, carries the page's heading level in a title slot that resets
font and margin, floors a link target at `--opsin-target-minimum`, and keeps its
edge under greyscale, `forced-colors` and print.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
At most one `urgent` surface per screen, counted on the status axis. If the step is ringing
for help, give the number: the component ships none.
## Anatomy [#anatomy]
**"Book a repeat blood test"**, with an author, a reason and a date.
**"Action required: abnormal result. Contact your provider."** No author, a banned
word, no reason, no timing.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA.** A source pass covered the rubric and a rendered pass ran
axe, target size, focus visibility and reflow at 320px. The audit is author-run, not
independent, and clinical review is pending.
Confirmed:
* The card is a `section` named by `aria-label` from its heading, so entering it speaks the
instruction.
* Urgency is text with no glyph or colour, and status is carried by
[StatusPill](./status-pill.mdx) as word, glyph and tint, never colour alone.
* The card takes no tab stop. Of two actions, the recommended one is set apart by a
bordered shape and a hidden qualifier, not by colour.
Not confirmed in a browser: the `sm` quiet button and secondary quiet link variants, which
inherit the 44px target floor but were not exercised. Contrast for the action tones and the
timing phrase stays unmeasured, as the report below records.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Email me a copy"** ticks to a plain yes, with the detail in the description.
**"Do not exclude me from reminders"** makes an empty box a double negative.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA in a source pass and a rendered pass. The audit is
author-run, not an independent review, and clinical review is still pending.
**What was fixed.** Base UI draws the box as a `span` with `role="checkbox"`, and
the wrapping `label` named only the hidden input, so the box had no accessible name
(WCAG 4.1.2). The visible label carries an `id` and the box points at it
with `aria-labelledby`, so the name is the visible words verbatim (WCAG 2.5.3).
The fix reaches the demo and both examples.
**What holds.** The description is tied with `aria-describedby`, colour is never
the sole state carrier because fill, border and the Check against Minus glyph all
move together, and sizes are rem.
**Residual.** The rendered probe measured the inner box at 20 by
20, under SC 2.5.8, but the pointer target is the 44px label row that toggles
anywhere along it, so it clears the house floor. The colour transition moves no transform and needs no reduced-motion guard. Contrast pairs are not yet measured.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**A label of "Medication", a placeholder of "Search medications".** The field
names the thing, the prompt the act.
**A label of "Search" and a built-in list of medicines.** opsinjs ships no
vocabulary.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA** in a source pass and a rendered pass, author-run
rather than independent. Clinical review is pending.
The audit fixed two defects in the source: the trigger button now takes an
`aria-label` built from the field's label, and the input's stray `outline-none`
no longer hides the keyboard focus ring.
* Base UI renders `role="combobox"` on the input, `role="listbox"` on the popup
and `role="option"` with `aria-selected` on each match.
* The input is the single tab stop; Arrow keys move a highlight through the popup.
* The selection is a lucide Check and the highlight a neutral surface under
`data-highlighted`, so both survive greyscale.
* The input and the trigger floor a 44pt target in rem and carry their own
focus ring.
**Known gaps.** The label reaches a screen reader as `aria-label`, not a visible
label element; a shared repair across the other input wrappers is still open.
The live match count is not announced as the reader filters. No contrast pair is
measured, so the report below stands in.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
No pre-ticked boxes, no default-on switches, no *agree* that is also *continue*, and no
sheet that cannot be closed without deciding.
## Anatomy [#anatomy]
**Both labels written as the answer they are**, the refusal naming what will not
happen, at the same size.
**A large filled "Allow" with a small grey "Not now" beneath.** The hierarchy is the
question.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA, source pass and rendered axe pass. The audit is author-run,
not an independent review, and clinical review is still pending.
**Gated on every commit by `pnpm run check:a11y`:** no `px` size, no raw colour, no banned
word, no element resolving a category or status property.
* `heading` is the dialog's accessible name and `purpose` its description; focus lands on
the sheet. The two decisions are one grid, one `Button` variant at one size, decline first,
never stacked, and the copy carries every meaning so nothing rides on colour. The details
trigger is a real button with `aria-expanded` and `aria-controls`.
**What the audit changed.** One fix: the disclosure trigger's focus ring now uses the
`--opsin-border-focus` token the decision buttons share, so a theme that thickens the focus
ring reaches it too. A ring was already visible, so this closes no gap.
**Residual.** With `heading` omitted the sheet refuses to ask and the dialog then has no
accessible name; the component dev-warns, so this is invalid usage, not a supported state.
The open sheet could not be exercised on the stale port 4000 build, so those verdicts rest on
source. Focus trap, focus return, dismissal and the swipe close alternative belong to
[Sheet](./sheet.mdx) and are verified there.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Delete reading
setOpen(false)}>Keep it
}
/>
```
## When to use it [#when-to-use-it]
**"Delete this reading? It will be removed from your history. \[Delete reading]
\[Keep it]"** Question, consequence, two verbs.
**"Are you sure? \[OK] \[Cancel]"** Sure about what, and which button does which?
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA: a source pass and a rendered pass. The rendered pass
found no axe violations, no undersized target, no focus-visible miss, and held at
320px. The source pass found no critical, serious or moderate defect. The audit is
author-run, not independent, and clinical review is pending.
Confirmed:
* `severity="alert"` swaps in Base UI's alert-dialog root, tying the role to the
refusal to dismiss.
* Named by its title, described by its description; a blank description renders
nothing.
* Focus moves in on open, is trapped, and returns on close to whatever had it.
* The page behind is `aria-hidden`, not `inert`, so focus from behind can still
reach it.
One residual: `Dialog.Close` uses a raw `focus-visible` utility, not the
border-focus token, but renders a valid 2px offset ring, so 2.4.7 and 1.4.11 pass;
it matches the reviewed `sheet` close control by design.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
The product's own two sentences go here. opsinjs ships none of them.
```
## When to use it [#when-to-use-it]
This note sets expectations. It never transfers risk onto the reader.
## Anatomy [#anatomy]
**Name what the product does, then the one limit that matters most, one sentence
each, in the product's register.**
**Open with the trading name, stack abstract nouns for what it is not, and close by
placing reliance on the reader.**
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA.** A source pass and a rendered pass, author-run rather
than independent, clinical review still pending. The rendered pass on
`/view/base/base-lyra/component/disclaimer-note` was clean: zero axe violations, the
link kept its target floor, focus-visible held, and nothing scrolled sideways at 320px
or 200% text. Nothing in the source needed changing. The standing guarantees hold: type
sizes and colours are role tokens, the decorative glyph is `aria-hidden`, the statement
is a real paragraph, and the only interactive element is a real anchor that warns on
unhelpful labels.
**One deferred item.** The root is a plain `` with no `role` and no accessible
name, so a screen reader meets the note as ordinary sentences rather than a bounded
"note". Reading order and content are fully conveyed, so this is not an AA failure. The
boundary is an enhancement left out on purpose: a `role` is a spec decision reserved to
review, and an `aria-label` would inject an English string into a translation-neutral
component. Standing gates still cover its one string on every commit: no `px` type size,
no raw colour literal, no banned word.
## API reference [#api-reference]
`children` is typed optional and required by the contract, so the missing state can
render and print its admission. `placement` changes only the space above the note, and
there is no `top` value: never above the result. There is no default text and no
colour prop, and an axis class through `className` raises a development warning.
## Related [#related]
* [Callout](./callout.mdx) is information about the content. A disclaimer is about the product.
* [AlertBanner](./alert-banner.mdx) is entitled to speak; styling a disclaimer as one is the commonest mistake.
* [ConsentSheet](./consent-sheet.mdx) is a request the reader answers, not a statement they read.
* [CareCard](./care-card.mdx) is an instruction with an author. A disclaimer asks for nothing.
---
# Divider
Source: https://opsinjs.pensievelabs.org/components/divider
Markdown: https://opsinjs.pensievelabs.org/components/divider.md
Section: Components · kind: component · status: shipped · also known as: separator, rule
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
## Installation [#installation]
## Usage [#usage]
```tsx
import { Divider } from "@/components/ui/divider"
```
```tsx
```
## When to use it [#when-to-use-it]
## Anatomy [#anatomy]
## Examples [#examples]
### A labelled boundary in a list [#a-labelled-boundary-in-a-list]
`label` marks the seam between today's items and the earlier ones. The two lists
carry the grouping on their own; the divider is the visible echo, not the only signal.
### A vertical rule between inline facts [#a-vertical-rule-between-inline-facts]
`orientation="vertical"` draws a hairline that takes its height from the flex row
around it. In a block that gives it no height it collapses to nothing.
## Content guidelines [#content-guidelines]
A label is a short plain noun for the boundary it marks: *Earlier*, *Today*,
*Archived*. It is not a heading and not a sentence, so no verb and no full stop.
Never let a divider be the only thing separating two groups; group with a list, a
heading or a region first, then add the line.
**A divider between two lists** that already carry their own structure, so the line is an echo.
**A divider between two runs of paragraphs** to imply sections a screen reader cannot hear.
## Accessibility [#accessibility]
**Checked by `pnpm run check:a11y` on every commit.** Every colour is a role
token, no type size is in `px`, and no banned word appears anywhere.
**Audited against WCAG 2.2 AA**, in a source pass over `divider.tsx` and its two
examples and a rendered pass over the shipped preview. The audit is author run,
not an independent review, and clinical review is still pending. It found
nothing to change.
* Not focusable and captures no key, in either orientation and whether or not
it is labelled.
* Unlabelled, the root exposes `role="separator"` with `aria-orientation`, so a
reader navigating by region can skip it.
* Labelled, the root has no role, because a separator cannot carry an accessible
name. The label is plain text between two `aria-hidden` hairlines.
* A divider is never the only carrier of grouping for a screen reader; the groups
either side must be separated by structure too.
**Residual, not yet measured.** The hairline's contrast against a card, a sheet
and the page, and the labelled form's footnote text against
`--muted-foreground`, are both shared role token pairs missing from the
generated contrast table; fixing either means editing the token set, which sits
outside this component's own file.
## API reference [#api-reference]
`orientation` defaults to `horizontal`; an unknown value is drawn horizontal with
a development warning. `label` applies to the horizontal form only and is dropped
with a warning on a vertical rule. A whitespace-only label counts as none.
`className` is the only route by which colour can reach the component, and both
colour axes stay off it.
## Related [#related]
* [Card](./card.mdx) groups content by giving it a background, an edge and padding. A divider only draws a line.
* [Surface](./surface.mdx) places a group on its own material at a chosen depth. A divider marks a seam between peers.
* [SegmentedControl](./segmented-control.mdx) offers a choice between views. Its seams look like dividers but carry a selection.
---
# DoseTracker
Source: https://opsinjs.pensievelabs.org/components/dose-tracker
Markdown: https://opsinjs.pensievelabs.org/components/dose-tracker.md
Section: Components · kind: component · status: shipped · also known as: medication, pill tracker, dose, adherence tracker
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
## Installation [#installation]
## Usage [#usage]
```tsx
import { DoseTracker } from "@/components/ui/dose-tracker"
```
```tsx
```
## When to use it [#when-to-use-it]
## Clinical meaning [#clinical-meaning]
**Asserts.** Exactly the log the product handed it: these medicines, at these times, in these states. A "Missed" marker says the product recorded that dose as missed, and nothing further.
**Never read as.** Advice, a diagnosis, an adherence score or an instruction. A "Missed" row names a fact, never a fault and never a next step. It computes no percentage, because that would be a clinical figure nobody authored. [Clinical interaction guidelines](../health/clinical-interaction-guidelines.mdx) draws the line between recording a fact and prescribing a response.
**Colour axis.** Neither. A dose state is a fact, not a level of urgency, so no marker carries `data-status` or `data-category`. Each marker is neutral chrome with a word and a distinct shape, so the four states survive greyscale. Painting a missed dose the red that means "act now" is exactly the axis mixing [The two colour axes](../health/two-colour-axes.mdx) forbids.
**Thresholds.** The consuming product, always. DoseTracker ships no schedule, no drug data, no dose, no threshold and no default text. Each would be a clinical claim [Regulatory context](../health/regulatory-context.mdx) says a presentation layer cannot make.
**Time.** Each entry's `time` and `now` go to [RelativeTime](./relative-time.mdx) unmodified, so it owns what a stale or future instant renders as. [Uncertainty and staleness](../health/uncertainty-and-staleness.mdx) is the rule it keeps.
## Anatomy [#anatomy]
## Examples [#examples]
### A day's doses [#a-days-doses]
A day's medicines as the product logged them, some taken, one missed, one skipped, driven by each entry's `state`. In greyscale the states are still told apart by their words and shapes.
### A missed dose [#a-missed-dose]
One `state="missed"` entry, shown as a fact and left there: a word, a shape, a time, no red, no next step and no adherence figure.
## Content guidelines [#content-guidelines]
Write each medicine name in the words the reader already knows it by. Keep `note` short and factual, such as "with food" or who marked the dose. A note that tells the reader what to do is advice, and belongs in a [CareCard](./care-card.mdx). The banned words at [Reference ranges](../health/reference-ranges.mdx) apply to every name and note.
**A missed dose marked "Missed" in neutral chrome, with nothing else on the row.**
**A missed dose in a red chip reading "Take now" under an "80% adherence" figure.**
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA, in a source pass and a rendered pass.** This is an author-run audit, not an independent review, and clinical review is pending. The rendered pass on `/view/base/base-lyra/component/dose-tracker` was clean, and the source pass found no defect, so nothing was changed.
**What the audit confirmed.**
* Each marker shape carries `aria-hidden` beside a visible word (1.1.1), and a real `ul`/`li` carries the list semantics (1.3.1).
* No status colour, category colour or colour literal: each state is told by a word and a distinct lucide shape.
* Icons are em-sized, so at 200% text they grow with the step and the times wrap rather than clip. No `px` type size.
**What a reader should still know.**
* The list's accessible name is offered only through `label`, as an `aria-label`. Every example supplies one, but a persistent visible label is a recommended enhancement.
* No `aria-live` region is announced: this static read-only log renders once and never updates in place, so 4.1.3 owes no status message.
* With no interactive element, target size (2.5.8), focus visibility and keyboard operation do not apply.
**Not measured.** Every contrast pair of hairline and muted ink against the host ground, and the markers under `forced-colors: active`.
## API reference [#api-reference]
An empty `entries` array renders nothing and warns in development. A `state` outside the four renders its row with no marker and warns, never approximated into a shape. `now` is required: read the clock once per screen and pass the same instant to every timestamp. `label` is the list's `aria-label`.
## Related [#related]
* [LogSheet](./log-sheet.mdx) records the general daily entries the product defines. A symptom, a meal or a mood is not a dose.
* [CareCard](./care-card.mdx) is where advice about a dose belongs, with its guidance and author explicit.
* [TimelineEntry](./timeline-entry.mdx) marks one event on a timeline, where DoseTracker is a day's doses read together.
---
# EmptyState
Source: https://opsinjs.pensievelabs.org/components/empty-state
Markdown: https://opsinjs.pensievelabs.org/components/empty-state.md
Section: Components · kind: component · status: shipped · also known as: blank slate, no data, nothing here, zero state
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
## Installation [#installation]
## Usage [#usage]
```tsx
import { EmptyState } from "@/components/ui/empty-state"
```
```tsx
Once you add your first reading it will be here, with the range your product
compares it against.
```
## When to use it [#when-to-use-it]
## Anatomy [#anatomy]
## Examples [#examples]
### A filter matched nothing [#a-filter-matched-nothing]
`reason="no-matches"` with an `onSelect` that clears the filter. The list owns the
live region and moves focus when the control unmounts.
### What happens when nobody wrote the body [#what-happens-when-nobody-wrote-the-body]
The first card has no `children`, so it admits the app does not say why and
warns. The second has two sentences.
### An illustration, and what it is not allowed to do [#an-illustration-and-what-it-is-not-allowed-to-do]
`illustration` is `aria-hidden` and `inert`, hidden in print and below 17rem.
Cover it and the state still reads whole.
## Content guidelines [#content-guidelines]
Say what is not here, then why, then what to do. For `not-enough`, state the
rule and the gap. For `could-not-load`, say the load failed, not that the reading is
missing. See
[Error and empty messages](../content/error-and-empty-messages.mdx).
**"No readings yet. Add your first and it will be here. \[Add a reading]"**
Names the absence, one action.
**"Nothing to see here!"** Cheerful about missing health data, no
explanation, nothing to do.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA in a source pass and a rendered pass. The audit is
author-run, not an independent review, and clinical review is pending.
Both passes found nothing to change. Neither colour axis is used, so nothing can
mix. `titleLevel` renders a real `h2` to `h6`, default `2`; check it against the outline. The `could-not-load` flag carries its meaning in a word beside an
`aria-hidden` icon, not colour. The `href` action is an anchor floored at
`var(--opsin-target-minimum, 2.75rem)` on both axes.
No live region is mounted, by design. On a stateless, read-only render a live region
could only mis-fire, since it announces only changes made after first paint. The
announcement belongs to whatever region changed, which the caller owns, as the
filter example shows.
The rendered pass measured the default preview on `/view` and returned clean; the
three example files were audited from source. Contrast against the card surface is
unmeasured; the report below carries it.
## API reference [#api-reference]
`reason` and `title` are required. There is no exported `EmptyReason` type, so
name the union `EmptyStateProps["reason"]`. A blank `title`, a body with no
text or only a number, and an action with nothing to do each render a fallback and
warn once. A `secondary` with no `action` also warns.
## Related [#related]
* [Skeleton](./skeleton.mdx) is for content that is coming, not content that is
absent.
* [AlertBanner](./alert-banner.mdx) speaks for the whole view. `could-not-load`
reports one surface's failure in place.
* [Callout](./callout.mdx) is a note beside content that exists.
* [TrendSparkline](./trend-sparkline.mdx) draws the too-short refusal in a chart
card. `not-enough` carries it with no chart.
---
# Field
Source: https://opsinjs.pensievelabs.org/components/field
Markdown: https://opsinjs.pensievelabs.org/components/field.md
Section: Components · kind: component · status: shipped · also known as: form field, label, input wrapper, error message, hint, form control, validation message
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
## Installation [#installation]
## Usage [#usage]
```tsx
import { Field } from "@/components/ui/field"
```
```tsx
```
## When to use it [#when-to-use-it]
## Anatomy [#anatomy]
## Examples [#examples]
### The error keeps the hint [#the-error-keeps-the-hint]
`error` adds a sentence beside the hint rather than replacing it.
### Marking the exception [#marking-the-exception]
One optional field among three needed ones, marked by `optionality="optional"`.
See [Required and optional](../patterns/forms/required-and-optional.mdx).
### A control opsinjs does not ship [#a-control-opsinjs-does-not-ship]
`render` on `Field.Control` puts the whole wiring onto a `textarea` and a
`select`.
### Validating on submit [#validating-on-submit]
The default `validateOn` fires on submit only inside `Field.Form`, where an
empty field on Save shows the browser's own message. Pass `error` instead.
## Content guidelines [#content-guidelines]
Labels are nouns in sentence case with no colon. Hints show the shape of a valid
answer, never a number a reader could read as a result. Errors say what to fix,
without blame.
**"Date of birth" over three labelled fields, error "Enter a date in the past".**
**"DOB*" with "Invalid input."*\* An abbreviation, an unexplained symbol, no fix.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA in a source pass and a rendered pass on
`/view/base/base-lyra/component/field`. The audit is author-run, not an
independent review, and clinical review is pending. The rendered pass was clean:
no axe violations, targets met `--opsin-target-minimum`, focus visible, no
reflow at 320px.
**Fixed here.** The error now carries a live region, so it is announced on
submit while focus is on Save, where it was silent before.
**From source.** A native `label` against a generated id; `aria-describedby`
survives unmount; `aria-invalid` sits on the control; the invalid state is a
glyph and a left rule, never colour. `pnpm run check:a11y` guards role tokens
and non-`px` sizes.
**Limits.** The required and optional word is English only and untranslatable by
prop. The focus ring lives in `product.css`, so a `shadcn add` copy without it
shows no ring until you add one. The invalid shadow drops
under forced colours and print, where the glyph, words and rule still carry the
state.
## Data attributes [#data-attributes]
## API reference [#api-reference]
`label` is required and there is no `hideLabel`. An empty `label` or `error` is
refused with a development warning. Without a `Field.Form` ancestor the default
`validateOn` checks on Enter alone.
## Related [#related]
* [ReadingInput](./reading-input.mdx) is a Field with a unit and a plausibility contract.
* [LogSheet](./log-sheet.mdx) captures several Fields together.
* [Callout](./callout.mdx) is guidance about a whole form, not one control.
* [AlertBanner](./alert-banner.mdx) is the summary at the top of a failed form.
---
# GoalRing
Source: https://opsinjs.pensievelabs.org/components/goal-ring
Markdown: https://opsinjs.pensievelabs.org/components/goal-ring.md
Section: Components · kind: component · status: shipped · also known as: activity ring, close your rings, daily goal
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
## Installation [#installation]
## Usage [#usage]
```tsx
import { GoalRing } from "@/components/ui/goal-ring"
```
```tsx
```
## When to use it [#when-to-use-it]
## Clinical meaning [#clinical-meaning]
**Asserts.** One thing: this value is this far towards a goal the product set.
The fraction is arithmetic over the two values, and the readout prints both in
the [reader's locale](../health/numbers-units-precision.mdx), unit after. The
fill is drawn where the reading sits, and
[nothing sweeps](../health/motion-in-health-ui.mdx) on first paint.
**Never read as.** A diagnosis, a verdict on the reader, or a target opsinjs
chose. A full ring means the product's goal was met, never that the reader is
well, and an open ring never means something is wrong. It rewards no streak, and
"normal" and "abnormal" appear in
[no state it draws](../health/reference-ranges.mdx).
**Colour axis.** [Category only](../health/two-colour-axes.mdx). The fill takes
the [identity tint](../health/category-identity.mdx) of what the ring counts,
the track stays neutral, and no element carries `data-status`.
**Thresholds.** None. The product owns the goal, the label and the unit;
GoalRing ships no default goal and no clinical vocabulary.
## Anatomy [#anatomy]
## Examples [#examples]
### Progress towards a goal [#progress-towards-a-goal]
A synthetic step count part-way towards a goal the product set.
`category="activity"` tints the fill and the sentence beneath names the progress
without praise.
### No reading yet [#no-reading-yet]
`value={null}` draws an empty ring and words that say nothing has been measured,
never a zero.
## Content guidelines [#content-guidelines]
Write the label as the reader's own name for what the ring counts: "Steps
today", not a metric code. Keep the unit in their words too. Never phrase the
copy as a challenge, and never put a streak counter or celebration beside it.
When the goal is met the ring says so and stops.
**"Steps today", "6,200 of 8,000 steps"** prints the real figures against the product's goal.
**"Great job! 3 day streak, keep it up!"** beside a closed ring turns a reading into a game.
## Accessibility [#accessibility]
**Checked by `pnpm run check:a11y` on every commit.**
* No element carries both axes: the fill carries `data-category` alone and nothing stamps `data-status`.
* No raw colour literal and no ramp step. The track is the neutral border role and the fill a category `-accent` role.
* No type size in pixels: label, readout and sentence are the `subheadline`, `title2` and `footnote` steps.
**Audited against WCAG 2.2 AA.** A source pass and a rendered pass both ran and
found nothing to change in the source. This is an author audit, not an
independent review, and clinical review is still pending. The graphic is
`role="img"` with an accessible name that speaks the label, the value against the
goal and the progress sentence, all repeated in the visible words beside it.
Nothing takes focus or animates on first paint, so there is no keyboard contract.
Three states stay three: a finite value draws a fill, null says "no reading yet",
a broken value says "not available". Under forced colours the track maps to
CanvasText and the fill to Highlight.
**Residual.** No contrast pair is measured, so the page prints the contrast pairs
as unmeasured rather than as a pass. The arc and track repeat every fact in the
visible text and the accessible name, so under 1.4.11 they are not graphical
objects required to understand the content. A read-only display carries no live
region, so a screen reader is not told when the value changes over time; the
product owns whether to wrap the ring in a live region.
## Data attributes [#data-attributes]
## API reference [#api-reference]
`value` is `number | null`: null is no reading and is never drawn as zero, and a
non-finite value is announced as "not available". A goal of zero or less draws
an empty ring and raises a development warning. `category` outside the six
known names is refused with a development warning and the fill falls back to
neutral.
## Related [#related]
* [ScoreDial](./score-dial.mdx) is a composite number against a scale with named bands.
* [MetricTile](./metric-tile.mdx) is one reading on its own, with no goal to measure it against.
* [RangeBar](./range-bar.mdx) is a reading against a reference range, where the band it lands in is the meaning.
---
# IconButton
Source: https://opsinjs.pensievelabs.org/components/icon-button
Markdown: https://opsinjs.pensievelabs.org/components/icon-button.md
Section: Components · kind: component · status: shipped · also known as: glyph button, round button
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
## Installation [#installation]
## Usage [#usage]
```tsx
import { IconButton } from "@/components/ui/icon-button"
```
```tsx
import { Search } from "lucide-react"
}
label="Search readings"
onClick={openSearch}
/>
```
## When to use it [#when-to-use-it]
## Anatomy [#anatomy]
## Examples [#examples]
### A toolbar of icon buttons [#a-toolbar-of-icon-buttons]
A header row where each glyph is one the reader already knows. Each control
still carries a distinct `label`, because a toolbar is where an unnamed icon
button disappears.
### Icon buttons in a list row [#icon-buttons-in-a-list-row]
Repeated row actions, where a labelled Edit and Remove on every row would crowd
the reading out. Each `label` carries its row's context, so a voice-control user
reaches one control.
## Content guidelines [#content-guidelines]
The label is the whole message for a reader who does not see the glyph. Name
the action and its object, in sentence case, without terminal punctuation.
Choose a glyph the audience already knows, and let the glyph and the name
agree: a magnifier means search, a cross means close.
**`label="Close the reading details"`** with a cross glyph. A verb and its
object reads well aloud.
**`label="button"`, or no label at all.** A screen reader announces "button"
and nothing else.
## Accessibility [#accessibility]
**Checked by `pnpm run check:a11y` on every commit.** Every colour is a role
token, no type size is in `px`, and no banned word appears anywhere.
**Audited against WCAG 2.2 AA, source and rendered passes, author-run and not
independent.** Clinical review is pending. The audit found no critical, serious
or moderate defect in the source.
* A real `button` element through [Button](./button.mdx) supplies Return, Space,
the role and the tab stop.
* The name is `aria-label` plus a visually hidden text node; a missing or
whitespace-only `label` raises a development warning.
* The glyph is `aria-hidden`, never announced as a second, pictorial name.
* The target is a 44pt square in rem, with horizontal padding removed and
separation left to the caller's `--opsin-target-separation`.
**Icon-only by design.** With no visible text, `aria-label` plus the hidden
text node is the correct and complete name route rather than a persistent
visible label. The docblock warns in development on a missing `label`.
**Not measured.** Contrast on every variant, the focus ring, and forced
colours, all inherited from Button.
## API reference [#api-reference]
`icon` and `label` are both required. `variant` defaults to `secondary` over
`quiet`, since a bordered control is easier to recognise without a word inside
it. There is no `busy`, `busyLabel`, `fullWidth`, `iconPosition` or `type`.
`className` must never resolve a `--opsin-status-*` or `--opsin-category-*`
role; an IconButton carries no clinical axis.
## Related [#related]
* [Button](./button.mdx) is the labelled control this one defers to.
* [Switch](./switch.mdx) turns something on or off; an icon button acts and
does not hold a setting.
* [Tooltip](./tooltip.mdx) supplements a name and is never the name itself.
---
# Link
Source: https://opsinjs.pensievelabs.org/components/link
Markdown: https://opsinjs.pensievelabs.org/components/link.md
Section: Components · kind: component · status: shipped · also known as: anchor, hyperlink
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
## Installation [#installation]
## Usage [#usage]
```tsx
import { Link } from "@/components/ui/link"
```
```tsx
See your results
```
## When to use it [#when-to-use-it]
## Examples [#examples]
### Each emphasis [#each-emphasis]
`emphasis` is required and has no default. `inline` sits inside a sentence,
`action` is a card's primary action and `secondary` is the quiet one beside it.
```tsx
Your readings are yours to keep, and you can{" "}
Book a repeat appointment
Read about this measurement
```
### Routing through the product's own link [#routing-through-the-products-own-link]
Pass the router link as `render` so navigation stays client-side. Link merges
its classes, its `data-slot` and its target floor onto that element and replaces
its children with the label.
```tsx
import NextLink from "next/link"
import { Link } from "@/components/ui/link"
}>
See your results
```
## Content guidelines [#content-guidelines]
Link text names the destination, in sentence case, without terminal punctuation.
Write it to read alone, out of a screen reader's list of links. Never *click
here*, *read more*, *learn more* or a bare *here*: each sends the reader back up
the page to reconstruct what the link is about. A link that opens in a new tab
says so in its own text; opsinjs does not add that word.
**"See your results"** names where it goes and survives being read out of context.
**"Click here"** heard three times in a link list tells the reader nothing about any of them.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA** in a source pass and a rendered pass. The audit
is author-run, so it is not an independent review, and clinical review is still
pending. `pnpm run check:a11y` also runs on every commit: every colour is a role
token, no type size is in `px`, and no banned word appears anywhere.
Two moderate gaps were fixed in this pass:
* A `target="_blank"` link now defaults `rel` to `noopener noreferrer`, keeping
any `rel` the caller supplied, and appends an `sr-only` "(opens in a new tab)"
tail so the change of destination is spoken (2.4.4).
* The `inline` focus ring now reads `--opsin-border-focus`, so it grows when a
low-vision consumer raises that token instead of staying flat at 2px. It still
defaults to 2px, so nothing changes visually (2.4.7, 1.4.11).
Two items a reader should know are honestly left as they are:
* The new-tab cue is spoken only through `sr-only` text, not a visible marker,
to preserve the visual design. A caller who wants a visible external cue adds
their own.
* `inline` sits below the 24px target floor by design, because SC 2.5.8 exempts
an inline target inside a sentence and a full floor would inflate the line
box. `action` and `secondary` keep the `--opsin-target-minimum` floor in both
axes.
Contrast for the three emphases and for the per-level boundary on a status tint
is not yet measured, and whether the ladder holds in greyscale is argued rather
than tested.
## API reference [#api-reference]
`href` and `emphasis` are both required, with no default for either. `ground`
defaults to `neutral` and is inert for `inline`. When `render` is passed, Link's
own `href`, `data-slot` and attributes win over the router element's, and the
two class lists are joined.
## Related [#related]
* [Button](./button.mdx) does something rather than going somewhere. It refuses `href`, so an action with no new URL stays a button.
* [Card](./card.mdx) carries its own wrapper anchor when the whole surface is the destination, rather than a Link inside it.
---
# LogSheet
Source: https://opsinjs.pensievelabs.org/components/log-sheet
Markdown: https://opsinjs.pensievelabs.org/components/log-sheet.md
Section: Components · kind: component · status: shipped · also known as: log, capture, quick entry, bottom sheet entry, diary, journal, daily entry
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
## Installation [#installation]
## Usage [#usage]
```tsx
import { LogSheet } from "@/components/ui/log-sheet"
```
```tsx
store(entry)}
>
```
## When to use it [#when-to-use-it]
## Clinical meaning [#clinical-meaning]
**Asserts.** That the reader recorded this value, at this time, themselves.
`LogEntry.provenance` is the literal `"self-reported"` and no prop changes it. See
[Data provenance and device accuracy](../health/data-provenance-and-device-accuracy.mdx).
**Never read as.** A clinical observation or an assessment. The sheet never evaluates
what is entered or says whether it is worth acting on.
**Colour axis.** Category only, on one band beneath the heading carrying `data-category`
with no word and no glyph. The status axis never appears here: an amber field
mid-keystroke teaches a person to stop logging honestly.
**Thresholds.** None. LogSheet holds no ranges and never blocks a save, so an unlikely
value still saves. A plausibility warning belongs on [ReadingInput](./reading-input.mdx).
`maxBackdateDays` has no default and constrains the platform picker, not the save.
**Timing.** `occurredAt` is the time the entry is about and `recordedAt` the save time.
`backdated` is true only when the reader moved the time control.
## Anatomy [#anatomy]
## Examples [#examples]
### Leaving with unsaved input [#leaving-with-unsaved-input]
Escape, the background, a drag and the close control all ask the same question in the
footer. `onDiscard` receives the entry about to be lost.
### Two fields, and the window the product owns [#two-fields-and-the-window-the-product-owns]
Two controls write two keys into one entry through `values`. `maxBackdateDays` sets the
picker's earliest day, and the sheet still refuses no save.
## Content guidelines [#content-guidelines]
The title names what is being logged: *Blood pressure*, *How you slept*. `saveLabel`
says what it saves, *Save reading*, never *Done*, so it has no default. Ask for nothing
you can infer; the fourth field stops people logging.
**"Systolic, Diastolic, Time (now), Save reading."** Three inputs and an action
that says what it does.
**"Systolic, Diastolic, Pulse, Arm, Position, Cuff size, Mood, Notes, Submit."**
Defensible fields, unusable set.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA in a source pass and a rendered pass. This audit is
author-run, not an independent review, and clinical review is still pending.
The audit found nothing to change here. Both inputs take their name and description
from [Field](./field.mdx), so name, role and value hold; the only coloured element is
the aria-hidden category band; and the single tokenised column reflows and scales.
Three items are argued, not measured.
* The discard question is announced by a focus move and `aria-describedby`, not a live
region; a second modal was declined on purpose.
* No *Saved* status is announced: `onSave` never closes the sheet, so the component cannot
know the save landed and that feedback belongs to the product.
* Save is one explicit tap with no confirm step: no autosave, every field visible, sheet
stays open for undo.
The open sheet was not re-measured in a browser: port 4000 holds a stale build.
`axe` on the static rendered page is clean.
## Data attributes [#data-attributes]
## API reference [#api-reference]
`open`, `onOpenChange`, `title`, `detents` and `className` come from
[Sheet](./sheet.mdx). `footer`, `modal` and `dismissible` are omitted on purpose.
`onSave` never closes the sheet; only the product knows whether the save landed. Both
handlers receive a `LogEntry`:
```tsx
export interface LogEntry {
values: Record
occurredAt: string
recordedAt: string
backdated: boolean
provenance: "self-reported"
note?: string
}
```
## Related [#related]
* [Sheet](./sheet.mdx) is the general surface. LogSheet adds a capture contract and one save.
* [ReadingInput](./reading-input.mdx) is the single control that goes inside.
* [Questionnaire](./questionnaire.mdx) is an assessment, not a record.
* [Field](./field.mdx) is for entries that belong on a page, and wires every control here.
* [ConsentSheet](./consent-sheet.mdx) asks for permission rather than a record.
---
# Menu
Source: https://opsinjs.pensievelabs.org/components/menu
Markdown: https://opsinjs.pensievelabs.org/components/menu.md
Section: Components · kind: component · status: shipped · also known as: dropdown menu, context menu, overflow menu
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Actions}
items={[
{ label: "Share", onClick: onShare },
{ label: "Rename", onClick: onRename },
{ label: "Remove from list", separatorBefore: true, onClick: onRemove },
]}
/>
```
## When to use it [#when-to-use-it]
**"Share" · "Rename" · "Remove from list"** names the object.
**A red "Delete" item** borrows the status axis.
## Accessibility [#accessibility]
**Checked by `pnpm run check:a11y` on every commit.** No colour literal, no
`px` type size, every item floored at `--opsin-target-minimum`.
**Audited against WCAG 2.2 AA, source and rendered, author-run and not
independent.** Clinical review is still pending. The rendered pass (axe,
target size, focus, reflow) came back clean.
* Base UI renders `aria-haspopup`, `role="menu"` and `role="menuitem"`, and
wires the popup's accessible name to the trigger.
* The highlighted item takes real keyboard focus, so a house focus ring on
`focus-visible` marks it, drawn inward so the scroll clip never cuts it.
* A disabled row drops to the muted ink; Escape and a choice both return focus
to the trigger.
**Known gaps.** The roving highlight fill sits near 1.13:1 against the card,
short of the 3:1 a state cue needs; the focus ring covers that case for now.
An icon-only trigger ships an unnamed menu, so give it a label. Every
contrast pair remains unmeasured.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Resting heart rate"**, with the unit beside the number and the recency on the tile.
**"RHR"** with a bare number: an unknown acronym, no unit and no date.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA in a source pass and a rendered pass. The audit is author-run,
not an independent review, and clinical review is still pending. The rendered pass returned
zero axe violations, no target-size hits, no `focus-visible` failure and no reflow at 320px;
the source pass found no defect to fix.
**Residual.**
* A linked tile can trip WCAG 2.5.3 Label in Name because `Value` speaks *kilograms* for a
visible *kg*. The repair belongs in `Value` and is deferred; the *steps* demo does not trip.
* Nothing enforces the JSDoc rule that `attention` and `urgent` pair with an `href`.
* The event word names when a reading happened, not how it was obtained; there is no
provenance prop, so an estimate and a lab result sound alike.
**Beyond the audit.** Contrast as the tile composes it, `prefers-contrast: more`,
`forced-colors`, 200% text, print, and masking all stay unverified.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**`label="Number of copies"`, `step={1}`, `min={1}`.** Names the count, steps
by whole copies, floors at a real bound.
**`label="Systolic"` with a min and max around a reading.** A measurement
dressed as a count. It is a [ReadingInput](./reading-input.mdx).
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA, source and rendered.** The audit is author-run,
not independent, and clinical review is pending. The rendered
pass was clean: no axe violations, focus visible, a 44px target floor, no loss at
320px reflow. The source pass confirmed icons are `aria-hidden`, neither colour
axis nor a colour-only state, role tokens with no `px` type, and Base UI’s own keyboard and names.
**What the audit fixed.** The input could be named only through `aria-label`. The
wrapper now also forwards `id` and `aria-labelledby`, suppressing the redundant
`aria-label` when a visible label is wired so it wins the name and Label in Name
holds. `label` stays the required default, so the change is additive.
**Residual.** The default still names the input through `aria-label`; a
persistent visible label is a recommended enhancement, deferred to one central
repair across the input wrappers. Base UI hard-codes `autoComplete="off"`,
acceptable for a count with no WCAG token, and surfaces no error text, since it
clamps to bounds and owns validation. Every contrast pair, including the disabled
ink at a bound, is unmeasured, so the report below stands in.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Entries you add yourself sit in one list, and entries from a connected
device sit in another, so you can always tell which is which.
```
## When to use it [#when-to-use-it]
**"How readings are grouped"**, titled, short, easily dismissed.
**A blood pressure reading and its status**, untitled: no name, no range, wrong surface.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA on `/view/base/base-lyra/component/popover`, in a source
pass and a rendered pass. Author-run, not independent; clinical review is pending.
**Fixed.** The trigger's hit area was floored on height alone, so an icon-only
trigger could clear the AA 24px minimum while still missing the house width floor.
A matching `min-w` at `--opsin-target-minimum` now floors it too, following the
`icon-button` pattern.
**Confirmed.**
* The panel is `role="dialog"`, named by `aria-labelledby`; a missing title warns.
* Focus moves into the panel on open and back to the trigger on close, by Base UI.
* The arrow is `aria-hidden`; under `prefers-reduced-motion` only opacity crossfades.
* No status colour, literal, ramp step or `px` size: neutral chrome, the `overlay`
shadow token, and the `body` and `headline` steps only.
**Residual.** The wrapper takes no `aria-label` prop, so an icon-only trigger needs
a name from the caller's trigger node; every shipped trigger already uses named text.
Contrast pairs remain unmeasured, below.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Uploading photos" at a real 45.** The label names the task and the readout
matches the fill.
**A resting heart rate drawn as a fill towards a full track.** It invents a
target the reading never had.
## Accessibility [#accessibility]
**Checked by `pnpm run check:a11y` on every commit.** Colour is a role token
on neither axis; no type size is in `px`.
**Audited against WCAG 2.2 AA**, source and rendered, author-run rather than
independent, with clinical review still pending. Three fixes landed: a plain
`aria-label` on the root so the name survives a first paint before Base UI's
own wiring runs, a sibling status region announcing `"{label} complete."` at
max, and `aria-hidden` on the indeterminate branch's text to match the
determinate readout.
* `aria-valuenow` carries the amount done, with the label, minimum and
maximum.
* Nothing takes focus, so the bar costs no tab stop.
* The transition and pulse drop under `prefers-reduced-motion`; words carry
the state.
* Type steps and the `em` track height scale together, so 200% text grows
the bar rather than clipping it.
**Still open.** Fill contrast against the track, carried below until
measured. Wrap for a long label and print output were not checked.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**The product's own questions under one title**, with scoring done on a separate surface.
**A running total or a "your result" line inside the questionnaire.** It turns a container into a verdict.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA, in a source pass and a rendered pass.** The audit is author-run, not independent, and clinical review is pending.
**Fixed in this pass.**
* Every prompt carries a stable id, and each control sits in a `role="group"` named by that prompt through `aria-labelledby`.
* The default demo's free-text control gained an `aria-label`, so it is no longer unnamed.
**Neutral chrome, checked on every commit.**
* No status colour, no category colour, no colour literal and no ramp step.
* No `px` type size. Title, prompts and readout are semantic type steps.
**Known and deferred.**
* The shell cannot name a product's own control node, so a product that passes a bare input still labels it, with the per-question group supplying context.
* The title is the form's `aria-labelledby`, drawn as a styled div, because the shell cannot know the host page's heading level. A visible heading on the product's side is recommended.
* The progress line is `aria-live="polite"`, announced as focus moves. It may read as chatty, which is a tuning question for the product.
**Not measured.** Every contrast pair against the host ground, and `forced-colors: active`.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Standard" · "Quiet" · "None"** are parallel single words, ordered from most
to least, so they read as siblings.
**"Standard reminders" · "Keep it quiet" · "I want nothing"** are three
grammars, so they stop reading as one set.
## Accessibility [#accessibility]
This was audited against WCAG 2.2 AA in a source pass and a rendered pass on
`/view/base/base-lyra/component/radio-group`. The audit is author-run, not an independent review, and clinical review is still
pending.
The audit found nothing to change. The rendered pass was clean: zero axe
violations, rows floor at `--opsin-target-minimum`, focus stays visible, no
sideways scroll at 320px. The source pass confirmed one roving tab stop, a visible
legend wired by `aria-labelledby` rather than an `aria-label`, and selection
carried three ways through `aria-checked`, the lifted ring and the filled dot,
never on colour alone.
Two residual notes. An option's `description` renders inside the radio, so the
accessible name folds it in rather than exposing it through `aria-describedby`. It is
announced and passes AA; wiring it as a distinct description restructures
the name, a redesign rather than a fix. The colour transition on the row is not
motion under 2.3.3, and its `prefers-reduced-motion` handling lives in global
product CSS. Every colour is a role token, so no contrast ratio reads from the
source; the measured pairs are the report below.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Given no range, or one with neither bound or an empty `source`, RangeBar draws no band
and substitutes no default.
## Anatomy [#anatomy]
**"26 mg/dL, above the range 10 to 20 mg/dL, from Example data."**
**"26 mg/dL. Abnormal. Your result is poor."** A verdict with no basis.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA** over the source and the rendered preview. The audit is
author-run, not independent, and clinical review is pending. The rendered pass was
clean: no axe violations, no focus-visible failure, no horizontal scroll at 320px. It is
display-only, so nothing is focusable and the keyboard and target-size checks do not
apply.
* The summary paragraph is unconditional: reading, range with its source, and within,
above or below in words, so the picture is never named.
* `RangeBar.Track` is `aria-hidden`, with no `slider`, `meter` or `progressbar` role.
* Numbers go through [Value](./value.mdx), so the unit is spoken, not spelled.
* Status carries a word and a glyph through StatusPill, redundant to the tick colour.
* Under `forced-colors` the tick keeps a `Highlight` fill and `CanvasText` outline.
**Residual.** The band outline and the two boundary marks fall below the 3:1 non-text
contrast floor. They stay because the graphic is `aria-hidden` and the summary carries
the same facts. Its own text and colour pairs are not measured yet, so the report
below stands in.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"The usual range" with a neutral swatch, then "Worth watching" with its word, glyph and colour.**
**"Normal" with a green swatch and "Abnormal" with a red one.** A verdict on the person, carried by colour alone.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA in a source and a rendered pass. The audit is author-run, not independent, and clinical review is pending.
**What the audit fixed.**
* The legend ` ` had no accessible name. Optional `aria-label` and `aria-labelledby` props forward onto the root, so a caller names the key or points it at the bar's heading.
* A blank status label would draw colour and glyph with no word, a colour-alone failure. A guard warns on it, with the empty-bands and invalid-tone guards.
**What still holds from the source.**
* Each swatch and glyph carries `aria-hidden`, so a screen reader skips the decoration.
* No element carries both `data-category` and `data-status`, and this file writes no category colour.
* Nothing takes focus, answers a key or animates, so `prefers-reduced-motion` has no state to reduce.
* At 200% text the swatches hold size, the words wrap, and no ellipsis is set.
* Under `forced-colors: active` a status fill is stripped and the swatch keeps a `CanvasText` outline.
**Residual and deferred.**
* Status swatches are fills of RangeBar's tick tones with no explicit border, so swatch-to-page contrast is unmeasured. Each swatch is `aria-hidden` decoration redundant to the word and glyph, so a low-contrast swatch loses nothing. Measuring the four fills and the neutral border in light and dark is a recommended enhancement.
* Label and description use the foreground and muted-foreground role tokens, not re-measured in this pass.
* The legend cannot enforce in code that it sits beside its bar; `aria-labelledby` is the mechanism a caller uses to bind it, and the audit cannot verify callers do.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
{
setReading(next.value)
setUnit(next.unit)
}}
/>
```
## When to use it [#when-to-use-it]
Changing the unit must never silently change the stored value or keep the typed digits
without saying so on screen.
## Anatomy [#anatomy]
` with a ``, one box per part.
**"That is a long way above most readings. Did you mean to type a decimal point?"**
**"Invalid value. That reading is outside the accepted range."** blames the reader.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA** in a source pass and a rendered pass, and
`pnpm run check:a11y` runs on every commit. The author ran the audit, so it is not
independent, and clinical review is pending.
**Fixed in this pass.** `autoComplete` is now a prop reaching `Field.Control`, defaulting
to `"off"`, because a self-reported reading has no WCAG autofill token and the component
invents none (1.3.5).
**From the source.** `Field` renders a real ``, and a compound reading is a
`` of one `Field` per part. The unit's spoken form joins the box's description,
each option carries its plural on `aria-label`, and the box is `type="text"` with
`inputMode` defaulting to `decimal`. The advisory and the effect line are descriptions:
no `aria-invalid` and no focus move.
**Left to the product.** The effect line reporting a switch sits in no live region, so a
product must wire `effectText` to a polite announcer. Without that, a non-sighted reader
hears the new unit but not that the number changed.
**Not gated.** No hit area is measured, and the boundary inherits `--border` without a
gated pair.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Never put a sync time where a measurement time belongs. *Synced 2 minutes ago* above a
reading taken four months ago is two true statements that together mislead. Render both,
each with its event word.
## Anatomy [#anatomy]
**"Measured 3 days ago, on 11 March 2026 at 08:12 UTC"** names the event and keeps the
exact time beside it.
**"Updated 2 minutes ago"** above a reading taken four months ago. Both facts are true
and together they mislead.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA** in a source pass and a rendered pass. This audit is
author-run, not an independent review, and clinical review is still pending.
The rendered pass found no axe violations, no target-size hits, no focus-visible issue
and no reflow at 320px. The source pass found one moderate item: the log-list example
rendered its rows in a `` styled `list-none`, which drops list semantics under
Safari with VoiceOver, so the rows read as generic text. A `role="list"` restores the
role with no visual or API change. The component's own source held no critical or
serious defect.
* The exact date is always in the accessibility tree and in print, never behind hover,
focus or a disclosure. `showAbsolute` moves it on screen only.
* Staleness is stated in words, never by the muted tone alone, and the words stay at the
surrounding foreground while the phrase recedes.
* It mounts no live region and owns no timer. Nothing changes at runtime to announce, so
a product re-rendering it should add no `aria-live`.
* No `"use client"`, no effect and no clock read, so hydration is safe by determinism.
Pass an explicit `locale` or server and browser may differ.
Two items remain open. The muted stale treatment's contrast against the muted or tinted
grounds it may sit on is unmeasured, and no shipped preview renders the stale state.
Screen readers in a language other than English are also unverified.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
` takes `aria-label` from the title, not `aria-labelledby`. The
string matches the visible heading and the region is non-interactive, so there is no
name mismatch; a visible-heading reference is a future enhancement.
* `className` merges onto the root, so a caller who passes `truncate` can clip a
reading. The component truncates nothing; the JSDoc warns of it.
**Not checked by any gate.** Print, `forced-colors` and `prefers-contrast`.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**`label="Comfort right now"` with end words from the product's instrument.** Named question, fixed ends, so answers compare over time.
**No `label`, invented end words, a point count that drifts between screens.** Nameless radios whose answers cannot be compared.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA, in a source pass and a rendered pass.** The audit is
author-run, not an independent review, and clinical review is pending.
* One tab stop with a roving focus: `role="radiogroup"` on the root, `role="radio"`
and `aria-checked` on each point, and selection follows focus.
* Every point floors its hit area at `--opsin-target-minimum` in rem, and the row
wraps rather than shrinking a point below its target.
**Fixed in this pass.** In forced colours the chosen point now repaints to the system
Highlight pair with a Highlight border and `forced-color-adjust-none`, so selection
stays distinct.
**Deferred, and named.** The question reaches the radiogroup only as an `aria-label`,
weaker than a visible label, the recommended enhancement, a decision shared
with combobox. In normal mode the selection carries no glyph, so luminance inversion
and the border carry it without hue. Every contrast pair on the host's ground is
unmeasured, and the report below prints only what has been measured.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
When only part of the input data was available, `coverage` must say so. Name what was
counted in your derivation; it will not guess a noun.
## Anatomy [#anatomy]
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
{items.map((item) => (
{item.label}
))}
```
## When to use it [#when-to-use-it]
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Day" · "Week" · "Month"** Three parallel windows, one word each, ordered
shortest to longest.
**"Today" · "This week's readings" · "Show me the month"** Three lengths and
three grammars, so the row stops reading as one set.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA**, in a source pass over the full rubric and a
rendered pass in the browser. The audit is author-run, not an independent
review, and clinical review is still pending.
A radio group, so the row is one tab stop with a roving focus, with
`radiogroup` plus `radio` and `aria-checked` per segment for name, role and
value. Selection is carried three ways and never by colour alone: `aria-checked`,
the card surface lifting the segment off the track, and a hairline.
**What the audit changed here.** The 44px hit-area floor sat on the height axis
only, so a single-character label or the `sm` size could shrink a segment below
the house minimum. The floor now sits on both axes, matching `scale-input` and
`tab-bar`.
**What a reader should still know.** `label` is applied only as the group's
`aria-label`, so there is no persistent visible group heading. Every option
carries visible text, so the choices are seen, but a visible group label is a
recommended enhancement, deferred as one repair across the wrappers that share
this pattern. No contrast pair has been measured, so greyscale legibility of the
selected segment is argued, not confirmed.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Choose a timezone"** as the placeholder, with parallel labels: Lisbon, Berlin, Tokyo.
**"Lisbon"** as a placeholder while nothing is chosen. A default and a blank read alike.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA in a source pass and a rendered pass, author-run
rather than independent, with clinical review still pending.
Base UI supplies a combobox trigger, a listbox popup and `aria-selected`
options; icons are `aria-hidden`, and selection is shown by a Check glyph and
`aria-selected`, not colour. The focus ring, the `--opsin-target-minimum` hit
area, neutral chrome colours and non-`px` type sizes all hold.
Two gaps remain. The required `label` becomes the trigger's `aria-label`, so
once a value fills the trigger a reader can lose its programmatic name, a gap
shared by several wrappers and waiting on one system-wide repair. At 200%
text a long value truncates in the trigger, with no loss of function since
the full label stays readable in the open list.
Contrast pairs and the popup under `forced-colors: active` are still unmeasured.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
What this sheet is for.
{/* … */}
```
## When to use it [#when-to-use-it]
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Screen brightness"** with a bare nought to a hundred readout names the
thing adjusted.
**"Blood pressure"** with a mmHg readout dresses a rough position as a
measurement.
## Accessibility [#accessibility]
This component was audited against WCAG 2.2 AA in a source pass and a rendered
pass. The audit is author-run, it is not an independent review, and clinical
review is still pending. The rendered pass was clean: no axe violations, no
target-size breach and no reflow failure. The source already handled the flagged
risks, so nothing changed here.
* 2.5.7 Dragging: the thumb wraps Base UI unmodified, so click-to-position plus
Arrow, Home, End and Page keys give every drag a keyboard alternative.
* 4.1.2 Name, Role, Value: role, `aria-valuenow`, `min` and `max` come from the
nested real range input, and the `Slider.Label` text is forwarded onto it so
the name is present at render.
* 2.5.8: the thumb hit area is floored at `--opsin-target-minimum` on both axes,
with the knob drawn smaller inside.
Two residual items. The knob's colour fade on interaction has no reduced-motion
guard, but it is a colour change and not positional motion, so any neutralisation
belongs in a shared stylesheet. The `Slider.Value` readout renders as an `output`
with a polite live region, so while dragging the value is spoken twice, a
verbosity and not a defect. Contrast pairs remain unmeasured.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Never restate a manufacturer's accuracy figure as your own, and never invent one. Attribute the claim and link it through `more`, in the manufacturer's own terms.
## Anatomy [#anatomy]
**"Estimated by your watch from movement and heart rate."** Names the device, the inputs and the class of the figure.
**"Powered by clinically validated technology."** Names no device and no method.
## Accessibility [#accessibility]
This component was audited against WCAG 2.2 AA in two passes, one over the source and one over the rendered output. The audit is author-run, not independent, and clinical review is still pending. Both passes were clean: no axe violations, target sizes met, focus visible, and no loss at 320px reflow.
* No `px` type size. Both lines are set at `text-opsin-footnote`, a rem from the generated ramp.
* No raw colour literal and no ramp step. The source ink is `--foreground` and the date ink is `--muted-foreground`.
* `more` carries the label and the href together, so a link cannot be added without a label. An external href adds an off-screen "opens in a new tab".
* The link is not inside a sentence, so it re-adds `--opsin-target-minimum` on both axes. See [Target size and motor](../accessibility/target-size-and-motor.mdx).
* It reflows at 200% text: no fixed height, `min-w-0` with `wrap-break-word`, so a long device name breaks.
**Residual, left for you to weigh.**
* The source line, the last-checked time and the fuller-citation link render as loose siblings with no programmatic group binding them into one citation. Reading order keeps the association, so this is not an AA failure.
* The "Last checked on" chrome is always English while the date follows the caller's `locale`; when they differ, the localized date carries no `lang` seam yet, per ADR 0005.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Loading
```
## When to use it [#when-to-use-it]
**A ring beside "Loading" for a two-second action with no known shape.**
**A ring where a list is loading.** The list has an outline, so it wants a skeleton.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA in a source pass over the component and its
examples and a rendered pass covering axe, target size, focus visibility and
reflow at 320px wide. The audit is author run, not an independent review, and
clinical review is still pending.
The source pass found nothing that needed changing. The root already carries
a required `aria-label` plus a visually hidden text twin, the SVG ring is
`aria-hidden` so the decorative motion stays out of the accessibility tree,
sizing is em based throughout with no `px` type step, and the ring draws only
in `currentColor` with no status colour or category colour of its own. The
rendered pass came back clean: no axe violation, no target size finding and
no horizontal scroll at 320px.
Two points stay open. The ring's contrast against either theme's surfaces
cannot be verified or hardened from source, because the ring takes whatever
ink colour the caller's context supplies rather than a colour the component
sets itself, so that gap belongs to the ContrastReport below rather than to
this file. And the development only missing label warning does not stop a
production caller from passing an empty or whitespace `label`, which matches
the same convention already used by `divider` and `segmented-control`.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
At most one `urgent` pill may be visible on a screen. If the product's rules produce
two, the screen needs an [AlertBanner](./alert-banner.mdx) for the most serious one.
See [Alarm fatigue](../health/alarm-fatigue.mdx).
## Anatomy [#anatomy]
**"Steady"** for a result that needs nothing right now.
**"Normal"**, **"Healthy"**, **"Good"**, **"All clear"** are claims about the person.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA in a source pass and a rendered pass. The audit is
author-run, it is not an independent review, and clinical review is still pending.
The rendered pass reported no axe violations, no target-size hits, no focus problems
and no reflow break at 320px, and found nothing to change.
**Checked by `pnpm run check:a11y` on every commit.**
* No file paints a status colour without reading `CLINICAL_STATUS_META` and a glyph,
and every status surface carries `data-status`.
* The four levels name four distinct glyphs: circle, ringed dot, diamond and octagon.
A11Y017 fails the build when two levels share one.
* The status words are read from `CLINICAL_STATUS_META[level].word`, never written as
a literal.
**Argued from the source.**
* Status is a visible word plus one of four distinct glyph shapes plus colour, never
colour alone. The icon is `aria-hidden` and sized in `em`, so the word carries the
meaning and the glyph grows with it.
* With `describes`, the pill announces as *Needs attention, Second example
measurement*. Omit it when the subject is visible text in the same reading unit.
When the pill floats free of its subject, in a table cell reached by column
navigation or a card corner, the consuming product must pass `describes`, because
the component cannot know the reading context. That is by design, and the prop
JSDoc records it.
* The pill is a `span`, not focusable and not in the tab order. A pill made into a
filter is a Button and owes a Button's target and name.
* No live region is mounted, on purpose. The pill is a static read-only label rather
than a message, so a `role="status"` announcement would be wrong here.
* At 200% text the pill grows and wraps; the word is never truncated and never
replaced by the icon alone.
**Not yet measured.** The rendered pass ran in the light theme and reported no
contrast violation, so light-mode text contrast passes. Dark-mode text contrast,
forced colours, and the non-text contrast of the boundary and glyph against the
surface were not measured. Those pairs arrive through role tokens
and live in the token layer and the report below, not in this source.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Your details" then "Your preferences" then "Review"** reads as one set.
**"Step 1: fill in everything about yourself" then "Prefs"** mixes lengths and grammars.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA, in a source pass and a rendered pass. The audit is
author-run, not independent, and clinical review is still pending.
**Fixed.** The root list had no accessible name. An optional `label` now
forwards to the root `` as `aria-label`, set on the default and both
examples; omitted, the attribute is dropped rather than shipping empty.
**Confirmed sound.**
* `` root and `` steps, so a screen reader announces a list of known
length, in order.
* The current step carries `aria-current="step"`.
* State never rests on colour alone: glyph, fill weight, border weight, label
weight, list position, and an sr-only "Completed", "Current step" or
"Upcoming" all carry it.
* The check glyph is `aria-hidden`; the indicator takes no tab stop, since it
has nothing to operate.
**Residual.**
* The upcoming marker's hairline border against the page is an unmeasured
contrast pair. Meaning does not rest on it: number, position, the sr-only
word and label weight already carry upcoming state.
* No live region announces a change of `current`. The parent flow owns focus
and announces each new page, so `aria-live` would fire on unrelated renders.
* A consumer who omits `label` ships an unnamed list. The default and both
examples set it, the recommended usage.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Everything the surface holds
```
## When to use it [#when-to-use-it]
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Larger text"** names the setting and stays true whichever way the switch is flipped.
**"I agree"** records consent, which belongs in a [ConsentSheet](./consent-sheet.mdx).
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA.** A source pass over the full rubric and a rendered
pass with axe, both author-run rather than an independent review, with clinical
review still pending. The audit found nothing to change in this component's source.
**What the audit confirmed.**
* `role="switch"` comes from Base UI's Switch.Root, the accessible name is a visible
label span tied by `aria-labelledby`, and state rides `aria-checked`.
* On and off are carried by thumb position and `aria-checked`, not the fill alone,
and a `border-border` hairline survives `forced-colors: active` and a stripped fill.
* The 24px AA target floor is met by the track, and the 44pt house floor by the
enclosing label row, which toggles the control.
* Focus sits on the track with the house ring, and both transitions collapse under
`prefers-reduced-motion: reduce` through the fast-duration token.
* `pnpm run check:a11y` runs on every commit: only neutral chrome and the bridged
primary fill, so no colour literal, no type size in `px`, and no banned word.
**Still unmeasured.** No contrast pair has been read yet, so the report below stands
in for numbers nobody has produced.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**An option names one thing the reader recognises and ticks**, under a group label that asks a question.
**An option that smuggles a severity or a conclusion into its label**, dressing an interpretation as a plain choice.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA, in a source pass and a rendered pass.** The audit
is author-run, not an independent review, and clinical review is pending.
**What the audit fixed.** With `searchable` on, typing filters the rows and can
empty the list, but that count change sat in no live region, so a screen reader
never heard the result count or that nothing matched (SC 4.1.3 Status Messages). A
persistent visually hidden `role="status"` region now announces the filtered count.
**What the audit confirmed.** Each option is a real checkbox with its icon
`aria-hidden`, the pressable row floors at `--opsin-target-minimum` in rem, and
the rendered pass, run with axe, target-size and 320px reflow, was clean.
`forced-colors` stays unchecked.
**One residual, deferred.** The group and filter names are forwarded only as
`aria-label`, with no persistent visible label. A required `label` prop keeps the
group from being nameless, but a visible label is a recommended enhancement, held
for one repair across the whole set.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Home", "Trends", "Learn", "Settings"** Four peer nouns, ordered from the default screen outward.
**"More"** as a fifth stop, hiding whatever the bar could not fit, including a safety action.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA in a source pass and a rendered pass.** The audit is
author-run, so it is not an independent review, and clinical review is still
pending. The rendered pass was clean, with no axe violation, target-size breach,
focus gap, or reflow break at 320px, and the source pass found every top risk
already handled, so the audit changed nothing here.
Confirmed: a real `nav` landmark named by `label`; the current destination marked
three non-colour ways, `aria-current="page"`, a heavier label, and a top
indicator, so no cue rides on colour; every target floored at the 44pt minimum in
rem; and icons `aria-hidden` with the label as the accessible name.
Recorded residuals: the colour and opacity fades carry no `prefers-reduced-motion`
guard, which still meets AA since that guard is an AAA item;
a `forced-colors` repaint may flatten the indicator bar, but `font-weight` and
`aria-current` keep the current state legible; and a bottom-fixed bar can obscure
focused content, but this component owns no position, so SC 2.4.11 is the
product's concern. Contrast for the current treatment on the overlay
material is still unmeasured; see below.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Weekly figures for the example account, in the example unit"** names rows and columns.
**"Table"**, or an empty caption, leaves numbers counting nothing.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA in a source pass and a rendered pass on
`/view/base/base-lyra/component/table`. The audit is author-run, not
independent, and clinical review is pending.
The audit found nothing to change in the source. The rendered pass is clean: no
axe violations, no target-size failures, no focus-visible gaps, no sideways page
scroll at 320px. A real `` always renders, headers carry `scope="col"`,
and the first body cell carries `scope="row"` when `rowHeader` is on. The
`overflow-x-auto` container is `tabIndex=0`, reachable and scrollable by
keyboard. Padding-based spacing and no fixed cell heights keep text-spacing
overrides from clipping. No colour prop, no `data-status`, no `data-category`,
no transition.
Two items remain open. An empty `caption` renders an empty ``, warning
only in development. The scroll container has no `role` and no accessible name;
adding `role="region"` would require one, left to the consuming page.
Contrast for the header ink, caption ink and hairlines has not been measured;
the report below stands in its place.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Overview" · "History" · "Notes"** name what each tab reveals, in one grammar.
**"Overview" · "Click for the full history"** mixes grammars, and one label instructs.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA, in a source pass and a rendered pass at `/view`.**
This is an author-run audit, not an independent review, and clinical review is
still pending.
The audit found nothing to change and applied no fix. Base UI's Tabs carries the
tested WAI-ARIA pattern and the wrapper overrides none of it. Activation is
manual, three sighted carriers plus `aria-selected` mark the active tab, and the
row draws neutral chrome with no status or category axis. The rendered pass was
clean: no axe violation, no target-size breach, no focus gap, no 320px reflow.
Two items to weigh. Each tab floors its height at `--opsin-target-minimum` with
padding but sets no `min-w`, the house treatment for a word-labelled target under
SC 2.5.8. The `label` prop applies only as the tablist's `aria-label`, right here
because every tab shows its own text.
Contrast pairs for the active ink, the rail and the indicator stay unmeasured.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
An
```
## When to use it [#when-to-use-it]
Review the glossary as clinical content, not as microcopy. A definition that slides into
guidance has nobody behind it, and nothing catches the drift.
## Anatomy [#anatomy]
**"eGFR (estimated glomerular filtration rate, an estimate of how well your kidneys
are filtering)."** Expansion, then plain definition.
**"eGFR (estimated glomerular filtration rate)."** Every word in the expansion needs
its own definition.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA in a source pass and a rendered pass. The audit is
author-run, not independent, and clinical review is still pending.
**Fixed by the audit.** The disclosure trigger's focus ring hardcoded a 2px width and
offset, ignoring the `--opsin-border-focus` and `--opsin-border-focus-offset` tokens. It
now honours them, so the indicator grows with a reader's focus width.
**Verified in source.** `present` has no `hover` value, so the definition never depends on
hover. Collapsed, it is `display: none` yet still reaches the reader as the trigger's
description. The disclosure is a real button named by its visible word, meeting SC 2.5.3
Label in Name. The mark changes form, not colour: dotted at rest, solid while open.
**Residual, and stated plainly.** The inline trigger falls under the 44 by 44 floor and
relies on the SC 2.5.8 inline exception, and adjacent wrapped triggers can overlap. `aria-controls` deliberately points at the closed `display:
none` panel. No assistive technology has been tested against it, so the lived experience
is unverified.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
` pointed at its `id`.
**Label "Anything you want to add?", placeholder "A sentence or two is plenty."**
**No label, the question in the placeholder.** It vanishes on the first keystroke.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA in a source pass and a rendered pass.** The audit is
author-run and is not an independent review, and clinical review is still pending. The
rendered pass on the component view was clean: no axe violations, no target-size hit, no
focus-visible failure, and no reflow at 320px. The source pass confirmed the same, so the
audit found nothing to change and no fix was applied.
The box draws only neutral chrome roles, so no status colour, colour literal or ramp step
reaches it, and the type is the `body` step rather than a pixel size.
* The box needs an accessible name and invents none. A Field label, an `aria-label`, or
an `id` with a real `` gives it one, and the default export models the
visible-label path.
* With none of `aria-label`, `id` or `name` present, a development warning names the gap
rather than shipping an unnamed box.
* `invalid` sets `aria-invalid` and leaves the border neutral, because a form error is
not a clinical status. The message is [Field](./field.mdx)'s to place, so standalone
the box cannot associate an external message id.
* The focus ring rides in the box's own classes, so a project without the product
stylesheet keeps it. Height floors at the house target.
Known residual items a reader should weigh. The box accepts an `aria-label` on its own,
and a persistent visible label is the recommended enhancement rather than a requirement,
which is why the default export uses one. `maxLength` is forwarded but the box renders no
visible counter and no live remaining-count region, so pair the limit with a visible count
near the box as the Content guidelines say. Disabled state uses a muted fill rather than an
opacity wash so the text stays legible, and WCAG exempts disabled controls from the contrast
floor.
**Not checked by any gate.** Every contrast pair, and what the box draws under
`forced-colors: active` and `prefers-contrast: more`, including the browser's own
resize handle.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Issued by the example clinic.
```
## When to use it [#when-to-use-it]
**"Repeat prescription issued"** with the recorded time beneath it and the status on a pill.
**The whole entry tinted amber** to flag the event. A status carried by colour alone dies in greyscale.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA in a source pass and a rendered pass.** The
rendered pass (axe, target size, focus visible, reflow at 320px) and the source
pass against the rubric were both clean. This audit is author run, not an
independent review.
* The rail and the marker carry `aria-hidden`, so a screen reader meets the
time, the title, any status word and the body in reading order.
* The recorded time is the system RelativeTime, a semantic `time` element, so
the exact instant stays in the accessibility tree when only the phrase shows.
* Nothing in the entry is focusable, so keyboard, focus and target size do not
apply.
**Read this before you rely on it.**
* The marker and the connector are decorative chrome under `aria-hidden`, so
they are exempt from Non-text Contrast (1.4.11). They use role tokens anyway.
* The root renders a bare `li`, so the product must supply the `ol` or `ul`
around it for list semantics to hold. On Safari with VoiceOver a
`list-style: none` list can drop its list role, a platform quirk shared by
every list based component here rather than a fault in this one.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
manager.add({ title: "Saved" })}>Save note
)
}
function Screen() {
return (
)
}
```
## When to use it [#when-to-use-it]
**"Saved" with an optional "Undo".** The action still happened if the reader looks away.
**A toast carrying a number, a result or an urgency.** Whoever needs it most misses it.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA in a source pass and a rendered pass that together raised no axe violation, no target-size hit and no 320px reflow failure. This is an author-run audit, not an independent review; clinical review is pending.
**The audit found nothing in the source to change.** Roles, names, the polite live region, pause on hover and focus, Escape and focus return all come correctly from `@base-ui/react`. The X icon is `aria-hidden` and the close carries a translatable `aria-label`. Colours are role tokens, type sizes are `text-opsin-*` tokens, and the controls floor their hit area at `--opsin-target-minimum`.
**Residual items to know.** A toast pushed with a description and no title yields a dialog with no accessible name, because `ToastList` rightly emits no empty title; the default and both examples always pass a title, and a description-only toast is still announced by the live region through `aria-describedby`. Whether an appearing toast overlaps a control focused elsewhere is a product-layout question outside component scope. Contrast pairs are unmeasured, so the report below carries what was measured.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Overnight average
```
## When to use it [#when-to-use-it]
**"Reminders wait until the morning during the hours you set here"** beside a
labelled setting.
**The only label on an icon-only control, shown on hover alone.** A touch
reader sees a bare glyph.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA: a source pass over the whole rubric, and a rendered
pass over the measured findings. Author-run, not independent; clinical review
is still pending. The rendered pass found no axe violation, no target-size
breach, no focus-visible gap and no clipping at 320px. The source pass found
nothing to change in `tooltip.tsx`.
What holds:
* Base UI wires the popup through `aria-describedby`, so the label is a
description, never a replacement for the control's own name.
* Focus opens the tooltip, Escape dismisses it without moving focus, and the
label follows focus off the trigger.
* No status colour, no colour literal, no ramp step: `footnote` step, no `px`
size, neither colour axis.
Open:
* A tooltip is unreachable on a hover-less touch device, so `content` stays
supplementary.
* The popup's non-text contrast (SC 1.4.11) is the shared `border-border` role
token, reasoned rather than measured.
* The popup staying hoverable across the gap (SC 1.4.13) is a Base UI 1.7.0
default, not a manual trace.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
**"Down, from 20 steps to 16 steps, over the last 14 days."** Checkable against
the picture.
**"Trending in the right direction."** Valence with no author, magnitude or
window.
## Accessibility [#accessibility]
Audited against WCAG 2.2 AA in a source pass and a rendered pass. The audit is
author-run, not an independent review, and clinical review is still pending.
**What the audit found.** Nothing to change. The rendered pass was clean, with no serious
axe, target-size or focus breach at 320px, and the source pass
confirmed every check: the two colour axes stay apart, and status is carried by the
caption [StatusPill](./status-pill.mdx), never by colour alone. The committed
`check:a11y` gate reruns the literal, bound, colour and axis rules.
**Residual and deferred.**
* No per-point data table twin. The text alternative is the `role="img"` name plus the
visible caption. A full table is an enhancement, not an AA requirement.
* `className` merges onto the whole subtree, so an `sr-only` variant can hide the
caption, the only text carrier. A documented API risk; keep it visible.
* Under forced colours the line drops its category tint to `CanvasText`. Category is
identity only, so nothing else is lost, and this is intentional.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
`mmol/L` to `mg/dL` is refused, because the factor is a property of the analyte
rather than of either unit. `convertUnit` returns nothing rather than a
substituted default. See [Unit systems](../health/unit-systems.mdx).
## Anatomy [#anatomy]
**"1000.2 kg"** for a device that measures to 100 g. One decimal place,
spoken as *1000.2 kilograms*.
**"1000.2481 kg"** because that is what the device sent. Four decimal places
assert a precision the instrument lacks.
## Accessibility [#accessibility]
**Audited against WCAG 2.2 AA** in a source pass and a rendered pass on
`/view/base/base-lyra/component/value`. The audit is author-run, not an
independent review, and clinical review is still pending.
It changed nothing in source. The unit symbol is `aria-hidden` only when a
spoken form exists and the words follow it, so an English reader hears *1000.2
kilograms* as one phrase. Absence is spoken in words, never drawn at hero
weight, and carries no decorative glyph. The component imposes no truncation, no
fixed height and no `whitespace-nowrap`. The rendered pass returned empty axe,
target-size, focus-visible and 320px reflow results.
Three items sit outside this source. A Value must never be the sole accessible
name of a tappable control, because the visible symbol and the spoken words
share no substring, so the control owes its own name carrying the symbol (WCAG
2.2 SC 2.5.3). The only path to a clipped reading is a caller passing a
truncating class through `className`, which `twMerge` lets win, so truncation is
a caller responsibility documented on `ValueProps.className`. The spoken span
uses `select-none` to keep the words off the clipboard while leaving them in the
accessibility tree, untested by a copy test.
Audited against WCAG 2.2 AA. Clinical review pending.
## Preview [#preview]
Close the panel
```
## When to use it [#when-to-use-it]
**"Close the reminders panel"** names the action a sighted reader takes from the cross.
**An empty VisuallyHidden** names nothing, and the markup now looks labelled when it is not.
## Accessibility [#accessibility]
**Checked by `pnpm run check:a11y` on every commit.** The component sets no
colour and no type size, so the gate's token and unit rules pass trivially.
**Audited against WCAG 2.2 AA in a source pass and a rendered pass.** The
audit is author run, not an independent review, and clinical review is still
pending. The source pass covered the clip technique, the accessibility tree
and the two shipped examples; the rendered pass ran axe against the live
preview and checked target size, focus visibility and reflow at 320px, and
found nothing to flag.
* Content is announced because the span is clipped, not `display:none`,
`visibility:hidden` or the `hidden` attribute, each of which removes content
from the tree. The clip pattern was checked against the WebAIM sr-only
reference and stays hidden through 200% text and increased text spacing,
because neither touches the clip's own overflow and clip-path.
* It is text rather than a control, so it is never focusable and never a tab
stop.
* The audit fixed one gap the component's own open question named: nothing
previously warned when a focusable control was placed inside the always
hidden clip, a keyboard trap with no visible focus ring. The component now
walks its children in development and warns when it finds a focusable
descendant, the same pattern it already used for empty children. The
warning is development only, so it changes no markup, class or visual
output.
* The component paints nothing, so no colour or type size applies and there is
nothing to reflow at 200% text.
**Not checked by any gate.** Whether a screen reader announces the content
across VoiceOver, NVDA, JAWS and TalkBack. Whether hidden text duplicates a
visible name beside it is a per-usage question the component cannot see from
its own source, so it stays a concern for the caller rather than something
this audit could check.
` sits above `## Preview`,
first after the definition, and carries at most three open safety questions, one sentence
each. SAFE001 requires its sentences in authored MDX, never a generated string: audited
against WCAG 2.2 AA by the authors and not independently reviewed, clinical review still
pending, and not for a production health surface until a clinician signs it. See
[ADR 0025](../project/decisions/0025-the-audit-is-author-run.mdx) for the record.
C6001 fails the build when the notice is missing or sits below a heading. The H1 and the
definition come from `title` and `description`, never from MDX.
### The fourteen sections [#the-fourteen-sections]
`SHIPPED_SECTIONS` in `lib/status.ts` fixes the numbering, which is the order a page must
present. Five are optional: Anatomy, States, Content guidelines, Data attributes and CSS
variables. Each earns its place by the test in its row and keeps this position when it
appears. Omitting one is not a defect; inventing content to fill it is.
| # | Section | Written or generated | Required | What it is for |
| -- | ------------------ | -------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Preview | generated | always | `` and nothing else |
| 2 | Installation | generated | always | `` alone. Its manual tab hosts ``, the only place source appears |
| 3 | Usage | written | always | The import line and the minimal JSX. Two code blocks, zero prose |
| 4 | When to use it | written | always | `` alone: at most four cases for, five against, one line each. Every *against* names the component to use instead |
| 5 | Clinical meaning | written | health categories only | What it asserts, what it must never be read as, which colour axis reaches which element, who owns the thresholds, one or two sentences each. Required when `category` starts with `health-`, forbidden otherwise |
| 6 | Anatomy | written | optional | `` where the component has two or more parts, one line each. `` only where the tree nests below the root's children |
| 7 | Examples | written + generated | always | One H3 per example: a sentence or two on what it shows and which prop drives it, then the preview |
| 8 | States | written | optional | The five data states as a table, on a component that displays a reading. Left out where most rows would say not applicable |
| 9 | Content guidelines | written | optional | One `` pair, on a component that renders copy the product writes |
| 10 | Accessibility | written + generated | always | What a gate checks, what is argued from the source, what nothing checks, labelled apart. Then the keyboard table and the contrast report. Never delegated upstream |
| 11 | Data attributes | written | optional | The styling contract, where the component stamps more than `data-slot` |
| 12 | CSS variables | generated | optional | Where the component declares a custom property of its own |
| 13 | API reference | generated | always | `` from a named exported interface, plus a few sentences at most for a default or refusal the table cannot carry |
| 14 | Related | written | always | Two to five one-line bullets naming what the component is confused with, each pointing at the alternative |
A `planned` page is eight sections: Preview, Installation, When to use it, Clinical
meaning (health categories only), Anatomy (optional), Proposed API, Accessibility and
Related. `## Proposed API` replaces `## API reference`, written as a specification and
marked do-not-generate-against, and the two never both appear.
The page header is specified to carry more than it renders. The status badge, the
category, the base and style switcher and Copy Page are all specified in this
handbook's history and are rendered by nothing: `PageActions` exists in
`components/mdx.tsx` and has zero invocations in the corpus, and `PageTemplate`
emits a machine-readable contract script and its children and nothing visible. A
footer carrying a changelog link, an edit link and `
### Why the order [#why-the-order]
Installation is section 2 so a developer who came for the install command finds it at
once, with only the notice above it. **When to use it** is section 4 because the
expensive mistake is reaching for [AlertBanner](./alert-banner.mdx) when the situation
calls for [Callout](./callout.mdx), so every entry on the *against* side names an
alternative.
### What is generated [#what-is-generated]
Prop tables, CSS-variable tables, contrast reports and example source come from
`scripts/*.mts`. A page carries **names**, not code and not measured numbers, and CI fails
on a regeneration diff.
## Do this [#do-this]
* **Fill in the template**, or copy [Button](./button.mdx) and replace every fact.
* **Write the definition for the patient, not the engineer.** That one-sentence
`description` ends up in search results, in `llms.txt` and under the H1.
* **Name an alternative in every prohibition.** An `avoid` entry takes an `instead`, and
the value is a checked catalogue id.
* **Declare `governedBy` on every `health-*` component**, and have the doctrine page list
it back. `assert-ia` checks both directions.
* **Take aliases from the catalogue.** `registry/catalogue.ts` owns the alias namespace.
* **Say what the component refuses, in one line.** What it renders when the range is
unknown, what it will not derive, what it must never be read as.
* **Link doctrine rather than restating it.** One sentence and a link to
[Two colour axes](../health/two-colour-axes.mdx) beats a paraphrase that drifts.
* **Write a Related bullet as a sentence**, subject first, verb from the closed table in
[Documentation templates](../handbook/contributing/documentation-templates.mdx):
`- [Link](./link.mdx) is for navigation.`
## Not this [#not-this]
* **Do not write an essay under a heading.** A section is a component call or a short
paragraph. Doctrine goes on the page that owns it, reasoning in the commit message.
* **Do not leave a heading empty**, and do not write *TODO: fill this in*. Omit the
section, or use `` when the gap is real and must be tracked.
* **Do not paste code into MDX.** `` and `` resolve a
name against the registry and render the real thing.
* **Do not state a measured number you did not generate.** No contrast ratios, no
invented percentages. `` is the honest rendering of a table with no source.
* **Do not invent a citation.** Not a study, not a statistic, not a DOI, not a date. See
[Evidence and references](../health/evidence-and-references.mdx).
* **Do not add a section this contract does not have.** A page that genuinely needs one
changes `lib/status.ts` and the template together.
* **Do not give a non-health component a clinical meaning.** [Card](./card.mdx) is a box,
and a verdict hidden inside a box escapes review.
* **Do not grow the notice.** Three open questions, one sentence each. The rest stay in git
history, still open.
## Gotchas [#gotchas]
**Links are relative.** Write `[Two colour axes](../health/two-colour-axes.mdx)`. fumadocs
resolves it through `createRelativeLink`. An absolute site link is banned with no
exception.
**The MDX vocabulary is closed.** Only the tags in this contract exist. Content authors
never define one; an unknown JSX tag fails the build.
**Component ids are kebab-case in every path, frontmatter field and prop; PascalCase only
in prose.** `range-bar` in `usedIn`, `RangeBar` in a sentence.
**British spelling in prose, American in code.** `colour` and `behaviour` in what a reader
reads; `color`, `ColorScale` and `--color-*` in code.
**`aliases` are globally unique**, not unique per page. If two pages claim `gauge`, the
build fails on the second page rather than the wrong one.
**The word budget counts everything in the body.** JSX props, keyboard rows and code
blocks count too. A page over budget has a section arguing rather than stating.
**A `planned` page is a specification, not a placeholder.** If you cannot say what the
component asserts, what it refuses, how it composes and what it must never be read as, it
is not ready for a page.
## Related [#related]
* [Components overview](./index.mdx) has the full roster.
* [Button](./button.mdx) is the exemplar every page follows.
* [RangeBar](./range-bar.mdx) has the fullest clinical contract, and the best section 5.
* [ADR 0024](../project/decisions/0024-the-component-page-is-lean.mdx) explains what was
cut and why.
* [Documentation templates](../handbook/contributing/documentation-templates.mdx) covers
every page skeleton.
* [Component checklist](../handbook/contributing/component-checklist.mdx) is the definition
of done.
* [Proposing a component](../handbook/contributing/proposing-a-component.mdx) shows how a
new id reaches the catalogue.
* [Release phases](../project/release-phases.mdx) says what `planned`, `shipped` and
`deprecated` each promise.
---
# Screens
Source: https://opsinjs.pensievelabs.org/screens
Markdown: https://opsinjs.pensievelabs.org/screens.md
Section: Screens · kind: guide
Two of the six are now built. The results screen renders its real composition in
the preview frame, assembled from parts that already ship, so the three screen-level
checks below have something rendered to run against. The medicines app goes further
and renders a whole application out of thirty-five of them, with four destinations,
five overlays and a working form. The other four are still specifications: each
carries the composition it is intended to have, the ways it could mislead, and the
accessibility contract it must meet, so that it can be reviewed and argued with now,
and its preview frame falls back to the not-implemented notice until the registry
has something to put in it.
## What a screen page contains [#what-a-screen-page-contains]
The same six sections, in the same order.
| Section | What it is for |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| What this screen does | The reader's situation on arrival, what they are trying to find out, and an explicit statement of what the screen deliberately does not do. |
| Composition | The part hierarchy, and the material rung each surface sits on. |
| Preview | The screen rendered in isolation under the product theme, at device widths. |
| Safety notes | Where this specific screen could mislead, and what it does instead of guessing. |
| Accessibility | Heading structure, landmarks, focus on entry, reading order against visual order. |
| Status | What is decided, what is open, and the questions the implementation has to answer. |
Two conventions worth knowing:
**Previews render under the product theme, not the docs chrome.** A screen is
embedded from an isolated `(view)` route with its own document and its own token
scope, so what you see is the opsinjs product surface rather than this site's
deliberately dense square chrome. That surface has squircle corners, system-ui
and generous spacing. The reasoning is in
[Lyra and the docs chrome](../theming/lyra-and-the-docs-chrome.mdx).
**Material rungs are referred to by position, never by name.** The rungs are named
once, in [The ladder](../foundations/materials/the-ladder.mdx). These pages say
"one rung above the page" so that they cannot drift from that page as the names
settle.
## The screens [#the-screens]
* **[Results screen](./results-screen.mdx)** covers one result, what it means,
and what happens next. The highest-stakes screen in the set, and the one where
the reading order matters most.
* **[Daily log screen](./daily-log-screen.mdx)** is the surface somebody returns
to every day, judged on how little it costs rather than how much it shows.
* **[Trends screen](./trends-screen.mdx)** covers change over time across
several metrics, with the axis rules and the data-table twins.
* **[Consent flow](./consent-flow.mdx)** is a sequence rather than a screen, and
the one place where the design's honesty is directly testable.
* **[Onboarding screen](./onboarding-screen.mdx)** is the first run. The minimum
is collected before something useful is visible.
* **[Diabetes medicines app](./diabetes-medicines-app.mdx)** is the whole
application: four destinations, thirty-five components, and a set of refusals
that keep a medicines record on the safe side of the line between a diary and a
regulated device.
## Recipes and patterns first [#recipes-and-patterns-first]
If you are building rather than reviewing, a screen page is usually the wrong
place to start. It is a specimen of the finished thing, not a build order.
* **[Recipes](../recipes/index.mdx)** build one piece of a screen, with the steps.
* **[Patterns](../patterns/index.mdx)** describe the flow a screen sits in.
* Screens show the assembly, and are what you check your assembly against.
## Verify it worked [#verify-it-worked]
Hold your screen against these three, in this order. They are the checks that a
per-component review passes and a screen fails.
1. **Read the screen from top to bottom with the styling off.** The order you get
is the order a screen-reader user gets. If the number the person came for is
fourth, the screen is wrong however it looks.
2. **Count the coloured elements and name the axis of each.** Category colours
identify; status colours grade. If any one element is doing both, or if you
cannot say which it is doing, fix it before anything else.
3. **Count the surfaces at *attention* and *urgent*.** The budget is one urgent
surface per screen. See [Alarm fatigue](../health/alarm-fatigue.mdx). Two means
one of them is going to be ignored, and you do not get to choose which.
## Troubleshooting [#troubleshooting]
**"The preview is empty."** Expected on the four screens that are still
specifications. Their frame renders the not-implemented notice, naming the screen
and its status, and the composition and the contract on the page are the reviewable
artefact for now. The results screen and the medicines app are the exceptions:
both frames render the real assembly.
**"My screen has parts no specimen covers."** Likely. These six are specimens,
not a catalogue. Compose from [Recipes](../recipes/index.mdx) and check the result
against the three questions above.
**"The screen I need is not here."**
There is still no multi-metric **dashboard** specimen. The medicines app is a
today surface for one domain and it carries neither colour axis, so it answers
the composition half of the question and not the hard half: a home screen showing
readings from several categories, where the alarm budget and the two axes have to
hold at once. That remains the largest gap in this set.
There is no **result disclosure** specimen: the moment between a notification and
an out-of-range result. The flow is described in
[Result disclosure](../patterns/result-disclosure.mdx) but no screen shows it.
**"Two screens disagree about a rule."** The doctrine page wins. Screens are
downstream of [Health](../health/index.mdx) and
[Foundations](../foundations/index.mdx), and a screen that contradicts either is
the thing that is wrong.
## Next [#next]
* **[Results screen](./results-screen.mdx)** is where to start. It is the
specimen with the most decided.
* **[Safety review checklist](../health/safety-review-checklist.mdx)** is the
pre-ship pass for any screen showing a health value.
* **[Layout](../foundations/layout.mdx)** covers page shells, safe areas and the
two canonical health screen layouts these specimens are built on.
---
# Consent flow
Source: https://opsinjs.pensievelabs.org/screens/consent-flow
Markdown: https://opsinjs.pensievelabs.org/screens/consent-flow.md
Section: Screens · kind: screen · evidence: opinion
> NOT IMPLEMENTED. "Consent flow" 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.
This specimen describes an interface. It does not establish a lawful basis for
processing and it is not legal advice; what you must ask, record and retain is a
question for your data protection lead. See
[Safety, scope and limitations](../start/safety-scope-and-limitations.mdx).
## Composition [#composition]
Escape all mean *no answer given*, and the flow may be
re-entered without penalty.
* **The grant is recorded against the wording version**, so that the question "what
exactly did this person agree to" has an answer later.
* **Re-ask on a change of scope or wording, never on a timer.** A periodic re-ask
trains people to tap through, which destroys the meaning of the answer.
* **Revocation lives in one predictable place** for every scope, takes effect
immediately, and says what happens to data already collected. See
[Consent and disclosure](../health/consent-and-disclosure.mdx).
* **Consent to a feature is not consent to research, marketing, or sharing with an
employer or insurer.** Each is a separate ask, in its own words.
* **Consent given by a carer, or for a child, is a different flow** with different
obligations. If the product does not support it, say so rather than letting the
adult flow be used on somebody else's behalf.
* **No clinical status colour appears anywhere in this flow.** Consent is not a
clinical state. [The two colour axes](../health/two-colour-axes.mdx) explains
the separation.
## Accessibility [#accessibility]
**Landmarks and headings.** Each step has one H1 stating what is being asked.
Each scope is asked on its own sheet rather than as an item in a list, and its
description is programmatically associated with the answers it governs.
**Reading order is the contract.** Purpose, scope, handling, boundary, then the two
answers. This screen fails more often on order than on anything else: an Allow
button that appears early in the DOM for visual reasons puts the answer before the
question for anyone not reading visually.
**Focus.** Focus enters the sheet on open and lands on the heading, not on Allow.
Focus is trapped while the sheet is modal, Escape dismisses it, and
focus returns to the control that opened it.
[Keyboard and focus](../accessibility/keyboard-and-focus.mdx) specifies that
behaviour.
**Equal weight is verifiable.** Render the sheet in greyscale: if one answer still
dominates, the dominance was built from colour and the screen is a funnel.
[Colour independence](../accessibility/colour-independence.mdx) is the rule it
breaks.
**Targets.** Both answers clear 44pt with real separation between them, so that the
wrong one is not tapped by accident. See
[Target size and motor accessibility](../accessibility/target-size-and-motor.mdx).
**Text at 200%.** Both answers remain visible together. A reflow that puts Allow on
screen and Decline below the fold creates a dark pattern out of a layout bug, so
this is a test case rather than a nicety.
[Text resizing and zoom](../accessibility/text-resizing-and-zoom.mdx) has the
reflow case.
**Reading level.** Consent copy fails more readers than any other copy in a health
product. Check it against the target in
[Health literacy](../content/health-literacy.mdx), and expand clinical words
inline with [Term](../components/term.mdx) rather than in a footnote.
**No timers.** Nothing in the flow expires, auto-advances or auto-dismisses. A
sheet that closes itself has taken the decision.
[Cognitive accessibility](../accessibility/cognitive-accessibility.mdx) is where
that rule lives.
## Status [#status]
Escape dismisses it; and focus returns to the control that
opened it, not to the top of the page.
[Keyboard and focus](../accessibility/keyboard-and-focus.mdx) specifies this.
**The keyboard never covers the save.** The sheet respects the keyboard-safe inset
at every detent and at every text size. This is the failure that makes a logging
flow unusable one-handed while looking fine in a screenshot.
**Announcements are proportionate.** The save is announced politely and does not
interrupt. Undo remains reachable by keyboard for as long as it is offered. An
undo only a pointer can reach is not an undo.
**Validation is heard, not only seen.** Messages are associated with their field
and announced when they appear. See
[Screen readers](../accessibility/screen-readers.mdx).
**Targets.** Every control clears 44pt with real separation, and the primary
action sits in the one-handed reach zone.
[Density and touch](../foundations/space/density-and-touch.mdx) defines that
zone.
**Text at 200%.** The sheet scrolls internally, the save control stays visible, and
the history list reflows to stacked rows rather than truncating values.
**Input survives.** Rotation, backgrounding and dismissing the keyboard do not
discard a half-typed reading. Losing typed input is the fastest way to end a
logging habit.
## Status [#status]
Those refusals are not politeness. The MHRA's guidance on stand-alone software
names an app that works out an insulin dose from the carbohydrate in a meal as
a worked example of a medical device, and names a reminder, a diary that
replaces a written one, and referral to a clinician as the things that keep
software outside the definition. The same guidance states that a general
disclaimer does not exempt an app that qualifies as a device. So the refusals
are in the code, and the copy only reports them. Read the guidance in its
current published form with your own regulatory advisers; this page is design
rationale, not a compliance assessment. [Regulatory
context](../health/regulatory-context.mdx) is the map.
**Who this specimen is for.** A team building a medicines surface, who need to see
what the boundary looks like when it is drawn in components rather than in prose.
And a reviewer, who can hold the rendered app against the three screen-level checks
in [Screens](./index.mdx) without taking anything on faith.
## Composition [#composition]
The whole app, rendered under the opsinjs product theme. The four destinations
at the foot are live, the log sheet saves, and the undo beside a saved record
puts it back. Every medicine, dose, time and count in it is invented.
Open the frame at tablet and desktop width and the app stays one column, because
the reading order is the same order at every width and a second column would put
the thing somebody came for beside something they did not. Switch the frame to
dark and every state survives, because no state here is carried by a colour.
**Everything in it is synthetic (ADR 0012).** The medicines are called "Morning
tablet" and "Bedtime pen", never a real drug and never a real strength. The
instants are fixed, so the app says the same thing every time it is built. A
screenshot of this page must never be mistakable for somebody's own medicines
record, which is why the demonstration marker sits on the surface rather than in
an about screen nobody opens.
## Safety notes [#safety-notes]
**It carries neither colour axis, and that is the finding.** No surface in the app
takes `data-status` or `data-category`, and none is tinted from either ramp. A
medicines record states no clinical level and names no category, so painting one
would be a verdict the product has no right to. A dose with nothing recorded
against it is never painted the red that means "act now", because whether it
matters is a clinical judgement this product does not own, and a red that means
"you have not logged this" cannot share a screen with a red that means "contact
your care team". [The two colour axes](../health/two-colour-axes.mdx) is the rule;
this screen is what obeying it all the way looks like.
**The app never marks a dose as missed.** It cannot know. The `missed` state
reaches DoseTracker only where the person themselves pressed a control that says
"I did not take it", and a dose nobody has answered for stays at `scheduled`
however long ago it was due. No clock moves it. This is the one place a medicines
app is most likely to assert something it has not got, and it is the reason
DoseTracker's own specification insists it reaches no verdict about any entry it
draws.
**A dose that was not taken routes to a person, and stops.** The app does not say
"do not double up", it does not say "take it as soon as you remember", and it does
not say anything conditioned on which medicine it was or how late it is. The
answer genuinely differs by medicine and by person, and a generic answer attached
to a specific medicine is treatment advice however it is worded. What the screen
does is name who can answer: the pharmacist, the prescriber, and the leaflet in the
box.
**No number in the app belongs to opsinjs, and none belongs to the product
either.** The doses are strings the person transcribed from their own label, shown
back unchanged rather than parsed into a quantity, because a dose is a written
instruction and not a measurement. The count at which a reorder reminder appears is
a number the person set. The emergency routing is the product's own copy, carried
here precisely because opsinjs ships no emergency number, in the same breath as it
ships no reference range: it does not know where the reader is.
**The emergency routing is never triggered.** It sits in the disclaimer at the foot
of every destination and it fires on nothing. A modal that opens because a value
crossed a line is the product making a triage judgement, and
[Emergency and escalation](../health/emergency-and-escalation.mdx) is where that
path is specified for a product that owns one.
**A dose is written back, never parsed.** The add flow offers names and forms and
nothing else. There is no strength picker, no prefilled dose and no dose-shaped
placeholder, because a list of strengths to choose from is a list of doses and a
default is a recommendation. The word "units" is written out in full everywhere it
appears, never shortened to a single letter after a number.
**Cited.** Huckvale K, Adomaviciute S, Prieto JT, Leow MKS, Car J. Smartphone
apps for calculating insulin dose: a systematic assessment. *BMC Medicine*
2015;13:106. Of 46 insulin dose calculator apps assessed, 91 per cent lacked
numeric input validation and 67 per cent carried a risk of an inappropriate
output dose, while 59 per cent carried a clinical disclaimer. The disclaimer was
shipped by more apps than input validation was. That is the evidence behind this
screen treating a disclaimer as a required disclosure and never as a mitigation.
**Cited.** The FDA's Class I recall of the Insulet Omnipod 5 Android App,
initiated 7 November 2023, records that a bolus entered without a leading zero
could be read as ten to one hundred times the intended amount, because the
calculator did not register a decimal point entered as the first character. A
regulated device from a major manufacturer, and the near-fatal defect was a text
field. It is the reason this screen ships no numeric dose field at all.
**Opinion.** That a medicines record belongs on neither colour axis is ours, and
it is the single decision on this page most worth arguing with. If it is right,
the design system has a gap where a non-clinical state vocabulary should be. If
it is wrong, this screen is under-describing something a reader needs.
**Opinion.** That a count is safe and a grade is not. "You recorded 18 of 22" is
a fact about a log; a percentage under a label is an interpretation of a person.
The line between them has not been tested with readers.
What would change our mind: a clinical safety officer's review of this screen
against a real hazard log, and a usability study with the audience it is drawn
for, would revise both opinions and the strength they are stated at.
## Accessibility [#accessibility]
**Landmarks and headings.** One `header`, one `main`, one `footer` and the `nav`
that TabBar supplies. One H1 names the application, one H2 names the destination
showing, and H3s name the groups inside it. The heading outline read on its own is
a usable summary of whichever destination is open.
**Focus follows the destination.** The bar swaps the whole of `main`, so `main`
carries `tabIndex={-1}` and takes focus when a destination changes. Without that, a
screen-reader user and a keyboard user are left at the foot of a page that is no
longer the page they were on. The focus ring is never suppressed, and the sticky
bar is the one thing on the screen that can cover a focused control at the end of a
long list. [Keyboard and focus](../accessibility/keyboard-and-focus.mdx) sets the
rule.
**The confirmation is announced, and it does not leave.** A saved record puts a
persistent panel on the surface carrying what was recorded and the undo beside it,
in a `role="status"` region. There is no toast anywhere in this app, and that is
deliberate: a message that dismisses itself after a few seconds is unreadable at
the reading speed this audience reads at, and it takes the undo with it when it
goes. [Timing adjustable](../accessibility/cognitive-accessibility.mdx) is the
constraint; nothing here expires, and no dose changes state while somebody is
reading it.
**Colour independence.** Nothing on the screen is told by colour. Every dose state
carries a word and a distinct lucide silhouette, every control carries its label,
and the whole app reads the same in greyscale and under all three simulated
colour-vision deficiencies. [Colour independence](../accessibility/colour-independence.mdx)
is the rule, and this screen is the easy case for it because neither clinical
palette is in use.
**Targets and text.** Every control floors at the published target size in rem, so
it grows with the reader's own text size rather than staying put. Type comes from
the opsinjs steps and never from a pixel value, so a reader at 200 per cent gets a
larger reading of their own medicines. Nothing in the content truncates: a medicine
name wraps, and the dose beside it wraps with it.
[Target size and motor](../accessibility/target-size-and-motor.mdx) and
[Text resizing and zoom](../accessibility/text-resizing-and-zoom.mdx) set both
floors.
**One thing does not reflow, and it is measured rather than argued.** At 200 per
cent text in a 390 pixel frame the document scrolls sideways by 115 pixels, and
every element past the edge belongs to the tab bar. Four destinations, each floored
at the target size in rem and each carrying a word, come to more than the width
they have. Nothing the app owns overflows at that setting, and the app cannot
repair the bar from outside it. The question is recorded below rather than worked
around, because a workaround here would hide a defect in a component other products
will meet.
**Two controls ship no visible label, so the product draws one.** Select and
NumberField apply their `label` as an accessible name and expose no id, so the app
renders the same words above each one as a plain span. A `label` element with
nothing to point at is markup that looks associated and is not, which is why it is
a span, and the visible words match the accessible name so voice control reaches
the control by what a person can see.
**Reading order matches visual order** on every destination: what needs an answer
first, then what was recorded, then what is still to come, then the way to add
something, then where it all came from, then the boundary. The boundary sits in the
same place on all four, so it is findable rather than merely present.
## Status [#status]
Everything on this page renders. The app is assembled entirely from parts that
already ship, it holds its own state, and the controls work. What is unproven
is the composition rather than the components: the four destinations, the
refusals written into them and the accessibility contract above are a
proposal, they have had no clinical safety review, no hazard log, no clinical
safety case and no data protection impact assessment, and none of those is
claimed. Every opsinjs component has now been audited against WCAG 2.2 AA by
its authors, in a static source pass and a rendered pass, but that audit is
author-run rather than an independent accessibility review, and no component
has had a clinical review either
([ADR 0025](../project/decisions/0025-the-audit-is-author-run.mdx)). Do not
ship this app to readers. Do generate product code against its
refusals, because those are the part worth copying.
---
# Onboarding screen
Source: https://opsinjs.pensievelabs.org/screens/onboarding-screen
Markdown: https://opsinjs.pensievelabs.org/screens/onboarding-screen.md
Section: Screens · kind: screen · evidence: opinion
> 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.
This composition names
`source-citation`
, which has no component on the
roster yet. Until it lands, a team building the provenance section writes the
source and the instrument as plain prose the product supplies, rather than
composing a component that does not exist.
Three composition rules this screen exists to demonstrate:
**The card is the only surface off the page ground.** Elevation is meaning here:
exactly the result and the action are lifted, so that lifting reads as "this is
the answer" rather than as decoration. A screen where every section is a card has
no hierarchy left to spend.
**CareCard is conditional, not decorative.** It appears when there is a real
action with real timing, and is absent otherwise. A permanently present card with
"no action needed" in it teaches the reader to skip the position where the real
action will one day be.
**One status pill, or none.** The status never colours the card, the band or the
marker. See [The two colour axes](../health/two-colour-axes.mdx). If no clinical
rule assigned a status, the screen shows no status and no colour stands in for one.
## Preview [#preview]
Everything on this page renders. Nothing here is a new component: the preview above
arranges parts that already ship into the composition this page specifies, so the
three screen-level checks have something real to run against. What is unproven is
the composition rather than the components. The arrangement, its refusals and its
accessibility bar are a proposal, and the questions below are still open. Every
opsinjs component has now been audited against WCAG 2.2 AA by its authors, in a
static source pass and a rendered pass, but that audit is not an independent
review, and no component has had a clinical review yet
([ADR 0025](../project/decisions/0025-the-audit-is-author-run.mdx) records the
reach and the limits of it). Do not put this screen in front of a patient. Do copy its refusals, because those are the part
worth carrying into product code. The specimen lives under `registry/screens/` and
is not served from `/r`, so there is no `shadcn add` for it.
---
# Trends screen
Source: https://opsinjs.pensievelabs.org/screens/trends-screen
Markdown: https://opsinjs.pensievelabs.org/screens/trends-screen.md
Section: Screens · kind: screen · evidence: opinion
> NOT IMPLEMENTED. "Trends 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.
RangeLegend, Table and SegmentedControl now ship, so the band key, the
DataTable twin and the WindowControl each have a component behind them.
What the roster still leaves to the team is the MetricSelector: choosing which
metric is lifted is a product decision, so a team assembling this screen wires a
SegmentedControl or a Field select to it rather than reaching for a dedicated
component.
Three composition rules this screen demonstrates:
**One chart is lifted at a time.** The metric in question sits a rung above the
page; the related tiles sit on the ground. A screen of six equally weighted charts
has no subject, and the reader supplies one by guessing.
**The caption is inside the card, not under it.** Chart and sentence are one
artefact. If they can be screenshotted apart, they will be, and the chart travels
without its caveat.
**The data table is a peer, not a disclosure.** It is on the page, reachable
without opening anything, because for a large number of readers it is the more
useful representation.
[Accessible charts](../foundations/data-visualisation/accessible-charts.mdx) makes
the case.
## Preview [#preview]