Card
A bounded region holding things that belong together. In a patient record, a boundary is a claim — it asserts that everything inside relates to one subject, from one source, at one time. Draw one carelessly and you have made a clinical statement by accident.
Overview
Cards are the least interesting component in most design systems and one of the more consequential here, because grouping carries meaning. A clinician reading a card containing a troponin value and an ECG finding will reasonably infer that both belong to the same patient, the same encounter and roughly the same moment. If any of that is untrue, the card said so and nobody wrote it down.
Truthful grouping
Everything inside one card shares a subject, a source and a time. If those differ, it is two cards.
Flat
One level of nesting, never two. A card inside a card inside a panel is a hierarchy nobody can hold while being interrupted.
Complete
A card shows all of its content or says how much it is hiding. Nothing clinical scrolls silently inside a fixed-height box.
Anatomy
High-sensitivity troponin I
RisingNSTEMI cannot be excluded on this trajectory. Repeat sampling due 15:10.
| Region | Contains | Rule |
|---|---|---|
| Header | Title, optional status chip | A real heading element at the correct level. The title names the subject, not the widget — "High-sensitivity troponin I", not "Lab panel". |
| Body | The content | One subject. Values carry units. Nothing scrolls without a visible affordance. |
| Footer | Provenance | Patient, time and source. Required on any card holding clinical data — this is the line that makes the grouping checkable rather than assumed. |
A card asserts that its contents belong together. The footer is where that assertion is made explicit and falsifiable: whose data, from when, from where. A clinical card without provenance is a grouping claim with nothing behind it — and it is exactly the construct that lets data from a previous encounter, or a different patient, sit unnoticed beside current results.
What may share a card
| Together | Separate |
|---|---|
| Serial values of the same measurement in one encounter | The same measurement from a previous admission |
| Findings from one ECG acquisition | Findings from two acquisitions — even minutes apart |
| A model output and the confidence and version that produced it | Outputs from two model versions |
| Fields a clinician fills in one action | Fields that submit to different systems |
Where a genuine comparison across sources is needed — a current ECG against a prior — that is two cards side by side, each with its own provenance, never one card with two halves. See ECG review.
Variants
default
Bordered, on --card. The workhorse.
interactive
The whole card is one link or button leading to detail. Border strengthens on hover, focus ring on the card itself. Only permitted when the card contains no other interactive element — nested controls inside a clickable card produce a target a clinician cannot aim at and a nesting violation assistive technology cannot resolve.
flush
Body padding removed so a table or trace can meet the card edge. Used by Data grid and ECG review.
Border, not shadow
Cards are separated by a 1 px border, not a drop shadow. Shadow means "floating above, and probably temporary" — it belongs to popovers, menus and dialogs. Using it for static content teaches clinicians that raised things are transient, which then undermines the components where transience is the point. A card that needs a shadow to be found is a card on the wrong surface.
Nesting and density
- One level of nesting maximum. A card may sit inside a layout panel. A card may not sit inside a card.
- An inline alert may sit inside a card when it concerns that card's subject — see Alert Banner. It never carries a priority higher than the card's own subject warrants.
- No fixed heights on clinical content. A card that clips a value is worse than a card that is tall. Where scrolling is unavoidable, the count of hidden items is stated in the header.
- Card grids reflow, they do not compress. Minimum 230 px per card; below that they stack. Squeezing a card until its provenance line wraps to four lines is not responsive design.
12-lead ECG
One acquisition, one subject, provenance stated. The grouping can be checked.
Cardiac summary
Troponin 47 ng/L.
Prior ECG: normal.
Three sources, three times, no provenance. The card asserts they belong together and gives no way to check whether they do.
Do's and don'ts
12-lead ECG
One acquisition, one subject, provenance stated. The grouping claim can be checked.
Cardiac summary
Troponin 47 ng/L.
Prior ECG: normal.
Three sources, three times, no provenance. The boundary asserts a relationship nobody can verify.
Troponin
RisingFlat card; urgency carried by the chip, where a clinician already looks for it.
Troponin
Raised to signal importance. It now reads as floating and dismissible, competing with the alarm layer.
Accessibility
- The title is a real heading at the level the page structure requires, so a screen-reader user can navigate a record by card.
- A card is a
<section aria-labelledby>when it is a landmark region worth jumping to; otherwise it is a plain container. Not everything needs a role. - Interactive cards are one element — an
<a>or<button>wrapping the content, never a div with a click handler and never nested interactive children. - Focus ring on the card, offset outside its border so it is visible against both the card and the surface behind it.
- Reflow before truncation. At 200 % zoom cards stack; they do not clip.
- Provenance is text, in the reading order, never a hover tooltip.
Outcomes of use
What this contributes to, in the terms of Usability & context of use. These are attributes believed to contribute to an outcome; the outcome itself is settled by observing real use in a specified context, not by this page.
- Effectiveness — the relationships a clinician infers from a boundary are the relationships that actually exist. Wrongly grouped data is the failure this component owns.
- Efficiency — a whole card read in one fixation rather than assembled from scattered fields. Provenance in a fixed position means it is checked rather than hunted for.
- Satisfaction — confidence that what is on screen belongs to the patient in front of you. Cards without provenance produce a low-grade doubt clinicians resolve by opening the source, which is the cost of the missing line.
Clinical safety notes
Trace these in your risk file (ISO 14971) and usability engineering file (IEC 62366-1).
- One subject, one source, one time per card. Mitigates: data from another encounter or another patient being read as current and related.
- Provenance required on clinical cards. Mitigates: an unfalsifiable grouping claim; supports wrong-patient detection at the point of reading.
- Comparison is two cards, never one. Mitigates: a prior result being read as a current one.
- No fixed heights on clinical content. Mitigates: a value clipped out of view with no indication anything is missing.
- One nesting level. Mitigates: structural depth that cannot be held under interruption, and unresolvable landmark nesting for assistive technology.
- Interactive cards contain no other controls. Mitigates: mis-activation and ambiguous targets, particularly gloved.
- Border rather than shadow. Mitigates: elevation losing its meaning as a signal of transience where that matters.
Implementation
$ npx shadcn@latest add https://md.notjustany.tech/r/card.json<Card variant="default">
<CardHeader>
<CardTitle as="h3">High-sensitivity troponin I</CardTitle>
<StatusChip status="urgent" alarmRef={alarm.id}>Rising</StatusChip>
</CardHeader>
<CardBody>
<Measurement value={47} unit="ng/L" reference="< 34 ng/L" />
</CardBody>
// Required for any card holding clinical data. Rendering CardBody with
// clinical content and no CardProvenance fails lint.
<CardProvenance
subjectId="51330264"
observedAt="2026-08-13T14:41:00Z"
source="Central lab"
/>
</Card>| Prop | Type | Default | Notes |
|---|---|---|---|
variant | default | interactive | flush |
default |
interactive throws if any focusable descendant is present. |
as (title) | h2 | h3 | h4 | h3 |
Set to match the surrounding heading structure. Never skipped. |
subjectId | string | — | Required on clinical cards, via CardProvenance. |
observedAt · source | string | — | Required alongside subjectId. |
maxHeight | number | — | Ignored for clinical content; warns in development. |
Related
- Status chip — the header's state label.
- Alert Banner — the inline variant inside a card.
- Data grid — when the content is a list, not a subject.
- Patient header — the identity a card's provenance must agree with.