Cost Estimate Breakdown — Design Brief¶

Status: Ready for /impeccable craft Issue: #246 Spec source: docs/specs/platform-restructuring-design.md Part 15 Target app: apps/patient-app/ (rich content card in chat + summary panel)

1. Feature Summary¶

A comprehensive cost breakdown shown to patients after provider quotes arrive, combining medical costs (from provider quote), travel estimates (platform-generated), optional recovery costs, Curaway's coordination fee, and a contingency buffer. Displayed as a rich content card inline in the conversational UI and also accessible in the summary panel. When multiple providers have quoted, patients can compare estimates side-by-side.

2. Primary User Action¶

Understand what the full journey will cost and whether it fits their budget. The estimate must build confidence that the price is transparent and complete — no hidden costs.

3. Users¶

Primary: Patient (age 35-70, anxious about cost, comparing options)
Context: Mid-journey in the chat — they've been matched with providers, quotes have arrived. This is the decision point.
State of mind: Cautious, comparison-shopping, looking for reassurance that the total is manageable
Frequency: 1-3 times per case (once per quoted provider)

4. Design Direction¶

Trustworthy and transparent. This is a financial document, not a marketing page. Think medical billing statement meets modern fintech receipt.

Use the existing rich content card pattern (same as match_results, consent_form)
Curaway teal for structure, slate for data, semantic colors only for budget comparison indicators
Numbers are the hero — large, scannable, left-aligned. No decorative elements.
Montserrat for all text. Crimson Pro serif accent on the total line for gravitas.
Expand/collapse for category details — top-level shows 5 category totals + grand total
Budget comparison indicator uses color + icon + text (never color alone per WCAG)

Referencing .impeccable.md: "Reassuring — patients are making a scary decision. The UI should reduce anxiety, not add to it." The cost breakdown must feel complete and honest — if something is estimated, say so. If something is optional, mark it clearly.

5. Layout Strategy¶

Single Provider View (Rich Content Card)¶

┌──────────────────────────────────────────────────────────────┐
│  COST ESTIMATE                                               │
│  TKR Bilateral · Acibadem Maslak, Istanbul                  │
│                                                              │
│  Medical                                    $7,200 – $8,500 │
│  Travel                                     $1,200 – $1,800 │
│  Recovery (optional)                        $1,500 – $2,000 │
│  Curaway Coordination                              $1,500   │
│  Contingency (10%)                          $1,000 – $1,300 │
│  ─────────────────────────────────────────────────────────── │
│  ESTIMATED TOTAL                          $12,400 – $15,100 │
│                                                              │
│  ● Within your budget ($6K – $15K)                          │
│                                                              │
│  [▾ See full breakdown]                                      │
└──────────────────────────────────────────────────────────────┘

Top: provider name + procedure (contextual header)
Middle: 5 category lines with min-max ranges, right-aligned numbers
Divider: total line (bold, slightly larger, Crimson Pro serif)
Budget indicator: green dot + text (within), amber triangle + text (slightly over), red circle + text (over)
Bottom: expand toggle for line-item detail

Expanded Detail (per category)¶

Medical                                        $7,200 – $8,500
  Procedure + hospital (5 nights)              $6,500 – $7,500
  Implants                                       $500 – $700
  Post-op follow-ups (2)                         $200 – $300

Travel                                         $1,200 – $1,800
  Flights (London → Istanbul return × 2)         $600 – $900
  Hotel (3 nights)                               $300 – $450
  Ground transport (T1 Standard)                 $150 – $200
  Visa (e-Visa)                                       $50

Side-by-Side Comparison (2-3 providers)¶

┌────────────────────────────────────────────────────────────────┐
│  COMPARE ESTIMATES                                             │
│                                                                │
│               Acibadem       Apollo         Bumrungrad         │
│               Istanbul       Chennai        Bangkok            │
│  ──────────────────────────────────────────────────────────── │
│  Medical      $7,200–8,500   $5,800–6,500   $8,500–9,200     │
│  Travel       $1,200–1,800   $1,800–2,200   $1,600–2,000     │
│  Recovery     $1,500–2,000   $1,000–1,500   $1,800–2,200     │
│  Curaway      $1,500         $1,500         $1,500            │
│  Contingency  $1,000–1,300   $1,000–1,200   $1,300–1,500     │
│  ──────────────────────────────────────────────────────────── │
│  TOTAL        $12.4K–15.1K   $11.1K–12.9K   $14.7K–16.4K    │
│               ● Within       ● Within       ▲ Slightly over   │
│  ──────────────────────────────────────────────────────────── │
│  [View Acibadem]  [View Apollo]  [View Bumrungrad]            │
└────────────────────────────────────────────────────────────────┘

Horizontal scroll on mobile if > 2 providers
Lowest total column gets subtle teal background tint
Budget indicators per column

6. Key States¶

State	User sees	User feels
Loading	Shimmer placeholder matching card shape	Patient
Single estimate	Full breakdown card with expand toggle	Informed, transparent
Multiple estimates	Comparison table with provider columns	Empowered to choose
Within budget	Green dot, "Within your budget (range)"	Reassured
Slightly over	Amber triangle, "Slightly above budget — options to adjust"	Aware, not alarmed
Significantly over	Red circle, "Above budget — consider alternatives" with destination suggestions	Guided, not rejected
Recovery declined	Recovery line shows "—" or "Declined"	Clear
Estimate updated	"Updated" badge, diff highlight on changed lines	Aware of change
Error (no quotes)	"Waiting for provider quotes" placeholder	Patient

7. Interaction Model¶

Expand/collapse categories: click category row to toggle line items. Default collapsed.
Compare: when 2+ quotes exist, show "Compare estimates" action below single card. Tapping opens comparison view (replaces single card, back arrow to return).
Budget adjustment: if over budget, inline link "Adjust your budget range" scrolls/focuses financial layer in summary panel.
Print/save: subtle "Save as PDF" link below estimate. Not prominent.
Hover on category: no tooltip — all info inline. Hover just dims slightly for click feedback.

8. Content Requirements¶

Header copy: "Cost Estimate" (not "Quote" — Curaway produces estimates, providers produce quotes)
Range format: "$X,XXX – $X,XXX" with en-dash, not hyphen. Single values (visa, Curaway fee) show as "$X,XXX"
Budget indicator copy:
Within: "Within your budget ($Xk – $Xk)"
Slightly over: "Slightly above your budget — we can help adjust"
Over: "Above your budget range — consider alternatives"
Disclaimer (small print): "Estimates based on provider quotes and platform data. Final costs may vary."
"Estimated" label: all travel/recovery lines should show "(est.)" suffix since they're platform-generated, not provider-quoted
Currency: Always show USD. If patient currency differs, show conversion in parentheses.

9. Recommended References¶

spatial-design.md — table alignment, number column rhythm
typography.md — tabular number features for financial data, serif accent on totals
interaction-design.md — expand/collapse, comparison toggle
color-and-contrast.md — semantic indicators (budget status)
ux-writing.md — financial copy, disclaimer tone

10. Open Questions¶

Should the Curaway fee be shown as a flat amount or "Included" (hidden in total)?
Currency conversion: show local currency alongside USD, or USD only?
How many providers max in comparison view? (Recommend: cap at 3, show "View all" for more)