Documentation location/URL

On this link https://www.drupal.org/docs/getting-started/accessibility/how-to-do-an-a... i'd like to have a new link to address to a new page

Problem/Motivation

The goal of this guide is to help create a shared set of test cases — with clear, step-by-step instructions — to support QAs and developers in performing keyboard accessibility tests with confidence.
By following these structured steps, teams can consistently identify and fix issues that affect keyboard navigation, ensuring that we're building websites that are accessible to everyone.

Proposed resolution

Create a practical guide focused on keyboard accessibility testing. This guide will include:
- The WCAG 2.2 Success Criterion being validated
- The acceptance criteria for passing that Success Criterion
- A set of test cases, with step-by-step instructions, that must be performed to ensure the website meets the requirements of the specific Success Criterion
The goal is to make it easier for teams to integrate accessibility checks into their regular QA process, helping to ensure that Drupal websites are usable for keyboard-only users.

Remaining tasks

Comments

brunaemerich created an issue. See original summary.

brunaemerich’s picture

brunaemerich commented
brunaemerich’s picture

brunaemerich commented

On this link https://www.drupal.org/docs/getting-started/accessibility/how-to-do-an-a... i'd like to have a new link to address to a new page

brunaemerich’s picture

brunaemerich commented
Issue summary: View changes
brunaemerich’s picture

brunaemerich commented
mgifford’s picture

mgifford
he/him
Primary language English
commented

Sounds useful. I'd love to see some proposed language here.

mgifford’s picture

mgifford
he/him
Primary language English
commented

Sample text mostly from ChatGPT.

So we take the current “Test Keyboard Navigation” section in "How to do an accessibility review" and:
1. Keep the section, but shorten it to a short overview (1–2 paragraphs) that explains why keyboard navigation is critical.
2. Link out to the new page for full step-by-step guidance:

Suggested wording:

For a detailed, step-by-step process tied to WCAG 2.2 criteria, see the Keyboard Accessibility Testing Guide.

This avoids duplication and makes the main accessibility review page more scannable while still pointing users to deeper material.

⸻

Draft: Keyboard Accessibility Testing Guide

Introduction

Keyboard accessibility is essential for people who cannot or choose not to use a mouse. This includes screen reader users, people with motor impairments, and anyone relying on assistive technology. Ensuring that all Drupal websites are operable by keyboard alone is a baseline accessibility requirement.

This guide provides structured, step-by-step test cases tied directly to WCAG 2.2 Success Criteria. It is designed to support QA testers, developers, and site builders in validating keyboard accessibility with confidence and consistency.

⸻

Scope

This guide focuses only on keyboard-only testing. For full accessibility review guidance (color contrast, headings, screen readers, etc.), see the main How to do an accessibility review page.

⸻

WCAG 2.2 Success Criteria Covered

The following WCAG 2.2 criteria are addressed by keyboard testing:
• 2.1.1 Keyboard – All functionality must be operable via keyboard.
• 2.1.2 No Keyboard Trap – Users must not get stuck.
• 2.1.4 Character Key Shortcuts – Provide alternatives if single-key shortcuts exist.
• 2.4.3 Focus Order – Navigation order must be logical and predictable.
• 2.4.7 Focus Visible – Focus indicators must be visible at all times.
• 2.5.8 Target Size (Minimum) – Ensure controls meet minimum target size.

⸻

Test Setup

• Test using only the keyboard: Tab, Shift+Tab, Enter, Space, Arrow keys, Escape.
• Test at 100%, 200%, and 400% zoom to account for users with low vision and responsive layouts.
• Test in multiple browsers (Chrome, Firefox, Safari, Edge) where possible.

⸻

Step-by-Step Test Cases

1. Tabbing through the page
• Action: Press Tab repeatedly through the page.
• Expected: All interactive elements are reachable.
• Fail: Any element is skipped or unreachable.
• SC: 2.1.1 Keyboard

⸻

2. Reverse navigation

• Action: Use Shift+Tab to move backwards.
• Expected: Reverse navigation works without trapping focus.
• Fail: User cannot navigate backward or gets stuck.
• SC: 2.1.2 No Keyboard Trap

⸻

3. Skip links

• Action: Tab from the top of the page.
• Expected: A skip link is available, visible on focus, and takes the user to the main content.
• SC: 2.4.1 Bypass Blocks

⸻

4. Focus visibility

• Action: Tab through all elements.
• Expected: Each focusable item has a clear visible indicator (not just color).
• Fail: Focus is missing, subtle, or inconsistent.
• SC: 2.4.7 Focus Visible

⸻

5. Logical focus order

• Action: Tab through sections of the page.
• Expected: Focus order follows a logical sequence (visual and DOM order).
• Fail: Focus jumps in unexpected ways.
• SC: 2.4.3 Focus Order

⸻

6. Dialogs and modals

• Action: Open any dialog or modal, then Tab/Shift+Tab.
• Expected: Focus is constrained inside until the dialog is closed. Focus returns to trigger on close.
• SC: 2.1.2 No Keyboard Trap

⸻

7. Interactive widgets

• Action: Test sliders, menus, dropdowns, and drag-and-drop alternatives.
• Expected: All are operable with standard keyboard commands (arrows, Enter, Space, Escape).
• SC: 2.1.1 Keyboard

⸻

8. Hover-triggered content

• Action: Identify content that appears on hover with a mouse.
• Expected: Same content must be available by focus.
• SC: 1.4.13 Content on Hover or Focus

⸻

9. Non-interactive elements

• Action: Tab through the page.
• Expected: Decorative or non-interactive elements should not receive focus.
• SC: 2.4.3 Focus Order

⸻

Reporting Issues

When documenting failures, include:
• WCAG Success Criterion reference.
• Test case name.
• Steps to reproduce.
• Expected vs actual behavior.
• Screenshot or video if available.

⸻

Integrating Into QA

• Run keyboard testing before every release as part of accessibility acceptance criteria.
• Combine with automated checks (axe-core, Lighthouse) but always confirm focus and keyboard traps manually.