Designing inclusive and engaging digital experiences
The art of writing accessibility issue documentation
There are several ingredients for effective accessibility issue documentation. In this post, I describe what I include in writing accessibility issues and how that helps progress remediation work. I outline how I structure issue documentation drawing on an example issue of icon buttons in a toolbar.
A modern issue-tracking tool such as Jira is a powerful collaborative issue documentation space. Whatever tool you use, a solid structure maximises the effectiveness of accessibility issue write-ups.
Introduce benefits that can be realised from resolving the issue. Using plain language describe user-centred gains that can motivate action. For example:
Using visible text in each icon button will benefit:
Describe the actual or current experience followed by what the experience should be. When the experience is accessible, what will it be like?
In the case of our button toolbar, I described these actual results:
Buttons have a title attribute that does not serve 1:
mobile and tablet users
assistive tech users
keyboard-only users
Buttons lack visible onscreen text.
Usually we have only 1 expected result, and it often contrasts with the actual result. However, there are several ways to create a more accessible2 button toolbar. In the expected results, I described these options:
Option a: each button has an icon plus onscreen text.
Option b: each button has an icon plus hidden text serving some screen reader users.
Providing options made it easier to scope progress on remediation work and to engage teammates on their accessibility literacy journey3.
This part requires thoughtful consideration and collaboration amongst designers, developers, testers, and product roles. Our icon button toolbar has 2 actual problems and 2 recommendations.
My first recommendation was to remove the redundant title attribute from each <button> element. This sparked a question:
Why do we need to remove the title attribute? My understanding is we generally want to keep it as it provides further context (a user can hover and see the title)
My second recommendation was to add visibly hidden text in each button, as an interim measure. This also stimulated a question:
Is there a reason to use a hidden text node instead of an aria-label here?
To answer this, I referred to another authoritative resource, My Priority of Methods for Labeling a Control. In that post, Adrian lists this order when assigning an accessible name:
Native HTML techniques,
aria-labelledby pointing at an existing visible text,
Visibly hidden content that is still on the page,
aria-label.
For both options 3 and 4, “The only users who will know it is there are screen reader users.” Some of the reasons aria-label is a last resort:
aria-label content cannot be relied on for translation
aria-label content will not become visible when CSS or scripts fail to load
Using information from authorities is highly effective in supporting your recommendations.
Write acceptance criteria to indicate success and done #
Write acceptance criteria to clarify when an accessibility issue will be resolved. Use a structured, easy-to-understand format, such as the Given-When-Then format4. Your project might adopt and adapt these 10 Accessibility Acceptance Criteria. For our icon buttons:
AAC9 Alt text Given I use a screen reader, When I encounter a button with visibly hidden text, Then I can understand the button content non-visually.
Each accessibility acceptance criteria follows the format of user + action + outcome and centres the story on the user’s requirement.
Help teammates find the guidelines that affect their role and responsibilities, and those that are appropriate for a given feature. For our icon buttons, there is a guideline for the icons:
Delving deeper, the interaction shows the buttons are behaving as toggle buttons. For example, open/close filters and show/hide search. In a separate issue, I documented the need for a toggle role and the current state of show/hide to be conveyed audibly. I’ll leave it to you to name the appropriate guideline for that.
Useful labels for filtering, prioritising and reporting #
Accessibility audits often target a particular standard and level of conformance. For example, Government projects started before September 2024 may have contractual obligations for conformance with WCAG 2.0 up to level AA. Useful labels for filtering and prioritising include:
accessibility
WCAG_2.0
Level_A
Level_AA
Forms for authentication and collecting personal data may benefit from autocomplete functionality or turning autofill off for privacy. 1.3.5 Identify Input Purpose is a guideline from WCAG 2.1. Authentication guidelines arrived in WCAG 2.2. To group issues according to their guideline version, I use labels:
WCAG_2.1
WCAG_2.2
My audits are scoped to several pages and components and performed over a few days. Chronologically grouping issues, I label issues:
The map resembles an underground train map, showing 86 success criteria as stations across 8 lines.
In Andrew Hick’s WCAG 2.2 map by theme6, “all the criteria that can be tested using a keyboard are on one line.” Each of the 8 lines groups several WCAG guidelines into practical themes for testing. The guideline we identified earlier for icon buttons, 1.1.1 Non-text Content, maps to themes:
Sensory
Code & labels
Wording
I add the themes as labels. After remediation work, we test whether each theme’s criteria are met. Criteria are listed on the web page at the start of each theme. For example, Sensory:
These criteria prevent content from being reliant on particular senses, by:
avoiding audio or video distractions
having enough contrast
not relying on vision, colour, hearing or timing
Link to related issues and relevant web resources #
Link issues to communicate related work. Developers gain efficiency by remediating issues on the same component or common templates. In this case, once I had separately documented the need for a toggle button’s interactive state to be conveyed audibly, I linked these related issues.
Sharing tools and resources appropriate for a given feature is a frame of Devon Persing’s Accessibility Literacy Framework. It helps people in their accessibility learning and practice.
One of the fantastic A11y Tools bookmarklets is List Buttons.
In addition to the resources mentioned throughout this post, I also link to exemplar components and patterns that solve interaction problems. In the case of our icon buttons toolbar:
Save your audience’s precious time. Edit your accessibility issue documentation. Ask for feedback from your audience to help you edit it further. Make it brief. Any parts that can be left out will save everyone time. You might consider iterative editing a shift-left approach to effective issue documentation.
I believe there is an art to writing successful accessibility issue documentation. This structure and ingredients made my accessibility issue write-ups useful and usable by the audiences responsible for progressing the work. Product owners, designers, developers, and testers have praised my issue write-ups. Comprehensive documentation made it easier for everyone to perform their role7 in creating more inclusive digital experiences.
What else could help make accessibility issue documentation more effective? What works in your team to catalyse conversations about accessibility, raise accessibility literacy, and progress remediation? Let me know in the comments.
