Modernize ARIA usage, in line with ARIA 1.1 and the ARIA Authoring Practices guide.

Created on 10 July 2017, almost 8 years ago
Updated 1 July 2025, 3 days ago

Problem/Motivation

There is still a lot of scope for improving our use of ARIA techniques. During the early phases of D8 development (2012-2013, say) the level of support for ARIA was quite inconsistent across various browsers and assistive technology. Many accessibility issues were decided on the basis of what we could get away with in the present state of technology. Since then, ARIA 1.0 has been more completely implemented. Broadly speaking we've moved from "not ready yet" to dealing with known bugs/quirks, and we are seeing more consensus in the wider accessibility community about how to use ARIA effectively.

Proposed resolution

The new six-monthly release cycle provides scope for modernizing our ARIA usage in stages, adopting new patterns once we feel they are well enough established. Quick wins can come in D8 minor releases, and major changes can be postponed to D9 if necessary.

The W3C ARIA Authoring Practices guide (APG for short) is being developed as a set of best-practice patterns for accessible UI widgets. It provides a good starting point to compare our existing UI widgets against. We don't have to adopt it wholesale though.

Similarly, WAI-ARIA 1.1 is now a W3C recommendation, and introduces some new roles, states and [properties which we can employ.

Some places we could use better ARIA patterns include:

  • Improve the Drop-button pattern (used e.g. to wrap entity operation links).
  • Bartik main menu does not convey open/closed state to assistive tech at small screen breakpoint, and fails "focus visible" for sighted keyboard-only users.
  • Bring our vertical tabs into line with the tabs behaviour described in the ARIA Authoring Practices.
    • Or we could look at contributing upstream to jQuery UI tabs, which already implements some of the keyboard behaviour suggested by the authoring practices. This already ships with Drupal core, but vertical tabs isn't based on it.
    • Also horizontal tabs could follow the APG, if Add horizontal tabs supports to FAPI Active gets into core.
  • #2865199: Adopting ARIA Grid pattern . Could be a good fit for some admin pages where we have form elements in a table (e.g. Field UI's Manage Display).
  • ARIA 1.1 introduces the aria-current property, which can make pagers, breadcrumbs, menus, and multi-step forms, more robust.
    • Use aria-current=page in pagination links. Fixed
    • Use aria-current=page in menu blocks. NEEDS CHILD ISSUE
    • Use aria-current=page in breadcrumb blocks. NEEDS CHILD ISSUE? Might get it for free when fixing menu blocks.
    • Investigate use aria-current=step in multi-step forms. NEEDS CHILD ISSUE. The installer page is an example, where we currently have a visually hidden span to indicate the current step. This is OK but could be replaced with aria-current=step.
  • ARIA 1.1 introduces the aria-errormessage relationship property. We could programatically associate error messages with form inputs, similar to how we use aria-describedby for help text.
  • Using role="progressbar" for Batch API could provide clearer announcements than the current approach which is just a basic live region. See comment #22-24.
  • ARIA 1.1 introduces aria-modal="true" to clarify the behaviour of dialogs. Additionally, HTML 5.2 introduced a <dialog open> element with an accompanying HtmlDialogElement interface. We might employ these eventually. The authoring practices have some advice about how dialog implementation.
  • aria-haspopup="dialog", per ARIA 1.1, does not have good support yet as of Feb 2019. When it does, it should be useful for places where we have dialogs: Views UI, Workspaces, MediaLibraryWidget, Layout builder, etc..
  • aria-haspopup="true", per ARIA 1.0, has good support and can be used for menus like dropbuttons.

Use child issues to explore particular UI widgets in detail.

Remaining tasks

  • Evaluate which new ARIA patterns will be useful to us, especially the ones described in the W3C ARIA Authoring Practices guide.
  • Find examples in the wild.
  • Find other FL/OSS libraries which already provide them.

User interface changes

This is primarily about accessibility improvements, for screen reader users, keyboard-only users, etc..
No major changes propsed to the current designs (visually speaking).
Some markup changes might be necessary; aim to minimize these.

API changes

Possibly some additions to the Javascript API. Some of these ARIA patterns might work as a JS library, or involve expanding the capabilities of existing libraries. On the scale of our existing Drupal.announce() and Drupal.tabbingManager() APIs.

Data model changes

Hopefully none.

🌱 Plan
Status

Active

Version

11.0 🔥

Component

markup

Created by

🇬🇧United Kingdom andrewmacpherson

Live updates comments and jobs are added and updated live.
  • Accessibility

    It affects the ability of people with disabilities or special needs (such as blindness or color-blindness) to use Drupal.

Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

Production build 0.71.5 2024