Visible name and accessible name must match
Aliases: visible vs accessible name · label in name · name matching
What it is
The button is printed “Send”; the name in the tree is submitForm. The user says “tap Send” from the print; the matcher compares against the name in the tree, and misses. For voice control to work, the visible name and the accessible name have to be the same words. That is a demand of the matcher, not a naming aesthetic.
Why it happens
Users build the utterance by look → speak; the engine string-matches the accessible name (often requiring the visible words as a substring — label-in-name). The two pipes start in different places: the eye samples visible text, the matcher samples the name in the tree. Filling that name with an internal field, an English identifier, or a different marketing line hands the matcher a dictionary the user never saw.
The failure is concrete: speaking the visible words does nothing; speaking the internal name would hit, but the user cannot guess it. Screen-reader users sometimes hear the computed name; voice-control users, by default, do not — they only see those few characters, so the visible words must appear in the string being matched.
Studying it
Build a pair: visible text identical to the accessible name, versus visible “Send” with a different name. Turn on Voice Control / Voice Access, allow only words that can be seen, and record hits and misses.
Independent variables: whether the visible words are contained in the accessible name, whether the languages match, whether another name overrides them. Dependent variables: hit rate when the visible label is spoken as-is, whether a rephrase happens to hit the internal name.
Do not hint “try English.” The measurement is whether seeing Chinese leads to speaking Chinese.
Where it stops holding
An icon plus visible text, or a longer name that still contains the visible words (“Send order” contains “Send”), usually still hits — match is not full-string equality. When the system overlays numbers, users can hit a control without the name; that is a fallback, not proof that names may be arbitrary. Several controls sharing the same visible words will collide in the matcher — that is disambiguation, and it comes after each visible/accessible pair already agrees.
Applying it
- Start the accessible name with the on-screen words, or include them as-is; do not override with a second internal copy deck.
- When visible copy changes, change the name with it. Do not leave Chinese on the glass and old English in the tree.
- How to check: speak the visible text on the button. If it misses, inspect the name in the tree — if the visible words are not in that string, voice control will refuse the utterance by design.