mgifford/accessibility-skills/charts-graphs

Charts and Graphs Accessibility Skill

Canonical source: examples/CHARTS_GRAPHS_ACCESSIBILITY_BEST_PRACTICES.md in mgifford/ACCESSIBILITY.md

This skill is derived from that file. When in doubt, the example is authoritative.

Apply these rules when creating or reviewing any data visualisation. Only load this skill if the project contains charts or graphs.

Core Mandate

Charts must communicate their information and support their intended tasks without requiring users to perceive a particular colour, inspect a visual position, use a pointer, or understand an unexplained graphic. Accessibility is not one long alt label — use a layered presentation: an understandable visual, a concise summary, structured data when needed, and accessible controls for any interaction. The appropriate depth depends on purpose — a single-value sparkline and an exploratory dashboard don't need the same amount of description.

Start with the user's question before choosing a chart type: what should the chart answer, which comparison/trend/distribution matters, do users need the conclusion, exact values, or exploration? The accessible summary should answer the same question as the visual — don't describe every visual property while omitting the conclusion.

Severity Scale (this skill)

The Layered Information Model

Provide the layers users need, without duplicating everything into one long accessible name:

1. Title — identifies the subject
2. Context — scope, dates, units, population, filters
3. Summary — the main trend, comparison, or finding
4. Structured detail — exact values/categories/relationships when needed
5. Source and methodology — lets users evaluate and reuse the information
6. Interaction feedback — active filters, selections, loading, errors

Do not put every layer into an image's alt, an SVG <title>, or one aria-label — long accessible names are difficult to review and navigate.

Choosing a representation:

SVG is not automatically accessible, and canvas is not automatically inaccessible — the implementation must expose equivalent information regardless of rendering technology. If a table or short paragraph answers the question more clearly than a chart, use the simpler representation.

Critical: Every Chart Must Have a Text Alternative

A chart with no text alternative is Critical — blind users and users with images disabled receive no data at all.

Simple chart — concise `alt` for one clear takeaway:

<figure>
  <img src="/assets/charts/quarterly-sales.svg"
       alt="Sales increased each quarter, from $1.4 million in Q1 to $2.3 million in Q4."
       width="800" height="450">
  <figcaption>Quarterly sales for 2025. Values are in Canadian dollars.</figcaption>
</figure>

Write the alternative for the chart's purpose in context, not a visual inventory. Avoid: "Chart", "Sales chart", a filename, every axis tick, or an interpretation the data doesn't support. If the surrounding article already states the same finding, keep alt concise rather than forcing a duplicate announcement.

Complex chart — short identification + visible long description:

<figure>
  <img src="/assets/charts/visitors-by-sector.svg"
       alt="Line chart of accessibility adoption from 2019 to 2024, described below."
       width="900" height="520">
  <figcaption>
    <h2>Accessibility adoption by sector, 2019 to 2024</h2>
    <p>Adoption increased in all three sectors. Government remained highest,
    rising from 42% to 78%. Corporate adoption rose from 28% to 61%, with its
    largest increase in 2021. Non-profit adoption rose from 19% to 47%.</p>
    <details><summary>View annual values</summary><!-- data table --></details>
    <p>Source: Annual organizational survey. Percentages are rounded.</p>
  </figcaption>
</figure>

Make the detailed description visible — this benefits magnification, text-to-speech, translation, and unfamiliar-subject users, not just screen reader users. aria-describedby can associate an image with a plain-text description, but AT generally flattens referenced content into one string — headings, lists, and tables lose navigable structure. Do not use `aria-describedby` as the only route to a structured long description.

Serious: Provide Structured Data When Users Need Values

<details>
  <summary>View data for monthly website visitors</summary>
  <table>
    <caption>Monthly website visitors, January to March 2025</caption>
    <thead>
      <tr><th scope="col">Month</th><th scope="col">Visitors</th><th scope="col">Change</th></tr>
    </thead>
    <tbody>
      <tr><th scope="row">January</th><td>12,400</td><td>Not applicable</td></tr>
      <tr><th scope="row">February</th><td>15,800</td><td>27.4%</td></tr>
    </tbody>
  </table>
</details>

There is no standards-based threshold requiring a table after a particular number of series or points — provide structured data when exact values or independent comparison are part of the task. For very large datasets, offer a usable filtered table plus a downloadable open format (CSV) — a download does not replace an on-page summary. State how missing, suppressed, estimated, or rounded values are represented.

Serious: SVG Charts

Atomic SVG image — when the chart is exposed as one image:

<figure>
  <svg role="img" aria-labelledby="sales-title" aria-describedby="sales-summary" viewBox="0 0 640 360">
    <title id="sales-title">Quarterly sales for 2025</title>
    <!-- Visual chart content -->
  </svg>
  <figcaption id="sales-summary">
    Sales increased in every quarter, from $1.4 million in Q1 to $2.3 million
    in Q4. Values are in Canadian dollars.
  </figcaption>
