Healthcare uiser interfaces

A guide fur teams biggin clinical saftware wi Lily: clinical portals, results an reportin, prescribin an medicines administration, decision support an hospital dashboards.

This owersettin is a machine draft that naebody has checkit yet. The English page is the ane that coonts.

Whit Lily daes, an whit it daesnae

Lily gies ye display contracts: semantic markup, ARIA, keyboard behaviour an class hooks fur the things clinical screens repeat. It daesnae gie ye clinical logic, clinical content or a regulatory claim.

Whit Lily provides, an whit ye provide
Lily provides Ye provide
observation-view: a value, unit, flag in words, range, an missin states The value, the flag decision, the reference range
allergy-record-list an allergy-record-list-item: a status that's niver blank The allergy record an its terminology
medication-view: name, strength, form, route an frequency, nane o it cuttit aff The drug data, the tall man segments, the formattit strength
decision-support-card: the CDS Hooks caird shape The rules, the suggestion actions, recordin the ootcome
early-warning-score-view: a score, band an escalation, displayit The scorin system an its validatit calculation
age-view an ageParts(): an age in units that suit it The wirds fur the units (Intl.DurationFormat or yer ain labels)
formatQuantity(): 5 mg, niver 5.0 mg; 0.5 mg, niver .5 mg The nummer, the unit an the locale
The patient banner composition Ilka label an value, an wha can see clinical information

