Skip to main content

UI and UX patterns (patient consumer)

References: SPEC.md NFR-PORT-003, NFR-PORT-007, NFR-PORT-008, SOLUTION_DESIGN.md.

1. Persona: patient, not clinician​

The patient app is consumer-grade: low cognitive load, large tap targets, plain language, minimal jargon. It is not the dense clinician EHR surface.

  • Berry template (used for ehr-web clinician) does not apply as a layout template. You may align spacing rhythm, color accessibility, and token naming with platform design docs if a shared token package exists, but prioritize simplicity over dashboard density.
  • Enterprise patient-app parity (patterns, not vendors): prioritize clear visit prep (what to bring, when to arrive), one-tap actions for rescheduling or messaging when policy allows, and obvious next steps after booking or results release—reduce cognitive burden and support accessibility.

2. Visual hierarchy​

  • One primary action per screen when possible (e.g. “Book”, “Send message”).
  • Use cards for appointments and results; avoid multi-table clinical grids.
  • Progressive disclosure: summary first, detail on tap; lab trends and raw FHIR are out of scope unless product explicitly adds them.

3. Touch and ergonomics​

  • Minimum touch target 44×44 pt (iOS HIG) / 48dp (Material) for primary controls.
  • Adequate spacing between destructive actions (cancel appointment) and primary actions.

4. States​

Every list and detail SHALL implement:

  • Loading (skeleton or spinner—prefer skeleton for lists).
  • Empty (actionable copy, e.g. “No upcoming visits”).
  • Error (retry, offline hint when applicable).
  • Permission denied (403-safe messaging without PHI).

5. Accessibility (WCAG-aligned)​

SPEC.md requires WCAG 2.1 AA for patient-facing experiences; NFR-PORT-008 encourages WCAG 2.2 as a stretch.

  • Contrast: default theme meets 4.5:1 for body text; test patient-facing strings on primary buttons.
  • Dynamic type: respect OS font scaling (allowFontScaling, maxFontSizeMultiplier where needed to prevent layout explosion).
  • Screen readers: label all icons; announce state changes (e.g. booking success).
  • Focus: logical focus order in RTL (I18N_AND_RTL.md).

6. Clinical accuracy​

  • Preliminary vs final results must be visibly distinct (SPEC.md FR-PORT-005).
  • AI-assisted content MUST be labeled as non-authoritative per SPEC.md AI subsection.

7. Theming​

  • Support light theme; dark mode if product requires (OLED-friendly, same contrast rules).
  • Tenant white-label colors (if provided) apply to primary, header, and key CTA only—do not reduce contrast below AA.