English
Site menu

svg-text-alternative-quality

<svg> text alternative must be appropriate (manual review)

manualWCAG 1.1.1 (A)confidence: mediumseverity: minorperceivable

Flags applicable <svg> graphics with a detected text alternative for human review of appropriateness.

Applies to. Applies to inline <svg> elements that already carry a text alternative: non-empty <title> or <desc> text, a non-empty aria-label, or an aria-labelledby that resolves to non-empty text. <desc> counts here as something to review even though it never contributes to the accessible name: that distinction is svg-text-alternative-present's. The element must be included in the accessibility tree, and role="presentation"/"none" takes it out of scope unless it is focusable, which restores its role.

Expectation. Human review is required to confirm that the provided text alternative is accurate and appropriate.

What a finding reports.

  • hasNonEmptyTitle: true when the first <title> inside the <svg> has text.
  • hasNonEmptyDesc: true when the first <desc> inside the <svg> has text.
  • ariaLabel: the aria-label value, or null when there is none.
  • ariaLabelledBy: the aria-labelledby value, the ids it points to, or null when there is none.
  • ariaLabelledByText: the text of the elements aria-labelledby points to, up to 120 characters. Only looked up when there is no aria-label; null otherwise or when it resolves to nothing.
  • reasonCode: IMAGE_ONLY_CONTROL_CONTENT when the <svg> is the only content of a link or button (no text and no other image in it), so its text alternative is the control's name, with controlContent naming the control's role (link or button); TEXT_ALTERNATIVE_REVIEW otherwise.

These data.details fields help to read and reproduce a finding. Apart from reasonCode and the few fields Output schema names as stable, they are not a stable contract: a field may be renamed or dropped in a minor release, so don’t build on them.

Examples

can't tell
<svg role="img" viewBox="0 0 24 24"><title>Growth chart</title><path d="M0 0h24v24H0z"/></svg>

A <title> is present — worth confirming "Growth chart" describes what the chart actually shows, not just that it's a chart.

n/a
<svg role="img" viewBox="0 0 24 24"><path d="M0 0h24v24H0z"/></svg>

No <title>/<desc> text, aria-label, or resolved aria-labelledby exists to review; that's svg-text-alternative-present's failure instead.

How to check

When this rule can’t decide, it reports cantTell and leaves the question to a person. Each question it can ask is listed here under its reason code, with the steps to answer it. A finding carries the same steps as howToCheck, in the scan’s language. See Output schema.

IMAGE_ONLY_CONTROL_CONTENT

  1. Find the link or button the report names; its only content is this svg.
  2. Activate the control and note what it does or where it goes.
  3. Read the control's name in the Accessibility pane of the developer tools (it comes from the svg's text alternative), or Tab to it with a screen reader.
  4. Compare: does the name say what the control does ("Search", "Close menu"), not just what the icon looks like ("magnifying glass")?

Pass. The control's name says what it does or where it goes.

Fail. The name describes the picture, is vague, or is wrong for the action, which fails WCAG 1.1.1 (and leaves the control's purpose unclear).

TEXT_ALTERNATIVE_REVIEW

  1. Look at the graphic the report names and note what it shows (an icon, a logo, a chart and its data).
  2. Read its text alternative from the report (title, desc, aria-label or aria-labelledby text), or in the Accessibility pane of the developer tools.
  3. If the text alternative only names the graphic, as is common for charts and diagrams, the details may be given elsewhere: in a caption, text or a table next to it, or a link beside it. That counts only if a screen reader user can find it from the graphic and it gives everything the graphic shows.
  4. Compare: does the text say what the graphic shows or means? If the graphic is decorative, it should instead be hidden (aria-hidden="true").

Pass. The text alternative conveys what the graphic shows, or names it and a description a screen reader user can reach from it gives the rest, or the decorative graphic is hidden from assistive technology.

Fail. The text alternative is wrong, vague (such as "image" or "icon") or leaves out what the graphic conveys, and no description reachable from it gives that, which fails WCAG 1.1.1.

View source