|
| 1 | +export const meta = { |
| 2 | + title: "Accessibility", |
| 3 | + description: "Explanation of accessibility features provided by the Highcharts module and how to customize them.", |
| 4 | + slug: "/foundations/data-visualization/accessibility/", |
| 5 | +}; |
| 6 | + |
| 7 | +import Image from "next/image"; |
| 8 | +import Highcharts from "highcharts"; |
| 9 | +import HighchartsAccessibilityModule from "highcharts/modules/accessibility"; |
| 10 | +import HighchartsReact from "highcharts-react-official"; |
| 11 | +import { applyPasteHighchartsModules, usePasteHighchartsTheme } from "@twilio-paste/data-visualization-library"; |
| 12 | + |
| 13 | +import { Box } from "@twilio-paste/box"; |
| 14 | +import { Heading } from "@twilio-paste/heading"; |
| 15 | +import { Text } from "@twilio-paste/text"; |
| 16 | +import { Callout, CalloutHeading, CalloutText } from "@twilio-paste/callout"; |
| 17 | +import { ChartProvider } from "@twilio-paste/chart-provider"; |
| 18 | +import { PageHeaderSeparator } from "@twilio-paste/page-header"; |
| 19 | +import { Separator } from "@twilio-paste/separator"; |
| 20 | +import { InlineCode } from "@twilio-paste/inline-code"; |
| 21 | +import { Anchor} from "@twilio-paste/anchor"; |
| 22 | + |
| 23 | +import { SidebarCategoryRoutes } from "../../../../constants"; |
| 24 | +import DefaultLayout from "../../../../layouts/DefaultLayout"; |
| 25 | +import { getNavigationData } from "../../../../utils/api"; |
| 26 | +import { ExamplesDataVizBaseChart as BaseChart } from "../../../../component-examples/data-visualization/BaseChart"; |
| 27 | +import { SimpleChartAccessibilityExample, SimpleChartAccessibilityDefaultExample } from "../../../../component-examples/data-visualization/ChartExamples"; |
| 28 | + |
| 29 | +export default DefaultLayout; |
| 30 | + |
| 31 | +export const getStaticProps = async () => { |
| 32 | + const navigationData = await getNavigationData(); |
| 33 | + return { |
| 34 | + props: { |
| 35 | + navigationData, |
| 36 | + }, |
| 37 | + }; |
| 38 | +}; |
| 39 | + |
| 40 | +<GenericHeader name={meta.title} description={meta.description} categoryRoute={SidebarCategoryRoutes.FOUNDATIONS}> |
| 41 | + <PageHeaderSeparator> |
| 42 | + <Separator orientation="horizontal" /> |
| 43 | + </PageHeaderSeparator> |
| 44 | +</GenericHeader> |
| 45 | + |
| 46 | +<contentwrapper> |
| 47 | + |
| 48 | +<PageAside data={mdxHeadings} /> |
| 49 | + |
| 50 | +<content> |
| 51 | + |
| 52 | +## Introduction |
| 53 | + |
| 54 | +<Box marginBottom="space60"> |
| 55 | + <Callout variant="neutral"> |
| 56 | + <CalloutHeading>In progress</CalloutHeading> |
| 57 | + <CalloutText>As our current data visualization offerings are in progress, these guidelines may change. We will update these pages when new features are supported. Please raise a <Anchor showExternal={true} href="https://github.com/twilio-labs/paste/discussions/new?category=general">GitHub discussion</Anchor> for any feedback or requests.</CalloutText> |
| 58 | + </Callout> |
| 59 | +</Box> |
| 60 | + |
| 61 | +Highcharts offers an accessibility module which we recommend always enabling. If using our [BaseChart](/foundations/data-visualization/for-engineers#basechart) implementation, this is taken care of. It provides many useful features that help visually impaired users interact with and understand charts. More information on this module can be found on [Highcharts docs](https://www.highcharts.com/docs/accessibility/accessibility-module). Features that are offered are: |
| 62 | +- Announces chart metadata such as title, subtitle, and description. |
| 63 | +- Allows keyboard navigation of series, points, and legend items. |
| 64 | +- Describes series when focused. |
| 65 | +- Describes points when focused. |
| 66 | +- Announces the legend item when focused and describes whether the series is hidden or shown. |
| 67 | +- Toggles series visibility via keyboard. |
| 68 | +- When switching from a series to the legend, legend items announce that they are used to toggle series, along with the title of chart. |
| 69 | + |
| 70 | +## Screen reader announcements |
| 71 | + |
| 72 | +The accessibility module provides announcements by default for the series and point formatters. These can be overridden by passing additional props. See below for more details. Note that the default formats are in English only - any translations would need to be overridden. |
| 73 | + |
| 74 | +- When switching points, announce the point index, _x_-axis, value, and series name. Example: "2, _x_ 3, 8105, Installation", which means it is the 2nd point in the series, with _x_-axis = 3, and a value of 8105 (_y_-axis) in the series "Installation". |
| 75 | +- When focusing on a series, announce the series name, series position of total, and how many points. Example: "Installation, line 1 of 2 with 8 data points." |
| 76 | + |
| 77 | +### Customizing announcements |
| 78 | + |
| 79 | +To override the default announcements you can set the `accessibility` attribute in the support options of the [Chart Provider](/components/chart-provider/api#charttypeoptions) |
| 80 | + |
| 81 | +The point and series will be passed to the `descriptionFormatter` to retrieve the correct values, such as axis values and series names. |
| 82 | + |
| 83 | +Below is an example where we have not overridden the default announcements to understand the base features. |
| 84 | + |
| 85 | +<LivePreview |
| 86 | + scope={{ChartProvider, BaseChart}} |
| 87 | + language="jsx" |
| 88 | + noInline |
| 89 | +> |
| 90 | + {SimpleChartAccessibilityDefaultExample} |
| 91 | +</LivePreview> |
| 92 | + |
| 93 | + |
| 94 | +## Custom example |
| 95 | + |
| 96 | +Below is an example of a chart with custom `descriptionFormatter` for the series and point. The title and sub title are both specified but hidden. They will still be included in the screen reader announcements to give context to visually impaired users but not be visible on the chart. |
| 97 | + |
| 98 | +If you inspect the rendered chart element you will see that an aria-label is applied to both the series and the point with the correct formatting provided in the config. |
| 99 | +- `aria-label="The series Installation has a total of 8 points"` is applied to the series. |
| 100 | +- `aria-label="The point 0 has a value of 43934"` is applied to the point. |
| 101 | + |
| 102 | +<LivePreview |
| 103 | + scope={{ChartProvider, BaseChart}} |
| 104 | + language="jsx" |
| 105 | + noInline |
| 106 | +> |
| 107 | + {SimpleChartAccessibilityExample} |
| 108 | +</LivePreview> |
| 109 | + |
| 110 | +## Notes |
| 111 | + |
| 112 | +- When focusing on points, the tooltip is not announced by screen readers. Instead the point description is read out. If you have key information in the tooltip, be sure to include it in the `point.descriptionFormatter`. |
| 113 | + |
| 114 | +</content> |
| 115 | + |
| 116 | +</contentwrapper> |
0 commit comments