docs: Add "skip to main content" a11y feature

Bug: 344643289 Change-Id: I5acc683d7eecc61dbc0b570f83fde326fea0448c Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/213659 Lint: Lint 🤖 <[email protected]> Pigweed-Auto-Submit: Kayce Basques <[email protected]> Reviewed-by: Asad Memon <[email protected]> Presubmit-Verified: CQ Bot Account <[email protected]> Commit-Queue: Auto-Submit <[email protected]>
google · Jun 3, 2024 · fd77c2f · fd77c2f
1 parent f89935d
commit fd77c2f
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 3 deletions.
diff --git a/docs/_static/css/pigweed.css b/docs/_static/css/pigweed.css
@@ -41,6 +41,17 @@
   scroll-behavior: auto !important;
 }
 
+/********** Focus behavior ***********/
+
+/* (a11y) Provide clear visual indication that an element is focused:
+ * https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html
+ *
+ * This rule should be applied to all focusable HTML elements:
+ * https://stackoverflow.com/a/1600194 */
+a:focus, area:focus, button:focus, input:focus, select:focus, textarea:focus {
+  outline: 3px solid var(--color-text-selection-background);
+}
+
 /********** General document coloring ***********/
 
 /* Code blocks inside block quotes end up getting italicized. */
@@ -258,3 +269,20 @@ div.font-monospace {
   border-bottom: 3px solid var(--color-sidebar-link-text);
   padding-bottom: 0.5rem;
 }
+
+/* Position the "skip to main content" anchor offscreen by default.
+ * https://pwbug.dev/344643289 */
+#skip {
+  position: absolute;
+  left: -1000%;
+  top: -1000%;
+  background-color: var(--color-background-primary);
+}
+
+/* Show the "skip to main content" anchor at the top-left of the viewport when
+ * it's focused. */
+#skip:focus {
+  left: 10px;
+  top: 10px;
+  z-index: 1000;
+}
diff --git a/docs/layout/page.html b/docs/layout/page.html
@@ -15,8 +15,14 @@
 -->
 {% extends "furo/page.html" %}
 
+{% block body %}
+  {# (a11y) Always provide the skip link as the very first thing in the body
+     so that people who navigate the site with their keyboard don't need to
+     tab through the entire site nav. https://pwbug.dev/344643289 #}
+  <a id="skip" href="#skip-target">Skip to main content</a>
+  {{ super() }}
+{% endblock body %}
 
-{# Extend the "content" block that's found in "furo/page.html". #}
 {% block content %}
   {% if pagename == 'index' %}
     {# Don't render breadcrumbs on the homepage. #}
@@ -41,7 +47,7 @@
       <li class="breadcrumb">{{ title }}</li>
     </ul>
   {% endif %}
-  {# Let Furo proceed with it's usual rendering of the "content" block. #}
+  {# Focus will be here after using the "skip to main content" link. #}
+  <span id="skip-target"></span>
   {{ super() }}
 {% endblock content %}
-