fix: Make keyboard focus visible and name the unnamed controls

ui/src/css/base.css

@@ -88,7 +88,11 @@ button::-moz-focus-inner {
 summary {
   cursor: pointer;
   -webkit-tap-highlight-color: transparent;
-  outline: none;
+}
+
+summary:focus-visible {
+  outline: 2px solid currentcolor;
+  outline-offset: 2px;
 }
 
 table {

ui/src/css/doc.css

@@ -132,12 +132,20 @@
   content: "\00a7";
 }
 
+/* A focusable control that only appears on hover is invisible to anyone
+ * tabbing to it, so every reveal below pairs hover with focus. */
 .doc h1:hover .anchor,
 .doc h2:hover .anchor,
 .doc h3:hover .anchor,
 .doc h4:hover .anchor,
 .doc h5:hover .anchor,
-.doc h6:hover .anchor {
+.doc h6:hover .anchor,
+.doc h1 .anchor:focus-visible,
+.doc h2 .anchor:focus-visible,
+.doc h3 .anchor:focus-visible,
+.doc h4 .anchor:focus-visible,
+.doc h5 .anchor:focus-visible,
+.doc h6 .anchor:focus-visible {
   visibility: visible;
 }
 
@@ -841,7 +849,8 @@
   z-index: 1;
 }
 
-.doc .listingblock:hover .source-toolbox {
+.doc .listingblock:hover .source-toolbox,
+.doc .listingblock:focus-within .source-toolbox {
   visibility: visible;
 }
 
@@ -863,14 +872,18 @@
   background: none;
   border: none;
   color: inherit;
-  outline: none;
   padding: 0;
   font-size: inherit;
   line-height: inherit;
   width: 1em;
   height: 1em;
 }
 
+.doc .source-toolbox .copy-button:focus-visible {
+  outline: 2px solid currentcolor;
+  outline-offset: 2px;
+}
+
 .doc .source-toolbox .copy-icon {
   flex: none;
   width: inherit;

ui/src/css/header.css

@@ -189,8 +189,13 @@ body {
   color: var(--navbar-menu-font-color-hover);
 }
 
+/* font: inherit is required, not tidiness: .svg-icon sizes the magnifier in em,
+ * so the UA button font would shrink it from 16px to 13px. */
 #search-button {
+  background: none;
+  border: none;
   cursor: pointer;
+  font: inherit;
   padding-right: 2rem;
 }
 
@@ -201,7 +206,6 @@ body {
 .navbar-burger {
   background: none;
   border: none;
-  outline: none;
   line-height: 1;
   position: relative;
   padding: 0;
@@ -213,6 +217,11 @@ body {
   min-width: 0;
 }
 
+.navbar-burger:focus-visible {
+  outline: 2px solid currentcolor;
+  outline-offset: 2px;
+}
+
 .navbar-burger span {
   background-color: var(--navbar-font-color);
   height: 1.5px;

ui/src/css/nav.css

@@ -117,19 +117,24 @@
   height: 1em;
   margin-right: -0.5rem;
   opacity: 0.75;
-  outline: none;
   padding: 0;
   position: sticky;
   top: calc((var(--nav-line-height) - 1 + 0.5) * 1rem);
   visibility: hidden;
   width: 1em;
 }
 
+.nav-menu-toggle:focus-visible {
+  outline: 2px solid currentcolor;
+  outline-offset: 2px;
+}
+
 .nav-menu-toggle.is-active {
   background-image: url(../img/octicons-16.svg#view-fold);
 }
 
-.nav-panel-menu.is-active:hover .nav-menu-toggle {
+.nav-panel-menu.is-active:hover .nav-menu-toggle,
+.nav-panel-menu.is-active:focus-within .nav-menu-toggle {
   visibility: visible;
 }
 
@@ -173,7 +178,6 @@
 .nav-item-toggle {
   background: transparent url(../img/caret.svg) no-repeat center / 50%;
   border: none;
-  outline: none;
   line-height: inherit;
   padding: 0;
   position: absolute;
@@ -183,6 +187,11 @@
   margin-left: calc(var(--nav-line-height) * -1em);
 }
 
+.nav-item-toggle:focus-visible {
+  outline: 2px solid currentcolor;
+  outline-offset: 2px;
+}
+
 .nav-item.is-active > .nav-item-toggle {
   transform: rotate(90deg);
 }

ui/src/css/tabs.css

@@ -2,3 +2,10 @@
 .tabs {
   margin-top: 1rem;
 }
+
+/* asciidoctor-tabs sets `outline: none` on its tab list items, so keyboard users
+ * cannot see which tab they are on. Imported before this file, so this wins. */
+.tablist > ul li:focus-visible {
+  outline: 2px solid currentcolor;
+  outline-offset: 2px;
+}

ui/src/css/toc.css

@@ -76,7 +76,11 @@
 
 .sidebar.toc .toc-menu a {
   display: block;
-  outline: none;
+}
+
+.sidebar.toc .toc-menu a:focus-visible {
+  outline: 2px solid currentcolor;
+  outline-offset: 2px;
 }
 
 .toc .toc-menu a:hover {

ui/src/css/toolbar.css

@@ -30,14 +30,18 @@
   background: url(../img/menu.svg) no-repeat 50% 47.5%;
   background-size: 49%;
   border: none;
-  outline: none;
   line-height: inherit;
   padding: 0;
   height: var(--toolbar-height);
   width: var(--toolbar-height);
   margin-right: -0.25rem;
 }
 
+.nav-toggle:focus-visible {
+  outline: 2px solid currentcolor;
+  outline-offset: 2px;
+}
+
 @media screen and (min-width: 1024px) {
   .nav-toggle {
     display: none;

ui/src/js/08-search.js

@@ -4,6 +4,7 @@
   function openSearchPopover () {
     document.getElementById('search-background').style.display = 'block'
     document.getElementById('search').style.display = 'block'
+    setSearchExpanded(true)
 
     // the search assets load on first use (see footer-scripts.hbs)
     window.loadSearch().then(function () {
@@ -17,6 +18,12 @@
   function closeSearchPopover () {
     document.getElementById('search-background').style.display = 'none'
     document.getElementById('search').style.display = 'none'
+    setSearchExpanded(false)
+  }
+
+  function setSearchExpanded (expanded) {
+    var button = document.getElementById('search-button')
+    if (button) button.setAttribute('aria-expanded', String(expanded))
   }
 
   function focusSearchInput () {

ui/src/js/09-heading-anchors.js

@@ -0,0 +1,16 @@
+;(function () {
+  'use strict'
+
+  // Asciidoctor emits section anchors as an empty <a class="anchor"> inside the
+  // heading, so they are links with no accessible name -- one per section, and
+  // axe flags every one. The glyph comes from CSS, so there is no text to find:
+  // name them after the heading they link to.
+  var anchors = document.querySelectorAll('.doc a.anchor')
+  Array.prototype.forEach.call(anchors, function (anchor) {
+    if (anchor.getAttribute('aria-label')) return
+    var heading = anchor.parentNode
+    if (!heading) return
+    var text = heading.textContent.trim()
+    if (text) anchor.setAttribute('aria-label', 'Link to ' + text)
+  })
+})()

ui/src/partials/footer-content.hbs

@@ -4,7 +4,7 @@
       <!-- link columns -->
       <div class="footer-info">
         <div class="footer-info-item-large">
-          <img src="{{{uiRootPath}}}/img/logo-2-1.png" width="150" height="26">
+          <img src="{{{uiRootPath}}}/img/logo-2-1.png" width="150" height="26" alt="Stackable">
           <p class="footer-motto">
             your data, your platform
           </p>
@@ -54,16 +54,16 @@
       <div class="c-and-socials">
         <div>© 2025 Stackable.</div>
         <div class="social-icons-container">
-          <a class="social-icon" href="https://www.xing.com/pages/stackable" target="_blank">
+          <a class="social-icon" href="https://www.xing.com/pages/stackable" target="_blank" aria-label="Stackable on Xing">
             <svg class="svg-icon" aria-hidden="true"><use href="#icon-xing"/></svg>
           </a>
-          <a class="social-icon" href="https://www.linkedin.com/company/stackabletech/" target="_blank">
+          <a class="social-icon" href="https://www.linkedin.com/company/stackabletech/" target="_blank" aria-label="Stackable on LinkedIn">
             <svg class="svg-icon" aria-hidden="true"><use href="#icon-linkedin"/></svg>
           </a>
-          <a class="social-icon" href="https://github.com/stackabletech" target="_blank">
+          <a class="social-icon" href="https://github.com/stackabletech" target="_blank" aria-label="Stackable on GitHub">
             <svg class="svg-icon" aria-hidden="true"><use href="#icon-github"/></svg>
           </a>
-          <a class="social-icon" href="https://twitter.com/stackabletech" target="_blank">
+          <a class="social-icon" href="https://twitter.com/stackabletech" target="_blank" aria-label="Stackable on X">
             <svg class="svg-icon" aria-hidden="true"><use href="#icon-twitter"/></svg>
           </a>
         </div>

ui/src/partials/header.hbs

@@ -2,7 +2,7 @@
   <nav class="navbar">
     <div id="topbar-left" class="navbar-brand">
       <a class="navbar-item" href="{{{ relativize (versioned "home" page "index.html") }}}">
-        <img src="{{{uiRootPath}}}/img/stackable-logo.png" width="199" height="30">
+        <img src="{{{uiRootPath}}}/img/stackable-logo.png" width="199" height="30" alt="Stackable">
       </a>
       <a class="navbar-item documentation-link" href="{{{ relativize (versioned "home" page "index.html") }}}">
         Docs
@@ -32,13 +32,13 @@
         <span></span>
         <span></span>
       </button>
-      <div id="search-button" class="navbar-item">
+      <button type="button" id="search-button" class="navbar-item" aria-label="Search" aria-expanded="false" aria-controls="search">
         <svg class="svg-icon" aria-hidden="true"><use href="#icon-search"/></svg>
-        <div id="search-background"></div>
-        <div id="search">
-          <div id="search-input"></div>
-          <ul id="search-results"></ul>
-        </div>
+      </button>
+      <div id="search-background"></div>
+      <div id="search" role="dialog" aria-label="Search">
+        <div id="search-input"></div>
+        <ul id="search-results"></ul>
       </div>
       {{#if @root.page.versions}}
       {{#with @root.page.versions}}

ui/src/partials/toolbar.hbs

@@ -1,7 +1,7 @@
 <div class="toolbar" role="navigation">
 {{> nav-toggle}}
   {{#with site.homeUrl}}
-  <a href="{{{relativize this}}}" class="home-link{{#if @root.page.home}} is-current{{/if}}"></a>
+  <a href="{{{relativize this}}}" class="home-link{{#if @root.page.home}} is-current{{/if}}" aria-label="Home"></a>
   {{/with}}
 {{> breadcrumbs}}
 {{> edit-this-page}}