mywhoosh2garmin/docs/superpowers/specs/2026-08-16-visual-redesign-design.md

Visual Redesign — "Ride Computer" Dark Theme — Design

Date: 2026-08-16 Status: Draft for user review

1. Goal

Replace the current light, generic admin-template look with a distinctive dark "bike computer cockpit" theme grounded in the app's own subject matter (indoor cycling sync, Garmin telemetry). The redesign is a shared foundation: it must land before the planned dashboard summary tiles and live-update UX polish, so those can be built directly in the new visual language instead of needing a second pass.

This spec covers only the visual system and the already-shipped next-sync indicator's evolution into a live countdown. It does not add new pages, new data, or new business logic.

2. Scope

In scope

• New CSS design-token system (color, spacing reuse, borders) replacing the current light theme in app/web/static/style.css.
• Cockpit-style topbar (dark, brand mark, nav, live sync countdown).
• Restyled shared components: cards, buttons, badges, tables, forms, empty states — applied globally via shared CSS classes so every existing template (login, account-login, dashboard, account detail/edit, users detail/new/edit, system, sync result fragment) picks it up without structural rewrites.
• Typographic treatment: uppercase tracked labels for headings/section labels (extends the existing table-header pattern), tabular monospace numerals for all stats/timestamps/counters.
• Evolving the existing static next-sync timestamp (app/web/static/app.js, base.html) into a live, client-ticking countdown.
• Accessible focus states (visible lime outline) and prefers-reduced-motion handling for the one animated element (the countdown) and card entrance.

Out of scope (separate follow-up specs)

• Dashboard summary/stat tiles (next phase, builds on this theme).
• Live sync results without full page reload (UX-polish phase).
• Any light-mode / theme-toggle support (explicitly rejected by user — dark only).
• New charts/statistics views.
• Any change to routes, models, or sync/business logic.

3. Design tokens

Color

Token	Hex	Usage
--bg	#12151A	Page background
--surface	#1A1F27	Cards, topbar, table zebra-free rows
--surface-raised	#232935	Hover states, inputs
--border	#2A3038	Hairline dividers/card borders
--text	#E7EAF0	Primary text
--text-muted	#8B93A3	Secondary text, labels, hints
--accent	#C8FF4D	Electric lime — signature countdown, primary buttons, focus rings, "healthy" status

Semantic status colors (each with a ~14% opacity tint of the same hue over --surface for badge backgrounds, matching the existing --*-bg variable pattern already in style.css):

State	Hex	Meaning
Success / healthy	--accent #C8FF4D	Reuses the signature accent — a healthy sync is the good state the accent celebrates
Warning / degraded	#FFB454	Amber
Danger / action required / failed	#FF5F6D	Coral
Info / syncing / running	#5FD4FF	Cyan
Neutral / disabled	#5A6472	Slate

These map 1:1 onto the existing --success, --warning, --danger, --info, --neutral variable names already used by .badge-* classes in style.css — only their values change, not the class structure, so templates need no edits for badges.

Typography

• Body/UI face: unchanged system stack (-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif) — no new font loads, works offline in a self-hosted container.
• Monospace face for all numeric data (stats, timestamps, the countdown, table numeric columns): ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace, with font-variant-numeric: tabular-nums.
• Headings and structural labels (h1/h2, .badge, table th, the new topbar labels): uppercase, letter-spacing: 0.06em, extending the tracked uppercase style table th already has today — applied consistently instead of only in tables.

Layout

• Topbar becomes the cockpit header: --surface background, hairline bottom border, brand mark left, nav + live countdown grouped right (existing .topbar-right wrapper from the next-sync work is reused).
• Cards: hairline --border outline, --surface background, no drop shadow (shadows read poorly on dark; hairlines carry the "device bezel" feel instead). Radius stays at the existing --radius: 10px, unchanged.
• Buttons: primary uses --accent background with dark text (for contrast against the light lime); secondary keeps outline/ghost style against --surface.
• Focus-visible: 2px --accent outline on all interactive elements (links, buttons, inputs) — dark backgrounds need this to stay accessible since the current subtle browser default focus ring is hard to see on --surface.

Motion

• The live countdown ticks once per second (text content update only, no layout shift).
• Cards fade/slide in ~150ms on initial page load, translateY(4px) → 0.
• Both respect prefers-reduced-motion: reduce (countdown text still updates, since it's informational, not decorative; the card entrance animation is skipped entirely).

4. Signature element: live sync countdown

app/web/static/app.js currently does a one-time UTC→local conversion of the time[data-utc] element on DOMContentLoaded. It's extended to:

1. On load, read data-utc as the target instant.
2. If the target is in the future, start a setInterval (1s) that computes the remaining duration and renders it as HH:MM:SS (or MM:SS under an hour) in monospace, e.g. NEXT SYNC ▸ 00:12:04.
3. If the target is in the past (page left open past the sync time, or next_tick not yet known on first boot), render due now instead of a negative countdown.
4. The title attribute keeps showing the absolute local time (via toLocaleString()) and the original UTC instant, so hovering still gives an absolute reference — this preserves today's behavior as a fallback/aid.
5. data-utc stays the templating contract between server and client (same attribute the current tests assert on), so no server-side route or test changes are needed for this evolution — only app.js behavior and the surrounding CSS/markup in base.html change.

No server-side change: next_sync_tick() in app/web/routes.py and the base.html template variable wiring stay as they are; only the visual presentation and app.js ticking logic change.

5. Testing

This is a CSS/JS-presentation change with one markup adjustment (countdown wrapper element/label in base.html). Existing server-rendered tests assert on data-utc="..." substrings and text content, not on CSS classes or exact visual output, so no test breakage is expected. No new automated test is meaningful for pure CSS token values; the existing tests/web/test_next_sync_display.py continues to guard the server-side contract (the attribute and value), and manual verification (screenshot) is used to confirm the visual outcome, consistent with how the next-sync feature was verified.

6. Rollout

Single pass across style.css, base.html, app.js. No template restructuring needed beyond base.html's topbar, since all other templates already consume the shared .card, .badge, button/.btn, table, and form.stacked-form classes this spec restyles centrally.