Problem/Motivation
Current heading structure in Drupal 8 includes visibly hidden headings, plus H2 and H3 headings that proceed the first H1. This deviates from the following best practices:
- Use H1 to markup the most important heading on the page. Typically this will be the site name on the home page, and on other pages it will be the top-level heading or title of the main unique content.
- Use H2 to markup headings that are secondary to the H1, thereby forming an outline of the page content.
- Don't overuse headings. Headings provide important organizational clues for screen reader users and facilitate navigation (screen reader users can jump between headings with a single keystroke). If there are too many headings or if headings don't form an outline that is consistent with the organizational structure of the page, the benefits of having headings are diminished.
- Avoid hidden headings that are only intended for screen reader users. Instead use HTML5 semantic elements, ARIA roles, and aria-label attributes. These are now widely supported by screen readers, rendering hidden headings obsolete.
Proposed resolution
- Remove all headings that have class="visually-hidden"
- Add an aria-label attribute to the nearest semantic parent element (e.g., nav) and use the text of the visually hidden heading as the value of aria-label
Example:
- Remove
<h2 class="visually-hidden">Toolbar Items</h2> - Add aria-label="Toolbar Items" to nav#toolbar-administration