Every component, and the hazard it mitigates.
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 — 68 pages, written and complete. Not clinically validated.
The regulation says the interface must be safe. This says what that looks like on screen.
The navigator and the courses here answer what does the regulation say? Regulatory Sidekick answers what do I actually do on Monday morning? The design system answers the one left over — what does it look like when a clinician reads it at 3am, on a ward display, mid-interruption?
Most design systems answer only 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. All 68 pages carry all three.
What the whole system is held to.
Every page then carries its own three principles for its own domain. These are the three that never move.
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.
Not a swatch sheet. A design control.
Every example below is live markup rendered in this page, using the system's own values. Nothing here is a screenshot.
Seven annotated parts, each tied to what it prevents. The provenance line is not optional decoration — it is the control against acting on a stale or out-of-scope model output. All patient data shown on this page is fabricated.
Software has no packaging. The label still has to go somewhere.
A physical device carries its identity on the box. MDR Annex VI Part C §6.5.4 requires software to display the UDI on an easily accessible screen in readily readable form — an about screen, a splash screen, a menu. IVDR Annex VI Part C says the same.
That turns a labelling obligation into a user-interface obligation, and it is why this is a component rather than a paragraph in someone's technical file.
“It is also the screen most likely to be built last, by whoever had capacity, and never reviewed — which is a poor fate for the one screen a vigilance report is written from.”
- Version
- 4.3.1 (build 2026.08.14-a91f2c)
- Basic UDI-DI
- 5060XXXXXXXXXAL7Q
- UDI-DI
- (01)05060XXXXXXXXX
- UDI-PI
- (8012)4.3.1
- Class & route
- Class IIa under MDR Annex VIII Rule 11 · Annex IX conformity assessment
Symbols are drawn from ISO 15223-1's published descriptions, not traced from the standard — the system says so on the page, and is built so replacing the artwork is a one-file change.
An alarm scale that shadcn has no concept of.
Stock shadcn ships --destructive. A destructive action is not an alarm, and conflating the two is how a delete button ends up wearing the colour reserved for a life-threatening condition.
These five are byte-identical in light and dark, and CI fails the build if they ever drift apart — because the standard's hues are absolute, not a theme preference.
Two gates, fifteen checks, on every change.
Tokens are split in two. Open tokens are re-themable by a product or customer skin under normal design review. Governed tokens are controlled characteristics: changing a value is a design change with safety consequence, requiring risk assessment under ISO 14971, usability re-validation under IEC 62366-1, and a documented rationale.
That distinction is enforced by a script, not by a convention nobody reads. Both gates have been negative-tested — violations of every class they claim to detect were injected and confirmed to fail the build.
PASS contrast 40 colour pairs meet their documented minimum
PASS sync njt-ds.css matches tokens.json
PASS redefinition 69 files scanned, no governed token redefined
PASS links 887 internal links and anchors resolve
PASS skeleton 68 pages carry their required sections
note 68 pages · 216 do/don't pairs
The gate is a design control, not a style check. It runs on every change that can reach a released build, and its result is evidence for the technical file — which is why the report is retained as a build artefact rather than printed and forgotten.
It tells you which parts are not proven.
Every assertion in the system falls into one of five classes. They are written in the same tone and carry very different weight — so the class is stated, every time.
| Class | Means | What you must do |
|---|---|---|
| Computed | Calculated and machine-checked. Reproducible on demand. | Nothing — run the gates and reproduce it. |
| Standard | Traceable to a published standard. | Verify against the current edition. This paraphrases; it does not substitute. |
| Convention | Widely used ergonomics and industry figures, reproduced without primary sourcing. | Substantiate for your own device. Starting points, not validated thresholds. |
| Reasoned | Design rationale reached by argument. Defensible, unevidenced. | Treat as a hypothesis to test, and as an input to your hazard analysis. |
| Fiction | Invented for illustration — the reference applications, every patient name, MRN, timing and waveform. | Never reuse as clinical content. |
Every Clinical safety notes entry — every “Mitigates: wrong-patient selection” — is a Reasoned claim. It is a design rationale explaining why a behaviour exists. It is not the output of a hazard analysis, has no severity or probability attached, and does not discharge any obligation under ISO 14971. Use them as candidate hazards and candidate controls, to feed your own risk process.
29 studies, each naming its own falsifier.
Every Reasoned claim has a study design attached and a stated result that would prove it wrong — for instance, that model annotation being off by default reduces anchoring, falsified by finding no difference in agreement with truth. Current status of the roadmap: open — no studies completed. That is published as a headline rather than buried, because a roadmap nobody can check is a marketing document.
43 changes it will not accept.
- Bulk acknowledgement, in any form. Not as a toolbar action, not as a keyboard shortcut, not behind a setting.
- A configuration flag that disables a stated risk control. If a control can be switched off per deployment, it is not a control.
- A negative result hedged with a quality caveat. “No disease detected, image quality limited” is read and repeated as its first four words.
Source you own, not a dependency you can't inspect.
Components are Radix primitives styled with Tailwind and distributed as source you copy into your own repository. 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 package you cannot read at review time. Nothing is added to your dependency tree.
Brand on standard names
Brand values bound to --primary, --muted, --radius — so the wider shadcn ecosystem's blocks and examples still work unchanged.
The alarm extension
An --alarm-* group for IEC 60601-1-8 priorities, machine-checked for parity across both themes.
Invariants in the variants
ARIA roles derived from priority; hazardous prop combinations rejected at the component boundary rather than documented and hoped for.
All of it is written. All of it is public.
68 pages — 15 foundations, 27 components, 20 clinical patterns, 216 worked do-and-don't pairs. Nothing is scoped and pending, and the navigation is the sitemap: if it is listed, it is written. Start with Status & limitations, which is the more useful of the two front doors.
Teams building Software as a Medical Device who need a UI layer they can cite from a risk file — and manufacturers who would otherwise be reverse-engineering their own interface rationale in the week before an audit.
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 the MDR or IVDR remain yours — as they would with any design input.