# Accessibility

What keyboard and screen-reader users get from each component today, and what is left to you.

KPIs and tables are HTML, so assistive technology can read them as they are. Charts are drawn on a canvas, which holds no data a screen reader can reach, so each chart needs a text alternative from you. This page lists what the components do today, gaps included.

## Charts

- **The title and description are text.** The card’s `title` is a heading and its `description` is a paragraph. Both are read aloud.
- **The plot is named, not described.** It is a `<canvas role="img">` named after the card’s title and description. A screen reader hears that name, not the values.
- **The plot needs a pointer.** Tooltips and click handlers work with a mouse or touch. Nothing inside the plot takes keyboard focus.
- **Series differ by colour only.** On line charts, the `dashedLine` field option adds a second cue.
- **Charts animate when they draw**, whatever the reader’s reduced-motion setting. [Chart.js options](/docs/theming.md#chartjs-options) shows how to turn that off.

## KPIs

The title, the number and the change are all text. The change carries a plus or minus sign as well as a colour and an arrow, so it does not depend on colour.

## Tables

- Tables are a real `<table>` with column headers. The pivot table and the heat map add row headers.
- A sortable column header is a button with a spoken label, and its column carries `aria-sort`.
- The pagination buttons are labelled “First page”, “Previous page”, “Next page” and “Last page”.
- An expandable pivot row is a button with `aria-expanded`. Every heat map cell is a button that takes focus, whether or not you pass `onCellClicked`.

Three gaps:

- The sort and pagination labels are in English, whatever language the provider is set to.
- `onRowClicked` needs a pointer. Rows do not take focus.
- Each body cell holds a copy button, shown on hover and whenever focus is in its cell: a table of many cells is many keyboard stops.

## The card: menu, picker and states

- **Export menu.** It works from the keyboard, with the keys below. Its button is named after the chart (“Chart menu: Revenue by region”) in the provider’s language. Its entries are yours to change: see [Card menu](/docs/card-menu.md).
- **Maximised view.** It opens as a modal dialog named after the chart’s title, with a “Minimize” button. Focus is not put back on the card when it closes.
- **Granularity picker.** A menu button that shows the current value, with the same keys as the export menu.
- **States.** The empty and error states are text. The loading skeleton has none, and a change of state is not announced: the card has no live region.
- **Focus.** Buttons keep the browser’s default focus ring.

## Keyboard

| Key | Where | What it does |
|---|---|---|
| `Tab`, `Shift` + `Tab` | Anywhere | Moves between the controls of a card: export menu, granularity picker, column headers, cell copy buttons and pagination. |
| `Enter` or `Space` | Export menu button, granularity picker | Opens the menu and moves focus to its first item. |
| `↓`, `↑` | Open menu | Moves to the next or previous item, wrapping at the ends. |
| `Home`, `End` | Open menu | Moves to the first or last item. |
| `Enter` | Menu item | Chooses it. |
| `Esc` | Open menu | Closes it and returns focus to its button. |
| `Esc` | Maximised view | Closes it. |
| `Enter` or `Space` | Column header | Sorts ascending, then descending, then clears the sort. |
| `Enter` or `Space` | Expandable pivot row | Opens or closes the row. |
| `Enter` or `Space` | Heat map cell | Calls `onCellClicked`, if you passed one. |

## What to do in your app

1. Give every chart a `title`, and state its main finding in `description`. “Revenue rose 37% from January to June” is read aloud; the bars are not.
2. Offer the numbers as a table near each chart. The same fields and rows work in a [table component](/docs/tables.md).
3. Never make a click handler the only way to reach something. Add a link, button or filter outside the chart that does the same.
4. Check the contrast of your [theme](/docs/theming.md): text tokens against their background, and neighbouring chart colours against each other.
5. Turn animation off for readers who ask for reduced motion, as in [Chart.js options](/docs/theming.md#chartjs-options).
