bloodpressure/IMPLEMENTATION_PLAN.md

# Lightweight UI redesign implementation plan

## Objective

Make recording and reviewing blood pressure clearer on mobile and desktop while keeping browser downloads small. Keep Flask/Jinja, build-time Tailwind, native controls, SVG charts, and a small amount of JavaScript.

This plan is based on repository inspection, not a live browser audit. Size budgets below are proposed acceptance criteria; actual compressed page transfers still need measuring.

## Current baseline

- Compiled CSS: 26,156 bytes uncompressed (26.2 kB).
- Minified navigation JavaScript: 1,384 bytes uncompressed (1.4 kB). Additional inline scripts in templates are not included in this figure.
- Flask compression and HTML minification are already configured; verify their production response headers and effects.
- Five dashboard views: list, table, weekly, monthly, graph. List/table pagination already limits pages to 25 readings.
- Graph defaults to the entire history and emits repeated SVG tooltip markup per reading. This can dominate page size for established accounts.
- Table view renders separate mobile and desktop copies of readings.
- Dashboard initially renders a spinner and then fetches the default content separately.
- CSV import/export, personal thresholds, timezone, and a stored dark-mode preference already exist.
- Table highlighting uses fixed thresholds, and the shared layout does not apply the saved dark-mode preference.
- Custom navigation replaces body HTML; inserted inline scripts do not execute. Interaction initialisation needs checking when entering pages from elsewhere.

## Proposed design

Use a quiet off-white background, white surfaces, dark slate text, and the existing teal accent. Establish consistent spacing, small corner radii, restrained borders, system fonts, and tabular numerals. Use colour sparingly and accompany status colours with text.

Navigation: Overview, History, Trends, with Data and Settings secondary. Preserve calendar access under History with a week/month switch. Keep Add reading prominent; on narrow screens use a compact sticky action area that does not obscure content or focused controls.

Overview layout:

1. Page heading and Add reading action.
2. Latest reading, with local date/time and clearly labelled units.
3. Selected-period average and reading count, using one shared range selector.
4. Compact blood pressure trend, with pulse available separately.
5. Five recent readings and a link to full history.

Default to the last 7 days on Overview and last 30 days on Trends. Offer 7/30/90-day and custom ranges. Summary numbers and charts must describe the same period. Empty states say No readings yet instead of showing zero averages.

History uses one responsive representation of the data, retaining 25-row pagination. Filters and view selection live in query parameters so refresh, sharing a URL within the authenticated account, and browser Back behave predictably.

## Functionality priorities

| Priority | Feature | Implementation / weight |
| --- | --- | --- |
| First release | Faster reading entry | Large labelled numeric fields, mobile numeric keyboard, local timestamp default, clear validation, Save and Save & add another. Never prefill previous measurement values. |
| First release | Consistent date filtering | Shared server-side range parsing and SQL aggregates; preserve range across relevant views and export. |
| First release | Finish existing preferences | Apply saved dark mode with CSS variables and saved thresholds consistently. Describe thresholds as personal settings; avoid inventing clinical categories. |
| First release | Better trend review | SVG chart, clear units/legend, local timestamps, accessible text summary, keyboard/touch access to details. |
| First release | Printable summary | Dedicated HTML report with print CSS, selected dates, averages, count and readings; browser Print/Save as PDF. Extend existing CSV export with date filtering. |
| Follow-up | Optional notes | Nullable, length-limited reading note; migration, form support, escaped display, and backward-compatible CSV handling. |
| Follow-up | Import preview | Server-rendered preview with row errors and possible duplicates before commit; explicit timezone handling. |

Keep reminders, offline sync, device integrations, and medication tracking out of the initial release; each requires a separate product and implementation decision.

## Download-size budgets

Use decimal kB (1,000 bytes). Measure response bodies after gzip or Brotli, and record raw sizes separately. These budgets cover browser transfers, not Python packages or the Docker image.

| Resource | Proposed maximum |
| --- | ---: |
| Shared CSS | 8 kB compressed |
| All first-load JavaScript, including inline code | 5 kB compressed |
| Default Overview HTML, including inline SVG | 20 kB compressed |
| Complete cold Overview load, including images/icons and any automatic requests | 40 kB compressed |
| Any interactive History/Trends response | 20 kB compressed |

Reports and explicit exports are measured separately because their size necessarily depends on the requested data. Large uploaded avatars must not silently defeat the normal-page budget; use a bounded thumbnail or initials.

Controls:

- Keep Tailwind as a build tool; add no runtime UI framework, chart library, font download, or icon pack.
- Consolidate template scripts into one cacheable minified file with handlers registered once.
- Render useful dashboard content in the initial response and progressively enhance ordinary links/forms.
- Use one responsive history DOM instead of sending mobile and desktop copies.
- Limit chart output to at most 180 time buckets per series; choose daily/weekly/monthly aggregation for the range and label it clearly. Calculate averages/counts from original readings, not bucket averages. Keep raw values in History/export and disclose aggregation.
- Avoid per-point tooltip panels; use one shared details region and compact SVG paths.
- Render calendar day counts/averages with a drill-down for raw readings so dense months remain bounded.
- Fingerprint static asset URLs and cache them; keep authenticated health-data responses out of shared caches.
- Add a reproducible size check using deterministic fixtures and fail the build when agreed budgets are exceeded.

## Delivery sequence

### 1. Baseline and design specification

Run locally against an isolated fixture database. Capture existing mobile/desktop screens and response sizes for empty, typical, and large histories. Check ancestor repository instructions before implementation. Create desktop and mobile mockups of Overview and Add reading, and settle tokens and component states. Verify production compression separately when deployment access is available.

Acceptance: measured size report and a reviewable visual direction. No production data is needed.

### 2. Shared shell and forms

Update `_layout.html`, Tailwind configuration, and shared Jinja form/navigation components. Apply theme variables, mobile navigation, accessible focus styles, and consistent buttons/errors across login, signup, settings, and reading forms. Consolidate JavaScript initialisation and verify navigation between pages.

Acceptance: responsive at 360/768/1440 px, usable by keyboard and at 200% zoom, with core navigation and form submission working without JavaScript.

### 3. Overview, History, and Trends

Refactor `app/routes/main.py` around shared range parsing and summary queries. Build the new Overview, merge list/table presentation, retain calendar access, and bound graph/calendar output. Preserve existing route access through appropriate redirects or compatible handlers. Ensure rapid filter changes cannot let a stale response overwrite the latest view.

Acceptance: correct date filtering, local timestamps, personal threshold display, empty states, pagination, Back/Forward, and bounded output with 10,000 fixture readings.

### 4. Useful additions

Ship Save & add another, filtered CSV export, and printable report. Treat notes/import preview as a separate follow-up so the initial redesign does not depend on a schema migration.

Acceptance: save/edit/delete round trips, validation errors preserve entered data, and exports/reports match the selected period and documented timezone.

### 5. Verification and release preparation

Run the existing tests plus targeted integration tests for changed behaviour: user isolation, date boundaries including daylight-saving transitions, summaries, export streaming/download navigation, form validation, and empty/large histories. Check chart operation with touch and keyboard, dark-mode contrast, print layout, and repeated navigation. Measure all size budgets against built assets and rendered responses.

Acceptance: a short before/after report containing screenshots, transferred kB, request counts, test results, and any remaining limitations. Deploy only within the separately authorised deployment scope.

## Recommended first implementation slice

Deliver phases 1–3 first: the shared visual system, fast Add reading, a useful Overview, and simplified History/Trends. Complete preferences as part of that work. Add filtered export and printing next, then decide whether notes and import preview are worth expanding the scope.