From 216b120539bf6cfbe4969c288b0a85eca5e73787 Mon Sep 17 00:00:00 2001
From: Charlotte Wickham <cwickham@gmail.com>
Date: Thu, 27 Aug 2026 15:02:38 -0700
Subject: [PATCH] Make website sidebar section toggles keyboard-operable
 buttons

The expandable sidebar sections were <a> elements with no href, so the
keyboard could not reach them at all, and they carried role="navigation",
which made each one an unnamed nested navigation landmark instead of a
named control.

Sections without their own page now render one <button> that holds both
the label and the chevron, so there is a single tabstop. Sections that do
have a page keep their link and get a <button> chevron beside it, named
after the section. Every disclosed list is named with aria-labelledby
pointing at its own section label.

Also removes the duplicated `role` attribute from the mobile sidebar
toggle in nav-before-body.ejs, which was invalid HTML.

Fixes #12116
Fixes #4935
---
 news/changelog-1.11.md                        |  4 ++
 .../website/navigation/quarto-nav.scss        | 42 +++++++++++++++++++
 .../website/templates/nav-before-body.ejs     |  6 +--
 .../website/templates/sidebaritem.ejs         | 12 +++---
 .../website/sidebar-disclosure/.gitignore     |  2 +
 .../website/sidebar-disclosure/_quarto.yml    | 25 +++++++++++
 .../website/sidebar-disclosure/group-a.qmd    | 15 +++++++
 .../website/sidebar-disclosure/group-b.qmd    |  5 +++
 .../website/sidebar-disclosure/index.qmd      | 23 ++++++++++
 .../website/sidebar-disclosure/nested.qmd     |  5 +++
 .../sidebar-disclosure/section-child.qmd      |  5 +++
 .../website/sidebar-disclosure/section.qmd    |  5 +++
 12 files changed, 139 insertions(+), 10 deletions(-)
 create mode 100644 tests/docs/smoke-all/website/sidebar-disclosure/.gitignore
 create mode 100644 tests/docs/smoke-all/website/sidebar-disclosure/_quarto.yml
 create mode 100644 tests/docs/smoke-all/website/sidebar-disclosure/group-a.qmd
 create mode 100644 tests/docs/smoke-all/website/sidebar-disclosure/group-b.qmd
 create mode 100644 tests/docs/smoke-all/website/sidebar-disclosure/index.qmd
 create mode 100644 tests/docs/smoke-all/website/sidebar-disclosure/nested.qmd
 create mode 100644 tests/docs/smoke-all/website/sidebar-disclosure/section-child.qmd
 create mode 100644 tests/docs/smoke-all/website/sidebar-disclosure/section.qmd

diff --git a/news/changelog-1.11.md b/news/changelog-1.11.md
index 35f6ee3a280..cb39df990fe 100644
--- a/news/changelog-1.11.md
+++ b/news/changelog-1.11.md
@@ -1,5 +1,9 @@
 All changes included in 1.11:
 
