Changes to the Drupal Accessibility Review Guide

This document explains the redraft of How to do an accessibility review. The original page was last updated on April 15, 2026. The revision aligns the review process with the proposed accessibility gate, contribution guidance, and coding standards.

Summary

The revised page is organized as an eight-step review workflow. It begins with people, tasks, proportionate scope, and test conditions. Automated results are treated as evidence from limited rules. Manual testing, assistive-technology testing, and disabled-user testing are separate evidence sources. The final sections require accessible artifacts and classify what blocks approval, what requires review, and what remains aspirational.

The original body contained approximately 2,559 words. The revised body contains 2,257 words, a decrease of 11.8 percent. Product lists, outdated tutorials, duplicated standards, and inaccurate requirements were removed while the review workflow and evidence requirements were expanded.

The revision:

Detailed changes

Changes grouped by original section or claim
Original area Change Reason
Introduction Replaced the general reassurance with a definition of an accessibility review and its limits. The original page did not distinguish a review of a contribution from a scoped WCAG conformance evaluation.
Review scope Added user tasks, workflows, versions, configuration, roles, content, states, viewports, preferences, browsers, assistive technologies, applicable checks, and explained exclusions. A result cannot be reproduced or interpreted without knowing what was tested, under which conditions, and why the scope is proportionate.
Tugboat previews Retained Tugboat as a useful way to provide a stable preview but reduced the implementation detail. A preview supports testing. It is not itself an accessibility test and local environments remain valid.
“Start by running automated tooling” Moved automated checks after scope definition and the evidence hierarchy. Starting with a tool encourages reviewers to define accessibility by the tool’s available rules rather than by affected people, tasks, and requirements.
Tool list Removed the fixed list of WAVE, Accessibility Insights, Lighthouse, Siteimprove, and Editoria11y. The products serve different audiences and workflows, and the list will become stale. The guide now states what evidence a tool result must provide.
Automated findings Separated deterministic failures from incomplete, needs-review, context-dependent, and best-practice results. Tools test specific rules, not accessibility as a whole. Only a smaller reliable subset is appropriate for unattended build failures.
Rule suppression Added requirements for narrow exceptions, written reasons, linked follow-up issues, and conditions for rechecking. Current Drupal core Nightwatch tests use targeted disabled rules with issue references. Broad or indefinite suppression can hide regressions.
Keyboard navigation Reorganized the repeated questions into checks for operation, order, visible focus, obscured focus, traps, temporary contexts, custom widgets, and hover or focus content. The revised checklist is shorter, testable, and includes WCAG 2.2 Focus Not Obscured.
Dialog focus Limited focus containment to modal dialogs and required a predictable close action. Not every dialog is modal. Applying a focus trap to a non-modal interaction can create a barrier.
Pointer and touch Added pointer gestures, cancellation, dragging alternatives, label in name, and target size. The original page concentrated on keyboard and omitted several applicable input requirements, including WCAG 2.2 additions.
Responsive breakpoints Retained responsive keyboard testing and placed it within zoom, reflow, and personalization testing. Responsive states affect high-zoom users as well as mobile users, but the test must also address reflow, text spacing, and changed interaction patterns.
Screen magnification Replaced product and keyboard-shortcut guidance with tests for 200 percent text resize and 400 percent reflow. The original page described 200 percent as a best practice, contained typographical errors, and did not state the Level AA reflow test accurately.
Headings Retained descriptive, hierarchical headings but stated that WCAG does not require exactly one h1. Removed the blanket claim that automated tools cover most heading issues. One h1 and unbroken levels can be useful conventions, but they are not universal WCAG conformance requirements. Tools cannot judge whether headings describe the structure well.
Rendered semantics Added inspection of the final rendered document object model and accessibility tree when generated names, roles, states, properties, or relationships affect the result. Source templates and screenshots do not establish what browsers and assistive technologies receive after rendering.
Color contrast Added the large-text exception and non-text contrast for controls, focus indicators, states, and essential graphics. The original statement that text should always meet 4.5:1 was incomplete.
Icons Replaced the universal requirement for visible accompanying text with checks for understandable visible context, accessible names, and non-color cues. Visible text is often preferable, but an icon can be accessible when its purpose is clear and exposed programmatically.
Forms and errors Added a complete section covering labels, instructions, groups, input purpose, validation, error recovery, redundant entry, authentication, and error prevention. The original page did not provide a usable form-review process despite the importance of forms in Drupal administration.
Sound and video Replaced the media-type assertions with a requirement to apply the correct WCAG criterion based on whether media is live, prerecorded, audio-only, video-only, or synchronized. Captions, transcripts, audio descriptions, and media alternatives are not interchangeable. The original page mixed Level A, AA, and AAA requirements.
Animation and autoplay Replaced the simplified five-second advice with checks for autoplaying audio, moving and auto-updating content, time limits, flashing, and reduced motion. WCAG applies different requirements to these behaviors. One duration rule does not cover them.
Authoring workflows Added separate outcomes for disabled authors, support for producing accessible content, generated output, preservation of accessibility information, defaults, prompts, and repair options. Drupal is an authoring tool. Reviewing only the editor or only public-facing output omits distinct ATAG Part A, ATAG Part B, and WCAG concerns.
Dynamic content Removed the Drupal 8 API link and added visible state, semantics, focus, announcements, loading, completion, empty, and error states. A screen reader alone does not determine whether a dynamic interaction is accessible. Review must cover every affected state and input method.
Screen-reader testing Replaced the long introductory tutorials with a task-based test covering structure, controls, forms, dynamic changes, focus, and content. The review guide should define what to test. Product tutorials and videos change and can be linked from separate learning resources.
Turning off the monitor Removed the instruction and explicitly rejected it as a substitute for testing with blind users. It is a poor simulation of blindness and can create false confidence in a sighted tester’s results.
“Test on as many as you can” Replaced unlimited combinations with a documented matrix of exact browser, operating-system, assistive-technology, task, state, and date information based on project support, affected users, and technical risk. Unbounded testing is not achievable or repeatable. A defined matrix produces evidence reviewers can compare without generalizing one combination.
Link purpose Changed the check to link and button purpose in context. WCAG Level A requires link purpose in context. Requiring every link to make sense independently applies the stricter Level AAA criterion.
Disabled-user testing Added a separate section with scope, task, voluntary participation, privacy, diagnosis, approval-role, public-evidence, reporting, and generalization limits. Disabled-user testing can find barriers missed by conformance evaluation. It does not establish conformance, turn participants into approvers, represent every disabled person, or justify publishing identifying details without permission.
Review artifacts Requires descriptions for information in images and captions or transcripts for recordings needed to understand a result. Reviewers should not need visual-only evidence to understand or reproduce an accessibility result.
Review outcome Added explicit treatments and rationale for confirmed failures, deterministic regressions, review-needed results, pre-existing problems, accepted exceptions, aspirational findings, false positives, and barriers without a WCAG mapping. A review process needs a decision model and a recheck condition for follow-ups or exceptions. A list of checks alone does not determine whether a change is ready.
Needs accessibility review Links to the core gate for the canonical issue-tag indicators and retains the Topic Maintainer signoff meaning. The gate owns the escalation decision, while this page owns the review procedure and evidence. Linking avoids duplicated policy text that could drift.

Content removed or consolidated

Claims not added

The revision does not claim that:

Sources checked