On this page

Guides

Accessibility

tally-charts aims at WCAG 2.2 AA. This page describes what the library does for keyboard and screen-reader users, what it checks automatically, what is decorative on purpose, and what is still checked by hand before a release. The names on this page are part of the public API described in Stability.

What CI checks #

  • axe (@axe-core/playwright 4.13.0) with the wcag2a, wcag2aa, wcag21a, wcag21aa, wcag22aa and best-practice tags on every Storybook story, in the light and the dark theme. Zero violations is the gate.
  • Rendered text contrast: axe reports SVG text as "incomplete", so an e2e test measures every text run the library renders against the pixels behind it, at rest and with a point active: 4.5:1, or 3:1 for large text.
  • Token contrast (unit tests on theme.css): toned text at 4.5:1 on the surface and the tooltip, every mark at 3:1 (the soft accent through its outline), and every sequential level (6 tones × 2 themes × 5 levels) with its cell text at 4.5:1, neighbouring levels 1.3:1 apart and the top level at 3:1 against the surface.
  • Reflow at 320 CSS px (the width a 1280px window has at 400% zoom): no story scrolls the page sideways; no SVG text overlaps other text in its chart or leaves the viewport; and heatmap cells and headers, legend labels and pills don't clip their text. The heatmap may scroll inside its own container.
  • Forced colors (Chromium emulation): HTML marks keep visible fills, heatmap levels differ by border, chart text follows the system text color, and focus rings stay visible.
  • Keyboard: focus, arrow keys, Home/End, Enter, Escape and the announcements, per chart.

Keyboard model #

Charts #

Everything built on <Chart>.

  • A chart is one tab stop: the element with role="application" and aria-roledescription="chart" inside the <figure>. A <Chart> whose marks register no points (only lines, areas or a grid) is not a tab stop.
  • Tabbing in shows the first point: its tooltip appears and it is announced. A click that focuses the chart doesn't.
  • ←/→ (and ↑/↓) move to the previous or next point; Home and End go to the first and last. Charts whose points form stacks or rows move in two dimensions: DotHistogram walks bins with ←/→ and stacks with ↑/↓; StripPlot walks a row with ←/→ and changes rows with ↑/↓.
  • Enter or Space selects the active point when the chart has onSelect.
  • Escape clears the active point. It is only consumed when something is active, so an enclosing dialog still closes. Escape also closes a tooltip opened by hovering, wherever focus is, and the pointer can move onto a hover tooltip without closing it (WCAG 1.4.13).
  • The widget is described by the chart's description and a hint: "Use arrow keys to move between points, Home and End for first and last, Escape to clear.", plus " Press Enter to select." with onSelect, but only while the active point (the first one, before any is active) can be selected: a point with selectable: false never promises Enter. keyboardHint replaces it as is (to translate it); keyboardHint="" turns it off.

RunwayChart #

  • Without onSelect the rows are a plain list of listitems: there is no tab stop and no keys.
  • With onSelect the rows container is a listbox and one tab stop. The focused row is aria-activedescendant; real focus stays on the container. Tabbing in resumes at the existing cursor (set by earlier keys or a click), else the selected row, else the first. Hovering a row highlights it but does not move the cursor; pressing a row moves the cursor there, and a click that focuses the list does not scroll it. The cursor follows its row by id when rows change; if that row is gone it falls back to the first row.
  • Up and Down move one row, Home and End go to the first and last, PageUp and PageDown move five. Enter or Space selects the focused row. Escape clears the active row, and is only consumed when one is active. Keys with Alt, Ctrl or Cmd pass through.

Heatmap #

  • The grid is one tab stop (a roving tabindex), on the first data cell until another cell had focus.
  • Arrow keys move one cell, Home and End to the start and end of the row, Ctrl+Home and Ctrl+End (or Cmd) to the first and last cell of the grid, PageUp and PageDown five rows.
  • The column totals row and the row total column are cells too: arrow keys reach them, and focusing one clears the active cell. Enter or Space selects a data cell with onSelect; on a total it does nothing.
  • Escape clears the active cell, only when one is active.
  • In a container too narrow for the columns, the grid scrolls sideways inside a role="group" named after the title ("Heatmap" without one), which then becomes a tab stop of its own so keyboard users can scroll it. There are then two tab stops: the scroll region first, then the grid.

