Consistent focus ring (first pass) (#1549)

* wip

* Style focus state in header nav

* update focus ring style on all focussable elements

* simplify

* fix links in mobile sidebar overlay

* put focus rings around a few more focusable elements

* polish

* update comment

* review

* better align focus ring on collapsible admonitions

* comment and simplify sphinx-togglebutton focus ring

* make css override more explicit

* Fix SD link-card focus ring and on homepage, bring links inside card

* Update docs/index.md

---------

Co-authored-by: Daniel McCloy <[email protected]>

Author: gabalafou

docs/examples/gallery.md

@@ -35,7 +35,7 @@ Thanks for your support!
   link: https://fairlearn.org/main/about/
 - title: Feature-engine
   link: https://feature-engine.readthedocs.io/
-- title: idtracker.ai
+- title: idtracker.ai
   link: https://idtracker.ai/
 - title: MegEngine
   link: https://www.megengine.org.cn/doc/stable/en/index.html

docs/index.md

@@ -21,13 +21,11 @@ A clean, Bootstrap-based Sphinx theme by and for [the PyData community](https://
 - header: "{fas}`circle-half-stroke;pst-color-primary` Light / Dark theme"
   content: "Users can toggle between light and dark themes interactively."
 - header: "{fas}`palette;pst-color-primary` Customizable UI and themes"
-  content: "Customize colors and branding with CSS variables, and build custom UIs with [Sphinx Design](user_guide/web-components)."
+  content: "Customize colors and branding with CSS variables, and build custom UIs with [Sphinx Design components](user_guide/web-components)."
 - header: "{fab}`python;pst-color-primary` Supports PyData and Jupyter"
-  content: "CSS and UI support for Jupyter extensions and PyData execution outputs."
-  link: "examples/pydata.html"
+  content: "CSS and UI support for [Jupyter extensions](examples/execution) and [PyData execution outputs](examples/pydata.ipynb)."
 - header: "{fas}`lightbulb;pst-color-primary` Example Gallery"
-  content: "See our gallery of projects that use this theme."
-  link: "examples/gallery.html"
+  content: "See [our gallery](examples/gallery.md) of projects that use this theme."
 ```
 
 ```{seealso}

src/pydata_sphinx_theme/assets/styles/abstracts/_links.scss

@@ -86,7 +86,6 @@ $link-hover-decoration-thickness: unquote("max(3px, .1875rem, .12em)") !default;
       color: var(--pst-color-link-hover);
     }
   }
-  @include focus-indicator;
 }
 
 // Text link styles
@@ -102,7 +101,6 @@ $link-hover-decoration-thickness: unquote("max(3px, .1875rem, .12em)") !default;
     @include link-decoration;
     @include link-decoration-hover;
   }
-  @include focus-indicator;
 }
 
 // Sidebar and TOC links
@@ -137,10 +135,8 @@ $link-hover-decoration-thickness: unquote("max(3px, .1875rem, .12em)") !default;
   font-weight: 600;
   color: var(--pst-color-primary);
   @if $link-hover-decoration-thickness {
-    box-shadow: inset
-      $link-hover-decoration-thickness
-      0px
-      0px
+    border-left: $link-hover-decoration-thickness
+      solid
       var(--pst-color-primary);
   }
 }
@@ -175,10 +171,3 @@ $link-hover-decoration-thickness: unquote("max(3px, .1875rem, .12em)") !default;
     }
   }
 }
-
-// Focus indicator
-@mixin focus-indicator {
-  &:focus-visible {
-    outline: 2px solid var(--pst-color-accent);
-  }
-}

src/pydata_sphinx_theme/assets/styles/base/_base.scss

@@ -179,3 +179,13 @@ pre {
   background-color: var(--pst-color-secondary);
   border: none;
 }
+
+// Focus ring
+//
+// Note: The Bootstrap stylesheet provides the focus ring (customized via Sass
+// variables in _bootstrap.scss) in some cases. This rules covers all other
+// cases.
+:focus-visible {
+  outline: $focus-ring-outline;
+  box-shadow: none; // override Bootstrap
+}

src/pydata_sphinx_theme/assets/styles/components/_search.scss

@@ -58,8 +58,6 @@
   &:focus,
   &:focus-visible {
     border: none;
-    box-shadow: none;
-    outline: 3px solid var(--pst-color-accent);
     background-color: var(--pst-color-background);
     color: var(--pst-color-text-muted);
   }
