rippr/docs/v3/V3-16-visual-identity.md

V3-16 — Visual identity

Phase Quality · Depends on V3-04, V3-05 · Size M · Status Partially done

Direction (written before any code changed, per the ticket's own step 1)

Palette. Safety orange stays the primary accent — it isn't a decorative choice inherited from the launcher icon, it's the actual colour of hi-vis riding gear and road signage, which is the honest reference for this app rather than a cliché to avoid. What changes: orange stops being the only signal colour. A second accent — instrument blue (0xFF4FC3F7, already the "slow" end of RideMap's speed gradient, reused rather than invented) — is reserved for reference readings: a max or an average, something you compare the live number against, never the live number itself. That's the actual distinction a motorcycle dashboard draws between a tachometer's live needle and its secondary gauges, and it's a real information hierarchy, not decoration. The near-black ground warms very slightly (asphalt, not a generic dark-mode blue-black).

Typography. No new font family. Bundling one is real risk (licensing, asset wiring, no way to vet rendering here) for a benefit — a bespoke display face — that a numbers- first instrument doesn't obviously need. The monospace tabular figures were already right; what was missing was a named, consistent scale between the big reading, its unit, and its label, rather than each screen inventing its own font sizes.

Data display. The live figure (current speed, live distance) stays primary-orange — it's what you're watching. Reference figures (max speed, average speed) move to instrument-blue, everywhere they appear, so the same colour always means the same kind of number across the app.

Motion. Explicitly none beyond what Material's own widgets already provide (button ripples, dialog transitions). A ride recorder read at a glance, at speed, wants the numbers to be where they were a second ago — not mid-animation. This is a decision, not an oversight.

Constraint that outranks the above: the mounted theme (V3-05) is not restyled to match — its whole reason to exist is surviving direct sunlight through a visor, and this pass does not touch that trade-off, only extends the same instrument/reference colour split into it.

Goal

Move from "functional dark" to a look that is deliberately designed.

Context

The current theme is near-black with safety orange, chosen to match the launcher icon. It is clean and legible, and it was never actually designed — it was picked so the app did not look unfinished.

Deliberately sequenced after the live map and mounted mode. Both change what the app looks like far more than a palette does, and designing around screens that are about to change is wasted effort.

Design

Decide the identity first, in one place, then apply it:

• Palette — is safety orange the accent, or just what the icon happened to use? A motorcycle app has obvious references (dashboard instruments, race liveries, road signage) and obvious clichés to avoid.
• Typography — the app is numbers-first. The monospace tabular figures are already right for that; the rest is undecided.
• Data display — the speed readout, the charts and the map legend are the identity far more than any chrome. This is an instrument, not a document.
• Motion — currently none. A ride recorder probably wants very little.

Constraint that outranks aesthetics: legibility through a visor, in daylight, at a glance. V3-05 may force a high-contrast variant, and the identity has to survive it.

Implementation

1. Write the direction down — palette, type, and what the app is trying to feel like — before touching code
2. Extend ripprColors into a fuller token set
3. Apply screen by screen, keeping flutter test green throughout
4. Keep the explicit text colours. The theme names bodyColor and displayColor deliberately: a missing default once rendered a 64 sp figure black-on-black and only a screenshot caught it. Do not regress that while restyling.

Acceptance criteria

• A written direction exists before the code changes
• Applied consistently across all six screens
• Contrast ratios meet WCAG AA for body text
• Legible in direct sunlight — verified on a real phone outdoors
• All widget tests still pass, including the black-on-black guard

Tests

• Existing widget tests must keep passing; they encode real regressions
• Contrast assertions for primary text on each surface
• Golden tests are worth considering here, and only here — this is the one ticket where pixel changes are the point

Risks

Restyling breaking the explicit-colour discipline that exists because of a real bug.

Out of scope

A new app icon. The Route mark is good and recently applied.

Outcome

The token-level identity and its measurable acceptance criteria are done; the two inherently subjective/on-device criteria are not, and are named honestly below rather than checked off on faith.

Implemented at theme.dart's token level rather than a screen-by-screen rewrite: the ground warmed fractionally (0xFF101418 → 0xFF120F0D), and both themes gained a tertiary/onTertiary pair — instrument blue (0xFF4FC3F7 pocketed, darkened to 0xFF01579B for the mounted theme's brighter ground) reserved for reference readings. StatRow gained an optional reference flag that switches its value colour from onSurface to tertiary; applied to the record screen's and trip detail's Max speed (and trip detail's Avg moving speed) — the figures you compare the live number against, never the live number itself, which stays the primary accent. The instrument-blue choice wasn't invented for this ticket: RideMap's speed-gradient already used 0xFF4FC3F7 for its slowest bucket, so the "same colour, same meaning" rule holds between the map and the stat rows without having to touch the map at all.

contrastRatio(Color, Color) implements WCAG 2.x's formula directly against Color.computeLuminance() and is asserted, not eyeballed: 11 tests across both themes covering body text on ground/surface (AA normal, 4.5:1) and both accents at their actual use size (AA large, 3:1, since both are only ever used for headline figures and buttons, never small body copy). Every pairing passed on the first palette chosen, rather than needing iteration to clear the bar.

Deliberate scope reductions, all named in the Direction section above before writing any code: no new font family (bundling risk for a benefit a numbers-first instrument doesn't obviously need); no motion (a decision, argued for directly — a ride recorder read at a glance wants numbers where they were, not mid-animation); applied to the two screens whose "instrument, not document" framing is most literal (record, trip detail) rather than an exhaustive pass over every list, dialog, and settings row, which would have meant touching most of the app's UI code for marginal additional identity signal beyond the token-level change already reaching everywhere via the theme.

Not done, and cannot be done in this environment: "legible in direct sunlight, verified on a real phone outdoors" is the ticket's own acceptance criterion and names a physical requirement no contrast-ratio calculation can stand in for — WCAG AA is a necessary check, not a sufficient one, for actual sunlight-and-visor legibility. Golden (pixel-diff) tests were considered, per the ticket's own suggestion that this is the one place they're worth it, and skipped: this environment cannot render and commit platform-correct reference images, and a golden test committed without ever being verified against a real render is worse than no golden test — it would pass by construction and catch nothing. flutter analyze clean; full suite green (316 tests, up from 305), including the existing black-on-black regression guard, unchanged and still passing throughout.