---
title: "Result disclosure"
description: "Showing someone a result they may not want to see, without ambush, from notification to number to next step"
url: "https://opsinjs.pensievelabs.org/docs/patterns/result-disclosure"
source: "https://opsinjs.pensievelabs.org/docs/patterns/result-disclosure.md"
section: "Patterns"
kind: "pattern"
aliases: ["showing a result", "lab result flow", "disclosing a test result", "result ambush"]
---

> Elements written as `<PascalCase … />` below are opsinjs documentation
> components. Their attributes are the content: the values they render are
> generated from `tokens/*.json` and `registry/catalogue.ts` and are
> published separately at https://opsinjs.pensievelabs.org/r/index.json and under the Reference
> section.
> Nothing is missing from this page. The data simply does not live in
> the prose.

The reader knows a result is coming but not what it says, and your notification schedule picks the moment they find out. This pattern designs that moment.

## When to use it [#when-to-use-it]

Use it for a value the reader did not create and cannot interpret on sight, such as a lab result or a risk score. Use something else for:

* a number the reader typed: [Daily logging](./daily-logging.mdx);
* a value whose next step is emergency services, or a score with a self-harm item: [High-stakes moments](../health/high-stakes-moments.mdx);
* change over time: [Trend review](./trend-review.mdx);
* a pending result: [Empty and first use](./empty-and-first-use.mdx), never a card with dashes in it.

## How it works [#how-it-works]

1. **Notification.** "Your ferritin result is ready." Never the value, the status word or a colour that encodes one, because someone else may read the lock screen.
2. **Landing.** One plain-English sentence on what the test measures, before the number.
3. **The value.** Number, unit and range together on first paint. Nothing animates in, and the status never arrives after the value.
4. **Next step.** Something to do, including "nothing, and here is why". A result outside its range names a route to a human.

| State      | Shows                                         | Never                             |
| ---------- | --------------------------------------------- | --------------------------------- |
| Pending    | The test and when to expect it                | A dash or zero styled as a value  |
| Partial    | What arrived, marked incomplete               | Interpretation of a partial panel |
| Superseded | The current value, the previous one reachable | A silent replacement              |
| Withdrawn  | A statement that it was retracted             | The value quietly disappearing    |

<Todo>
  No screen shows the whole sequence yet. The results screen below covers the value and the next step. The notification and the landing surface have no specimen.
</Todo>

## Components [#components]

* [ResultCard](../components/result-card.mdx): value, range, meaning and next step as one unit.
* [RangeBar](../components/range-bar.mdx): where the value sits against its range, as position only.
* [StatusPill](../components/status-pill.mdx): the level, only when a rule your product owns assigned one.
* [Term](../components/term.mdx): a plain-English expansion of a clinical word.
* [CareCard](../components/care-card.mdx): the next step, only when there is a real action with real timing.
* [DisclaimerNote](../components/disclaimer-note.mdx): the boundary note, in the same place on every result screen.

## Value against a range [#value-against-a-range]

1. Write down the range's source, population, unit and date. Without all four you have two numbers, not a range. opsinjs supplies no ranges.
2. Convert units once, where data enters your system. A range in one unit drawn against a value in another looks plausible and is wrong.
3. Draw position, not a verdict: one continuous band, a marker told apart by shape, no truncated axis. Any status goes in the pill, never on the band.
4. Write the sentence first. The bar adds speed, never information. With no range, say so and draw no bar, because an empty bar reads as a missing result.

```tsx
import { ResultCard } from "@/components/ui/result-card"
import { EXAMPLE_SOURCE } from "@/lib/opsinjs"

<ResultCard
  title="Example measurement"
  value={14}
  unit="mg/dL"
  precision={0}
  measuredAt="2026-03-14T08:12:00+00:00"
  now="2026-03-14T11:12:00+00:00"
  range={{ low: 10, high: 20, source: EXAMPLE_SOURCE }}
  status="steady"
  category="labs"
  meaning="Two or three short sentences, in the second person, written by the product."
/>
```

ResultCard derives no level, so `status` is always your rule's output. Category reaches only the title and status only the pill, as [Two colour axes](../health/two-colour-axes.mdx) requires.

## Build a metric card [#build-a-metric-card]

A [MetricTile](../components/metric-tile.mdx) identifies and reports, and opens the detail screen where interpretation lives.

* Label what was measured in the reader's words: "Resting heart rate", not "Heart health" or "RHR".
* `measuredAt` is the measurement time, never the sync time. `staleAfterHours` is yours, per metric, with no default.
* Default to no `status`. Add one only when your rule assigned it and the screen is inside its [alarm budget](../health/alerts.mdx), and pair `attention` or `urgent` with an `href`.
* Decide all five [states](../foundations/states.mdx) first. Stale and partial are the two that mislead.

```tsx
import { MetricTile } from "@/components/ui/metric-tile"

<MetricTile
  label="Example measurement"
  value={14}
  unit="steps"
  precision={0}
  measuredAt="2026-04-06T07:15:00+00:00"
  now={now}
  href="/results/example"
/>
```

## Example [#example]

<IframePreview kind="screen" name="results-screen" />

Every part of the results screen ships, but its composition has had no clinical review. It is not served from `/r`, so there is no `shadcn add` for it.

## Content [#content]

Copy runs in a fixed order: what this is, what it says, what it means, what to do, who to ask.

> Your `<measurement>` was `<value> <unit>`, measured `<when>`. The usual range for this test is `<low>` to `<high>` `<unit>`. `<what this does or does not mean>` `<what happens next>`

Never write *normal*, *abnormal*, *good* or *bad*. Describe the position, such as "above the usual range", and not the person. [Reference ranges](../health/reference-ranges.mdx) owns the rule. DOM order follows the same sequence, because a pill placed first announces a verdict before the fact.
