Contributing
Changes to a system that renders clinical information are changes to a risk control, whether or not anyone calls them that. This page says what a proposal has to contain, who has to agree, and which changes are not accepted at all.
The standard a change is held to
Every rule in this system exists because something can go wrong without it. So a proposal is not assessed on whether it is nicer, more modern or more consistent with a fashion. It is assessed on one question:
What can a clinician now do, misread, or fail to notice, that they could not before? A proposal that cannot answer this is not ready. An answer of "nothing" is acceptable and common — it just has to be stated rather than assumed.
The corollary matters as much. A rule that forces clinicians into a workaround is a worse control than no rule, because it trains people to route around the interface. If you are here because a rule blocked real work, that is one of the most valuable things you can report.
What a proposal contains
| Section | What it has to say |
|---|---|
| The use situation | Who, doing what, under what conditions. In the terms of Usability & context of use: specified users, goals, context. Not a persona — a situation. |
| The failure today | What goes wrong now, and how you know. An observation beats an opinion; a near-miss beats a preference. |
| The change | The smallest version of it. Large proposals are almost always several small ones that should be argued separately. |
| New failure modes | What the change makes possible that was not possible before, including for users of assistive technology and in degraded network or data states. |
| Standards touched | Whether it affects alarm priority (IEC 60601-1-8), contrast or interaction (WCAG 2.2), or a stated risk control on a component page. |
| Do's and don'ts | At least one pair, authored with the change. If you cannot write the "don't", the rule is not yet clear enough to enforce. |
Three classes of change
| Class | Examples | Review |
|---|---|---|
| Editorial | Wording, examples, a clearer explanation of an existing rule, a new do/don't pair that restates something already true. | One reviewer. Merged when the prose is right. |
| Behavioural | A new component, a new state, a changed keyboard model, a new open token, a relaxed or tightened rule. | Two reviewers, one of whom must have clinical or human-factors background. Requires the full proposal above. |
| Governed | Anything touching --alarm-*, --input,
--ring, --destructive, alarm priority mapping, the filter
escape rule, or a stated risk control. |
Two reviewers plus a written risk assessment recorded in
tokens.json or the component's safety notes. Never merged the same day
it is opened. |
A governed change is a change to a controlled characteristic. It carries a
rationale that a manufacturer's risk file can cite, and the CI report from the
change is retained as evidence. "It looked better" is not a rationale; neither is "the brand
guidelines say so". See Tokens &
governance.
Reporting an unsafe behaviour
This is the highest-priority class of report and it skips the normal proposal format. Include:
- The component and page, and the version you are on.
- What a clinician would conclude from what is on screen, and what is actually true.
- Whether it is reachable in normal use, or only in a degraded state.
- A screenshot or reproduction with fabricated data only — never real patient data, never a real MRN, never a screenshot of a live system.
If you are a manufacturer and the behaviour is reachable in a product you have placed on the market, your own vigilance and post-market surveillance obligations apply independently of anything reported here, and on their own timelines. Reporting it here is not a substitute for them.
Changes that are not accepted
- Alarm hues re-themed for brand. The IEC 60601-1-8 hues are the point; a brand-adjacent red is a different signal to a clinician trained on every other device on the ward.
- Bulk acknowledgement, in any form. Not as a toolbar action, not as a keyboard shortcut, not behind a setting. See Acknowledge & escalate.
- Alarms or active findings behind a collapse, a hover, or a filter. Three separate rules with one shared reason: a clinician must not have to ask to be told.
- Capped counts, approximate totals, or a list without its denominator.
- Colour as the sole carrier of clinical meaning, in any component.
- Iconography as a semantic layer. This system deliberately has no icon set; meaning is carried in text. Adding an icon vocabulary would be a large new source of ambiguity for a small gain in density.
- Animation on alarm or value changes. See Motion, and WCAG 2.2 SC 2.3.1.
- A configuration flag that disables a stated risk control. If a control can be switched off per deployment, it is not a control.
- A quality gate with an operator override or a per-site threshold. The pressure to loosen a capture gate is a throughput pressure, and resisting it is the entire reason the gate exists. See Capture & quality gate.
- A negative result hedged with a quality caveat. "No disease detected, image quality limited" is read and repeated as its first four words.
- An autonomously issued result with no stated follow-up interval, or one whose follow-up depends on a person remembering to create it. See Autonomous result.
- Concealing that no human reviewed a result. Recipients assume human review by default; silence is a misrepresentation.
- Suppressing a high-priority or technical alarm, by any mechanism, under any rule. A signal meaning "this patient is not being monitored" is the last thing that may be quietened. See Suppression.
- Suppression that cannot be recovered from the clinical surface. If retrieval needs an administrator or a second system, it was not suppression — it was data loss.
- A clinical rule that can be saved without being previewed against real data. Configuration reviewed only as parameters is configuration nobody has understood.
- A configuration change that is not announced where its effects land. A ward that changes behaviour with no explanation is indistinguishable from one that broke.
- A triage device whose output is visible during the read, or which pre-populates a report. That is a detection aid operating on prioritisation evidence. See Reprioritisation.
- A parallel "AI findings" list beside the real worklist. Two incomplete queues competing for attention, one of which decays into being unchecked.
- Overwriting a reader's pre-assistance impression with their revised one. It makes the effect of the assistance permanently unmeasurable.
- Blocking deviation from a reading paradigm, or demanding a written justification. Both move the deviation out of the product, which loses the record rather than the behaviour.
- An auto-fitted y-axis on a clinical chart, a dual-axis chart, or a line drawn across a gap or a method change. See Data visualisation.
- A change smaller than the measurement’s own variability presented as a change. Noise rendered as progression generates real investigations.
- A “seen” state that closes a loop. An item is closed with a recorded reason, or open with a named owner and a due date. See Pending work.
- Closing a follow-up because the patient did not attend. Non-attendance is the strongest signal the loop is still open.
- Re-scoring an issued result in place under a new model version. It destroys the record of what was known when a decision was made.
- A pre-filled, pre-selected or single-gesture therapy-affecting value. Pre-filling converts judgement into confirmation reflex. See Therapy recommendation.
- A dismissible warning in place of a safety bound. Refuse the value; a limit that can be waved through is not a limit.
- Holding the last value, or interpolating, across a gap in a live stream. A frozen number is indistinguishable from a stable patient.
- Letting a remote follower silence an alarm, dose, or change a setting. They are acting on delayed data about a body they cannot see.
- Monitoring the subject cannot see, enumerate, or end. Followers, their scope and their last access are visible to the person being watched.
- Shipping a regulatory symbol as verified when it has not been checked against ISO 15223-1, distorting the CE mark, or recolouring any symbol for brand or dark mode. The system provides renderings; confirming them against the licensed standard is the manufacturer's step and it is not optional. See Device identification panel.
- A symbol with no published source, or a non-harmonised symbol presented as harmonised. Every glyph traces to ISO 15223-1 or to recognised industry guidance, and the page states which. See symbols outside the core set.
- A version string maintained by hand. It must be injected at build time, or the panel is making a false statement about which software is running.
- A truncated or abbreviated UDI, or UDI-DI and Basic UDI-DI shown as one field. Their only use is being transcribed exactly.
- A clinical output stored without the version that produced it, or a migration that rewrites historical version stamps.
- Paraphrasing the intended purpose in the UI. It is reproduced verbatim from the technical documentation or not shown at all.
These are not permanent in principle — they are permanent until someone brings evidence, not a preference. Two of them are narrower than they were because someone did.
Do's and don'ts
"On a night shift, a nurse acknowledging from the worklist twice acted on the wrong row because the list re-sorted between look and click. Observed twice in two weeks."
A use situation, a failure, and evidence. This is a proposal a reviewer can act on within an hour.
"The worklist feels cluttered. Suggest we simplify the rows."
No user, no situation, no failure. There is nothing here to agree or disagree with, and nothing to verify afterwards.
Propose the smallest change that addresses the failure, and say what it makes newly possible.
"This lets a clinician dismiss the banner without reading the provenance line" is the sentence that gets a proposal reviewed properly.
Bundle a component rewrite, a token change and a documentation restructure into one proposal.
A governed change buried in a large diff gets the review a small editorial change deserves, which is how controls quietly disappear.
Report a rule that forced you into a workaround, with the workaround described.
A rule people route around is producing use errors somewhere else. The workaround is the diagnosis.
Fork the component locally, remove the rule, and carry the patch forward silently.
Your product now differs from its documentation in a way no reviewer of either will notice.
Use fabricated data in every example, screenshot and reproduction.
Every example in this system is fictional for the same reason. There is no version of a real MRN in an issue tracker that is acceptable.
Attach a screenshot from a live clinical system, "anonymised" by cropping.
Cropping is not anonymisation. Timestamps, bed numbers and value combinations re-identify.
Before you open it
npm run checkpasses — token governance and the documentation checks. A failing gate on a proposal moves the conversation to the gate instead of the idea.- Keyboard path walked end to end, including focus placement after every state change.
- Read at 320 px and at 200% zoom (WCAG 2.2 SC 1.4.10).
- Read in greyscale. If a state disappears, colour was doing work text should have been doing.
- Read in dark theme. Governed tokens do not change between themes, so anything that only works in light has borrowed something it should not have.
- Degraded states drawn — loading, partial, stale, unavailable. Most proposals only draw the happy path, and most clinical risk is in the other four.
- Outcomes of use and Clinical safety notes written for any new component page, in the same terms as the existing ones.
Related
- Using the system — install, theming, and what stays your responsibility.
- Status & limitations — coverage and known gaps.
- Validation roadmap — what validation would and would not mean here.
- Tokens & governance — the five checks a change has to survive.
- Usability & context of use — the vocabulary a proposal is written in.