These standards apply to user interfaces and rendered content produced by Drupal core and Drupal.org projects. Contributed projects should follow them and document any additional accessibility requirements.

Accessibility is an outcome for people, not a property that a testing tool can certify. Use these standards while planning, implementing, reviewing, and testing a change.

Standards and scope

Drupal targets Web Content Accessibility Guidelines (WCAG) 2.2 Level AA. Apply all relevant Level A and AA success criteria to the complete user task, including public-facing and administration interfaces.

Drupal is also an authoring tool. Drupal targets Authoring Tool Accessibility Guidelines (ATAG) 2.0 Level AA for applicable authoring functionality. Part A addresses accessibility for authors with disabilities. Part B addresses support for producing accessible content.

Level AAA success criteria and advisory techniques are aspirational under a Level AA target. They should be encouraged when they improve the experience, but reported separately from Level A and AA failures unless another project requirement makes them mandatory.

Start with barriers, not tool results

Accessibility standards and automated tools operate at different levels. Keep these levels distinct:

1. Accessibility barriers affect people. Describe who is affected, what task they are trying to complete, and how the interface prevents or limits that task.
2. Accessibility requirements define expected outcomes. WCAG success criteria, ATAG success criteria, and Drupal policies are requirements, not automated test cases.
3. Test rules evaluate specific conditions. A rule may test part of one requirement, contribute evidence about several requirements, or test a best practice that is not required for WCAG conformance.
4. Automated gates should use the smaller subset of tests that are deterministic in the project’s environment and can fail without routine false positives.

Passing an automated rule does not establish that a WCAG success criterion is satisfied. Passing every rule available in a tool does not establish conformance. Some rules return an incomplete or needs-review result because human judgment is required. Treat those results as review evidence, not automatic failures.

Use semantic HTML first

Use the native HTML element that matches the content or control. Native elements provide semantics and behavior that custom elements must otherwise reproduce. A div or span is appropriate when no semantic element is required, but it must not replace a heading, link, button, list, table, or form control.

• Use headings to identify sections and reflect their hierarchy. Choose levels by structure, not visual size.
• Use lists for list content and data tables for tabular relationships.
• Use landmarks and page regions consistently.
• Keep the source order meaningful when CSS changes the visual layout.
• Identify the page language and changes in language when required.
• Provide text alternatives that communicate the purpose of meaningful non-text content. Use empty alternative text for decorative images.

Use ARIA only when needed

Accessible Rich Internet Applications (WAI-ARIA) can expose names, roles, states, properties, and relationships that HTML does not provide. It does not add keyboard behavior, repair an unsuitable element, or make a custom widget accessible by itself.

• Prefer native HTML when it provides the required semantics and behavior.
• Do not override correct native semantics with an unnecessary or conflicting role.
• Keep ARIA states and properties synchronized with the visible interface.
• Reference elements with valid, unique IDs when using aria-describedby, aria-labelledby, or similar relationships.
• Use accessible names that identify the same purpose as the visible label.

When a Drupal render or Form API property provides the required output, use that property instead of adding ARIA manually. Use #attributes only when no appropriate API property or native HTML relationship is available.

Support keyboard and focus operation

Every action available with a pointer must also be available by keyboard unless the task fundamentally depends on a path-based movement. Provide a non-dragging way to complete drag interactions.

• Use the expected keyboard behavior for the native element or established widget pattern.
• Keep the focus order consistent with the reading and interaction order. Do not use positive tabindex values to repair source order.
• Provide a visible focus indicator with sufficient contrast. Do not allow sticky headers, overlays, or other content to obscure the focused control.
• Do not create a keyboard trap. Constrain focus only when the active pattern requires it and always provide a predictable way to close or leave the context.
• Move focus only when the user action or task requires it. Restore focus to a logical location when a temporary context closes.
• Make content shown on pointer hover also available on keyboard focus and dismissible when required.
• Do not make static content focusable unless keyboard users must interact with or scroll it.

The ARIA Authoring Practices Guide patterns can help define expected interaction for complex widgets. Use them as design guidance, then test the implementation in Drupal’s actual context.

Reuse an established Drupal component when it fits the task and has no known accessibility problem that affects the change. A pattern library, framework, or example does not guarantee an accessible result. A custom component needs documented keyboard behavior, focus behavior, names, roles, states, and regression coverage.

Provide accessible names and instructions

Every control must have an accessible name. Prefer a persistent visible label. A placeholder is not a label, and a title attribute is not a reliable replacement for visible instructions.

• Make the accessible name include the visible label when both are present.
• Write link and button text that identifies the action or destination in context.
• Provide instructions before they are needed and associate them programmatically with the relevant control.
• Do not rely only on position, shape, size, color, sound, or an icon to communicate meaning.
• Keep hidden explanatory text concise and consistent with the visible interface.

Keep navigation and interaction predictable

• Give each page a descriptive title and provide headings that help people understand their location and the available tasks.
• Provide a way to bypass repeated blocks, such as navigation and administration controls.
• Keep repeated navigation, help, and controls in a consistent order and identify controls with the same function consistently.
• Do not change context when a control receives focus. Do not submit, navigate, or substantially change the interface when a value changes unless the behavior is expected or explained in advance.
• After an Ajax update, preserve the user’s position and provide a clear next step. Move focus only when leaving it in place would make the result difficult to find or use.
• Allow users to review, correct, and confirm important submissions when WCAG requires error prevention.

Build accessible forms and errors

Use Drupal’s Form API properties so labels, descriptions, required states, validation, and error relationships are rendered consistently. For example:

