revealjs: bundled slide-menu plugin link missing accessible name (axe link-name violation)

[presnick]

Description

The slide menu button (from the bundled reveal.js-menu plugin) renders as <a href="#"> with no text content or aria-label, which fails the axe-core link-name rule (WCAG 2.4.4, Level A).

Screen reader users encounter a link announced as just "link" with no indication of what it does.

Note: The upstream plugin repo (denehyg/reveal.js-menu) is archived, so this can only be fixed in Quarto's bundled copy.

Selector

.slide-menu-button > a[href="#"]

Suggested fix

Add an aria-label to the menu button link:

<a href="#" aria-label="Slide menu">

How to reproduce

1. Create a minimal Quarto revealjs presentation
2. Run axe-core against the rendered HTML:

quarto render presentation.qmd
npx @axe-core/cli file:///path/to/presentation.html

Output:

Violation of "link-name" with 1 occurrences!
  Ensure links have discernible text. Correct invalid elements at:
   - .slide-menu-button > a[href="#"]

Environment

• Quarto 1.9.36
• reveal.js 5.1.0 (bundled)
• axe-core 4.11.1

Reference

• axe-core link-name rule
• WCAG 2.4.4 Link Purpose

[mcanouil]

Thanks, the issue was already known, but now that the plugin project has been archived, waiting for upstream change does not make sense.

• quarto-cli/tests/integration/playwright/tests/axe-accessibility.spec.ts

  Lines 51 to 64 in 64a2120

  	// RevealJS — axe-check.js loads as standalone module (#13781).
  	// RevealJS CSS transforms prevent axe-core from computing color contrast,
  	// so we check for link-name (slide-menu-button has unlabeled <a>).
  	{ format: 'revealjs', outputMode: 'document', url: '/revealjs/axe-accessibility.html',
  	expectedViolation: 'link-name' },
  	{ format: 'revealjs', outputMode: 'console', url: '/revealjs/axe-console.html',
  	expectedViolation: 'link-name' },
  	{ format: 'revealjs', outputMode: 'json', url: '/revealjs/axe-json.html',
  	expectedViolation: 'link-name' },
  	// RevealJS dark theme — verifies CSS custom property bridge for theming.
  	// Report should use --r-background-color/#191919, not the Sass fallback #fff.
  	{ format: 'revealjs-dark', outputMode: 'document', url: '/revealjs/axe-accessibility-dark.html',
  	expectedViolation: 'link-name' },

---

Side note: use the bug template next time.

[presnick]

Thanks for fixing the button label so fast! Wow. (And apologies for not using the bug template; will look for that next time.)

The menu plugin has several other accessibility issues beyond the missing aria-label that we found through screen reader testing. (If it would be better to submit these as a separate issue/bug, let me know and I can do that.)

1. Menu items lack ARIA roles — the toolbar items need role="tablist"/role="tab", and slide list items need role="menu"/role="menuitem" with tabindex="0" for keyboard navigation within the menu.
2. Menu is navigable by screen readers when closed — the menu DOM is always present in the page, so screen readers can tab into it and read its contents even when the menu is visually hidden. The wrapper needs inert when closed.
3. No focus management — when the menu opens, focus stays on the button rather than moving into the menu. When it closes, focus is lost rather than returning to the current slide. This makes the menu essentially unusable via keyboard.

I've been working around these with runtime JavaScript patches via include-in-header. Here's the code — it could serve as a starting point for fixing the plugin source directly.

The code was created by Claude, and I'm not really expert at using the screen reader myself, so I can't promise that this is 100% the right thing. But one visually impaired user did try the slides I generated before and after this patch and said it was much better afterward. Before he was getting distracted by the menu content when he hadn't clicked to open the menu.

// Wait for the menu plugin to create its DOM
var observer = new MutationObserver(function(mutations, obs) {
  var nav = document.querySelector('.slide-menu-wrapper nav.slide-menu');
  if (!nav) return;
  obs.disconnect();

  // Label the nav element
  nav.setAttribute('aria-label', 'Slide navigation menu');

  // Fix toolbar: make it a tablist with proper tab roles
  var toolbar = nav.querySelector('ol.slide-menu-toolbar');
  if (toolbar) {
    toolbar.setAttribute('role', 'tablist');
    toolbar.querySelectorAll('li.toolbar-panel-button').forEach(function(li) {
      li.setAttribute('role', 'tab');
      li.setAttribute('tabindex', '0');
      var label = li.querySelector('.slide-menu-toolbar-label');
      if (label) li.setAttribute('aria-label', label.textContent);
    });
  }

  // Fix slide list items
  nav.querySelectorAll('.slide-menu-items').forEach(function(ul) {
    ul.setAttribute('role', 'menu');
  });
  nav.querySelectorAll('.slide-menu-item').forEach(function(li) {
    li.setAttribute('role', 'menuitem');
    li.setAttribute('tabindex', '0');
    var title = li.querySelector('.slide-menu-item-title');
    if (title) li.setAttribute('aria-label', 'Go to slide: ' + title.textContent);
  });

  // Fix tool items
  nav.querySelectorAll('.slide-tool-item a').forEach(function(a) {
    a.setAttribute('role', 'button');
  });

  // Hide menu from screen readers when closed, manage focus
  var wrapper = document.querySelector('.slide-menu-wrapper');
  if (wrapper) {
    wrapper.inert = true;
    var menuObserver = new MutationObserver(function() {
      var isOpen = nav.classList.contains('active');
      wrapper.inert = !isOpen;
      if (isOpen) {
        var firstItem = nav.querySelector('[role="tab"], [role="menuitem"]');
        if (firstItem) setTimeout(function() { firstItem.focus(); }, 50);
      } else {
        setTimeout(function() {
          var current = document.querySelector('.reveal .slides section.present');
          if (current) {
            var heading = current.querySelector('h1, h2, h3');
            if (heading) {
              heading.setAttribute('tabindex', '-1');
              heading.focus();
            }
          }
        }, 100);
      }
    });
    menuObserver.observe(nav, { attributes: true, attributeFilter: ['class'] });
  }
});

observer.observe(document.body, { childList: true, subtree: true });

These are runtime patches — ideally the fixes would go directly into the plugin source. Happy to help test if you'd like to incorporate any of this.

[mcanouil]

Thanks for fixing the button label so fast! Wow.

It's still require review by the Quarto team.

---

I'll see to update the PR to include the other fixes appropriately, but this might deserve a separate PR/issue.

How can I check the violations for screen-readers as Axe-core does not seem to detect them? Preferably an approach that is not manual.