Healthcare user interfaces

A guide for teams building clinical software with Lily: clinical portals, results and reporting, prescribing and medicines administration, decision support and hospital dashboards.

Translations of this page are unreviewed machine drafts. The English page is the authoritative version.

What Lily does, and what it does not

Lily gives you display contracts: semantic markup, ARIA, keyboard behaviour and class hooks for the things clinical screens repeat. It does not give you clinical logic, clinical content or a regulatory claim.

What Lily provides, and what you provide
Lily providesYou provide
observation-view: a value, unit, flag in words, range, and missing statesThe value, the flag decision, the reference range
allergy-record-list and allergy-record-list-item: a status that is never blankThe allergy record and its terminology
medication-view: name, strength, form, route and frequency, none truncatedThe drug data, the tall man segments, the formatted strength
decision-support-card: the CDS Hooks card shapeThe rules, the suggestion actions, recording the outcome
early-warning-score-view: a score, band and escalation, displayedThe scoring system and its validated calculation
age-view and ageParts(): an age in units suited to itThe words for the units (Intl.DurationFormat or your own labels)
formatQuantity(): 5 mg, never 5.0 mg; 0.5 mg, never .5 mgThe number, the unit and the locale
The patient banner compositionEvery label and value, and who may see clinical information

Regulation. Software that computes a score, a centile, a dose or a drug interaction is usually a medical device. Lily computes none of these, on purpose. If your product is regulated, you own its usability engineering file (IEC 62366-1, the FDA's human factors guidance, EU MDR). Lily's tests, its self-assessed accessibility conformance report and its screen-reader matrix can be evidence in that file; none of them is a conformance claim, and the matrix has no results yet.

Alerts: interrupt only for what is critical

Alert fatigue is a safety problem: when every alert interrupts, people dismiss them all. AHRQ's guidance is to tier alerts by severity and make only the severe ones interruptive.

  • Information (indicator="info"): inline, beside the task, a decision-support card in the page.
  • Warning (indicator="warning"): visible without blocking, the same card, styled to stand out; no modal.
  • Critical (indicator="critical"): put the card inside an alert dialog, and offer overrideReasons so dismissing it asks for a reason.
  • A decision-support card is never a live region by itself. Announce a new critical card by moving focus into the dialog, not by aria-live.
  • Remove a card when the event it answered happens again, and record each outcome (accepted, or overridden with its reason).

Wrong-patient errors: identify, do not restrict

  • Show two identifiers wherever a patient's data appears: the name with the date of birth, and the national identifier with its view component (The Joint Commission, Quick Safety 45).
  • Use the patient banner on every screen that acts on one patient's record, and keep it visible.
  • Before an action on a record other than the one in the banner, confirm it with the name, date of birth and identifier.
  • An entry about someone other than the patient (a parent's history, a fetus, a donor) says whose it is first, in words: give the record items a subjectLabel ("Mother"), so a relative's diagnosis is never read as the patient's (openEHR PARTY_RELATED, FHIR FamilyMemberHistory).
  • Do not limit how many records a clinician may open: a randomised trial of 3,356 clinicians (JAMA, 2019) found that it did not reduce wrong-patient orders, and people work around it.
  • A menu of actions on one record names that record first, with subjectLabel on context-menu or dropdown-menu ("Ada Lovelace, blood pressure 3 Nov"): a non-interactive first part that is also the menu's accessible name.
  • Tier each action by what it does, and make the tier visible before it runs. Routine (view, print) runs at once. Documented says what it will write to the record ("Adds a note to the encounter"). Clinical (discontinue, cancel an order) asks a second time, in an alert-dialog whose confirming button is the verb ("Discontinue"), never "OK" or "Yes". Disclosive (break the glass, share outside the care team) asks for a reason first and records it.
  • When several records are open (tabs, windows, split panes), every tab's visible text and accessible name include the patient's name and a second identifier, the active panel repeats the banner, and no action applies to a patient other than its panel's.
  • Show the location records will be attributed to (the ward, clinic or facility chosen at sign-in) as text in the page header, and make changing it an explicit action.
  • Show the active visit, or "No active visit", in the banner. A form that needs a visit says so and offers to start one, rather than failing when it is saved.

The patient banner

The composition is documented with medical-banner, with a working page at /patient-banner in the SvelteKit example app:

  • two identifiers, and the age beside the date of birth;
  • allergies through an allergy list, so "no known allergies", "not recorded" and "unavailable" never look alike;
  • a missing value is words ("Not known"), never a question mark, a dash or an empty cell;
  • a deceased patient: data-deceased for the theme, and a visible line of text, never colour alone;
  • no field truncated, clipped or hidden at any width; it wraps.
  • patient flags ("Needs an interpreter", "Infection risk") are a labelled tag-group of words, never icons or colour alone, and stay visible when the banner wraps.

Results

  • One display for a result, whatever system it came from: the observation view.
  • The flag is words from your translation (flagLabel), with the FHIR interpretation code as data-interpretation for the theme.
  • Separate new results from earlier ones, and show a trend (a sparkline, or a line chart with its data table): clinicians look for a significant change, not only the range.
  • A result that was never recorded and one that is unavailable are different states, with different words.
  • Unknown is not normal. A result whose reference range is missing, still loading or unreadable has no interpretation and says so; observation-view never infers one, so a result with a range and no interpretation shows no flag.
  • An off-scale result is the instrument's limit with a comparator ("> 33.3 mmol/L": formatQuantity with ">") and your critical flag, never a bare number. An approximate value keeps its ≈ ("~").
  • Give further named ranges ("Critical: below 2.5") as ranges, each its own part.
  • A corrected or amended result keeps the value it replaced, in a <del>, with your words for when it changed (previousValue, previousLabel), so a clinician who read the old value knows it changed.
  • An interval reading says its width and function ("Mean, 24 hours"), and a reading's state and method ("Sitting, large cuff") are visible text beside it, never only a tooltip (openEHR INTERVAL_EVENT, state, protocol).
  • A trend needs comparable points: draw no line below your minimum, break the line where the method or assay changed, and say direction and meaning in words ("falling, improving").
  • Vitals entered in one unit system may show the other beside them as your text ("70 kg (154 lb)"); Lily converts nothing, so state your rounding. Enter a quantity with quantity-input-div, whose number takes each unit's limits.
  • A growth chart is a line-chart with your centile lines as series, the child's points and its data table of age and value; Lily computes no centile and ships no growth reference.

Medicines

  • Generic names in lower case, except tall man letters from the FDA and ISMP lists or your country's (Australia and Canada publish their own). Mark them in nameSegments; Lily never guesses them.
  • Write the strength with formatQuantity: no trailing zero, a leading zero, a no-break space before the unit.
  • Keep a result's comparator: formatQuantity(5, "mmol/L", locale, "<") writes "<5 mmol/L". FHIR's Quantity.comparator is written <, ≤, ≥ or >; dropping it turns "less than 5" into "5".
  • Write mL, never cc, and avoid every abbreviation on ISMP's error-prone list.
  • Never truncate a medicine's name or dose.

Dates and times

  • Write the month as text so a date cannot be read two ways (Intl.DateTimeFormat with month: "short").
  • Choose the clock on purpose: pass hourCycle explicitly. The NHS asks for the 24-hour clock; that is a UK rule, not a worldwide one, so Lily never picks it for you.
  • Ages follow the Common User Interface bands through ageParts(); a service with another convention passes its own words.
  • A date known only to the month or year stays that way: ask for it with date-field precision="month" or "year", store 2019-03 or 2019, and write it with formatPartialDate(). Never invent a day.
  • A length of time is duration-view, a <time datetime="P3DT4H"> holding your words, from durationParts() and Intl.DurationFormat.

Dashboards

  • A ward board or command-centre screen updates often. Never announce each change: keep one polite summary region ("3 beds free, 2 discharges due") and let people read the board.
  • Every state on a board (bed clean, occupied, blocked) is text or a data-* state with words, never colour alone.
  • Nothing blinks (WCAG 2.2.2, 2.3.1), and a board that updates on a timer has a pause control or updates only when asked; updates never move focus. An overdue entry says so in words ("Waiting over 20 minutes") with data-overdue.
  • A count or rate shows its denominator ("12 of 68") and links to the list behind it.
  • A list or timeline says what it is a view of: what it shows, its order and window, what is hidden and why, and which sources did not answer. An empty list from a source that did not answer is not proof that nothing exists.
  • A reminder list is a record-list whose items carry a due date (review-date) and a due state in words, with data-due; the rule that produced it is yours.

Forms

  • A question answered "yes", "no" or "not asked" is a radio-group of three answers, none chosen at first, never a checkbox: a checkbox cannot tell "denied" from "never asked". A review of systems is one fieldset per body system, and an "all others absent" button sets only the unanswered ones.
  • A question with a list of answers (medicines, addresses) is a repeatable-fieldset: an item is added or removed, focus follows, and each remove button is named for its item.
  • A number with a decimal comma: show it with Intl.NumberFormat and, where type="number" does not accept the comma, take it in a text field with inputmode="decimal" and parse it in your code. Never change a value the person typed, even to clamp it to a range: an out-of-range value is an error they can see.
  • A long list that renders only part of its options at a time sets aria-setsize and aria-posinset on each option, and remembers that find-in-page cannot see the rest.

Records, notes and their provenance

  • Say what a list or a grid is a view of, before its rows: its window and order, what it leaves out and why, and which sources did not answer ("Last 12 months, newest first. The GP record did not answer."). Give record-list and timeline-list a coverageLabel, and the data-grid helper its coverageLabel. An empty list from a source that did not answer says so in words, so it is never read as "nothing recorded".
  • Say where a record came from and whether it is final with record-provenance-view: signed, awaiting a signature, amended, saved on this device and not yet sent. An unsigned draft must never look signed.
  • An entry about someone else (a parent, a fetus, a donor) says whose it is first, with the record items' subjectLabel.
  • A withheld entry stays in the list with your words ("Restricted: not available to you"), and an entry made in error stays struck through with "Entered in error": give record-list-item or timeline-list-item an entryState and an entryStateLabel. Never remove either silently, since a gap is read as "nothing happened".
  • In a clinical note, mark each passage's source (typed, dictated, template, copied forward, generated) with data-source and visible words, so copied or generated text is never taken for today's examination.
  • A section that cannot load is unavailable in your words, with a retry button; a technical code, if shown at all, sits behind a disclosure. A failure caused by a person's action is announced, with the value the record now holds; a failure on page load is not.
  • An order's history is a timeline-list, one item per step (planned, scheduled, active, suspended, completed, cancelled) with its time and reason, and the current state also on the item.

From FHIR to Lily

Lily does not read FHIR resources; your code maps them to Lily's props. These tables map the HL7 FHIR International Patient Summary (IPS 2.0.1, FHIR R4). The code mapping is a suggestion: your clinical safety review decides it, and the words for every state are your own.

IPS sections and the Lily components for them
IPS sectionLily
Allergies and intolerances (48765-2)allergy-record-list and its items
Medication summary (10160-0)medication-record-list, each item holding a medication-view
Problem list (11450-4)problem-record-list and its items
Immunizations (11369-6)immunization-record-list and its items
Results (30954-2)observation-view, in a data table or summary list
History of procedures (47519-4)procedure-record-list and its items
Medical devices (46264-8)device-record-list and its items
Alerts (104605-1)Warning text or an alert, never behind a collapsed control
Any other sectionrecord-list and its items
A required section the document leaves outThe section's list with status="omitted"
FHIR codes and the Lily values for them
FHIRLily
emptyReason nilknownThe list's status="none-known"
emptyReason notasked, notstartedstatus="not-recorded"
emptyReason unavailable, withheld, closedstatus="unavailable", with words that say which
The IPS codes no-known-allergies, no-known-medications and the likestatus="none-known"
The IPS codes no-allergy-info, no-medication-info and the likestatus="not-recorded"
AllergyIntolerance.criticalitycriticality, apart from a reaction's severity
clinicalStatus, verificationStatusThe same props on the allergy and problem items, with the same codes
MedicationStatement.statusThe medication item's status
Dosage.textmedication-view dosageText
Observation.statusobservation-view status, with the same codes
Observation.dataAbsentReason maskedstatus="masked"
dataAbsentReason not-applicablestatus="not-applicable" (also on the record lists)
Quantity.comparatorformatQuantity(value, unit, locale, comparator)

Map an entered-in-error record to its entered-in-error status, with words, rather than dropping it silently: whether to show it at all is your service's decision.

From openEHR to Lily

Lily does not read openEHR compositions either. The mapping for openEHR Reference Model data types and codes, as a suggestion your clinical safety review decides:

openEHR data types and codes, and the Lily values for them
openEHRLily
DV_QUANTITY (entry)quantity-input-div; units as UCUM codes with your words
DV_QUANTITY (display), magnitude_statusobservation-view with formatQuantity(value, unit, locale, comparator) (~ is ≈)
DV_ORDERED.normal_status HHH, HH, H, L, LL, LLLobservation-view interpretation: FHIR HU, HH, H, L, LL, LU
other_reference_ranges with a meaningobservation-view ranges
DV_DATE partial (year, year and month)date-field precision; formatPartialDate(); date-time-view
DV_DURATIONduration-view with durationParts()
DV_PROPORTIONformatProportion() inside observation-view
DV_ORDINAL, DV_SCALEa radio-group whose labels carry the number and its words
DV_CODED_TEXTthe coded values pattern below
DV_BOOLEANcheckbox-input, only when "not asked" cannot happen
ELEMENT.null_flavour 253 unknown, 271 no informationstatus="not-recorded" or "unavailable", with words that say which
null_flavour 272 maskedobservation-view status="masked"
null_flavour 273 not applicablestatus="not-applicable"
PARTY_RELATED subjectsubjectLabel on the record items
AUDIT_DETAILS, ATTESTATION, FEEDER_AUDITrecord-provenance-view
Instruction State Machine stepsa timeline-list of steps, with the current state on the item
an archetype item with occurrences 0..*repeatable-fieldset

Coded values

  • Show Coding.display; if there is none, CodeableConcept.text; if neither, system|code. Never an empty cell.
  • Offer a control that reveals the code system and code beside each value, such as a toggle button that says "Show codes". Hidden codes stay out of the reading order until shown.
  • Mark clinical text with the document's language (lang), which may differ from the interface's. Translate the interface; never translate the clinical content.
  • Lily ships no terminology: no SNOMED CT, LOINC, ATC or UCUM lookups. Write what the document says. The SvelteKit example's /patient-summary page shows the pattern.

What Lily will not do

  • Compute an early warning score, a growth centile, a dose or a reference range.
  • Ship a drug database, a tall man list, or SNOMED CT, ICD, LOINC or UCUM codes.
  • Reproduce a licensed instrument (Wong-Baker FACES) or another body's design (the NEWS2 chart).
  • Limit the number of records open at once.
  • Infer an interpretation from a range, convert a unit, or parse a relative date ("next Tuesday").
  • Use a switch for "yes, no or unknown": ARIA's switch has no third state, so it is three radios.

The research, sources and decisions behind this guide are in spec/healthcare-ui.