Skip to content

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.