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.
What the component enforces, and what it only asks for
Presentational throughout. The parts hold structure and semantics; everything about content is yours.
| Rule | Held by | How |
|---|---|---|
| The title is a real heading | The component | CardTitle renders a heading element, so a card is reachable by heading navigation rather than being a div with large text.Asserted: Card: the title is a real heading, not large text in a div |
| A whole-card link is a real anchor | The component | CardLink is an <a href>, so it opens in a new tab, is copyable and works before the bundle loads.Asserted: CardLink: a whole-card target is a real anchor |
| Clinical content carries its provenance | You | The footer is children. Nothing checks that a card holding a result also states where and when it came from. |
| A card is not made into a button | You | Nothing stops a click handler on the container, which makes a target inside a target. |
| The card is about one subject | You | Two patients in one card is expressible and is the failure this page warns about. |
A rule stated on a component page reads as a rule the component keeps. 2 of these 5 are; 3 are obligations this page was quietly handing to the reader. A card is a box. Its rules are about what you put in the box, and the box cannot check them.
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). Which of these the component keeps and which are yours is stated in the guarantees table; a control the component does not keep is one your risk file must show you keep.
- One subject, one source, one time per card. (you) Mitigates: data from another encounter or another patient being read as current and related.
- Provenance required on clinical cards. (you) Mitigates: an unfalsifiable grouping claim; supports wrong-patient detection at the point of reading.
- Comparison is two cards, never one. (you) Mitigates: a prior result being read as a current one.
- No fixed heights on clinical content. (you) Mitigates: a value clipped out of view with no indication anything is missing.
- One nesting level. (you) Mitigates: structural depth that cannot be held under interruption, and unresolvable landmark nesting for assistive technology.
- Interactive cards contain no other controls. (you) Mitigates: mis-activation and ambiguous targets, particularly gloved.
- Border rather than shadow. (the component) 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>
<CardHeader>
<CardTitle>High-sensitivity troponin I</CardTitle>
<StatusChip tone="urgent">Rising</StatusChip>
</CardHeader>
<CardBody>
<KeyValue
label="Result"
value={{ kind: "value", value: "47", unit: "ng/L" }}
/>
</CardBody>
<CardFooter>
<p>Central lab · 14:41 · MRN 51 330 264</p>
</CardFooter>
</Card>
// Provenance is content in the footer, not a component that enforces itself.
// Nothing fails a lint if it is missing; see the rules above.What the component is: six parts, each taking the attributes of the element it renders plus
the one prop listed. This table used to list variant, as,
subjectId, observedAt and maxHeight — props no part of
Card has, or ever had. Provenance, the subject and the time are content you put in the card; the
rules for them are in the guarantees table.
| Part | Renders | Takes | Notes |
|---|---|---|---|
Card | <div> | div attributes | The bordered container. Not interactive; for a whole-card target use CardLink. |
CardHeader | <div> | div attributes | The title row, with a rule beneath it. |
CardTitle | <h2>–<h6> | level, default 3 |
A real heading, at the level the surrounding outline needs. |
CardBody | <div> | div attributes | The content. |
CardFooter | <div> | div attributes | Provenance and time, set small and muted, above a rule. |
CardLink | <a> | anchor attributes | A whole-card link. It must contain no other control. |
When the whole card is the target
CardLink ships with this install command and was described on no page at all.
It is a card that is itself a link, for the case where the entire surface navigates.
- One destination, and nothing else interactive inside it. A link containing a button is a target inside a target: the reader cannot tell which one they hit, and neither can the keyboard.
- The accessible name is the card's own heading, not “read more”. A screen-reader user listing the links on a worklist hears the patients, not twelve identical phrases.
- It is a real
<a href>, so it opens in a new tab, is copyable, and works before the bundle loads. A div with a click handler is none of those. - Never for an action. A card that submits, acknowledges or deletes is a Button — links go somewhere, buttons do something.
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.