dequelabs / dequelabs/axe-core

title-only check approximates accessible description; build a proper accessibleDescription method

Open
#5,212 0 comments 0 reactions 0 assignees View on GitHub
fix tech debt
Dominant language
JavaScript
Stars
7.5k
Forks
933
Avg merge
2d 23h
Merged PRs (30d)
17

Description

_Follow-up from review of #5170 ([comment](https://github.com/dequelabs/axe-core/pull/5170#discussion_r3578289391))._

The `title-only` check (`lib/checks/label/title-only-evaluate.js`) decides whether an element's only labeling comes from `title`/`aria-describedby`:

```js
function titleOnlyEvaluate(node, options, virtualNode) {
const labelText = labelVirtual(virtualNode);
const title = titleText(virtualNode);
const ariaDescribedBy = virtualNode.attr('aria-describedby');

return !labelText && !!(title || ariaDescribedBy);
}
```

This is buggy (pre-existing, not introduced by #5170): it treats the mere *presence* of an `aria-describedby` attribute as an accessible description, without resolving the referenced elements or checking whether they actually contribute any text. An `aria-describedby` pointing at a missing/empty element yields no description, but this check still counts it.

Rather than patch the heuristic, we should build a proper `accessibleDescription` method — analogous to the existing accessible-name computation (`accessibleText`) — per the [accname](https://www.w3.org/TR/accname-1.2/) description algorithm, and use it here.

**Tasks**
- Add an `accessibleDescription` helper (alongside accessible-name computation in `commons/text`) implementing the accessible description algorithm.
- Update `title-only` (and other consumers of the `title`/`aria-describedby` presence heuristic) to use it.
- Cover with unit tests, including empty/missing `aria-describedby` references.

Contributor guide

Open the contributing guide

Research direction

Start with lib/checks/label/title-only-evaluate.js and the existing accessible-name computation in commons/text. Trace other consumers of the title/aria-describedby presence heuristic, then review the referenced accname description algorithm. Done means an accessibleDescription helper is used by those consumers and unit tests cover empty and missing aria-describedby references.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
accessibility
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.