Changes to Drupal Accessibility Coding Standards

This document explains the redraft of Accessibility Coding Standards. The original page was last updated on March 4, 2026. Its implementation guidance was checked against Drupal 11.x source, current W3C standards, and Drupal core’s current Nightwatch accessibility tests.

Summary

The revised page remains an implementation standard. It removes product-centered testing targets and distinguishes accessibility barriers, accessibility requirements, tool rules, and automated gates. It consolidates duplicated review instructions and updates Drupal examples without turning the page into an API reference.

The original body contained approximately 2,269 words. The revised body contains 2,099 words, a decrease of 7.5 percent. Repeated testing instructions and product-specific tool recommendations were removed while implementation requirements were expanded.

The revision:

Detailed changes

Changes grouped by original section or claim
Original area Change Reason
Page scope Defined the page as a coding standard for Drupal core and Drupal.org projects, with contributed projects encouraged to follow it and document additional requirements. The original page referred broadly to Drupal, websites, and digital assets without identifying where the standards apply.
Key goals Replaced three abstract goals with a standards-and-scope section followed by testable implementation requirements. Terms such as “inclusive strategy,” “accessible coding,” and “normalized testing” did not tell contributors what code must do.
Barriers and tool results Added a four-layer model: accessibility barriers, accessibility requirements, test rules, and deterministic automated gates. A user barrier, a WCAG success criterion, and an axe rule are different things. Treating them as equivalents encourages misleading counts and unsupported conformance claims.
WCAG and ATAG Retained WCAG 2.2 Level AA. Clarified that WCAG applies to complete user tasks and that ATAG Part A and Part B apply to authoring interfaces and output. The original standards were current, but their scope and relationship to implementation were underspecified.
Level AAA and advisory techniques Defined them as aspirational unless another project requirement makes them mandatory. They should remain visible as stretch goals without being reported as Level AA failures.
General best practices Reorganized the short checklist into requirements for semantics, names, keyboard access, forms, dynamic content, presentation, media, and authoring. The original list omitted several WCAG 2.2 requirements and mixed coding, content, and testing advice.
Semantic HTML video Removed the third-party video and retained the native-HTML-first rule in text. A coding standard should state the rule directly. The video was not needed to understand or maintain it.
ARIA description Replaced “ARIA shims labels for screen readers” with a description of names, roles, states, properties, and relationships. Added requirements to preserve native semantics and synchronize states. ARIA is exposed through accessibility APIs to more than screen readers. It does not merely add labels and does not supply interaction behavior.
aria-required example Replaced manually added aria-required with a current Form API example using #required, #title, and #description. Drupal APIs should generate the associated markup and validation. Manually duplicating a required state can become inconsistent with server-side behavior.
Drupal.announce() Retained the API, updated the example, and added limits on what to announce and when to use assertive priority. The original section treated every dynamic change as a live-region candidate and described assertive output without warning about interruption.
TabbingManager Replaced the Drupal 8 jQuery example with the current options signature, including trapFocus, and documented the API’s limits. The current API can constrain tabbing with or without wrapping focus. It does not provide component semantics, keyboard commands, or focus restoration by itself.
Hiding utilities Reduced the repeated class descriptions to a short summary and linked the dedicated hiding guide. The detailed guidance already has its own page. Duplicating it creates inconsistent updates.
Inline Form Errors Retained the module and confirmed that the Drupal 11.x Standard installation profile does not enable it. Added a requirement to test the complete validation workflow. The module improves error placement but cannot guarantee every form requirement or custom implementation.
Form groups Retained fieldset and legend while removing the claim that radios, checkboxes, Form API, and advanced search always provide them by default. Group semantics depend on the selected Form API elements and templates. The original statement was too broad.
Animation Replaced the long two-query example and article list with requirements for essential motion, reduced motion, flashing, and time-based controls. The original example mixed one implementation technique with a general standard and included subjective language.
Automated coverage percentage Removed the claim that automated tools catch 35 to 40 percent of issues. Coverage depends on the tool, rule set, content, interface state, and definition of an issue. A single percentage is not a stable or useful coding requirement.
“Zero axe errors” and “axe clean” Removed both terms. Automated results are described as evidence from specific rules, pages, states, viewports, and configurations. The terms did not become a useful Drupal standard. They collapse tool output into an accessibility claim and ignore incomplete results, untested requirements, and user barriers.
Tool list Removed the list of browser extensions, services, and integration packages. Tool lists age quickly. The standard should define the evidence and reliability required, while the review guide can discuss tool choices.
False positives Limited unattended build failures to deterministic tests in the project environment. Context-dependent, incomplete, and unstable results are routed to review. Even a low false-positive rate becomes disruptive when tests run across many pages, states, components, and builds. A review lane preserves useful evidence without making unreliable findings block development.
Nightwatch Retained axe-core Nightwatch testing and added requirements for representative states, viewports, regression coverage, and narrowly documented rule exceptions. Current Drupal 11.x tests run axe on public and administration pages, include a mobile viewport, and link disabled rules to follow-up issues.
Keyboard checklist Moved the coding requirements into the keyboard and focus section and linked the detailed review guide for test procedure. The standards page should define the required behavior. Repeating the full review procedure creates maintenance drift.
Scrollable regions Removed the general recommendation to add tabindex="0" to overflowing content. Making a static region focusable changes keyboard navigation and should be based on a demonstrated interaction requirement, not applied as a general fix.
Assistive-technology testing Retained assistive-technology and disabled-user testing but moved detailed procedure to the review guide. Testing by occasional assistive-technology users does not represent the lived experience of disabled users, and neither form of testing replaces standards-based evaluation.

Content removed or consolidated

Claims not added

The revision does not claim that:

Sources checked