What a screen reader gets #

Charts #

  • figure, named by title or by the element aria-labelledby points at (one of the two is required in the types, and aria-labelledby wins when both are set), and described by description.
  • Inside it, the chart widget (application, role description "chart"), with the same name and the description plus the keyboard hint. Screen readers switch to focus mode there, so the arrow keys reach the chart.
  • An aria-live="polite" region that announces each point the keyboard moves to: "{series}, {n} of {total}, {label}". The position counts within the point's series, and the series is left out when there is only one.
  • A visually hidden data table after the widget, outside it, so browse mode reads it: captioned with the title (or dataTable.caption), with column headers, the first column as row headers, and "no value" for empty cells.
  • The SVG and the HTML overlay (tooltips and callouts) are aria-hidden. A pinned callout says nothing to a screen reader: put the same facts in the title, the description or the data.
ChartAnnouncement, from the Storybook stories
BarChart, <Chart> + Bars"1 of 12, Jul 6, 37.5%"
ComparisonBars"1 of 6, Labor, plan $640, actual $1,060, +$420"
RankedBars"1 of 5, Labor overruns, $31.2K"; with meta: "1 of 5, Tyler Brooks, $2.6K, 9 jobs"
WaterfallChart"2 of 7, Labor overruns, −1.6 pts · $7.7K, running total 36.4%"
BridgeChart"2 of 5, After discount, $1,000, −$260 discount"
DotHistogram (toneBy thresholds)"Critical, 1 of 6, #5600, 3.1%"
StripPlot"Estimated, 1 of 29, #5900, 5.2 h"
WaffleColumns"1 of 8, Aug 3, $9.8K"
LineChart"9 of 9, Dec, 36.0% on the current path, 37.6% with changes"
LineChart on a time axis"1 of 90, Jan 1, 2026, 32.0% Margin this quarter"

A mark's ariaLabel (or a chart's own text) is the {label} part; the chart adds the series and the position around it.

The default headers of that table are the field names in sentence case ("grossMargin" reads "Gross margin") or the series labels. dataTable={{ caption, columns }} renames them, keyed by the default header: columns: { Week: 'Week ending' }.

A chart with two value axes (y2) is still one tab stop with one set of points, and those come from the marks. Screen-reader and keyboard users only get both series if you give them both: in the segments and ariaLabel of the mark that registers the points, which also fills the tooltip, and in dataTable.columns. See Two value axes.

Heatmap #

A grid named by title or aria-labelledby and described by description. The first row holds the column headers: the corner, named by rowLabel (default: the row field in sentence case), the column names and, with totals (on by default), a "Total" header (totalLabel). With totals, the next row is the column totals, headed by totalLabel, and ends with the grand total. Every data row starts with its row header and, with totals, ends with its total. A cell reads as its value with its row and column header, e.g. "Dallas, Labor, $14.8K"; a missing value reads "No data".

RunwayChart #

A list (or, with onSelect, a listbox) named by title or aria-labelledby and described by description. Each row is announced by its label followed by its status, e.g. "Work account Runs out Fri 03:24 Resets Mon 09:21"; with onSelect each is an option with aria-selected, named from those two parts. The strips, the time axis and the legend swatches are hidden from assistive technology (the legend text is read): the per-account detail (name, detail text, run-out, reset, projected share at reset, status) is in the hidden data table, and the status text carries the same facts. Icons are hidden. A custom status replaces the text that is read; a string also becomes the table's Status, and null leaves the row with its label only. A disconnected row reads "Disconnected".

Forced colors. Level cells become steps of the text colour (CanvasText at rising fill opacity) with CanvasText outlines; the locked hatch stays visible; empty cells are outlined; the runs-out dot is Highlight; the selected row has a dashed CanvasText outline and the keyboard-focused row a solid Highlight outline. The "reset" label is drawn only to the right of the reset tick, with a halo in the surface colour, and is omitted when it would not fit; the status says the same.

