From b42f3e2c4c594512498bc78c92f2383b21b4190a Mon Sep 17 00:00:00 2001 From: Alex Khomenko Date: Thu, 11 Aug 2022 14:00:38 +0300 Subject: [PATCH] A11y: Create Minimal Styleguide (#46948) * First draft of the guide * Fix Select part * Move a11y PR guidelines * Update contribute/create-pull-request.md Co-authored-by: Maria Alexandra <239999+axelavargas@users.noreply.github.com> Co-authored-by: Maria Alexandra <239999+axelavargas@users.noreply.github.com> --- contribute/create-pull-request.md | 11 +--- contribute/style-guides/accessibility.md | 77 ++++++++++++++++++++++++ 2 files changed, 79 insertions(+), 9 deletions(-) create mode 100644 contribute/style-guides/accessibility.md diff --git a/contribute/create-pull-request.md b/contribute/create-pull-request.md index ba93a37eb35..d130db61831 100644 --- a/contribute/create-pull-request.md +++ b/contribute/create-pull-request.md @@ -55,16 +55,9 @@ Pull requests that create new UI components or modify existing ones must adhere - Use the [Grafana theme palette](/contribute/style-guides/themes.md) for styling. It contains colors with good contrast which aids accessibility. - Use [RTL](https://testing-library.com/docs/dom-testing-library/api-accessibility/) for writing unit tests. It helps to create accessible components. -Pull requests that introduce accessibility(a11y) errors: +### Accessibility-specific guidelines -We use [pa11y-ci](https://github.com/pa11y/pa11y-ci) to collect accessibility errors on [some URLs on the project](https://github.com/grafana/grafana/issues/36555), threshold errors are specified per URL. - -If the contribution introduces new a11y errors, our continuous integration will fail, preventing you to merge on the main branch. In those cases there are two alternatives for moving forward: - -- Check the error log on the pipeline step `test-a11y-frontend-pr`, identify what was the error, and fix it. -- Locally run the command `yarn test:accessibility-report` that generates an HTML accessibility report, then go to the URL that contains your change, identify the error, and fix it. Keep in mind, a local e2e Grafana instance is going to be running on `http://localhost:3001`. - -You can also prevent introducing a11y errors by installing an a11y plugin in your browser, for example, axe DevTools, Accessibility Insights for Web among others. +Pull requests that introduce accessibility(a11y) errors - please refer to the [accessibility guidelines](/contribute/style-guides/accessibility.md). ### Betterer diff --git a/contribute/style-guides/accessibility.md b/contribute/style-guides/accessibility.md new file mode 100644 index 00000000000..c884a1efa1e --- /dev/null +++ b/contribute/style-guides/accessibility.md @@ -0,0 +1,77 @@ +# Accessibility at Grafana + +At Grafana we pay special attention to accessibility and that's why it's important that all components are written with it in +mind. + +The goal of this document is to list best practices and recommendations when it comes to writing accessible components. + +### grafana/ui components + +Some grafana/ui components have specific mechanisms built-in that make it easier to write accessible components. + +#### Form elements + +One of the important accessibility considerations when working with form elements is to make sure form controls are +properly labelled. For that a `label` element has to be associated with the respective form control. One way to +do that is to provide `for` attribute to the label that matches the `id` attribute of the form control. + +The form components from grafana/ui provide an easier way to achieve that. The form elements, used inside `Field` +components, will get the `label` properly associated with them given that the element has `id` (in case of `Select` the prop is `inputId`) specified. + +As an example, this code + +```tsx + + + +``` + +will be rendered as (simplified) + +```html +
+ + +
+``` + +As long as the form element has a unique `id` attribute specified, it will be automatically accessible when rendered. + +### Writing tests with accessibility in mind + +We use [React Testing Library](https://testing-library.com/docs/react-testing-library/intro) (RTL) for writing unit tests. +The library is built with accessibility in mind and makes it easier to ensure the written code is accessible to all users. +When querying DOM elements with RTL prefer using `*ByRole` queries as they resemble closely how the users interact +with the page - both using mouse/visual display and assistive technologies. +As a rule of thumb, if code is written with the accessibility concerns in +mind, `*ByRole` queries will be sufficient in most of the cases. There are certainly exceptions here, as not all the elements have defined [ARIA role](https://www.w3.org/TR/html-aria/#docconformance). + +As an example, for this code + +```tsx + + + +``` + +the test could case be as follows + +```tsx +it('has username set', () => { + expect(screen.getByRole('textbox', { name: 'Username' })).toHaveValue('Test'); +}); +``` + +Input with type `text` (default type value) has a role of `textbox` and the `name` option is not the name attribute +given to the input elements but their [accessible name](https://www.tpgi.com/what-is-an-accessible-name/), which in this case is the text content of the associated with input label. + +### Pull requests that introduce accessibility(a11y) errors: + +We use [pa11y-ci](https://github.com/pa11y/pa11y-ci) to collect accessibility errors on [some URLs in the project](https://github.com/grafana/grafana/issues/36555), threshold errors are specified per URL. + +If the contribution introduces new a11y errors, our continuous integration will fail, preventing you to merge to the main branch. In those cases there are two alternatives for moving forward: + +- Check the error log on the pipeline step `test-a11y-frontend-pr`, identify what was the error, and fix it. +- Locally run the command `yarn test:accessibility-report` that generates an HTML accessibility report, then go to the URL that contains your change, identify the error, and fix it. Keep in mind, a local e2e Grafana instance is going to be running on `http://localhost:3001`. + +You can also prevent introducing a11y errors by installing an a11y plugin in your browser, for example, axe DevTools, Accessibility Insights for Web among others.