Components
StatusPill
A short label that says which of four levels of attention something needs. It is shown as a word, an icon and a colour together, never as a colour alone.
Usage
pnpm dlx shadcn@latest add @opsinjs/status-pill
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 { StatusPill } from "@/components/ui/status-pill"<StatusPill status="attention" describes="Second example measurement" />Examples
status-pill · base base · style base-lyraOpen under the product themeScanning a column
Four rows, each graded by status, and exactly one urgent.
status-pill-in-a-list · base base · style base-lyraOpen under the product themeimport { StatusPill } from "@/components/ui/status-pill"
const ROWS = [
{ subject: "First example measurement", status: "steady" },
{ subject: "Second example measurement", status: "watch" },
{ subject: "Third example measurement", status: "attention" },
{ subject: "Fourth example measurement", status: "urgent" },
] as const
export default function StatusPillInAList() {
return (
<ul className="m-0 flex w-full max-w-md list-none flex-col gap-opsin-2 p-0">
{ROWS.map((row) => (
<li
key={row.subject}
className="flex flex-wrap items-center justify-between gap-opsin-4 border-b border-border py-opsin-2 text-opsin-body"
>
<span className="min-w-0">{row.subject}</span>
<StatusPill status={row.status} />
</li>
))}
</ul>
)
}Every size keeps the word
size sets the type step and padding and nothing else. sm and md label a status in
prose and lists, and lg matches a heading.
status-pill-sizes · base base · style base-lyraOpen under the product themeimport { StatusPill } from "@/components/ui/status-pill"
export default function StatusPillSizes() {
return (
<div className="flex flex-col gap-opsin-4">
<div className="flex flex-wrap items-center gap-opsin-3">
<span className="text-opsin-caption1 text-muted-foreground">lg</span>
<StatusPill status="watch" size="lg" describes="example measurement" />
<StatusPill status="attention" size="lg" describes="example measurement" />
</div>
<div className="flex flex-wrap items-center gap-opsin-3">
<span className="text-opsin-caption1 text-muted-foreground">md</span>
<StatusPill status="watch" describes="example measurement" />
<StatusPill status="attention" describes="example measurement" />
</div>
<div className="flex flex-wrap items-center gap-opsin-3">
<span className="text-opsin-caption1 text-muted-foreground">sm</span>
<StatusPill status="watch" size="sm" describes="example measurement" />
<StatusPill status="attention" size="sm" describes="example measurement" />
</div>
</div>
)
}When to use it
Use it when
- Labelling one result, reading or item with the level of attention the product has assigned to it.
- Making a status scannable in a list, a table or a grid, where reading each row in full is not realistic.
- Summarising a surface whose status the reader would otherwise have to infer from its contents.
Do not use it when
- The status needs explaining, or the reader needs to know what to do about it.Use
care-cardinstead. - The status must interrupt what the reader is doing rather than wait to be noticed.Use
alert-bannerinstead. - The label is a category, a source, a tag, a count or a release phase rather than a level of attention.Use
badgeinstead. - You want to show where a value sits relative to a range, which is a position rather than a level.Use
range-barinstead. - The message is informational and carries no clinical level at all.Use
calloutinstead.
Clinical meaning
Asserts. That the product has assigned one of exactly four levels of attention to
the thing the pill labels: steady, watch, attention or urgent, defined in
Two colour axes. It does not say what is wrong, why,
or what happens next.
Never read as. A diagnosis, a severity score or a triage category. The levels
describe what the interface asks of the reader, not the state of their body, so
urgent on a screen is not urgent in a clinical handover.
Colour axis. Status only, and never alone: every pill renders a word and a glyph beside its colour. A category colour belongs on a Badge, never on a pill, and Two colour axes says why the two never share an element.
Thresholds. None. The consuming product assigns the level from rules or a clinician, and the pill derives nothing.
Accessibility
The icon is aria-hidden and sized in em, so the word carries the meaning and the
glyph grows with it. At 200% text the pill grows and wraps, and the word is never
truncated or replaced by the icon alone. The pill is an enamel plate, the same in both
themes: white on the deep Steady, Needs attention and Urgent plates, deep brown on the
gold Watch plate. Every plate's word clears the body-text floor on its face and on the lit
band along its top, the build refuses a plate that does not, and the report below
measures both pairs. There is no axe, target-size, focus or 320px reflow failure.
pnpm run check:a11y checks on every commit that no file paints a status colour
without reading CLINICAL_STATUS_META and a glyph, that every status surface carries
data-status, and that status words come from CLINICAL_STATUS_META[level].word, never
a literal. The four levels name four distinct glyphs: circle, ringed dot, diamond and
octagon, the last two filled so each silhouette is heavier than the one below it. A11Y017
fails the build when two levels share one. The glyph takes the word's colour.
Residual items.
- The consuming product must pass
describeswhen the pill floats free of its subject, in a table cell reached by column navigation or a card corner, because the component cannot know the reading context. - With
describes, the pill announces as Needs attention, Second example measurement. Omit it when the subject is visible text in the same reading unit. - The pill is a
span. One made into a filter is a Button and owes a Button's target and name. - No live region is mounted, on purpose. A static read-only label is not a message, so
a
role="status"announcement would be wrong. - Steady and Urgent are both deep plates with a white word, so in greyscale and under some colour-vision deficiencies they differ by word and glyph shape, not by colour.
- On paper the plate, its light and its shadow go, and the pill prints as the level's tint with its ink and a full-strength boundary. Forced colours drop the plate's light; that rendering is not measured. The boundary and the shadow are decorative and not measured.
| Key | Action | Notes |
|---|---|---|
| Tab | Skips the pill | Not focusable. A label with a tab stop is a stop every row pays for. |
| Shift+Tab | Skips the pill | Same in reverse. Never in the focus order in either direction. |
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 StatusPillProps in registry/bases/base/status-pill.tsx.
status has no default, and a value outside the four, including unknown, renders no
pill and warns in development. className is merged last and can strip the
fill or the line, so change size instead. It cannot recolour the word; a rule on
[data-slot="status-pill"] can.
Data attributes
| Attribute | Condition | Value |
|---|---|---|
| data-slot | On the root and both inner parts, always | status-pill, status-pill-icon, status-pill-label |
| data-status | On the root, always, because status is required | steady | watch | attention | urgent |