---
title: "Trend review"
description: "Reading change over time without over-interpreting noise, with minimum windows, honest axes and direction kept apart from valence"
url: "https://opsinjs.pensievelabs.org/docs/patterns/trend-review"
source: "https://opsinjs.pensievelabs.org/docs/patterns/trend-review.md"
section: "Patterns"
kind: "pattern"
aliases: ["trends over time", "change over time", "chart review", "is it going up", "noise vs signal"]
---

> 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's question is "is this getting better or worse", not "what is my number". By default, charts mislead here. Three points make a line, an axis fitted to the data turns a small drift into a cliff, and a nightly average changes direction twice a week.

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

Use it when the reader compares a value with their own history, the measure varies day to day, and someone might change a behaviour or a dose because of the line. Use something else for:

* one value against one range: [Result disclosure](./result-disclosure.mdx);
* a sustained change that needs action: [Alert escalation](./alert-escalation.mdx);
* chart mechanics or the doctrine: [Data visualisation](../foundations/data-visualisation.mdx) and [Trends and uncertainty](../health/trends.mdx).

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

1. **Count the readings.** Below the metric's minimum, show the points with no line and no direction word, and say how many more are needed. Your product owns that minimum.
2. **Fix an honest axis.** Zero where zero means something, otherwise the reference band or a fixed span. Keep it stable, and never fit it to the data.
3. **Compare the change with the noise.** A change smaller than the measure's own variation is "about the same", with no direction named.
4. **Name direction, never valence.** Up, down or about the same. Down is not worse. A status your rule assigned appears in words beside the chart and never recolours the line.
5. **Write the caption.** Direction, size, unit and window, in words. The caption is the deliverable and the chart illustrates it.
6. **Ship the table twin,** with the same numbers, on the page, in every state.

Gaps are drawn as gaps, never interpolated. A stale series promotes its last-updated stamp and demotes the direction. Series in different units are split, never rescaled onto one axis. No causal language: "your sleep improved because you walked more" is a claim self-tracked data cannot support.

<NotBuiltYet />

## Components [#components]

* [TrendSparkline](../components/trend-sparkline.mdx): the series and its caption, with category colour on the line only.
* [Table](../components/table.mdx): the readable twin, which TrendSparkline does not supply.
* [RangeLegend](../components/range-legend.mdx): the key to a band behind the series.
* [SegmentedControl](../components/segmented-control.mdx): the window, such as 7 days, 30 days or 12 months.
* [Value](../components/value.mdx) and [MetricTile](../components/metric-tile.mdx): the latest reading, and related metrics.
* [Skeleton](../components/skeleton.mdx) and [EmptyState](../components/empty-state.mdx): never a flat line at zero.

## Trend with an honest caption [#trend-with-an-honest-caption]

```tsx
import { TrendSparkline } from "@/components/ui/trend-sparkline"

<TrendSparkline
  label="Example measurement"
  unit="steps"
  precision={0}
  locale="en-GB"
  window="the last 6 entries"
  series={series}
  minimumPoints={readingsATrendNeeds}
/>
```

`minimumPoints` is required and has no default. Below it nothing is drawn, and the caption says why. `changeThreshold` is the smallest difference your metric counts as a change, and without it the caption names no direction. A gap is an entry with `value: null`, never an omitted one.

To write your own sentence, pass `caption`. The count of readings and of missing entries is still appended. Keep to this shape:

> `<metric>` `<direction>` `<magnitude> <unit>` over `<window>`, compared with `<comparison window>`. `<what a change of this size does not mean>`

"Your resting heart rate was about 4 bpm lower over the last 7 days than the 7 days before. Day-to-day variation of this size is common and does not on its own mean anything has changed." Lead with absolute change, because a percentage of a small number makes a trivial change sound large. Never congratulate or commiserate.

<Todo>
  Marking an event on the line itself, such as a medication change or an illness, has no component and no guidance yet. [TimelineEntry](../components/timeline-entry.mdx) covers a dated history list, not the chart.
</Todo>

## Example [#example]

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

The trends screen is still a specification, so its frame shows the not-built notice. Its caption sits inside the card with the chart, so the two cannot be screenshotted apart.

## Accessibility [#accessibility]

* The caption is the chart's accessible description, not "line chart showing resting heart rate".
* Changing the metric or window announces the new summary politely and does not move focus.
* A focused point announces its value, unit and date, and every value is in the table without a gesture.
* No draw-on animation carries meaning, and at 200% text the sentence is never truncated.
