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:

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

Three classes of change

Reporting an unsafe behaviour

This is the highest-priority class of report and it skips the normal proposal format. Include:

1. The component and page, and the version you are on.
2. What a clinician would conclude from what is on screen, and what is actually true.
3. Whether it is reachable in normal use, or only in a degraded state.
4. 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.
• A generic Popover. A container defined by nothing except being transient, so every rule it would need depends on what is put inside it. The rules live on Tooltip, Menu and Dialog instead — see why there is no Popover.
• 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. If you add one anyway, it is not a styling exercise: a symbol that carries meaning on a medical device owes comprehension testing — ISO 15223-1 sets a threshold for symbols used without accompanying text, and IEC 62366-1 treats a misread symbol as a use error like any other. Budget for the study, and until it exists, keep the text.
• 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.
• A saliency, heat or attention overlay presented as an explanation of a finding. It shows where a model responded, not why it concluded, and the two are not related in any way a reader can act on. See Attribution.
• A continuous intensity or colour ramp on an attribution overlay. It reads as a measured surface over anatomy — a quantity the model does not produce.
• A finding expressible only as an overlay. If it cannot be stated in words with a location, there is no finding; there is a picture.
• A model-derived measurement compared against a threshold established by a different measurement method, or a delta computed across a method or model-version change. See Derived measurement.
• A derived measurement shown without its method, or one that changes as a reader drags a boundary without that adjustment being recorded.
• Machine-composed text credited to a human author. The committing clinician is recorded as having accepted it. See Authorship & the record.
• A composed-text disclosure that lives only in the chrome. If selecting the text and copying it removes the disclosure, there is no disclosure.
• Overwriting the composed version on commit. Silent correction destroys the only evidence that the model needs correcting.
• An unbindable assertion shown with a hedge instead of withheld. A footnote does not survive contact with fluent prose. See Composed output.
• A composed artefact with no statement of what it omitted, or one claiming complete coverage — relevance is a clinical judgement the composer was not authorised to exercise.
• An aggregate reliability score on a composed artefact, and token-by-token streaming — the first has no calibrated referent, the second is read before the bindings that make it checkable exist.
• A governed string produced by the system it governs, or paraphrased into composed prose to read more naturally. See Voice & tone.
• Any gesture that acknowledges, silences or dismisses an alarm. A swipe is the motion a sleeve and a cleaning cloth make. See Touch & gestures.
• A gesture as the only route to a function, and any required path-based or multi-point gesture — SC 2.5.1.
• Actions that fire on touch-down, and swipe-to-delete or swipe-to-dismiss on any clinical item.
• A dragged value committed on release. A drag proposes; a targeted press commits.
• Anything with a consequence in a transient vehicle. A timer is a claim that missing the message costs nothing. See Messaging.
• A dialog with no branch in it. Information does not block; it goes in a banner and stays visible.
• Two live representations of one condition. The chip becomes the banner; it does not accompany it.
• A gap in a timeline left as empty space. Absence of record is not absence of event, and white space asserts the reassuring reading. See Clinical timeline.
• Entries plotted at recorded time while labelled as event time, or simultaneous entries stacked so that database order reads as clinical sequence.
• Compression that is selective by importance. Compress by time or not at all — a relevance rule deciding what a clinician sees is an unvalidated clinical judgement.
• An approximate time stored or exported as an exact one, or an unknown time defaulted to now, to admission, or to blank. See Date & time picker.
• An imprecise interval reported against a threshold as though exact. Where it straddles a decision boundary, say so rather than reporting an end or a midpoint.
• A split button whose menu holds a clinical or irreversible action, or whose default half is destructive. See Toolbar.
• A link that acts, or a button that navigates. Different keys, different browser affordances, different announcements.
• A prose link distinguished by colour alone, or link text that does not say where it goes.
• A relative date range shown without its absolute dates, or a preset that silently clamps to the retention period. See Date & time picker.
• A recovery route that is also the emergency access control, or a lockout screen that names no staffed route at the hour it appears. See Lockout & recovery.
• A credential expiring mid-session, or a forced password change presented between a decision and its record.
• A printed page without the patient's identity and its place in the set. A sheet that separates and cannot be identified gets filed against the wrong patient. See Printed output.
• A printout with no print time or staleness statement, or a printed extract that does not declare what it excluded.
• A draft marked only by watermark. It is the first thing a low-toner printer drops.
• Priority encoded in loudness rather than pulse structure, or a volume control that reaches zero. See Auditory alarms.
• A global quiet or night mode. Same objection as bulk acknowledgement: the control cannot tell which alarm it is silencing.
• Silence used as a state with meaning. A listener cannot distinguish a resolved condition from a failed speaker.
• A remote alarm that replaces the bedside signal, or one whose delivery is not confirmed. It fails by nothing happening.
• A private melodic alarm vocabulary. A category signal that means something different on the pump beside you is worse than none.
• A device in service that still looks like a device that is working. Stale clinical data on screen, or service state carried by a chip. See Commissioning & service mode.
• A calibration recorded without its as-found value, or one that fails and leaves the device in clinical use.
• Patient population, location or clock defaulted or inferred rather than chosen at commissioning.
• Shared or default service credentials. A commissioning record naming "Service" as the person has no accountability in it.
• Mixed node types in one accordion. A node that looks unlike its neighbours reads as a different kind of thing, and readers hunt for a meaning that is not there. See Accordion.
• Node metadata in varying slots or a caret that changes edge between nodes. The eye locates these by position before it reads them; moving them turns a scan into a search.
• A 32 px node anywhere a finger may reach. Compact density is a documented exception for deployments with no touch input at all, not a density setting.
• A required-field marker on an accordion node. Forms do not span sections here, and “required” is stated in words rather than punctuation.
• A skeleton standing where a clinical value will land. A grey bar promises a number the system may not be able to deliver, and its absence then reads as “no value”. See Skeleton.
• An animated skeleton. A shimmer performs activity, and movement is the alarm channel.
• An indicator shown for under half a second, or one with no stated bound. A flicker reads as a fault; an unbounded spinner is an unreported error.
• Reassurance in place of elapsed time. “This may take a moment” is a guess presented as information.
• Collapsed content that the browser cannot find. A hand-built accordion using plain hidden defeats Ctrl+F, so text that is present reads as absent. Use <details>, or hidden="until-found". See Accordion.
• <details name> for grouping. The platform offers mutually exclusive disclosure; this system forbids exclusive-open.
• A previous subject's value surviving a change of patient. Clear first, then load. Keeping stale data through a switch manufactures a wrong-patient error out of a loading optimisation. See Pending value.
• Stale data shown without its age, or an age given as a mood (“recently”) rather than a time.
• A wait past its bound with nothing outstanding named and no way to stop. The clinician leaves, and the sources that did answer are lost with them.
• A partial result rendered as though complete. The gap is stated and travels with the artefact.
• A badge counting the filtered subset without saying so. Exact about a number and wrong about which set it is a number for. See Badge.
• A count frozen by a failed refresh and still stated in the present tense, or a count whose age is unknowable where it drives a decision.
• A page number used as an address. Links resolve to the item; page 3 of a live worklist holds different patients tomorrow.
• Infinite scroll in place of a stated total. It removes the one thing the component exists to provide — knowing whether you have seen everything.
• A badge made clickable. The row is the control; a 24 px target sits below the floor beside the larger one it will be mistaken for.
• An icon-only navigation rail whose labels appear on hover. There is no icon set to carry the meaning and no hover on a cart. See Side navigation.
• Navigation that expands on hover. A delay and extra spacing treat the symptom; the layout still changes without anyone deciding.
• A truncated navigation or breadcrumb label. Labels wrap to two lines, or the panel is too narrow. Never an ellipsis with the full text on hover.
• A route change that does not move focus and announce. Focus left on a removed control, or reset to the body, is silent to a screen reader and invisible in mouse testing.
• A context menu on a navigation item. Undiscoverable, with no touch equivalent that does not compete with scroll.
• “Leave blank if unknown”, or any hint that assigns a meaning to an empty field. A blank records nothing about why it is blank — unasked, unknown, declined, awaited and lost in transfer all look alike. Originally scoped to dates; the argument is about blanks, not dates. See Date & time picker and Text field.
• Input assistance that chooses between readings. It may complete what the format implies; it may never correct an impossible value to a legal one or infer an ambiguous order.
• A field that reformats under the cursor. Formatting settles on blur; a value changing shape while it is typed cannot be checked while it is typed.
• A calendar as the only route to a date of birth, or a two-digit year anywhere. Both are ordinary and both are wrong on the most frequently entered date in clinical software.
• An open interval rendered as an empty end field. Ongoing and end-not-recorded are opposite situations; a duration derived from either states its openness.
• A truncated clinical cell. A clipped identifier is a wrong-patient hazard and a clipped value is a number with unknown digits missing; the tooltip carrying the full text does not exist on a cart. See Data grid.
• A virtualised grid without aria-rowcount. A screen reader counts the DOM, so a window of thirty rows out of three hundred announces as thirty.
• Hover-revealed row actions, drag-only reordering, or double-click as a route to anything. Each is imperceptible to some readers and each works perfectly for the person who built it.
• A form control with a clinical envelope inside a grid row. There is no room for units, range or confirmation, and eleven identical rows around it.
• Rows reordered by hand in a clinical queue. Row order is a clinical statement, not a reader preference.
• Filter criteria whose combining rule is left to be inferred. A tag row and a count are equally consistent with matching all of them and matching any of them. See Filter.
• An inherited filtered view that does not say so on arrival. A shared link or a pre-filtered default gives a reader a narrowed set they never chose.
• A truncated filter tag, an icon-only filter control, or tags that reorder by dragging.
• An empty filter result rendered as a validation error. The clinician did nothing wrong, and now believes they did.
• A bare “Select all” beside a filtered list. It names neither set, and the two differ by however many rows the filter is hiding. See List.
• A selection that outlives the visible set without saying so. Three selected, one shown, and an action that quietly takes all three.
• Bulk acknowledge, sign, dismiss, mark-reviewed or delete via multi-select. Each records a judgement about an individual finding; doing it to a set records something that did not happen.
• A locked list item whose reason is only in a tooltip. An option that cannot be chosen for an unstated reason reads as a fault.
• A technical alarm condition rendered as a physiological one. The reader cannot tell “the patient is deteriorating” from “we have stopped being able to see the patient”. See Alert banner.
• An alarm hue on a message about the software. A failed export is not an alarm condition however severe it feels; the boundary is the patient, not the severity.
• A truncated alarm headline. It is the one string on screen that must survive intact, and the tooltip carrying the rest does not exist on a cart.
• An alarm headline that rewrites itself as the condition evolves. The description updates; the headline is what gets quoted on the phone.
• A form control inside a menu. A menu closes on outside click, Escape and focus loss, all of which silently discard half-entered input. See Menu.
• A menu that covers the row it acts on, or that names no subject when it acts on one.
• Escape that closes a transient surface without returning focus to its trigger. It leaves a keyboard user at the top of the document.
• Secondary text describing what a menu item does. It carries the reason an item is unavailable, or a shortcut; a description means the label failed.
• A tooltip carrying alternative text for an image. Assistive technology reads alt; a hover bubble is not a substitute, and the substitution removes the description from the reader who most needs it. See Tooltip.
• A chart whose values are only readable on hover. A trend with a shape and no numbers cannot be read on a cart or quoted on the phone.
• A definition a reader needs in order to act, placed in a tooltip. An abbreviation expanded as a convenience is fine; anything load-bearing goes in the text on first use.
• A confirmation that does not show the data its question rests on. “Confirm dose?” cannot be checked; the record may have moved since. See Dialog.
• A dialog whose answer depends on content that must be scrolled. The confirm button is reachable while the content is unread, and gating it on scroll is also prohibited.
• “Don't show this again” on a clinical confirmation. It silences a safety prompt permanently, in the moment the clinician is most rushed, for everyone who uses that workstation afterwards.
• A dialog opened from within a dialog, or tabs inside one.
• Confusable options adjacent in a list, or distinguished by name alone. Alphabetical order actively creates the hazard. See Select.
• Type-ahead selection in a clinical vocabulary. Three keystrokes landing on whichever confusable name sorts first is the look-alike failure, automated.
• A hyperlink among a dropdown's options, or multiple columns inside one. One is a category error; the other is a data grid in a transient surface.
• Options that change while the menu is open. A list re-populating under a pointer already moving is how the wrong option is chosen.
• 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

Before you open it

• npm run check passes — 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.