Markup
<figure class="tray-chart" id="harvest">
<figcaption class="tray-chart__title">Caviar collected by month</figcaption>
</figure>
<script>
TrayUI.chart(document.getElementById('harvest'), {
type: 'bar', unit: ' kg',
labels: ['Mar', 'Apr', 'May'],
series: [{ name: 'Collected', values: [6, 14, 22] }],
summary: 'Bar chart of caviar collected by month. The most, 22 kg, came in May.'
});
</script>Or put the same object as JSON in data-chart and add data-tray="chart".
| Option | Values |
|---|---|
type | bar, line, area, donut, radial, radar |
labels, series | The categories, and one or more { name, values } |
unit | Text set after every value: ' kg', '%' |
stacked | Stack the series of a bar or area chart |
horizontal | A ranked list of bars, for one series |
step | Draw a line or area as steps |
max, height | The top of the scale; the plot height in px |
label | 'peak' (default) labels the extreme of a single series; 'none' turns that off |
table | false leaves out the "Show the figures" table |
summary | The sentence a screen reader hears for the chart. Write it: say what the chart shows. |
Colour
- One series is drawn in
ink, or inaccenton an ink card. A single series never takes a data colour (the Entity Colour Rule). - Several series take
data-1todata-4in that order. A colour belongs to its series; filtering one out must not repaint the others. A fifth series is "Other", inink-hint. - Text is never set in a series colour. Values, labels and legends stay in ink; a swatch beside them carries the identity.
- Two of the four data colours are below 3:1 on light grounds, so every chart with several series has a legend, a tooltip and a table view.
Marks
Bars are 24px wide at most, with 4px top corners and a 2px gap between neighbours. Lines are 2px. Areas are the line plus a 14% fill. Donut segments are separated by a small gap. Nothing is outlined or shadowed, and there is never a second value axis: two measures of different scale go in two charts.
Interaction
Pointing at the plot shows a crosshair or a highlighted column and a tooltip with every series at that point. On a donut the centre shows the segment pointed at.
Choosing the form
- Change over time: line (trend), area (volume), bar (separate periods).
- Parts of a whole: stacked bar over time; donut for one moment and at most five parts.
- A single share or score: radial, or just a Figure in a card.
- Ranking: horizontal bars.
- Several measures of one thing: radar, two series at most.
In React
The React package draws its charts with Recharts instead of this script, in the same frame and with the same rules: Chart takes the options above as props, and ChartContainer frames any Recharts chart. Both come from trayui-react/charts.
Accessibility
- The figure is named by its
figcaption, and the drawing isrole="img"named by thesummary. Write the summary: without it a screen reader hears a long list of every value, made up by the script. - The plot of a bar, line or area chart takes focus:
ArrowLeftandArrowRightmove through the points,HomeandEndjump to the ends,Escapeclears, and the tooltip shows the values at that point. On a donut or a radar the arrow keys walk the segments or the spokes, and the centre or the tooltip shows the one in focus. What the keys reach is said through a polite live region that sits in the figure beside the drawing, since whatever is inside arole="img"is not read. - A radial chart and horizontal bars take focus too, so their
summaryis read whenTabreaches them. They have nothing to walk: every figure is written beside its bar, in the middle of the ring or in the key. - Colour never names a series alone: several series come with a legend, a donut with a key table, and "Show the figures" opens a real table with scoped heads. Set
labelHeadto name its first column.
Do and don't
- Do label the extreme directly and leave the rest to the tooltip; never a number on every point.
- Do give every chart a title that states the subject and a
summary. - Don't use a pie for more than five parts, a rainbow, a gradient, or 3D.
- Don't use data colours anywhere outside a chart.