Contrib.social

Improve Header Hierarchy Accessibility in Drupal websites using the Gin theme

Open on Drupal.org →
Created on 5 December 2024, about 2 months ago

Problem/Motivation

The current HTML output of the toolbar in Drupal, including themes such as Gin, uses heading tags h2 and h3 for non-content elements like toolbar items and administration menu sections.
These headings appear before the page's main heading (h1), leading to potential issues with the semantic structure of the page and accessibility.

Screen readers may interpret these headings as part of the document hierarchy, which can confuse users by implying a false structure unrelated to the page's main content.

The WAI-ARIA specification provides an alternative approach for conveying heading semantics without disrupting the document hierarchy.
By replacing heading tags with

elements that use the role="heading" and aria-level attributes, the toolbar can retain its accessibility while improving semantic correctness.

Steps to reproduce

1. Install a Drupal 11 site with the latest "gin" theme and the "gin_toolbar" module enabled.
Tested on Drupal 11.0.9, drupal/gin 3.0.0-rc14, and drupal/gin_toolbar 1.0.0-rc6, but this issue is actual for all previous versions for sure.
2. Navigate to the home page or any other page on the site.
3. Inspect the HTML structure of the toolbar using browser developer tools.
4. Observe the following heading structure:

    <h2 class="visually-hidden">Toolbar items</h2>
    <h3 class="toolbar-tray-name visually-hidden">Administration menu</h3>
    <h3 class="toolbar-tray-name visually-hidden">User-defined shortcuts</h3>
... 
... 
... 
<h1 class="title page-title">Welcome!</h1>

5. Note that these headings appear before the main `
` of the page.

Proposed resolution

Replace the heading tags in the toolbar-related templates with `

` elements that include `role="heading"` and `aria-level` attributes. For example: 
<div class="visually-hidden" role="heading" aria-level="2">{{ toolbar_heading }}</div>

This change would maintain accessibility for screen readers while improving the semantic structure of the page.

Remaining tasks

Request feedback from accessibility experts and the community.

User interface changes

No visual changes are expected since the updated elements will remain hidden visually (class="visually-hidden"). The changes only affect the semantic HTML structure and accessibility.

API changes

None. This change only modifies Twig templates and does not affect the API.

Data model changes

None. This change is purely a template and accessibility enhancement.

References

MDN Web Docs on ARIA Roles: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/he...
Explains the use of role="heading" and aria-level attributes for headings.

Why this change is important

This change ensures that the semantic structure of Drupal's toolbar does not interfere with the document's main content hierarchy.
While the current approach does not break functionality, improving semantic correctness aligns with best practices for accessible and clean HTML.

Screen-reader tools (like VoiceOver on Mac) are reading these items and announcing that they are headers (but it could confuse the user, because they are not content-related headers).
Framework Best Practices: Adopting ARIA roles instead of h tags for UI-specific elements (e.g., toolbars, modals) aligns with WCAG best practices.

📌 Task
Status

Active

Component

Code

Created by

🇩🇪Germany kufliievskyi Germany, Bayern

Live updates comments and jobs are added and updated live.
  • Needs accessibility review

    Used to alert the accessibility topic maintainer(s) that an issue significantly affects (or has the potential to affect) the accessibility of Drupal, and their signoff is needed (see the governance policy draft for more information). Useful links: Drupal's accessibility standards, the Drupal Core accessibility gate.

Sign in to follow issues

Merge Requests

Comments & Activities

  • Issue created by @kufliievskyi
  • Pipeline finished with Success
    about 2 months ago
    Total: 338s
    #360706
  • Pipeline finished with Success
    about 2 months ago
    Total: 221s
    #360707
  • Comment about 2 months ago →
    🇩🇪Germany kufliievskyi Germany, Bayern

    The same question applies to the gin_toolbar module, but I've found only one header occurrence in it.
    Don't want to create one more ticket at the moment, because the task requirements are quite debatable.
    So in case someone wants to test both package updates, I've attached 2 simple patches for both gin/gin_toolbar.

    In order to test them together this code snippet could be used:

    {
  "patches": {
    "drupal/gin": {
      "Improve administrative gin theme heading semantics by replacing h tags with a <div>" : "./patches/gin/3492096-gin-improve-header-hierarchy.patch"
    },
    "drupal/gin_toolbar": {
      "Improve administrative gin_toolbar heading semantics by replacing h tags with a <div>" : "./patches/git_toolbar/3492096-gin-toolbar-improve-header-hierarchy.patch"
    }
  }

    I appreciate it if someone with an accessibility background could leave a comment/review it. Thank you in advance for any comments.

  • Comment about 2 months ago →
    🇩🇪Germany kufliievskyi Germany, Bayern
  • Comment about 2 months ago →
    🇩🇪Germany kufliievskyi Germany, Bayern
  • Comment about 2 months ago →
    🇩🇪Germany kufliievskyi Germany, Bayern
  • Comment about 1 month ago →
    rafasmour

    I have reviewed the patch and tested it using Screen Reader (Chrome Extention) and the Accessibility Tree. The heading structure appears to be correctly replaced with

    elements, maintaining the appropriate aria-level hierarchy. The changes are applied correctly and are accessible by screen readers.

    Also corrected the 3492096-gin-improve-header-hierarchy.patch div not closing correctly.

    Everything looks good from an accessibility standpoint. I approve this change for further testing and review.

  • Comment about 1 month ago →
    rafasmour

    I have reviewed the patch and tested it using Screen Reader (Chrome Extention) and the Accessibility Tree. The heading structure appears to be correctly replaced with

    elements, maintaining the appropriate aria-level hierarchy. The changes are applied correctly and are accessible by screen readers.

    Also corrected the 3492096-gin-improve-header-hierarchy.patch div not closing correctly.

    Everything looks good from an accessibility standpoint. I approve this change for further testing and review.

  • Merge request !549Issue #3492096: Improve Header Hierarchy Accessibility in Drupal websites using the Gin theme → (Open) created by saschaeggi
  • Comment about 1 month ago →
    🇨🇭Switzerland saschaeggi Zurich

    The MR needs testing, we're not reviewing patches

    Thanks!

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024