Small pieces #

  • Meter: role="meter" with aria-valuemin, aria-valuemax, aria-valuenow and an aria-valuetext such as "34.0%, target 38.0%".
  • RangeMeter: role="img" named "{label}: {value} against {reference}".
  • ShareBar: with the list, a group named by label; the bar is hidden and each row reads "Internal links 2,711 46%" (the middle dot is hidden). Without it (legend={false}) there is no group: the bar is role="img" named "{label}: Internal links 46% (2,711), Search 34% (1,968), …". Numbers use the format prop.
  • ZoneMeter: role="meter" with aria-valuemin, aria-valuemax and aria-valuenow (pinned to the range) and an aria-valuetext such as "4.1 s, Poor"; above the range "6.4 s, above 6.0 s, Poor", below it "-1.0 s, below 0.0 s, Good", and "No data" for a missing value (the value and the range end are formatted with the same format). The break labels under the track are hidden.
  • Sparkline: role="img" named by label, and "{label}: No data" with no valid value. It has no tab stop and no tooltip, so put the numbers somewhere else on the page if they matter.
  • Delta: the arrow is hidden; a visually hidden "Up", "Down" or "No change" precedes the value.
  • Legend: a list; swatches are hidden.
  • Stat, InlineBar, DotCount, TooltipPill: their text.

Decorative on purpose #

These carry no information that isn't also available as text, in the tooltip or in the data table, so they keep their low contrast (WCAG 1.4.11 applies to what is needed to understand the content):

  • grid lines and row dividers;
  • bar, meter and inline-bar tracks, the bar of a ShareBar that has its list, and the tick labels of a ZoneMeter (the value text already names the zone);
  • the light tint between hatch stripes, and the faded end of hatch-fade bars;
  • soft dots (the faded non-peak periods in WaffleColumns): any dot drawn soft is decorative emphasis and gets no 3:1 outline;
  • dimmed marks while another one is active;
  • bands (a likely range), regions (forecast shading) and the column highlight;
  • dotted connectors between waterfall steps;
  • the dashed border of an empty heatmap cell, and the glow on its top cell.

The vivid palette #

data-ch-palette="vivid" (opt-in, light theme only) switches to a brighter --ch-warn, --ch-gain and --ch-neutral. They give up the 3:1 non-text contrast the default tokens keep. Against the light surface #fafafa:

TokenDefaultVivid
--ch-warn#be802f 3.18:1#f1a23b 2.02:1
--ch-gain#3a93b8 3.33:1#4fa3c7 2.72:1
--ch-neutral#8e8e95 3.12:1#a3a3ab 2.40:1

None of the three reaches 3:1 (WCAG 1.4.11), so a mark in one of these tones can be hard to see for low-vision users. Use the palette only where the data is also carried by text, labels or the data table, or where the marks are outlined. Toned text keeps its 4.5:1 (it is mixed with the ink), and the dark theme and forced colors are unchanged. CI checks the text and axe on the Vivid BarChart story; the 3:1 token tests cover the default palette only.

Known limits #

  • In forced colors, the gaps between ShareBar segments and between ZoneMeter zones keep the parts apart. Segments and zones keep distinct system colors (forced-color-adjust: none), and the ZoneMeter marker uses Highlight.
  • Forced colors are verified only in Chromium's emulation. Windows with a real high-contrast theme (Edge, Firefox) should be checked by hand.
  • No screen reader runs in CI. The checklist below is run by hand before a release.
  • Font sizes are in px: browser zoom scales them, but a user's default font size has no effect. Zoom itself isn't tested; 320 CSS px, the width a 1280px window has at 400% zoom, passes the reflow test.
  • Row labels cut with an ellipsis keep the full text in an SVG <title>, but chart text takes no pointer events (so labels never block the bars under them), so browsers don't show it on hover. The tooltip and the data table have the full text.
  • In a very narrow chart, BridgeChart shows only some column totals and no notes, and a pinned pill can take three lines. The tooltip and the data table have everything.
  • data-ch-seq-tone must sit on, or below, the element that sets data-ch-theme. If it sits above a theme boundary, the ramp is computed in the outer theme.
  • ComparisonBars chooses its layout from the measured width. On a server-rendered page a narrow screen first renders columns at the 640px default and switches to stacked after hydration. To avoid the jump, pass initialWidth or an explicit layout.
  • At very narrow widths an axis may keep only its first label. Every value stays reachable through the tooltip and the data table.
  • Hatched marks (hatch fill) and the soft accent get their 1px outline in both themes: on bars, on accent-soft dots that aren't drawn soft, and on legend swatches.
  • Screen readers differ in how they enter and announce role="application". The checklist covers VoiceOver; NVDA and JAWS should be checked the same way.
  • A hover tooltip has pointer-events: auto, so the pointer can rest on it (WCAG 1.4.13: hoverable). While it's visible it covers the hit areas of neighboring points under it; to reach a covered point, move the pointer off the tooltip or use the keyboard. Custom tooltip content (content render prop) is rendered into the chart's overlay, which is aria-hidden, so a screen reader doesn't read it. What it announces comes from the live region and the data table, and interactive elements in custom content can't be reached with the keyboard. Accepted under WCAG 1.4.13. Pinned callouts are click-through.
  • Heatmap breaks (and heatmapLevel) and RunwayChart breaks are lower-inclusive only: a value equal to an edge falls into the higher level. thresholds() has inclusive: 'upper'; these two have no such option yet. An inclusive option is planned for 1.x.