@@ -75,11 +73,16 @@
   align-items: center;
   align-content: center;
   color: var(--pst-color-text-muted);
-  // Needed to match other icons hover
-  padding: 0 0 0.25rem 0;
   border-radius: 0;
+  border: none; // Override Bootstrap button border
+  font-size: 1rem; // Override Bootstrap button font size
+
+  // Override Bootstrap button padding-x. Whitespace in nav bar is controlled
+  // via column gap rule on the container.
+  padding-left: 0;
+  padding-right: 0;
+
   @include icon-navbar-hover;
-  @include focus-indicator;
 
   i {
     font-size: 1.3rem;
@@ -136,19 +139,21 @@
  * Lives at components/search-button-field.html
  */
 .search-button-field {
+  $search-button-border-radius: 1.5em;
   display: inline-flex;
   align-items: center;
   border: var(--pst-color-border) solid 1px;
-  border-radius: 1.5em;
+  border-radius: $search-button-border-radius;
   color: var(--pst-color-text-muted);
   padding: 0.5em;
   background-color: var(--pst-color-surface);
 
   &:hover {
     border: 2px solid var(--pst-color-link-hover);
   }
+
   &:focus-visible {
-    border: 2px solid var(--pst-color-accent);
+    border-radius: $search-button-border-radius;
   }
 
   // The keyboard shotcut text

src/pydata_sphinx_theme/assets/styles/components/_switcher-theme.scss

@@ -3,18 +3,23 @@
  */
 
 .theme-switch-button {
-  // overide bootstrap settings
-  margin: 0 -0.5rem;
-  padding: 0; // We pad the `span` not the container
   color: var(--pst-color-text-muted);
   border-radius: 0;
-  @include focus-indicator;
+  border: none; // Override Bootstrap button border
+  font-size: 1rem; // Override Bootstrap's button font size
+
+  // Override Bootstrap button padding-x. Whitespace in nav bar is controlled
+  // via column gap rule on the container.
+  padding-left: 0;
+  padding-right: 0;
+
+  &:hover {
+    @include icon-navbar-hover;
+  }
 
   span {
     display: none;
-    padding: 0.5em;
 
-    @include icon-navbar-hover;
     &:active {
       text-decoration: none;
       color: var(--pst-color-link-hover);

src/pydata_sphinx_theme/assets/styles/components/_switcher-version.scss

@@ -8,7 +8,6 @@ button.btn.version-switcher__button {
   }
 
   @include link-style-hover;
-  @include focus-indicator;
   &:active {
     color: var(--pst-color-text-base);
     border-color: var(--pst-color-border);

src/pydata_sphinx_theme/assets/styles/components/_toc-inpage.scss

@@ -48,4 +48,8 @@ nav.page-toc {
       }
     }
   }
+
+  :focus-visible {
+    border-radius: 0.125rem;
+  }
 }

src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss

@@ -3,13 +3,14 @@
  * Admonitions CSS originally inspired by https://squidfunk.github.io/mkdocs-material/getting-started/
  */
 $admonition-border-radius: 0.25rem;
+$admonition-left-border-width: 0.2rem;
 div.admonition,
 .admonition {
   margin: 1.5625em auto;
   padding: 0 0.6rem 0.8rem 0.6rem;
   overflow: hidden;
   page-break-inside: avoid;
-  border-left: 0.2rem solid;
+  border-left: $admonition-left-border-width solid;
   border-color: var(--pst-color-info);
   border-radius: $admonition-border-radius;
   background-color: var(--pst-color-on-background);
@@ -205,7 +206,7 @@ div.admonition,
     margin-top: 0;
 
     // Undo the .sidebar directive border
-    border-width: 0 0 0 0.2rem;
+    border-width: 0 0 0 $admonition-left-border-width;
 
     // TODO: these semantic-color-names border-color rules might no longer be
     //       needed when we drop support for Sphinx 4 / docutils 0.17

src/pydata_sphinx_theme/assets/styles/extensions/_copybutton.scss

@@ -31,4 +31,13 @@ div.highlight button.copybtn {
     color: var(--pst-color-text);
     background-color: var(--pst-color-surface);
   }
+
+  &:focus {
+    // For keyboard users, make the copy button visible when focussed.
+    opacity: 1;
+  }
+
+  &:focus-visible {
+    outline: $focus-ring-outline;
+  }
 }