Skip to content

Add a smooth progress-based timer colour gradient #66

Description

@PurpleSentinel

Parent: #23

Summary

Replace the track timer's abrupt 85% and 95% background changes with a continuous, progress-based colour gradient. The display should communicate the whole session at a glance, progressing from green through yellow and amber to red as scheduled time expires, then using deep purple for overrun.

User experience

  • A track session starts with a green background.
  • As time elapses, the background fades smoothly from green to yellow, yellow to amber, and amber to red.
  • The colour progression is based on elapsed percentage, so it behaves consistently for every configured track-session duration.
  • The scheduled-time colour anchors are evenly distributed: green at 0%, yellow at one-third, amber at two-thirds, and red at 100%.
  • Once scheduled time has expired, the timer remains at 00:00 with a deep-purple background and white text while elapsed time continues to show the overrun.
  • Countdown and elapsed-time text must remain highly visible throughout every intermediate colour, including the exact anchor colours and overrun state.

Functional behavior

Scheduled session gradient

  • Calculate progress as elapsed scheduled time divided by total scheduled duration and clamp it to 0–100%.
  • Linearly interpolate the RGB colour inside the current green/yellow, yellow/amber, or amber/red segment.
  • Derive gradient state from the displayed elapsed second so the background and timer digits update together without unnecessary full-frame redraws.
  • Preserve the current 00:00 remaining-time behavior at and after expiry.

Text contrast

  • Evaluate each generated background colour and automatically select black or white text, choosing whichever provides the stronger WCAG-style contrast.
  • Apply the selected colour to both the large remaining time and smaller elapsed time.
  • Do not rely on fixed text-colour thresholds tied only to the named anchor colours.

Overrun

  • At scheduled expiry, enter the semantically distinct deep-purple overrun state.
  • Keep the existing double-tap stop behavior and elapsed overrun counter unchanged.

Hardware, safety, and compatibility

  • Generate native RGB565 values compatible with the Waveshare 240×240 LCD.
  • Do not allocate a second framebuffer or retain a full set of pre-rendered gradient frames.
  • Keep display updates bounded to visible timer changes so SPI traffic, touch responsiveness, and RP2040 heap usage remain safe.
  • Track/rest duration settings, Launch Mode, fixed/Auto rotation, stop gestures, and saved configuration must remain compatible.
  • The rest timer and Ready screen are outside this feature and retain their current colour behavior.

Acceptance criteria

  • Track background is green at 0%, yellow at one-third, amber at two-thirds, and red immediately before scheduled expiry.
  • Intermediate scheduled-session frames use smoothly interpolated colours without abrupt 85% or 95% jumps.
  • The same proportional progression applies to every supported track duration.
  • Expired/overrunning track sessions use deep purple with white text while showing 00:00 remaining and continuing elapsed time.
  • Every generated background selects the higher-contrast black or white timer text.
  • Rendering does not allocate a second framebuffer and remains responsive to the stop gesture.
  • Existing rest-session colours and timing behavior remain unchanged.
  • Host-side tests cover exact anchors, interpolation, clamping, contrast selection, duration scaling, and overrun.
  • The feature is exercised on supported physical hardware.

Documentation

  • Update the README and User Guide to explain the smooth colour sequence, proportional anchors, overrun state, and automatic high-contrast text.

Relationship

This is an implementation-focused visual improvement beneath roadmap epic #23. It supersedes the abrupt expiry-colour concern in #2. User-configurable warning points and overtime policies remain tracked separately by #29, and alternate accessible themes remain tracked by #34.

Metadata

Metadata

Assignees

No one assigned

    Labels

    NewFeatureCandidate product capability for future development

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions