GitHub, along with your tracking software (which may also be GitHub), are incredibly valuable tools for managing application development, especially when you have more than one developer and are using an iterative process. The larger the project, the more features you’ll want to use so that team members have the information they need in order to work effectively and efficiently.
It is also useful to think of these tools as a historical record, something that will help future teams understand how previous work was done and how decisions were made.
The suggestions in this guide are simply that. They can be adapted or cherry-picked to best align with the needs of your project and team.
Issue templates
Adding accessibility details to your bug templates can help describe and add context to accessibility defects in your products. You can add these snippets to your existing bug template, but you’ll also want to make sure to give accessibility bugs appropriate visibility, either with labels or a descriptive title.
## Screen recording or screenshot:
## Accessibility Impact
- [ ] Does this bug affect keyboard navigation?
- [ ] Does this bug affect screen reader users?
- [ ] Does this bug affect users with visual impairments?
- [ ] Does this bug affect users with motor impairments?
**Assistive Technology Tested:**
- [ ] Screen reader (specify which: NVDA/JAWS/VoiceOver/etc.)
- [ ] Keyboard only
- [ ] Voice control
- [ ] Other: ___________
**WCAG Guidelines Affected:** (if known)
- Guideline reference: ___________
## Severity
- [ ] 0: Critical (blocks core functionality)
- [ ] 1: High (significant barrier)
- [ ] 2: Medium (moderate barrier)
- [ ] 3: Low (minor enhancement)
- [ ] Not surePull request templates
Pull request templates save developers time by providing a standardized set of criteria to fill out so that code reviewers have all the background they need in order to confidently accept or request changes to the work. This often includes information such as the issue number, some instructions how to review the work, and screenshots. There might be a checkbox where the developer can affirm that the work is accessible, but for many developers, that might be too vague to be meaningful.
Here is a snippet you can use in your project’s pull request template that asks more detailed questions about the work’s accessibility.
## Validated user-facing changes
- [ ] Added `user-facing` label or reviewed with a designer for all user-facing changes
- [ ] Checked responsiveness for mobile, tablet, desktop, and all screen sizes
- [ ] Increased page zoom to 400%
## Full a11y review for major UI/UX changes
Tested general usability, equivalent experience as mouse users without degradation or additional burden, landmarks, page header structure, and links with a screen reader (check at least on applicable work):
- [ ] VoiceOver on MacOS
- [ ] JAWS on Windows
- [ ] NVDA on Windows
- [ ] None, added `needs-sr-check` label
Tested for keyboard navigability to ensure equivalent experience for keyboard users as mouse/trackpad users without degradation or additional burden
- [ ] Logical and intuitive tab order
- [ ] Added appropriate focus transferring and/or trapping
Used an a11y tool to check these changes conform to at least WCAG 2.2 AA. If this feature has multiple states, you have also run accessibility checks on those states.
- [ ] Axe DevTools and/or ANDI
- [ ] Browser web inspector
- [ ] Browser accessibility inspector (web inspector > elements > right panel)
- [ ] For storybook-only components, use the accessibility tab in Storybook.Upon first glance, this might seem like a lot, but does several important things:
- With the term, “user-facing,” it communicates that any code change that is delivered to the browser is delivered to the user, which may have accessibility implications
- Asks to check the work at different screen sizes and page zoom levels because reflow is often overlooked
- Uses the terms “equivalent experience” and “additional burden.” Without requiring the developer to review the entire Web Content Accessibility Guidelines, these terms ask questions about assistive technology, like:
- Can the user access the same information or controls?
- Does it require what seems like more steps than necessary?
Labels
Use labels to give visibility to accessibility tickets and pull requests. Some potential labels could be:
- “Accessibility”: This is a generic accessibility label that can be applied to issues and pull requests
- “User-facing”: As we discussed previously, this label could be applied to any pull requests that include work that will be presented to the user. This could serve as a catch-all if you are not sure if there are accessibility implications (spoiler alert: it’s very likely). A team member could use this label to filter out any any user-facing work for accessibility review
- Defect severity: use these labels on your bug tickets to help define the level of severity for accessibility defects. You can use 0-3 scale or 0-4 scale. What is important is that you are actively prioritizing defect remediation appropriately. For more info, look at the Department of Veteran’s Affairs’s accessibility defect rubric:
- “A11y defect: 0 (harmful)”: Launch-blocking. Level 0 defects could cause life-threatening harm and must resolved immediately
- “A11y defect: 1(critical)”: Launch-blocking. Level 1 defects could prevent users from accessing services or completing important tasks
- “A11y defect: 2”: Level 2 defects could be disruptive or frustrating, but could be resolved in a sprint or two
- “A11y defect: 3”: Level 3 defects reflect simple user experience issues that should be resolved in two to three sprints
Artifacts
In both tickets and pull requests, use screenshots or recording as much as possible. There’s the saying that a picture is worth a thousand words, and that rings especially true when trying to describe interactions and digital content behaviors, and extra-especially true when it comes to screen reader issues.
Recording the screen with audio isn’t always straightforward. Here are some tips: