Design system · v0.1 draft

A design system for clinical software

Components, tokens and reasoned guidance for building Software as a Medical Device — built on shadcn/ui, branded to NotJustAnyMed.Tech, and written against the standards a notified body will actually ask about.

Draft · v0.1 shadcn/ui Tailwind IEC 60601-1-8 IEC 62366-1 WCAG 2.2 AA Framework · ISO 9241-11

What this is

Most design systems answer "what should this look like." A system for regulated clinical software has to answer two more questions: what could go wrong if this is misread, and how do we show that we thought about it. Every page here carries all three.

Concretely, that means each component ships with its usual anatomy and variants, and also with a Clinical safety notes section pairing each behaviour to the hazard it mitigates — so the documentation can be referenced directly from a risk file rather than reverse-engineered at audit time.

Where this sits in your file

Structurally informed by conventions proven at scale in enterprise clinical design systems, and aligned to IEC 60601-1-8 alarm priorities and WCAG 2.2 AA — with all contrast ratios computed and machine-verified in CI.

A design system is not a medical device and cannot itself be clinically validated. If you build with it, usability validation under IEC 62366-1 and clinical evaluation under MDR or IVDR remain yours — as they would with any design input. This system is built to make that work shorter and better evidenced, not to stand in for it. See Status & limitations, and the validation roadmap for what would be tested and what would prove it wrong.

Reference applications

Worked examples belong to named, fictional medical devices. AcuteLine is the primary one: it ingests 12-lead and continuous ECG plus high-sensitivity troponin results and flags patients with suspected acute coronary syndrome (ACS) for clinician review. It is decision support — it never diagnoses, never triggers therapy, and every output is confirmed by a qualified clinician.

Others exist because one example teaches its own assumptions. AcuteLine assumes a clinician who can verify the output, software that waits for a human, a single episode, and harm that is fast and visible. Break any of those — an autonomous screening result, a suppressed alarm, a finding due in eight months, a patient dosing at home — and the interface changes shape. See Reference applications. All screens, copy and patient data in these docs are fabricated.

System principles

Three commitments the whole system is held to. Individual pages then carry their own three principles for their own domain.

Four outcomes, not one

This system is structured around human-centred quality: usability, accessibility, user experience and avoidance of harm from use. Safety is the outcome medical software remembers; the other three are the ones it forgets. Each page carries both an Outcomes of use section and Clinical safety notes for that reason. See Usability & context of use.

Legible under pressure

Every decision assumes an interrupted reader, imperfect lighting, and a screen at arm's length or further. Comfort is the baseline; legibility is the requirement.

Honest about certainty

Algorithmic output always arrives with its provenance and its limits attached. The software detects; the clinician diagnoses. Nothing in the UI blurs that line.

Safe by construction

Where a combination is hazardous, the component refuses it rather than trusting each team to remember. Guidance that can be ignored is not a control.

Built on shadcn/ui

Components are hand-written, styled with Tailwind and distributed as source you copy into your own repository. They follow shadcn/ui’s token contract and its copy-in model — not its dependencies: there is no Radix, no cva and no clsx here, and no item in the registry declares a runtime dependency at all. For a regulated product that distribution model is the point: every line is auditable, diffable and version-pinned in your own SCM, rather than arriving through a dependency you cannot inspect at review time.

Three things are layered on top of stock shadcn:

Brand values bound to standard shadcn variable names — --primary, --muted, --radius behave exactly as any shadcn developer expects, so the ecosystem's blocks and examples still work.
An --alarm-* token group for IEC 60601-1-8 priorities, which stock shadcn has no concept of. --destructive is not an alarm.
Safety invariants compiled into the variants — ARIA roles derived from priority, hazardous prop combinations rejected at the component boundary.

Start here

Foundation

Usability & context of use

Specified users, goals and context — and how anyone would know the system worked.

Start here

Status & limitations

What is computed, what is convention, what is argument, and what is fiction.

Start here

Reference applications

The fictional devices behind every example, and the four axes on which they differ.

Start here

Validation roadmap

Thirty-nine reasoned claims, their study designs, and the result that would falsify each.

Foundation

Tokens

The shadcn contract, the alarm extension, and how a value travels from ramp to component.

Foundation

Colour

Brand ramps, the two themes, and why coral is banned inside a clinical product.

Foundation

Typography

Fraunces and Inter, the product type scale, and reading at clinical distance.

Component

Alert Banner

Priority-ranked messaging, IEC alarm levels, and the acknowledgement model.

Component

Button

Action hierarchy, touch targets, and destructive confirmation in a clinical workflow.

Pattern

Triage worklist

Ordering by consequence, why confidence is never the default sort, and proving liveness.

Pattern

Confidence disclosure

Showing how much to trust an output — and designing against automation bias.

Pattern

Patient header

The persistent identity band — the primary control against wrong-patient error.

Pattern

ECG review

The evidence screen, and why model annotation is off by default.

Pattern

Clinician override

Disagreeing with the software, the audit trail, and honest surveillance data.

Build status

The left-hand navigation is the sitemap, and every entry in it is written — nothing is scoped and pending. Where future work is planned it is announced in the Planned column below rather than as a dimmed nav entry. What "written" does not mean is covered on Status & limitations, and it is the more important page of the two.

Area	Written	Planned	Notes
Start	8	8	Overview, status, reference applications, roadmap, using, contributing.
Foundations	20	20	Complete. Includes AI transparency & human oversight, the EU AI Act anchor the imaging, generative and agentic patterns cite.
Components	42	42	Complete. This row used to record which pages merged several components. None do now. Four pages remain that document a set rather than a component — Navigation, Selection controls, Progress and Grid & layout — and each of those ships nothing of its own: they carry the comparison, and the components they compare have their own pages and their own install commands.
Clinical patterns	29	29	Grouped by design problem rather than by application, across seven reference applications. Includes what a spatial model output may claim and when a contour becomes a measurement; three more are scoped for output that is a paragraph rather than a score.
Do's and don'ts	374	—	Worked pairs across foundations, components and patterns.
Iconography	—	—	Deliberately out of scope. Meaning is carried in text throughout — see Contributing.