Improve the Web UI design and UX

[angeloINTJ]

What

Redesign or improve the embedded Web UI — the browser interface served directly from the Pico W.

Why

The current Web UI is functional and was given a design pass in v2.2.0-beta (measured light/dark palette, --ok/--warn/--track tokens, theme-aware graph and login). There is still room in layout, mobile ergonomics, forms and error states.

⚠️ Resource constraints (corrected — read carefully)

Measured on main @ 217e28a (v2.2.14-beta, release build, 2026-08-19)	Bytes
Flash used	1,006,076 of 1,044,480 (96.3%)
Flash headroom	38,404

Numbers here age with every release — an earlier revision said 50,268 B; h5g (v2.2.11), HA Discovery + /metrics (v2.2.13) and syslog (v2.2.14) consumed the difference. Re-measure before budgeting: arm-none-eabi-size -A on the release ELF, formula in docs/ANALISE_FLASH_RAM.md (the PlatformIO % lies). The practical budget is unchanged: a few KB of gzipped growth is affordable, a framework is not.

• No frameworks. No React, Vue, Tailwind, or npm. Static HTML/CSS/JS only.
• RP2040: 264 KB SRAM, dual-core at 133 MHz. The web server shares the chip with sensor polling, display rendering, WiFi and telemetry. Heavy JS or large DOM trees will OOM the device.
• Browser target: modern Chrome, Firefox, Safari, Edge. Mobile-first (most users arrive from a phone).
• i18n ceiling (the hidden cost). Every new visible string ships in BOTH .lng packs, and language_es-ES.lng is at 97% of its 32,768 B ceiling (723 B free). Overflow is invisible at runtime — python3 tools/check_lang_packs.py is the only guard. Prefer reusing existing visible labels (e.g. aria-labelledby) over minting new strings; text-heavy improvements (error messages) need a pack diet first.

How the pipeline actually works (corrected)

WebUI.h is the source (currently 452,625 B of raw-string HTML/CSS/JS). It is not shipped as-is:

1. tools/build_webui_gz.py runs as a pre-build hook — it minifies each page, gzips it, and writes src/WebUI_GZ.h.
2. The minifier is a stateful scanner, not a regex, because the regex predecessor silently ate JS inside string literals. It is guarded by tools/test_webui_minify.py — run it after any edit; a page that stops being literal-equivalent fails the gate.
3. custom_fs_pages can move a page out of flash and into LittleFS, but build_webui_gz.py refuses that option for shipping environments — it is a bench-only diet lever and is not a way to buy space for a UI change.

So the loop is: edit WebUI.h → python3 tools/test_webui_minify.py → pio run -e pico_w_release → read the gzipped size delta out of the build.

What you can improve — pick ONE

• Dashboard cards — temperature/humidity as cards instead of raw tables
• Mobile-first responsive — touch-friendly controls, no horizontal scroll at 375px
• Settings form UX — grouping, validation, save/cancel patterns
• Loading states — CSS-only spinner, skeleton screens
• Accessibility — ARIA labels, keyboard nav, focus management
• Error states — friendly messages, retry buttons, offline indicators
• Login page — modern and branded, under 1 KB of added CSS

Already done, do not pick: dark mode. It shipped in v2.2.0-beta as a full light/dark palette chosen by measured contrast, not a toggle bolted on top.

Acceptance

• UI improvement submitted as changes to WebUI.h
• Works on mobile (375px) and desktop
• python3 tools/test_webui_minify.py passes
• Builds with pio run -e pico_w_release (zero warnings)
• Gzipped size change measured and documented (before/after)
• Flash headroom reported and still positive
• python3 tools/check_lang_packs.py still passes (both packs under the 32 KB ceiling)
• Before/after screenshots attached

References

• WebUI.h — UI source
• tools/build_webui_gz.py — minify + gzip pre-build hook
• tools/test_webui_minify.py — equivalence gate
• src/WebManager_*.cpp — server-side handlers

[angeloINTJ]

Updates in v1.4.1-beta

Web UI fixes and improvements:

• Sensor type column — dashboard table now shows driver type per sensor
• Calibration UX — per-sensor humidity fields shown conditionally based on hasHum flag from API
• JSON fixes — restored missing commas in /api/sensors, /api/status, and /api/users that broke JSON parsing
• Sensor selector — graph/history page now shows all 16 slots, slot 10 (humidity) first
• Universal slot indices — idx: -1 replaced with standard slot 10, all sensors in uniform loop
• API metadata — /api/status sensors now include type and ch (channel count) fields

Commit: 5d7d1b1

[angeloINTJ]

Status update — 2026-08-18 (v2.2.10-beta)

Still open, but the pick-list above is out of date and one item on it is finished.

Already delivered — do not redo:

• Dark mode is complete, not partial. Light/dark ships since v2.2.0-beta: an html.light class applied pre-paint from localStorage.getItem('simut_ui_theme'), with a full token set (--bg, --card, --txt, --sub, --acc, --dang, --border, plus --ok/--warn/--track) and color-scheme set on both. The palettes were chosen by measured contrast, and the graph and login pages are theme-aware.
• Mobile responsiveness is largely there — 13 viewport declarations, 16 @media blocks, 44 px touch targets under 640 px on the history controls.

Two real gaps worth claiming instead:

1. The history page loads Chart.js from a CDN. WebUI.h line 659: <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>. SIMUT is advertised as offline-first, and on an air-gapped lab network the history graph simply never draws. The data path is already ours (the page downloads .h5 and decimates into min/max buckets in the browser) — only the drawing is outsourced. Embedding Chart.js is not an option at ~65 KB gzipped; a hand-rolled canvas line+band renderer at 3–6 KB is. This is the highest-value web contribution available.
2. Accessibility is thin — 6 aria- attributes across the whole UI. No focus management on the modals, no keyboard path through the slot editor.

