Skip to content

Commit 5e2d950

Browse files
authored
Improved the accessibility guide
- fixed broken links - mention some good browser extensions for testing - mention Capybara accessibility tools - suggest using role selectors in testing - suggest validating HTML and announcing content changes
1 parent 852089d commit 5e2d950

1 file changed

Lines changed: 37 additions & 10 deletions

File tree

accessibility/README.md

Lines changed: 37 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -13,20 +13,39 @@ accessible.
1313
Automated checks can catch a lot of common issues before they reach production.
1414

1515
- Test the application in a browser (like Capybara-driven [Acceptance
16-
Tests](./testing-rspec/README.md#acceptance-tests))
16+
Tests](../testing-rspec/README.md#acceptance-tests))
17+
- When using Capybara, use [CapybaraAccessibilityAudit]
1718
- Use tools such as [WAVE] or [axe's browser extensions] to run audits on your
1819
local build
19-
- Use a CI/CD solution such as [AccessLint] or [axe]
20+
- Use a CI/CD solution such as [AccessLint] or [axe]. axe has integrations with popular test frameworks like RSpec and Jest
21+
22+
[CapybaraAccessibilityAudit]: https://github.com/thoughtbot/capybara_accessibility_audit
2023

2124
### Usability
2225

2326
[Manual usability testing] ensures things work as intended.
2427

2528
- Test your local build using a screen reader such as [VoiceOver] or [NVDA]
26-
- Use tools such as [Accessibility Insights] to catch issues that cannot be
29+
- Use auditing tools to catch issues that cannot be
2730
found using automated checks
31+
- [Accessibility Insights] accessibility auditing browser extension
32+
- [Readability Analyzer][simple and direct] for auditing text
33+
- [axe DevTools] accessibility testing browser extension
34+
- [WAVE Evaluation Tool] accessibility testing browser extension
35+
- [ARIA DevTools] browser extension for checking ARIA roles
36+
- [tab11y] browser extension for checking tab order
37+
- [WCAG Color contrast checker] browser extension
38+
- Validate your HTML with a tool like [W3C's Markup Validation Service][w3c-markup-validator]
2839
- Hire assistive technology users to user test your product
2940

41+
[Juicy Studio]: https://juicystudio.com/services/readability.php
42+
[axe DevTools]: https://chromewebstore.google.com/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd
43+
[WAVE Evaluation Tool]: https://chromewebstore.google.com/detail/wave-evaluation-tool/jbbplnpkjmmeebjpijfedlgcdilocofh
44+
[ARIA DevTools]: https://chromewebstore.google.com/detail/aria-devtools/dneemiigcbbgbdjlcdjjnianlikimpck
45+
[tab11y]: https://chromewebstore.google.com/detail/taba11y-tab-order-accessi/aocppmckdocdjkphmofnklcjhdidgmga
46+
[WCAG Color contrast checker]: https://chromewebstore.google.com/detail/wcag-color-contrast-check/plnahcmalebffmaghcpcmpaciebdhgdf
47+
[w3c-markup-validator]: https://validator.w3.org/
48+
3049
## Quick checks
3150

3251
### Design
@@ -86,14 +105,22 @@ Automated checks can catch a lot of common issues before they reach production.
86105
label them
87106
- Ensure form feedback messaging is programmatically associated with the
88107
relevant inputs
108+
- Ensure that [dynamic changes to a web page are announced](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html)
109+
- Prefer using role selectors in automated acceptance tests
110+
- [capybara_accessible_selectors]
111+
- [Testing Library's `getByRole()`][testing-library-getbyrole]
112+
- [Playwright's `getByRole()`][playwright-getbyrole]
89113

90114
[accessible name]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/
91-
[Cardinal Rules of Naming]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#x5-3-cardinal-rules-of-naming
92-
[rule-1]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#x5-3-1-rule-1-heed-warnings-and-test-thoroughly
93-
[rule-2]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#x5-3-2-rule-2-prefer-visible-text
94-
[rule-3]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#x5-3-3-rule-3-prefer-native-techniques
95-
[rule-4]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#x5-3-4-rule-4-avoid-browser-fallback
96-
[rule-5]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#x5-3-5-rule-5-compose-brief-useful-names
115+
[Cardinal Rules of Naming]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#cardinalrulesofnaming
116+
[rule-1]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#naming_rule_heed_warnings
117+
[rule-2]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#naming_rule_visible_text
118+
[rule-3]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#naming_rule_native_techniques
119+
[rule-4]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#naming_rule_avoid_fallback
120+
[rule-5]: https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/#naming_rule_brief_names
121+
[capybara_accessible_selectors]: https://github.com/citizensadvice/capybara_accessible_selectors
122+
[testing-library-getbyrole]: https://testing-library.com/docs/queries/byrole
123+
[playwright-getbyrole]: https://playwright.dev/docs/locators#locate-by-role
97124

98125
## Full audit
99126

@@ -126,7 +153,7 @@ assign it one of four ratings:
126153
Use the Notes sheet to leave per-cell comments when necessary, referencing them
127154
with a link. The next steps for an audit are handled on a per-project basis.
128155

129-
[accessibility audit template]: https://www.fsb.org.uk/resources-page/accessibility-audit-template.html
156+
[accessibility audit template]: https://www.fsb.org.uk/resources/article/accessibility-audit-template-MCTMWUV4Z27FEXRANM566TOZXNOE
130157
[accesslint]: https://github.com/marketplace/accesslint
131158
[axe]: https://www.deque.com/axe/axe-for-web/integrations/
132159
[axe's browser extensions]: https://www.deque.com/axe/axe-for-web/

0 commit comments

Comments
 (0)