Static Site Generators in Production

Accessible SVG Diagrams on Static Sites

Technical documentation leans on diagrams: request flows, deployment pipelines, architecture overviews, before-and-after charts. On a static site these are increasingly inline SVG, because inline SVG can follow the page's theme, scale without blurring and weigh a few kilobytes. It also starts with no accessibility at all. An inline svg element without a role or a name is either ignored by screen readers or read as a stream of disconnected labels — "Build", "Deploy", "200 ms", "CDN" — with no indication of how they relate.

The reference site from Accessibility for Static Sites has 410 diagrams. The first audit found 288 with no accessible name, 74 with a name but no description, and 31 whose labels failed contrast in the dark theme. This guide covers the markup each diagram needs, how to write a description that carries the diagram's information, when a diagram needs a table beside it, and the build-time check that keeps new diagrams compliant.

Prerequisites

  • Diagrams authored as inline SVG in Markdown, MDX or components, or generated at build time.
  • A site palette defined as CSS custom properties or known hex values, so diagram colours can follow the theme.
  • A post-build HTML check step, such as the one in Validating HTML Output in CI.

What the Audit Found

ProblemDiagramsHow found
No role and no accessible name288axe svg-img-alt (with role) and manual (without)
Name but no description74Build script
Description restates the title only29Manual review
Labels below 4.5:1 in dark theme31axe in dark mode
Labels drawn on transparent background46Visual check in dark mode
Information only in colour (red/green bars)12Manual review

axe-core's svg-img-alt rule only checks SVGs that already have role="img"; an SVG with no role is not reported at all. That is why the largest category was invisible to the automated scan.

Number of diagrams affected by each accessibility problem Horizontal bars. No role and no name 288 diagrams. Name but no description 74. Labels drawn on a transparent background 46. Labels failing contrast in the dark theme 31. Description that only restates the title 29. Information conveyed only by colour 12. Diagram problems found in the first audit No role or name 288 No description 74 Transparent background 46 Dark theme contrast 31 Desc restates title 29 Colour-only meaning 12
410 diagrams audited; most problems came from a diagram template that had never had accessibility attributes.

Step 1: The Markup Every Diagram Needs

The pattern that works consistently across NVDA, JAWS and VoiceOver is a figure containing the SVG, with the SVG marked as a single image and labelled by its own title and desc, and a visible figcaption. The SVG element's attributes are:

role="img"
aria-labelledby="deploy-flow-title deploy-flow-desc"
viewBox="0 0 760 240"

And its first two children are:

<title id="deploy-flow-title">How a pull request reaches production</title>
<desc id="deploy-flow-desc">Five steps: push, build in CI, deploy a preview, run checks against it,
  then promote the same build to production. A failed check stops the flow at step four.</desc>

role="img" tells assistive technology to treat the whole SVG as one image instead of reading every text node. aria-labelledby pointing at both title and desc is more reliable than relying on the SVG's native title handling, which differs between browsers. IDs must be unique on the page; a page with two diagrams generated from the same template will otherwise have two deploy-flow-title IDs, and screen readers will read the first diagram's name for both. The site's generator prefixes every ID with a per-diagram slug for that reason.

Step 2: Write Descriptions That Carry the Information

A description is not a caption and not an alt text for decoration. It should let someone who cannot see the diagram learn what a sighted reader learns from it. The reference site's writing rules for desc:

  • Say what it shows, not what it looks like. "Build time fell from 4 minutes 10 seconds to 70 seconds after caching" rather than "Two blue bars, one longer".
  • Follow the reading order. For flows, list the steps in order and say where they branch.
  • Include the numbers. A chart's description states its values; a reader using a screen reader should not have to guess them from the prose.
  • Keep it under about 60 words. Longer than that, the diagram needs a text alternative in the page.
Comparison of a weak and a useful description for the same deployment diagram Two panels. The weak description says a diagram with five boxes and arrows, in blue and green. The useful description lists the five steps in order, push, build, preview deploy, checks and promote, and says that a failed check stops the flow before production. A weak description and a useful one Weak "Diagram with five boxes" "arrows between them" "blue and green" describes shapes Useful push, build, preview deploy checks, then promote a failed check stops it describes what happens
The useful version is longer by about twenty words and is the only one that conveys what the diagram is for.

Step 3: Add a Text Alternative for Complex Diagrams

Some diagrams hold more than 60 words can carry: an architecture diagram with fifteen components, a comparison matrix, a chart with twenty data points. For those, the information belongs in the page as HTML — a table, a list or a paragraph — and the desc points to it: "Architecture of the build and deploy system; each component is described in the table below." On the reference site, 38 diagrams got a table, either visible directly under the figure or inside a details element labelled "Diagram as a table" for diagrams where a visible table would duplicate the prose. Tables help sighted readers too: several readers mentioned copying numbers from them.

Step 4: Never Rely on Colour Alone

Twelve charts used red and green bars to mean "before" and "after" with no other marker. That fails WCAG 1.4.1 for anyone who cannot distinguish those colours — about 8% of men of Northern European descent have some form of red-green colour vision deficiency. Every chart now has a legend with text, value labels on the bars, and before-and-after pairs in a fixed order so position also encodes the series. A quick check is to view the page through Chrome DevTools' "Emulate vision deficiencies" panel with deuteranopia selected; if the chart still makes sense, it passes.

Step 5: Keep Labels Readable in Both Themes

