Skip to content
opsinjs
Edit this page

Patterns

Offline and stale data

What a health screen shows when it cannot vouch for its numbers. The value stays, and every claim about now is withdrawn.

Staleness degrades assertions, not values. The number stays, because the reader is entitled to it. Its status, trend, range comparison and alerts are claims about now, which the product no longer knows.

When to use it

Use it when the product shows a value it can no longer stand behind, because the network is gone, a device has not synced or a refresh failed.

Do not use it when:

  • There is no value at all. That is Empty and first use.
  • The value is old by design. A March blood test is dated, not stale, so show its date.

Trends and uncertainty holds the doctrine on staleness and provenance.

How it works

  1. Every measure has a freshness window, set by the team that owns its thresholds.
  2. Beyond the window, keep the value and its timestamp and withdraw the status axis: no StatusPill, no colour-coded verdict, no trend arrow.
  3. Suspend alerts computed from stale data rather than firing them. See Alert escalation.
  4. Refresh quietly. Success restores full assertions without a banner. Failure says what being offline means here.
  5. Show an offline entry at once, marked unsynced, with the time it was made.
  6. Show conflicts and never merge them. Two devices writing one slot make two entries the reader resolves.
StateStatus axisTimestamp
FreshFullDe-emphasised
AgeingFullVisible, age promoted
StaleWithdrawnProminent
Offline, cachedWithdrawnProminent, with an offline notice
Unsynced writeNone yetTime of entry, marked unsynced
ConflictWithdrawn until resolvedBoth times shown
Unknown ageWithdrawn"We don't know when this was measured"

The value shows in every state. Never hide the timestamp, and never stamp an imported value with the import time.

Components

  • RelativeTime writes the age. The product supplies staleAfterHours, which has no default, and event separates measured from synced.
  • MetricTile mutes past staleAfterHours and adds "may be out of date".
  • StatusPill is removed once the value is stale, never greyed.
  • AlertBanner carries a screen-wide condition, such as a queued write that failed to send.

Content

  • Name what is uncertain: "Last synced 4 hours ago. Your monitor may have taken readings since then. We can't show a current status until it reconnects." Not "Some data may be out of date."
  • Tell the reader their entry is safe: "Saved on your phone. It will sync when you're back online."

Accessibility

  • Entering the stale state is one polite status message per transition, not one per tile (WCAG 2.2 SC 4.1.3).
  • The offline notice is announced, never modal, and never takes focus.
  • Never grey a value out to show staleness, because it fails the contrast floor. Use words and position.
  • Retry is a focusable, labelled control, even where pull-to-refresh exists.