</figure>

Do not put `role="list"`/`role="listitem"` on descendants of an SVG whose root has `role="img"` and expect them to remain navigable — the image role represents an atomic graphic and its children are presentational; this is not just inconsistently supported, it contradicts the role="img" semantics.

Structured or interactive SVG — when individual parts must be browsed or operated, do not flatten the whole graphic with role="img". The ARIA Graphics Module defines structured graphic roles, but support must be tested with the project's actual AT combinations. Even when a structured SVG accessibility tree works, still provide a visible HTML summary and data presentation — don't force users to traverse every bar, point, and grid line to discover the conclusion. See skills/svg/SKILL.md for decorative-group exclusion, unique IDs, and DOM order.

Serious: Canvas-Based Charts Require Accessible Alternatives

<canvas> draws pixels — the bitmap exposes no visual objects, labels, or relationships to AT. A chart rendered to canvas with no alternative is Serious at minimum, Critical if it's the only presentation of the data.

<figure>
  <canvas id="regional-sales-chart" width="800" height="450"
          role="img" aria-label="Q2 sales by region"
          aria-describedby="regional-sales-summary">
    Q2 sales by region. A summary and data table follow.
  </canvas>
  <figcaption id="regional-sales-summary">
    The West had the highest Q2 sales at $510,000. The East had the lowest at
    $280,000. A complete data table follows.
  </figcaption>
</figure>

Always keep the visual canvas synchronized with an adjacent summary/table — this is the primary, most reliable access route, more so than canvas ARIA alone. Canvas fallback content (focusable descendants mapping interactive regions) requires one-to-one state/focus/hit-region/keyboard synchronization — prefer visible HTML controls outside the canvas unless there's a tested reason to use the fallback subtree. Do not put essential detail only in canvas-drawing commands or library configuration.

Library-specific notes: Chart.js exposes accessibility hooks but its built-in table is a starting point, not a full solution — supplement with an adjacent summary. D3 renders SVG by default, not canvas — use SVG patterns above. Highcharts/Vega-Lite/Observable Plot each have their own accessibility module — check current docs and always supplement with an adjacent data table regardless of library claims. Treat generated ARIA as code your team owns — inspect the browser accessibility tree, don't rely on marketing descriptions.

Serious: Colour and Visual Encoding

Do not use colour as the only way to identify a series, state, threshold, or region — roughly 8% of males and 0.5% of females have colour vision deficiency. Combine colour with: direct text labels, different line styles, point shapes, fill patterns, symbols, boundaries, or explained position.

<svg width="0" height="0" aria-hidden="true" style="position:absolute">
  <defs>
    <pattern id="pattern-dots" patternUnits="userSpaceOnUse" width="6" height="6">
      <circle cx="2" cy="2" r="1.5" fill="currentColor"/>
    </pattern>
  </defs>
</svg>
<rect fill="url(#pattern-dots)" x="50" y="50" width="60" height="100"/>

Colorblind-safe palettes:

• [Okabe-Ito](https://jfly.uni-koeln.de/color/) — recommended default for

quantitative data: #E69F00, #56B4E9, #009E73, #F0E442, #0072B2, #D55E00, #CC79A7, #000000

• [ColorBrewer](https://colorbrewer2.org/) — sequential (ordered data),

diverging (data with a meaningful centre), or qualitative (categorical) palettes with a colorblind-safe filter

Do not rely on a palette merely being described as "colour-blind safe" — test the complete chart including line weight, point size, overlapping marks, selected states, and every supported theme. Simulation is a review aid, not a substitute for standards testing. Avoid: red/green as sole differentiators (the most common CVD combination); saturated rainbow/jet palettes (poor perceptual ordering, uniform to many CVD users).

Contrast: text labels ≥4.5:1 (or 3:1 for large text); required non-text graphical information ≥3:1 against adjacent colour. Decorative grid lines don't become subject to 3:1 merely for appearing in a chart — test only visual information actually required to understand or operate the chart.

Serious: Separate Data Browsing from Actions

Most chart values do not need to be interactive. Provide a summary/table for browsing; reserve buttons, links, and checkboxes for actual actions (filtering, selecting, drilling down). Use native HTML controls for legends and filters:

<fieldset class="series-controls">
  <legend>Data series shown</legend>
  <label><input type="checkbox" name="series" value="2024" checked> 2024 sales</label>
  <label><input type="checkbox" name="series" value="2025" checked> 2025 sales</label>
</fieldset>

Do not add every data point to the page's Tab sequence — a chart with hundreds of focus stops is reachable but not practically operable.

Serious: Keyboard Interaction