The results of an accessibility audit can be in many different formats. A report, Jira tickets, a spreadsheet, or something else. Whatever the format, it’s useful to be as clear as possible.
Some popular fields in audit reports are: summary, user impact, Ideas for how to fix it. Different teams use different names for these. Below I explain what each one means, give an example, and provide links to sources that I consult for finding good wording.
A one sentence summary of the issue describing what’s missing or incorrect.
For example: the page title is not unique and does not describe the page content.
- Take the Success Criteria.
- Flip it to describe the “failure criteria”.
- Reword it to make it more readable and less formal.
- Add specifics: the page, the element.
A one sentence description of who the issue affects and the barrier they are facing.
- Aligns with the Severity. Describes the problem, inconvenience, or frustrations.
- Includes the Functional Category (or Categories): vision (blind, low vision, colourblind), motor / physical, cognitive.
- Uses bold and unqualified language: “users can not” rather than “users may not be able to”.
- Includes the technology: keyboard, magnification tools, increased text size, screen reader, voice control.
- The A11y Project Checklist
- The Benefits section from an individual Success Criteria in the WCAG 2.1 Understanding Docs.
- “Why it Matters” from the relevant axe rule.
Ideas for how to fix it
A one sentence description of the change(s) needed to resolve the issue.
- Where possible, the HTML to use.
- Where possible, the technology-specific code to use (e.g. which component in the design system, which props of a React component to use).
- For HTML: check the name and Rule Description for axe rules.
- For technology-specific code: the design system documentation.
When describing the solution, tailor the text to the team.
- Some teams want to know the required outcome. For example: “the
buttonmust have an accessible name.”
- Some teams want more specific and detailed descriptions of how to fix the issue. For example: “Give the
buttonan accessible name by adding an
button”. Another example: “Give the
buttonan accessible name by adding by setting the
ariaLabelprop of the
ButtonReact component to
Ways to know if the fix has resolved the issue:
- check that the Summary sentence is now false;
- check that the User Impact is no longer applicable.