Spec¶
TL;DR
The specs describe, in plain language, how the app must look and behave. Every rule has an ID that tests, issues, and code point to.
What the specs are¶
A spec is a readable description of how one part of the app behaves. I write it before or alongside the code, and I change it whenever the behavior changes. It is the source of truth. If the app and a spec disagree, one of them has a bug.
Each rule has a requirement ID such as CFG-015 or UX-V-012. Tests and code refer to these IDs, so you can find the check for any rule, and the rule behind any check.
Words that have a fixed meaning¶
| Word | Meaning |
|---|---|
| must | The rule is required. |
| should | The rule is expected unless there is a good reason to do otherwise. |
| may | The rule is optional. |
How to read a spec¶
Start with the TL;DR. Then read the sections you care about. Each section opens with a short description of what you see and what happens, often with an example. After that comes a table of rules with their IDs. Finer points sit in a collapsed "Edge cases" block that you can open when you need it.
The specs¶
Features¶
| Spec | ID prefix | What it covers |
|---|---|---|
| Saved configurations | CFG |
Save, reload, rename, delete, import, and share mappings. |
| Controller detection | CTRL |
How the controller list follows controllers as they connect and disconnect, and which one is selected. |
UX¶
| Spec | ID prefix | What it covers |
|---|---|---|
| UX overview | none | Brand idea, audiences, how screens are designed and reviewed. |
| Principles | UX-P |
The design principles the whole app follows. |
| Visual system | UX-V |
Color, type, spacing, buttons, illustration, motion. |
| Voice and copy | UX-W |
How the app talks and what it calls things. |
| Navigation | UX-N |
Tabs, the More button, and where they go on each screen size. |
| Controller input | UX-C |
What a controller press means on each kind of screen. |
| Accessibility | UX-A |
Contrast, targets, IDs, reading order, live updates. |
| Platforms | UX-PL |
What changes per platform, and what never does. |
Screens¶
| Spec | ID prefix | What it covers |
|---|---|---|
| Setup screens | SCR-SETUP |
Connect a controller, pair with Zwift, try a shift. |
| Ride screens | SCR-RIDE |
Home, riding view, connection lost, ride finished. |
| Buttons screens | SCR-BTN |
Mappings, the function picker, and sticks and triggers. |
| Connections screens | SCR-CONN |
Controller and Zwift status, "Zwift can't find Voltage Gamepad". |
| Settings and help screens | SCR-SET |
Settings, Help and feedback, Credits, and Support this project. |
The saved configurations spec calls a saved set of button assignments a "configuration". The app calls it a mapping. The screen specs use "mapping" and refer to the CFG rules by ID.