Components
RangeLegend
The key naming the tones a RangeBar draws, so a reader learns in one place what the reference band and each status colour mean. It asserts nothing itself.
Usage
pnpm dlx shadcn@latest add @opsinjs/range-legend
The @opsinjs namespace is declared in your components.json. Everything it installs is code you then own. There is no runtime package to keep in step.
import { RangeLegend } from "@/components/ui/range-legend"<RangeLegend
bands={[
{ label: "The usual range", description: "From your laboratory. Most results sit here." },
{ label: "Worth watching", tone: "watch" },
{ label: "Needs attention", tone: "attention" },
]}
/>Examples
range-legend · base base · style base-lyraOpen under the product themeThe legend beside its bar
The same container as the bars it names, bands holding the tones they draw. Each swatch is a miniature of the bar's own piece: the lit band in the tube, or the cursor with its index line.
range-legend-beside-its-bar · base base · style base-lyraOpen under the product themeimport { EXAMPLE_SOURCE, type ClinicalStatus } from "@/lib/opsinjs"
import { RangeBar } from "@/components/ui/range-bar"
import { RangeLegend } from "@/components/ui/range-legend"
const ROWS: { label: string; value: number; status: ClinicalStatus; measuredAt: string }[] = [
{
label: "First example measurement",
value: 22,
status: "watch",
measuredAt: "2026-03-14T08:12:00+00:00",
},
{
label: "Second example measurement",
value: 27,
status: "attention",
measuredAt: "2026-03-13T21:05:00+00:00",
},
]
export default function RangeLegendBesideItsBar() {
return (
<div className="flex w-full max-w-md flex-col gap-opsin-6">
<ul className="m-0 flex list-none flex-col gap-opsin-8 p-0">
{ROWS.map((row) => (
<li key={row.label} className="m-0">
<RangeBar
label={row.label}
value={row.value}
unit="mg/dL"
precision={0}
range={{ low: 10, high: 20, source: EXAMPLE_SOURCE }}
status={row.status}
measuredAt={row.measuredAt}
locale="en-GB"
/>
</li>
))}
</ul>
<RangeLegend
bands={[
{ label: "The usual range", description: "The band on each bar above." },
{ label: "Worth watching", tone: "watch" },
{ label: "Contact your care team", tone: "attention" },
]}
/>
</div>
)
}The four levels, named once
The whole vocabulary in one key: the neutral band and four status levels, each row's tone giving its word, glyph and colour.
range-legend-the-four-levels · base base · style base-lyraOpen under the product themeimport { RangeLegend } from "@/components/ui/range-legend"
export default function RangeLegendTheFourLevels() {
return (
<div className="w-full max-w-xs">
<RangeLegend
aria-label="The range tone key"
bands={[
{
label: "The usual range",
description: "From your laboratory. Most results sit here.",
},
{
label: "In the expected range",
description: "Where this reading is expected to be.",
tone: "steady",
},
{
label: "Worth watching",
description:
"Outside the usual range. Nothing to do before your next reading.",
tone: "watch",
},
{
label: "Contact your care team",
description:
"Your care team set this. Contact them about this reading.",
tone: "attention",
},
{
label: "Contact urgent care now",
description: "Contact your urgent care service now.",
tone: "urgent",
},
]}
/>
</div>
)
}When to use it
Use it when
- Beside RangeBars that share a status vocabulary, naming each level once instead of a pill per row.
- As the key beneath a single RangeBar whose status tones a first time reader has not met.
- Wherever a reader must learn the neutral band and the status colours before reading the numbers.
Do not use it when
- You are showing one measurement against its range; the bar already states reading, range and position.Use
range-barinstead. - You want the level of one reading. A legend names the vocabulary, never a verdict.Use
status-pillinstead. - You are explaining a single clinical term rather than a set of tones.Use
terminstead.
Clinical meaning
Asserts. The tones the bar beside it draws, and what each one means. Nothing about any reading, cause or next step.
Never read as. A scale, a diagnosis or a verdict on the reader. "Needs attention" names a tone a product may assign, not the reader's result. "Normal" and "abnormal" are banned; Reference ranges carries the list.
Colour axis. The status axis and the neutral reference range band only. No element carries data-category, because Two colour axes never mix. Every status row draws fill, glyph and word together, so the level survives greyscale.
Thresholds. The product owns every word, range and level. RangeLegend ships no band names; words arrive as props and the swatch colours are all it supplies.
Accessibility
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 grow with the words, which wrap with no ellipsis, and under forced-colors: active the tube keeps a CanvasText outline and a status swatch's index line takes Highlight.
The audit fixed two gaps. The legend <ul> had no accessible name, and optional aria-label and aria-labelledby props now 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, and a guard now warns on it, with the empty-bands and invalid-tone guards.
Residual items.
- A status swatch's index line takes RangeBar's tick tone, the level's line role, inside a glass cursor, so its contrast against the cursor is unmeasured. Each is
aria-hiddendecoration redundant to the word and glyph, so a low-contrast swatch loses nothing, and measuring the four lines 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-labelledbyis how a caller binds it, and the audit cannot verify callers do.
| Key | Action | Notes |
|---|---|---|
| Tab | Skips the whole component | Nothing here is focusable. |
| Shift+Tab | Skips the whole component | Never in the focus order. |
| Arrow keys | Nothing | Swatches are decorative, words static. |
Contrast: 134 measured token pairs, 33 below floor
| Pair | Theme | APCA Lc | WCAG 2.2 | Floor |
|---|---|---|---|---|
| attention ink on attention surface | light | 89.4 | 10.35:1 | Pass |
| attention ink on attention surface | dark | -81.1 | 12.54:1 | Pass |
| attention line on attention surface | light | 70.0 | 4.90:1 | Pass |
| attention line on attention surface | dark | -65.5 | 9.54:1 | Pass |
| attention accent on attention surface | light | 65.1 | 4.18:1 | Pass |
| attention accent on attention surface | dark | -49.4 | 6.80:1 | Pass |
| attention ink on the attention band | light | 22.4 | 2.48:1 | Below floor |
| attention ink on the attention band | dark | -31.0 | 1.84:1 | Below floor |
| attention accent on the page | light | 67.8 | 4.35:1 | Pass |
| attention accent on the page | dark | -50.5 | 7.47:1 | Pass |
| attention ink on the page | light | 92.2 | 10.77:1 | Pass |
| attention ink on the page | dark | -82.3 | 13.76:1 | Pass |
| steady ink on steady surface | light | 88.3 | 9.62:1 | Pass |
| steady ink on steady surface | dark | -82.9 | 12.56:1 | Pass |
| steady line on steady surface | light | 67.5 | 4.45:1 | Pass |
| steady line on steady surface | dark | -68.9 | 9.91:1 | Pass |
| steady accent on steady surface | light | 56.4 | 3.21:1 | Pass |
| steady accent on steady surface | dark | -53.2 | 7.25:1 | Pass |
| steady ink on the steady band | light | 30.0 | 3.00:1 | Below floor |
| steady ink on the steady band | dark | -28.8 | 1.73:1 | Below floor |
| steady accent on the page | light | 58.6 | 3.31:1 | Pass |
| steady accent on the page | dark | -54.5 | 8.19:1 | Pass |
| steady ink on the page | light | 90.6 | 9.94:1 | Pass |
| steady ink on the page | dark | -84.2 | 14.20:1 | Pass |
| unknown ink on unknown surface | light | 89.5 | 9.98:1 | Pass |
| unknown ink on unknown surface | dark | -82.2 | 12.56:1 | Pass |
| unknown line on unknown surface | light | 69.2 | 4.64:1 | Pass |
| unknown line on unknown surface | dark | -67.2 | 9.72:1 | Pass |
| unknown accent on unknown surface | light | 43.1 | 2.29:1 | Below floor |
| unknown accent on unknown surface | dark | -51.3 | 7.05:1 | Pass |
| unknown accent on the page | light | 45.6 | 2.37:1 | Below floor |
| unknown accent on the page | dark | -52.3 | 7.84:1 | Pass |
| unknown ink on the page | light | 92.0 | 10.34:1 | Pass |
| unknown ink on the page | dark | -83.1 | 13.97:1 | Pass |
| urgent ink on urgent surface | light | 88.2 | 10.58:1 | Pass |
| urgent ink on urgent surface | dark | -80.3 | 12.52:1 | Pass |
| urgent line on urgent surface | light | 70.0 | 5.09:1 | Pass |
| urgent line on urgent surface | dark | -64.8 | 9.52:1 | Pass |
| urgent accent on urgent surface | light | 72.3 | 5.58:1 | Pass |
| urgent accent on urgent surface | dark | -48.0 | 6.63:1 | Pass |
| urgent ink on the urgent band | light | 13.9 | 1.90:1 | Below floor |
| urgent ink on the urgent band | dark | -31.5 | 1.89:1 | Below floor |
| urgent accent on the page | light | 75.3 | 5.84:1 | Pass |
| urgent accent on the page | dark | -49.5 | 7.24:1 | Pass |
| urgent ink on the page | light | 91.2 | 11.06:1 | Pass |
| urgent ink on the page | dark | -81.8 | 13.66:1 | Pass |
| watch ink on watch surface | light | 89.4 | 10.02:1 | Pass |
| watch ink on watch surface | dark | -82.1 | 12.58:1 | Pass |
| watch line on watch surface | light | 69.5 | 4.72:1 | Pass |
| watch line on watch surface | dark | -66.8 | 9.68:1 | Pass |
| watch accent on watch surface | light | 61.7 | 3.72:1 | Pass |
| watch accent on watch surface | dark | -50.7 | 6.95:1 | Pass |
| watch ink on the watch band | light | 25.7 | 2.70:1 | Below floor |
| watch ink on the watch band | dark | -30.6 | 1.81:1 | Below floor |
| watch accent on the page | light | 64.2 | 3.85:1 | Pass |
| watch accent on the page | dark | -51.7 | 7.71:1 | Pass |
| watch ink on the page | light | 91.9 | 10.38:1 | Pass |
| watch ink on the page | dark | -83.1 | 13.95:1 | Pass |
| body text on the page | light | 101.6 | 17.18:1 | Pass |
| body text on the page | dark | -100.5 | 18.00:1 | Pass |
| body text on a card | light | 104.7 | 17.96:1 | Pass |
| body text on a card | dark | -99.6 | 16.32:1 | Pass |
| body text on the muted ground | light | 98.1 | 16.32:1 | Pass |
| body text on the muted ground | dark | -97.5 | 13.77:1 | Pass |
| secondary text on the page | light | 83.9 | 7.42:1 | Pass |
| secondary text on the page | dark | -80.7 | 13.44:1 | Pass |
| secondary text on a card | light | 87.0 | 7.76:1 | Pass |
| secondary text on a card | dark | -79.8 | 12.19:1 | Pass |
| secondary text on the muted ground | light | 80.4 | 7.05:1 | Pass |
| secondary text on the muted ground | dark | -77.8 | 10.28:1 | Pass |
| a hairline boundary on the page | light | 19.3 | 1.41:1 | Below floor |
| a hairline boundary on the page | dark | -8.2 | 1.90:1 | Below floor |
| a hairline boundary on a card | light | 22.4 | 1.47:1 | Below floor |
| a hairline boundary on a card | dark | -7.3 | 1.72:1 | Below floor |
| a hairline boundary on the muted ground | light | 15.8 | 1.34:1 | Below floor |
| a hairline boundary on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on the page | light | 69.8 | 4.52:1 | Pass |
| a placeholder boundary on the page | dark | -51.0 | 7.62:1 | Pass |
| a placeholder boundary on a card | light | 72.8 | 4.72:1 | Pass |
| a placeholder boundary on a card | dark | -50.1 | 6.91:1 | Pass |
| a placeholder boundary on the muted ground | light | 66.2 | 4.29:1 | Pass |
| a placeholder boundary on the muted ground | dark | -48.1 | 5.83:1 | Pass |
| a placeholder fill on the page | light | 8.3 | 1.18:1 | Below floor |
| a placeholder fill on the page | dark | -8.2 | 1.90:1 | Below floor |
| a placeholder fill on a card | light | 11.4 | 1.23:1 | Below floor |
| a placeholder fill on a card | dark | -7.3 | 1.72:1 | Below floor |
| a placeholder fill on the muted ground | light | 0.0 | 1.12:1 | Below floor |
| a placeholder fill on the muted ground | dark | 0.0 | 1.45:1 | Below floor |
| a placeholder boundary on its own fill | light | 58.9 | 3.84:1 | Pass |
| a placeholder boundary on its own fill | dark | -41.5 | 4.01:1 | Below floor |
| the card hairline on the page | light | 69.8 | 4.52:1 | Pass |
| the card hairline on the page | dark | -28.7 | 4.19:1 | Below floor |
| the card hairline on a card | light | 72.8 | 4.72:1 | Pass |
| the card hairline on a card | dark | -27.9 | 3.80:1 | Below floor |
| attention surface on the card material | light | 0.0 | 1.09:1 | Below floor |
| attention surface on the card material | dark | 0.0 | 1.00:1 | Below floor |
| steady surface on the card material | light | 0.0 | 1.08:1 | Below floor |
| steady surface on the card material | dark | 0.0 | 1.03:1 | Below floor |
| urgent surface on the card material | light | 0.0 | 1.09:1 | Below floor |
| urgent surface on the card material | dark | 0.0 | 1.01:1 | Below floor |
| watch surface on the card material | light | 0.0 | 1.08:1 | Below floor |
| watch surface on the card material | dark | 0.0 | 1.01:1 | Below floor |
| the focus ring on the attention surface | light | 69.5 | 4.83:1 | Pass |
| the focus ring on the attention surface | dark | -57.5 | 8.14:1 | Pass |
| attention ink on the neutral hover fill | light | 88.6 | 10.23:1 | Pass |
| attention ink on the neutral hover fill | dark | -79.3 | 10.53:1 | Pass |
| the focus ring on the steady surface | light | 70.0 | 4.86:1 | Pass |
| the focus ring on the steady surface | dark | -57.3 | 7.91:1 | Pass |
| steady ink on the neutral hover fill | light | 87.0 | 9.43:1 | Pass |
| steady ink on the neutral hover fill | dark | -81.3 | 10.86:1 | Pass |
| the focus ring on the urgent surface | light | 69.3 | 4.81:1 | Pass |
| the focus ring on the urgent surface | dark | -57.1 | 8.19:1 | Pass |
| urgent ink on the neutral hover fill | light | 87.7 | 10.50:1 | Pass |
| urgent ink on the neutral hover fill | dark | -78.9 | 10.46:1 | Pass |
| the focus ring on the watch surface | light | 69.8 | 4.85:1 | Pass |
| the focus ring on the watch surface | dark | -57.6 | 8.07:1 | Pass |
| watch ink on the neutral hover fill | light | 88.3 | 9.86:1 | Pass |
| watch ink on the neutral hover fill | dark | -80.1 | 10.67:1 | Pass |
| steady plate word on the plate's face | light | -83.2 | 5.69:1 | Pass |
| steady plate word on the plate's face | dark | -83.2 | 5.69:1 | Pass |
| steady plate word on the plate's lit band | light | -78.1 | 4.77:1 | Pass |
| steady plate word on the plate's lit band | dark | -78.1 | 4.77:1 | Pass |
| watch plate word on the plate's face | light | 76.4 | 11.33:1 | Pass |
| watch plate word on the plate's face | dark | 76.4 | 11.33:1 | Pass |
| watch plate word on the plate's lit band | light | 81.9 | 12.50:1 | Pass |
| watch plate word on the plate's lit band | dark | 81.9 | 12.50:1 | Pass |
| attention plate word on the plate's face | light | -81.4 | 5.43:1 | Pass |
| attention plate word on the plate's face | dark | -81.4 | 5.43:1 | Pass |
| attention plate word on the plate's lit band | light | -77.0 | 4.66:1 | Pass |
| attention plate word on the plate's lit band | dark | -77.0 | 4.66:1 | Pass |
| urgent plate word on the plate's face | light | -85.9 | 6.63:1 | Pass |
| urgent plate word on the plate's face | dark | -85.9 | 6.63:1 | Pass |
| urgent plate word on the plate's lit band | light | -81.7 | 5.59:1 | Pass |
| urgent plate word on the plate's lit band | dark | -81.7 | 5.59:1 | Pass |
These are the measured token pairs this component draws colour from, not a measurement of the component itself.
Props interface
Prop
Type
Generated from RangeLegendProps in registry/bases/base/range-legend.tsx.
tone is typed to the four ClinicalStatus levels in Two colour axes. A value outside the four is refused with a development warning and falls back to the neutral band. An empty bands array renders nothing and warns in development.
Data attributes
| Attribute | Condition | Value |
|---|---|---|
| data-slot | On the root and every named inner part, always | range-legend, range-legend-item, range-legend-swatch, range-legend-label |
| data-status | On a status row's item; absent on the neutral band row | The row's tone: steady, watch, attention or urgent |