Overview

When you add a title to a navigation block (using the Navigation.module module) in the admin menu, it is not focusable when tabbing through, whether or not the menu is extended or collapsed. This means that users with a screen reader do not get the information contained within that title, which is formatted as an H2 and provides information about the subitems underneath it.

Steps to Reproduce

  • Login to Drupal, and enable Navigation
  • Observe that all the navigation block elements are <h2> elements, which is the same level as headings in the rest of the page.

Previous Summary: Problem/Motivation

A follow up to #3435989: Add Collapsed Status for Menu Block Title, I've noticed that the titles for navigation blocks cant receive focus when stepping (tabbing) through the navigation. since it is not focusable that structuring / wrapping element is unavailable for a user tabbing through the menu and is going announced/unnoticed to screenreaders in this context. the only cue and information are five headings (just looking at the activated titles for the default navigation blocks). the announcement in voiceover looks like this:

  • h3: Administrative toolbar content
  • h2: SHORTCUTS
  • heading level 4
  • h2: CONTENT
  • heading level 4
  • h2: ADMINiSTRATION
  • heading level 4
  • h3: Administrative toolbar footer
  • h4: RKOLLER

just based on the announcement it is not clear what shortcuts, content, administration, rkoller actually are, or better that shortcuts and the rest of the h2/h4 are actual navigation blocks. with the screenreader you are missing the visual context available to sighted users. about h4: RKOLLER, i would assume it is about my username but there is actually the top level menu item about help wrapped inside as well, therefore the username is inaccurate as a label for the two. In addition to that if the same pattern was followed as for the navigation blocks for the administrative toolbar content region rkoller would have to have h2 instead of h4.
it also has to be noted that there are three empty visually hidden h4 elements. and in general there is no consecutive way getting an announcement of the different parts of the navigation in consecutive order due to the fact that you have headings, and the top level menu items either being buttons (with submenu) or links (without submenu), you have to let voiceover start reading the entire page in consecutive order with (VO-A) to get all parts in context.

Proposed resolution

Discussed with @mgifford, @rkoller, and @kat-shaw about this on a Zoom call.

  1. There should be a parent <h2> element that communicates that this is the administrative sidebar
  2. The <nav> landmark element should use this heading as its accessible name
  3. All nested headings should be <h3>'s to allow a hierarchy.
CommentFileSizeAuthor
#35 headings.jpg173.78 KBrkoller
#33 Cursor_and_Welcome____Drush_Site-Install_and_admin___Drush_Site-Install.png264.87 KBmherchel
#29 Issue-3439643-28-navigation-blocks-default-configuration-voice-over-rotor-headings.png222.31 KBkentr
#28 Issue-3439643-27-navigation-blocks-default-configuration-voice-over-rotor-headings.png68.44 KBkentr
#24 rotor_headings.mp4846.62 KBscottatdrake

Issue fork drupal-3439643

Command icon Show commands

Start within a Git clone of the project using the version control instructions.

Or, if you do not have SSH keys set up on git.drupalcode.org:

About issue forks

Comments

rkoller created an issue. See original summary.

rkoller’s picture

rkoller
he/him
Primary language German
Location Nürnberg, Germany
commented
Parent issue: » #3391723: [PLAN] Accessibility review for new Navigation bar
katannshaw’s picture

katannshaw commented

I'm also seeing three instances of these focusable yet visually-hidden headings.

<h4 id="menu--shortcuts--2" class="toolbar-block__title visually-hidden focusable"></h4>
<h4 id="menu--content" class="toolbar-block__title visually-hidden focusable"></h4>
<h4 id="menu--admin" class="toolbar-block__title visually-hidden focusable"></h4>

Because these are meant to be visually-hidden headings, I'd recommend the following proposed solution:

1. Add missing heading text for each of them
2. Remove the CSS class .focusable

<h4 id="menu--shortcuts--2" class="toolbar-block__title visually-hidden">Shortcuts</h4>
<h4 id="menu--content" class="toolbar-block__title visually-hidden">Content</h4>
<h4 id="menu--admin" class="toolbar-block__title visually-hidden">Administration</h4>
ckrina’s picture

ckrina
she/her
Primary language Catalan
Location Barcelona
commented
Project: Navigation » Drupal core
Version: 1.x-dev » 11.x-dev
Component: Code » navigation.module
ckrina’s picture

ckrina
she/her
Primary language Catalan
Location Barcelona
commented
Issue summary: View changes
Issue tags: +Portland2024, +Novice

Thanks @katannshaw! Updating the issue summary with the detailed recommended approach to make it easier to understand and address the issue.

sjhunsinger’s picture

sjhunsinger commented

Hey there, I'm working on this issue at the Mentored Contribution during DrupalCon Portland 2024. I'll be working on this for the next few hours.

