When should you NOT use Accessible SVGs?

Do not add aria-label to a decorative SVG already inside a button with visible text — it creates redundant announcements. Avoid embedding critical data only inside SVG paths with no text alternative — screen readers cannot parse drawn content.

When is Accessible SVGs the right choice?

Add aria-hidden="true" to purely decorative SVGs — icons inside labelled buttons, dividers, background flourishes. Add role="img" and aria-label (or +) to informative SVGs that convey meaning independently. For interactive SVGs (charts, maps), add focusable elements with keyboard handlers and descriptive labels.

← Back to glossary

Accessible SVGs

Accessibility SVG1.1 Intermediate

debt(d4/e3/b3/t6)

d4 Detectability Operational debt — how invisible misuse is to your safety net

Closest to 'default linter catches the common case' (d3) +1. Tools like axe and Lighthouse (listed in detection_hints) can detect missing aria-hidden on decorative SVGs and missing role/title on informative SVGs automatically. However, they cannot fully distinguish decorative from informative SVGs without developer intent, and interactive SVG patterns (charts, keyboard handlers) require manual review. The automated coverage is good but not complete, so d4.

e3 Effort Remediation debt — work required to fix once spotted

Closest to 'simple parameterised fix' (e3). The quick_fix shows that decorative SVGs need a single attribute (aria-hidden=true), and informative SVGs need role=img + aria-label or title+desc — these are small, localized additions per SVG element. However, if there are many SVGs across templates, it touches multiple files but each fix is mechanical. Interactive SVGs requiring full ARIA widget patterns push higher, but the common cases are e3-level fixes.

b3 Burden Structural debt — long-term weight of choosing wrong

Closest to 'localised tax' (b3). This applies only to the web context and affects individual SVG elements in templates/components. It's not an architectural choice — it's a per-element concern. However, every new SVG added to the project needs to follow the pattern, creating a small ongoing tax for front-end developers. It doesn't shape the system's architecture or affect non-UI code.

t6 Trap Cognitive debt — how counter-intuitive correct behaviour is

Closest to 'notable trap' (t5) +1. The misconception is telling: developers assume SVG icons are automatically read correctly by screen readers, when in fact browsers may read file paths or class names. This is a genuine surprise — the 'obvious' approach (just drop in an SVG) produces bad results silently. The additional trap that <title> must be the first child of <svg> to work, and that different browsers handle SVG accessibility inconsistently, adds to the cognitive load. It contradicts the mental model from <img alt='...'> where there's one clear pattern, pushing this to t6.

About DEBT scoring → scored by claude-opus-4-6 · 2026-05-06 · reviewed by human

Also Known As

SVG accessibility aria-hidden SVG

TL;DR

Decorative SVGs need aria-hidden=true; informative SVGs need role=img and aria-label or title+desc elements.

Explanation

Decorative (icon in labelled button): aria-hidden=true. Informative (standalone chart): role=img, aria-labelledby pointing to title inside SVG. Interactive: full ARIA widget pattern. Inline SVG: add title as first child, desc for description, aria-labelledby to title id. Img tag SVG: alt attribute works normally.

Watch Out

⚠ An unlabelled SVG icon inside a button with no other text produces an announced button name of "" — screen readers read the button as completely empty, making it unusable without a mouse.

Common Misconception

✗ SVG icons are automatically read correctly — without aria-hidden, browsers may read file paths or class names.

Why It Matters

SVGs used as images without title and desc elements are either announced as their filename or completely skipped by screen readers, depending on the browser. Inline SVGs used for interactive controls — charts, diagrams, custom checkboxes — require ARIA roles and keyboard handlers that are easy to omit. Decorative SVGs should explicitly have aria-hidden='true' to avoid cluttering the accessibility tree. Getting this right matters most for data visualisations, where the information exists only in the graphic.

Common Mistakes

No aria-hidden on decorative SVGs
No alt on informative SVGs
title not first child of svg

Avoid When

Do not add aria-label to a decorative SVG already inside a button with visible text — it creates redundant announcements.
Avoid embedding critical data only inside SVG paths with no text alternative — screen readers cannot parse drawn content.

When To Use

Add aria-hidden="true" to purely decorative SVGs — icons inside labelled buttons, dividers, background flourishes.
Add role="img" and aria-label (or <title>+<desc>) to informative SVGs that convey meaning independently.
For interactive SVGs (charts, maps), add focusable elements with keyboard handlers and descriptive labels.

Code Examples

💡 NoteThe bad button has an SVG icon with no label; a screen reader announces "button" with no name. The fix adds aria-label to the button so the action is clearly announced.

✗ Vulnerable

<button><svg><!-- icon --></svg>Search</button>

✓ Fixed

<button><svg aria-hidden="true" focusable="false"><!-- icon --></svg>Search</button>
<svg role="img" aria-labelledby="t"><title id="t">Monthly Revenue</title></svg>

References

https://www.w3.org/TR/SVG-access/