Drupal themes control much of the structure, presentation, and interaction that people experience. A theme can preserve Drupal’s accessible defaults, improve them, or introduce new barriers. Using Drupal core or an accessible base theme does not make the completed site accessible.

Plan accessibility before changing templates, styles, scripts, or components. It is usually easier to preserve appropriate semantics and behavior than to repair a finished theme.

Understand the theme’s responsibility

Accessibility is shared across Drupal core, contributed projects, themes, site configuration, and content. Theme developers are responsible for the output and behavior they add or change.

A theme may affect:

• Page regions, landmarks, headings, navigation, forms, tables, images, and other rendered markup.
• Reading order, focus order, responsive layouts, text presentation, contrast, motion, and visible focus.
• Keyboard behavior, dynamic updates, dialogs, menus, disclosures, and other interactive components.
• Authoring interfaces, previews, layout tools, and the accessibility of generated content.

Test the theme with representative content and configuration. A template may be correct with one view mode or menu depth and fail with another.

Use the relevant standards

Drupal themes should target Web Content Accessibility Guidelines (WCAG) 2.2 Level AA for rendered content and user interfaces. Apply all relevant Level A and AA success criteria to complete user tasks, not only individual pages or components.

When a theme changes an authoring interface or the content it produces, also apply the Authoring Tool Accessibility Guidelines (ATAG) 2.0. 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. Other laws, policies, or project requirements may set additional obligations.

Start with accessible design decisions

Define the people, tasks, content, components, and interface states the theme must support. Include public pages, administration pages affected by the theme, empty and error states, long and translated content, and layouts at different viewport sizes.

During design:

• Use a clear content hierarchy and predictable navigation.
• Choose layouts that support zoom, text resizing, reflow, text-spacing overrides, and different display orientations.
• Meet contrast requirements for text, controls, focus indicators, states, and essential graphics.
• Do not use color, position, shape, sound, or motion as the only way to communicate meaning.
• Keep controls large enough to operate and allow enough space between adjacent targets.
• Provide alternatives to dragging, complex gestures, motion, and time-limited interactions when required.

Do not treat an accessibility toolbar, alternate style sheet, or overlay as remediation. Optional presentation controls may support user preferences, but every default interface and every available variation must remain accessible.

Preserve semantic HTML and Drupal output

Use the native HTML element that matches the content or control. Native elements provide semantics and behavior that custom elements must otherwise reproduce. Use Accessible Rich Internet Applications (ARIA) only when HTML does not provide the required semantics.

When overriding Twig templates or preprocess logic:

• Preserve Drupal attributes, IDs, classes, labels, descriptions, relationships, and states unless the replacement provides an equivalent result.
• Keep the source order consistent with the reading and interaction order, even when CSS changes the visual arrangement.
• Use headings to identify sections. Choose heading levels from the content hierarchy, not their visual appearance.
• Provide appropriate landmarks and accessible names for repeated regions.
• Keep form labels, instructions, required states, errors, and status messages programmatically associated with the relevant controls.
• Use empty alternative text for decorative images and purposeful alternatives for meaningful images.
• Use the appropriate Drupal utility when content must be hidden visually, hidden from everyone, or displayed when it receives focus.

See Theming Drupal for current Twig, asset, attribute, breakpoint, and theme-development documentation. Drupal’s Single-Directory Components can provide maintainable boundaries for reusable HTML, CSS, and JavaScript. A component system does not guarantee accessibility. Each component still needs documented semantics, states, keyboard behavior, and tests.

Make interactions work with different input methods

Every action available with a pointer must also be available by keyboard unless the task fundamentally depends on path-based movement. Do not use a link as a button or add interaction to a generic element when a native control fits the task.

For interactive components:

• Define the accessible name, role, state, value, description, and expected keyboard behavior.
• Keep focus visible and prevent sticky content, overlays, or animation from obscuring it.
• Manage focus when a dialog or other temporary context opens and closes.
• Provide a non-dragging way to complete drag interactions.
• Make content shown on hover also available on keyboard focus and dismissible when required.
• Communicate meaningful Ajax and JavaScript updates without announcing every document change.
• Respect reduced-motion and forced-colors settings when the component is affected by them.

Test the finished behavior in Drupal. Copying an ARIA pattern or using an established component library does not establish that the implementation is accessible.

Support accessible authoring

A theme can affect both the interface used by authors and the content presented to site visitors. When the theme provides layout tools, previews, component options, or content templates:

• Make every authoring action available to disabled authors.
• Generate accessible markup by default.
• Preserve headings, language, alternative text, table structure, and other accessibility information when content is transformed or displayed.
• Do not offer configuration choices that create an inaccessible result without a clear warning or constraint.
• Test authored content in its published context, not only inside the editor or preview.

Test the complete theme

Test representative pages, components, roles, languages, content lengths, responsive layouts, and interaction states. Review both public-facing and administration interfaces when the theme changes them.

Testing should include, when relevant:

• Complete keyboard operation, focus order, visible focus, and focus restoration.
• Text resizing, zoom, reflow, text spacing, orientation, forced colors, and reduced motion.
• Page titles, landmarks, headings, lists, tables, links, forms, errors, and status messages.
• Dynamic content, loading, empty, error, expanded, selected, disabled, and completed states.
• Screen readers and other assistive technologies selected for the affected behavior and supported platforms.
• Testing with disabled users for new, complex, unfamiliar, or high-impact patterns when possible.

Automated tools can find some barriers by applying rules to limited testable conditions. They cannot determine accessibility or WCAG conformance. Use deterministic rules for unattended build failures. Send context-dependent or incomplete results to human review.

Follow How to do an accessibility review and record enough evidence for another contributor to repeat the test.

Maintain accessibility

Document the theme’s supported browsers, assistive technologies, components, known barriers, and testing approach. Add regression tests for stable component behavior where practical. Review accessibility when dependencies, templates, components, or supported platforms change.

Report barriers in the relevant project issue queue. Describe the affected people and task, the expected and actual behavior, the configuration and theme, and the steps required to reproduce the problem.

See Drupal’s Accessibility Coding Standards and How to Ensure Your Contribution is Accessible for implementation and contribution requirements.