scottatdrake’s picture

scottatdrake commented

Working on this issue during the mentored contribution DrupalCon Portland 2024.

deivalko’s picture

deivalko commented

Hello. I'm working on this at the DrupalCon Mentor Contribution in Portland 2024.

I will be working on this for the next few hours.

hktang’s picture

hktang commented

Hi, I am working on this at the mentor contribution session in Drupalcon in Portland 2024. I will be working on this for the next few hours.

joshmiller’s picture

joshmiller
he/him
Primary language English
Location Indianapolis, Indiana, USA
commented

Hello! I'm working at the mentored contribution in Drupalcon Portland 2024. I will be working on this for the next few hours.

hktang changed the visibility of the branch 3439643-block-title-accessibility to hidden.

hktang changed the visibility of the branch 3439643-block-title-accessibility to hidden.

scottatdrake opened merge request !7973

mrcgomez’s picture

mrcgomez commented

Hello! I'm working at the mentored contribution in Drupalcon Portland 2024. I will be working on this for the next few hours.

emoleee’s picture

emoleee commented

Hello! I'm working at the mentored contribution in Drupalcon Portland 2024 too. I will be working on this for the next few hours.

sjhunsinger’s picture

sjhunsinger commented

So far we have accomplished the following:

  • We are spun up to do the work with DrupalPod/Tugboat.
  • Everyone on our team has posted a comment.

Up next:

  • We have begun to validate the issue so that we reproduce the issue properly. So far we have not been able to recreate. I used a screen reader extension to tab through the admin experience via Tugboat and was not able to recreate.
  • We are going to continue our investigation after lunch and use the parent issue for clues to ensure we are recreating properly.

We'll be back at it after lunch!

emoleee’s picture

emoleee commented

I am working on this issue at DrupalCon 2024 PDX and will be working with it for the next few hours as well.

sjhunsinger’s picture

sjhunsinger commented
Issue summary: View changes
sjhunsinger’s picture

sjhunsinger commented
Issue summary: View changes
sjhunsinger’s picture

sjhunsinger commented
Issue summary: View changes
hktang’s picture

hktang commented

We've got some feedback and further information from @rkoller. We are summarizing these and provide an update soon.

thehuffman’s picture

thehuffman commented

I am also taking a look at this issue as part of contribution day at DrupalCon Portland 2024.

So far I'm not seeing the title variable (see line 4) ever get populated in the navigation--menu.html.twig template. Either way, I'm also seeing a heading level is being skipped between the menu template and its parent block--navigation.html.twig template.

We might consider not outputting a heading in the menu template, and instead provide an aria-label attribute for the <ul>, which would use the title var as its value.

Update:
Assuming I'm looking the right place, I don't think the title var is ever output in the template: https://git.drupalcode.org/project/drupal/-/blob/11.x/core/modules/navig...

scottatdrake’s picture

scottatdrake commented
StatusFileSize
new rotor_headings.mp4846.62 KB

We are out of time today. We spoke with the original opener of this issue, rkoller, via slack. The thread can be found at: https://drupal.slack.com/archives/C7AB68LJV/p1715202081200079

rkoller is using voiceover on a mac, and looking at the headings using voice over's rotor feature. The uploaded video nicely illustrates this.

deivalko’s picture

deivalko commented

Some hopefully useful context:

https://www.w3.org/WAI/tutorials/menus/structure/#label-menus

This is an indication that the invisible h4 tag is desirable, but in the time I've had, I haven't found an explanation for specifically why this is useful or what the outcome should be. That section includes a link to https://www.w3.org/WAI/tutorials/page-structure/labels/ which might be more useful.

jacobupal’s picture

jacobupal commented
Issue summary: View changes
jacobupal’s picture

jacobupal commented
Issue tags: -Novice

Removing novice tag as the next steps require some specialist expertise.

kentr’s picture

kentr commented
StatusFileSize
new Issue-3439643-27-navigation-blocks-default-configuration-voice-over-rotor-headings.png68.44 KB

The markup might have been changed in #3452724: Navigation side bar and top bar should have appropriate aria labels. From what I can tell:

  • block titles are rendered but visually-hidden by default
  • the User block has been renamed. It is no longer the user's name.

With the default configuration, I see h2 in the voiceover rotor headings menu:

Screenshot

So, the IS might need updating.

I can't verify currently b/c I'm experiencing a problem with configuring the block (maybe a bug, and definitely a separate issue): CSS seems to be broken, there's no pencil icon, "Configure" and other options are displayed and very unstyled, and it's not possible to click "Configure".

