Contrib.social

Links and buttons in toolbar missing accessible name

Open on Drupal.org →
Created on 2 August 2025, 3 months ago

Problem/Motivation

Axe & Accessibility Insights report that several links & buttons in toolbar don't have "discernible text".

Also seen in VoiceOver when tabbing through that link & button names are not included in the output.

Setting to Major because both SCs mentioned in the reports are Level A.

Attaching Accessibility Insights export.

Steps to reproduce

  1. Install profile: standard
  2. Admin theme: Gin
  3. Log in
  4. Collapse the sidebar
  5. Run Axe scan or tab through the links with VoiceOver.

Proposed resolution

They're currently hidden with display: none:

html:not(.admin-toolbar-expanded) .toolbar-menu__item--level-1:not(.toolbar-menu__item--has-dropdown) .toolbar-link span {
    display: none;
}

html:not(.admin-toolbar-expanded) .toolbar-menu__item--level-1 > .toolbar-link span, html:not(.admin-toolbar-expanded) .toolbar-menu__item--level-1 > .toolbar-menu__item--has-dropdown > button {
    display: none;
    opacity: 0;
}

@cwilcox808 noted in #3093378-35: Use ARIA disclosure pattern for submenu buttons in vertical toolbar orientation → that aria-label is problematic for client-side translation:

I'd add that a reason to not name the buttons using an attribute string like aria-label="Site settings menu" is translation software tends to skip aria-label entirely but does translate both visually hidden text and text hidden from everyone (with the hidden attribute, display: none styles, etc.)

So, hide them only visually instead? Here's core's visually-hidden rule. It appears to do the trick playing around in DevTools.

.visually-hidden {
    position: absolute !important;
    overflow: hidden;
    clip: rect(1px, 1px, 1px, 1px);
    width: 1px;
    height: 1px;
    word-wrap: normal;
}

Remaining tasks

User interface changes

  • Improved usability for screen reader users.

API changes

Data model changes

🐛 Bug report
Status

Active

Version

5.0

Component

Code

Created by

🇺🇸United States kentr Durango, CO

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

Merge Requests

Comments & Activities

  • Issue created by @kentr
  • Comment 3 months ago →
    🇺🇸United States kentr Durango, CO
  • Comment 2 months ago →
    🇺🇸United States kentr Durango, CO

    Clarified in STR that it's with the standard installation profile.

  • Comment 2 months ago →
    🇺🇸United States kentr Durango, CO
  • Comment 2 months ago →
    🇮🇳India anweshas Kolkata

    I’d like to work on this issue.

    I’ll start by reproducing the problem on a fresh Drupal site with the Gin theme enabled, using Axe and/or Accessibility Insights to confirm which toolbar links and buttons are missing accessible names.

    Next, I’ll review the relevant template or markup in Gin to add proper accessible names using either visible text, aria-label, or aria-labelledby, ensuring that the fix passes accessibility audits.

    I’ll post my findings and a patch/MR here for review.

  • Comment 2 months ago →
    🇮🇳India anweshas Kolkata
  • Merge request !655Issue #3539420: Fixed accessible text for toolbar links and buttons. → (Open) created by Unnamed author
  • Comment 2 months ago →
    🇮🇳India anweshas Kolkata

    I have pushed my code changes. Here are the results.

  • Pipeline finished with Success
    2 months ago
    Total: 224s
    #570294
  • Comment 2 months ago →
    🇮🇳India anju.philip@zyxware.com

    Hi, I've verified and tested MR!655 and applied the patch successfully on 5.0.x-dev version. The changes are not working as expected.

    1. Go to Appearance.
    2. Enable Gin Admin Theme and set it as the default admin theme.
    3. Create Some Content: Go to Content > Add content > Test Content
    4. Navigate to /admin.
    5. Collapse the Gin sidebar into icon-only mode.
    6. Run accessibility tests using:Axe (Browser extension),NVDA (screen reader)
    7. Observed the changes here

    Testing Result:
    After applying the patch, the toolbar items are still not accessible as expected.NVDA screen reader does not announce the toolbar icons.Axe still reports the following issues: “Links must have discernible text”, “Buttons must have discernible text”
    Attaching the screenshot for reference.

    Thanks

  • Comment about 2 months ago →
    🇮🇳India anweshas Kolkata
  • Comment about 2 months ago →
    🇮🇳India anweshas Kolkata

    Moving this issue for testing.

  • Pipeline finished with Success
    about 2 months ago
    Total: 137s
    #581343
  • Comment about 2 months ago →
    🇮🇳India anju.philip@zyxware.com

    Hi,
    I've verified and tested MR!655 and successfully applied the patch on the 5.0.x-dev version. I followed the steps #9 for testing.

    Testing Results:
    Axe: The previously reported issues — “Links must have discernible text” and “Buttons must have discernible text” — are now resolved after applying the patch.
    NVDA: The screen reader does not announce the toolbar icons when the sidebar is collapsed. This issue still exists.
    Attaching a screenshot for reference.

    Thanks,

  • Comment about 2 months ago →
    🇺🇸United States kentr Durango, CO

    It looks like the MR uses aria-label in places where there's already text.

    I believe the problem is that all of the existing text is hidden with display: none (which completely hides an element, even from AT).

    My suggestion is to avoid aria-label and hide the text names visually, so that they are still available to assistive tech. This avoids redundancy, and recent Slack discussions in the #accessibility channel indicate that visually-hidden text is preferred over aria-label. There's more information on that in the issue summary.

    My quick experiment indicated that using core's visually-hidden CSS solves the problem.

    Off the top of my head, I think it would be possible to replicate the CSS rule into a selector that applies to the text of the elements (they appear to all be wrapped in span) when the toolbar is collapsed. Maybe there's already a selector for this state. I don't remember. I also don't know what the Gin maintainers prefer regarding implementation.

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024