SiteLint documentation and guidelines

Accessible name should match the control’s label

Description

This rule checks whether an element’s accessible name (the text announced by screen readers) is similar enough to its visible label (the text sighted users see). Exact matching is not required. Small differences – such as punctuation, case changes, extra keyboard shortcuts (e.g., Ctrl+S), or minor word variations – are allowed as long as the meaning remains clear. However, completely different or contradictory names will be reported as an accessibility issue.

Disabilities impacted

  • Visual impairments: screen‑reader users depend on the accessible name. A name that differs significantly from the visible label creates confusion and misidentification of controls.
  • Cognitive disabilities: consistent and predictable labeling helps users understand and interact with interface elements.
  • Motor impairments: voice‑command users often speak the visible label. If the accessible name is too different, the command may fail or target the wrong element.

Why it matters

Aligning the accessible name with the visible label – without requiring exact string equality – ensures that all users can reliably identify and activate controls. The rule tolerates minor, non‑semantic differences (like trailing keyboard hints or different punctuation) while flagging real mismatches. This balance improves accessibility without penalising harmless variations.

Coding problems and solutions

Common coding problems

  • Substantially different text: the visible label says Email Address, but aria-label says Your Email.
  • Missing or misleading words: the label says Delete post, the accessible name says Remove item (different actions).
  • Hidden text overriding the visible meaning: visible label Save, but accessible name includes only hidden text like Save document as PDF.

How to fix it

Ensure names are similar, not necessarily identical

The rule accepts minor differences. For example, these are all considered valid:

  • Punctuation or case: label Search → aria-label="Search!"
  • Keyboard shortcuts: label Save → aria-label="Save Ctrl+S"
  • Phone number formatting: label (555) 123-4567 → aria-label="5551234567"
  • Word overlap >75%: label Submit form → aria-label="Submit the form now"
Allowed example (similar, not exact)
<label for="email">Email Address</label>
<input type="email" id="email" aria-label="Email address (required)">
Incorrect example (too different)
<label for="email">Email Address</label>
<input type="email" id="email" aria-label="Your contact info">

Do not hide essential parts of the accessible name

If you use visually hidden text (e.g., .sr-only) to extend the accessible name, it should still be semantically similar to the visible label. Avoid replacing the visible meaning entirely.

Acceptable use of hidden text
<button>
  Save
  <span class="sr-only">the document</span>
</button>
The accessible name becomes “Save the document” – similar to the visible “Save”.
Incorrect (hidden text contradicts the visible label)
<button>
  Delete
  <span class="sr-only">Cancel</span>
</button>

Match ARIA labels with visible labels (within reason)

When using aria-label, keep the core wording similar to the visible text.

Acceptable (synonyms, slight rephrasing)
<button aria-label="Search the site">Search</button>
Unacceptable (completely different action)
<button aria-label="Go">Search</button>

Known limitations

  • Fuzzy matching thresholds: the rule uses a 75% word overlap and 60% hybrid similarity. Very short strings (1‑2 words) may still be flagged if they don’t share core terms.
  • Dynamic content: if both the visible label and aria-label update together, the rule re‑evaluates automatically. Stale mismatches will be reported.
  • Complex widgets: for custom controls with multiple parts, ensure the computed accessible name (visible text + aria-label / aria-labelledby) is reasonably similar to the primary visible label.
  • Browser & screen reader differences: the accessible name computation may vary slightly, but the rule follows the standardised algorithm. Cross‑platform testing is still recommended.

Resources

Rule

  • Audit: Accessibility
  • Standard: WCAG 2.1 / 2.2
  • Level: A
  • Success Criteria: 2.5.3 Label in Name (A), 4.1.2 Name, Role, Value (A)
  • ID: accessible-name-mismatch-element-description