Here are some notes on the STR from my experience. I'm also not editing the STR b/c someone who is more familiar with it should verify:

  • You need to be on a wider viewport (aka, "desktop" mode).
  • At /admin/config/user-interface/navigation-block, you need to click the "Enable edit mode" button before you see an option to configure anything.
kentr’s picture

kentr commented
Issue tags: +Needs issue summary update
StatusFileSize
new Issue-3439643-28-navigation-blocks-default-configuration-voice-over-rotor-headings.png222.31 KB

It turns out I can click "Configure"...

With titles displayed, there is no h4. It's still just the h2 block titles. This is consistent with #3452724: Navigation side bar and top bar should have appropriate aria labels. For this, I do think it needs an IS update.

However, I still can't reach them with the tab key.

Since it's possible to tab through the menu items, it doesn't seem necessary to also tab to the headings.

Here's a screenshot of the rotor menu when the block titles are displayed.

screenshot

Version: 11.x-dev » main

Drupal core is now using the main branch as the primary development branch. New developments and disruptive changes should now be targeted to the main branch.

Read more in the announcement.

mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented

Discussed with @mgifford, @rkoller, and @kat-shaw about this.

The success criteria is to

  • Add a visually-hidden h2 for the entire navigation. The navigation should use aria-labelledby to point to this.
  • Change all nested navigation blocks to h3s
  • We will not make any changes to the display of the headings (other than the level).
mgifford’s picture

mgifford
he/him
Primary language English
commented

In the meeting we decided that this was a stable blocker.

mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented
Status: Active » Needs review
StatusFileSize
new Cursor_and_Welcome____Drush_Site-Install_and_admin___Drush_Site-Install.png264.87 KB

OK! This should be good to go!

mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented
Issue summary: View changes
Issue tags: -Needs issue summary update

Updating IS

rkoller’s picture

rkoller
he/him
Primary language German
Location Nürnberg, Germany
commented
StatusFileSize
new headings.jpg173.78 KB

looks good thank you! i've tested with voiceover's rotor as well a with this little bookmarklet: https://a11y-tools.com/bookmarklets/#navigateLikeSR

navigate like a screenreader bookmarklet dialog showing the available headings on a page

the only detail to note is that the workspaces menu item is missing a heading. but that is probably a shortcoming on the end of the workspaces module and the menu item needs some refinement? and for reference the administrative sidebar name is discussed in #3539715: Review navigation landmark naming. cuz from my point of view "administrative sidebar" not necessarily communicates that this is the main administrative navigation. but that is out of the scope for this issue, sticking to the status quo in regard to terminology is the right call for this issue.

kentr’s picture

kentr commented

the only detail to note is that the workspaces menu item is missing a heading. but that is probably a shortcoming on the end of the workspaces module and the menu item needs some refinement?

I haven't looked at the code.

If this problem is likely to occur with other modules adding to the Navigation, then it's worth looking at this from the Navigation module: Something like automatically adding headers for sections that are injected from other modules.

In the end, I'd think that it's the Navigation module's responsibility to ensure that everything it renders is structured correctly.

mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented

the only detail to note is that the workspaces menu item is missing a heading. but that is probably a shortcoming on the end of the workspaces module and the menu item needs some refinement?

This is a potential followup issue. Way out of scope for this.

bernardm28’s picture

bernardm28 commented
Status: Needs review » Reviewed & tested by the community

Looks good, I wish we could do something with random like clean_id or something. Other than that, it seems to achieve all the goals.

mherchel’s picture

mherchel
he/him
Primary language English
Location Gainesville, FL, US
commented

Thanks for the review. Yeah, the random() is needed, as the clean_unique_id filter can be problematic in cache

  • longwave committed dcdd4cfc on 11.3.x 
    fix: #3439643 Improve how and what navigation block titles are...

  • longwave committed 9b05c0ff on 11.x 
    fix: #3439643 Improve how and what navigation block titles are...
longwave’s picture

longwave
he/him
Primary language English
Location UK
commented
Version: main » 11.3.x-dev
Status: Reviewed & tested by the community » Fixed

Had the same thought about random vs clean_unique_id but it was answered above. There's already the use of clean_unique_id in this template but then the variables it sets appear to be unused, but that's out of scope to fix here.

Backported to 11.3.x as an eligible accessibility fix. While this does change the markup slightly it's only admin markup and to me the fix outweighs any possible disruption.

Committed and pushed adb94030dfb to main and 9b05c0ff34d to 11.x and dcdd4cfcf53 to 11.3.x. Thanks!

Now that this issue is closed, review the contribution record.

As a contributor, attribute any organization that helped you, or if you volunteered your own time.

Maintainers, credit people who helped resolve this issue.

  • longwave committed adb94030 on main 
    fix: #3439643 Improve how and what navigation block titles are...

longwave closed merge request !7973

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.