Clarify accessibility criteria descriptions#1403
Clarify accessibility criteria descriptions#1403scottaohara wants to merge 1 commit intogithub:mainfrom
Conversation
I have not been able to look through everything in this file. But these changes attempt to clarify / correct what initially stood out to me
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
main, but PRs should target staged.
The main branch is auto-published from staged and should not receive direct PRs.
Please close this PR and re-open it against the staged branch.
You can change the base branch using the Edit button at the top of this PR,
or run: gh pr edit 1403 --base staged
There was a problem hiding this comment.
Pull request overview
Updates the repository’s accessibility instruction guidance to more precisely reflect WCAG 2.2 criteria summaries and related ARIA/keyboard best-practice explanations.
Changes:
- Clarifies multiple WCAG 2.2 success criterion summaries in the quick reference tables (Perceivable/Operable).
- Refines wording in ARIA and keyboard/focus anti-pattern guidance (e.g., focus obscured, pointer cancellation, modal focus return).
- Minor additions/edits to explanatory notes in ARIA sections.
| | 1.4.4 Resize Text | AA | Text resizable to 200% without loss of content. | | ||
| | 1.4.10 Reflow | AA | Content reflows at 320px CSS width (no horizontal scroll). | | ||
| | 1.4.4 Resize Text | AA | Text resizable to 200% without loss of content or functionality. | | ||
| | 1.4.10 Reflow | AA | Sections of content can fit within 320px CSS width viewports without needing to scroll in two-dimensions to read. | |
There was a problem hiding this comment.
In the Reflow criterion summary, “scroll in two-dimensions” is grammatically incorrect; it should be phrased as “scroll in two dimensions” (or “two-dimensional scrolling”) to avoid a typo in the criteria text.
| | 1.4.10 Reflow | AA | Sections of content can fit within 320px CSS width viewports without needing to scroll in two-dimensions to read. | | |
| | 1.4.10 Reflow | AA | Sections of content can fit within 320px CSS width viewports without needing to scroll in two dimensions to read. | |
| - **WCAG**: ARIA Rule 4 | ||
|
|
||
| Use `inert` attribute or remove from tab order entirely. | ||
| Use `disabled` attribute for allowed elements. Use `inert` attribute for obscured/off-screen content if the content is meant to be completely hidden and not functional. |
There was a problem hiding this comment.
This guidance is too broad/incorrect for the detected elements listed above (button, input, a, [tabindex]): disabled is not a valid attribute for anchors or arbitrary focusable elements, and disabling also changes semantics rather than simply preventing focus. Consider revising to explicitly recommend removing focusability (e.g., remove href/tabindex, use hidden/CSS + remove from tab order) or using inert/removing from the DOM when the content must be non-interactive and hidden from assistive tech.
| Use `disabled` attribute for allowed elements. Use `inert` attribute for obscured/off-screen content if the content is meant to be completely hidden and not functional. | |
| Do not leave focusable elements inside `aria-hidden="true"` content. For native controls that support it, such as `<button>` or `<input>`, use `disabled` only when disabling the control is the intended behavior. For `<a>` elements or arbitrary elements made focusable with `[tabindex]`, remove focusability instead (for example, remove `href` or `tabindex`). If the content should be completely non-interactive and hidden from assistive technology, use `inert`, `hidden`, or remove it from the DOM. |
| - **WCAG**: 2.1.1 (A) | ||
|
|
||
| Use `<button>` instead. If div is required: add `role="button"`, `tabIndex={0}`, and handle Enter/Space. | ||
| Use `<button>` instead. If div is required: add `role="button"`, `tabIndex={0}`, and handle Enter/Space as well as expected high contrast styling. |
There was a problem hiding this comment.
The phrase “expected high contrast styling” is ambiguous here (it’s not clear what specific requirement to implement). Consider replacing it with concrete, testable guidance (e.g., ensure visible focus styles and contrast for the custom control meet the relevant WCAG criteria) or remove it to avoid unclear instructions.
| Use `<button>` instead. If div is required: add `role="button"`, `tabIndex={0}`, and handle Enter/Space as well as expected high contrast styling. | |
| Use `<button>` instead. If a `<div>` is required, add `role="button"`, `tabIndex={0}`, handle Enter and Space, provide a visible focus indicator, and ensure the control's focus and interactive states meet applicable WCAG 2.2 AA contrast requirements. |
| - **WCAG**: 2.4.3 (A) | ||
|
|
||
| Store reference to trigger element. On modal close, call `triggerElement.focus()`. | ||
| Store reference to trigger element or to best logical location if triggering element is no longer present upon close. On modal close, call `triggerElement.focus()`. |
There was a problem hiding this comment.
There’s trailing whitespace at the end of this line, which can cause noisy diffs and some markdown lint failures. Please remove the extra space at the end of the sentence.
| Store reference to trigger element or to best logical location if triggering element is no longer present upon close. On modal close, call `triggerElement.focus()`. | |
| Store reference to trigger element or to best logical location if triggering element is no longer present upon close. On modal close, call `triggerElement.focus()`. |
Pull Request Checklist
Description
I have not been able to look through everything in the accessibility instruction file. But the changes I'm submitting attempt to clarify / correct content that needed it.
Type of Contribution
By submitting this pull request, I confirm that my contribution abides by the Code of Conduct and will be licensed under the MIT License.