Accessibility
TL;DR
Target WCAG 2.2 AA on every platform. Every color pair is checked. Every tap or click target is at least 48 by 48 px. Every interactive or meaningful element has a stable ID (the same string on Windows, Android and iOS), a spoken name, a role, and, where it changes, a live status.
In the rules, "must", "should", and "may" have the meaning given in how to read a spec.
Color contrast
Text needs 4.5:1. Icons, focus rings, status dots, and graphics people need to see need 3:1. Color is never the only signal: every status also has words. The full pair table is in the visual system.
| Rule |
ID |
| Text pairs must reach 4.5:1 and meaningful non-text pairs 3:1, in both modes. |
UX-A-001 |
| Every status must have words as well as color. |
UX-A-002 |
Accent text, icons, and dots must use accent-ink (#ED7600 in dark mode, #A55200 in light mode). |
UX-A-003 |
Text on the accent fill must be #1F1B16 (5.86:1). The app must not use white on the accent (2.92:1). |
UX-A-004 |
| The app must follow the system dark or light setting. |
UX-A-005 |
| When a Windows contrast theme is on, the app must use system colors. |
UX-A-006 |
Fixes made to pairs that failed:
| Problem |
Before |
Fix |
| Connections tab dot, light mode |
Amber placeholder at 1.57:1 |
accent-ink #A55200, 5.20:1 on bg |
| Lit button on the controller drawing, light mode |
Accent on the body at 1.39:1 |
Dark outline around the lit key |
| Keys against the body, both modes |
1.2:1 |
Thin muted outline on every key, dashed outline on free keys |
| Rule |
ID |
| The lit key must have a dark outline. Every key must have a thin muted outline, and free keys a dashed one. |
UX-A-007 |
| The Buttons list must carry the same information as the drawing in text, so the drawing is never the only way to know a mapping. |
UX-A-008 |
Edge cases
In light mode the accent fill is 2.75:1 against the background. A primary button is identified by its label and shape, never by fill alone (UX-V-005).
Tap and click targets
| Rule |
ID |
| Anything you can tap, click or focus must have a hit area of at least 48 by 48 px. |
UX-A-009 |
| The visual may be smaller than the hit area. The More button is a 40 px circle inside a 48 px target. |
UX-A-010 |
| Text links must have a 48 px tall hit area. |
UX-A-011 |
| Neighboring targets must be at least 8 px apart. |
UX-A-012 |
Edge cases
WCAG 2.2 AA asks for 24 px. Material asks for 48 dp and Apple for 44 pt. The app goes beyond all of them.
IDs, names, and roles
ID naming scheme
An ID is {Area}{Element}{Role} in PascalCase. IDs never change with language or state. Names are translated and may include state.
|
Windows (WPF or WinUI) |
Android (Compose) |
iOS (SwiftUI) |
| ID (tests, tools) |
AutomationProperties.AutomationId |
Modifier.testTag with testTagsAsResourceId = true |
.accessibilityIdentifier |
| Name (read out) |
AutomationProperties.Name |
contentDescription or semantics |
.accessibilityLabel |
| Hint |
AutomationProperties.HelpText |
onClickLabel, stateDescription |
.accessibilityHint |
| Heading |
AutomationProperties.HeadingLevel |
semantics { heading() } |
.accessibilityAddTraits(.isHeader) |
| Live status |
AutomationProperties.LiveSetting="Polite" and LiveRegionChanged |
liveRegion = LiveRegionMode.Polite |
Announcement notification |
| Hide decoration |
AutomationProperties.AccessibilityView="Raw" |
clearAndSetSemantics {} |
.accessibilityHidden(true) |
| Part |
Values |
| Areas |
Setup, Nav, Menu, Ride, Buttons, Mapping, Connections, Settings, Help, Credits, Support, Dialog |
| Roles |
Button, Tab, Item, Link, Toggle, Field, Status, Title, Row, Card, Image |
Repeated items add a key after an underscore: ButtonsRow_RB, FunctionItem_ShiftUp, MappingItem_{id}.
| Rule |
ID |
| Every interactive or meaningful element must have an ID, a name, and a role. |
UX-A-013 |
IDs must follow {Area}{Element}{Role} in PascalCase, with the same string on every platform. |
UX-A-014 |
| IDs must not change with language or state. |
UX-A-015 |
A mapping's ID key must be the mapping's GUID (see CFG-008), never its name. |
UX-A-016 |
| The app must hide decorative elements from assistive technology. |
UX-A-017 |
Core IDs
| ID |
Role |
Name read out |
NavRideTab, NavButtonsTab, NavConnectionsTab |
Tab (1 to 3 of 3) |
"Ride", "Buttons", "Connections" (plus ", Zwift not connected" when the dot shows) |
MenuButton |
Button, expands |
"More: settings, help, credits, support" or "Close menu" |
MenuSettingsItem, MenuHelpItem, MenuCreditsItem, MenuSupportItem |
Menu item |
"Settings", "Help and feedback", "Credits", "Support this project" |
NavBackButton |
Button |
"Back" |
SetupPressAnyButtonStatus |
Live status |
"Got it. That's your left bumper" |
SetupContinueButton, SetupPairBluetoothButton |
Button |
"Continue", "Pair a new Bluetooth controller" |
SetupZwiftStatus |
Live status |
"Waiting for Zwift" or "Zwift is connected" |
RidePageTitle |
Heading 1 |
"Ready when you are" |
RideControllerCard |
Group |
"Your Xbox controller, awake and connected" |
RideStats |
Group |
"12 rides together, 1,086 shifts, riding since September" |
RideZwiftStatus |
Live status |
"Zwift is connected to Voltage Gamepad" or "Zwift isn't connected yet" |
RideStartButton |
Button |
"Start riding" |
RideLastPressStatus |
Live status |
"Shift up, right bumper" |
RideWindowSizeGroup |
Radio group |
"Window size: Full, Float, Mini" |
RideStopButton |
Button |
"Stop riding" |
ButtonsMappingPicker |
Button, opens |
"Mapping: Climbing, unsaved changes" |
ButtonsSaveButton, ButtonsSaveAsButton |
Button |
"Save", "Save as new" |
ButtonsRow_{input} |
Button |
"Right bumper: shift up" |
ButtonsControllerImage |
Image |
"Your controller. Right bumper selected. X and Menu are free" |
FunctionItem_{function} |
Radio |
"Shift up, harder gear, selected" |
ConnectionsZwiftCard, ConnectionsShowMeHowButton |
Group, Button |
Per screen |
DialogPrimaryButton, DialogSecondaryButton, DialogCancelButton |
Button |
Per dialog |
| Rule |
ID |
| Screens must use the core IDs above where the element exists. |
UX-A-018 |
| The example numbers in the name column (12 rides, 1,086 shifts) are examples. The app must show only real values (UX-P-005). |
UX-A-019 |
Reading and focus order
| Rule |
ID |
| Focus order and screen reader reading order must follow a left-to-right reading layout: what sits further left comes first, then top to bottom. The table below gives the order for each tab placement. |
UX-A-020 |
| Each screen must have one level 1 heading (the screen title). Card titles must be level 2. |
UX-A-021 |
| Dialogs and menus must trap focus. Esc must close them, and focus must return to what opened them. |
UX-A-022 |
| Every focusable element must show the 3 px focus ring. Arrow keys must move in the menu and tab bar. Enter must activate. |
UX-A-023 |
| The Buttons screen must tell you its input rule: "Press a button on your controller to see it light up. Tap a row to change what it does." |
UX-A-024 |
| Tab placement |
Order |
| Sidebar or rail on the left (desktop, Android tablet) |
Tabs, More button, screen content |
| Tab bar at the top center (iPad) |
Tabs, More button, screen content |
| Bottom bar (phone, narrow desktop window) |
More button, screen content, tabs |
Live updates without noise
| Rule |
ID |
| The app must announce changes, not repeats: Zwift connected or lost, controller asleep or back, and the first press in setup. |
UX-A-025 |
| While riding, shift announcements must be optional: Settings has "Announce each shift", off by default. |
UX-A-026 |
| The app must always announce connection problems. |
UX-A-027 |
| The app must never move focus to announce something. |
UX-A-028 |
Example: on the setup screen your first press is announced ("Got it. That's your left bumper"). Your next ten presses are not.
Text size and motion
| Rule |
ID |
| Layouts must work at 200% text size (Windows text size, Android font scale, iOS Dynamic Type). Rows grow taller and nothing truncates. |
UX-A-029 |
| The riding readout must wrap to two lines before it shrinks. |
UX-A-030 |
| With reduce-motion on, the menu and sheets must appear without sliding, and the "waiting" pulse must be static. |
UX-A-031 |
How to check
| Platform |
Tools |
| Windows |
Accessibility Insights for Windows (FastPass) and Narrator on every new screen. The UI tests locate elements by ID. |
| Android |
Accessibility Scanner and TalkBack. |
| iOS |
Accessibility Inspector and VoiceOver. |
| Design |
A contrast check against the token table and an annotated reading order before a screen is built. |
| Rule |
ID |
| Every new screen must pass a contrast check and have a written reading order before I build it. |
UX-A-032 |
| I must check every new Windows screen with Accessibility Insights and Narrator. |
UX-A-033 |