4. User Experience Documentation

This section documents the experience layer: what every screen does, how navigation is structured, and what happens on success, failure and recovery. For how each persona moves through the product end to end, see the User Journeys section. Each screen also has an exhaustive in-product reference (purpose, controls, fields, workflows, navigation, rules, data, errors, roles, related features and a flow diagram) in the Screen Reference, which is the single source of truth and is generated from the same content that powers the in-app Help panel.

4.1 Design language

The product uses a crisp, fintech-enterprise aesthetic that stays warm enough for healthcare. The primary colour is a trusted medical teal and deep green; a warm amber accent always marks "your next action". Headlines use a serif for an editorial, premium feel; body and UI use a clean sans; reference numbers and ledger amounts use a monospace face. Cards have generous radii, soft shadows and hairline borders. The product is English-only and left-to-right today; internationalisation is Planned.

A consistent rule across the patient and clinic apps: the amber element is always the single most important next step, so a patient or clinic user can always find what to do next at a glance.

4.2 Complete user flows by persona

The complete per-persona user flows (patient discovery to funded case, the in-portal journey to treatment, the clinic onboarding-to-cases flow, and the planned staff-console journeys) now live in the User Journeys section, organised by lifecycle phase. This page focuses on the experience layer that those journeys move through: navigation, screens, decision trees and recovery scenarios.

4.3 Navigation maps

Public site

Header links: brand to home, primary nav (Find Care, Treatments, Pricing, Reviews, Quality, Destinations), and a call to action. Footer mirrors the marketplace: Explore, Trust, For clinics, plus legal links. Every public page shares the same header and footer for a consistent information architecture.

Patient portal sidebar

The sidebar also carries an active-case card with a progress bar (for example "Stage 6 of 14") and a patient footer linking to Account with a sign-out control. Below 880px the sidebar becomes an overlay reached from a topbar menu button. The topbar shows a per-route title and subtitle, a notifications bell, the Help button, and the patient avatar.

Clinic console sidebar

4.4 Screen-by-screen descriptions

Below is a concise description of each screen. For the full reference (controls, every field, edge cases and a flow diagram), follow the link to the Screen Reference page.

Public site

• Home (/): the value proposition, a trust bar, the 14-stage journey, the visa-engine spotlight, corridor cards and conversion CTAs. See site-home.
• Find Care (/clinics): the marketplace. Filter clinics by specialty, country, price and rating; open a comparison. See site-find-care.
• Treatments (/treatments): the procedure catalogue with indicative pricing and savings. See site-treatments.
• Pricing (/pricing): transparent, itemised cost breakdowns and home-market savings comparison. See site-pricing.
• Reviews (/reviews): blended, verified-transaction-weighted reviews and the star distribution. See site-reviews.
• Quality (/quality): JCI / NABH explainer, the vetting process and external ratings. See site-quality.
• Destinations (/destinations): network coverage by destination and honest considerations. See site-destinations.

Authentication

• Sign In (/signin): credential sign-in with a role toggle (patient or clinic). See auth-signin.
• Create Account (/register): registration. See auth-register.
• Verify Email (/verify): code verification. See auth-verify.
• Forgot / Reset Password (/forgot, /reset): password recovery. See auth-forgot and auth-reset.

Patient portal

• Patient Journey (/portal): the home dashboard. A "Next step" hero, a care-coordinator card, four status tiles (escrow, e-Visa, surgery date, documents), the interactive 14-stage strip, a recent-activity feed and a concierge and stay card. Every tile deep-links to the owning screen. See portal-journey.
• Find Care (/portal/clinics): the in-portal marketplace and match wizard. See portal-find-care.
• Care Plan (/portal/care): treatment phases, treating hospital and surgeon, vitals and accommodation tags. See portal-care-plan.
• Visa (/portal/visa): the visa engine. Status hero, document checklist with the submit gate, application timeline, and the corridor rules engine. See portal-visa.
• Travel & Stay (/portal/travel): flight, accommodation, transfer and add-on selection for the corridor and trip. See portal-travel.
• Documents (/portal/docs): the wallet. Upload, store and verify documents; the source of visa checklist completion. See portal-documents.
• Payments (/portal/pay): the escrow view. Total, amount held, milestone schedule and ledger. See portal-payments.
• Messages (/portal/messages): threads with the care team. See portal-messages.
• Account, Settings, Notifications: profile and case details, preferences and security, and journey updates. See portal-account, portal-settings, portal-notifications.

Clinic console

• Dashboard (/clinic): performance overview. See clinic-dashboard.
• Inquiries (/clinic/inquiries): inbound leads with status and budget. See clinic-inquiries.
• Cases (/clinic/cases): active patients by case stage. See clinic-cases.
• Profile, Pricing, Reviews, Team, Settings, Onboarding: see clinic-profile, clinic-pricing, clinic-reviews, clinic-team, clinic-settings, clinic-onboarding.

4.5 Decision trees

"Can the patient submit the visa application?"

flowchart TD
  A[On Visa screen] --> B{All checklist items verified?}
  B -- No --> C[Submit disabled: 'Upload n more to submit']
  C --> D[Tap Upload on a pending item]
  D --> E[Documents wallet]
  E --> F[Upload document]
  F --> G[Document verified]
  G --> A
  B -- Yes --> H[Submit enabled]
  H --> I[Submit -> Granted + timeline complete]

"What should a clinic do with a new inquiry?"

flowchart TD
  A[New inquiry] --> B{Within our specialties + capacity?}
  B -- No --> C[Decline with a reason]
  B -- Yes --> D[Prepare itemised quote]
  D --> E[Send quote -> status quoted]
  E --> F{Patient accepts?}
  F -- Yes --> G[Create case: Treatment planned]
  F -- No --> H[Follow up or close]

4.6 Success, failure and recovery scenarios

The product is designed so that the patient always knows the state and the recovery path. Representative cases:

Cross-cutting UX recovery principles:

• Never lose user input. Composer text, form entries and selections survive transient failures.
• State the next action. Every blocked state names exactly what to do (for example "Upload 2 more to submit").
• Degrade gracefully. When a provider or service is unavailable, the product falls back to a coordinator-mediated path rather than a dead end.
• Confirm money and medical actions. Irreversible or high-stakes actions are confirmed and acknowledged with a visible toast and a recorded activity entry.

4.7 Accessibility in the experience

The experience targets WCAG 2.2 AA: semantic landmarks for navigation, header and main content; labels on icon-only buttons; decorative icons hidden from assistive technology; visible keyboard focus; and AA-contrast text throughout. The mobile experience keeps the primary next action and the case status at the top of the screen so a patient on a phone is never lost. See the accessibility considerations in the data and security docs for the technical posture.