Diagrams drawn with fixed colours look right in the light theme and break in the dark one: dark grey labels on a transparent background become dark grey on near-black. The reference site fixed this in two parts. Every diagram got a full-canvas background rectangle in the palette's surface colour, so labels always sit on a known background. Then the dark theme remaps the palette's exact hex values with attribute selectors, so the surface becomes dark, neutral text becomes light, and brand colours keep their saturation:

[data-theme='dark'] figure [fill='#ffffff'] { fill: #111827; }
[data-theme='dark'] figure [fill='#1f2937'] { fill: #e5e7eb; }
[data-theme='dark'] figure [fill='#556071'] { fill: #a3adbd; }
[data-theme='dark'] figure [stroke='#d9e2ef'] { stroke: #374151; }

Because the selectors match exact values, diagrams must use only palette colours. One off-palette grey added to "fix" a contrast warning stays light on the dark background and fails again — the build check in the next step rejects colours outside the palette for that reason.

How each palette role is remapped between light and dark themes A matrix of four palette roles. The canvas surface is white in light and near black in dark. Body labels are dark grey in light and light grey in dark. Muted labels are slate in light and lighter slate in dark. Brand fills such as blue and green keep their colour in both themes, with lightened text variants in dark. Palette remapping in the dark theme Role Light theme Dark theme Rule Canvas surface white near black always remapped Body labels dark grey light grey always remapped Muted labels slate light slate always remapped Brand and data fills saturated saturated text variants lightened
Only roles that sit behind or form text are remapped; data colours stay saturated so charts keep their meaning.

Step 6: Check Diagrams at Build Time

A post-build script walks every figure svg in the HTML and fails on the mechanical problems, so the manual review can focus on description quality:

for (const svg of root.querySelectorAll('figure svg')) {
  const id = svg.getAttribute('id') || svg.querySelector('title')?.id || '(unnamed)';
  if (svg.getAttribute('role') !== 'img') fail(`${file}: ${id} missing role="img"`);
  const ids = (svg.getAttribute('aria-labelledby') || '').split(/\s+/).filter(Boolean);
  const title = ids.map(i => root.getElementById(i)).find(e => e?.tagName === 'TITLE');
  const desc = ids.map(i => root.getElementById(i)).find(e => e?.tagName === 'DESC');
  if (!title?.text.trim()) fail(`${file}: ${id} has no title`);
  if (!desc || desc.text.trim().split(/\s+/).length < 8) fail(`${file}: ${id} needs a desc of at least 8 words`);
  if (desc && title && desc.text.trim() === title.text.trim()) fail(`${file}: ${id} desc repeats title`);
  for (const c of svg.querySelectorAll('[fill],[stroke]'))
    for (const v of [c.getAttribute('fill'), c.getAttribute('stroke')])
      if (v && v.startsWith('#') && !PALETTE.has(v.toLowerCase())) fail(`${file}: ${id} off-palette colour ${v}`);
}

It also checks for duplicate IDs across the page. On 1,140 pages it runs in about 4 seconds.

Measured Impact

MeasureBeforeAfterTool
Diagrams with role and name122 of 410410Build check
Diagrams with a useful description48410Build check + review
Dark theme label contrast failures310axe-core 4.10, dark
Colour-only charts120Manual, vision emulation
Complex diagrams with a table038Manual
Build check time—4 sCI logs

Four NVDA users who reviewed a sample of 20 diagrams rated 17 as "understandable without seeing it" after the changes, against 2 before.

Pitfalls & Rollback

  • No role on the SVG. axe does not report it; the build check must.
  • Shared IDs from a template. Prefix every title and desc ID per diagram.
  • Describing appearance. Describe information, in reading order, with the numbers.
  • Off-palette colours. They escape the dark theme remap.
  • Rollback: the attributes and descriptions are additive; reverting the build check alone leaves the improved diagrams in place.

Conclusion

An inline SVG diagram is accessible when it is one named image with a description that carries its information, sits on its own background in a palette the dark theme can remap, and does not rely on colour alone — with a table beside it when the information is too much for a description. A build check over the HTML enforces the mechanical parts, which on the reference site moved 288 unnamed diagrams to zero.

FAQ

Should a diagram be an inline SVG or an img with an SVG file?

Both can be accessible. An img element with an SVG source takes its accessible name from the alt attribute and is simpler to get right. Inline SVG is needed when the diagram must follow the page theme through CSS or contain links, and then it needs role img with title and desc, or a labelled figure. Choose inline only when you need what it offers.

What should the desc of a diagram say?

What a sighted reader learns from the diagram, in the order they would learn it. For a flow, list the steps and what connects them. For a chart, state the values or the comparison it makes. Avoid describing shapes and colours unless they carry meaning. If the description would run past a few sentences, put a table or list in the page and keep desc short.

Do screen readers read text inside an SVG?

If the SVG has role img, screen readers treat it as a single image and read only its accessible name and description, not the text elements inside. Without role img, some screen readers read every text node in source order, which for a diagram is often a jumble of labels. Setting role img and writing a proper description gives a predictable result.

How do I keep diagram labels readable in dark mode?

Define diagram colours through the same palette as the rest of the site and remap them in the dark theme with CSS, so backgrounds become dark and neutral text becomes light. Give every diagram a full-size background rectangle so labels are never drawn directly on the page background, and check label contrast in both themes like any other text.

Filed underHow-tos