controls-without-accessible-names.md (3099B)
1 # Controls a screen reader cannot announce 2 3 > **Fixed on master** (checked 2026-11-08, commit `24f7b249`). See [STATUS.md](STATUS.md) for the fix and the test that pins it. 4 5 **Severity:** low individually, and an accessibility bug collectively: a 6 cashier using TalkBack cannot tell these controls apart from each other. 7 8 **Where:** `merchant-terminal/src/main/java/net/taler/merchantpos/` -- 9 `config/ConfigFragment.kt` (the password-visibility toggle), `MainActivity.kt` 10 (the navigation-drawer button) and the "Remember password" checkbox on the 11 login form. 12 13 **Found by:** `pos-simulator`, the `unnamed-control` oracle, which fires on 14 every screen the suite visits. 15 16 ## What happens 17 18 Three clickable controls publish no text and no content description, and 19 contain no labelled node for the framework to borrow one from, so TalkBack 20 announces each of them as an unlabelled button: 21 22 | Screen | Control | Position in a 2560x1600 window | 23 | --- | --- | --- | 24 | login (manual) | the eye icon that reveals the password | (2472, 800) | 25 | login (manual) | the "Remember password" checkbox | (88, 936) | 26 | every screen with a top bar | the navigation-drawer button | (64, 112) | 27 28 The drawer button is the one that matters most: it is the only way to reach the 29 history, the settings and the other order screen, and it is announced as 30 nothing at all. 31 32 The checkbox is a subtler case. Its label *is* on screen -- "Remember 33 password" sits next to it -- but as a sibling rather than inside it, so the 34 semantics do not merge and the two are announced separately: a piece of text, 35 and an unlabelled checkbox. A sighted user reads them as one control; a screen 36 reader does not. 37 38 ## Why 39 40 Each is an `IconButton` or a `Checkbox` whose content has 41 `contentDescription = null`: 42 43 ```kotlin 44 // ConfigFragment.kt, the password field's trailing icon 45 IconButton(onClick = { passwordVisible = !passwordVisible }) { 46 Icon(imageVector = ..., contentDescription = null) 47 } 48 49 // MainActivity.kt, in each of the three top-bar variants 50 IconButton(onClick = { scope.launch { drawerState.open() } }) { 51 Icon(Icons.Default.Menu, contentDescription = null) 52 } 53 ``` 54 55 `contentDescription = null` is the right thing for an icon that is decoration 56 beside a label. It is wrong for an icon that *is* the control. 57 58 ## Reproducing it 59 60 ```bash 61 cd /tmp/taler-pos-sim/driver && . ../env.sh 62 python3 probe.py # on any screen; unnamed controls are listed 63 python3 suite.py accessibility_names 64 ``` 65 66 `probe.py` prints a trailing section for every clickable node with no 67 accessible name, which is the same check the oracle runs. 68 69 ## The fix 70 71 A `contentDescription` on each icon, from a string resource -- `menu_order`, 72 `config_password` and friends already exist, so this is three strings and three 73 lines. For the checkbox, the fix is to put the label inside the clickable 74 instead: wrap the row in `Modifier.toggleable(...)` with the `Text` inside it, 75 so the semantics merge and the whole row is one announced control with one tap 76 target. 77 78 No patch here: the strings have to be written and translated, which is not a 79 mechanical change.