+## Accessibility
+
+- ([#12116](https://github.com/quarto-dev/quarto-cli/issues/12116), [#4935](https://github.com/quarto-dev/quarto-cli/issues/4935)): Website sidebar section toggles are now `<button>` elements, so the keyboard can reach them and `Enter` or `Space` can operate them. Each toggle carries `aria-expanded`, and `aria-labelledby` names each disclosed list after its own section. The toggles no longer carry `role="navigation"`, which removed a spurious navigation landmark from every section.
+
 ## Engines
 
 ### `knitr`
diff --git a/src/resources/projects/website/navigation/quarto-nav.scss b/src/resources/projects/website/navigation/quarto-nav.scss
index 29932e5791d..aa3ba4065ff 100644
--- a/src/resources/projects/website/navigation/quarto-nav.scss
+++ b/src/resources/projects/website/navigation/quarto-nav.scss
@@ -375,6 +375,48 @@ $sidebar-section-bottom-margin: 0.2em;
   cursor: pointer;
 }
 
+// Section disclosure controls are <button> elements so that they are reachable
+// by keyboard and expose the button role (quarto-cli#12116, quarto-cli#4935).
+// Strip the browser's default button styling so they still look like the
+// sidebar links beside them.
+.sidebar-item .sidebar-item-toggle,
+.sidebar-item button.sidebar-item-text {
+  background: none;
+  border: none;
+  padding: 0;
+  font: inherit;
+  color: inherit;
+  text-align: inherit;
+}
+
+// In a section without its own page, the label and the chevron are one control,
+// so that button has to lay out its own children instead of relying on the
+// flex container. `margin-left: auto` keeps the chevron hard right whether or
+// not the item also has a navicon.
+//
+// `align-items: baseline` is deliberate, not a typo for `center`: it reproduces
+// the line box of the inline `<a>` this button replaced, so row heights and the
+// chevron position are unchanged from 1.10. `center` renders 1-2px shorter per
+// section, which shifts every row below it.
+.sidebar-item button.sidebar-item-text {
+  display: flex;
+  align-items: baseline;
+  width: 100%;
+}
+
+.sidebar-item button.sidebar-item-text > .bi-chevron-right {
+  margin-left: auto;
+  padding-left: 0.5rem;
+}
+
+// A bare button gets no focus ring from Bootstrap's reboot, so state one
+// explicitly rather than depend on the UA default (quarto-cli#14774).
+.sidebar-item .sidebar-item-toggle:focus-visible,
+.sidebar-item button.sidebar-item-text:focus-visible {
+  outline: 2px solid currentColor;
+  outline-offset: 2px;
+}
+
 .sidebar-item .sidebar-item-toggle .bi {
   // The dongle for opening and closing sections
   font-size: 0.7rem;
diff --git a/src/resources/projects/website/templates/nav-before-body.ejs b/src/resources/projects/website/templates/nav-before-body.ejs
index f3115d95262..0dc34c626a5 100644
--- a/src/resources/projects/website/templates/nav-before-body.ejs
+++ b/src/resources/projects/website/templates/nav-before-body.ejs
@@ -71,13 +71,11 @@ const navbarTocRight = nav['toc-location'] === "right" || nav['toc-location'] ==
       </button>
       <% if (nav.showBreadCrumbs) { %>
         <h1 class="quarto-secondary-nav-title no-breadcrumbs"></h1>
-        <a class="flex-grow-1" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" role="link"
-        aria-controls="quarto-sidebar" aria-expanded="false" aria-label="<%- nav.language['toggle-sidebar'] %>"
+        <a class="flex-grow-1" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item"
         onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
         </a>
       <% } else { %>
-        <a class="flex-grow-1 no-decor" role="navigation" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item" role="link"
-        aria-controls="quarto-sidebar" aria-expanded="false" aria-label="<%- nav.language['toggle-sidebar'] %>"
+        <a class="flex-grow-1 no-decor" data-bs-toggle="collapse" data-bs-target=".quarto-sidebar-collapse-item"
         onclick="if (window.quartoToggleHeadroom) { window.quartoToggleHeadroom(); }">      
           <h1 class="quarto-secondary-nav-title"></h1>
         </a>     
diff --git a/src/resources/projects/website/templates/sidebaritem.ejs b/src/resources/projects/website/templates/sidebaritem.ejs
index 784bff938c2..6af4cf9eb72 100644
--- a/src/resources/projects/website/templates/sidebaritem.ejs
+++ b/src/resources/projects/website/templates/sidebaritem.ejs
@@ -19,15 +19,15 @@
     <% if (item.contents.length > 0) { %>
       <div class="sidebar-item-container"> 
           <% if (item.href) { %>
-            <a href="<%- item.href %>" class="sidebar-item-text sidebar-link<%- item.active ? " active" : "" %>"<%= item.rel ? ` rel="${item.rel}"` : "" %><%= item.target ? ` target="${item.target}"` : "" %>><% partial('navicon.ejs', { item }) %> <span class="menu-text"><%= item.text %></span></a>
+            <a href="<%- item.href %>" class="sidebar-item-text sidebar-link<%- item.active ? " active" : "" %>"<%= item.rel ? ` rel="${item.rel}"` : "" %><%= item.target ? ` target="${item.target}"` : "" %>><% partial('navicon.ejs', { item }) %> <span class="menu-text"<%= sectionId ? ` id="${sectionId}-label"` : "" %>><%= item.text %></span></a>
+            <button type="button" class="sidebar-item-toggle text-start<%- isCollapsed ?  " collapsed" : "" %>" data-bs-toggle="collapse" data-bs-target="#<%- sectionId %>"<%= sectionId ? ` aria-controls="${sectionId}"` : "" %> aria-expanded="<%- isCollapsed ? "false" : "true" %>" aria-label="<%- language['toggle-section'] %>: <%- item.text %>">
+              <i class="bi bi-chevron-right ms-2" aria-hidden="true"></i>
+            </button> 
           <% } else { %> 
-            <a class="sidebar-item-text sidebar-link text-start<%- isCollapsed ? " collapsed" : "" %>" data-bs-toggle="collapse" data-bs-target="#<%- sectionId %>"  role="navigation" aria-expanded="<%- isCollapsed ? "false" : "true" %>"><% partial('navicon.ejs', { item }) %> <span class="menu-text"><%= item.text %></span></a>
+            <button type="button" class="sidebar-item-text sidebar-item-toggle sidebar-link text-start<%- isCollapsed ? " collapsed" : "" %>" data-bs-toggle="collapse" data-bs-target="#<%- sectionId %>"<%= sectionId ? ` aria-controls="${sectionId}"` : "" %> aria-expanded="<%- isCollapsed ? "false" : "true" %>"><% partial('navicon.ejs', { item }) %> <span class="menu-text"<%= sectionId ? ` id="${sectionId}-label"` : "" %>><%= item.text %></span><i class="bi bi-chevron-right" aria-hidden="true"></i></button>
           <% }  %>      
-          <a class="sidebar-item-toggle text-start<%- isCollapsed ?  " collapsed" : "" %>" data-bs-toggle="collapse" data-bs-target="#<%- sectionId %>" role="navigation" aria-expanded="<%- isCollapsed ? "false" : "true" %>" aria-label="<%- language['toggle-section'] %>">
-            <i class="bi bi-chevron-right ms-2"></i>
-          </a> 
       </div>
-      <ul id="<%- sectionId %>" class="collapse list-unstyled sidebar-section depth<%-depth%> <%- isCollapsed ? "" : "show" %>">  
+      <ul id="<%- sectionId %>"<%= sectionId ? ` aria-labelledby="${sectionId}-label"` : "" %> class="collapse list-unstyled sidebar-section depth<%-depth%> <%- isCollapsed ? "" : "show" %>">  
         <% item.contents.forEach(subItem => { %>
           <% partial('sidebaritem.ejs', { item: subItem, depth: depth + 1, collapse: collapse, borderColor: borderColor, language: language, draftMode }) %>
         <% }) %>
diff --git a/tests/docs/smoke-all/website/sidebar-disclosure/.gitignore b/tests/docs/smoke-all/website/sidebar-disclosure/.gitignore
new file mode 100644
index 00000000000..ad293093b07
--- /dev/null
+++ b/tests/docs/smoke-all/website/sidebar-disclosure/.gitignore
@@ -0,0 +1,2 @@
+/.quarto/
+**/*.quarto_ipynb
diff --git a/tests/docs/smoke-all/website/sidebar-disclosure/_quarto.yml b/tests/docs/smoke-all/website/sidebar-disclosure/_quarto.yml
new file mode 100644
index 00000000000..2900a1e66cd
--- /dev/null
+++ b/tests/docs/smoke-all/website/sidebar-disclosure/_quarto.yml
@@ -0,0 +1,25 @@
+project:
+  type: website
+  output-dir: .
+
+website:
+  title: "Sidebar disclosure"
+  sidebar:
+    style: docked
+    collapse-level: 1
+    contents:
+      - index.qmd
+      - section: "Group"
+        contents:
+          - group-a.qmd
+          - group-b.qmd
+          - section: "Nested"
+            contents:
+              - nested.qmd
+      - section: section.qmd
+        contents:
+          - section-child.qmd
+
+format:
+  html:
+    theme: cosmo
diff --git a/tests/docs/smoke-all/website/sidebar-disclosure/group-a.qmd b/tests/docs/smoke-all/website/sidebar-disclosure/group-a.qmd
new file mode 100644
index 00000000000..d898eea7377
--- /dev/null
+++ b/tests/docs/smoke-all/website/sidebar-disclosure/group-a.qmd
@@ -0,0 +1,15 @@
+---
+title: "Group A"
+_quarto:
+  tests:
+    html:
+      ensureHtmlElements:
+        - ['button.sidebar-item-toggle[data-bs-target="#quarto-sidebar-section-1"][aria-expanded="true"]',
+           'ul#quarto-sidebar-section-1.show[aria-labelledby="quarto-sidebar-section-1-label"]',
+           'button.sidebar-item-toggle[data-bs-target="#quarto-sidebar-section-2"][aria-expanded="false"]']
+        - ['#quarto-sidebar a.sidebar-item-toggle',
+           '#quarto-sidebar a[role="navigation"]']
+---
+
+The section holding the active page reports `aria-expanded="true"`, while a
+nested section that stays closed still reports `false`.
diff --git a/tests/docs/smoke-all/website/sidebar-disclosure/group-b.qmd b/tests/docs/smoke-all/website/sidebar-disclosure/group-b.qmd
new file mode 100644
index 00000000000..a49211bff5e
--- /dev/null
+++ b/tests/docs/smoke-all/website/sidebar-disclosure/group-b.qmd
@@ -0,0 +1,5 @@
+---
+title: "group-b"
+---
+
+Page group-b.
diff --git a/tests/docs/smoke-all/website/sidebar-disclosure/index.qmd b/tests/docs/smoke-all/website/sidebar-disclosure/index.qmd
new file mode 100644
index 00000000000..3e78889be10
--- /dev/null
+++ b/tests/docs/smoke-all/website/sidebar-disclosure/index.qmd
@@ -0,0 +1,23 @@
+---
+title: "Index"
+_quarto:
+  tests:
+    html:
+      ensureHtmlElements:
+        - ['button.sidebar-item-text.sidebar-item-toggle[data-bs-toggle="collapse"][data-bs-target="#quarto-sidebar-section-1"][aria-controls="quarto-sidebar-section-1"][aria-expanded="false"]',
+           'button.sidebar-item-text.sidebar-item-toggle span.menu-text#quarto-sidebar-section-1-label',
+           'ul#quarto-sidebar-section-1[aria-labelledby="quarto-sidebar-section-1-label"]',
+           'button.sidebar-item-text.sidebar-item-toggle[data-bs-target="#quarto-sidebar-section-2"][aria-expanded="false"]',
+           'ul#quarto-sidebar-section-2[aria-labelledby="quarto-sidebar-section-2-label"]',
+           'a.sidebar-item-text[href="./section.html"] span.menu-text#quarto-sidebar-section-3-label',
+           'button.sidebar-item-toggle[aria-label="Toggle section: section"][aria-expanded="false"][aria-controls="quarto-sidebar-section-3"]',
+           'ul#quarto-sidebar-section-3[aria-labelledby="quarto-sidebar-section-3-label"]']
+        - ['#quarto-sidebar a.sidebar-item-toggle',
+           '#quarto-sidebar a[data-bs-toggle="collapse"]',
+           '#quarto-sidebar a[role="navigation"]',
+           '#quarto-sidebar a[aria-expanded]']
+---
+
+Every sidebar section toggle is a `<button>` with `aria-expanded`, and every
+disclosed list is named by its own section label. See quarto-cli#12116 and
+quarto-cli#4935.
diff --git a/tests/docs/smoke-all/website/sidebar-disclosure/nested.qmd b/tests/docs/smoke-all/website/sidebar-disclosure/nested.qmd
new file mode 100644
index 00000000000..886ed38e19c
--- /dev/null
+++ b/tests/docs/smoke-all/website/sidebar-disclosure/nested.qmd
@@ -0,0 +1,5 @@
+---
+title: "nested"
+---
+
+Page nested.
diff --git a/tests/docs/smoke-all/website/sidebar-disclosure/section-child.qmd b/tests/docs/smoke-all/website/sidebar-disclosure/section-child.qmd
new file mode 100644
index 00000000000..e41b766ae37
--- /dev/null
+++ b/tests/docs/smoke-all/website/sidebar-disclosure/section-child.qmd
@@ -0,0 +1,5 @@
+---
+title: "section-child"
+---
+
+Page section-child.
diff --git a/tests/docs/smoke-all/website/sidebar-disclosure/section.qmd b/tests/docs/smoke-all/website/sidebar-disclosure/section.qmd
new file mode 100644
index 00000000000..8a54a53adab
--- /dev/null
+++ b/tests/docs/smoke-all/website/sidebar-disclosure/section.qmd
@@ -0,0 +1,5 @@
+---
+title: "section"
+---
+
+Page section.