Build note: since v2.2.9-beta the minifier is a stateful scanner, not a regex. After editing WebUI.h, run python3 tools/test_webui_minify.py — it checks literal equivalence and parses the output with node --check. A silent minifier bug used to eat JavaScript here.

Flash: "98.7%" is stale — ~44 KB of headroom in the release image as of v2.2.10-beta. Measure before/after regardless.

[angeloINTJ]

Update — v2.2.11-beta

The first of the two gaps listed above is done and shipped. Do not start work on it.

The history page no longer loads Chart.js from a CDN. WebUI.h now carries h5g, a canvas renderer written for this one chart: 784 lines, 4.721 B gzipped, 15× smaller than the CDN bundle. Trimming Chart.js was measured first and refused — registering only what the page used still cost 56.818 B, because 43.527 B of that is core that draws zero pixels.

See the release notes for the measurements and the validation: https://github.com/angeloINTJ/simut/releases/tag/v2.2.11-beta

The second gap in that comment is still open and still worth claiming: accessibility. The count is now 6 aria- attributes across the whole UI, no focus management on the modals, no keyboard path through the slot editor. That one has no measurement blocking it — it is straightforward work with real user impact.

One thing the renderer added that is worth knowing if you touch the history page: the chart is drawn by our own code now, so anything you want it to show is reachable. holes is already computed (WebUI.h:1216) and still only surfaces as a corner toast; shading those regions on the chart needs no new API.

[angeloINTJ]

Status update — 2026-08-19 (v2.2.14-beta)

Re-measured everything on today's main (217e28a) and corrected the body: flash headroom is 38,404 B, not the 50,268 B written earlier — h5g, HA Discovery + /metrics and syslog consumed the difference across three releases. The body now says how to re-measure instead of trusting a frozen number.

The accessibility gap, quantified. Counted on the source today, whole UI (12 blocks, 453,569 B raw → 89,862 B gzipped):

Signal	Count
aria-* attributes	6 (1 login, 2 config, 3 lang.js)
role	1
tabindex	0
.focus() calls	1
keydown handlers	1
prefers-reduced-motion	0
<label> elements	83

The last row is the good news: forms are already labelled, so most controls can get an accessible name via aria-labelledby — reusing visible text instead of minting new strings. That matters because of the constraint now added to the body: the es-ES language pack has 723 B left of its 32,768 B ceiling, every new visible string ships in both packs, and overflow is invisible at runtime. tools/check_lang_packs.py joined the acceptance checklist.

Claimed: first accessibility slice (in progress, feat/webui-a11y), scoped to zero new translatable strings:

• focus trap + Escape + focus restore on the credentials modal; role="dialog"/aria-modal
• keyboard path for the custom select (csel): arrows change value, Enter/Space opens, Escape closes, aria-haspopup/aria-expanded — today it is mouse-only
• drawer: aria-expanded, Escape closes, focus management
• role="status" + aria-live="polite" on the toast
• aria-label on the icon-only buttons (calendar ◀ ▶, graph prev/next, the five ♪ sound-test buttons), following the existing English aria-label convention
• global :focus-visible outline and a prefers-reduced-motion block in the shared stylesheet

Budget: ~1 KB gzipped, out of 38.4 KB headroom. Gzipped delta and post-build headroom will be reported here, per the checklist.

Still open for contributors after this slice: extending applyLang() so aria-label participates in i18n, form validation states (aria-invalid + messages — needs the pack diet first), and the error-states item from the pick-list (same dependency).

[angeloINTJ]

As promised above, the measured numbers for the first slice — now up as #82:

Checklist item	Result
Gzipped UI delta	89,862 → 90,709 B (+847)
Flash headroom after build	37,564 B (was 38,404)
test_webui_minify.py	49/49
pio run -e pico_w_release	zero warnings (incl. a pre-existing -Wcomment fixed)
check_lang_packs.py	both packs byte-identical — zero new strings
Keyboard validation	30/30 real-keyboard CDP checks, branch vs main, on the local bench

One claim from my previous comment corrected while implementing: the shared :focus-visible outline already reaches the custom select — the injected outline:none loses the cascade tie because the injected <style> lands before the stylesheet <link>. Verified by computed style. So no CSS was needed there; the pre-session pages (login, force-chpass), which don't load the shared stylesheet, did get their own :focus-visible + prefers-reduced-motion.

Still open for later slices: aria-label participating in i18n via applyLang(), aria-invalid form states (needs the es-ES pack diet first), error-states from the pick-list (same dependency).

[angeloINTJ]

Shipped — v2.2.15-beta (2026-08-19)

The first accessibility slice (#82) and the language-pack ceiling split (#83) are in the v2.2.15-beta release, now Latest. Validated on hardware before publishing: 3 OTA hops (both applier directions), /api/lang byte-identical A/B, and a 36,545 B pack accepted by the new dual ceiling.

What this changes for contributors picking items from this issue:

• Flash headroom on this release: 37,572 B (re-measure per the body's formula before budgeting).
• The i18n constraint is now two numbers: es-ES resident 13,251 B of 16,384 (80%) and file 32,045 B of 49,152 (65%) — ~17 KB of room for new web-visible strings. Error states and aria-label i18n are unblocked.
• tools/check_lang_packs.py (in the acceptance checklist) now reports both ceilings and enforces that @WEBDICT stays the file's last section. A pack over 32,768 B requires v2.2.15-beta or newer firmware first.