Visible text and the computed accessible name can disagree

What it is

The button says “Next.” The reader says “Continue,” or just “button.” Accessible name mismatch is that split: the string on screen and the string AccName wrote into the accessibility tree are not the same. The algorithm is not broken. Two pipes were fed different material — paint gets visible text, the name gets attributes and hidden nodes.

This is not a slogan about gathering name, role, and state. Role can be right and state complete while the name still fails to match the words the user is looking at.

Why it happens

Once an override wins, visible text is no longer a name source. aria-label holds an internal English code, labelledby points at hidden developer copy, icon fonts turn the “text” into a glyph, CSS content draws letters that often never enter the computation. The reverse is also true: an icon is visible and the computed name lives on aria-label; they were never meant to match. The danger is the author thinking they do.

The second layer is user strategy. Screen-reader users build a model from the computed name. People who can see the screen — magnification, voice control, low-vision users checking against the words — issue commands and do verification from visible text. When the strings diverge, one control becomes two objects under two strategies. Voice control is brittle here: the user speaks the word on screen, and the matcher looks in the computed name.

Studying it

Build a visible-versus-computed table; do not only listen. For each interactive control record: the words in a screenshot, Computed Name in the pane, NVDA speech, and whether speaking the visible words with OS voice control hits the control. Hunt three classes: icon buttons, links with aria-label, menu items whose visible text is truncated or replaced by CSS.

Independent variables: presence of an override, whether visible text is a substring of the computed name (label-in-name), pseudo-elements / icon fonts. Dependent variables: string equality, voice-control hit rate, which string participants repeat when they paraphrase the control.

Where it stops holding

Intentional elaboration is not a failure: visible “12” with computed “12 items, cart” is fine if the visible substring is still in the name. Icon-only controls must live on the computed name; mismatch is then a design, not a defect — the defect is an empty name or icon-btn-32. Under localization, a missed translation of aria-label can align in one language and split in another. Letters painted on a canvas are neither DOM text nor a name source; both columns of the table go empty.

Applying it

• Visible words should appear as a substring of the computed name; when overriding, put those words inside aria-label or the labelledby target, and do not invent an internal code.
• Do not use a CSS pseudo-element or icon font as the only visible label and expect the computed name to follow.
• Icon-button tooltips or adjacent text and the aria-label should be the same sentence, not Chinese on the surface and English in the attribute.
• How to check: two columns, screenshot text versus Computed Name. On unequal rows, speak the left column with Voice Control / Voice Access. A miss, or a reader speaking a different phrase, means name and paint have already split.

Related

• Same group: J5.10.1 Accessible names are computed from multiple sources in a fixed, overridable order · J5.10.3 State changes must be written to the accessibility tree, not only to appearance · J5.10.4 Custom widgets often ship a role but omit the matching state properties
• Nearby: J3.12 Voice control name matching · J5.04 Voice control
• Search terms: accessible name mismatch · label in name · computed name