Manual checklist #

Before each release:

  1. Run pnpm test:e2e; it must pass (axe, contrast, reflow, forced colors, keyboard).
  2. In Storybook, Tab through Reference/Estimate vs actual, Reference/Drill columns, Reference/Where it leaks and Reference/Margin outlook with the keyboard only: every chart is one tab stop, the first point and its tooltip appear on focus, arrows, Home, End, Enter and Escape work, and the focus ring is visible.
  3. Hover a bar in Reference/Last 12 weeks, press Escape: the tooltip closes.
  4. Zoom the browser to 400% (or a 320px-wide window) on every reference story: nothing overlaps, the page doesn't scroll sideways, and the heatmap scrolls inside its card.
  5. On Windows, turn on a high-contrast theme and look at the same stories in Edge.
  6. Run the VoiceOver script below in Safari on macOS (VO = Control+Option).

VoiceOver script #

Open each story with iframe.html?id=…&viewMode=story so only the story is on the page. The wording below is what the library provides; VoiceOver's own words for roles ("web application", "chart") and its pauses vary by version. A step passes when the same information comes in the same order.

LineChart: reference-margin-outlook--light

  1. VO+Right to the chart. Expected: "Margin outlook, figure" (or similar), then the description "Margin reaches 36.0% by December on the current path and 37.6% with your changes, still under the 38% target."
  2. Tab into the chart. Expected: "Margin outlook, chart" with the description and "Use arrow keys to move between points, Home and End for first and last, Escape to clear.", then "1 of 9, Apr, 32.9% Actual".
  3. Press →. Expected: "2 of 9, May, 34.2% Actual".
  4. Press End. Expected: "9 of 9, Dec, 36.0% on the current path, 37.6% with changes".
  5. Press Escape, then VO+Right past the chart. Expected: the table "Margin outlook" with columns "Month, Actual, Current path, With your changes, Likely range"; row "Apr" reads "32.9%" then "no value" three times.

RankedBars: reference-drill-columns--light

  1. Tab to the first chart. Expected: "Leakage by cause, chart", "Use arrow keys to move between points, Home and End for first and last, Escape to clear. Press Enter to select.", then "1 of 5, Labor overruns, $31.2K".
  2. Press ↓. Expected: "2 of 5, Material variance, $18.7K".
  3. Press Enter. Expected: the row gets the selection highlight and the story's output reads "Selected cause: Material variance".
  4. Tab to the last chart. Expected: "1 of 5, Tyler Brooks, $2.6K, 9 jobs".

Heatmap: reference-where-it-leaks--light

  1. Tab into the grid. Expected: "Profit leaked by branch and cause, grid" (or "table"), the description, then "Dallas, Labor, $14.8K" (row, column, value; VoiceOver may add the position).
  2. Press →. Expected: "Materials, $7.9K".
  3. Press ↑. Expected: the column total, "Total, Materials, $18.7K".
  4. Press Ctrl+End. Expected: "Houston, Total, $21.9K".
  5. Press Ctrl+Home. Expected: "Total, Labor, $31.2K".
  6. Press ↓ to "$14.8K" and Enter. Expected: "Selected: Dallas · Labor" in the story's output.
  7. Shrink the window to 320px wide and Tab from the grid backwards: the scroller is a stop of its own, "Profit leaked by branch and cause, group"; with VO, Shift+scroll or arrow keys scroll it.