dequelabs / dequelabs/axe-core
title-only check approximates accessible description; build a proper accessibleDescription method
- 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
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