Regulation. Saftware that works oot a score, a centile, a dose or a drug interaction is usually a medical device. Lily works oot nane o thae, on purpose. If yer product is regulatit, ye ain its usability engineerin file (IEC 62366-1, the FDA's human factors guidance, EU MDR). Lily's tests, its self-assessit accessibility conformance report an its screen-reader matrix can be evidence in that file; nane o them is a conformance claim, an the matrix haes nae results yet.

Alerts: interrupt anely fur whit's critical

Alert fatigue is a safety problem: whan ilka alert interrupts, fowk dismiss them aw. AHRQ's guidance is tae tier alerts bi severity an mak anely the severe anes interruptive.

  • Information (indicator="info"): inline, aside the task, a decision-support caird in the page.
  • Warnin (indicator="warning"): veesible athoot blockin, the same caird, stylit tae staund oot; nae modal.
  • Critical (indicator="critical"): pit the caird inside an alert dialog, an offer overrideReasons sae dismissin it asks fur a reason.
  • A decision-support caird is niver a live region bi itsel. Announce a new critical caird bi movin focus intae the dialog, no bi aria-live.
  • Tak awa a caird whan the event it answert happens again, an record ilka ootcome (accepit, or owerridden wi its reason).

Wrang-patient errors: identify, dinnae restrict

  • Shaw twa identifiers wherever a patient's data appears: the name wi the date o birth, an the national identifier wi its view component (The Joint Commission, Quick Safety 45).
  • Uise the patient banner on ilka screen that acts on ae patient's record, an keep it veesible.
  • Afore an action on a record ither than the ane in the banner, confirm it wi the name, date o birth an identifier.
  • An entry aboot somebody ither nor the patient (a parent's history, a fetus, a donor) says wha's it is first, in words: gie the record items a subjectLabel ("Mither"), sae a relative's diagnosis is ne'er read as the patient's (openEHR PARTY_RELATED, FHIR FamilyMemberHistory).
  • Dinnae limit hou mony records a clinician can open: a randomised trial o 3,356 clinicians (JAMA, 2019) fand that it didnae reduce wrang-patient orders, an fowk wirk roond it.
  • A menu o actions on ae record names that record first, wi subjectLabel on context-menu or dropdown-menu ("Ada Lovelace, bluid pressur 3 Nov"): a non-interactive first pairt that's forby the menu's accessible name.
  • Tier ilka action by whit it daes, an mak the tier visible afore it rins. Routine (view, prent) rins at aince. Documentit says whit it will write tae the record ("Adds a note tae the encounter"). Clinical (stap, cancel an order) speirs a seicont time, in an alert-dialog that's confirmin button is the verb ("Stap"), ne'er "OK" or "Aye". Disclosive (brak the gless, share ootside the care team) speirs for a raison first an records it.
  • When a wheen records is open (tabs, windaes, split panes), ilka tab's visible text an accessible name include the patient's name an a seicont identifier, the active panel repeats the banner, an nae action applees tae a patient ither nor its panel's.
  • Shaw the place records will be attributit tae (the ward, clinic or facility waled at sign-in) as text in the page heider, an mak chyngin it an explicit action.
  • Shaw the active visit, or "Nae active visit", in the banner. A form that needs a visit says sae an offers tae stert ane, raither nor failin when it's saved.

The patient banner

The composition is documentit wi medical-banner, wi a wirkin page at /patient-banner in the SvelteKit example app:

  • twa identifiers, an the age aside the date o birth;
  • allergies throu an allergy list, sae "nae kent allergies", "no recordit" an "unavailable" niver luik alike;
  • a missin value is wirds ("No kent"), niver a question mark, a dash or an toom cell;
  • a deceased patient: data-deceased fur the theme, an a veesible line o text, niver colour alane;
  • nae field cuttit short, clippit or hidden at ony width; it wraps.
  • patient flags ("Needs an interpreter", "Infection risk") is a labelt tag-group o words, ne'er icons or colour alane, an bide visible when the banner wraps.

Results

  • Ae display fur a result, whitever system it cam frae: the observation view.
  • The flag is wirds frae yer translation (flagLabel), wi the FHIR interpretation code as data-interpretation fur the theme.
  • Separate new results frae earlier anes, an shaw a trend (a sparkline, or a line chart wi its data table): clinicians luik fur a significant chynge, no jist the range.
  • A result that wis niver recordit an ane that's unavailable are different states, wi different wirds.
  • Unkent isnae normal. A result that's reference range is missin, still loadin or unreadable haes nae interpretation an says sae; observation-view ne'er infers ane, sae a result wi a range an nae interpretation shaws nae flag.
  • An aff-scale result is the instrument's limit wi a comparator ("> 33.3 mmol/L": formatQuantity wi ">") an yer critical flag, ne'er a bare nummer. An approximate value keeps its ≈ ("~").
  • Gie further namit ranges ("Critical: ablow 2.5") as ranges, ilka ane its ain pairt.
  • A correctit or amendit result keeps the value it replaced, in a <del>, wi yer words for whan it chynged (previousValue, previousLabel), sae a clinician that read the auld value kens it chynged.
  • An interval readin says its wideness an function ("Mean, 24 oors"), an a readin's state an method ("Sittin, big cuff") is visible text aside it, ne'er jist a tooltip (openEHR INTERVAL_EVENT, state, protocol).
  • A trend needs comparable pynts: draw nae line ablow yer minimum, brak the line whaur the method or assay chynged, an say direction an meanin in words ("fawin, impruivin").
  • Vitals pit in in ae unit seestem can shaw the ither aside them as yer text ("70 kg (154 lb)"); Lily converts naethin, sae state yer roondin. Pit in a quantity wi quantity-input-div, that's nummer taks ilka unit's limits.
  • A growthe chairt is a line-chart wi yer centile lines as series, the bairn's pynts an its data table o age an value; Lily works oot nae centile an ships nae growthe reference.

Medicines

  • Generic names in lawer case, except tall man letters frae the FDA an ISMP lists or yer country's (Australia an Canada publish thair ain). Mairk them in nameSegments; Lily niver guesses them.
  • Scrieve the strength wi formatQuantity: nae trailin zero, a leadin zero, an a no-brak space afore the unit.
  • Haud a result's comparator: formatQuantity(5, "mmol/L", locale, "<") writes "<5 mmol/L". FHIR's Quantity.comparator is written <, ≤, ≥ or >; drappin it turns "less nor 5" intae "5".
  • Scrieve mL, niver cc, an avoid ilka abbreviation on ISMP's error-prone list.
  • Niver cut short a medicine's name or dose.

Dates an times

  • Scrieve the month as text sae a date cannae be read twa weys (Intl.DateTimeFormat wi month: "short").
  • Pick the clock on purpose: pass hourCycle explicitly. The NHS asks fur the 24-hour clock; that's a UK rule, no a warldwide ane, sae Lily niver picks it fur ye.
  • Ages follae the Common User Interface bands throu ageParts(); a service wi anither convention passes its ain wirds.
  • A date kent anly tae the month or year bides that wey: speir for it wi date-field precision="month" or "year", store 2019-03 or 2019, an write it wi formatPartialDate(). Ne'er mak up a day.
  • A lenth o time is duration-view, a <time datetime="P3DT4H"> haudin yer words, frae durationParts() an Intl.DurationFormat.

Dashboards

  • A ward board or command-centre screen updates aften. Niver announce ilka chynge: keep ae couthie summary region ("3 beds free, 2 discharges due") an lat fowk read the board.
  • Ilka state on a board (bed clean, occupied, blockit) is text or a data-* state wi wirds, niver colour alane.
  • Naethin blinks (WCAG 2.2.2, 2.3.1), an a board that updates on a timer haes a pause control or updates anly when speirt; updates ne'er muive focus. An owerdue entry says sae in words ("Waitin ower 20 minutes") wi data-overdue.
  • A coont or rate shaws its denominator ("12 o 68") an links tae the leet ahint it.
  • A leet or timeline says whit it's a view o: whit it shaws, its order an windae, whit's hidden an why, an whit sources didnae answer. A tuim leet frae a source that didnae answer isnae pruif that naethin exists.
  • A reminder leet is a record-list that's items cairy a due date (review-date) an a due state in words, wi data-due; the rule that made it is yer ain.

Forms

  • A question answert "aye", "naw" or "no speirt" is a radio-group o three answers, nane waled at first, ne'er a checkbox: a checkbox cannae tell "denied" frae "ne'er speirt". A review o seestems is ae fieldset for ilka body seestem, an an "aw ithers absent" button sets anly the unanswert anes.
  • A question wi a leet o answers (medicines, addresses) is a repeatable-fieldset: an item is addit or taen awa, focus follaes, an ilka remove button is namit for its item.
  • A nummer wi a decimal comma: shaw it wi Intl.NumberFormat an, whaur type="number" disnae tak the comma, tak it in a text field wi inputmode="decimal" an parse it in yer code. Ne'er chynge a value the body typit, e'en tae clamp it tae a range: an oot-o-range value is an error they can see.
  • A lang leet that renders anly pairt o its options at a time sets aria-setsize an aria-posinset on ilka option, an minds that find-in-page cannae see the lave.

Records, notes an whaur they cam frae

  • Say whit a leet or a grid is a view o, afore its raws: its windae an order, whit it leaves oot an why, an whit sources didnae answer ("Last 12 month, newest first. The GP record didnae answer."). Gie record-list an timeline-list a coverageLabel, an the data-grid helper its coverageLabel. A tuim leet frae a source that didnae answer says sae in words, sae it's ne'er read as "naethin recordit".
  • Say whaur a record cam frae an whether it's final wi record-provenance-view: signed, waitin on a signatur, amendit, saved on this device an no sent yet. An unsigned draft maun ne'er look signed.
  • An entry aboot somebody else (a parent, a fetus, a donor) says wha's it is first, wi the record items' subjectLabel.
  • A withhaudit entry bides in the leet wi yer words ("Restrictit: no available tae ye"), an an entry made in error bides struck throu wi "Pit in in error": gie record-list-item or timeline-list-item an entryState an an entryStateLabel. Ne'er tak awa either quietlike, syne a gap is read as "naethin happent".
  • In a clinical note, mark ilka passage's source (typit, dictatit, template, copied forrit, generatit) wi data-source an visible words, sae copied or generatit text is ne'er taen for the day's examination.
  • A section that cannae load is unavailable in yer words, wi a retry button; a technical code, gin it's shawn ava, sits ahint a disclosure. A failur caused by a body's action is annoonced, wi the value the record noo hauds; a failur on page load isnae.
  • An order's history is a timeline-list, ae item per step (plannt, scheduled, active, suspendit, completit, cancelled) wi its time an raison, an the current state on the item forby.

Frae FHIR tae Lily

Lily disnae read FHIR resources; yer code maps them tae Lily's props. Thir tables map the HL7 FHIR International Patient Summary (IPS 2.0.1, FHIR R4). The code mapping is a suggestion: yer clinical safety review decides it, an the wirds for ilka state are yer ain.

IPS sections an the Lily components for them
IPS section Lily
Allergies an intolerances (48765-2) allergy-record-list an its items
Medication summary (10160-0) medication-record-list, ilka item haudin a medication-view
Problem list (11450-4) problem-record-list an its items
Immunizations (11369-6) immunization-record-list an its items
Results (30954-2) observation-view, in a data table or summary list
History o procedures (47519-4) procedure-record-list an its items
Medical devices (46264-8) device-record-list an its items
Alerts (104605-1) Warnin text or an alert, niver ahint a collapsed control
Ony ither section record-list an its items
A required section the document leaves oot The section's list wi status="omitted"
FHIR codes an the Lily values for them
FHIR Lily
emptyReason nilknown The list's status="none-known"
emptyReason notasked, notstarted status="not-recorded"
emptyReason unavailable, withheld, closed status="unavailable", wi wirds that say which
The IPS codes no-known-allergies, no-known-medications an the like status="none-known"
The IPS codes no-allergy-info, no-medication-info an the like status="not-recorded"
AllergyIntolerance.criticality criticality, apairt frae a reaction's severity
clinicalStatus, verificationStatus The same props on the allergy an problem items, wi the same codes
MedicationStatement.status The medication item's status
Dosage.text medication-view dosageText
Observation.status observation-view status, wi the same codes
Observation.dataAbsentReason masked status="masked"
dataAbsentReason not-applicable status="not-applicable" (forby on the record leets)
Quantity.comparator formatQuantity(value, unit, locale, comparator)

Map an entered-in-error record tae its entered-in-error status, wi wirds, raither nor drappin it quaietly: whither tae shaw it at aa is yer service's decision.

Frae openEHR tae Lily

Lily disnae read openEHR compositions neither. The mappin for openEHR Reference Model data types an codes, as a suggestion yer clinical safety review decides:

openEHR data types an codes, an the Lily values for them
openEHR Lily
DV_QUANTITY (entry) quantity-input-div; units as UCUM codes wi yer words
DV_QUANTITY (display), magnitude_status observation-view wi formatQuantity(value, unit, locale, comparator) (~ is ≈)
DV_ORDERED.normal_status HHH, HH, H, L, LL, LLL observation-view interpretation: FHIR HU, HH, H, L, LL, LU
other_reference_ranges wi a meaning observation-view ranges
DV_DATE pairtial (year, year an month) date-field precision; formatPartialDate(); date-time-view
DV_DURATION duration-view wi durationParts()
DV_PROPORTION formatProportion() inside observation-view
DV_ORDINAL, DV_SCALE a radio-group that's labels cairy the nummer an its words
DV_CODED_TEXT the coded values pattren ablow
DV_BOOLEAN checkbox-input, anly when "no speirt" cannae happen
ELEMENT.null_flavour 253 unkent, 271 nae information status="not-recorded" or "unavailable", wi wirds that say which
null_flavour 272 maskit observation-view status="masked"
null_flavour 273 no applicable status="not-applicable"
PARTY_RELATED subject subjectLabel on the record items
AUDIT_DETAILS, ATTESTATION, FEEDER_AUDIT record-provenance-view
Instruction State Machine steps a timeline-list o steps, wi the current state on the item
an archetype item wi occurrences 0..* repeatable-fieldset

Coded values

  • Shaw Coding.display; gin there's nane, CodeableConcept.text; gin neither, system|code. Niver an tuim cell.
  • Offer a control that reveals the code system an code aside ilka value, sic as a toggle button that says "Shaw codes". Hidden codes bide oot the readin order till shawn.
  • Mairk clinical text wi the document's leid (lang), that micht differ frae the interface's. Translate the interface; niver translate the clinical content.
  • Lily ships nae terminology: nae SNOMED CT, LOINC, ATC or UCUM lookups. Scrieve whit the document says. The SvelteKit example's /patient-summary page shaws the pattern.

Whit Lily will no dae

  • Work oot an early warnin 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 anither body's design (the NEWS2 chart).
  • Limit the nummer o records open at yince.
  • Infer an interpretation frae a range, convert a unit, or parse a relative date ("next Tuesday").
  • Uise a switch for "aye, naw or unkent": ARIA's switch haes nae third state, sae it's three radios.

The research, sources an decisions ahint this guide are in spec/healthcare-ui.