$form['email'] = [
  '#type' => 'email',
  '#title' => $this->t('Email address'),
  '#description' => $this->t('Used only for account notifications.'),
  '#required' => TRUE,
];

Do not replace #required with a manually added aria-required attribute. Do not remove #title to hide a label. Use #title_display set to invisible when a visible label is not suitable, and verify that the visible context still identifies the field.

• Group related controls with a fieldset and legend, or the equivalent Form API element.
• Explain input formats and constraints before submission.
• Identify each error in text, associate it with the affected control, and explain how to correct it.
• Make an error summary available at a predictable location and move focus or provide another reliable notification when validation fails.
• Preserve entered values when validation fails unless retaining the value would create a security or privacy risk.
• Do not require users to enter the same information twice in one process when Drupal can provide or select it, subject to WCAG exceptions.
• Support password managers and copying and pasting. Do not require a cognitive-function test where an accessible authentication method can be provided.

The Inline Form Errors module places error messages next to affected controls and provides an error summary. It is included in Drupal core but is not enabled by the Standard installation profile. If a project enables or replaces it, test the complete validation workflow rather than assuming the module resolves every form requirement.

Communicate dynamic changes

When JavaScript or Ajax changes content without moving focus, make meaningful changes available to assistive-technology users. Do not announce every DOM update. Announce the result a user needs to continue the task.

Drupal’s Drupal.announce() API writes translated text to a shared ARIA live region:

Drupal.announce(Drupal.t('Three results were added.'));

The default priority is polite. Use an assertive announcement only for urgent information because it may interrupt other speech. Keep announcements concise, avoid duplicating visible text that is already announced through focus, and update the visible interface before announcing its result.

Use Drupal’s TabbingManager API when an active context must temporarily restrict keyboard navigation:

const tabbingContext = Drupal.tabbingManager.constrain(dialogElement, {
  trapFocus: true,
});

// Release the constraint when the context closes.
tabbingContext.release();

TabbingManager does not make a component accessible. The component still needs correct semantics, expected keyboard commands, initial focus, a visible focus indicator, and logical focus restoration. Set trapFocus only when wrapping focus is required by the interaction.

Support visual presentation and user preferences

• Meet WCAG 2.2 Level AA contrast requirements for text, controls, states, and essential graphics.
• Do not use color as the only way to convey status, selection, errors, or other information.
• Support text resize and reflow without loss of content or functionality. Test responsive states at high zoom, including the equivalent of a 320 CSS-pixel viewport where applicable.
• Do not prevent users from applying WCAG text-spacing adjustments.
• Keep controls and their spacing large enough to meet the WCAG 2.2 target-size requirement, including its exceptions.
• Test system settings such as forced colors and reduced motion when the change affects them.
• Do not remove or weaken browser and operating-system accessibility features.

Drupal’s Hide Content Properly guide explains the hidden, visually-hidden, focusable, and invisible utility classes. Choose the class based on who should receive the content and whether it should occupy layout space. Prefer one consistent experience to separate visible and non-visual instructions.

Use motion and media responsibly

• Provide captions, transcripts, and audio descriptions when the applicable WCAG success criteria require them.
• Provide controls to pause, stop, hide, or adjust time-based content when required.
• Do not create content that flashes more than the applicable threshold.
• Avoid unnecessary motion. Respect prefers-reduced-motion and provide a static or reduced alternative when motion is not essential.
• Do not start audio automatically unless the user can stop it as WCAG requires.

Support accessible authoring

For editors, layout tools, media tools, and other authoring features, test both the authoring interface and its output.

• Make every authoring action available to disabled authors.
• Generate accessible markup and content by default.
• Preserve accessibility information when content is edited, transformed, saved, or reused.
• Prompt authors for required accessibility information, such as text alternatives, without encouraging meaningless values.
• Provide checks, repair guidance, and documentation where authors must make an accessibility decision.
• Give accessibility options the same prominence and usability as comparable authoring options.

Test code and rendered behavior

Test the rendered interface in the pages, states, themes, configurations, and viewports affected by the change. Review source code, but do not assume correct source guarantees correct browser or assistive-technology behavior.

Automated testing

Drupal core uses axe-core in Nightwatch tests to catch regressions on representative pages and interaction states. Automated results are evidence. They are not a count of accessibility barriers and do not establish conformance.

• Map a failed rule to the affected element, user task, and applicable requirement.
• Use deterministic rules for automated build failures. Route context-dependent, incomplete, or unstable results to manual review.
• Report WCAG 2.2 Level A and AA failures separately from Level AAA and best-practice results.
• Add regression coverage for new or substantially changed interactive behavior where practical.
• Run tests after relevant content or interaction states become available, not only on initial page load.
• Keep every disabled rule narrow, explain why it is disabled, and link to an issue that tracks the underlying problem.

Do not use a score or the absence of tool violations as an accessibility target. The target is that people can complete the task and that the applicable accessibility requirements are satisfied.

When an automated result becomes an issue, record the rule and tool version, affected markup or component, page and interaction state, configuration, viewport, steps to reproduce, and expected user outcome. Tool output without this context is not a complete bug report.

Manual and user testing

Automated testing must be combined with relevant manual checks, including keyboard, focus, zoom, reflow, text spacing, contrast, forced colors, reduced motion, and assistive technology. New, complex, or high-impact patterns should be tested with disabled users when possible.

Record enough evidence for another contributor to repeat the test. Follow the guide to performing an accessibility review and the guidance on ensuring a contribution is accessible.