Visible labels and spoken commands

Say what you see: the idea behind label in name

People who control a device by voice read the label on screen and speak it: "click Reserve". The software looks for a control whose accessible name matches. WCAG 2.1 success criterion 2.5.3 says that for components with a visible text label (or an image of text), the accessible name must contain the visible text. The name can be longer. Best practice is to start it with the visible words.

Capitalization and most punctuation are ignored, so a visible "First name:" matches the name "first name". The criterion does not apply to a control with no visible text label, but such a control still needs an accessible name under 4.1.2.

How the two drift apart

• A developer adds aria-label with a more "helpful" phrase that leaves out the visible word. The attribute overrides the visible text for assistive technology.
• Hidden text is placed before the visible words ("Delete" becomes "Remove item, Delete"). That can still pass, but speech matching works best when the visible words come first.
• The visible text is an abbreviation or symbol and the name spells out something different.
• Icons that are symbols rather than words ("B", ">", "+") are not labels for this criterion; give them a name that describes the function.

What it looks like on civic sites (ADA angle)

Government forms are full of short button labels: Reserve, Look up, Pay, Apply, Renew. When a screen reader or voice user hears or says one thing and the control is named another, the task stalls at the last step. This is also a place where automated tools report a pass (every button has a name), while a person speaking the visible label gets no response. Relevant background: WCAG 2.1 AA and the ADA.

Web code: campsite, voter lookup, bill pay

Campsite reservation button

<button aria-label="Book a site">Reserve</button>

<button>Reserve</button>
<!-- or, with more detail that still starts with the visible word: -->
<button aria-label="Reserve campsite 12">Reserve</button>

Voter registration lookup

<label for="vr-zip">ZIP code</label>
<input id="vr-zip" aria-label="Postal area" inputmode="numeric">

<label for="vr-zip">ZIP code</label>
<input id="vr-zip" inputmode="numeric" autocomplete="postal-code">

Bill link whose name replaces the visible words

<a href="/pay" aria-label="Account balance">Pay bill</a>

<a href="/pay">
  Pay bill
  <span class="visually-hidden">for account ending 4471</span>
</a>

Mobile code: SwiftUI and Jetpack Compose

// SwiftUI
Button("Renew book") { renew() }
  .accessibilityLabel("Extend loan")

// SwiftUI
Button("Renew book") { renew() }
  .accessibilityLabel("Renew book, The Grapes of Wrath")

// Jetpack Compose
Button(
  onClick = { reserve() },
  modifier = Modifier.semantics { contentDescription = "Book campsite" }
) { Text("Reserve") }

// Jetpack Compose
Button(
  onClick = { reserve() },
  modifier = Modifier.semantics { contentDescription = "Reserve campsite 12" }
) { Text("Reserve") }

If you do not override the name at all, both platforms use the visible text, which is the simplest way to comply.

Checking it with a voice and a speaker

1. Turn on voice control (Voice Control on iOS and macOS, Voice Access on Android, or Dragon on desktop) and speak the exact visible label of ten controls. Each should activate.
2. Inspect the accessible name in the browser accessibility tree or with the screen reader. Confirm the visible words appear in it, ideally at the start.
3. Search code for aria-label and aria-labelledby on elements that also have visible text, and compare the two by eye.
4. Tools: automated rules can flag a mismatch between visible text and name for some patterns. Treat that as a lead, not a verdict.

Common slips

• Rewording the visible label in aria-label "for clarity".
• Putting the visible word at the end of a long name, which makes voice matching less reliable.
• Using a different number or unit in the name ("3 items" vs "three items").
• Treating "(required)" or format hints as part of the label. They may be left out of the name, but required state must still be exposed to assistive technology.

Ship it when

• Every visible text label is contained in its control's accessible name.
• Overrides with aria-label exist only where they add words after the visible text.
• You have spoken the labels aloud with voice control on at least one platform.

Sources

• Understanding SC 2.5.3: Label in Name (W3C), opens in a new tab
• 28 CFR Part 35, Subpart H: Accessibility of Web Information and Services (eCFR), opens in a new tab

Standard version: WCAG 2.1 (W3C Recommendation, 5 June 2018), as named in the Title II web rule. This page is for informational purposes only and is not legal advice. For binding requirements, refer to the official ADA statute and regulations, and ask a lawyer how they apply to you.