Health user interface dem
Guide for teams wey dey build clinical software with Lily: clinical portal dem, results and reporting, how to prescribe and give medicine, decision support and hospital dashboard dem.
Translation dem of dis page na machine draft wey nobody don check. Di English page na di correct version.
Wetin Lily dey do, and wetin e no dey do
Lily dey give you display contracts: semantic markup, ARIA, keyboard behaviour and class hooks for di tins wey dey repeat for clinical screens. E no dey give you clinical logic, clinical content or any regulatory claim.
| Lily dey give | You go give |
|---|---|
| observation-view: value, unit, flag for words, range, and wetin to show when nothing dey | Di value, how to decide di flag, di reference range |
| allergy-record-list and allergy-record-list-item: status wey no dey ever empty | Di allergy record and im terminology |
| medication-view: name, strength, form, route and how often, no part dey cut | Di drug data, di tall man segments, di strength wey dem don format |
| decision-support-card: di shape of CDS Hooks card | Di rules, di suggestion actions, how to record wetin happen |
| early-warning-score-view: score, band and escalation, as dem show am | Di scoring system and im validated calculation |
age-view and ageParts(): age for units wey fit am |
Di words for di units (Intl.DurationFormat or your own labels) |
formatQuantity(): 5 mg, never 5.0 mg; 0.5 mg, never .5 mg |
Di number, di unit and di locale |
| Di patient banner composition | Every label and value, and who fit see clinical information |
Regulation. Software wey dey calculate score, centile, dose or drug interaction na medical device normally. Lily no dey calculate any of dem, for purpose. If dem dey regulate your product, na you get im usability engineering file (IEC 62366-1, FDA human factors guidance, EU MDR). Lily tests, im self-assessed accessibility conformance report and im screen-reader matrix fit be evidence for dat file; none of dem na conformance claim, and di matrix neva get any result.
Alerts: interrupt only for wetin dey critical
Alert fatigue na safety wahala: if every alert dey interrupt, people go dismiss all of dem. AHRQ guidance na to arrange alert dem by how serious dem be and make only di serious ones interrupt.
- Information (
indicator="info"): inline, beside di work, one decision-support card inside di page. - Warning (
indicator="warning"): dem fit see am without blocking, di same card, wey dem style make e stand out; no modal. - Critical (
indicator="critical"): put di card inside alert dialog, and giveoverrideReasonsso say if person dismiss am, e go ask for reason. - Decision-support card no dey ever be live region by itself. Announce new critical card by moving focus enter di dialog, no use
aria-live. - Remove card when di event wey e answer happen again, and record every outcome (dem accept am, or dem override am with di reason).
Wrong-patient errors: identify, no restrict
- Show two identifiers anywhere wey patient data dey show: di name with di date of birth, and di national identifier with im view component (The Joint Commission, Quick Safety 45).
- Use di patient banner for every screen wey dey act on one patient record, and make e dey show.
- Before action on record wey no be di one for di banner, confirm am with di name, date of birth and identifier.
-
Entry wey dey talk about another person wey no be the patient (parent history, belle pikin, donor) go first talk with word who e belong to: give the record items one
subjectLabel("Mama"), so that relative diagnosis no go ever read like say na the patient own (openEHRPARTY_RELATED, FHIRFamilyMemberHistory). - No limit how many records clinician fit open: randomised trial of 3,356 clinicians (JAMA, 2019) find say e no reduce wrong-patient orders, and people dey find way waka around am.
-
Menu of action for one record go first call that record name, with
subjectLabelforcontext-menuordropdown-menu("Ada Lovelace, blood pressure 3 Nov"): one first part wey no dey interactive and na im be the menu accessible name. -
Arrange every action by wetin e dey do, and make the level show before e run. Routine (look, print) dey run sharp sharp. Documented dey talk wetin e go write for the record ("E dey add note to the visit").
Clinical (stop, cancel order) dey ask second time, inside one
alert-dialogwey im confirm button na the verb ("Stop"), never "OK" or "Yes". Disclosive (emergency access, share outside the care team) go first ask for reason and write am down. - When plenty record open (tab, window, split panel), every tab visible text and accessible name get the patient name and second identifier, the active panel go repeat the banner, and no action go touch patient wey no be im panel own.
- Show the place wey record go dey attributed to (the ward, clinic or facility wey dem choose for sign-in) as text for the page header, and make changing am one clear action.
- Show the active visit, or "No active visit", for the banner. Form wey need visit go talk am and offer to start one, instead to fail when dem save am.
Di patient banner
Dem document di composition with medical-banner, with working page for /patient-banner inside di SvelteKit example app:
- two identifiers, and di age beside di date of birth;
- allergies through allergy list, so say "no known allergies", "not recorded" and "unavailable" no go ever look di same;
- missing value na words ("Not known"), no be question mark, dash or empty cell;
- patient wey don die:
data-deceasedfor di theme, and one line of text wey dey show, no be colour alone; - no field dey cut, clip or hide for any width; e dey wrap.
-
patient flags ("E need interpreter", "Infection risk") na one labelled
tag-groupof words, never icon or colour alone, and dem go still show when the banner wrap.
Results
- One display for result, no matter which system e come from: di observation view.
- Di flag na words from your translation (
flagLabel), with di FHIR interpretation code asdata-interpretationfor di theme. - Separate new results from di earlier ones, and show trend (sparkline, or line chart with im data table): clinicians dey look for big change, no be only di range.
- Result wey dem neva ever record and one wey no dey available na different states, with different words.
-
Wetin nobody know no be normal. Result wey im reference range miss, still dey load or no fit read no get interpretation and e go talk am;
observation-viewno dey ever guess one, so result wey get range but no getinterpretationno go show flag. -
Result wey pass the scale na the instrument limit with comparator ("> 33.3 mmol/L":
formatQuantitywith">") and your critical flag, never naked number. Approximate value go keep im ≈ ("~"). - Give other named ranges ("Critical: below 2.5") as
ranges, each one im own part. -
Result wey dem correct or amend go keep the value wey e replace, inside one
<del>, with your word for when e change (previousValue,previousLabel), so clinician wey read the old value go know say e don change. -
Interval reading go talk im width and function ("Mean, 24 hours"), and the reading state and method ("Sitting, big cuff") na visible text near am, never only tooltip (openEHR
INTERVAL_EVENT,state,protocol). - Trend need points wey fit compare: no draw line below your minimum, cut the line where the method or test change, and talk direction and meaning with word ("e dey fall, e dey better").
-
Vitals wey dem enter for one unit system fit show the other one near am as your text ("70 kg (154 lb)"); Lily no dey convert anything, so talk how you round am. Enter quantity with
quantity-input-div, wey im number dey follow each unit limit. -
Growth chart na one
line-chartwith your centile lines as series, the pikin points and im data table of age and value; Lily no dey calculate centile and e no dey bring growth reference.
Medicines
- Generic names for lower case, except tall man letters from FDA and ISMP lists or your country own (Australia and Canada dey publish dia own). Mark dem for
nameSegments; Lily no dey ever guess dem. - Write di strength with
formatQuantity: no trailing zero, one leading zero, and no-break space before di unit. - Keep di comparator of one result:
formatQuantity(5, "mmol/L", locale, "<")dey write "<5 mmol/L". FHIR ownQuantity.comparatordey write as <, ≤, ≥ or >; if you drop am, "less than 5" go turn "5". - Write mL, never cc, and avoid every abbreviation for ISMP error-prone list.
- Never cut medicine name or dose.
Dates and times
- Write di month as text so say dem no fit read date two ways (
Intl.DateTimeFormatwithmonth: "short"). - Choose di clock on purpose: pass
hourCycleclearly. NHS dey ask for 24-hour clock; dat one na UK rule, no be worldwide one, so Lily no dey ever pick am for you. - Ages dey follow di Common User Interface bands through
ageParts(); service wey get another convention go pass im own words. -
Date wey dem know only reach month or year go stay like that: ask for am with
date-fieldprecision="month"or"year", store2019-03or2019, and write am withformatPartialDate(). Never make up day. -
Length of time na
duration-view, one<time datetime="P3DT4H">wey hold your words, fromdurationParts()andIntl.DurationFormat.
Dashboards
- Ward board or command-centre screen dey update often. No announce every change: keep one polite summary region ("3 beds free, 2 discharges due") and let people read di board.
- Every state for board (bed clean, occupied, blocked) na text or
data-*state with words, no be colour alone. -
Nothing dey blink (WCAG 2.2.2, 2.3.1), and board wey dey update with timer get pause control or e go only update when dem ask; update no dey ever move focus. Entry wey don pass time go talk am with word ("E don wait pass 20 minutes") with
data-overdue. - Count or rate go show im denominator ("12 of 68") and link to the list wey dey behind am.
- List or timeline go talk wetin e be view of: wetin e dey show, im order and window, wetin hide and why, and which source no answer. Empty list from source wey no answer no be proof say nothing dey.
-
Reminder list na one
record-listwey im items carry due date (review-date) and due state with word, withdata-due; the rule wey make am na your own.
Forms
-
Question wey dem answer "yes", "no" or "dem no ask" na one
radio-groupof three answer, none choose for start, never checkbox: checkbox no fit separate "e deny" from "dem never ask". Review of systems na onefieldsetfor each body system, and "all others no dey" button go only set the ones wey nobody answer. -
Question wey get list of answer (medicine, address) na one
repeatable-fieldset: dem go add or remove item, focus go follow, and every remove button get im item name. -
Number with decimal comma: show am with
Intl.NumberFormatand, wheretype="number"no gree accept comma, collect am for text field withinputmode="decimal"and parse am for your code. Never change value wey person type, even to clamp am inside range: value wey pass range na error wey dem fit see. -
Long list wey dey show only part of im options at once dey set
aria-setsizeandaria-posinseton each option, and e remember say find-in-page no fit see the rest.
Records, notes and where dem from
-
Talk wetin list or grid be view of, before im rows: im window and order, wetin e leave out and why, and which source no answer ("Last 12 months, newest first. The GP record no answer."). Give
record-listandtimeline-listonecoverageLabel, and thedata-gridhelper im owncoverageLabel. Empty list from source wey no answer go talk am with word, so nobody go ever read am as "nothing record". -
Talk where record come from and whether e don final with
record-provenance-view: signed, dey wait signature, amended, saved for this device and dem never send am. Unsigned draft no suppose ever look like say e don sign. - Entry about another person (parent, belle pikin, donor) go first talk who e belong to, with the record items
subjectLabel. -
Entry wey dem hold back go stay for the list with your word ("Restricted: e no dey for you"), and entry wey dem make by mistake go stay cancel with "Enter by mistake": give
record-list-itemortimeline-list-itemoneentryStateand oneentryStateLabel. Never remove any of dem quietly, because gap go read like "nothing happen". -
For clinical note, mark each passage source (typed, dictated, template, copy forward, generated) with
data-sourceand word wey people fit see, so copied or generated text no go ever pass as today examination. -
Section wey no fit load na
unavailablefor your word, with retry button; technical code, if dem show am at all, go dey behind disclosure. Failure wey person action cause go dey announced, with the value wey the record hold now; failure for page load no go announce. -
Order history na one
timeline-list, one item for each step (planned, scheduled, active, suspended, completed, cancelled) with im time and reason, and the current state still dey on the item.
From FHIR to Lily
Lily no dey read FHIR resources; your code dey map dem to Lily props. Dis tables dey map di HL7 FHIR International Patient Summary (IPS 2.0.1, FHIR R4). Di code mapping na suggestion: your clinical safety review go decide am, and di words for every state na your own.
| IPS section | Lily |
|---|---|
Allergies and intolerances (48765-2) |
allergy-record-list and im items |
Medication summary (10160-0) |
medication-record-list, each item dey hold one medication-view |
Problem list (11450-4) |
problem-record-list and im items |
Immunizations (11369-6) |
immunization-record-list and im items |
Results (30954-2) |
observation-view, for data table or summary list |
History of procedures (47519-4) |
procedure-record-list and im items |
Medical devices (46264-8) |
device-record-list and im items |
Alerts (104605-1) |
Warning text or alert, never behind one collapsed control |
| Any oda section | record-list and im items |
| One required section wey di document leave out | Di section list with status="omitted" |
| FHIR | Lily |
|---|---|
emptyReason nilknown |
Di list own status="none-known" |
emptyReason notasked, notstarted |
status="not-recorded" |
emptyReason unavailable, withheld, closed |
status="unavailable", with words wey talk which one |
Di IPS codes no-known-allergies, no-known-medications and di like |
status="none-known" |
Di IPS codes no-allergy-info, no-medication-info and di like |
status="not-recorded" |
AllergyIntolerance.criticality |
criticality, apart from one reaction own severity |
clinicalStatus, verificationStatus |
Di same props for di allergy and problem items, with di same codes |
MedicationStatement.status |
Di medication item own status |
Dosage.text |
medication-view dosageText |
Observation.status |
observation-view status, with di same codes |
Observation.dataAbsentReason masked |
status="masked" |
dataAbsentReason not-applicable |
status="not-applicable" (also for the record lists) |
Quantity.comparator |
formatQuantity(value, unit, locale, comparator) |
Map one entered-in-error record to im entered-in-error status, with words, no just drop am quietly: whether to show am at all na your service decision.
From openEHR go Lily
Lily no dey read openEHR compositions too. The mapping for openEHR Reference Model data types and codes, as suggestion wey your clinical safety review go decide:
| openEHR | Lily |
|---|---|
DV_QUANTITY (entry) |
quantity-input-div; units as UCUM codes with your words |
DV_QUANTITY (display), magnitude_status |
observation-view with formatQuantity(value, unit, locale, comparator) (~ na ≈) |
DV_ORDERED.normal_status HHH, HH, H, L, LL, LLL |
observation-view interpretation: FHIR HU, HH, H, L, LL, LU |
other_reference_ranges with one meaning |
observation-view ranges |
DV_DATE part (year, year and month) |
date-field precision; formatPartialDate(); date-time-view |
DV_DURATION |
duration-view with durationParts() |
DV_PROPORTION |
formatProportion() inside observation-view |
DV_ORDINAL, DV_SCALE |
one radio-group wey im labels carry the number and im words |
DV_CODED_TEXT |
the coded values pattern for down |
DV_BOOLEAN |
checkbox-input, only when "dem no ask" no fit happen |
ELEMENT.null_flavour 253 nobody know, 271 no information |
status="not-recorded" or "unavailable", with words wey talk which one |
null_flavour 272 hidden |
observation-view status="masked" |
null_flavour 273 e no apply |
status="not-applicable" |
PARTY_RELATED subject |
subjectLabel for the record items |
AUDIT_DETAILS, ATTESTATION, FEEDER_AUDIT |
record-provenance-view |
| Instruction State Machine steps | one timeline-list of steps, with the current state on the item |
archetype item wey get occurrences 0..* |
repeatable-fieldset |
Coded values
- Show
Coding.display; if e no dey,CodeableConcept.text; if none dey,system|code. Never one empty cell. - Give one control wey go show di code system and code beside each value, like toggle button wey talk "Show codes". Hidden codes no go dey for di reading order until dem show.
- Mark clinical text with di document language (
lang), wey fit differ from di interface own. Translate di interface; never translate di clinical content. - Lily no dey ship terminology: no SNOMED CT, LOINC, ATC or UCUM lookups. Write wetin di document talk. Di SvelteKit example
/patient-summarypage dey show di pattern.
Wetin Lily no go do
- Calculate early warning score, growth centile, dose or reference range.
- Ship drug database, tall man list, or SNOMED CT, ICD, LOINC or UCUM codes.
- Copy licensed instrument (Wong-Baker FACES) or another body design (di NEWS2 chart).
- Limit how many records dey open at once.
- Guess interpretation from range, convert unit, or parse relative date ("next Tuesday").
- Use switch for "yes, no or nobody know": ARIA
switchno get third state, so na three radio.
Di research, sources and decisions wey dey behind dis guide dey for spec/healthcare-ui.