Skip to content
opsinjs
Edit this page

Foundations

States

The six interaction states every control shows, and the five data states every surface that displays a value must render.

Interaction states say what you are doing to a control. Data states say what the system knows about the value inside it. A button can be hovered but never stale, and a reading can be stale but never hovered.

Interaction states

Every interactive component must implement all six, or its page must say why not.

StateRule
HoverPointer only, so never the only signal. A small lightness step, darker in the light theme and lighter in the dark
PressApplied on pointer-down, not on click, on duration-instant, and released on spring-snap, or on duration-fast where the control holds a reading
Focus:focus-visible only. An offset outline outside the box, in one system-wide colour, so it never moves layout or gets clipped
SelectedPersistent and distinct from focus. A fill and a mark, never a fill alone
DisabledDimmed, with no pointer affordance, but readable. It leaves the tab order, so state the reason where a keyboard user will find it
BusyKeeps its label and tab stop and refuses activation, without becoming disabled. Button's busy prop sets aria-busy and aria-disabled

States resolve in a fixed order: disabled, busy, pressed, selected, focus, hover. A pressed control keeps its focus ring, and a disabled control never looks hoverable.

  • Never author a state colour. Hover and press come from shared fills.
  • A state is never a verdict. A tapped result card may darken, but it never takes a status colour.
  • When a control becomes disabled or disappears, focus moves somewhere documented, never to the document body.

Press is implemented on Button and Link, and every component built from them inherits it. It is also on a linked Card and MetricTile, and on the close controls of Dialog, Sheet and Toast. Motion sets out how it moves.

Derived state values and their measured contrast are not generated yet.

This table has not been generated. It is produced by scripts/build-tokens.mts. Run pnpm run generate and reload.

Nothing on this site types a measured number by hand, so an ungenerated table shows this rather than an example.

Data states

Every surface that shows a value must render five data states, so that a blank, a -- or a zero never stands in for a value nobody knows. A surface shows the first state below that applies.

StateMeansRender
ErrorThe system tried and failedEmptyState with reason="could-not-load", a neutral word and icon with a retry or a route onwards
LoadingThe system is tryingA Skeleton in the final layout, with no placeholder digits or plausible chart
EmptyThere is genuinely nothingEmptyState naming what would appear here, with one next action
PartialOnly some of the window arrivedThe value with its coverage, such as four of seven days, or EmptyState with reason="not-enough"
StaleReal but oldThe value with its age and a refresh route, keeping its status colour. MetricTile takes staleAfterHours
  • Every state carries a word, and the state itself never takes a status colour.
  • Never average across a gap without saying so.
  • The product's clinical governance sets when a value turns stale (Trends and uncertainty), and the product sets how long loading runs before saying what it waits for. opsinjs renders the state, never the number.
  • Announce each change once. Skeletons are hidden from assistive technology, and stale and partial belong in the accessible name.
Not written yet.

No surface takes a state input or emits data-state, and nothing accepts the DataState type in lib/opsinjs.ts yet. Wire the five states from separate parts, and select on the words a surface renders.