Accessibility

We aim to adhere to strict accessibility standards with AA as the minimum

We have configured a few tools to help automate some accessibility testing but these tests are only valid with the context they are testing on, so they can't guarantee that a component is fully accessible. Manual testing is always required along with design validation.

To enable this, eslint-plugin-jsx-a11y is set to strict mode. Different tools are used to validate the components as each serves a different purpose. The accessibility unit tests will fail the pipeline and prevent releasing inaccessible components.

Before contributing to the codebase, please take some time to read the following sections and the reading provided.

Things to consider whilst developing

  • Add unit tests to test accessibility

    Add an accessibility unit test (using the jest-axe package) to ensure that the components’ different variations or functionality don't have any accessibility issues. Example:
it('has no programmatically detectable a11y issues', async () => {
  const { container } = render(<Component />)
  expect(await axe(container)).toHaveNoViolations()
})


// or


it('has no programmatically detectable a11y issues', async () => {
  render(<Flex />, document.body)
  const results = await axe(document.body)
  expect(results).toHaveNoViolations()
})

Note: axe doesn't catch contrast issues when run on jsdom which jest is using.

  • Using React.Fragment where possible to avoid adding extra <div>

    Sometimes we break HTML semantics when we add <div> elements to our JSX to make our React code work, especially when working with lists (<ol>, <ul> and <dl>) and the HTML <table>. In these cases we should rather use React Fragments to group together multiple elements. for examples please look at the React documentation

  • Using the React Testing Library rules into adopting a user-centric testing an approach. Priority

    • Test real interactions
    • Verify the perceivable results

  • Always validating any concerns with the design team

  • Manually test complex components for keyboard navigation

Things to consider whilst consuming the library

As mentioned above, accessibility testing is heavily reliant on the context, so when using the Design System in an app, please consider the following:

  • Testing the components for accessibility in the context of where they are used
  • Testing the entire page for at least the following:
    • contrast issues
    • keyboard navigation
    • autofocus
    • general accesibility issues
  • Always raising concerns to the design team

Reading list