taler-android

Android apps for GNU Taler (wallet, PoS, cashier)
Log | Files | Refs | README | LICENSE

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.