Skip to content

Ride screens

TL;DR

Ride is the home tab. It shows your controller, honest stats, your mapping, and whether Zwift can see you. The one main action is Start riding, or Pair with Zwift when Zwift is not connected. While riding you get one big readout and three window sizes: Full, Float, and Mini. Problems are said in words: "Your controller is fine", "Wake your controller".

In the rules, "must", "should", and "may" have the meaning given in how to read a spec.

flowchart TD
    H["Home:<br/>Ready when you are"] -->|"Start riding"| R["Riding view"]
    N["No controller:<br/>Wake your controller"] -->|"Controller wakes"| H
    Z["Home: Zwift isn't<br/>connected yet"] -->|"Pair with Zwift"| C["Connections"]
    R -->|"Zwift lost"| L["Zwift lost the connection"]
    R -->|"Controller asleep"| S["Controller asleep"]
    R -->|"Stop riding"| F["Ride finished"]
    F --> H

Home

What it is for: the screen you see every day. It tells you that you are ready, or what is missing.

Content, top to bottom: the screen title "Ready when you are" (RidePageTitle), your controller card (for example "Your Xbox controller, awake and connected", RideControllerCard), your stats (RideStats), your current mapping, the Zwift status (RideZwiftStatus), and the main action Start riding (RideStartButton).

Example: "12 rides together, 1,086 shifts, riding since September."

Rule ID
The title must be "Ready when you are". SCR-RIDE-001
The controller card must name your controller and say its state in words, such as "Your Xbox controller, awake and connected". SCR-RIDE-002
The stats must show only real values the app counts: rides together, shifts, and riding since. Until there is something real to show, the app must hide the stats or say nothing. SCR-RIDE-003
The screen must show the selected mapping and let you change it by going to Buttons. SCR-RIDE-004
The Zwift status must say "Zwift is connected to Voltage Gamepad" when IsZwiftConnected is true. SCR-RIDE-005
The one main action must be Start riding. SCR-RIDE-006
The status text must be a live region and announce only changes. SCR-RIDE-007

Home, no controller

What it is for: every rider will open the app with the controller turned off, asleep, or unplugged. The screen says so and shows the way out.

Copy: title "Wake your controller", status "Looking for your controller...".

Content: a faded controller, the status, and two ways out: Use a different controller, and Pair a new Bluetooth controller (opens Windows settings). The Connections tab shows its dot.

Rule ID
When no controller is found after first run, Ride must show "Wake your controller" with "Looking for your controller..." and a faded controller. SCR-RIDE-008
It must offer two ways out: use a different controller, and pair a new Bluetooth controller. SCR-RIDE-009
It must not offer Start riding as the main action while there is no controller. SCR-RIDE-010
The screen must return to Home by itself when the controller wakes, and announce that it is back. SCR-RIDE-011

Home, Zwift not connected

What it is for: the state at the start of every Zwift session. Zwift needs the three pairing steps again, so this is the most repeated task in the app.

Copy: "Zwift isn't connected yet", with a short version of the three steps. The main action is Pair with Zwift.

Rule ID
When Zwift is not connected, Home must say "Zwift isn't connected yet" instead of "Zwift is connected to Voltage Gamepad". SCR-RIDE-012
Home must show a short version of the three steps and make Pair with Zwift the main action. SCR-RIDE-013
Pair with Zwift must open the live pairing steps on Connections. SCR-RIDE-014
The Connections tab must show its dot while Zwift is not connected (UX-N-002). SCR-RIDE-015

Riding view

What it is for: a glance from the saddle. One big readout, nothing else competing.

Content: the big "You just pressed" readout (RideLastPressStatus, for example "Shift up, right bumper"), shifts this ride, a quick reference of your main buttons, the window size choice (RideWindowSizeGroup: Full, Float, Mini), and Stop riding (RideStopButton).

Window size What it is
Full The whole riding view.
Float A small always-on-top window you can check over a full-screen Zwift.
Mini The smallest form: a notification-area icon and toast on Windows.
Rule ID
The riding view must have one big readout (the last press) readable at arm's length. SCR-RIDE-016
The riding view must show shifts this ride and a quick reference of the main buttons. SCR-RIDE-017
You must be able to change the window size between Full, Float, and Mini. The app may offer Switch window size as an app action that can be mapped to a controller input, such as View. SCR-RIDE-018
Float and Mini must have no navigation. SCR-RIDE-019
Float, Mini, and Full must show the same problems (Zwift lost, controller asleep) as the riding view. SCR-RIDE-020
The riding view must follow platform limits in Platforms. SCR-RIDE-021
The app must keep shift announcements for assistive technology off by default. You control them with "Announce each shift" in Settings. SCR-RIDE-022
Edge cases
  • "Switch window size" is an app behavior, not a Zwift function. It is not part of the function picker for Zwift functions. If the app offers it as a mappable action, the picker lists it under This app.
  • At 200% text size the readout wraps to two lines before it shrinks.

Zwift lost the connection

What it is for: tell you the controller is fine and Zwift is the one that needs a nudge.

Copy: "Your controller is fine." Then: pick Voltage Gamepad under Controls in Zwift again.

Rule ID
When IsZwiftConnected becomes false while riding, the app must say "Your controller is fine" and explain what to pick in Zwift. SCR-RIDE-023
The app must announce the message right away and also show it in Float and Mini. SCR-RIDE-024
The screen must not move focus when it appears. SCR-RIDE-025

Controller asleep while riding

What it is for: the controller went to sleep or disconnected mid-ride. It needs a state on the full riding screen as well as in Float and Mini.

Rule ID
When the controller goes to sleep or disconnects while riding, the riding view must say so in words and say how to wake it. SCR-RIDE-026
The app must also show the message in Float and Mini, and must announce it. SCR-RIDE-027
When the controller is back, the app must say so and return to the riding readout. SCR-RIDE-028

Ride finished

What it is for: show a short honest summary and, once, ask for support.

Content: time, shifts, and rides together. The one-time donation ask: Chip in on Ko-fi or Maybe later.

Copy: a short line about supporting the project.

Rule ID
The summary must show only real values: ride time, shifts, and rides together. SCR-RIDE-029
The donation ask must appear at most once, on a ride finished screen, with "Chip in on Ko-fi" and "Maybe later". SCR-RIDE-030
The ask must never block anything. "Maybe later" must dismiss it, and the app must not ask again. SCR-RIDE-031
The app must frame the ask as supporting the project. It must not claim impact the app cannot verify. SCR-RIDE-032

Controller input on these screens

On Home and the riding view, a controller press goes to Zwift as mapped. The only exception is the optional Switch window size action. See Controller input.

Rule ID
Controller input on Ride must follow UX-C-004. SCR-RIDE-033

Accessibility IDs

ID Where
RidePageTitle, RideControllerCard, RideStats, RideZwiftStatus, RideStartButton Home
RideLastPressStatus, RideWindowSizeGroup, RideStopButton Riding view
NavConnectionsTab Name adds ", Zwift not connected" when the dot shows