quarto-dev / quarto-dev/quarto-cli
a11y: narrow-viewport sidebar toolbar is a nav landmark with no links
Nobody has claimed this yet.
- 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.
- With breadcrumbs on (the default), every link is inside a nested
nav.quarto-page-breadcrumbs, which is its own landmark. The postprocessor
swaps it in for the title element:
https://github.com/quarto-dev/quarto-cli/blob/093316c3348715aab8447bd09faa2eca0ca0e98a/src/project/types/website/website-navigation.ts#L470-L482 - With
breadcrumbs: falsethere are no links at all. The<a>at L74 and L78
has nohref. It is a Bootstrap collapse trigger, and #14826 already removed
therole="navigation"androle="link"it used to carry.
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:
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 selectornav.quarto-secondary-navand need updating. - With
breadcrumbs: falsethe bar then holds no landmark at all. Make sure the
page title inside it is still reachable. - The
navigation-toolbar-labellanguage key added by #14813 becomes unused. It
ships in_language.ymland 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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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