quarto-dev / quarto-dev/quarto-cli

a11y: narrow-viewport sidebar toolbar is a nav landmark with no links

Open
#14,868 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

accessibility bug themes
Dominant language
JavaScript
Stars
6k
Forks
458
Avg merge
1d 9h
Merged PRs (30d)
41

Description

The bar that appears below the navbar under the lg breakpoint is marked up as a
nav, so it becomes a navigation landmark. It holds the sidebar toggle button,
the page title or the breadcrumbs, and the search button. In neither
configuration does the nav itself hold a navigation link.

https://github.com/quarto-dev/quarto-cli/blob/093316c3348715aab8447bd09faa2eca0ca0e98a/src/resources/projects/website/templates/nav-before-body.ejs#L63-L89

So the landmark holds a button, a heading, and another landmark.

The strip only exists below lg, and the sidebar it toggles is a collapse that
sits under it, so both are in the accessibility tree together when a reader opens
the sidebar:

https://github.com/quarto-dev/quarto-cli/blob/093316c3348715aab8447bd09faa2eca0ca0e98a/src/resources/projects/website/navigation/quarto-nav.scss#L454-L493

This surfaced in review of #14813, which gives every nav landmark a distinct
aria-label. Naming this one is hard because there is no honest navigation word
for it. The label there is Toolbar, which a screen reader announces as
"Toolbar, navigation".

axe does not flag this. landmark-unique only requires that the labels differ,
which #14813 satisfies. This is a markup question, not a rule violation.

Suggested fix

Change the nav to a div and drop its aria-label. The nested breadcrumbs
nav keeps its own landmark and label, so the only difference for a reader is
that the Toolbar entry drops out of the landmark list. Nothing else moves, and
no links become unreachable.

Points to check:

  • Most CSS selectors are class based (.quarto-secondary-nav), but four rules
    use the element selector nav.quarto-secondary-nav and need updating.
  • With breadcrumbs: false the bar then holds no landmark at all. Make sure the
    page title inside it is still reachable.
  • The navigation-toolbar-label language key added by #14813 becomes unused. It
    ships in _language.yml and in all 33 translated files, so remove it before
    1.11 is released rather than after.

Split from #14813. Part of #8706.

Investigated with AI (Claude Code), grounded in a local clone.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with src/resources/projects/website/templates/nav-before-body.ejs and update the four nav.quarto-secondary-nav selectors in src/resources/projects/website/navigation/quarto-nav.scss. Check the breadcrumbs and breadcrumbs: false configurations, then remove navigation-toolbar-label from _language.yml and all 33 translated files. Done means the toolbar is a div, the page title remains reachable, and the nested breadcrumbs landmark is unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
accessibility, frontend, internationalization
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.