From af45d7ea89bbdd3e40cd066462a68a7feb39f141 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 9 Feb 2023 11:52:53 +0000
Subject: [PATCH 01/64] :memo: Update file names in documentation

---
 docs/community/structure.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/community/structure.md b/docs/community/structure.md
index 9bd143bcf..f16297169 100644
--- a/docs/community/structure.md
+++ b/docs/community/structure.md
@@ -9,14 +9,14 @@ The content is written in a combination of reStructuredText and MyST Markdown.
 ## Location and structure of CSS/JS assets
 
 The CSS and JS for this theme are built for the browser from `src/pydata_sphinx_theme/assets/*` with
-[webpack](https://webpack.js.org/). The main entrypoints are:
+[webpack](https://webpack.js.org/). The main entry points are:
 
-- CSS: `src/pydata_sphinx_theme/assets/styles/index.scss`
+- CSS: `src/pydata_sphinx_theme/assets/styles/pydata-sphinx-theme.scss`
 
   - the main part of the theme assets
   - customizes [Bootstrap](https://getbootstrap.com/) with [Sass](https://sass-lang.com)
 
-- JS: `src/pydata_sphinx_theme/assets/scripts/index.js`
+- JS: `src/pydata_sphinx_theme/assets/scripts/pydata-sphinx-theme.js`
 
   - provides add-on Bootstrap features, as well as some custom navigation behavior
 

From 63af29778386b2e780e39102227de09ff955a122 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 10 Feb 2023 16:53:49 +0000
Subject: [PATCH 02/64] :art: Update mixins to match new colour system

---
 .../assets/styles/variables/_color.scss       | 35 +++++++++++--------
 1 file changed, 21 insertions(+), 14 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index 08ddb4d43..5e1e1abc3 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -78,24 +78,31 @@ $pst-semantic-colors: (
     ),
 );
 
-/*******************************************************************************
-* write the color rules for each theme (light/dark)
-*/
+@mixin create-color-var($key, $value, $identifier: "") {
+  //$identifier is an optional variable - used for the new system
+  @if $identifier != "" {
+    --pst-color-#{$key}-#{$identifier}: #{$value};
+  } @else {
+    --pst-color-#{$key}: #{$value};
+  }
+}
 
-/* NOTE:
- * Mixins enable us to reuse the same definitions for the different modes
- * https://sass-lang.com/documentation/at-rules/mixin
- * #{...} inserts a variable into a CSS selector or property name
- * https://sass-lang.com/documentation/interpolation
- */
 @mixin theme-colors($mode) {
-  // check if this color is defined differently for light/dark
   @each $name, $value in $pst-semantic-colors {
+    // check if there is a map (i.e. multiple light/dark definitions)
     @if type-of($value) == map {
-      $value: map-get($value, $mode);
-    }
-    & {
-      --pst-color-#{$name}: #{$value};
+      // support for single light/dark colour definitions
+      @if map-has-key($value, $mode) {
+        $value: map-get($value, $mode);
+        @include create-color-var($name, $value);
+      } // support for multiple light/dark colour definitions - as our new design system
+      @else {
+        @each $key, $val in $value {
+          @include create-color-var($key, $val, $name);
+        }
+      }
+    } @else {
+      @include create-color-var($name, $value);
     }
   }
   // assign the "duplicate" colors (ones that just reference other variables)

From 06ad7370e9fa5fb739ad0701a11306f92046ddc2 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 10 Feb 2023 18:20:26 +0000
Subject: [PATCH 03/64] :wheelchair: Update colours

---
 .../assets/styles/variables/_color.scss       | 62 ++++++++++++++++---
 1 file changed, 52 insertions(+), 10 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index 5e1e1abc3..c14c94e5c 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -5,21 +5,63 @@
 * NOTE: this theme defines "info == primary" and "warning == secondary"
 */
 $pst-semantic-colors: (
-  "primary": rgb(69, 157, 185),
-  "secondary": rgb(238, 144, 64),
-  "info": rgb(69, 157, 185),
-  "warning": rgb(238, 144, 64),
+  "primary": (
+    //WCAG AA compliant against dark bg
+    "50": #f4fbfc,
+    "100": #e9f6f8,
+    "200": #d0ecf1,
+    "300": #abdde6,
+    "400": #3fb1c5,
+    //WCAG AA compliant against light bg
+    "500": #0a7d91,
+    "600": #085d6c,
+    "700": #064752,
+    "800": #042c33,
+    "900": #021b1f,
+  ),
+  "secondary": (
+    //WCAG AA compliant against dark bg
+    "50": #fbf8fe,
+    "100": #f6f2fe,
+    "200": #ece3fc,
+    "300": #decdfa,
+    "400": #b691f5,
+    //WCAG AA compliant against light bg
+    "500": #894def,
+    "600": #6730c5,
+    "700": #4e2595,
+    "800": #31175f,
+    "900": #1e0e39,
+  ),
+  "info": (
+    "light": #276be9,
+    "light-bg": #eff4fd,
+    "dark": #79a3f2,
+    "dark-bg": #06245d,
+  ),
+  "warning": (
+    "light": #f66a0a,
+    "light-bg": #fff8f2,
+    "dark": #ff9245,
+    "dark-bg": #652a02,
+  ),
   "success": (
-    "light": rgb(40, 167, 69),
-    "dark": rgb(72, 135, 87),
+    "light": #00843f,
+    "light-bg": #ecf6f1,
+    "dark": #5fb488,
+    "dark-bg": #002f17,
   ),
   "attention": (
-    "light": rgb(255, 193, 7),
-    "dark": rgb(220, 169, 15),
+    "light": #f66a0a,
+    "light-bg": #fff8f2,
+    "dark": #ff9245,
+    "dark-bg": #652a02,
   ),
   "danger": (
-    "light": rgb(220, 53, 69),
-    "dark": rgb(203, 70, 83),
+    "light": #d72d47,
+    "light-bg": #fcf1f2,
+    "dark": #e78894,
+    "dark-bg": #4e111b,
   ),
   "text-base": (
     "light": rgb(50, 50, 50),

From 74c2eeadffa6d859ade9ebd7eb8f3eafa550da78 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 10 Feb 2023 19:00:52 +0000
Subject: [PATCH 04/64] :wheelchair: Update foundation and text colours

---
 .../styles/extensions/_sphinx_design.scss     |  3 +-
 .../assets/styles/variables/_color.scss       | 69 +++++++++++--------
 2 files changed, 43 insertions(+), 29 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index f73bd1d86..11d7509ac 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -53,7 +53,8 @@ $extra-semantic-colors: (
   "dark": map-get($pst-semantic-colors, "text-base"),
   "muted": map-get($pst-semantic-colors, "text-muted"),
   "light": rgb(201, 201, 201),
-  "black": rgb(0, 0, 0),
+  "black": hsl(216, 20%, 10%),
+  //gray-900
   "white": rgb(255, 255, 255),
 );
 
diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index c14c94e5c..e8073cda1 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -64,55 +64,68 @@ $pst-semantic-colors: (
     "dark-bg": #4e111b,
   ),
   "text-base": (
-    "light": rgb(50, 50, 50),
-    // Black + 50
-    "dark": rgb(206, 206, 206),
-    // White - 50
+    "light": rgb(34, 40, 50),
+    // gray-800
+    // "dark": #e5e7ea
+    "dark": #ced6dd,
+    // gray-100
   ),
   "text-muted": (
-    "light": rgb(100, 100, 100),
-    // Twice as far from 0 as base
-    "dark": rgb(166, 166, 166),
-    // Twice as far from 256 as base
-  ),
-  "shadow": (
-    "light": rgb(216, 216, 216),
-    "dark": rgb(33, 33, 33),
-  ),
-  "border": (
-    "light": rgb(201, 201, 201),
-    "dark": rgb(192, 192, 192),
-  ),
-  "inline-code": (
-    "light": rgb(232, 62, 140),
-    "dark": rgb(221, 158, 194),
-  ),
-  "target": (
-    "light": rgb(251, 229, 78),
-    "dark": rgb(71, 39, 0),
+    "light": #48566b,
+    // gray-600
+    "dark": #d1d5da,
+    // gray-300
   ),
+  // TODO - update
+  "shadow":
+    (
+      "light": rgb(216, 216, 216),
+      "dark": rgb(33, 33, 33),
+    ),
+  // TODO- update
+  "border":
+    (
+      "light": rgb(201, 201, 201),
+      "dark": rgb(192, 192, 192),
+    ),
+  // TODO - update
+  "inline-code":
+    (
+      "light": rgb(232, 62, 140),
+      "dark": rgb(221, 158, 194),
+    ),
+  // TODO - update
+  "target":
+    (
+      "light": rgb(251, 229, 78),
+      "dark": rgb(71, 39, 0),
+    ),
   // DEPTH COLORS
   // background: color of the canvas / the furthest back layer
   "background":
     (
       "light": rgb(255, 255, 255),
-      "dark": rgb(18, 18, 18),
+      "dark": #14181e,
     ),
   // on-background: provides slight contrast against background
   // (by use of shadows in light theme)
   "on-background":
     (
       "light": rgb(255, 255, 255),
-      "dark": rgb(30, 30, 30),
+      "dark": #222832,
+      // gray-800
     ),
   // surface: object set above the background (without shadows)
   // Uses JupyterLab cell background colors in light/dark theme
   "surface":
     (
-      "light": rgb(245, 245, 245),
-      "dark": rgb(33, 33, 33),
+      "light": #f3f4f5,
+      // gray-100
+      "dark": #364150,
+      // gray-700
     ),
   // on_surface: object on top of surface object (without shadows)
+  //TODO - update
   "on-surface":
     (
       "light": rgb(225, 225, 225),

From 722f4d50be2a1cf679d094f89acfb8acfd2894c3 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 13 Feb 2023 12:11:51 +0000
Subject: [PATCH 05/64] Add more colours - shadows and neutrals

---
 .../assets/styles/variables/_color.scss               | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index e8073cda1..7e51b78fa 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -79,14 +79,15 @@ $pst-semantic-colors: (
   // TODO - update
   "shadow":
     (
-      "light": rgb(216, 216, 216),
-      "dark": rgb(33, 33, 33),
+      // "light": rgb(216, 216, 216),
+      "light": rgba(0, 0, 0, 0.1),
+      "dark": rgba(0, 0, 0, 0.2),
     ),
-  // TODO- update
+  // TODO- update (need muted and regular - this is muted)
   "border":
     (
-      "light": rgb(201, 201, 201),
-      "dark": rgb(192, 192, 192),
+      "light": rgba(23, 23, 26, 0.2),
+      "dark": #48566b,
     ),
   // TODO - update
   "inline-code":

From fbe4f35d1552ce208b224c941eeeccc26ba92b82 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 13 Feb 2023 13:08:12 +0000
Subject: [PATCH 06/64] :wheelchair: Replace text colour function w/WCAG one

---
 .../styles/extensions/_sphinx_design.scss     | 26 ++++++++++++++-----
 1 file changed, 19 insertions(+), 7 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 11d7509ac..12596e103 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -16,12 +16,12 @@
   * https://github.com/executablebooks/sphinx-design/blob/9226a12a/style/_colors.scss#L31-L43
   */
 $sd-semantic-color-names: (
-  "primary",
-  "secondary",
-  "success",
-  "info",
-  "warning",
-  "danger",
+  // "primary",
+  // "secondary",
+  // "success",
+  // "info",
+  // "warning",
+  // "danger",
   "light",
   "muted",
   "dark",
@@ -33,8 +33,17 @@ $sd-semantic-color-names: (
   * function, to make sure that text is legible on colored buttons and badges.
   * https://github.com/executablebooks/sphinx-design/blob/9226a12a/style/_colors.scss#L45-L47
   */
+
 @function text-color($value) {
-  @return if(lightness($value) > 70, #000, #fff);
+  // Using WCAG luminance formula https://www.w3.org/TR/WCAG20/#relativeluminancedef
+  // this function will return text-colour that would meet WCAG AA contrast ratio
+  $luminance: (0.2126 * red($value)) + (0.7152 * green($value)) +
+    (0.0722 * blue($value));
+  @return if(
+    $luminance >= 0.1791,
+    "var(--pst-color-black)",
+    "var(--pst-color-black)"
+  );
 }
 
 /**
@@ -71,11 +80,14 @@ $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
       }
       // define the pst variables, so that downstream user overrides will work
       --pst-color-#{$name}: #{$value};
+      // TODO: update to allow for new scheme
       --pst-color-#{$name}-text: #{text-color($value)};
+      // TODO: check where highlight is used
       --pst-color-#{$name}-highlight: #{darken($value, 15%)};
       // override the sphinx-design variables
       --sd-color-#{$name}: var(--pst-color-#{$name});
       --sd-color-#{$name}-text: var(--pst-color-#{$name}-text);
+      // TODO: check where highlight is used
       --sd-color-#{$name}-highlight: var(--pst-color-#{$name}-highlight);
     }
   }

From 4e71156a04e1f7ad3072669c302a4c122b3ca3d9 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 13 Feb 2023 16:40:43 +0000
Subject: [PATCH 07/64] :recycle: Add full color system to root

---
 .../assets/styles/variables/_color.scss       | 84 +++++++++++++++++--
 1 file changed, 77 insertions(+), 7 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index 7e51b78fa..c3ff7ba82 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -2,8 +2,80 @@
 * master color map. Only the colors that actually differ between light and dark
 * themes are specified separately.
 *
-* NOTE: this theme defines "info == primary" and "warning == secondary"
 */
+
+/* PyData theme - adaptive color scheme */
+/* These are the base colors for the PyData Sphinx theme */
+$theme-colors: (
+  // Primary color
+  "light-blue":
+    (
+      "50": #f4fbfc,
+      "100": #e9f6f8,
+      "200": #d0ecf1,
+      "300": #abdde6,
+      "400": #3fb1c5,
+      "500": #0a7d91,
+      "600": #085d6c,
+      "700": #064752,
+      "800": #042c33,
+      "900": #021b1f,
+    ),
+  // Secondary color
+  "violet":
+    (
+      "50": #fbf8fe,
+      "100": #f6f2fe,
+      "200": #ece3fc,
+      "300": #decdfa,
+      "400": #b691f5,
+      "500": #894def,
+      "600": #6730c5,
+      "700": #4e2595,
+      "800": #31175f,
+      "900": #1e0e39,
+    ),
+  // Neutrals
+  "gray":
+    (
+      "50": #f9f9fa,
+      "100": #f3f4f5,
+      "200": #e5e7ea,
+      "300": #d1d5da,
+      "400": #9ca4af,
+      "500": #677384,
+      "600": #48566b,
+      "700": #364150,
+      "800": #222832,
+      "900": #14181e,
+    ),
+  // Accent color
+  "pink":
+    (
+      "50": #fcf8fd,
+      "100": #fcf0fa,
+      "200": #f8dff5,
+      "300": #f3c7ee,
+      "400": #e47fd7,
+      "500": #c132af,
+      "600": #912583,
+      "700": #6e1c64,
+      "800": #46123f,
+      "900": #2b0b27,
+    )
+);
+
+:root {
+  @each $group-color, $color in $theme-colors {
+    @each $color-name, $value in $color {
+      --pst-#{$group-color}-#{$color-name}: #{$value};
+    }
+  }
+  // Foundation colors
+  --pst-color-white: #ffffff;
+  --pst-color-black: var(--pst-gray-900);
+}
+
 $pst-semantic-colors: (
   "primary": (
     //WCAG AA compliant against dark bg
@@ -89,12 +161,10 @@ $pst-semantic-colors: (
       "light": rgba(23, 23, 26, 0.2),
       "dark": #48566b,
     ),
-  // TODO - update
-  "inline-code":
-    (
-      "light": rgb(232, 62, 140),
-      "dark": rgb(221, 158, 194),
-    ),
+  "inline-code": (
+    "light": var(--pydata-pink-400),
+    "dark": var(--pydata-pink-500),
+  ),
   // TODO - update
   "target":
     (

From e072eb19a2b373200fe7c2a4ea03f383f89a6134 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 13 Feb 2023 16:48:11 +0000
Subject: [PATCH 08/64] :wheelchair: Update variables - use color names

---
 .../assets/styles/variables/_color.scss       | 52 +++++--------------
 1 file changed, 13 insertions(+), 39 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index c3ff7ba82..b5005ae9f 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -78,32 +78,12 @@ $theme-colors: (
 
 $pst-semantic-colors: (
   "primary": (
-    //WCAG AA compliant against dark bg
-    "50": #f4fbfc,
-    "100": #e9f6f8,
-    "200": #d0ecf1,
-    "300": #abdde6,
-    "400": #3fb1c5,
-    //WCAG AA compliant against light bg
-    "500": #0a7d91,
-    "600": #085d6c,
-    "700": #064752,
-    "800": #042c33,
-    "900": #021b1f,
+    light: var(--pst-light-blue-500),
+    dark: var(--pst-light-blue-400),
   ),
   "secondary": (
-    //WCAG AA compliant against dark bg
-    "50": #fbf8fe,
-    "100": #f6f2fe,
-    "200": #ece3fc,
-    "300": #decdfa,
-    "400": #b691f5,
-    //WCAG AA compliant against light bg
-    "500": #894def,
-    "600": #6730c5,
-    "700": #4e2595,
-    "800": #31175f,
-    "900": #1e0e39,
+    light: var(--pst-violet-500),
+    dark: var(--pst-violet-400),
   ),
   "info": (
     "light": #276be9,
@@ -136,17 +116,14 @@ $pst-semantic-colors: (
     "dark-bg": #4e111b,
   ),
   "text-base": (
-    "light": rgb(34, 40, 50),
-    // gray-800
+    "light": var(--pst-gray-800),
     // "dark": #e5e7ea
     "dark": #ced6dd,
     // gray-100
   ),
   "text-muted": (
-    "light": #48566b,
-    // gray-600
-    "dark": #d1d5da,
-    // gray-300
+    "light": var(--pst-gray-600),
+    "dark": var(--pst-gray-300),
   ),
   // TODO - update
   "shadow":
@@ -175,25 +152,22 @@ $pst-semantic-colors: (
   // background: color of the canvas / the furthest back layer
   "background":
     (
-      "light": rgb(255, 255, 255),
-      "dark": #14181e,
+      "light": var(--pst-color-white),
+      "dark": var(--pst-color-black),
     ),
   // on-background: provides slight contrast against background
   // (by use of shadows in light theme)
   "on-background":
     (
-      "light": rgb(255, 255, 255),
-      "dark": #222832,
-      // gray-800
+      "light": var(--pst-color-white),
+      "dark": var(--pst-color-gray-800),
     ),
   // surface: object set above the background (without shadows)
   // Uses JupyterLab cell background colors in light/dark theme
   "surface":
     (
-      "light": #f3f4f5,
-      // gray-100
-      "dark": #364150,
-      // gray-700
+      "light": var(--pst-gray-100),
+      "dark": var(--pst-gray-700),
     ),
   // on_surface: object on top of surface object (without shadows)
   //TODO - update

From 884b8225c7798919c752ef4cc10022a95b554bf4 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 14 Feb 2023 12:53:01 +0000
Subject: [PATCH 09/64] :wheelchair: Ensure all the colours are evaluated
 correctly

---
 .../assets/styles/variables/_color.scss       | 87 ++++++++++++-------
 1 file changed, 54 insertions(+), 33 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index b5005ae9f..9023e3c7a 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -2,10 +2,10 @@
 * master color map. Only the colors that actually differ between light and dark
 * themes are specified separately.
 *
+* To see the full list of colors see https://www.figma.com/file/rUrrHGhUBBIAAjQ82x6pz9/PyData-Design-system---proposal-for-implementation-(2)?node-id=1234%3A765&t=ifcFT1JtnrSshGfi-1
 */
 
-/* PyData theme - adaptive color scheme */
-/* These are the base colors for the PyData Sphinx theme */
+/* Assign base colors for the PyData theme */
 $theme-colors: (
   // Primary color
   "light-blue":
@@ -62,28 +62,52 @@ $theme-colors: (
       "700": #6e1c64,
       "800": #46123f,
       "900": #2b0b27,
-    )
+    ),
+  "foundation": (
+    "white": #ffffff,
+    "black": #14181e,
+  )
 );
 
-:root {
+html {
+  // Add theme colours to the html element
   @each $group-color, $color in $theme-colors {
     @each $color-name, $value in $color {
       --pst-#{$group-color}-#{$color-name}: #{$value};
     }
   }
-  // Foundation colors
-  --pst-color-white: #ffffff;
-  --pst-color-black: var(--pst-gray-900);
+
+  // Minimum contrast ratio used for the theme.
+  // Acceptable values for WCAG 2.0 are 3, 4.5 and 7.
+  // See https://www.w3.org/TR/WCAG20/#visual-audio-contrast-contrast
+  $min-contrast-ratio: 4.5;
+
+  // Customize the light and dark text colors for use in our color contrast function.
+  $color-contrast-dark: #{pst-color-black};
+  $color-contrast-light: #{pst-color-white};
+}
+
+/**
+* Function to get items from nested maps
+*/
+// @param {Map} $map - Map
+// @param {Arglist} $keys - Keys to fetch
+// @return {*}
+@function map-deep-get($map, $keys...) {
+  @each $key in $keys {
+    $map: map-get($map, $key);
+  }
+  @return $map;
 }
 
 $pst-semantic-colors: (
   "primary": (
-    light: var(--pst-light-blue-500),
-    dark: var(--pst-light-blue-400),
+    light: #{map-deep-get($theme-colors, "light-blue", "500")},
+    dark: #{map-deep-get($theme-colors, "light-blue", "400")},
   ),
   "secondary": (
-    light: var(--pst-violet-500),
-    dark: var(--pst-violet-400),
+    light: #{map-deep-get($theme-colors, "violet", "500")},
+    dark: #{map-deep-get($theme-colors, "violet", "400")},
   ),
   "info": (
     "light": #276be9,
@@ -116,14 +140,14 @@ $pst-semantic-colors: (
     "dark-bg": #4e111b,
   ),
   "text-base": (
-    "light": var(--pst-gray-800),
+    "light": #{map-deep-get($theme-colors, "gray", "800")},
     // "dark": #e5e7ea
     "dark": #ced6dd,
     // gray-100
   ),
   "text-muted": (
-    "light": var(--pst-gray-600),
-    "dark": var(--pst-gray-300),
+    "light": #{map-deep-get($theme-colors, "gray", "600")},
+    "dark": #{map-deep-get($theme-colors, "gray", "300")},
   ),
   // TODO - update
   "shadow":
@@ -136,45 +160,42 @@ $pst-semantic-colors: (
   "border":
     (
       "light": rgba(23, 23, 26, 0.2),
-      "dark": #48566b,
+      "dark": #{map-deep-get($theme-colors, "gray", "600")},
     ),
   "inline-code": (
-    "light": var(--pydata-pink-400),
-    "dark": var(--pydata-pink-500),
+    "light": #{map-deep-get($theme-colors, "pink", "600")},
+    "dark": #{map-deep-get($theme-colors, "pink", "300")},
+  ),
+  "target": (
+    "light": #8b6e31,
+    "dark": #c79d41,
   ),
-  // TODO - update
-  "target":
-    (
-      "light": rgb(251, 229, 78),
-      "dark": rgb(71, 39, 0),
-    ),
   // DEPTH COLORS
   // background: color of the canvas / the furthest back layer
   "background":
     (
-      "light": var(--pst-color-white),
-      "dark": var(--pst-color-black),
+      "light": #{map-deep-get($theme-colors, "foundation", "white")},
+      "dark": #{map-deep-get($theme-colors, "foundation", "black")},
     ),
   // on-background: provides slight contrast against background
   // (by use of shadows in light theme)
   "on-background":
     (
-      "light": var(--pst-color-white),
-      "dark": var(--pst-color-gray-800),
+      "light": #{map-deep-get($theme-colors, "foundation", "white")},
+      "dark": #{map-deep-get($theme-colors, "gray", "800")},
     ),
   // surface: object set above the background (without shadows)
   // Uses JupyterLab cell background colors in light/dark theme
   "surface":
     (
-      "light": var(--pst-gray-100),
-      "dark": var(--pst-gray-700),
+      "light": #{map-deep-get($theme-colors, "gray", "100")},
+      "dark": #{map-deep-get($theme-colors, "gray", "700")},
     ),
   // on_surface: object on top of surface object (without shadows)
-  //TODO - update
   "on-surface":
     (
-      "light": rgb(225, 225, 225),
-      "dark": rgb(55, 55, 55),
+      "light": #{map-deep-get($theme-colors, "gray", "800")},
+      "dark": #ced6dd,
     ),
 );
 
@@ -208,7 +229,7 @@ $pst-semantic-colors: (
   // assign the "duplicate" colors (ones that just reference other variables)
   & {
     --pst-color-link: var(--pst-color-primary);
-    --pst-color-link-hover: var(--pst-color-warning);
+    --pst-color-link-hover: var(--pst-color-secondary);
   }
   // adapt to light/dark-specific content
   @if $mode == "light" {

From d520b728c839376a5372f155035a8a8a493a3488 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 14 Feb 2023 20:39:34 +0000
Subject: [PATCH 10/64] Update mixins - move to separate file

---
 .../assets/styles/abstracts/_mixins.scss      | 102 ++++++++++++++++++
 .../assets/styles/variables/_color.scss       |  16 ++-
 2 files changed, 108 insertions(+), 10 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
index 47fc9ed28..a56f59762 100644
--- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
+++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -71,6 +71,26 @@
   }
 }
 
+/**
+ * Assign the admonition colours from our variables
+ */
+@mixin assign-background-color($color-variable) {
+  &:before {
+    content: "";
+    width: 100%;
+    height: 100%;
+    position: absolute;
+    left: 0;
+    top: 0;
+    background-color: var(#{$color-variable}-bg);
+
+    // So that hovering over the text within background is still possible.
+    // Otherwise the background overlays the text and you cannot click or select easily.
+    // ref: https://developer.mozilla.org/en-US/docs/Web/CSS/pointer-events
+    pointer-events: none;
+  }
+}
+
 /**
  * Set background of some cell outputs to white-ish to make sure colors work
  * This is because many libraries make output that only looks good on white
@@ -81,3 +101,85 @@
   border-radius: 0.25rem;
   padding: 0.5rem;
 }
+
+/**
+* Function to calculate the contrast ratio between two colors - this is used to
+* determine the best color to use for text on a given background color. For example,
+* for buttons.
+*/
+@function color-contrast(
+  $background,
+  $color-contrast-dark: $color-contrast-dark,
+  $color-contrast-light: $color-contrast-light,
+  $min-contrast-ratio: $min-contrast-ratio
+) {
+  $foregrounds: $color-contrast-light, $color-contrast-dark, $white, $black;
+  $max-ratio: 0;
+  $max-ratio-color: null;
+
+  @each $color in $foregrounds {
+    $contrast-ratio: contrast-ratio($background, $color);
+    @if $contrast-ratio > $min-contrast-ratio {
+      @return $color;
+    } @else if $contrast-ratio > $max-ratio {
+      $max-ratio: $contrast-ratio;
+      $max-ratio-color: $color;
+    }
+  }
+
+  @warn "Found no color leading to #{$min-contrast-ratio}:1 contrast ratio against #{$background}...";
+
+  @return $max-ratio-color;
+}
+
+// Return WCAG2.1 relative luminance
+// See https://www.w3.org/TR/WCAG/#dfn-relative-luminance
+// See https://www.w3.org/TR/WCAG/#dfn-contrast-ratio
+@function luminance($color) {
+  $rgb: (
+    "r": red($color),
+    "g": green($color),
+    "b": blue($color),
+  );
+
+  @each $name, $value in $rgb {
+    $value: if(
+      divide($value, 255) < 0.04045,
+      divide(divide($value, 255), 12.92),
+      nth($_luminance-list, $value + 1)
+    );
+    $rgb: map-merge(
+      $rgb,
+      (
+        $name: $value,
+      )
+    );
+  }
+
+  @return (map-get($rgb, "r") * 0.2126) + (map-get($rgb, "g") * 0.7152) +
+    (map-get($rgb, "b") * 0.0722);
+}
+
+@function contrast-ratio($background, $foreground: $color-contrast-light) {
+  $l1: luminance($background);
+  $l2: luminance(opaque($background, $foreground));
+
+  @return if(
+    $l1 > $l2,
+    divide($l1 + 0.05, $l2 + 0.05),
+    divide($l2 + 0.05, $l1 + 0.05)
+  );
+}
+
+/**
+* Function to get items from nested maps
+*/
+// @param {Map} $map - Map
+// @param {Arglist} $keys - Keys to fetch
+// @return {*}
+@function map-deep-get($map, $keys...) {
+  @each $key in $keys {
+    $map: map-get($map, $key);
+  }
+  @return $map;
+}
diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index 9023e3c7a..6b3063dce 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -69,7 +69,7 @@ $theme-colors: (
   )
 );
 
-html {
+:root {
   // Add theme colours to the html element
   @each $group-color, $color in $theme-colors {
     @each $color-name, $value in $color {
@@ -111,6 +111,7 @@ $pst-semantic-colors: (
   ),
   "info": (
     "light": #276be9,
+    // TODO: update this to passs the bg colours
     "light-bg": #eff4fd,
     "dark": #79a3f2,
     "dark-bg": #06245d,
@@ -141,21 +142,16 @@ $pst-semantic-colors: (
   ),
   "text-base": (
     "light": #{map-deep-get($theme-colors, "gray", "800")},
-    // "dark": #e5e7ea
     "dark": #ced6dd,
-    // gray-100
   ),
   "text-muted": (
     "light": #{map-deep-get($theme-colors, "gray", "600")},
     "dark": #{map-deep-get($theme-colors, "gray", "300")},
   ),
-  // TODO - update
-  "shadow":
-    (
-      // "light": rgb(216, 216, 216),
-      "light": rgba(0, 0, 0, 0.1),
-      "dark": rgba(0, 0, 0, 0.2),
-    ),
+  "shadow": (
+    "light": rgba(0, 0, 0, 0.1),
+    "dark": rgba(0, 0, 0, 0.2),
+  ),
   // TODO- update (need muted and regular - this is muted)
   "border":
     (

From c4f9894a0c917ce85833b38de7ac57beddbf7749 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Sun, 19 Feb 2023 16:55:13 +0000
Subject: [PATCH 11/64] Update contrast ratios - add comments

---
 .../assets/styles/variables/_color.scss       | 48 ++++++++-----------
 1 file changed, 20 insertions(+), 28 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index 6b3063dce..ec75f0e1c 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -80,6 +80,9 @@ $theme-colors: (
   // Minimum contrast ratio used for the theme.
   // Acceptable values for WCAG 2.0 are 3, 4.5 and 7.
   // See https://www.w3.org/TR/WCAG20/#visual-audio-contrast-contrast
+  // 4.5 - is for text that is 14pt or less
+  $min-contrast-ratio-text: 4.5;
+  // 3 is for text that is 18pt or bold, or for non-text elements
   $min-contrast-ratio: 4.5;
 
   // Customize the light and dark text colors for use in our color contrast function.
@@ -166,7 +169,8 @@ $pst-semantic-colors: (
     "light": #8b6e31,
     "dark": #c79d41,
   ),
-  // DEPTH COLORS
+  // DEPTH COLORS - you can see the elevation colours and shades
+  // in the Figma file https://www.figma.com/file/rUrrHGhUBBIAAjQ82x6pz9/PyData-Design-system---proposal-for-implementation-(2)?node-id=1492%3A922&t=sQeQZehkOzposYEg-1
   // background: color of the canvas / the furthest back layer
   "background":
     (
@@ -180,13 +184,10 @@ $pst-semantic-colors: (
       "light": #{map-deep-get($theme-colors, "foundation", "white")},
       "dark": #{map-deep-get($theme-colors, "gray", "800")},
     ),
-  // surface: object set above the background (without shadows)
-  // Uses JupyterLab cell background colors in light/dark theme
-  "surface":
-    (
-      "light": #{map-deep-get($theme-colors, "gray", "100")},
-      "dark": #{map-deep-get($theme-colors, "gray", "700")},
-    ),
+  "surface": (
+    "light": #{map-deep-get($theme-colors, "gray", "100")},
+    "dark": #{map-deep-get($theme-colors, "gray", "700")},
+  ),
   // on_surface: object on top of surface object (without shadows)
   "on-surface":
     (
@@ -195,32 +196,23 @@ $pst-semantic-colors: (
     ),
 );
 
-@mixin create-color-var($key, $value, $identifier: "") {
-  //$identifier is an optional variable - used for the new system
-  @if $identifier != "" {
-    --pst-color-#{$key}-#{$identifier}: #{$value};
-  } @else {
-    --pst-color-#{$key}: #{$value};
-  }
-}
-
 @mixin theme-colors($mode) {
+  // check if this color is defined differently for light/dark
   @each $name, $value in $pst-semantic-colors {
-    // check if there is a map (i.e. multiple light/dark definitions)
+    @debug "name: #{$name}";
     @if type-of($value) == map {
-      // support for single light/dark colour definitions
-      @if map-has-key($value, $mode) {
-        $value: map-get($value, $mode);
-        @include create-color-var($name, $value);
-      } // support for multiple light/dark colour definitions - as our new design system
-      @else {
-        @each $key, $val in $value {
-          @include create-color-var($key, $val, $name);
+      @each $key, $val in $value {
+        // since now we define the bg colours in the semantic colours and not
+        // by changing opacity, we need to check if the key contains bg
+        @if (str-index($key, "bg")) != null {
+          @debug "key: #{$key}";
+          @debug "val: #{$val}";
+          --pst-color-#{$key}: #{$val};
         }
       }
-    } @else {
-      @include create-color-var($name, $value);
+      $value: map-get($value, $mode);
     }
+    --pst-color-#{$name}: #{$value};
   }
   // assign the "duplicate" colors (ones that just reference other variables)
   & {

From fe6fe763570de27723bbf99a847237da26f407c4 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Sun, 19 Feb 2023 17:33:48 +0000
Subject: [PATCH 12/64] =?UTF-8?q?=E2=99=BF=EF=B8=8F=20=20Add=20luminance?=
 =?UTF-8?q?=20formula=20and=20ignore=20text=20col=20for=20now?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../assets/styles/abstracts/_mixins.scss      |  69 --------
 .../styles/extensions/_sphinx_design.scss     | 154 ++++++++++++++----
 .../assets/styles/variables/_color.scss       |  56 +++----
 3 files changed, 151 insertions(+), 128 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
index a56f59762..ca8e17096 100644
--- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
+++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -102,75 +102,6 @@
   padding: 0.5rem;
 }
 
-/**
-* Function to calculate the contrast ratio between two colors - this is used to
-* determine the best color to use for text on a given background color. For example,
-* for buttons.
-*/
-@function color-contrast(
-  $background,
-  $color-contrast-dark: $color-contrast-dark,
-  $color-contrast-light: $color-contrast-light,
-  $min-contrast-ratio: $min-contrast-ratio
-) {
-  $foregrounds: $color-contrast-light, $color-contrast-dark, $white, $black;
-  $max-ratio: 0;
-  $max-ratio-color: null;
-
-  @each $color in $foregrounds {
-    $contrast-ratio: contrast-ratio($background, $color);
-    @if $contrast-ratio > $min-contrast-ratio {
-      @return $color;
-    } @else if $contrast-ratio > $max-ratio {
-      $max-ratio: $contrast-ratio;
-      $max-ratio-color: $color;
-    }
-  }
-
-  @warn "Found no color leading to #{$min-contrast-ratio}:1 contrast ratio against #{$background}...";
-
-  @return $max-ratio-color;
-}
-
-// Return WCAG2.1 relative luminance
-// See https://www.w3.org/TR/WCAG/#dfn-relative-luminance
-// See https://www.w3.org/TR/WCAG/#dfn-contrast-ratio
-@function luminance($color) {
-  $rgb: (
-    "r": red($color),
-    "g": green($color),
-    "b": blue($color),
-  );
-
-  @each $name, $value in $rgb {
-    $value: if(
-      divide($value, 255) < 0.04045,
-      divide(divide($value, 255), 12.92),
-      nth($_luminance-list, $value + 1)
-    );
-    $rgb: map-merge(
-      $rgb,
-      (
-        $name: $value,
-      )
-    );
-  }
-
-  @return (map-get($rgb, "r") * 0.2126) + (map-get($rgb, "g") * 0.7152) +
-    (map-get($rgb, "b") * 0.0722);
-}
-
-@function contrast-ratio($background, $foreground: $color-contrast-light) {
-  $l1: luminance($background);
-  $l2: luminance(opaque($background, $foreground));
-
-  @return if(
-    $l1 > $l2,
-    divide($l1 + 0.05, $l2 + 0.05),
-    divide($l2 + 0.05, $l1 + 0.05)
-  );
-}
-
 /**
 * Function to get items from nested maps
 */
diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 12596e103..2dac34e30 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -7,6 +7,7 @@
  */
 
 @use "../variables/color" as *;
+@use "sass:color" as color;
 
 /*******************************************************************************
   * Color and variables
@@ -16,12 +17,12 @@
   * https://github.com/executablebooks/sphinx-design/blob/9226a12a/style/_colors.scss#L31-L43
   */
 $sd-semantic-color-names: (
-  // "primary",
-  // "secondary",
-  // "success",
-  // "info",
-  // "warning",
-  // "danger",
+  "primary",
+  "secondary",
+  "success",
+  "info",
+  "warning",
+  "danger",
   "light",
   "muted",
   "dark",
@@ -29,20 +30,110 @@ $sd-semantic-color-names: (
   "white"
 );
 
-/* Here we incorporate a modified version of sphinx-design's text-color
-  * function, to make sure that text is legible on colored buttons and badges.
-  * https://github.com/executablebooks/sphinx-design/blob/9226a12a/style/_colors.scss#L45-L47
-  */
+// A list of pre-calculated numbers of pow(divide((divide($value, 255) + .055), 1.055), 2.4). (from 0 to 255)
+$_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
+  0.0027 0.003 0.0033 0.0037 0.004 0.0044 0.0048 0.0052 0.0056 0.006 0.0065
+  0.007 0.0075 0.008 0.0086 0.0091 0.0097 0.0103 0.011 0.0116 0.0123 0.013
+  0.0137 0.0144 0.0152 0.016 0.0168 0.0176 0.0185 0.0194 0.0203 0.0212 0.0222
+  0.0232 0.0242 0.0252 0.0262 0.0273 0.0284 0.0296 0.0307 0.0319 0.0331 0.0343
+  0.0356 0.0369 0.0382 0.0395 0.0409 0.0423 0.0437 0.0452 0.0467 0.0482 0.0497
+  0.0513 0.0529 0.0545 0.0561 0.0578 0.0595 0.0612 0.063 0.0648 0.0666 0.0685
+  0.0704 0.0723 0.0742 0.0762 0.0782 0.0802 0.0823 0.0844 0.0865 0.0887 0.0908
+  0.0931 0.0953 0.0976 0.0999 0.1022 0.1046 0.107 0.1095 0.1119 0.1144 0.117
+  0.1195 0.1221 0.1248 0.1274 0.1301 0.1329 0.1356 0.1384 0.1413 0.1441 0.147
+  0.15 0.1529 0.1559 0.159 0.162 0.1651 0.1683 0.1714 0.1746 0.1779 0.1812
+  0.1845 0.1878 0.1912 0.1946 0.1981 0.2016 0.2051 0.2086 0.2122 0.2159 0.2195
+  0.2232 0.227 0.2307 0.2346 0.2384 0.2423 0.2462 0.2502 0.2542 0.2582 0.2623
+  0.2664 0.2705 0.2747 0.2789 0.2831 0.2874 0.2918 0.2961 0.3005 0.305 0.3095
+  0.314 0.3185 0.3231 0.3278 0.3325 0.3372 0.3419 0.3467 0.3515 0.3564 0.3613
+  0.3663 0.3712 0.3763 0.3813 0.3864 0.3916 0.3968 0.402 0.4072 0.4125 0.4179
+  0.4233 0.4287 0.4342 0.4397 0.4452 0.4508 0.4564 0.4621 0.4678 0.4735 0.4793
+  0.4851 0.491 0.4969 0.5029 0.5089 0.5149 0.521 0.5271 0.5333 0.5395 0.5457
+  0.552 0.5583 0.5647 0.5711 0.5776 0.5841 0.5906 0.5972 0.6038 0.6105 0.6172
+  0.624 0.6308 0.6376 0.6445 0.6514 0.6584 0.6654 0.6724 0.6795 0.6867 0.6939
+  0.7011 0.7084 0.7157 0.7231 0.7305 0.7379 0.7454 0.7529 0.7605 0.7682 0.7758
+  0.7835 0.7913 0.7991 0.807 0.8148 0.8228 0.8308 0.8388 0.8469 0.855 0.8632
+  0.8714 0.8796 0.8879 0.8963 0.9047 0.9131 0.9216 0.9301 0.9387 0.9473 0.956
+  0.9647 0.9734 0.9823 0.9911 1;
+
+@function a11y-combination(
+  $bg,
+  $target-color-contrast-dark: $foundation-black,
+  $target-color-contrast-light: $base-light-text,
+  $target-color-contrast-white: $foundation-white,
+  $min-contrast-ratio: $min-contrast-ratio
+) {
+  // will test against our two base foreground colors
+  $foregrounds: $target-color-contrast-light, $target-color-contrast-dark;
+  $max-ratio: 0;
+  $max-ratio-color: null;
+
+  @debug "Using AA #{$min-contrast-ratio}:1 contrast ratio for #{$bg} ♿️";
+  @each $fg in $foregrounds {
+    $contrast-ratio: get-contrast-ratio($bg, $fg);
+    @debug "Contrast ratio for #{$bg} and #{$fg} is #{$contrast-ratio}... 🔴";
+    @if $contrast-ratio >= $min-contrast-ratio {
+      @return $fg;
+    } @else if $contrast-ratio > $max-ratio {
+      $max-ratio: $contrast-ratio;
+      $max-ratio-color: $fg;
+    }
+  }
+  @warn "Found no color leading to #{$min-contrast-ratio}:1 contrast ratio against #{$bg}...";
+
+  @return $max-ratio-color;
+}
+
+@function get-contrast-ratio($bg, $foreground: #ced6dd) {
+  @debug "Calculating contrast ratio for #{$bg} 💡";
+  $l1: luminance($bg);
+  $l2: luminance($foreground);
+
+  // return the relative contrast ratio
+  @if $l1 > $l2 {
+    @return ($l1 + 0.05) / ($l2 + 0.05);
+  } @else {
+    @return ($l2 + 0.05) / ($l1 + 0.05);
+  }
+}
+
+// Return WCAG2.1 relative luminance
+// See https://www.w3.org/TR/WCAG/#dfn-relative-luminance
+// See https://www.w3.org/TR/WCAG/#dfn-contrast-ratio
 
-@function text-color($value) {
-  // Using WCAG luminance formula https://www.w3.org/TR/WCAG20/#relativeluminancedef
-  // this function will return text-colour that would meet WCAG AA contrast ratio
-  $luminance: (0.2126 * red($value)) + (0.7152 * green($value)) +
-    (0.0722 * blue($value));
-  @return if(
-    $luminance >= 0.1791,
-    "var(--pst-color-black)",
-    "var(--pst-color-black)"
+@function luminance($target-color) {
+  @debug "Calculating luminance for #{$target-color}";
+  $rgb-col: (
+    "r": red($target-color),
+    "g": green($target-color),
+    "b": blue($target-color),
+  );
+
+  @each $channel, $value in $rgb-col {
+    // here we get RsRGB, GsRGB, and BsRGB
+    @if $value / 255 <=0.03928 {
+      $rgb-col: map-merge(
+        $rgb-col,
+        (
+          $channel: (
+            $value / 255,
+          ) /
+          12.92,
+        )
+      );
+    } @else {
+      $rgb-col: map-merge(
+        $rgb-col,
+        (
+          $channel: nth($_luminance-list, $value + 1),
+        )
+      );
+    }
+  }
+
+  @return (
+    0.2126 * map-get($rgb-col, "r") + 0.7152 * map-get($rgb-col, "g") + 0.0722 *
+      map-get($rgb-col, "b")
   );
 }
 
@@ -61,10 +152,9 @@ $sd-semantic-color-names: (
 $extra-semantic-colors: (
   "dark": map-get($pst-semantic-colors, "text-base"),
   "muted": map-get($pst-semantic-colors, "text-muted"),
-  "light": rgb(201, 201, 201),
-  "black": hsl(216, 20%, 10%),
-  //gray-900
-  "white": rgb(255, 255, 255),
+  "light": $foundation-light-grey,
+  "black": $foundation-black,
+  "white": $foundation-white,
 );
 
 $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
@@ -75,20 +165,22 @@ $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
     @each $name in $sd-semantic-color-names {
       // check if this color is defined differently for light/dark
       $value: map-get($all-colors, $name);
+      @debug "Using #{$name}: #{$value} 🔴";
       @if type-of($value) == map {
-        $value: map-get($value, $mode);
+        $value: #{map-get($value, $mode)};
+        @debug "Using #{$mode} for #{$name}: #{$value}";
       }
       // define the pst variables, so that downstream user overrides will work
       --pst-color-#{$name}: #{$value};
-      // TODO: update to allow for new scheme
-      --pst-color-#{$name}-text: #{text-color($value)};
-      // TODO: check where highlight is used
-      --pst-color-#{$name}-highlight: #{darken($value, 15%)};
-      // override the sphinx-design variables
+      // TODO: the text might be best set in the component itself
+      // --pst-color-#{$name}-text: #{a11y-combination($value)};
+      // // TODO: check where highlight is used
+      // --pst-color-#{$name}-highlight: #{darken(#{$value}, 15%)};
+      // // override the sphinx-design variables
       --sd-color-#{$name}: var(--pst-color-#{$name});
-      --sd-color-#{$name}-text: var(--pst-color-#{$name}-text);
+      // --sd-color-#{$name}-text: var(--pst-color-#{$name}-text);
       // TODO: check where highlight is used
-      --sd-color-#{$name}-highlight: var(--pst-color-#{$name}-highlight);
+      // --sd-color-#{$name}-highlight: var(--pst-color-#{$name}-highlight);
     }
   }
 }
diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index ec75f0e1c..fa0441dc4 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -5,6 +5,19 @@
 * To see the full list of colors see https://www.figma.com/file/rUrrHGhUBBIAAjQ82x6pz9/PyData-Design-system---proposal-for-implementation-(2)?node-id=1234%3A765&t=ifcFT1JtnrSshGfi-1
 */
 
+/**
+* Function to get items from nested maps
+*/
+// @param {Map} $map - Map
+// @param {Arglist} $keys - Keys to fetch
+// @return {*}
+@function map-deep-get($map, $keys...) {
+  @each $key in $keys {
+    $map: map-get($map, $key);
+  }
+  @return $map;
+}
+
 /* Assign base colors for the PyData theme */
 $theme-colors: (
   // Primary color
@@ -76,32 +89,23 @@ $theme-colors: (
       --pst-#{$group-color}-#{$color-name}: #{$value};
     }
   }
-
-  // Minimum contrast ratio used for the theme.
-  // Acceptable values for WCAG 2.0 are 3, 4.5 and 7.
-  // See https://www.w3.org/TR/WCAG20/#visual-audio-contrast-contrast
-  // 4.5 - is for text that is 14pt or less
-  $min-contrast-ratio-text: 4.5;
-  // 3 is for text that is 18pt or bold, or for non-text elements
-  $min-contrast-ratio: 4.5;
-
-  // Customize the light and dark text colors for use in our color contrast function.
-  $color-contrast-dark: #{pst-color-black};
-  $color-contrast-light: #{pst-color-white};
 }
 
-/**
-* Function to get items from nested maps
-*/
-// @param {Map} $map - Map
-// @param {Arglist} $keys - Keys to fetch
-// @return {*}
-@function map-deep-get($map, $keys...) {
-  @each $key in $keys {
-    $map: map-get($map, $key);
-  }
-  @return $map;
-}
+// Static SCSS variables used thoroughout the theme
+// Minimum contrast ratio used for the theme.
+// Acceptable values for WCAG 2.0 are 3, 4.5 and 7.
+// See https://www.w3.org/TR/WCAG20/#visual-audio-contrast-contrast
+// 4.5 - is for text that is 14pt or less
+$min-contrast-ratio-4: 4.5;
+// 3 is for text that is 18pt or bold, or for non-text elements
+$min-contrast-ratio-3: 3;
+
+// Customize the light and dark text colors for use in our color contrast function.
+$foundation-black: #14181e;
+$foundation-white: #ffffff;
+$base-light-text: #ced6dd;
+// used in sphinx_design - grey 100
+$foundation-light-grey: #f3f4f5;
 
 $pst-semantic-colors: (
   "primary": (
@@ -114,7 +118,6 @@ $pst-semantic-colors: (
   ),
   "info": (
     "light": #276be9,
-    // TODO: update this to passs the bg colours
     "light-bg": #eff4fd,
     "dark": #79a3f2,
     "dark-bg": #06245d,
@@ -199,14 +202,11 @@ $pst-semantic-colors: (
 @mixin theme-colors($mode) {
   // check if this color is defined differently for light/dark
   @each $name, $value in $pst-semantic-colors {
-    @debug "name: #{$name}";
     @if type-of($value) == map {
       @each $key, $val in $value {
         // since now we define the bg colours in the semantic colours and not
         // by changing opacity, we need to check if the key contains bg
         @if (str-index($key, "bg")) != null {
-          @debug "key: #{$key}";
-          @debug "val: #{$val}";
           --pst-color-#{$key}: #{$val};
         }
       }

From 244772a23bef0a89f0f9508a49a16396039dc600 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Sun, 19 Feb 2023 17:42:27 +0000
Subject: [PATCH 13/64] Update variables and remove debugs

---
 .../assets/styles/extensions/_sphinx_design.scss           | 7 +------
 .../assets/styles/variables/_color.scss                    | 4 ++--
 2 files changed, 3 insertions(+), 8 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 2dac34e30..99fcf429c 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -61,7 +61,7 @@ $_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
   $target-color-contrast-dark: $foundation-black,
   $target-color-contrast-light: $base-light-text,
   $target-color-contrast-white: $foundation-white,
-  $min-contrast-ratio: $min-contrast-ratio
+  $min-contrast-ratio: $min-contrast-ratio-4
 ) {
   // will test against our two base foreground colors
   $foregrounds: $target-color-contrast-light, $target-color-contrast-dark;
@@ -71,7 +71,6 @@ $_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
   @debug "Using AA #{$min-contrast-ratio}:1 contrast ratio for #{$bg} ♿️";
   @each $fg in $foregrounds {
     $contrast-ratio: get-contrast-ratio($bg, $fg);
-    @debug "Contrast ratio for #{$bg} and #{$fg} is #{$contrast-ratio}... 🔴";
     @if $contrast-ratio >= $min-contrast-ratio {
       @return $fg;
     } @else if $contrast-ratio > $max-ratio {
@@ -85,7 +84,6 @@ $_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
 }
 
 @function get-contrast-ratio($bg, $foreground: #ced6dd) {
-  @debug "Calculating contrast ratio for #{$bg} 💡";
   $l1: luminance($bg);
   $l2: luminance($foreground);
 
@@ -102,7 +100,6 @@ $_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
 // See https://www.w3.org/TR/WCAG/#dfn-contrast-ratio
 
 @function luminance($target-color) {
-  @debug "Calculating luminance for #{$target-color}";
   $rgb-col: (
     "r": red($target-color),
     "g": green($target-color),
@@ -165,10 +162,8 @@ $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
     @each $name in $sd-semantic-color-names {
       // check if this color is defined differently for light/dark
       $value: map-get($all-colors, $name);
-      @debug "Using #{$name}: #{$value} 🔴";
       @if type-of($value) == map {
         $value: #{map-get($value, $mode)};
-        @debug "Using #{$mode} for #{$name}: #{$value}";
       }
       // define the pst variables, so that downstream user overrides will work
       --pst-color-#{$name}: #{$value};
diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index fa0441dc4..5a8ee9119 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -148,7 +148,7 @@ $pst-semantic-colors: (
   ),
   "text-base": (
     "light": #{map-deep-get($theme-colors, "gray", "800")},
-    "dark": #ced6dd,
+    "dark": $base-light-text,
   ),
   "text-muted": (
     "light": #{map-deep-get($theme-colors, "gray", "600")},
@@ -195,7 +195,7 @@ $pst-semantic-colors: (
   "on-surface":
     (
       "light": #{map-deep-get($theme-colors, "gray", "800")},
-      "dark": #ced6dd,
+      "dark": $base-light-text,
     ),
 );
 

From 7ef23d8f696038af774a4ac65db57d9f63570b9e Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 23 Feb 2023 16:16:47 +0000
Subject: [PATCH 14/64] :zap: Improve colours parsing

---
 .../assets/styles/variables/_color.scss       | 135 +++++++++++-------
 1 file changed, 80 insertions(+), 55 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index 5a8ee9119..8156eab5b 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -19,9 +19,9 @@
 }
 
 /* Assign base colors for the PyData theme */
-$theme-colors: (
+$color-palette: (
   // Primary color
-  "light-blue":
+  "teal":
     (
       "50": #f4fbfc,
       "100": #e9f6f8,
@@ -58,7 +58,7 @@ $theme-colors: (
       "400": #9ca4af,
       "500": #677384,
       "600": #48566b,
-      "700": #364150,
+      "700": #29313d,
       "800": #222832,
       "900": #14181e,
     ),
@@ -83,10 +83,10 @@ $theme-colors: (
 );
 
 :root {
-  // Add theme colours to the html element
-  @each $group-color, $color in $theme-colors {
-    @each $color-name, $value in $color {
-      --pst-#{$group-color}-#{$color-name}: #{$value};
+  // Add theme colours to the html root element
+  @each $group-color, $color in $color-palette {
+    @each $color-name, $definition in $color {
+      --pst-#{$group-color}-#{$color-name}: #{$definition};
     }
   }
 }
@@ -109,64 +109,78 @@ $foundation-light-grey: #f3f4f5;
 
 $pst-semantic-colors: (
   "primary": (
-    light: #{map-deep-get($theme-colors, "light-blue", "500")},
-    dark: #{map-deep-get($theme-colors, "light-blue", "400")},
+    "light": #{map-deep-get($color-palette, "teal", "500")},
+    "bg-light": #{map-deep-get($color-palette, "teal", "100")},
+    "dark": #{map-deep-get($color-palette, "teal", "400")},
+    "bg-dark": #{map-deep-get($color-palette, "teal", "800")},
   ),
   "secondary": (
-    light: #{map-deep-get($theme-colors, "violet", "500")},
-    dark: #{map-deep-get($theme-colors, "violet", "400")},
+    "light": #{map-deep-get($color-palette, "violet", "500")},
+    "bg-light": #{map-deep-get($color-palette, "violet", "100")},
+    "dark": #{map-deep-get($color-palette, "violet", "400")},
+    "bg-dark": #{map-deep-get($color-palette, "violet", "800")},
+  ),
+  "accent": (
+    "light": #{map-deep-get($color-palette, "pink", "500")},
+    "bg-light": #{map-deep-get($color-palette, "pink", "100")},
+    "dark": #{map-deep-get($color-palette, "pink", "400")},
+    "bg-dark": #{map-deep-get($color-palette, "pink", "800")},
   ),
   "info": (
     "light": #276be9,
-    "light-bg": #eff4fd,
+    "bg-light": #eff4fd,
     "dark": #79a3f2,
-    "dark-bg": #06245d,
+    "bg-dark": #06245d,
   ),
   "warning": (
     "light": #f66a0a,
-    "light-bg": #fff8f2,
+    "bg-light": #fff8f2,
     "dark": #ff9245,
-    "dark-bg": #652a02,
+    "bg-dark": #652a02,
   ),
   "success": (
     "light": #00843f,
-    "light-bg": #ecf6f1,
+    "bg-light": #ecf6f1,
     "dark": #5fb488,
-    "dark-bg": #002f17,
-  ),
-  "attention": (
-    "light": #f66a0a,
-    "light-bg": #fff8f2,
-    "dark": #ff9245,
-    "dark-bg": #652a02,
+    "bg-dark": #002f17,
   ),
+  // This is is based on the warning color
+  "attention":
+    (
+      "light": var(--pst-colors-warning),
+      "bg-light": var(--pst-colors-warning-bg-light),
+      "dark": var(--pst-colors-warning),
+      "bg-dark": var(--pst-colors-warning-bg-dark),
+    ),
   "danger": (
     "light": #d72d47,
-    "light-bg": #fcf1f2,
+    "bg-light": #fcf1f2,
     "dark": #e78894,
-    "dark-bg": #4e111b,
+    "bg-dark": #4e111b,
   ),
   "text-base": (
-    "light": #{map-deep-get($theme-colors, "gray", "800")},
+    "light": #{map-deep-get($color-palette, "gray", "800")},
     "dark": $base-light-text,
   ),
   "text-muted": (
-    "light": #{map-deep-get($theme-colors, "gray", "600")},
-    "dark": #{map-deep-get($theme-colors, "gray", "300")},
+    "light": #{map-deep-get($color-palette, "gray", "600")},
+    "dark": #{map-deep-get($color-palette, "gray", "300")},
   ),
   "shadow": (
     "light": rgba(0, 0, 0, 0.1),
     "dark": rgba(0, 0, 0, 0.2),
   ),
-  // TODO- update (need muted and regular - this is muted)
-  "border":
-    (
-      "light": rgba(23, 23, 26, 0.2),
-      "dark": #{map-deep-get($theme-colors, "gray", "600")},
-    ),
+  "border": (
+    "light": #{map-deep-get($color-palette, "gray", "300")},
+    "dark": #{map-deep-get($color-palette, "gray", "500")},
+  ),
+  "border-muted": (
+    "light": rgba(23, 23, 26, 0.2),
+    "dark": #{map-deep-get($color-palette, "gray", "600")},
+  ),
   "inline-code": (
-    "light": #{map-deep-get($theme-colors, "pink", "600")},
-    "dark": #{map-deep-get($theme-colors, "pink", "300")},
+    "light": #{map-deep-get($color-palette, "pink", "600")},
+    "dark": #{map-deep-get($color-palette, "pink", "300")},
   ),
   "target": (
     "light": #8b6e31,
@@ -177,43 +191,54 @@ $pst-semantic-colors: (
   // background: color of the canvas / the furthest back layer
   "background":
     (
-      "light": #{map-deep-get($theme-colors, "foundation", "white")},
-      "dark": #{map-deep-get($theme-colors, "foundation", "black")},
+      "light": #{map-deep-get($color-palette, "foundation", "white")},
+      "dark": #{map-deep-get($color-palette, "foundation", "black")},
     ),
   // on-background: provides slight contrast against background
   // (by use of shadows in light theme)
   "on-background":
     (
-      "light": #{map-deep-get($theme-colors, "foundation", "white")},
-      "dark": #{map-deep-get($theme-colors, "gray", "800")},
+      "light": #{map-deep-get($color-palette, "foundation", "white")},
+      "dark": #{map-deep-get($color-palette, "gray", "800")},
     ),
   "surface": (
-    "light": #{map-deep-get($theme-colors, "gray", "100")},
-    "dark": #{map-deep-get($theme-colors, "gray", "700")},
+    "light": #{map-deep-get($color-palette, "gray", "100")},
+    "dark": #{map-deep-get($color-palette, "gray", "700")},
   ),
   // on_surface: object on top of surface object (without shadows)
   "on-surface":
     (
-      "light": #{map-deep-get($theme-colors, "gray", "800")},
+      "light": #{map-deep-get($color-palette, "gray", "800")},
       "dark": $base-light-text,
     ),
 );
 
 @mixin theme-colors($mode) {
   // check if this color is defined differently for light/dark
-  @each $name, $value in $pst-semantic-colors {
-    @if type-of($value) == map {
-      @each $key, $val in $value {
-        // since now we define the bg colours in the semantic colours and not
-        // by changing opacity, we need to check if the key contains bg
-        @if (str-index($key, "bg")) != null {
-          --pst-color-#{$key}: #{$val};
+  @debug "mode: #{$mode} 🌕";
+  @each $col-name, $definition in $pst-semantic-colors {
+    @debug "key: #{$col-name}";
+    @if type-of($definition) == map {
+      @each $key, $val in $definition {
+        @if str-index($key, $mode) != null {
+          // since now we define the bg colours in the semantic colours and not
+          // by changing opacity, we need to check if the key contains bg and the
+          // correct mode (light/dark)
+          @if str-index($key, "bg") != null {
+            --pst-color-bg-#{$col-name}: #{$val};
+            @debug "📡 Added name: --pst-color-bg-#{$col-name}: #{$val}";
+          } @else {
+            --pst-color-#{$col-name}: #{$val};
+            @debug "📝 Added name: --pst-color-#{$col-name}: #{$val}";
+          }
         }
       }
-      $value: map-get($value, $mode);
+    } @else {
+      @debug "name: #{$col-name} - value: #{$definition}";
+      --pst-color-#{$col-name}: #{$definition};
     }
-    --pst-color-#{$name}: #{$value};
   }
+
   // assign the "duplicate" colors (ones that just reference other variables)
   & {
     --pst-color-link: var(--pst-color-primary);
@@ -265,8 +290,8 @@ html:not([data-theme]) {
 }
 
 // assign classes too, for runtime use of theme colors
-@each $name, $value in $pst-semantic-colors {
-  .pst-color-#{$name} {
-    color: var(--pst-color-#{$name});
+@each $col-name, $definition in $pst-semantic-colors {
+  .pst-color-#{$col-name} {
+    color: var(--pst-color-#{$col-name});
   }
 }

From ef43e09abcdc9d89a0934f0e3fd86e2cec2c047c Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 23 Feb 2023 19:21:18 +0000
Subject: [PATCH 15/64] :wheelchair: Update admonition bg colours

---
 .../styles/components/_versionmodified.scss   | 17 ++-----
 .../assets/styles/content/_admonitions.scss   | 51 ++++++-------------
 .../assets/styles/variables/_color.scss       | 15 ++----
 3 files changed, 24 insertions(+), 59 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/components/_versionmodified.scss b/src/pydata_sphinx_theme/assets/styles/components/_versionmodified.scss
index e99b0cf06..a8f03d1f3 100644
--- a/src/pydata_sphinx_theme/assets/styles/components/_versionmodified.scss
+++ b/src/pydata_sphinx_theme/assets/styles/components/_versionmodified.scss
@@ -18,32 +18,23 @@ div.deprecated {
     margin-bottom: 0.6rem;
     margin-top: 0.6rem;
 
-    @include background-from-color-variable(--pst-color-info);
+    @include format-before(--pst-color-info);
   }
 }
 
 div.versionadded {
   border-color: var(--pst-color-success);
-
-  p:before {
-    background-color: var(--pst-color-success);
-  }
+  background-color: var(--pst-color-success-bg);
 }
 
 div.versionchanged {
   border-color: var(--pst-color-warning);
-
-  p:before {
-    background-color: var(--pst-color-warning);
-  }
+  background-color: var(--pst-color-warning-bg);
 }
 
 div.deprecated {
   border-color: var(--pst-color-danger);
-
-  p:before {
-    background-color: var(--pst-color-danger);
-  }
+  background-color: var(--pst-color-danger-bg);
 }
 
 span.versionmodified {
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss b/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
index 325ac5ec6..aa00ee69a 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
@@ -38,6 +38,7 @@ div.admonition,
     padding: 0.4rem 0.6rem 0.4rem 2rem;
     font-weight: var(--pst-font-weight-heading);
     position: relative;
+    background-color: var(--pst-color-info-bg);
 
     &:after {
       position: absolute;
@@ -51,7 +52,7 @@ div.admonition,
       opacity: 1;
     }
 
-    @include background-from-color-variable(--pst-color-info);
+    @include format-before(--pst-color-info);
 
     // Next element after title needs some extra upper-space
     + * {
@@ -62,9 +63,7 @@ div.admonition,
   &.attention {
     border-color: var(--pst-color-attention);
     > .admonition-title {
-      &:before {
-        background-color: var(--pst-color-attention);
-      }
+      background-color: var(--pst-color-warning-bg);
 
       &:after {
         color: var(--pst-color-attention);
@@ -76,9 +75,7 @@ div.admonition,
   &.caution {
     border-color: var(--pst-color-warning);
     > .admonition-title {
-      &:before {
-        background-color: var(--pst-color-warning);
-      }
+      background-color: var(--pst-color-warning-bg);
 
       &:after {
         color: var(--pst-color-warning);
@@ -90,9 +87,7 @@ div.admonition,
   &.warning {
     border-color: var(--pst-color-warning);
     > .admonition-title {
-      &:before {
-        background-color: var(--pst-color-warning);
-      }
+      background-color: var(--pst-color-warning-bg);
 
       &:after {
         color: var(--pst-color-warning);
@@ -104,9 +99,7 @@ div.admonition,
   &.danger {
     border-color: var(--pst-color-danger);
     > .admonition-title {
-      &:before {
-        background-color: var(--pst-color-danger);
-      }
+      background-color: var(--pst-color-danger-bg);
 
       &:after {
         color: var(--pst-color-danger);
@@ -118,9 +111,7 @@ div.admonition,
   &.error {
     border-color: var(--pst-color-danger);
     > .admonition-title {
-      &:before {
-        background-color: var(--pst-color-danger);
-      }
+      background-color: var(--pst-color-danger-bg);
 
       &:after {
         color: var(--pst-color-danger);
@@ -132,9 +123,7 @@ div.admonition,
   &.hint {
     border-color: var(--pst-color-success);
     > .admonition-title {
-      &:before {
-        background-color: var(--pst-color-success);
-      }
+      background-color: var(--pst-color-success-bg);
 
       &:after {
         color: var(--pst-color-success);
@@ -146,9 +135,7 @@ div.admonition,
   &.tip {
     border-color: var(--pst-color-success);
     > .admonition-title {
-      &:before {
-        background-color: var(--pst-color-success);
-      }
+      background-color: var(--pst-color-success-bg);
 
       &:after {
         color: var(--pst-color-success);
@@ -160,9 +147,7 @@ div.admonition,
   &.important {
     border-color: var(--pst-color-attention);
     > .admonition-title {
-      &:before {
-        background-color: var(--pst-color-attention);
-      }
+      background-color: var(--pst-color-warning-bg);
 
       &:after {
         color: var(--pst-color-attention);
@@ -174,9 +159,7 @@ div.admonition,
   &.note {
     border-color: var(--pst-color-info);
     > .admonition-title {
-      &:before {
-        background-color: var(--pst-color-info);
-      }
+      background-color: var(--pst-color-info-bg);
 
       &:after {
         color: var(--pst-color-info);
@@ -188,9 +171,7 @@ div.admonition,
   &.seealso {
     border-color: var(--pst-color-success);
     > .admonition-title {
-      &:before {
-        background-color: var(--pst-color-success);
-      }
+      background-color: var(--pst-color-success-bg);
 
       &:after {
         color: var(--pst-color-success);
@@ -200,14 +181,12 @@ div.admonition,
   }
 
   &.admonition-todo {
-    border-color: var(--pst-color-border);
+    border-color: var(--pst-color-secondary);
     > .admonition-title {
-      &:before {
-        background-color: var(--pst-color-border);
-      }
+      background-color: var(--pst-color-secondary-bg);
 
       &:after {
-        color: var(--pst-color-border);
+        color: var(--pst-color-secondary);
         content: var(--pst-icon-admonition-todo);
       }
     }
diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index 8156eab5b..3b42da96e 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -147,10 +147,10 @@ $pst-semantic-colors: (
   // This is is based on the warning color
   "attention":
     (
-      "light": var(--pst-colors-warning),
-      "bg-light": var(--pst-colors-warning-bg-light),
-      "dark": var(--pst-colors-warning),
-      "bg-dark": var(--pst-colors-warning-bg-dark),
+      "light": var(--pst-color-warning),
+      "bg-light": var(--pst-color-warning-bg-light),
+      "dark": var(--pst-color-warning),
+      "bg-dark": var(--pst-color-warning-bg-dark),
     ),
   "danger": (
     "light": #d72d47,
@@ -215,9 +215,7 @@ $pst-semantic-colors: (
 
 @mixin theme-colors($mode) {
   // check if this color is defined differently for light/dark
-  @debug "mode: #{$mode} 🌕";
   @each $col-name, $definition in $pst-semantic-colors {
-    @debug "key: #{$col-name}";
     @if type-of($definition) == map {
       @each $key, $val in $definition {
         @if str-index($key, $mode) != null {
@@ -225,16 +223,13 @@ $pst-semantic-colors: (
           // by changing opacity, we need to check if the key contains bg and the
           // correct mode (light/dark)
           @if str-index($key, "bg") != null {
-            --pst-color-bg-#{$col-name}: #{$val};
-            @debug "📡 Added name: --pst-color-bg-#{$col-name}: #{$val}";
+            --pst-color-#{$col-name}-bg: #{$val};
           } @else {
             --pst-color-#{$col-name}: #{$val};
-            @debug "📝 Added name: --pst-color-#{$col-name}: #{$val}";
           }
         }
       }
     } @else {
-      @debug "name: #{$col-name} - value: #{$definition}";
       --pst-color-#{$col-name}: #{$definition};
     }
   }

From 16678ea1a110677597d3e6856071c2e7dd79235b Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 23 Feb 2023 19:37:57 +0000
Subject: [PATCH 16/64] Update headings colours

---
 .../assets/styles/base/_base.scss                    | 12 ++++++------
 .../assets/styles/variables/_color.scss              |  4 ++++
 2 files changed, 10 insertions(+), 6 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/base/_base.scss b/src/pydata_sphinx_theme/assets/styles/base/_base.scss
index 3791f42fc..210eee7aa 100644
--- a/src/pydata_sphinx_theme/assets/styles/base/_base.scss
+++ b/src/pydata_sphinx_theme/assets/styles/base/_base.scss
@@ -49,8 +49,8 @@ a {
   }
 
   &.headerlink {
-    color: var(--pst-color-warning);
-    opacity: 0.4;
+    color: var(--pst-color-secondary);
+    opacity: 0.6;
     font-size: 0.8em;
     padding: 0 4px 0 4px;
     margin-left: 0.2em;
@@ -93,25 +93,25 @@ h1 {
   @extend .heading-style;
   margin-top: 0;
   font-size: var(--pst-font-size-h1);
-  color: var(--pst-color-primary);
+  color: var(--pst-heading-color);
 }
 
 h2 {
   @extend .heading-style;
   font-size: var(--pst-font-size-h2);
-  color: var(--pst-color-primary);
+  color: var(--pst-heading-color);
 }
 
 h3 {
   @extend .heading-style;
   font-size: var(--pst-font-size-h3);
-  color: var(--pst-color-text-base);
+  color: var(--pst-heading-color);
 }
 
 h4 {
   @extend .heading-style;
   font-size: var(--pst-font-size-h4);
-  color: var(--pst-color-text-base);
+  color: var(--pst-heading-color);
 }
 
 h5 {
diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index 3b42da96e..2328d782d 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -166,6 +166,10 @@ $pst-semantic-colors: (
     "light": #{map-deep-get($color-palette, "gray", "600")},
     "dark": #{map-deep-get($color-palette, "gray", "300")},
   ),
+  "heading-color": (
+    "light": #{$foundation-white},
+    "dark": #{$foundation-black},
+  ),
   "shadow": (
     "light": rgba(0, 0, 0, 0.1),
     "dark": rgba(0, 0, 0, 0.2),

From 0c9a6b5fe2569db30988d94be61807ca55d589d5 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 24 Feb 2023 12:28:30 +0000
Subject: [PATCH 17/64] :wheelchair: Change topic text colour and replace
 mixins

---
 src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss | 5 ++---
 .../assets/styles/content/_admonitions.scss                  | 5 +++++
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
index ca8e17096..507efa1d2 100644
--- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
+++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -72,9 +72,9 @@
 }
 
 /**
- * Assign the admonition colours from our variables
+ * Format before pseudo element - TODO: decide if we still need this
  */
-@mixin assign-background-color($color-variable) {
+@mixin format-before($color-variable) {
   &:before {
     content: "";
     width: 100%;
@@ -82,7 +82,6 @@
     position: absolute;
     left: 0;
     top: 0;
-    background-color: var(#{$color-variable}-bg);
 
     // So that hovering over the text within background is still possible.
     // Otherwise the background overlays the text and you cannot click or select easily.
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss b/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
index aa00ee69a..2373799bd 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
@@ -267,6 +267,11 @@ aside.topic {
     margin: 0 0 0.5rem 0;
   }
 
+  // Over-ride text color to ensure enough contrast
+  p {
+    color: var(--pst-color-on-surface) !important;
+  }
+
   // Over-ride large default padding
   ul.simple {
     padding-left: 1rem;

From f89e2628c6eae3aa4d8ba0e28b2868a95c5022b0 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 24 Feb 2023 12:28:55 +0000
Subject: [PATCH 18/64] :wheelchair: Minor tweaks to secondary colour

---
 .../assets/styles/variables/_color.scss       | 22 ++++++++++---------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index 2328d782d..36a2e2adf 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -37,15 +37,15 @@ $color-palette: (
   // Secondary color
   "violet":
     (
-      "50": #fbf8fe,
-      "100": #f6f2fe,
-      "200": #ece3fc,
-      "300": #decdfa,
-      "400": #b691f5,
-      "500": #894def,
-      "600": #6730c5,
-      "700": #4e2595,
-      "800": #31175f,
+      "50": #f4eefb,
+      "100": #e1cafe,
+      "200": #cda5ff,
+      "300": #b680ff,
+      "400": #9c5ffd,
+      "500": #8045e5,
+      "600": #6432bd,
+      "700": #4b258f,
+      "800": #341a61,
       "900": #1e0e39,
     ),
   // Neutrals
@@ -103,6 +103,8 @@ $min-contrast-ratio-3: 3;
 // Customize the light and dark text colors for use in our color contrast function.
 $foundation-black: #14181e;
 $foundation-white: #ffffff;
+// This is a custom - calculated  color between gray 100 and 200 - to reduce
+// the contrast ratio (avoid a jarring effect)
 $base-light-text: #ced6dd;
 // used in sphinx_design - grey 100
 $foundation-light-grey: #f3f4f5;
@@ -213,7 +215,7 @@ $pst-semantic-colors: (
   "on-surface":
     (
       "light": #{map-deep-get($color-palette, "gray", "800")},
-      "dark": $base-light-text,
+      "dark": $foundation-light-grey,
     ),
 );
 

From 055f7c05afbb7ae56bf5c6102c7d96ba761f8b25 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 24 Feb 2023 12:51:24 +0000
Subject: [PATCH 19/64] :wheelchair: Update code and announcement colours

---
 src/pydata_sphinx_theme/assets/styles/content/_code.scss     | 2 +-
 .../assets/styles/sections/_announcement.scss                | 5 ++---
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/content/_code.scss b/src/pydata_sphinx_theme/assets/styles/content/_code.scss
index e20129ddf..78792b0d1 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_code.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_code.scss
@@ -51,6 +51,6 @@ div.literal-block-wrapper {
 code.literal {
   padding: 0.1rem 0.25rem;
   background-color: var(--pst-color-surface);
-  border: 1px solid var(--pst-color-on-surface);
+  border: 1px solid var(--pst-color-border);
   border-radius: 0.25rem;
 }
diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss b/src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss
index b2287d6aa..315197608 100644
--- a/src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss
+++ b/src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss
@@ -18,15 +18,14 @@
     margin: 0;
   }
 
-  // The same background color transparency hack we use in admonitions
+  // Bg color is now defined in the theme color palette
   &:after {
     position: absolute;
     width: 100%;
     height: 100%;
     left: 0;
     top: 0;
-    background-color: var(--pst-color-info);
-    opacity: 0.2;
+    background-color: var(--pst-color-secondary-bg);
     content: "";
     z-index: -1; // So it doesn't hover over the content
   }

From 7930b5da5d37ec7d9a0dbaa80e6daba3fca92221 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 24 Feb 2023 13:13:34 +0000
Subject: [PATCH 20/64] Update text-muted in dark theme

---
 src/pydata_sphinx_theme/assets/styles/variables/_color.scss | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index 36a2e2adf..47076e4f2 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -166,7 +166,7 @@ $pst-semantic-colors: (
   ),
   "text-muted": (
     "light": #{map-deep-get($color-palette, "gray", "600")},
-    "dark": #{map-deep-get($color-palette, "gray", "300")},
+    "dark": #{map-deep-get($color-palette, "gray", "400")},
   ),
   "heading-color": (
     "light": #{$foundation-white},

From a663273bf11f5e5b5dd634c830cb36c3572274fb Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 24 Feb 2023 18:57:42 +0000
Subject: [PATCH 21/64] =?UTF-8?q?=E2=99=BF=EF=B8=8F=20=20Buttons=20are=20n?=
 =?UTF-8?q?ow=20WCAG=20AA=20conformant?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../assets/styles/abstracts/_mixins.scss      | 162 +++++++++++++++++-
 .../styles/extensions/_sphinx_design.scss     | 129 ++------------
 2 files changed, 175 insertions(+), 116 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
index 507efa1d2..9ac42aa3f 100644
--- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
+++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -105,7 +105,7 @@
 * Function to get items from nested maps
 */
 // @param {Map} $map - Map
-// @param {Arglist} $keys - Keys to fetch
+// @param {Arglist} $keys - Keys to fetc
 // @return {*}
 @function map-deep-get($map, $keys...) {
   @each $key in $keys {
@@ -113,3 +113,163 @@
   }
   @return $map;
 }
+
+/**
+* Function to convert the string represenation of a color to a color type
+*/
+// @param {String} $string - String representation of a color
+@function from-hex($string) {
+  $string-lower: to-lower-case($string);
+  $r: "";
+  $g: "";
+  $b: "";
+  $hex: "0" "1" "2" "3" "4" "5" "6" "7" "8" "9" "a" "b" "c" "d" "e" "f";
+  $length: str-length($string);
+  $max: if($length == 4, 1, 2);
+
+  // Check for length accuracy
+  @if $length != 4 and $length != 7 {
+    @return $string;
+  }
+
+  // Loop from the second character (omitting #)
+  @for $i from 2 through $length {
+    $c: str-slice($string-lower, $i, $i);
+
+    // If wrong character, return
+    @if index($hex, $c) == null {
+      @return $string;
+    }
+
+    @if str-length($r) < $max {
+      $r: $r + $c;
+    } @else if str-length($g) < $max {
+      $g: $g + $c;
+    } @else if str-length($b) < $max {
+      $b: $b + $c;
+    }
+  }
+
+  @if $length == 4 {
+    $r: $r + $r;
+    $g: $g + $g;
+    $b: $b + $b;
+  }
+
+  @return rgb(_hex-to-dec($r), _hex-to-dec($g), _hex-to-dec($b));
+}
+
+@function _hex-to-dec($string) {
+  $hex: "0" "1" "2" "3" "4" "5" "6" "7" "8" "9" "a" "b" "c" "d" "e" "f";
+  $string: to-lower-case($string);
+  $length: str-length($string);
+
+  $dec: 0;
+  @for $i from 1 through $length {
+    $factor: 1 + (15 * ($length - $i));
+    $index: index($hex, str-slice($string, $i, $i));
+    $dec: $dec + $factor * ($index - 1);
+  }
+
+  @return $dec;
+}
+
+// A list of pre-calculated numbers of pow(divide((divide($value, 255) + .055), 1.055), 2.4). (from 0 to 255)
+$_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
+  0.0027 0.003 0.0033 0.0037 0.004 0.0044 0.0048 0.0052 0.0056 0.006 0.0065
+  0.007 0.0075 0.008 0.0086 0.0091 0.0097 0.0103 0.011 0.0116 0.0123 0.013
+  0.0137 0.0144 0.0152 0.016 0.0168 0.0176 0.0185 0.0194 0.0203 0.0212 0.0222
+  0.0232 0.0242 0.0252 0.0262 0.0273 0.0284 0.0296 0.0307 0.0319 0.0331 0.0343
+  0.0356 0.0369 0.0382 0.0395 0.0409 0.0423 0.0437 0.0452 0.0467 0.0482 0.0497
+  0.0513 0.0529 0.0545 0.0561 0.0578 0.0595 0.0612 0.063 0.0648 0.0666 0.0685
+  0.0704 0.0723 0.0742 0.0762 0.0782 0.0802 0.0823 0.0844 0.0865 0.0887 0.0908
+  0.0931 0.0953 0.0976 0.0999 0.1022 0.1046 0.107 0.1095 0.1119 0.1144 0.117
+  0.1195 0.1221 0.1248 0.1274 0.1301 0.1329 0.1356 0.1384 0.1413 0.1441 0.147
+  0.15 0.1529 0.1559 0.159 0.162 0.1651 0.1683 0.1714 0.1746 0.1779 0.1812
+  0.1845 0.1878 0.1912 0.1946 0.1981 0.2016 0.2051 0.2086 0.2122 0.2159 0.2195
+  0.2232 0.227 0.2307 0.2346 0.2384 0.2423 0.2462 0.2502 0.2542 0.2582 0.2623
+  0.2664 0.2705 0.2747 0.2789 0.2831 0.2874 0.2918 0.2961 0.3005 0.305 0.3095
+  0.314 0.3185 0.3231 0.3278 0.3325 0.3372 0.3419 0.3467 0.3515 0.3564 0.3613
+  0.3663 0.3712 0.3763 0.3813 0.3864 0.3916 0.3968 0.402 0.4072 0.4125 0.4179
+  0.4233 0.4287 0.4342 0.4397 0.4452 0.4508 0.4564 0.4621 0.4678 0.4735 0.4793
+  0.4851 0.491 0.4969 0.5029 0.5089 0.5149 0.521 0.5271 0.5333 0.5395 0.5457
+  0.552 0.5583 0.5647 0.5711 0.5776 0.5841 0.5906 0.5972 0.6038 0.6105 0.6172
+  0.624 0.6308 0.6376 0.6445 0.6514 0.6584 0.6654 0.6724 0.6795 0.6867 0.6939
+  0.7011 0.7084 0.7157 0.7231 0.7305 0.7379 0.7454 0.7529 0.7605 0.7682 0.7758
+  0.7835 0.7913 0.7991 0.807 0.8148 0.8228 0.8308 0.8388 0.8469 0.855 0.8632
+  0.8714 0.8796 0.8879 0.8963 0.9047 0.9131 0.9216 0.9301 0.9387 0.9473 0.956
+  0.9647 0.9734 0.9823 0.9911 1;
+
+@function a11y-combination(
+  $bg,
+  $target-color-contrast-dark: $foundation-black,
+  $target-color-contrast-white: $foundation-white,
+  $min-contrast-ratio: $min-contrast-ratio-4
+) {
+  // will test against the specified foreground colors
+  $foregrounds: $target-color-contrast-white, $target-color-contrast-dark;
+  $max-ratio: 0;
+  $max-ratio-color: null;
+
+  @debug "Using AA #{$min-contrast-ratio}:1 contrast ratio for #{$bg} ♿️";
+  @each $fg in $foregrounds {
+    $contrast-ratio: get-contrast-ratio($bg, $fg);
+    @if $contrast-ratio >= $min-contrast-ratio {
+      @return $fg;
+    } @else if $contrast-ratio > $max-ratio {
+      $max-ratio: $contrast-ratio;
+      $max-ratio-color: $fg;
+    }
+  }
+  @warn "Found no color leading to #{$min-contrast-ratio}:1 contrast ratio against #{$bg}...";
+
+  @return $max-ratio-color;
+}
+
+@function get-contrast-ratio($bg, $foreground: #ced6dd) {
+  $l1: luminance($bg);
+  $l2: luminance($foreground);
+
+  // return the relative contrast ratio
+  @if $l1 > $l2 {
+    @return ($l1 + 0.05) / ($l2 + 0.05);
+  } @else {
+    @return ($l2 + 0.05) / ($l1 + 0.05);
+  }
+}
+
+// Return WCAG2.1 relative luminance
+// See https://www.w3.org/TR/WCAG/#dfn-relative-luminance
+// See https://www.w3.org/TR/WCAG/#dfn-contrast-ratio
+
+@function luminance($target-color) {
+  $rgb-col: (
+    "r": red($target-color),
+    "g": green($target-color),
+    "b": blue($target-color),
+  );
+
+  @each $channel, $value in $rgb-col {
+    // here we get RsRGB, GsRGB, and BsRGB
+    @if $value / 255 <=0.03928 {
+      $rgb-col: map-merge(
+        $rgb-col,
+        (
+          $channel: $value / 255 / 12.92,
+        )
+      );
+    } @else {
+      $rgb-col: map-merge(
+        $rgb-col,
+        (
+          $channel: nth($_luminance-list, $value + 1),
+        )
+      );
+    }
+  }
+
+  @return (
+    0.2126 * map-get($rgb-col, "r") + 0.7152 * map-get($rgb-col, "g") + 0.0722 *
+      map-get($rgb-col, "b")
+  );
+}
diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 99fcf429c..8c2bc5d4e 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -5,8 +5,7 @@
  * NOTE: sphinx-design uses !important quite liberally, so here we must do the
  * same for our overrides to have any effect.
  */
-
-@use "../variables/color" as *;
+@use "../variables/color" as pst-color;
 @use "sass:color" as color;
 
 /*******************************************************************************
@@ -30,110 +29,6 @@ $sd-semantic-color-names: (
   "white"
 );
 
-// A list of pre-calculated numbers of pow(divide((divide($value, 255) + .055), 1.055), 2.4). (from 0 to 255)
-$_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
-  0.0027 0.003 0.0033 0.0037 0.004 0.0044 0.0048 0.0052 0.0056 0.006 0.0065
-  0.007 0.0075 0.008 0.0086 0.0091 0.0097 0.0103 0.011 0.0116 0.0123 0.013
-  0.0137 0.0144 0.0152 0.016 0.0168 0.0176 0.0185 0.0194 0.0203 0.0212 0.0222
-  0.0232 0.0242 0.0252 0.0262 0.0273 0.0284 0.0296 0.0307 0.0319 0.0331 0.0343
-  0.0356 0.0369 0.0382 0.0395 0.0409 0.0423 0.0437 0.0452 0.0467 0.0482 0.0497
-  0.0513 0.0529 0.0545 0.0561 0.0578 0.0595 0.0612 0.063 0.0648 0.0666 0.0685
-  0.0704 0.0723 0.0742 0.0762 0.0782 0.0802 0.0823 0.0844 0.0865 0.0887 0.0908
-  0.0931 0.0953 0.0976 0.0999 0.1022 0.1046 0.107 0.1095 0.1119 0.1144 0.117
-  0.1195 0.1221 0.1248 0.1274 0.1301 0.1329 0.1356 0.1384 0.1413 0.1441 0.147
-  0.15 0.1529 0.1559 0.159 0.162 0.1651 0.1683 0.1714 0.1746 0.1779 0.1812
-  0.1845 0.1878 0.1912 0.1946 0.1981 0.2016 0.2051 0.2086 0.2122 0.2159 0.2195
-  0.2232 0.227 0.2307 0.2346 0.2384 0.2423 0.2462 0.2502 0.2542 0.2582 0.2623
-  0.2664 0.2705 0.2747 0.2789 0.2831 0.2874 0.2918 0.2961 0.3005 0.305 0.3095
-  0.314 0.3185 0.3231 0.3278 0.3325 0.3372 0.3419 0.3467 0.3515 0.3564 0.3613
-  0.3663 0.3712 0.3763 0.3813 0.3864 0.3916 0.3968 0.402 0.4072 0.4125 0.4179
-  0.4233 0.4287 0.4342 0.4397 0.4452 0.4508 0.4564 0.4621 0.4678 0.4735 0.4793
-  0.4851 0.491 0.4969 0.5029 0.5089 0.5149 0.521 0.5271 0.5333 0.5395 0.5457
-  0.552 0.5583 0.5647 0.5711 0.5776 0.5841 0.5906 0.5972 0.6038 0.6105 0.6172
-  0.624 0.6308 0.6376 0.6445 0.6514 0.6584 0.6654 0.6724 0.6795 0.6867 0.6939
-  0.7011 0.7084 0.7157 0.7231 0.7305 0.7379 0.7454 0.7529 0.7605 0.7682 0.7758
-  0.7835 0.7913 0.7991 0.807 0.8148 0.8228 0.8308 0.8388 0.8469 0.855 0.8632
-  0.8714 0.8796 0.8879 0.8963 0.9047 0.9131 0.9216 0.9301 0.9387 0.9473 0.956
-  0.9647 0.9734 0.9823 0.9911 1;
-
-@function a11y-combination(
-  $bg,
-  $target-color-contrast-dark: $foundation-black,
-  $target-color-contrast-light: $base-light-text,
-  $target-color-contrast-white: $foundation-white,
-  $min-contrast-ratio: $min-contrast-ratio-4
-) {
-  // will test against our two base foreground colors
-  $foregrounds: $target-color-contrast-light, $target-color-contrast-dark;
-  $max-ratio: 0;
-  $max-ratio-color: null;
-
-  @debug "Using AA #{$min-contrast-ratio}:1 contrast ratio for #{$bg} ♿️";
-  @each $fg in $foregrounds {
-    $contrast-ratio: get-contrast-ratio($bg, $fg);
-    @if $contrast-ratio >= $min-contrast-ratio {
-      @return $fg;
-    } @else if $contrast-ratio > $max-ratio {
-      $max-ratio: $contrast-ratio;
-      $max-ratio-color: $fg;
-    }
-  }
-  @warn "Found no color leading to #{$min-contrast-ratio}:1 contrast ratio against #{$bg}...";
-
-  @return $max-ratio-color;
-}
-
-@function get-contrast-ratio($bg, $foreground: #ced6dd) {
-  $l1: luminance($bg);
-  $l2: luminance($foreground);
-
-  // return the relative contrast ratio
-  @if $l1 > $l2 {
-    @return ($l1 + 0.05) / ($l2 + 0.05);
-  } @else {
-    @return ($l2 + 0.05) / ($l1 + 0.05);
-  }
-}
-
-// Return WCAG2.1 relative luminance
-// See https://www.w3.org/TR/WCAG/#dfn-relative-luminance
-// See https://www.w3.org/TR/WCAG/#dfn-contrast-ratio
-
-@function luminance($target-color) {
-  $rgb-col: (
-    "r": red($target-color),
-    "g": green($target-color),
-    "b": blue($target-color),
-  );
-
-  @each $channel, $value in $rgb-col {
-    // here we get RsRGB, GsRGB, and BsRGB
-    @if $value / 255 <=0.03928 {
-      $rgb-col: map-merge(
-        $rgb-col,
-        (
-          $channel: (
-            $value / 255,
-          ) /
-          12.92,
-        )
-      );
-    } @else {
-      $rgb-col: map-merge(
-        $rgb-col,
-        (
-          $channel: nth($_luminance-list, $value + 1),
-        )
-      );
-    }
-  }
-
-  @return (
-    0.2126 * map-get($rgb-col, "r") + 0.7152 * map-get($rgb-col, "g") + 0.0722 *
-      map-get($rgb-col, "b")
-  );
-}
-
 /**
   * Here we create some extra --pst-color-* variables and use
   * them to override the value of the corresponding sphinx-design variables.
@@ -155,6 +50,7 @@ $extra-semantic-colors: (
 );
 
 $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
+@debug "sd-semantic-color-names: #{$sd-semantic-color-names}";
 
 // Now we override the --sd-color-* variables.
 @each $mode in (light, dark) {
@@ -163,19 +59,23 @@ $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
       // check if this color is defined differently for light/dark
       $value: map-get($all-colors, $name);
       @if type-of($value) == map {
-        $value: #{map-get($value, $mode)};
+        $value: map-get($value, $mode);
+        @if type-of($value) == string {
+          $value: from-hex($value);
+        }
       }
       // define the pst variables, so that downstream user overrides will work
       --pst-color-#{$name}: #{$value};
-      // TODO: the text might be best set in the component itself
-      // --pst-color-#{$name}-text: #{a11y-combination($value)};
+      // TODO: the text might be best set in the component itself - for now I am leaving
+      // the previous approach of using the a11y-combination function
+      --pst-color-#{$name}-text: #{a11y-combination($value)};
       // // TODO: check where highlight is used
-      // --pst-color-#{$name}-highlight: #{darken(#{$value}, 15%)};
-      // // override the sphinx-design variables
+      --pst-color-#{$name}-highlight: #{darken($value, 15%)};
+      // override the sphinx-design variables
       --sd-color-#{$name}: var(--pst-color-#{$name});
-      // --sd-color-#{$name}-text: var(--pst-color-#{$name}-text);
+      --sd-color-#{$name}-text: var(--pst-color-#{$name}-text);
       // TODO: check where highlight is used
-      // --sd-color-#{$name}-highlight: var(--pst-color-#{$name}-highlight);
+      --sd-color-#{$name}-highlight: var(--pst-color-#{$name}-highlight);
     }
   }
 }
@@ -305,8 +205,7 @@ details.sd-dropdown {
       border-left: 0.2rem solid var(--pst-sd-dropdown-color) !important;
       border-bottom-left-radius: calc(0.25rem - 1px);
     }
-
-    span.sd-summary-icon {
+    phi span.sd-summary-icon {
       display: inline-flex;
       align-items: center;
       color: var(--pst-sd-dropdown-color) !important;

From f1b3787231c648f50c6b201a4289ffab1e6e3059 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 24 Feb 2023 19:13:39 +0000
Subject: [PATCH 22/64] :lipstick: Update tabs hover

---
 .../assets/styles/extensions/_sphinx_design.scss       | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 8c2bc5d4e..92142fa91 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -133,9 +133,8 @@ html[data-theme="light"] {
 
     // hover label
     &:not(:checked) + label:hover {
-      border-color: var(--pst-color-primary);
-      color: var(--pst-color-primary);
-      opacity: 0.5;
+      border-color: var(--pst-color-secondary);
+      color: var(--pst-color-secondary);
     }
   }
 
@@ -145,9 +144,8 @@ html[data-theme="light"] {
 
     // Hovered label
     html &:hover {
-      color: var(--pst-color-primary);
-      border-color: var(--pst-color-primary);
-      opacity: 0.5;
+      color: var(--pst-color-secondary);
+      border-color: var(--pst-color-secondary);
     }
   }
 }

From 5a6ae4cec7f7f553b6c5decee3937c1232216207 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 20 Mar 2023 12:07:40 +0000
Subject: [PATCH 23/64] =?UTF-8?q?=E2=99=BF=EF=B8=8F=20Tweaks=20to=20colour?=
 =?UTF-8?q?s=20in=20small=20components?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../assets/styles/components/_switcher-theme.scss             | 4 ++--
 .../assets/styles/extensions/_sphinx_design.scss              | 1 -
 .../assets/styles/sections/_announcement.scss                 | 2 +-
 3 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/components/_switcher-theme.scss b/src/pydata_sphinx_theme/assets/styles/components/_switcher-theme.scss
index 81b9dc7a5..0d5cf39fb 100644
--- a/src/pydata_sphinx_theme/assets/styles/components/_switcher-theme.scss
+++ b/src/pydata_sphinx_theme/assets/styles/components/_switcher-theme.scss
@@ -21,8 +21,8 @@
   &:hover,
   &:active {
     // overide bootstrap settings
-    background-color: var(--pst-color-on-surface) !important;
-    border-color: var(--pst-color-on-background) !important;
+    background-color: var(--pst-color-border) !important;
+    border-color: var(--pst-color-border) !important;
     a {
       color: var(--pst-color-text-muted);
     }
diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 92142fa91..18c73c47f 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -50,7 +50,6 @@ $extra-semantic-colors: (
 );
 
 $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
-@debug "sd-semantic-color-names: #{$sd-semantic-color-names}";
 
 // Now we override the --sd-color-* variables.
 @each $mode in (light, dark) {
diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss b/src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss
index 315197608..aa59a6bf2 100644
--- a/src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss
+++ b/src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss
@@ -18,7 +18,7 @@
     margin: 0;
   }
 
-  // Bg color is now defined in the theme color palette
+  // Bg color is now defined in the theme color palette - using our secondary color
   &:after {
     position: absolute;
     width: 100%;

From cb5b81b6bbe96de2fceef42cfea389cf8b577f1b Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 20 Mar 2023 12:08:51 +0000
Subject: [PATCH 24/64] =?UTF-8?q?=E2=99=BF=EF=B8=8F=20Move=20WCAG=20contra?=
 =?UTF-8?q?st=20to=20mixin=20file?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/user_guide/announcements.rst             |  2 +-
 docs/user_guide/web-components.rst            | 21 +++++++++------
 .../assets/styles/abstracts/_mixins.scss      | 27 +++++++++----------
 3 files changed, 26 insertions(+), 24 deletions(-)

diff --git a/docs/user_guide/announcements.rst b/docs/user_guide/announcements.rst
index 6c44c2d3b..09f7d8598 100644
--- a/docs/user_guide/announcements.rst
+++ b/docs/user_guide/announcements.rst
@@ -12,7 +12,7 @@ Provide local HTML in your theme
 
 By default, the value of your ``html_theme_options["announcement"]`` will be inserted directly into your announcement banner as raw HTML.
 
-For example, the following configuration adds a simple ``<p>`` with an announcement.
+For example, the following configuration adds a simple block of text (``<p>``) with an announcement.
 
 .. code-block:: python
 
diff --git a/docs/user_guide/web-components.rst b/docs/user_guide/web-components.rst
index d01f8dca9..5df510495 100644
--- a/docs/user_guide/web-components.rst
+++ b/docs/user_guide/web-components.rst
@@ -4,11 +4,14 @@
 Sphinx Design Components
 ========================
 
-Cards and tabs provide some extra UI flexibility for your content. This theme provides custom CSS to ensure that `sphinx-design <https://sphinx-design.readthedocs.io/en/latest/index.html>`__ elements look and feel consistent with this theme.
+The PyData Sphinx Theme uses `sphinx-design <https://sphinx-design.readthedocs.io/en/latest/index.html>`__
+to add several UI components and provide extra flexibility for content creation.
+These include badges, buttons, cards, and tabs, among other components.
+This theme provides custom CSS to ensure that `sphinx-design <https://sphinx-design.readthedocs.io/en/latest/index.html>`__ elements look and feel consistent with this theme.
 
 .. seealso::
 
-   For more about how to use these extensions, see `the sphinx-design documentation <https://sphinx-design.readthedocs.io/en/latest/index.html>`_.
+    For more information about how to use these extensions, see `the sphinx-design documentation <https://sphinx-design.readthedocs.io/en/latest/index.html>`_.
 
 Below you can find some examples of the components created with the :code:`sphinx-design` extension.
 
@@ -18,15 +21,17 @@ Badges and buttons
 ==================
 
 Here are some of the available badges:
+
 :bdg-primary:`primary`
-:bdg-secondary:`secondary`
+:bdg-secondary:`secondary``
 :bdg-success:`success`
 :bdg-primary-line:`primary outline`
 :bdg-secondary-line:`secondary outline`
 :bdg-success-line:`success outline`
 
-Here are some buttons, also using semantic color names. **Note:** in this theme, ``info`` is defined to be the same color as ``primary``, and ``warning`` is the same color as ``secondary``.
-If in your site's `custom CSS file <custom-css>`_ you override the `CSS custom properties <css-variables>`_ ``--pst-color-*`` (where ``*`` is one of the semantic color names, e.g., ``primary``, ``danger``, etc), badges and buttons will automatically use the custom color.
+Here are some buttons, also using semantic color names.
+
+If in your site's `custom CSS file <custom-css>`_ you override the `CSS custom properties <css-variables>`_ ``--pst-color-*`` (where ``*`` is one of the semantic color names, e.g., ``primary``, ``danger``, etc.), badges and buttons will automatically use the custom color.
 
 .. grid:: auto
 
@@ -162,7 +167,7 @@ Tabs
 Dropdowns
 =========
 
-Dropdowns should look similar to admonitions, but clickable.
+Dropdowns look similar to admonitions, but they are clickable interactive elements that can be used to hide content.
 See `the Sphinx Design Dropdown documentation <https://sphinx-design.readthedocs.io/en/latest/dropdowns.html>`__ for more information.
 
 .. admonition:: An admonition for reference.
@@ -182,13 +187,13 @@ See `the Sphinx Design Dropdown documentation <https://sphinx-design.readthedocs
 
    And some content and an icon!
 
-.. dropdown:: A primary title and color
+.. dropdown:: A primary color dropdown
    :color: primary
    :icon: unlock
 
    And some content!
 
-.. dropdown:: A secondary title and color
+.. dropdown:: A secondary color dropdown
    :color: secondary
    :icon: unlock
 
diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
index 9ac42aa3f..026c90ea7 100644
--- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
+++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -1,7 +1,7 @@
 /*********************************************
 * SASS Mixins
 *********************************************/
-
+@use "sass:color";
 /**
 * Scrollbars should be thinner and slightly rounded, with a grey background
 * ref: https://www.nngroup.com/articles/scrolling-and-scrollbars/
@@ -22,7 +22,8 @@
   }
 
   &::-webkit-scrollbar-thumb {
-    background: var(--pst-color-on-surface);
+    // ensure we have a 3:1 contrast ratio
+    background: var(--pst-gray-500);
   }
 
   // Hovering behavior for the scrollbar
@@ -75,18 +76,15 @@
  * Format before pseudo element - TODO: decide if we still need this
  */
 @mixin format-before($color-variable) {
-  &:before {
-    content: "";
-    width: 100%;
-    height: 100%;
-    position: absolute;
-    left: 0;
-    top: 0;
-
-    // So that hovering over the text within background is still possible.
-    // Otherwise the background overlays the text and you cannot click or select easily.
-    // ref: https://developer.mozilla.org/en-US/docs/Web/CSS/pointer-events
-    pointer-events: none;
+  @if (str-index($color-variable, "bg") != null) {
+    background-color: var(#{$color-variable});
+  } @else {
+    // $color: change-color(var(#{$color-variable}), $lightness: 30%);
+    background-color: adjust-color(
+      var(#{$color-variable}),
+      $lightness: +20%,
+      $alpha: -0.4
+    );
   }
 }
 
@@ -211,7 +209,6 @@ $_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
   $max-ratio: 0;
   $max-ratio-color: null;
 
-  @debug "Using AA #{$min-contrast-ratio}:1 contrast ratio for #{$bg} ♿️";
   @each $fg in $foregrounds {
     $contrast-ratio: get-contrast-ratio($bg, $fg);
     @if $contrast-ratio >= $min-contrast-ratio {

From 9ed2d8c36647ae86df6290d3ae68ddf9d646f851 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 20 Mar 2023 12:47:52 +0000
Subject: [PATCH 25/64] Update theming docs

---
 docs/user_guide/extending.rst      | 3 +--
 docs/user_guide/web-components.rst | 2 +-
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/user_guide/extending.rst b/docs/user_guide/extending.rst
index 084790199..0bc02a842 100644
--- a/docs/user_guide/extending.rst
+++ b/docs/user_guide/extending.rst
@@ -39,7 +39,7 @@ Then add the ``dropdown`` class to any admonition directive (shown here on a ``n
 Custom admonition styles
 ========================
 
-A `limited set <https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions>`__ of admonitions are built-in to docutils (the rST → HTML engine that underlies Sphinx). However, it is possible to create custom admonitions with their own default colors, icons, and titles.
+A `limited set <https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions>`__ of admonitions are built-in to docutils (the ``rST`` → ``HTML`` engine that underlies Sphinx). However, it is possible to create custom admonitions with their own default colors, icons, and titles.
 
 
 Customizing the title
@@ -92,7 +92,6 @@ Note that it updates both the color and the icon.
 
 This theme defines classes for `the standard docutils admonition types <https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions>`__ (``attention``, ``caution``, etc) and additionally supports ``seealso`` and ``todo`` admonitions (see :doc:`../examples/kitchen-sink/admonitions` for a demo of all built-in admonition styles).
 
-
 Customizing the color
 ---------------------
 
diff --git a/docs/user_guide/web-components.rst b/docs/user_guide/web-components.rst
index 5df510495..5a4af875a 100644
--- a/docs/user_guide/web-components.rst
+++ b/docs/user_guide/web-components.rst
@@ -23,7 +23,7 @@ Badges and buttons
 Here are some of the available badges:
 
 :bdg-primary:`primary`
-:bdg-secondary:`secondary``
+:bdg-secondary:`secondary`
 :bdg-success:`success`
 :bdg-primary-line:`primary outline`
 :bdg-secondary-line:`secondary outline`

From 8d55e7dcaef46afade0f3c71b0178cbee68d98fb Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 20 Mar 2023 15:03:58 +0000
Subject: [PATCH 26/64] :memo: Update a11y docs

---
 docs/user_guide/accessibility.rst | 20 ++++++++++++--------
 docs/user_guide/styling.rst       | 31 ++++++++++++++++++-------------
 2 files changed, 30 insertions(+), 21 deletions(-)

diff --git a/docs/user_guide/accessibility.rst b/docs/user_guide/accessibility.rst
index 40e30c4d5..b0b82e3cf 100644
--- a/docs/user_guide/accessibility.rst
+++ b/docs/user_guide/accessibility.rst
@@ -8,8 +8,7 @@
 Accessibility
 *************
 
-Creating and publishing content that does not exclude audiences with limited abilities
-of various kinds is challenging, but also important, to achieve and then maintain.
+Creating and publishing content that does not exclude disabled users is a complex and iterative task.
 
 While there is no one-size-fits-all solution to maintaining accessible content, this
 theme and documentation site use some techniques to avoid common content shortcomings.
@@ -34,12 +33,17 @@ page that lacks metadata, please open a pull request to add it!
 Colors
 ======
 
-Our default code highlighting styles are ``a11y-high-contrast-light`` and
-``a11y-high-contrast-dark`` from https://github.com/Quansight-Labs/accessible-pygments.
-These styles are designed to be more accessible to users with limited visual abilities.
-If you don't like the look of our default code highlighting styles, there are several more
-to choose from at https://github.com/Quansight-Labs/accessible-pygments.
-
+* Our default code highlighting styles are ``a11y-high-contrast-light`` and
+  ``a11y-high-contrast-dark`` from https://github.com/Quansight-Labs/accessible-pygments.
+  These styles are designed to meet WCAG 2 AA or AAA contrast requirements.
+  If you don't like the look of our default code highlighting styles, there are several more
+  to choose from at https://github.com/Quansight-Labs/accessible-pygments.
+* We recently revisited the PyData Sphinx theme color palette to ensure that
+  the colors we use meet WCAG 2 AA or AAA contrast requirements.
+* We also re-defined our ``primary`` and ``secondary`` colors to be more accessible and distinct from semantic colors used
+  to denote success, warning, info, and danger situations.
+* We simplified the color palette and removed some colors that were problematic to meet WCAG 2 AA or AAA contrast requirements
+  and for certain types of colorblindness.
 
 What You Can Do
 ^^^^^^^^^^^^^^^
diff --git a/docs/user_guide/styling.rst b/docs/user_guide/styling.rst
index cb8228132..8b6022b26 100644
--- a/docs/user_guide/styling.rst
+++ b/docs/user_guide/styling.rst
@@ -17,8 +17,8 @@ Any rules in this style-sheet will over-ride the default theme rules.
 
 To add a custom stylesheet, follow these steps:
 
-1. **Create a CSS stylesheet** in ``_static/css/custom.css``, and add the CSS rules you wish.
-2. **Attach the stylesheet to your Sphinx build**. Add the following to ``conf.py``
+1. **Create a CSS stylesheet** in ``_static/css/custom.css``, and update the CSS rules as desired.
+2. **Attach the stylesheet to your Sphinx build**. Add the following to ``conf.py``:
 
    .. code-block:: python
 
@@ -37,16 +37,15 @@ This theme defines several `CSS variables <css-variable-help_>`_ that can be
 used to quickly control behavior and display across your documentation.
 
 These are based on top of the basic `Bootstrap CSS variables <https://getbootstrap.com/docs/4.0/getting-started/theming/#css-variables>`_
-extended with some theme specific variables.
+extended with some theme-specific variables.
 
-base variables
+Base variables
 --------------
 
-In order to change a variable, follow these steps:
+Follow these steps to update the base variables:
 
 1. :ref:`Add a custom CSS stylesheet <custom-css>`. This is where we'll configure the variables.
-2. Underneath a ``html`` section, add the variables you wish to update. For example, to update
-   the base font size, you might add this to ``custom.css``:
+2. Underneath a ``html`` section, add the variables you wish to update. For example, to change the base font size you would add the following to your ``custom.css`` file :
 
    .. code-block:: css
 
@@ -60,6 +59,7 @@ In order to change a variable, follow these steps:
    `SASS variables <https://sass-lang.com/documentation/variables>`_.
    The theme is defined with CSS variables, not SASS variables! Refer to the previous section if
    you desire a different behavior between the light and dark theme.
+.. TODO: add correct reference to light and dark theme @trallard
 
 For a complete list of the theme variables that you may override, see the
 `theme variables defaults CSS file <pydata-css-variables_>`_:
@@ -82,20 +82,20 @@ For a complete list of the theme variables that you may override, see the
 Color variables
 ---------------
 
-There are two special color variables for primary and secondary theme colors (``--pst-color-primary`` and ``--pst-color-secondary``, respectively).
+This theme specifies color variables for the primary and secondary colors (``--pst-color-primary`` and ``--pst-color-secondary``, respectively).
 These are meant to complement one another visually across the theme, if you modify these, choose colors that look good when paired with one another.
-There are also several other color variables that control color for admonitions, links, menu items, etc.
+There are also several other color variables that control the color for admonitions, links, menu items, etc.
 
 Each color variable has two values, one corresponding to the "light" and one for the "dark" theme.
 These are used throughout many of the theme elements to define text color, background color, etc.
 
 Here is an overview of the colors available in the theme (change theme mode to switch from light to dark versions).
 
+
 .. raw:: html
 
     <style>
-      span.pst-badge {border: 1px solid var(--pst-color-text-base);}
-      span.pst-primary {background-color: var(--pst-color-primary);}
+      span.pst-primary {background-color: var(--pst-color-primary); color: #{a11y-combination(--pst-color-primary)}}
       span.pst-secondary {background-color: var(--pst-color-secondary);}
       span.pst-success {background-color: var(--pst-color-success);}
       span.pst-info {background-color: var(--pst-color-info);}
@@ -140,7 +140,7 @@ It defines 4 color variables that help build overlays in your documentation.
 
 - :code:`background`: color of the back-most surface of the documentation
 - :code:`on-background` elements that are set on top of this background (e.g. the header navbar on dark mode).
-- :code:`surface` elements set on the background with a light-grey color in the light theme mode. this color has been kept in the dark theme (e.g. code-block directives).
+- :code:`surface` elements set on the background with a light-grey color in the light theme mode. This color has been kept in the dark theme (e.g. code-block directives).
 - :code:`on-surface` elements that are on top of :code:`surface` elements (e.g. sidebar directives).
 
 The following image should help you understand these overlays:
@@ -184,7 +184,8 @@ For a complete list of the theme colors that you may override, see the :download
 Configure pygments theme
 ========================
 
-As the Sphinx theme supports multiple modes, the code highlighting colors can be modified for each one of them by modifying the ``pygment_light_style`` and ``pygment_dark_style``. You can check available Pygments colors on this `page <https://pygments.org/styles/>`__.
+As the Sphinx theme supports multiple modes, the code highlighting colors can be modified for each one of them by modifying the ``pygment_light_style`` and ``pygment_dark_style``.
+You can check available Pygments colors on this `pygments demo page <https://pygments.org/styles/>`__.
 
 .. code-block:: python
 
@@ -194,6 +195,10 @@ As the Sphinx theme supports multiple modes, the code highlighting colors can be
       "pygment_dark_style": "monokai"
    }
 
+Note that the PyData Sphinx theme uses the `accessible pygments styles <https://github.com/Quansight-Labs/accessible-pygments>`__ for its default syntax highlighting themes.
+The accessible pygments themes are designed to meet `WCAG <https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html>`__ AA or AAA standards for contrast and some themes are also suitable for colorblind users
+or low light conditions. You can check all the available styles at the `accessible pygments demo page <https://quansight-labs.github.io/accessible-pygments/>`__.
+
 .. danger::
 
    The native Sphinx option ``pygments_style`` will be overwritten by this theme.

From 7b94982971f066b67ffc65d9fdf8ff66ca77af24 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 20 Mar 2023 20:26:49 +0000
Subject: [PATCH 27/64] Update accessibility docs

---
 docs/user_guide/accessibility.rst | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/docs/user_guide/accessibility.rst b/docs/user_guide/accessibility.rst
index b0b82e3cf..3b427febb 100644
--- a/docs/user_guide/accessibility.rst
+++ b/docs/user_guide/accessibility.rst
@@ -48,10 +48,10 @@ Colors
 What You Can Do
 ^^^^^^^^^^^^^^^
 
-In Configuration
-================
+Site configuration
+==================
 
-Some minor configuration options in a site's ``conf.py`` can impact the
+The following sections include recommendations for settings in the ``conf.py`` file can positively impact the
 accessibility of content generated by this theme, and Sphinx in general.
 
 
@@ -97,6 +97,23 @@ it's handy to generate a `sitemap.xml` locally or in CI with a tool like
         sitemap_url_scheme = "{link}"
 
 
+Logo best practices
+--------------------
+
+If you use both light and dark themes, it's best to provide a logo that works well in both, or to provide and alternate for the dark theme.
+If you have a logo, you can add alt-text to it by adding the following to your
+``conf.py``:
+
+.. code-block:: python
+
+  "logo": {
+      "text": "PyData Theme",
+      "image_dark": "_static/logo-dark.svg",
+      "alt_text": "PyData Theme home",
+  },
+
+Note the use of `home` to indicate that the logo is also a link to the home page.
+
 In Your Source
 ==============
 

From d21b3ed0455d358e3e4febcd8015ac866eebe020 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 21 Mar 2023 19:35:57 +0000
Subject: [PATCH 28/64] Fix search button text contrast

---
 .../assets/styles/components/_searchbox.scss                   | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/components/_searchbox.scss b/src/pydata_sphinx_theme/assets/styles/components/_searchbox.scss
index f213bdbac..a13caa14d 100644
--- a/src/pydata_sphinx_theme/assets/styles/components/_searchbox.scss
+++ b/src/pydata_sphinx_theme/assets/styles/components/_searchbox.scss
@@ -24,8 +24,7 @@ div#searchbox {
       font-size: 1.25rem;
       padding: 0.75rem;
       background-color: var(--pst-color-primary);
-      // Button text is always white with Sphinx Design buttons
-      color: white;
+      color: var(--pst-color-primary-text);
 
       // The box shadow is inset so that it darkens the button on hover
       transition: box-shadow 0.25s ease-out;

From 33484ddf76f616a69d85c3c4553d399a6c3b7085 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 21 Mar 2023 20:09:17 +0000
Subject: [PATCH 29/64] Fix colours in admonitions

---
 .../assets/styles/abstracts/_mixins.scss      | 29 ++++---------------
 .../styles/components/_versionmodified.scss   |  2 --
 .../assets/styles/content/_admonitions.scss   | 28 +++++++++---------
 3 files changed, 19 insertions(+), 40 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
index 026c90ea7..289abd833 100644
--- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
+++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -1,7 +1,7 @@
 /*********************************************
 * SASS Mixins
 *********************************************/
-@use "sass:color";
+// @use "sass:color";
 /**
 * Scrollbars should be thinner and slightly rounded, with a grey background
 * ref: https://www.nngroup.com/articles/scrolling-and-scrollbars/
@@ -48,13 +48,9 @@
 }
 
 /**
- * create a low opacity background behind object using our variable colors
+ * set background color from a color variable
  */
-@mixin background-from-color-variable($color-variable, $opacity: 0.1) {
-  // This is a hack to create a light background with controlled opacity
-  // using our css color variables
-  // ref: https://stackoverflow.com/a/56951626/6734243
-
+@mixin background-from-color-variable($color-variable) {
   &:before {
     content: "";
     width: 100%;
@@ -63,7 +59,7 @@
     left: 0;
     top: 0;
     background-color: var(#{$color-variable});
-    opacity: $opacity;
+    z-index: -1;
 
     // So that hovering over the text within background is still possible.
     // Otherwise the background overlays the text and you cannot click or select easily.
@@ -72,22 +68,6 @@
   }
 }
 
-/**
- * Format before pseudo element - TODO: decide if we still need this
- */
-@mixin format-before($color-variable) {
-  @if (str-index($color-variable, "bg") != null) {
-    background-color: var(#{$color-variable});
-  } @else {
-    // $color: change-color(var(#{$color-variable}), $lightness: 30%);
-    background-color: adjust-color(
-      var(#{$color-variable}),
-      $lightness: +20%,
-      $alpha: -0.4
-    );
-  }
-}
-
 /**
  * Set background of some cell outputs to white-ish to make sure colors work
  * This is because many libraries make output that only looks good on white
@@ -209,6 +189,7 @@ $_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
   $max-ratio: 0;
   $max-ratio-color: null;
 
+  @debug "Using AA #{$min-contrast-ratio}:1 contrast ratio for #{$bg} ♿️";
   @each $fg in $foregrounds {
     $contrast-ratio: get-contrast-ratio($bg, $fg);
     @if $contrast-ratio >= $min-contrast-ratio {
diff --git a/src/pydata_sphinx_theme/assets/styles/components/_versionmodified.scss b/src/pydata_sphinx_theme/assets/styles/components/_versionmodified.scss
index a8f03d1f3..921a3e823 100644
--- a/src/pydata_sphinx_theme/assets/styles/components/_versionmodified.scss
+++ b/src/pydata_sphinx_theme/assets/styles/components/_versionmodified.scss
@@ -17,8 +17,6 @@ div.deprecated {
   > p {
     margin-bottom: 0.6rem;
     margin-top: 0.6rem;
-
-    @include format-before(--pst-color-info);
   }
 }
 
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss b/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
index 2373799bd..16b9ecf51 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
@@ -38,7 +38,9 @@ div.admonition,
     padding: 0.4rem 0.6rem 0.4rem 2rem;
     font-weight: var(--pst-font-weight-heading);
     position: relative;
-    background-color: var(--pst-color-info-bg);
+    @include background-from-color-variable(--pst-color-info-bg);
+    // now that we use solid colors we want the title on top
+    z-index: 1;
 
     &:after {
       position: absolute;
@@ -52,8 +54,6 @@ div.admonition,
       opacity: 1;
     }
 
-    @include format-before(--pst-color-info);
-
     // Next element after title needs some extra upper-space
     + * {
       margin-top: 0.4em;
@@ -63,7 +63,7 @@ div.admonition,
   &.attention {
     border-color: var(--pst-color-attention);
     > .admonition-title {
-      background-color: var(--pst-color-warning-bg);
+      @include background-from-color-variable(--pst-color-warning-bg);
 
       &:after {
         color: var(--pst-color-attention);
@@ -75,7 +75,7 @@ div.admonition,
   &.caution {
     border-color: var(--pst-color-warning);
     > .admonition-title {
-      background-color: var(--pst-color-warning-bg);
+      @include background-from-color-variable(--pst-color-warning-bg);
 
       &:after {
         color: var(--pst-color-warning);
@@ -87,7 +87,7 @@ div.admonition,
   &.warning {
     border-color: var(--pst-color-warning);
     > .admonition-title {
-      background-color: var(--pst-color-warning-bg);
+      @include background-from-color-variable(--pst-color-warning-bg);
 
       &:after {
         color: var(--pst-color-warning);
@@ -99,7 +99,7 @@ div.admonition,
   &.danger {
     border-color: var(--pst-color-danger);
     > .admonition-title {
-      background-color: var(--pst-color-danger-bg);
+      @include background-from-color-variable(--pst-color-danger-bg);
 
       &:after {
         color: var(--pst-color-danger);
@@ -111,7 +111,7 @@ div.admonition,
   &.error {
     border-color: var(--pst-color-danger);
     > .admonition-title {
-      background-color: var(--pst-color-danger-bg);
+      @include background-from-color-variable(--pst-color-danger-bg);
 
       &:after {
         color: var(--pst-color-danger);
@@ -123,7 +123,7 @@ div.admonition,
   &.hint {
     border-color: var(--pst-color-success);
     > .admonition-title {
-      background-color: var(--pst-color-success-bg);
+      @include background-from-color-variable(--pst-color-success-bg);
 
       &:after {
         color: var(--pst-color-success);
@@ -135,7 +135,7 @@ div.admonition,
   &.tip {
     border-color: var(--pst-color-success);
     > .admonition-title {
-      background-color: var(--pst-color-success-bg);
+      @include background-from-color-variable(--pst-color-success-bg);
 
       &:after {
         color: var(--pst-color-success);
@@ -147,7 +147,7 @@ div.admonition,
   &.important {
     border-color: var(--pst-color-attention);
     > .admonition-title {
-      background-color: var(--pst-color-warning-bg);
+      @include background-from-color-variable(--pst-color-warning-bg);
 
       &:after {
         color: var(--pst-color-attention);
@@ -159,7 +159,7 @@ div.admonition,
   &.note {
     border-color: var(--pst-color-info);
     > .admonition-title {
-      background-color: var(--pst-color-info-bg);
+      @include background-from-color-variable(--pst-color-info-bg);
 
       &:after {
         color: var(--pst-color-info);
@@ -171,7 +171,7 @@ div.admonition,
   &.seealso {
     border-color: var(--pst-color-success);
     > .admonition-title {
-      background-color: var(--pst-color-success-bg);
+      @include background-from-color-variable(--pst-color-success-bg);
 
       &:after {
         color: var(--pst-color-success);
@@ -183,7 +183,7 @@ div.admonition,
   &.admonition-todo {
     border-color: var(--pst-color-secondary);
     > .admonition-title {
-      background-color: var(--pst-color-secondary-bg);
+      @include background-from-color-variable(--pst-color-secondary-bg);
 
       &:after {
         color: var(--pst-color-secondary);

From 655826c3579d4939fa07d401dcf1e6b4b8e2aa95 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 21 Mar 2023 20:09:32 +0000
Subject: [PATCH 30/64] Ensure we use WCAG compliant text color

---
 .../assets/styles/extensions/_sphinx_design.scss             | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 18c73c47f..9ebbb0094 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -6,7 +6,6 @@
  * same for our overrides to have any effect.
  */
 @use "../variables/color" as pst-color;
-@use "sass:color" as color;
 
 /*******************************************************************************
   * Color and variables
@@ -42,11 +41,12 @@ $sd-semantic-color-names: (
   * already define for our own needs.
   */
 $extra-semantic-colors: (
+  // TODO need to better adjust these colours (dark and muted)
   "dark": map-get($pst-semantic-colors, "text-base"),
   "muted": map-get($pst-semantic-colors, "text-muted"),
   "light": $foundation-light-grey,
   "black": $foundation-black,
-  "white": $foundation-white,
+  "white": $foundation-white
 );
 
 $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
@@ -173,7 +173,6 @@ details.sd-dropdown {
     font-weight: 600;
     padding-top: 0.5rem;
     padding-bottom: 0.5rem;
-    color: var(--pst-color-text) !important;
 
     // Set a variable that we can re-use for colors later
     // We must set this in the current and content sibling container

From 6943a46ca5e0285b54635e2d1ac2401d6d7651d2 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 21 Mar 2023 20:09:49 +0000
Subject: [PATCH 31/64] Update docs - web components

---
 docs/user_guide/web-components.rst | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/docs/user_guide/web-components.rst b/docs/user_guide/web-components.rst
index 5a4af875a..a88c3bb51 100644
--- a/docs/user_guide/web-components.rst
+++ b/docs/user_guide/web-components.rst
@@ -31,7 +31,7 @@ Here are some of the available badges:
 
 Here are some buttons, also using semantic color names.
 
-If in your site's `custom CSS file <custom-css>`_ you override the `CSS custom properties <css-variables>`_ ``--pst-color-*`` (where ``*`` is one of the semantic color names, e.g., ``primary``, ``danger``, etc.), badges and buttons will automatically use the custom color.
+If in your site's `custom CSS file <custom-css>`_ you override the `CSS custom properties <css-variables>`_ ``--pst-color-*`` (where ``*`` is one of the semantic color names, such as ``primary``, ``danger``), badges and buttons will automatically use the custom color.
 
 .. grid:: auto
 
@@ -44,6 +44,15 @@ If in your site's `custom CSS file <custom-css>`_ you override the `CSS custom p
 
             Info
 
+    .. grid-item::
+
+        .. button-ref:: badges-buttons
+            :ref-type: ref
+            :color: success
+            :shadow:
+
+            Success
+
     .. grid-item::
 
         .. button-ref:: badges-buttons

From bcce67e9be56b44a7716da5d12c0063b7f3d2a1c Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 21 Mar 2023 20:09:59 +0000
Subject: [PATCH 32/64] Fix quotes text colour

---
 src/pydata_sphinx_theme/assets/styles/content/_quotes.scss | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/content/_quotes.scss b/src/pydata_sphinx_theme/assets/styles/content/_quotes.scss
index e52b9e6fc..be5fd9655 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_quotes.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_quotes.scss
@@ -7,7 +7,7 @@ blockquote {
   position: relative;
 
   p {
-    color: var(--pst-color-text-muted);
+    color: var(--pst-color-text-base);
   }
 
   // remove padding from included line-block to avoid duplication
@@ -19,7 +19,7 @@ blockquote {
   p:last-child {
     margin-bottom: 0;
   }
-
+  // TODO replace colour
   @include background-from-color-variable(--pst-color-border);
 
   //hack to make the text in the blockquote selectable

From 19f789ca657afc9e6ab84b033092fbcb01ed4046 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 21 Mar 2023 20:48:28 +0000
Subject: [PATCH 33/64] Add more details re accessibility

---
 docs/_static/custom.css                            | 12 ++++++------
 docs/user_guide/accessibility.rst                  | 14 +++++---------
 .../assets/styles/extensions/_sphinx_design.scss   |  2 +-
 3 files changed, 12 insertions(+), 16 deletions(-)

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index 10feae3a2..9c7671efe 100644
--- a/docs/_static/custom.css
+++ b/docs/_static/custom.css
@@ -25,13 +25,13 @@
 /* begin-custom-color/* <your static path>/custom.css */
 
 div.admonition.admonition-olive {
-  border-color: olive;
+  border-color: hsl(60, 100%, 25%);
 }
 div.admonition.admonition-olive > .admonition-title:before {
-  background-color: olive;
+  background-color: hsl(60, 100%, 14%);
 }
 div.admonition.admonition-olive > .admonition-title:after {
-  color: olive;
+  color: hsl(60, 100%, 25%);
 }
 /* end-custom-color */
 
@@ -45,13 +45,13 @@ div.admonition.admonition-icon > .admonition-title:after {
 /* begin-custom-youtube/* <your static path>/custom.css */
 
 div.admonition.admonition-youtube {
-  border-color: #ff0000; /* YouTube red */
+  border-color: hsl(0, 100%, 50%); /* YouTube red */
 }
 div.admonition.admonition-youtube > .admonition-title:before {
-  background-color: #ff0000;
+  background-color: hsl(0, 99%, 18%);
 }
 div.admonition.admonition-youtube > .admonition-title:after {
-  color: #ff0000;
+  color: hsl(0, 100%, 50%);
   content: "\f26c"; /* fa-solid fa-tv */
 }
 /* end-custom-youtube */
diff --git a/docs/user_guide/accessibility.rst b/docs/user_guide/accessibility.rst
index 3b427febb..a39b7f778 100644
--- a/docs/user_guide/accessibility.rst
+++ b/docs/user_guide/accessibility.rst
@@ -44,6 +44,8 @@ Colors
   to denote success, warning, info, and danger situations.
 * We simplified the color palette and removed some colors that were problematic to meet WCAG 2 AA or AAA contrast requirements
   and for certain types of colorblindness.
+* We have improved how we assign text colors to interactive elements such as buttons and dropdowns to ensure that they meet
+  WCAG 2 AA or AAA contrast requirements.
 
 What You Can Do
 ^^^^^^^^^^^^^^^
@@ -114,14 +116,6 @@ If you have a logo, you can add alt-text to it by adding the following to your
 
 Note the use of `home` to indicate that the logo is also a link to the home page.
 
-In Your Source
-==============
-
-
-.. Note::
-
-    Stay tuned for more ideas here as we learn more working on this site!
-
 In the Browser
 ==============
 
@@ -152,8 +146,10 @@ WAVE
 ----
 
 `WAVE <https://wave.webaim.org/extension/>`__ is a proprietary (but *gratis*)
-browser extension which can highlight a large number of issues.
+browser extension which can highlight multiple issues.
 
+.. Warning::
+  Note that automated testing and extensions such as the mentioned above will at best catch 30-40% of accessibility issues. They are not a replacement for manual testing and having a perfect score on either of these tools does not mean your site is accessible but instead signal that it follows some accessibility best practices.
 
 In Continuous Integration
 =========================
diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 9ebbb0094..18cf05a5b 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -161,7 +161,7 @@ details.sd-dropdown {
       border: 0;
     }
   }
-
+  // TODO: colour should match admonitions
   // Drop shadow should behave same as admonitions
   @include box-shadow();
 

From daf994d4aecbd1919484fbdd3a3270433260c89e Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Wed, 22 Mar 2023 18:33:57 +0000
Subject: [PATCH 34/64] =?UTF-8?q?=F0=9F=93=9D=20Add=20accessibility=20note?=
 =?UTF-8?q?s=20to=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/user_guide/keyboard-shortcuts.md | 8 ++++++--
 docs/user_guide/web-components.rst    | 7 +++----
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/docs/user_guide/keyboard-shortcuts.md b/docs/user_guide/keyboard-shortcuts.md
index fa69b4cbe..89e67770e 100644
--- a/docs/user_guide/keyboard-shortcuts.md
+++ b/docs/user_guide/keyboard-shortcuts.md
@@ -2,11 +2,11 @@
 
 ## Trigger the search bar
 
-You can trigger the search bar pop-up with {guilabel}`ctrl`/{guilabel}`cmd` + {guilabel}`K`.
+You can trigger the search bar pop-up with <kbd>ctrl</kbd>/<kbd>cmd</kbd> + <kbd>K</kbd>.
 
 ## Change pages
 
-By default, you can move to the previous/next page using the {octicon}`arrow-left` and {octicon}`arrow-right` keys on a keyboard.
+By default, you can move to the previous/next page using the {octicon}`arrow-left` (left arrow) and {octicon}`arrow-right` (right arrow) keys on a keyboard.
 To disable this behavior, use the following configuration:
 
 ```py
@@ -14,3 +14,7 @@ html_theme_options = {
     "navigation_with_keys": False
 }
 ```
+
+```{attention}
+Keep in mind that many readers use their keyboards and other assistive technology to interact with web documents. If you disable the keyboard navigation, you might be making your documentaion inaccessible to many readers.
+```
diff --git a/docs/user_guide/web-components.rst b/docs/user_guide/web-components.rst
index a88c3bb51..7d8fae5dc 100644
--- a/docs/user_guide/web-components.rst
+++ b/docs/user_guide/web-components.rst
@@ -29,9 +29,7 @@ Here are some of the available badges:
 :bdg-secondary-line:`secondary outline`
 :bdg-success-line:`success outline`
 
-Here are some buttons, also using semantic color names.
-
-If in your site's `custom CSS file <custom-css>`_ you override the `CSS custom properties <css-variables>`_ ``--pst-color-*`` (where ``*`` is one of the semantic color names, such as ``primary``, ``danger``), badges and buttons will automatically use the custom color.
+Here are some of the available buttons, also using semantic colors:
 
 .. grid:: auto
 
@@ -80,6 +78,8 @@ If in your site's `custom CSS file <custom-css>`_ you override the `CSS custom p
 
             Muted
 
+If in your site's `custom CSS file <custom-css>`_ you override the `CSS custom properties <css-variables>`_ ``--pst-color-*`` (where ``*`` is one of the semantic color names, such as ``primary``, ``danger``), badges and buttons will automatically use the custom color.
+
 Cards
 =====
 
@@ -129,7 +129,6 @@ Cards
         ++++++++++++++
         panel 2 footer
 
-
 Tabs
 ====
 

From aafb573d81e191fe8b9e28db62dd92d3a35af9ec Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Wed, 22 Mar 2023 19:51:30 +0000
Subject: [PATCH 35/64] :lipstick: Ensure we are generating background colours
 too

---
 .../assets/styles/abstracts/_mixins.scss      | 14 ++++-
 .../assets/styles/content/_admonitions.scss   | 44 ++++++++++----
 .../styles/extensions/_sphinx_design.scss     | 59 +++++++++++++------
 3 files changed, 86 insertions(+), 31 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
index 289abd833..b964724ae 100644
--- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
+++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -93,7 +93,18 @@
 }
 
 /**
-* Function to convert the string represenation of a color to a color type
+* Function to check if the color needs converting to a "color" type
+*/
+// @param {String/Color} $color - Color definition from map
+@function check-color($color) {
+  @if type-of($color) == string {
+    $color: from-hex($color);
+  }
+  @return $color;
+}
+
+/**
+* Function to convert the string representation of a color to a color type
 */
 // @param {String} $string - String representation of a color
 @function from-hex($string) {
@@ -189,7 +200,6 @@ $_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
   $max-ratio: 0;
   $max-ratio-color: null;
 
-  @debug "Using AA #{$min-contrast-ratio}:1 contrast ratio for #{$bg} ♿️";
   @each $fg in $foregrounds {
     $contrast-ratio: get-contrast-ratio($bg, $fg);
     @if $contrast-ratio >= $min-contrast-ratio {
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss b/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
index c872b171b..e1822c721 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
@@ -63,7 +63,9 @@ div.admonition,
   &.attention {
     border-color: var(--pst-color-attention);
     > .admonition-title {
-      @include background-from-color-variable(--pst-color-warning-bg);
+      &:before {
+        background-color: var(--pst-color-attention-bg);
+      }
 
       &:after {
         color: var(--pst-color-attention);
@@ -75,7 +77,9 @@ div.admonition,
   &.caution {
     border-color: var(--pst-color-warning);
     > .admonition-title {
-      @include background-from-color-variable(--pst-color-warning-bg);
+      &:before {
+        background-color: var(--pst-color-warning-bg);
+      }
 
       &:after {
         color: var(--pst-color-warning);
@@ -87,7 +91,9 @@ div.admonition,
   &.warning {
     border-color: var(--pst-color-warning);
     > .admonition-title {
-      @include background-from-color-variable(--pst-color-warning-bg);
+      &:before {
+        background-color: var(--pst-color-warning-bg);
+      }
 
       &:after {
         color: var(--pst-color-warning);
@@ -99,7 +105,9 @@ div.admonition,
   &.danger {
     border-color: var(--pst-color-danger);
     > .admonition-title {
-      @include background-from-color-variable(--pst-color-danger-bg);
+      &:before {
+        background-color: var(--pst-color-danger-bg);
+      }
 
       &:after {
         color: var(--pst-color-danger);
@@ -111,7 +119,9 @@ div.admonition,
   &.error {
     border-color: var(--pst-color-danger);
     > .admonition-title {
-      @include background-from-color-variable(--pst-color-danger-bg);
+      &:before {
+        background-color: var(--pst-color-danger-bg);
+      }
 
       &:after {
         color: var(--pst-color-danger);
@@ -123,7 +133,9 @@ div.admonition,
   &.hint {
     border-color: var(--pst-color-success);
     > .admonition-title {
-      @include background-from-color-variable(--pst-color-success-bg);
+      &:before {
+        background-color: var(--pst-color-success-bg);
+      }
 
       &:after {
         color: var(--pst-color-success);
@@ -135,7 +147,9 @@ div.admonition,
   &.tip {
     border-color: var(--pst-color-success);
     > .admonition-title {
-      @include background-from-color-variable(--pst-color-success-bg);
+      &:before {
+        background-color: var(--pst-color-success-bg);
+      }
 
       &:after {
         color: var(--pst-color-success);
@@ -147,7 +161,9 @@ div.admonition,
   &.important {
     border-color: var(--pst-color-attention);
     > .admonition-title {
-      @include background-from-color-variable(--pst-color-warning-bg);
+      &:before {
+        background-color: var(--pst-color-warning-bg);
+      }
 
       &:after {
         color: var(--pst-color-attention);
@@ -159,7 +175,9 @@ div.admonition,
   &.note {
     border-color: var(--pst-color-info);
     > .admonition-title {
-      @include background-from-color-variable(--pst-color-info-bg);
+      &:before {
+        background-color: var(--pst-color-info-bg);
+      }
 
       &:after {
         color: var(--pst-color-info);
@@ -171,7 +189,9 @@ div.admonition,
   &.seealso {
     border-color: var(--pst-color-success);
     > .admonition-title {
-      @include background-from-color-variable(--pst-color-success-bg);
+      &:before {
+        background-color: var(--pst-color-success-bg);
+      }
 
       &:after {
         color: var(--pst-color-success);
@@ -183,7 +203,9 @@ div.admonition,
   &.admonition-todo {
     border-color: var(--pst-color-secondary);
     > .admonition-title {
-      @include background-from-color-variable(--pst-color-secondary-bg);
+      &:before {
+        background-color: var(--pst-color-secondary-bg);
+      }
 
       &:after {
         color: var(--pst-color-secondary);
diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 18cf05a5b..730b05732 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -51,30 +51,53 @@ $extra-semantic-colors: (
 
 $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
 
+@mixin create-sd-colors($value, $name) {
+  // define the pst variables, so that downstream user overrides will work
+  --pst-color-#{$name}: #{$value};
+  @debug "created color 🌱";
+  // we are now using a11y-combination to calculate the text color - this is based
+  // on the WCAG color contrast guidelines
+  --pst-color-#{$name}-text: #{a11y-combination($value)};
+  // // TODO: check where highlight is used
+  --pst-color-#{$name}-highlight: #{darken($value, 15%)};
+  // override the sphinx-design variables
+  --sd-color-#{$name}: var(--pst-color-#{$name});
+  --sd-color-#{$name}-text: var(--pst-color-#{$name}-text);
+  // adding bg colors - needed for dropdowns
+  // --sd-color-#{$name}-bg: var(--pst-color-#{$name});
+  // TODO: check where highlight is used
+  --sd-color-#{$name}-highlight: var(--pst-color-#{$name}-highlight);
+}
+
 // Now we override the --sd-color-* variables.
 @each $mode in (light, dark) {
   html[data-theme="#{$mode}"] {
+    // check if this color is defined differently for light/dark
     @each $name in $sd-semantic-color-names {
-      // check if this color is defined differently for light/dark
-      $value: map-get($all-colors, $name);
-      @if type-of($value) == map {
-        $value: map-get($value, $mode);
-        @if type-of($value) == string {
-          $value: from-hex($value);
+      @debug "name: #{$name} ✨";
+      $definition: map-get($all-colors, $name);
+      @if type-of($definition) == map {
+        @each $key, $value in $definition {
+          @debug "key: #{$key} value: #{$value} definition: #{$definition} ✨";
+          @if str-index($key, $mode) != null {
+            // since now we define the bg colours in the semantic colours and not
+            // by changing opacity, we need to check if the key contains bg and the
+            // correct mode (light/dark)
+            @if str-index($key, "bg") != null {
+              @debug "bg color ✨ #{$value}";
+              --sd-color-#{$name}-bg: #{$value};
+            } @else {
+              $value: check-color($value);
+              @include create-sd-colors($value, $name);
+            }
+          }
         }
+      } @else {
+        @debug "not a map ✨";
+        $value: map-get($all-colors, $name);
+        @debug "value: #{$value} name: #{$name} ✨";
+        @include create-sd-colors($value, $name);
       }
-      // define the pst variables, so that downstream user overrides will work
-      --pst-color-#{$name}: #{$value};
-      // TODO: the text might be best set in the component itself - for now I am leaving
-      // the previous approach of using the a11y-combination function
-      --pst-color-#{$name}-text: #{a11y-combination($value)};
-      // // TODO: check where highlight is used
-      --pst-color-#{$name}-highlight: #{darken($value, 15%)};
-      // override the sphinx-design variables
-      --sd-color-#{$name}: var(--pst-color-#{$name});
-      --sd-color-#{$name}-text: var(--pst-color-#{$name}-text);
-      // TODO: check where highlight is used
-      --sd-color-#{$name}-highlight: var(--pst-color-#{$name}-highlight);
     }
   }
 }

From 1a883d19b6d112877a3f1290f7c693acf924e38f Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 27 Mar 2023 13:52:20 +0100
Subject: [PATCH 36/64] :bug: Fix attention bg colour

---
 src/pydata_sphinx_theme/assets/styles/variables/_color.scss | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index 299f51292..ebb534bf5 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -150,9 +150,9 @@ $pst-semantic-colors: (
   "attention":
     (
       "light": var(--pst-color-warning),
-      "bg-light": var(--pst-color-warning-bg-light),
+      "bg-light": var(--pst-color-warning-bg),
       "dark": var(--pst-color-warning),
-      "bg-dark": var(--pst-color-warning-bg-dark),
+      "bg-dark": var(--pst-color-warning-bg),
     ),
   "danger": (
     "light": #d72d47,

From d62eb873e43b4ef78a80a02a05d201458b9367c7 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 27 Mar 2023 14:09:02 +0100
Subject: [PATCH 37/64] :bug: Fix bg colour issues

---
 src/pydata_sphinx_theme/assets/styles/content/_quotes.scss | 4 ++--
 src/pydata_sphinx_theme/assets/styles/content/_spans.scss  | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/content/_quotes.scss b/src/pydata_sphinx_theme/assets/styles/content/_quotes.scss
index be5fd9655..093f297c3 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_quotes.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_quotes.scss
@@ -19,8 +19,8 @@ blockquote {
   p:last-child {
     margin-bottom: 0;
   }
-  // TODO replace colour
-  @include background-from-color-variable(--pst-color-border);
+
+  @include background-from-color-variable(--pst-color-on-background);
 
   //hack to make the text in the blockquote selectable
   &:before {
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_spans.scss b/src/pydata_sphinx_theme/assets/styles/content/_spans.scss
index 4eb5ad182..cdda6e75b 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_spans.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_spans.scss
@@ -12,7 +12,7 @@ span.guilabel {
   margin: auto 2px;
   position: relative;
 
-  @include background-from-color-variable(--pst-color-info);
+  @include background-from-color-variable(--pst-color-info-bg);
 }
 
 a.reference.download:before {

From d460b67443d0221a7ef222d811ec3ae77e0086d8 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 27 Mar 2023 16:57:05 +0100
Subject: [PATCH 38/64] =?UTF-8?q?=F0=9F=8E=A8=20Improve=20sd=20colours?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../assets/styles/extensions/_sphinx_design.scss      | 10 ++++------
 .../assets/styles/variables/_color.scss               | 11 ++++++++---
 2 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 730b05732..4751230ce 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -41,12 +41,11 @@ $sd-semantic-color-names: (
   * already define for our own needs.
   */
 $extra-semantic-colors: (
-  // TODO need to better adjust these colours (dark and muted)
-  "dark": map-get($pst-semantic-colors, "text-base"),
-  "muted": map-get($pst-semantic-colors, "text-muted"),
-  "light": $foundation-light-grey,
+  "white": $foundation-white,
+  "light": $foundation-light-gray,
+  "muted": $foundation-muted-gray,
+  "dark": $foundation-dark-gray,
   "black": $foundation-black,
-  "white": $foundation-white
 );
 
 $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
@@ -54,7 +53,6 @@ $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
 @mixin create-sd-colors($value, $name) {
   // define the pst variables, so that downstream user overrides will work
   --pst-color-#{$name}: #{$value};
-  @debug "created color 🌱";
   // we are now using a11y-combination to calculate the text color - this is based
   // on the WCAG color contrast guidelines
   --pst-color-#{$name}-text: #{a11y-combination($value)};
diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index ebb534bf5..9562b8264 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -78,6 +78,7 @@ $color-palette: (
     ),
   "foundation": (
     "white": #ffffff,
+    // gray-900
     "black": #14181e,
   )
 );
@@ -106,8 +107,12 @@ $foundation-white: #ffffff;
 // This is a custom - calculated  color between gray 100 and 200 - to reduce
 // the contrast ratio (avoid a jarring effect)
 $base-light-text: #ced6dd;
-// used in sphinx_design - grey 100
-$foundation-light-grey: #f3f4f5;
+// used in sphinx_design - gray 100
+$foundation-light-gray: #f3f4f5;
+// used in sphinx_design - gray 700
+$foundation-muted-gray: #29313d;
+// used in sphinx_design - gray 800
+$foundation-dark-gray: #222832;
 
 $pst-semantic-colors: (
   "primary": (
@@ -215,7 +220,7 @@ $pst-semantic-colors: (
   "on-surface":
     (
       "light": #{map-deep-get($color-palette, "gray", "800")},
-      "dark": $foundation-light-grey,
+      "dark": $foundation-light-gray,
     ),
 );
 

From 5d7ebf4c97e18819a1d0504f3fc8377839044e60 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 27 Mar 2023 20:22:15 +0100
Subject: [PATCH 39/64] Update styling

---
 docs/user_guide/styling.rst                   |  2 +-
 .../styles/extensions/_sphinx_design.scss     | 25 +++++++++++++------
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/docs/user_guide/styling.rst b/docs/user_guide/styling.rst
index d32180c15..70d10c7db 100644
--- a/docs/user_guide/styling.rst
+++ b/docs/user_guide/styling.rst
@@ -100,7 +100,7 @@ Here is an overview of the colors available in the theme (change theme mode to s
 .. raw:: html
 
     <style>
-      span.pst-primary {background-color: var(--pst-color-primary); color: #{a11y-combination(--pst-color-primary)}}
+      span.pst-primary {background-color: var(--pst-color-primary);
       span.pst-secondary {background-color: var(--pst-color-secondary);}
       span.pst-success {background-color: var(--pst-color-success);}
       span.pst-info {background-color: var(--pst-color-info);}
diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 4751230ce..af10d2fbf 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -72,18 +72,17 @@ $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
   html[data-theme="#{$mode}"] {
     // check if this color is defined differently for light/dark
     @each $name in $sd-semantic-color-names {
-      @debug "name: #{$name} ✨";
       $definition: map-get($all-colors, $name);
       @if type-of($definition) == map {
         @each $key, $value in $definition {
-          @debug "key: #{$key} value: #{$value} definition: #{$definition} ✨";
           @if str-index($key, $mode) != null {
             // since now we define the bg colours in the semantic colours and not
             // by changing opacity, we need to check if the key contains bg and the
             // correct mode (light/dark)
             @if str-index($key, "bg") != null {
-              @debug "bg color ✨ #{$value}";
               --sd-color-#{$name}-bg: #{$value};
+              $value: check-color($value);
+              --sd-color-#{$name}-bg-text: #{a11y-combination($value)};
             } @else {
               $value: check-color($value);
               @include create-sd-colors($value, $name);
@@ -91,9 +90,7 @@ $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
           }
         }
       } @else {
-        @debug "not a map ✨";
         $value: map-get($all-colors, $name);
-        @debug "value: #{$value} name: #{$name} ✨";
         @include create-sd-colors($value, $name);
       }
     }
@@ -173,6 +170,13 @@ html[data-theme="light"] {
 /*******************************************************************************
   * Dropdowns
   */
+
+@mixin dropdown-colors($name) {
+  --pst-sd-dropdown-color: var(--sd-color-#{$name});
+  --pst-sd-dropdown-bg-color: var(--sd-color-#{$name}-bg);
+  --pst-sd-dropdown-text-color: var(--sd-color-#{$name}-bg-text);
+}
+
 details.sd-dropdown {
   // Remove all borders to over-ride SD behavior, and we'll add our own later
   border: 0px !important;
@@ -182,7 +186,6 @@ details.sd-dropdown {
       border: 0;
     }
   }
-  // TODO: colour should match admonitions
   // Drop shadow should behave same as admonitions
   @include box-shadow();
 
@@ -205,24 +208,30 @@ details.sd-dropdown {
     @each $name in $sd-semantic-color-names {
       &.sd-bg-#{$name} {
         --pst-sd-dropdown-color: var(--sd-color-#{$name});
+        --pst-sd-dropdown-bg-color: var(--sd-color-#{$name}-bg);
         // Otherwise it won't be defined in the sibling element
         & + div.sd-summary-content {
           --pst-sd-dropdown-color: var(--sd-color-#{$name});
+          --pst-sd-dropdown-bg-color: var(--sd-color-#{$name}-bg);
         }
       }
+      &.sd-bg-text-#{$name} {
+        color: var(--sd-color-#{$name}-bg-text) !important;
+      }
     }
 
     // Background color and border are grey by default
     background-color: unset !important;
-    @include background-from-color-variable(--pst-sd-dropdown-color);
+    @include background-from-color-variable(--pst-sd-dropdown-bg-color);
 
     // Add a left border with the same structure as our admonitions
     border-left: 0.2rem solid var(--pst-sd-dropdown-color) !important;
     & + div.sd-summary-content {
       border-left: 0.2rem solid var(--pst-sd-dropdown-color) !important;
       border-bottom-left-radius: calc(0.25rem - 1px);
+      background-color: var(--pst-color-on-background);
     }
-    phi span.sd-summary-icon {
+    span.sd-summary-icon {
       display: inline-flex;
       align-items: center;
       color: var(--pst-sd-dropdown-color) !important;

From 5aed77ca0b19a4a841553c4b4b817cdc60785617 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 27 Mar 2023 20:25:27 +0100
Subject: [PATCH 40/64] Lint files

---
 .../assets/styles/abstracts/_mixins.scss              | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
index b964724ae..842e79b82 100644
--- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
+++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -189,14 +189,21 @@ $_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
   0.8714 0.8796 0.8879 0.8963 0.9047 0.9131 0.9216 0.9301 0.9387 0.9473 0.956
   0.9647 0.9734 0.9823 0.9911 1;
 
+/**
+* Get color combinations that meet a minimum contrast ratio as per WCAG 2
+*/
+// @param {color} $bg - Background color of the element
+// @param {color} optional $target-color-contrast-dark $target-color-contrast-light  - Target text colors, defaul to our
+// $foundation-black and $foundation-white colors
+// @return {color} $max-ratio-color - The color that has the highest contrast ratio
 @function a11y-combination(
   $bg,
   $target-color-contrast-dark: $foundation-black,
-  $target-color-contrast-white: $foundation-white,
+  $target-color-contrast-light: $foundation-white,
   $min-contrast-ratio: $min-contrast-ratio-4
 ) {
   // will test against the specified foreground colors
-  $foregrounds: $target-color-contrast-white, $target-color-contrast-dark;
+  $foregrounds: $target-color-contrast-light, $target-color-contrast-dark;
   $max-ratio: 0;
   $max-ratio-color: null;
 

From 7d350f9a11c506414a2834b63b1597d587f6dce7 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 27 Mar 2023 20:28:22 +0100
Subject: [PATCH 41/64] :heavy_minus_sign: Remove unused mixin

---
 .../assets/styles/extensions/_sphinx_design.scss       | 10 ++--------
 1 file changed, 2 insertions(+), 8 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 91a0be4af..ae2ffa1c9 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -168,14 +168,8 @@ html[data-theme="light"] {
 }
 
 /*******************************************************************************
-  * Dropdowns
-  */
-
-@mixin dropdown-colors($name) {
-  --pst-sd-dropdown-color: var(--sd-color-#{$name});
-  --pst-sd-dropdown-bg-color: var(--sd-color-#{$name}-bg);
-  --pst-sd-dropdown-text-color: var(--sd-color-#{$name}-bg-text);
-}
+* Dropdowns
+*/
 
 details.sd-dropdown {
   // Remove all borders to over-ride SD behavior, and we'll add our own later

From a3395c35ce02319a1907afd8e1c80917478c5d7a Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 28 Mar 2023 10:50:15 +0100
Subject: [PATCH 42/64] Fix issues introduced by merging main

---
 .../assets/styles/extensions/_sphinx_design.scss                | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index ae2ffa1c9..5350a2130 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -48,7 +48,7 @@ $extra-semantic-colors: (
   "black": $foundation-black,
 );
 
-$all-colors: map-merge(pstcol.$pst-semantic-colors, $extra-semantic-colors);
+$all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
 
 @mixin create-sd-colors($value, $name) {
   // define the pst variables, so that downstream user overrides will work

From 2deceacfbd99a9f2927080eeb2921f84c2fafebc Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 7 Apr 2023 12:02:31 +0100
Subject: [PATCH 43/64] Add dropdowns background

---
 docs/user_guide/web-components.rst            | 24 ++++++++++++++---
 .../assets/styles/abstracts/_mixins.scss      | 17 +++++++-----
 .../styles/extensions/_sphinx_design.scss     | 26 +++++++++++++++----
 3 files changed, 53 insertions(+), 14 deletions(-)

diff --git a/docs/user_guide/web-components.rst b/docs/user_guide/web-components.rst
index 7d8fae5dc..54bae0db5 100644
--- a/docs/user_guide/web-components.rst
+++ b/docs/user_guide/web-components.rst
@@ -78,6 +78,24 @@ Here are some of the available buttons, also using semantic colors:
 
             Muted
 
+    .. grid-item::
+
+        .. button-ref:: badges-buttons
+            :ref-type: ref
+            :color: light
+            :shadow:
+
+            Light
+
+    .. grid-item::
+
+        .. button-ref:: badges-buttons
+            :ref-type: ref
+            :color: dark
+            :shadow:
+
+            Dark
+
 If in your site's `custom CSS file <custom-css>`_ you override the `CSS custom properties <css-variables>`_ ``--pst-color-*`` (where ``*`` is one of the semantic color names, such as ``primary``, ``danger``), badges and buttons will automatically use the custom color.
 
 Cards
@@ -97,13 +115,13 @@ Cards
 
         Content of the third card.
 
-        :bdg-primary:`example`
+        :bdg-primary:`Sample badge`
 
 .. grid::
 
     .. grid-item-card:: A card with a dropdown menu
 
-        .. dropdown:: :fa:`eye me-1` third card
+        .. dropdown:: :fa:`eye me-1` Click to expand dropdown
 
             Hidden content
 
@@ -190,7 +208,7 @@ See `the Sphinx Design Dropdown documentation <https://sphinx-design.readthedocs
 
    And some content!
 
-.. dropdown:: With a title
+.. dropdown:: With a title and icon
    :icon: unlock
 
    And some content and an icon!
diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
index 842e79b82..a851aaa33 100644
--- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
+++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -1,11 +1,14 @@
 /*********************************************
 * SASS Mixins
 *********************************************/
-// @use "sass:color";
 /**
 * Scrollbars should be thinner and slightly rounded, with a grey background
 * ref: https://www.nngroup.com/articles/scrolling-and-scrollbars/
 */
+
+// loading the math module
+@use "sass:math";
+
 @mixin scrollbar-style() {
   &::-webkit-scrollbar {
     width: 0.5rem;
@@ -94,8 +97,10 @@
 
 /**
 * Function to check if the color needs converting to a "color" type
+* if it is a string we cannot use other color manipulation functions
 */
 // @param {String/Color} $color - Color definition from map
+// @return {Color} - Color type (in hex)
 @function check-color($color) {
   @if type-of($color) == string {
     $color: from-hex($color);
@@ -104,7 +109,7 @@
 }
 
 /**
-* Function to convert the string representation of a color to a color type
+* Function to convert the string representation of a color to a color type (hex)
 */
 // @param {String} $string - String representation of a color
 @function from-hex($string) {
@@ -227,9 +232,9 @@ $_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
 
   // return the relative contrast ratio
   @if $l1 > $l2 {
-    @return ($l1 + 0.05) / ($l2 + 0.05);
+    @return math.div(($l1 + 0.05), ($l2 + 0.05));
   } @else {
-    @return ($l2 + 0.05) / ($l1 + 0.05);
+    @return math.div(($l2 + 0.05), ($l1 + 0.05));
   }
 }
 
@@ -246,11 +251,11 @@ $_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
 
   @each $channel, $value in $rgb-col {
     // here we get RsRGB, GsRGB, and BsRGB
-    @if $value / 255 <=0.03928 {
+    @if math.div($value, 255) <=0.03928 {
       $rgb-col: map-merge(
         $rgb-col,
         (
-          $channel: $value / 255 / 12.92,
+          $channel: math.div(math.div($value, 255), 12.92),
         )
       );
     } @else {
diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 5350a2130..90b1d7afb 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -6,6 +6,8 @@
  * same for our overrides to have any effect.
  */
 @use "../variables/color" as pst-color;
+@use "sass:meta";
+@use "sass:color";
 
 /*******************************************************************************
   * Color and variables
@@ -39,11 +41,22 @@ $sd-semantic-color-names: (
   * First, define the extra keys needed to cover the full range of semantic
   * color names used in sphinx-design, then merge them with the names we
   * already define for our own needs.
+  * see https://sphinx-design.readthedocs.io/en/latest/css_variables.html
   */
 $extra-semantic-colors: (
   "white": $foundation-white,
-  "light": $foundation-light-gray,
-  "muted": $foundation-muted-gray,
+  "light": (
+    light: $foundation-light-gray,
+    bg-light: color.scale($foundation-light-gray, $lightness: 30%),
+    dark: $foundation-light-gray,
+    bg-dark: color.scale($foundation-light-gray, $lightness: -30%),
+  ),
+  "muted": (
+    light: $foundation-muted-gray,
+    bg-light: color.scale($foundation-muted-gray, $lightness: 30%),
+    dark: $foundation-light-gray,
+    bg-dark: color.scale($foundation-muted-gray, $lightness: -30%),
+  ),
   "dark": $foundation-dark-gray,
   "black": $foundation-black,
 );
@@ -61,8 +74,6 @@ $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
   // override the sphinx-design variables
   --sd-color-#{$name}: var(--pst-color-#{$name});
   --sd-color-#{$name}-text: var(--pst-color-#{$name}-text);
-  // adding bg colors - needed for dropdowns
-  // --sd-color-#{$name}-bg: var(--pst-color-#{$name});
   // TODO: check where highlight is used
   --sd-color-#{$name}-highlight: var(--pst-color-#{$name}-highlight);
 }
@@ -81,6 +92,8 @@ $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
             // correct mode (light/dark)
             @if str-index($key, "bg") != null {
               --sd-color-#{$name}-bg: #{$value};
+              // create local variable
+              $bg-var: --sd-color-#{$name}-bg;
               $value: check-color($value);
               --sd-color-#{$name}-bg-text: #{a11y-combination($value)};
             } @else {
@@ -123,6 +136,7 @@ html[data-theme="light"] {
 .bd-content .sd-card {
   border: 1px solid var(--pst-color-border);
 
+  // TODO - --pst-color-panel-background is not defined... where is this coming from?
   .sd-card-header {
     background-color: var(--pst-color-panel-background);
     border-bottom: 1px solid var(--pst-color-border);
@@ -148,7 +162,7 @@ html[data-theme="light"] {
       color: var(--pst-color-primary);
     }
 
-    // hover label
+    // Hover label
     &:not(:checked) + label:hover {
       border-color: var(--pst-color-secondary);
       color: var(--pst-color-secondary);
@@ -196,6 +210,7 @@ details.sd-dropdown {
     // We must set this in the current and content sibling container
     // so that it is defined in both places
     --pst-sd-dropdown-color: var(--sd-color-card-border);
+    --pst-sd-dropdown-bg-color: var(--pst-color-surface);
     & + div.sd-summary-content {
       --pst-sd-dropdown-color: var(--sd-color-card-border);
     }
@@ -210,6 +225,7 @@ details.sd-dropdown {
         }
       }
       &.sd-bg-text-#{$name} {
+        // Use the WCAG conformant text color
         color: var(--sd-color-#{$name}-bg-text) !important;
       }
     }

From cd3d67a8a80af4a391181255c52317abc3fdba1e Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 7 Apr 2023 14:36:36 +0100
Subject: [PATCH 44/64] :memo: Update docs

---
 docs/user_guide/branding.rst                          | 11 ++++++-----
 docs/user_guide/indices.rst                           |  4 ++--
 src/pydata_sphinx_theme/assets/styles/base/_base.scss |  2 +-
 .../assets/styles/content/_code.scss                  |  3 +++
 .../assets/styles/variables/_color.scss               |  5 +++++
 5 files changed, 17 insertions(+), 8 deletions(-)

diff --git a/docs/user_guide/branding.rst b/docs/user_guide/branding.rst
index a5145e1bb..64e0f9ab4 100644
--- a/docs/user_guide/branding.rst
+++ b/docs/user_guide/branding.rst
@@ -5,7 +5,7 @@ Branding and logo
 Customize logo and title
 ========================
 
-By default the theme will use the value of ``project`` on the left side of the header navbar.
+By default, the theme will use the value of ``project`` on the left side of the header navbar.
 This can be replaced by a logo image, and optionally a custom ``html_title`` as well.
 
 Single logo for light and dark mode
@@ -80,9 +80,10 @@ To reference an external website, make sure your link starts with ``http``:
 Customize logo alternative text
 -------------------------------
 
-You may set a custom ``alt text`` to use with your logo to replace the default ("logo image").
-This can make the logo more accessible to those using screen readers or other assistive tech.
-To do so, use ``html_teme_options["logo"]["alt_text"]`` as in the following example:
+You may set a custom ``alt text`` for your logo to replace the default ``"logo image"`` generic description.
+Adding a descriptive ``alt text`` can help make your documentation more accessible to readers using screen readers or other assistive tech.
+
+To do so, customize the ``html_teme_options["logo"]["alt_text"]`` configuration option as in the following example:
 
 .. code-block:: python
    :caption: conf.py
@@ -96,7 +97,7 @@ To do so, use ``html_teme_options["logo"]["alt_text"]`` as in the following exam
 Add a logo title
 ----------------
 
-To add a title in the brand section of your documentation, define a value for ``html_theme_options.logo["text"]``
+To add a title in the brand section of your documentation, define a value for ``html_theme_options.logo["text"]``.
 This will appear just after your logo image if it is set.
 
 .. code-block:: python
diff --git a/docs/user_guide/indices.rst b/docs/user_guide/indices.rst
index bc5be4e01..6bbb9c279 100644
--- a/docs/user_guide/indices.rst
+++ b/docs/user_guide/indices.rst
@@ -2,7 +2,7 @@
 Sphinx indices
 ==============
 
-Sphinx generates indices named `genindex`, `modindex` and `py-modindex` when building a documentation. More information about them can be found in the Sphinx documentation `here <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-index>`__.
+Sphinx generates indices named `genindex`, `modindex` and `py-modindex` when building a documentation. More information about them can be found in the `Sphinx documentation for indices <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-index>`__.
 
 Add indices links
 =================
@@ -19,4 +19,4 @@ By design the indices pages are not linked in a documentation generated with thi
 
 .. note::
 
-    don't forget to add back the ``"sidebar-ethical-ads.html"`` template if you are serving your documentation using `ReadTheDocs <https://readthedocs.org>`__.
+    Don't forget to add back the ``"sidebar-ethical-ads.html"`` template if you are serving your documentation using `ReadTheDocs <https://readthedocs.org>`__.
diff --git a/src/pydata_sphinx_theme/assets/styles/base/_base.scss b/src/pydata_sphinx_theme/assets/styles/base/_base.scss
index fe9c96e92..114db54a7 100644
--- a/src/pydata_sphinx_theme/assets/styles/base/_base.scss
+++ b/src/pydata_sphinx_theme/assets/styles/base/_base.scss
@@ -50,7 +50,7 @@ a {
 
   &.headerlink {
     color: var(--pst-color-secondary);
-    opacity: 0.6;
+    opacity: 0.7;
     font-size: 0.8em;
     padding: 0 4px 0 4px;
     margin-left: 0.2em;
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_code.scss b/src/pydata_sphinx_theme/assets/styles/content/_code.scss
index 78792b0d1..e1b8d9120 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_code.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_code.scss
@@ -53,4 +53,7 @@ code.literal {
   background-color: var(--pst-color-surface);
   border: 1px solid var(--pst-color-border);
   border-radius: 0.25rem;
+  a {
+    color: var(--pst-color-inline-code-links);
+  }
 }
diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index e32c69d67..dcdf32aa8 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -193,6 +193,11 @@ $pst-semantic-colors: (
     "light": #{map-deep-get($color-palette, "pink", "600")},
     "dark": #{map-deep-get($color-palette, "pink", "300")},
   ),
+  "inline-code-links": (
+    // need to make sure there is enough contrast agains the code bg
+    "light": #{map-deep-get($color-palette, "teal", "700")},
+    "dark": #{map-deep-get($color-palette, "teal", "300")},
+  ),
   "target": (
     "light": #8b6e31,
     "dark": #c79d41,

From a855f97a4baf16418e2d55dc4c9f3ed26892f832 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 13 Apr 2023 18:59:40 +0100
Subject: [PATCH 45/64] :pencil2: Fix grammar and spelling

---
 docs/community/contributors.md         |  2 +-
 docs/community/practices/merge.md      | 14 +++++-----
 docs/community/practices/release.md    |  2 +-
 docs/community/practices/versions.md   | 10 +++----
 docs/community/setup.md                | 12 ++++-----
 docs/community/topics/accessibility.md |  4 +--
 docs/community/topics/assets.md        |  8 +++---
 docs/community/topics/bootstrap.rst    |  8 +++---
 docs/community/topics/config.md        |  2 +-
 docs/community/topics/manual-dev.md    |  4 +--
 docs/user_guide/ablog.md               |  4 +--
 docs/user_guide/accessibility.rst      | 36 ++++++++++++++------------
 docs/user_guide/analytics.rst          |  8 +++---
 docs/user_guide/announcements.rst      |  2 +-
 docs/user_guide/branding.rst           | 11 ++++----
 docs/user_guide/fonts.rst              | 10 +++----
 docs/user_guide/header-links.rst       | 14 +++++-----
 docs/user_guide/layout.rst             | 30 ++++++++++-----------
 docs/user_guide/light-dark.rst         | 10 +++----
 docs/user_guide/navigation.rst         |  8 +++---
 docs/user_guide/page-toc.rst           |  4 +--
 docs/user_guide/search.rst             |  8 +++---
 docs/user_guide/static_assets.md       | 12 ++++-----
 docs/user_guide/styling.rst            | 36 ++++++++++++++------------
 docs/user_guide/theme-elements.md      | 19 +++++++-------
 docs/user_guide/version-dropdown.rst   | 16 ++++++------
 26 files changed, 150 insertions(+), 144 deletions(-)

diff --git a/docs/community/contributors.md b/docs/community/contributors.md
index c89ea336a..e9bd63555 100644
--- a/docs/community/contributors.md
+++ b/docs/community/contributors.md
@@ -17,4 +17,4 @@ Support and development for this theme has been funded by one [NumFocus Small De
 
 ## Theme logo
 
-Thanks to [@drammock](https://github.com/drammock) for initial design of the theme logo.
+Thanks to [@drammock](https://github.com/drammock) for the initial design of the theme logo.
diff --git a/docs/community/practices/merge.md b/docs/community/practices/merge.md
index 8bb91e9fe..03effa8ae 100644
--- a/docs/community/practices/merge.md
+++ b/docs/community/practices/merge.md
@@ -1,20 +1,20 @@
 # Merge and review policy
 
 Our policy for merging and reviewing describes how we review one another's work, and when we allow others to merge changes into our main codebase.
-It tries to balance between a few goals:
+It tries to balance a few goals:
 
 - Iterate on PRs and merge them relatively quickly, so that we reduce the debt associated with long-lasting PRs.
 - Give enough time for others to provide their input and guide the PR itself, and to ensure that we aren't creating a problem with the PR.
 - Value iterative improvement over creating the perfect Pull Request, so that we do not burden contributors with cumbersome discussion and minor revision requests.
 - Recognize that we all have limited time and resources, and so cannot guarantee a full quality assurance process each time.
-- Give general preference to the opinions from maintainers of projects in the PyData ecosystem, as a key stakeholder community of this theme.
+- Give general preference to the opinions of maintainers of projects in the PyData ecosystem, as a key stakeholder community of this theme.
 
-We follow these guidelines in order to achieve these goals:
+We follow these guidelines to achieve these goals:
 
 - Assume that all maintainers are acting in good faith and will use their best judgment to make decisions in the best interests of the repository.
-- We can and will make mistakes, and so encourage best practices in testing and documentation to guard against this.
-- It's important to share information, so give a best effort at telling others about work that you're doing.
-- It's best to discuss and agree on important decisions at a high level before implementation, so give a best effort at providing time and invitation for others to provide feedback.
+- We can and will make mistakes, so encourage best practices in testing and documentation to guard against this.
+- It's important to share information, so give your best effort at telling others about the work that you're doing.
+- It's best to discuss and agree on important decisions at a high level before implementation, so give the best effort at providing time and invitation for others to provide feedback.
 
 ## Policy for moderate changes
 
@@ -35,7 +35,7 @@ They can be merged when the above conditions are met, and one of these things ha
 
 These are changes that significantly alter the experience of the user, or that add significant complexity to the codebase.
 
-All of the above, but PRs **must** have approval from at least one other core maintainer before merging.
+All the above, but PRs **must** have approval from at least one other core maintainer before merging.
 In addition, the PR author should put extra effort into ensuring that the relevant stakeholders are notified about a change, so they can gauge its impact and provide feedback.
 
 ## Policy For minor changes and bugfixes
diff --git a/docs/community/practices/release.md b/docs/community/practices/release.md
index 4ae1d8331..6b4617a40 100644
--- a/docs/community/practices/release.md
+++ b/docs/community/practices/release.md
@@ -5,7 +5,7 @@
 ## Our goals
 
 Our release policy describes how we decide when to make a new public release of the theme so that other projects may use new features and improvements.
-It tries to balance between these goals:
+It tries to balance these goals:
 
 - Release relatively frequently, so that we provide a continuous stream of improvement to projects that use the theme, and minimize the effort needed to upgrade.
 - Do not surprise people (especially with negative surprises) and provide time for projects to provide feedback about upcoming features.
diff --git a/docs/community/practices/versions.md b/docs/community/practices/versions.md
index c9202d965..917d08e2a 100644
--- a/docs/community/practices/versions.md
+++ b/docs/community/practices/versions.md
@@ -1,7 +1,7 @@
 # Supported Python and Sphinx versions
 
 Python and Sphinx are the two primary dependencies of this theme.
-We have special practices for deciding which versions of these we support (especially Sphinx, which tends to release breaking changes).
+We have particular practices for deciding which versions of these we support (especially Sphinx, which tends to release breaking changes).
 
 ## Supported Python versions
 
@@ -9,16 +9,16 @@ For releases of Python, we aim to follow this approach[^1]:
 
 > For a new major/minor release of this theme, we support any minor Python versions released in the last 3.5 years (42 months), as defined in [the EOL schedule for Python](https://endoflife.date/python)[^2].
 
-We define "support" as testing against each of these versions, so that users can be assured they will not trigger any bugs.
+We define "support" as testing against each of these versions so that users can be assured they will not trigger any bugs.
 
-For example, if we made a minor release tomorrow, we'd [look at the EOL schedule for Python](https://endoflife.date/python) and support all of the versions that fall within a 3.5 year window.
+For example, if we made a minor release tomorrow, we'd [look at the EOL schedule for Python](https://endoflife.date/python) and support all the versions that fall within a 3.5-year window.
 
 [^1]: Our support for Python versions is inspired by [NEP 029](https://numpy.org/neps/nep-0029-deprecation_policy.html).
-[^2]: These policies are goals, but not promises. We are a volunteer-led community with limited time. Consider these sections to be our intention, but we recognize that we may not always be able to meet these criteria if we do not have capacity to do so. We welcome contributions from others to help us more sustainably meet these goals!
+[^2]: These policies are goals, but no promises. We are a volunteer-led community with limited time. Consider these sections to be our intention, but we recognize that we may not always be able to meet these criteria if we cannot do so. We welcome contributions from others to help us more sustainably meet these goals!
 
 ## Supported Sphinx versions
 
-For supporting versions of Sphinx, we aim to follow this approach:
+For supported versions of Sphinx, we aim to follow this approach:
 
 > We support the latest released version of Sphinx that is **older than 6 months**.
 > We unofficially support earlier released versions of Sphinx, but may increase the lower-bound in our dependency pin without warning if needed[^2].
diff --git a/docs/community/setup.md b/docs/community/setup.md
index 3e732e14f..a6d23f3a3 100644
--- a/docs/community/setup.md
+++ b/docs/community/setup.md
@@ -18,7 +18,7 @@ of:
 For each pull request, the documentation is built and deployed to make it easier to review the changes in the PR.
 To access this, click on the {{ rtd }} preview in the CI/CD jobs.
 
-The sections below cover the steps to do this in more detail.
+The sections below cover the steps to take in more detail.
 
 ## Clone the repository
 
@@ -39,11 +39,11 @@ You can clone it for local development like so:
 Building a Sphinx site uses a combination of Python and Jinja to manage HTML, SCSS, and Javascript.
 To simplify this process, we use a few helper tools:
 
-- [The Sphinx Theme Builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) to automatically perform compilation of web assets.
+- [The Sphinx [Theme Builder](https://sphinx-theme-builder.readthedocs.io/en/latest/) automatically perform the compilation of web assets.
 - [pre-commit](https://pre-commit.com/) for automatically enforcing code standards and quality checks before commits.
 - [nox](https://nox.thea.codes/), for automating common development tasks.
 
-In particular, `nox` can be used to automatically create isolated local development environments with all of the correct packages installed to work on the theme.
+In particular, `nox` can be used to automatically create isolated local development environments with all the correct packages installed to work on the theme.
 The rest of this guide focuses on using `nox` to start with a basic environment.
 
 ```{seealso}
@@ -58,9 +58,9 @@ To start, install `nox`:
 $ pip install nox
 ```
 
-You can call `nox` from the command line in order to perform common actions that are needed in building the theme.
-`nox` operates with isolated environments, so each action has its own packages installed in a local directory (`.nox`).
-For common development actions, you'll simply need to use `nox` and won't need to set up any other packages.
+You can call `nox` from the command line to perform common actions that are needed in building the theme.
+`nox` operates with isolated environments, so each action has its packages installed in a local directory (`.nox`).
+For common development actions, you'll only need to use `nox` and won't need to set up any other packages.
 
 ### Setup `pre-commit`
 
diff --git a/docs/community/topics/accessibility.md b/docs/community/topics/accessibility.md
index 5bff788de..ad0307bf1 100644
--- a/docs/community/topics/accessibility.md
+++ b/docs/community/topics/accessibility.md
@@ -1,11 +1,11 @@
 # Accessibility checks
 
-The accessibility checking tools can find a number of common HTML patterns which
+The accessibility checking tools can find several common HTML patterns which
 assistive technology can't help users understand.
 We run a [Lighthouse](https://developers.google.com/web/tools/lighthouse) job in our CI/CD, which generates a "score" for all pages in our **Kitchen Sink** example documentation.
 The configuration for Lighthouse is in:
 
 - `.github/workflows/lighthouserc.json`
 
-For more information about configuring lighthouse, see [the lighthouse documentation](https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/configuration.md).
+For more information about configuring Lighthouse, see [the lighthouse documentation](https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/configuration.md).
 For more information about Accessibility in general, see [](../../user_guide/accessibility.rst).
diff --git a/docs/community/topics/assets.md b/docs/community/topics/assets.md
index fa2c9e9cd..c893c6348 100644
--- a/docs/community/topics/assets.md
+++ b/docs/community/topics/assets.md
@@ -38,7 +38,7 @@ This is configured in the `webpack.config.js` file, and imported in the respecti
 ## FontAwesome icons
 
 Three "styles" of the [FontAwesome 6 Free](https://fontawesome.com/icons?m=free)
-icon font are used for {ref}`icon links <icon-links>` and admonitions, and is
+icon font are used for {ref}`icon links <icon-links>` and admonitions and is
 the only `vendored` font.
 
 - It is managed as a dependency in `package.json`
@@ -50,7 +50,7 @@ the only `vendored` font.
 
 Our Webpack build generates a collection of [Jinja macros](https://jinja.palletsprojects.com/en/3.0.x/templates/#macros) in the `static/webpack-macros.html` file.
 
-These macros are imported in the main `layout.html` file, and then inserted at various places in the page to link the static assets.
+These macros are imported in the main `layout.html` file, and then inserted at various places on the page to link the static assets.
 
-Some of the assets [are "preloaded"](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/preload), meaning that the browser begins requesting these resources before they're actually needed.
-In particular, our JavaScript assets are preloaded in `<head>`, and the scripts are actually loaded at the end of `<body>`.
+Some assets [are "preloaded"](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types/preload), meaning that the browser begins requesting these resources before they're needed.
+In particular, our JavaScript assets are preloaded in `<head>`, and the scripts are loaded at the end of `<body>`.
diff --git a/docs/community/topics/bootstrap.rst b/docs/community/topics/bootstrap.rst
index 58b548a10..3a61ef249 100644
--- a/docs/community/topics/bootstrap.rst
+++ b/docs/community/topics/bootstrap.rst
@@ -10,16 +10,16 @@ Dropping **JQuery**
 Bootstrap Dropped its **JQuery** dependency and rewrote plugins to be in regular JavaScript.
 Sphinx *v6* will do the same (https://github.com/sphinx-doc/sphinx/issues/10070).
 As a consequence, we also rewrote all our javascript to only use vanilla **JavaScript**.
-Any documentation relying on **JQuery** in their ``custom.js`` files will need to rewrite it or specifically import **JQuery**.
+Any documentation relying on **JQuery** in their ``custom.js`` files will need to rewrite or specifically import **JQuery**.
 
 Breaking changes
 ----------------
 
 ‼️ Relevant for those using a ``custom.css`` and/or a ``custom.js`` file!
 
-Bootstrap changed a number of CSS classes, so if you wrote custom rules of JS logic that depended on them, it may have changed.
+Bootstrap changed several CSS classes, so if you wrote custom rules of JS logic that depended on them, it may have changed.
 
-All of the changes from *v4* to *v5* are `listed in their documentation <https://getbootstrap.com/docs/5.0/migration/>`_.
+All the changes from *v4* to *v5* are `listed in their documentation <https://getbootstrap.com/docs/5.0/migration/>`_.
 Below list the ones that had consequences on ``pydata-sphinx-theme`` components.
 
 Sass
@@ -57,4 +57,4 @@ Utilities
 JavaScript
 ^^^^^^^^^^
 
--   Data attributes for all JavaScript plugins are now namespaced to help distinguish Bootstrap functionality from third parties and your own code. For example, we use ``data-bs-toggle`` instead of ``data-toggle``.
+-   Data attributes for all JavaScript plugins are now name spaced to help distinguish Bootstrap functionality from third parties and your code. For example, we use ``data-bs-toggle`` instead of ``data-toggle``.
diff --git a/docs/community/topics/config.md b/docs/community/topics/config.md
index 1f3323d0d..a78725470 100644
--- a/docs/community/topics/config.md
+++ b/docs/community/topics/config.md
@@ -8,7 +8,7 @@ Here are some tips to do this the "right" way in Sphinx.
 ## Update config: use `app.config`
 
 For example, `app.config.foo = "bar"`.
-For some reason, when Sphinx sets things it directly uses `__dict__` but this doesn't seem to be different from the pattern described here.
+For some reason, when Sphinx sets things it directly uses `__dict__`, but this doesn't seem to be different from the pattern described here.
 
 ## Update theme options: use `app.builder.theme_options`
 
diff --git a/docs/community/topics/manual-dev.md b/docs/community/topics/manual-dev.md
index 6736f1636..35964d5cc 100644
--- a/docs/community/topics/manual-dev.md
+++ b/docs/community/topics/manual-dev.md
@@ -51,7 +51,7 @@ $ sphinx-build docs docs/_build/html
 
 ## Compile web assets (JS/CSS)
 
-To compile the javascript and CSS assets for the theme, run the following command:
+To compile the JavaScript and CSS assets for the theme, run the following command:
 
 ```console
 $ stb compile
@@ -59,7 +59,7 @@ $ stb compile
 
 This will compile everything in the `src/pydata_sphinx_theme/assets` folder and place them in the appropriate places in our theme's folder structure.
 
-## Start a live-server to build and serve your documentation
+## Start a live server to build and serve your documentation
 
 To manually open a server to watch your documentation for changes, build them, and display them locally in a browser, run this command:
 
diff --git a/docs/user_guide/ablog.md b/docs/user_guide/ablog.md
index 327b88c0f..19797b8e5 100644
--- a/docs/user_guide/ablog.md
+++ b/docs/user_guide/ablog.md
@@ -1,13 +1,13 @@
 # Blogs with `ABlog`
 
 The [ABlog extension](https://ablog.readthedocs.io/) allows you to tag pages as **blog posts** and additionally include them in landing pages for your blog.
-It also has a number of sidebar templates to show off collections of your posts.
+It also has several sidebar templates to show off collections of your posts.
 
 :::{admonition} Minimum version ABlog v0.11.0
 Make sure you have `ABlog>=0.11.0rc2` in your dependencies.
 :::
 
-This theme has styling support for ABlog, and demonstrates some of its functionality here.
+This theme has styling support for ABlog and demonstrates some of its functionality here.
 
 ## Example blog
 
diff --git a/docs/user_guide/accessibility.rst b/docs/user_guide/accessibility.rst
index a39b7f778..09e616fba 100644
--- a/docs/user_guide/accessibility.rst
+++ b/docs/user_guide/accessibility.rst
@@ -2,7 +2,7 @@
 
 .. meta::
     :description lang=en:
-        The features and plans for addressing accessibility concerns on pydata-sphinx-theme
+        The features and plans for addressing accessibility concerns on the PyData Sphinx Theme.
 
 *************
 Accessibility
@@ -10,8 +10,8 @@ Accessibility
 
 Creating and publishing content that does not exclude disabled users is a complex and iterative task.
 
-While there is no one-size-fits-all solution to maintaining accessible content, this
-theme and documentation site use some techniques to avoid common content shortcomings.
+While there is no one-size-fits-all solution to maintaining accessible content, the PyData Sphinx Theme
+and this documentation site use some techniques to avoid common content shortcomings.
 
 .. Note::
 
@@ -26,7 +26,7 @@ Metadata
 ========
 
 Several of our documentation pages contain metadata (i.e., ``.. meta::`` directives
-in reStructuredText) giving brief summaries of the page contents. If you notice a
+in reStructuredText) giving summaries of the page contents. If you notice a
 page that lacks metadata, please open a pull request to add it!
 
 
@@ -41,8 +41,8 @@ Colors
 * We recently revisited the PyData Sphinx theme color palette to ensure that
   the colors we use meet WCAG 2 AA or AAA contrast requirements.
 * We also re-defined our ``primary`` and ``secondary`` colors to be more accessible and distinct from semantic colors used
-  to denote success, warning, info, and danger situations.
-* We simplified the color palette and removed some colors that were problematic to meet WCAG 2 AA or AAA contrast requirements
+  to denote success, warning, info, and danger contexts or information.
+* We simplified the color palette and removed some colors that were problematic to meeting WCAG 2 AA or AAA contrast requirements
   and for certain types of colorblindness.
 * We have improved how we assign text colors to interactive elements such as buttons and dropdowns to ensure that they meet
   WCAG 2 AA or AAA contrast requirements.
@@ -53,7 +53,7 @@ What You Can Do
 Site configuration
 ==================
 
-The following sections include recommendations for settings in the ``conf.py`` file can positively impact the
+The following sections include recommendations for settings in the ``conf.py`` file that can positively impact the
 accessibility of content generated by this theme, and Sphinx in general.
 
 
@@ -66,9 +66,9 @@ identify if the content is in a language the reader understands.
 
 .. Hint::
 
-    Specifying a ``language`` will propagate to the top-level `html` tag.
+    Specifying a ``language`` will propagate to the top-level `HTML` tag.
 
-    .. code-block:: python
+    .. code-block:: Python
 
         language = "en"
 
@@ -81,7 +81,7 @@ approach to telling programs like search engines and assistive technologies wher
 different content appears on a website.
 
 If using a service like `ReadTheDocs <https://readthedocs.com>`__, these files
-will be created for you *automatically*, but for some of the other approaches below,
+will be created for you *automatically*, but for some other approaches below,
 it's handy to generate a `sitemap.xml` locally or in CI with a tool like
 `sphinx-sitemap <https://pypi.org/project/sphinx-sitemap/>`__.
 
@@ -102,7 +102,7 @@ it's handy to generate a `sitemap.xml` locally or in CI with a tool like
 Logo best practices
 --------------------
 
-If you use both light and dark themes, it's best to provide a logo that works well in both, or to provide and alternate for the dark theme.
+If you use both light and dark themes, it's best to provide a logo that works well in both or to provide an alternative for the dark theme.
 If you have a logo, you can add alt-text to it by adding the following to your
 ``conf.py``:
 
@@ -130,7 +130,7 @@ Built-in tools
 Most major browsers, including `Firefox <https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector>`__
 and `Chrome <https://developers.google.com/web/tools/chrome-devtools/accessibility/reference>`__
 include significant accessibility tooling in their development experience. Exploring
-these, and the modes they offer, can help to quickly pinpoint issues, and often
+these, and the modes they offer can help to quickly pinpoint issues and often
 include links to standards.
 
 
@@ -138,8 +138,8 @@ tota11y
 -------
 
 `tota11y <https://khan.github.io/tota11y/#Installation>`__ is an open source
-"bookmarklet" which modifies the currently-loaded page in-place, and highlights
-a number of accessibility issues.
+"bookmarklet" which modifies the currently-loaded page in place, and highlights
+several accessibility issues.
 
 
 WAVE
@@ -149,13 +149,15 @@ WAVE
 browser extension which can highlight multiple issues.
 
 .. Warning::
-  Note that automated testing and extensions such as the mentioned above will at best catch 30-40% of accessibility issues. They are not a replacement for manual testing and having a perfect score on either of these tools does not mean your site is accessible but instead signal that it follows some accessibility best practices.
+  Note that automated testing and extensions such as the ones mentioned above will at best catch 30-40% of accessibility issues.
+  They are not a replacement for manual testing and having a perfect score on any of these tools does not mean that
+  the site can be used by disabled users but instead signals that it follows some accessibility best practices.
 
 In Continuous Integration
 =========================
 
-A number of automated tools are available for assessing *glaring* accessibility
-issues across a number of pages at once, usually with many configurable options.
+Several automated tools are available for assessing *glaring* accessibility
+issues across some pages at once, usually with many configurable options.
 
 
 Lighthouse
diff --git a/docs/user_guide/analytics.rst b/docs/user_guide/analytics.rst
index c6ae09aa1..a6e2695f5 100644
--- a/docs/user_guide/analytics.rst
+++ b/docs/user_guide/analytics.rst
@@ -13,7 +13,7 @@ options depending on the analytics provider that you want to use.
        "analytics": analytics_options,
    }
 
-Generally speaking we recommend using Plausible over Google Analytics because
+Generally speaking, we recommend using Plausible over Google Analytics because
 it has a better story around user security and privacy. In addition, it is more
 open-source and transparent. In fact,
 `you can self-host a Plausible server <https://www.elvisduru.com/blog/how-to-self-host-plausible-analytics>`__.
@@ -36,7 +36,7 @@ and privacy-friendly analytics for the site. To configure, you will need to prov
 - A URL pointing to the JavaScript analytics script that is served by your Plausible server
 - A domain that reflects where your documentation lives
 
-Plausible's javascript will be included in all html pages to gather metrics.
+Plausible's JavaScript will be included in all HTML pages to gather metrics.
 The dashboard with analytics results will be accessible at ``https://<plausible-url>/<my-domain>``.
 
 .. code:: python
@@ -56,9 +56,9 @@ Google Analytics
 ================
 
 If the ``google_analytics_id`` config option is specified (like ``G-XXXXXXXXXX``),
-Google Analytics' javascript is included in the html pages.
+Google Analytics' JavaScript is included in the HTML pages.
 
-.. code:: python
+.. code:: Python
 
    html_theme_options["analytics"] = {
        "google_analytics_id": "G-XXXXXXXXXX",
diff --git a/docs/user_guide/announcements.rst b/docs/user_guide/announcements.rst
index 9bb23e273..2d71417d9 100644
--- a/docs/user_guide/announcements.rst
+++ b/docs/user_guide/announcements.rst
@@ -2,7 +2,7 @@ Announcement banners
 ====================
 
 You can add an announcement banner that draws extra attention from your reader.
-It will be displayed at the top of the screen, but will disappear once they start scrolling.
+It will be displayed at the top of the screen but will disappear once they start scrolling.
 
 To add an announcement banner, use the ``html_theme_options["announcement"]`` configuration.
 There are two ways to use this.
diff --git a/docs/user_guide/branding.rst b/docs/user_guide/branding.rst
index 64e0f9ab4..2154b67dd 100644
--- a/docs/user_guide/branding.rst
+++ b/docs/user_guide/branding.rst
@@ -5,7 +5,7 @@ Branding and logo
 Customize logo and title
 ========================
 
-By default, the theme will use the value of ``project`` on the left side of the header navbar.
+By default, the theme will use the value of ``project`` on the left side of the header navigation bar.
 This can be replaced by a logo image, and optionally a custom ``html_title`` as well.
 
 Single logo for light and dark mode
@@ -81,7 +81,7 @@ Customize logo alternative text
 -------------------------------
 
 You may set a custom ``alt text`` for your logo to replace the default ``"logo image"`` generic description.
-Adding a descriptive ``alt text`` can help make your documentation more accessible to readers using screen readers or other assistive tech.
+Adding a descriptive ``alt text`` can help make your documentation more accessible to readers using screen readers or another assistive tech.
 
 To do so, customize the ``html_teme_options["logo"]["alt_text"]`` configuration option as in the following example:
 
@@ -98,7 +98,7 @@ Add a logo title
 ----------------
 
 To add a title in the brand section of your documentation, define a value for ``html_theme_options.logo["text"]``.
-This will appear just after your logo image if it is set.
+This title will appear next to the logo image if set.
 
 .. code-block:: python
 
@@ -116,12 +116,13 @@ Add favicons
 
 .. deprecated:: 0.15
 
-   Support for complex and multiple favicons will be dropped in version 0.15. Instead use the `sphinx-favicon <https://sphinx-favicon.readthedocs.io/en/stable/>`__ extension. It provides the same functionality using more flexible parameters.
+   Support for complex and multiple favicons will be dropped in version 0.15. Instead, use the `sphinx-favicon <https://sphinx-favicon.readthedocs.io/en/stable/>`__ extension.
+   It provides the same functionality using more flexible parameters.
 
 
 ``pydata_sphinx_theme`` supports the `standard sphinx favicon configuration <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_favicon>`_, using ``html_favicon``.
 
-Additionally you may add any number of browser- or device-specific favicons of any size.
+Additionally, you may add any number of browser- or device-specific favicons of any size.
 To do so, use the ``html_theme_options["favicons"]`` configuration key.
 The only required argument is ``href``, which can be either an absolute URL (beginning with ``http``) or a local path relative to your ``html_static_path``.
 In addition, you may specify a size with ``sizes``, specify a ``rel`` value, and specify a ``color``.
diff --git a/docs/user_guide/fonts.rst b/docs/user_guide/fonts.rst
index 0d3564a92..0b36f3f94 100644
--- a/docs/user_guide/fonts.rst
+++ b/docs/user_guide/fonts.rst
@@ -4,14 +4,14 @@ Fonts and FontAwesome
 The theme includes the `FontAwesome 6 Free <https://fontawesome.com/icons?m=free>`__
 icon font (the ``.fa-solid, .fa-regular, .fa-brands`` styles, which are used for
 :ref:`icon links <icon-links>` and admonitions).
-This is the only *vendored* font, and otherwise the theme by default relies on
+This is the only *vendored* font, and otherwise, the theme by default relies on
 available system fonts for normal body text and headers.
 
 The default body and header fonts can be changed as follows:
 
-- Using :ref:`custom-css`, you can specify which fonts to use for body, header
-  and monospace text. For example, the following can be added to a custom
-  css file:
+- Using:ref:`custom-css`, you can specify which fonts to use for the body, header,
+  and monospaced text. For example, the following can be added to a custom
+  CSS file:
 
   .. code-block:: css
 
@@ -21,7 +21,7 @@ The default body and header fonts can be changed as follows:
           --pst-font-family-monospace: Courier, var(--pst-font-family-monospace-system);
       }
 
-  The ``*-system`` variables are available to use as fallback to the default fonts.
+  The ``*-system`` variables are available to use as a fallback to the default fonts.
 
 - If the font you want to specify in the section above is not generally available
   by default, you will additionally need to ensure the font is loaded.
diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst
index 95f302c07..482267d3b 100644
--- a/docs/user_guide/header-links.rst
+++ b/docs/user_guide/header-links.rst
@@ -9,7 +9,7 @@ Navigation Bar External links
 =============================
 
 You can add external links to your navigation bar. These will show up to the right
-of your site's main links, and will have a small icon indicating that they point to
+of your site's main links and will have a small icon indicating that they point to
 an external site. You can add external links to the nav bar like so:
 
 .. code:: python
@@ -27,7 +27,7 @@ Navigation bar dropdown links
 
 By default, this theme will display the first **five** navigation links in the header (including both top-level links and external links).
 It will place the remaining header links in a **dropdown menu** titled "More".
-This prevents the header links from taking up so much space that they crowd out the UI components or spill off screen.
+This prevents the header links from taking up so much space that they crowd out the UI components or spill off-screen.
 
 To control how many header links are displayed before being placed in the dropdown, use the ``header_links_before_dropdown`` theme configuration variable.
 For example, to change the number of displayed header links to be ``4`` instead of ``5``:abbr:
@@ -84,7 +84,7 @@ FontAwesome icons
 
 `FontAwesome <https://fontawesome.com/>`_ is a collection of icons that are
 commonly used in websites. They include both generic shape icons (e.g., "arrow-down"),
-as well as brand-specific icons (e.g. "github").
+and brand-specific icons (e.g. "GitHub").
 
 You can use FontAwesome icons by specifying ``"type": "fontawesome"``, and
 specifying a FontAwesome class in the ``icon`` value.
@@ -116,7 +116,7 @@ Here are several examples:
                "name": "Twitter",
                "url": "https://twitter.com/<your-handle>",
                "icon": "fa-brands fa-square-twitter",
-               # The default for `type` is `fontawesome` so it is not actually required in any of the above examples as it is shown here
+               # The default for `type` is `fontawesome`, so it is not required in any of the above examples as it shown here
            },
            {
                "name": "Mastodon",
@@ -215,7 +215,7 @@ You can add custom attributes to the link element (``<a>``) of your icon links.
 This is helpful if you need to add custom link behavior.
 To do so, use the pattern ``"attributes": {"attribute1": "value1"}`` in a given icon link entry.
 
-For example, to specify a custom ``target`` and ``rel`` attribute, and to define your own custom link classes:
+For example, to specify a custom ``target`` and ``rel`` attribute, and to define your custom link classes:
 
 .. code:: python
 
@@ -228,7 +228,7 @@ For example, to specify a custom ``target`` and ``rel`` attribute, and to define
                "icon": "_static/pydata-logo-square.png",
                "type": "local",
                # Add additional attributes to the href link.
-               # The defaults of target, rel, class, title and href may be overwritten.
+               # The defaults of the target, rel, class, title, and href may be overwritten.
                "attributes": {
                   "target" : "_blank",
                   "rel" : "noopener me",
@@ -240,4 +240,4 @@ For example, to specify a custom ``target`` and ``rel`` attribute, and to define
    }
 
 .. warning::
-   This might make your icon links behave unexpectedly and might over-ride default behavior, so make sure you know what you're doing!
+   This might make your icon links behave unexpectedly and might override the default behavior, so make sure you know what you're doing!
diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst
index 4c1da75fa..b4eafb424 100644
--- a/docs/user_guide/layout.rst
+++ b/docs/user_guide/layout.rst
@@ -11,7 +11,7 @@ Overview of theme layout
 Below is a brief overview of the major layout of this theme.
 Take a look at the diagram to understand what the major sections are called.
 Where you can insert component templates in ``html_theme_options``, we include the variable name ``in inline code``.
-Click on section titles to learn more about them and some basic layout configuration.
+Click on section titles to learn more about them and some basic layout configurations.
 
 .. The directives below generate a grid-like layout that mimics the structure of this theme.
 .. It uses Sphinx Design grids: https://sphinx-design.readthedocs.io/en/latest/grids.html
@@ -175,14 +175,14 @@ Click on section titles to learn more about them and some basic layout configura
 Horizontal spacing
 ------------------
 
-By default the theme's three columns have fixed widths.
+By default, the theme's three columns have fixed widths.
 The ``primary sidebar`` will snap to the left, the ``secondary sidebar`` will snap to the right, and the ``article content`` will be centered in between.
 
 - If one of the sidebars is not present, then the ``article content`` will be centered between the other sidebar and the side of the page.
 - If neither sidebar is present, the ``article content`` will be in the middle of the page.
 
 If you'd like the ``article content`` to take up more width than its default, use the ``max-width`` and ``flex-grow`` CSS variables with the ``.bd-content`` selector.
-For example, to make the content grow to fit all available width, add a custom CSS rule like:
+For example, to make the content grow to fit all available widths, add a custom CSS rule like:
 
 .. code-block:: css
 
@@ -195,8 +195,8 @@ Templates and components
 ========================
 
 There are a few major theme sections that you can customize to add/remove
-components, or add your own components. Each section is configured with a
-list of *html templates* — these are snippets of HTML that are inserted into
+components or add your components. Each section is configured with a
+list of *HTML templates* — these are snippets of HTML that are inserted into
 the section by Sphinx.
 
 You can choose which templates show up in each section, as well as the order in
@@ -215,7 +215,7 @@ Header / Navigation Bar
 
 Located in ``sections/header.html``.
 
-The header is at the top of the page above all other content, and contains site-level information.
+The header is at the top of the page above all other content and contains site-level information.
 
 Header sections
 ---------------
@@ -243,7 +243,7 @@ By default, the following configuration is used:
 
 .. warning::
 
-    The *Persistent right section* is placed next to the ``navbar_end`` but its elements will remain visible in the header even on small screens when all other elements are collapsed. It has been design for the ``search-button`` only and we cannot guarantee its compatibility with other components.
+    The *Persistent right section* is placed next to the ``navbar_end``, but its elements will remain visible in the header even on small screens when all other elements are collapsed. It has been design for the ``search-button`` only and we cannot guarantee its compatibility with other components.
 
 Configure the navbar center alignment
 -------------------------------------
@@ -259,7 +259,7 @@ page. This equals the following default configuration:
       # ...
    }
 
-If instead you'd like these items to snap to the left (closer to the logo), use this
+If instead, you'd like these items to snap to the left (closer to the logo), use this
 configuration:
 
 .. code-block:: python
@@ -305,9 +305,9 @@ Located in ``sections/sidebar-primary.html``.
 
 The primary sidebar is just to the left of a page's main content.
 It is primarily used for between-section navigation.
-By default it will show links to any sublings / children of the current active top-level section (corresponding to links in your header navigation bar).
+By default, it will show links to any siblings/children of the current active top-level section (corresponding to links in your header navigation bar).
 
-Configuring it is a bit different from configuring the other sections, because configuring the sidebar is natively supported in Sphinx, via the ``html_sidebars`` configuration variable.
+Configuring it is a bit different from configuring the other sections because configuring the sidebar is natively supported in Sphinx, via the ``html_sidebars`` configuration variable.
 
 For the primary sidebar only, you can configure templates so that they only show
 up on certain pages. You do so via a configuration like so in ``conf.py``:
@@ -391,8 +391,8 @@ Footer Content
 
 Located in ``sections/footer-content.html``.
 
-The footer content is a narrow bar spanning the article’s content and secondary sidebar.
-It does not contain anything immediately viewable to the reader, but is kept as a placeholder in case theme developers wish to re-use it in the future.
+The footer content is a narrow bar spanning the article's content and the secondary sidebar.
+It does not contain anything immediately viewable to the reader but is kept as a placeholder in case theme developers wish to re-use it in the future.
 
 
 .. _layout-sidebar-secondary:
@@ -402,7 +402,7 @@ Secondary Sidebar (right)
 
 Located in ``sections/sidebar-secondary.html``.
 
-The in-page sidebar is just to the right of a page's article content, and is
+The in-page sidebar is just to the right of a page's article content and is
 configured in ``conf.py`` with ``html_theme_options['secondary_sidebar_items']``.
 
 By default, it has the following templates:
@@ -424,7 +424,7 @@ Article Footer
 
 Located in ``sections/footer-article.html``.
 
-The article footer exists just below your page's article, and is primarily used for navigating between adjacent sections / pages.
+The article footer exists just below your page's article and is primarily used for navigating between adjacent sections/pages.
 By default, it has the following templates:
 
 .. code-block:: python
@@ -471,7 +471,7 @@ Footer
 
 Located in ``sections/footer.html``.
 
-The footer is just below a page’s main content, and is configured in ``conf.py``
+The footer is just below a page's main content, and is configured in ``conf.py``
 with ``html_theme_options['footer_start']`` and ``html_theme_options['footer_end']``.
 
 By default, ``footer_end`` is empty, and ``footer_start`` has the following templates:
diff --git a/docs/user_guide/light-dark.rst b/docs/user_guide/light-dark.rst
index 6ca1aa7c0..58d64ed0d 100644
--- a/docs/user_guide/light-dark.rst
+++ b/docs/user_guide/light-dark.rst
@@ -4,7 +4,7 @@
 Light and dark themes
 =====================
 
-You can change the major background / foreground colors of this theme according to "dark" and "light" modes.
+You can change the major background/foreground colors of this theme according to the "dark" and "light" modes.
 These are controlled by a button in the navigation header, with the following options:
 
 - A ``light`` theme with a bright background and dark text / UI elements
@@ -47,7 +47,7 @@ Customize the CSS of light and dark themes
 
 .. danger::
 
-    Theming is still a beta feature so the variables related to color theming are likely to change in the future. No backward compatibility is guaranteed when customization is done.
+    Theming is still a beta feature, so the variables related to color theming are likely to change in the future. No backward compatibility is guaranteed when customization is done.
 
 
 To customize the CSS of page elements in a theme-dependent manner, use the ``html[data-theme='<THEME>']`` CSS selector.
@@ -74,8 +74,8 @@ A complete list of the colors used in this theme can be found in the :doc:`CSS s
 Theme-dependent images and content
 ----------------------------------
 
-It is possible to use different content for light and dark mode, so that the content only shows up when a particular theme is active.
-This is useful if your content depends on the theme's style, such as a PNG image with a light or a dark background.
+It is possible to use different content for light and dark modes so that the content only shows up when a particular theme is active.
+This is useful if your content depends on the theme's style, such as a PNG image with a light or dark background.
 
 There are **two CSS helper classes** to specify items on the page as theme-specific.
 These are:
@@ -109,7 +109,7 @@ visible, and their brightness will be reduced by a filter.
 
 If your image is suitable for the dark theme, add the CSS class
 :code:`only-dark` as noted above. If your image is suitable for both light and
-dark theme, add the CSS class :code:`dark-light` to make your image
+dark themes, add the CSS class :code:`dark-light` to make your image
 theme-agnostic.
 
 For example, here's an image without adding this helper class.
diff --git a/docs/user_guide/navigation.rst b/docs/user_guide/navigation.rst
index be8b03aa6..8d219d5b4 100644
--- a/docs/user_guide/navigation.rst
+++ b/docs/user_guide/navigation.rst
@@ -3,7 +3,7 @@
 Navigation depth and collapsing sidebars
 ========================================
 
-By default, this theme enables to expand/collapse subsections in the primary
+By default, this theme enables to expand/collapse of subsections in the primary
 sidebar navigation (without actually navigating to the page itself), and this extends
 up to 4 levels deep:
 
@@ -24,10 +24,10 @@ default, you can use the following configuration in ``conf.py``:
      "show_nav_level": 2
    }
 
-This will make the first two navigations show up by default (AKA, top-level
+This will make the first two navigation levels show up by default (AKA, top-level
 pages and their immediate children).
 
-Collapse entire toctree captions / parts
+Collapse entire toctree captions/parts
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If your ``toctree`` elements have captions assigned to them (with ``:caption:``), you may
@@ -43,7 +43,7 @@ To enable this behavior, set the ``show_nav_level`` value to 0, like below:
    }
 
 You can only collapse your ``toctree`` items underneath their caption if a caption is defined for them!
-If your ``toctree`` does not have a caption defined, then all of the pages underneath it will be displayed
+If your ``toctree`` does not have a caption defined, then all the pages underneath it will be displayed
 (the same as the default theme behavior). See `the toctree documentation <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree>`_
 for more details.
 
diff --git a/docs/user_guide/page-toc.rst b/docs/user_guide/page-toc.rst
index 5c3c77f1a..60a3a423a 100644
--- a/docs/user_guide/page-toc.rst
+++ b/docs/user_guide/page-toc.rst
@@ -4,8 +4,8 @@ Page Table of Contents
 Show more levels of the in-page TOC by default
 ----------------------------------------------
 
-Normally only the 2nd-level headers of a page are show in the right
-table of contents, and deeper levels are only shown when they are part
+Normally only the 2nd-level headers of a page are shown in the right
+table of contents and deeper levels are only shown when they are part
 of an active section (when it is scrolled on screen).
 
 You can show deeper levels by default by using the following configuration, indicating how many levels should be displayed:
diff --git a/docs/user_guide/search.rst b/docs/user_guide/search.rst
index 9a0faf13c..ecab78254 100644
--- a/docs/user_guide/search.rst
+++ b/docs/user_guide/search.rst
@@ -15,9 +15,9 @@ Configure the search field position
 -----------------------------------
 
 The position of the search *button* is controlled by ``search-button`` and by default is included in ``html_theme_options["navbar_persistent"]``; you may move it elsewhere as befits your site's layout, or remove it.
-You can also add an always-visible search field to some/all pages in your site by adding ``search-field.html`` to one of the configuration variables (e.g., ``html_sidebars``, ``html_theme_options["footer_start"]``, etc).
+You can also add an always-visible search field to some/all pages in your site by adding ``search-field.html`` to one of the configuration variables (e.g., ``html_sidebars``, ``html_theme_options["footer_start"]``, etc.).
 
-For example, if you'd like the search field to be in your side-bar, add it to
+For example, if you'd like the search field to be in your sidebar, add it to
 the sidebar templates like so:
 
 .. code:: python
@@ -26,7 +26,7 @@ the sidebar templates like so:
         "**": ["search-field.html", "sidebar-nav-bs.html", "sidebar-ethical-ads.html"]
     }
 
-If instead you'd like to put the search field in the top navbar, use the
+If instead, you'd like to put the search field in the top navbar, use the
 following configuration:
 
 .. code:: python
@@ -37,7 +37,7 @@ following configuration:
 
 .. warning::
 
-    If a page includes *both* the search button and an always-visible search field, the keyboard shortcuts will focus the always-visible field and the hidden search field overlay will not display. *This may not be what you want:* on small screens (i.e. mobile devices) the sidebars may be hidden in a drawer, and if the persistent search field is there, it may receive focus without actually being made visible. It is **strongly recommended** that you use *either* search button and the hidden/overlaid field that comes with it, *or* use a persistent search field in a place that makes sense for your layout.
+    If a page includes *both* the search button and an always-visible search field, the keyboard shortcuts will focus on the always-visible field and the hidden search field overlay will not display. *This may not be what you want:* on small screens (i.e. mobile devices) the sidebars may be hidden in a drawer, and if the persistent search field is there, it may receive focus without actually being made visible. It is **strongly recommended** that you use *either* the search button and the hidden/overlaid field that comes with it, *or* use a persistent search field in a place that makes sense for your layout.
 
 
 Configure the search bar text
diff --git a/docs/user_guide/static_assets.md b/docs/user_guide/static_assets.md
index 8452a4eb5..2611bd27e 100644
--- a/docs/user_guide/static_assets.md
+++ b/docs/user_guide/static_assets.md
@@ -19,11 +19,11 @@ mysphinxsite/
 
 Any folders that are listed in `html_static_path` will be treated as containing static assets for your build.
 All files within these folders will be copied to your build's `_static` folder at build time.
-For example, with an `html` builder, files will be copied to `_build/html/_static`.
+For example, with an HTML builder, files will be copied to `_build/html/_static`.
 
 These files are _flattened_ when they are copied, so any folder hierarchies will be lost.
 
-Listing folders with your static assets must be done before any of the methods describe below.
+Listing folders with your static assets must be done before any of the methods described below.
 When you define asset names in the methods described below, they generally assume paths that are _relative to this `_static` output folder_.
 
 ## Define a list of assets in `conf.py`
@@ -44,9 +44,9 @@ html_js_files = ["myjs.js"]
 
 This will cause each to be linked in your `<head>`.
 
-## Add assets in your setup function
+## Add assets to your setup function
 
-Additionally you may add assets manually, to do so, use the `app` object in [the Sphinx `setup()` function](https://www.sphinx-doc.org/en/master/extdev/appapi.html#extension-setup).
+Additionally, you may add assets manually, to do so, use the `app` object in [the Sphinx `setup()` function](https://www.sphinx-doc.org/en/master/extdev/appapi.html#extension-setup).
 The `app` object has two relevant methods here:
 
 [**`app.add_css_file`**](https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_css_file) allows you to add CSS files directly.
@@ -77,7 +77,7 @@ def setup(app):
 
 ## Use an event to add it to specific pages
 
-If you'd like to use logic to only add a script to certain pages, or to trigger different behavior depending on the page, use [a Sphinx event hook](https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events).
+If you'd like to use logic to only add a script to certain pages or to trigger different behavior depending on the page, use [a Sphinx event hook](https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx-core-events).
 This involves defining a function that runs when a particular event is emitted in the Sphinx build, and using [`app.connect()`](https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.connect) to connect it to your build.
 
 The event you'll likely want to use is [`html-page-context`](https://www.sphinx-doc.org/en/master/extdev/appapi.html#event-html-page-context).
@@ -120,7 +120,7 @@ If you're using reStructuredText or MyST Markdown, you can use the `raw` directi
    </script>
 ```
 
-If you're using MyST Markdown, you may also simply directly include any HTML / style / script blocks in your content without using a directive.
+If you're using MyST Markdown, you may also directly include any HTML / style / script blocks in your content without using a directive.
 
 For example:
 
diff --git a/docs/user_guide/styling.rst b/docs/user_guide/styling.rst
index 70d10c7db..c14d3a473 100644
--- a/docs/user_guide/styling.rst
+++ b/docs/user_guide/styling.rst
@@ -12,7 +12,7 @@ This section covers a few ways that you can control the look and feel of your th
 Custom CSS Stylesheets
 ======================
 
-You may customize the theme's CSS by creating a custom stylesheet that Sphinx uses to build your site.
+You can customize the theme's CSS by creating a custom stylesheet. This stylesheet will be used by Sphinx while building your site.
 Any rules in this style-sheet will over-ride the default theme rules.
 
 .. seealso::
@@ -60,9 +60,10 @@ Follow these steps to update the base variables:
 
 .. important::
 
-   Note that these are `CSS variables <css-variable-help_>`_ and not
-   `SASS variables <https://sass-lang.com/documentation/variables>`_.
-   The theme is defined with CSS variables, not SASS variables! Refer to the previous section if
+   Note that the theme is defined with `CSS variables <css-variable-help_>`_
+   and **not** `SASS variables <https://sass-lang.com/documentation/variables>`_.
+
+   Refer to the previous section if
    you desire a different behavior between the light and dark theme.
 .. TODO: add correct reference to light and dark theme @trallard
 
@@ -100,8 +101,9 @@ Here is an overview of the colors available in the theme (change theme mode to s
 .. raw:: html
 
     <style>
-      span.pst-primary {background-color: var(--pst-color-primary);
+      span.pst-primary {background-color: var(--pst-color-primary);}
       span.pst-secondary {background-color: var(--pst-color-secondary);}
+      span.pst-accent {background-color: var(--pst-color-accent);}
       span.pst-success {background-color: var(--pst-color-success);}
       span.pst-info {background-color: var(--pst-color-info);}
       span.pst-warning {background-color: var(--pst-color-warning);}
@@ -114,17 +116,18 @@ Here is an overview of the colors available in the theme (change theme mode to s
     </style>
 
     <p>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-primary">primary</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-secondary">secondary</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-success">success</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-info">info</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-warning">warning</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-danger">danger</span>
+      <span class="sd-sphinx-override sd-badge pst-badge pst-primary sd-bg-text-primary">primary</span>
+      <span class="sd-sphinx-override sd-badge pst-badge pst-secondary sd-bg-text-secondary">secondary</span>
+      <span class="sd-sphinx-override sd-badge pst-badge pst-accent sd-bg-text-secondary">secondary</span>
+      <span class="sd-sphinx-override sd-badge pst-badge pst-success sd-bg-text-success">success</span>
+      <span class="sd-sphinx-override sd-badge pst-badge pst-info sd-bg-text-info">info</span>
+      <span class="sd-sphinx-override sd-badge pst-badge pst-warning sd-bg-text-warning">warning</span>
+      <span class="sd-sphinx-override sd-badge pst-badge pst-danger sd-bg-text-danger">danger</span>
       <span class="sd-sphinx-override sd-badge pst-badge pst-background">background</span>
       <span class="sd-sphinx-override sd-badge pst-badge pst-on-background">on-background</span>
       <span class="sd-sphinx-override sd-badge pst-badge pst-surface">surface</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-on-surface">on-surface</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-target">target</span>
+      <span class="sd-sphinx-override sd-badge pst-badge pst-on-surface sd-bg-text-primary">on-surface</span>
+      <span class="sd-sphinx-override sd-badge pst-badge pst-target sd-bg-text-primary">target</span>
     </p>
 
 
@@ -174,7 +177,7 @@ The following image should help you understand these overlays:
         <p class="label">surface</p>
       </div>
       <div class="pst-overlay pst-on-surface">
-        <p class="label">on-surface</p>
+        <p class="label sd-bg-text-primary">on-surface</p>
       </div>
     </div>
 
@@ -201,8 +204,9 @@ You can check available Pygments colors on this `pygments demo page <https://pyg
    }
 
 Note that the PyData Sphinx theme uses the `accessible pygments styles <https://github.com/Quansight-Labs/accessible-pygments>`__ for its default syntax highlighting themes.
-The accessible pygments themes are designed to meet `WCAG <https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html>`__ AA or AAA standards for contrast and some themes are also suitable for colorblind users
-or low light conditions. You can check all the available styles at the `accessible pygments demo page <https://quansight-labs.github.io/accessible-pygments/>`__.
+The accessible pygments themes are designed to meet `WCAG AA or AAA standards for color contrast <https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html>`__ and some included themes are also suitable for colorblind users
+or low-light conditions.
+You can check all the available styles at the `accessible pygments demo page <https://quansight-labs.github.io/accessible-pygments/>`__.
 
 .. danger::
 
diff --git a/docs/user_guide/theme-elements.md b/docs/user_guide/theme-elements.md
index ed43afaea..58d9cff68 100644
--- a/docs/user_guide/theme-elements.md
+++ b/docs/user_guide/theme-elements.md
@@ -1,7 +1,7 @@
 # Theme-specific elements
 
 There are a few elements that are unique or particularly important to this theme.
-Some of these are triggered with configuration or markdown syntax that is unique to the theme, and we cover them below.
+Some of these are triggered with configuration or Markdown syntax that is unique to the theme, and we cover them below.
 
 ```{contents} Page contents
 :local:
@@ -9,11 +9,10 @@ Some of these are triggered with configuration or markdown syntax that is unique
 
 ## Mathematics
 
-Most Sphinx sites support math, but it is particularly important for scientific computing and so we illustrate support here as well.
+Most Sphinx sites support math, but it is particularly important for scientific computing, so we illustrate support here as well.
 
 Here is an inline equation: {math}`X_{0:5} = (X_0, X_1, X_2, X_3, X_4)` and {math}`another` and {math}`x^2 x^3 x^4` another. And here's one to test vertical height {math}`\frac{\partial^2 f}{\partial \phi^2}`.
-
-Here is block-level equation:
+Here is a block-level equation:
 
 ```{math}
 :label: My label
@@ -45,7 +44,7 @@ And here is a really long equation with a label!
 \frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2}
 ```
 
-You can add a link to equations like the one above: {eq}`My label` and {eq}`My label 2`.
+You can add a link to equations like the one above {eq}`My label` and {eq}`My label 2`.
 
 ## Code blocks
 
@@ -58,7 +57,7 @@ print("A regular code block")
 print("A regular code block")
 ```
 
-You can also provide captions with code blocks, which will be displayed just above the code.
+You can also provide captions with code blocks, which will be displayed right above the code.
 For example, the following code:
 
 ````md
@@ -104,7 +103,7 @@ print("A code block with a caption and line numbers.")
 
 ## Inline code
 
-When used directly, the `code` role just displays the text without syntax highlighting, as a literal. As mentioned in the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#inline-code-highlighting) you can also enable syntax highlighting by defining a custom role. It will then use the same highligther as in the `code-block` directive.
+When used directly, the `code` role just displays the text without syntax highlighting, as a literal. As mentioned in the [Sphinx documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#inline-code-highlighting) you can also enable syntax highlighting by defining a custom role. It will then use the same highlighter as in the `code-block` directive.
 
 ```{code-block} rst
 
@@ -147,13 +146,13 @@ Here's one footnote[^1] and another footnote [^2] and a named footenote[^named],
 
 ## Version changes
 
-This theme supports a short-hand way of making **admonitions behave like sidebars**.
+This theme supports a shorthand way of making **admonitions behave like sidebars**.
 This can be a helpful way of highlighting content that lives to the side of your main text without interrupting the vertical flow as much.
 
 For example, look to the right of an "admonition sidebar" and a traditional Sphinx sidebar.
 
 To make an admonition behave like a sidebar, add the `sidebar` class to its list of classes.
-For example, the admonition sidebar was created with the following markdown:
+For example, the admonition sidebar was created with the following Markdown:
 
 ````md
 ```{admonition} A sidebar admonition!
@@ -169,7 +168,7 @@ Instead of displaying these as raw links, this theme does some lightweight forma
 
 In **reStructuredText**, URLs are automatically converted to links, so this works automatically.
 
-In **MyST Markdown**, by default you must define a standard markdown link and duplicate the URL in the link text.
+In **MyST Markdown**, by default, you must define a standard Markdown link and duplicate the URL in the link text.
 You may skip the need to manually define the link text by [activating the MyST Linkify extension](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#linkify).
 
 For example:
diff --git a/docs/user_guide/version-dropdown.rst b/docs/user_guide/version-dropdown.rst
index 8a9b17cef..7bbf6dcbf 100644
--- a/docs/user_guide/version-dropdown.rst
+++ b/docs/user_guide/version-dropdown.rst
@@ -7,7 +7,7 @@ switcher will differ depending on which page of the docs is being viewed. For
 example, on the page ``https://mysite.org/en/v2.0/changelog.html``, the
 switcher links will go to ``changelog.html`` in the other versions of your
 docs. When clicked, the switcher will check for the existence of that page, and
-if it doesn't exist, redirect to the homepage of that docs version instead.
+if it doesn't exist, redirect to the homepage of that docs' version instead.
 
 The switcher requires the following configuration steps:
 
@@ -23,7 +23,7 @@ The switcher requires the following configuration steps:
 
 3. Specify where to place the switcher in your page layout. For example, add
    the ``"version-switcher"`` template to one of the layout lists in
-   ``html_theme_options`` (e.g., ``navbar_end``, ``footer_start``, etc).
+   ``html_theme_options`` (e.g., ``navbar_end``, ``footer_start``, etc.).
 
 Below is a more in-depth description of each of these configuration steps.
 
@@ -39,7 +39,7 @@ each can have the following fields:
   ``switcher['version_match']`` to provide styling to the switcher.
 - ``url``: the URL for this version.
 - ``name``: an optional name to display in the switcher dropdown instead of the
-  version string (e.g., "latest", "stable", "dev", etc).
+  version string (e.g., "latest", "stable", "dev", etc.).
 
 Here is an example JSON file:
 
@@ -77,7 +77,7 @@ not specified as a path relative to the sphinx root of the current doc build).
 Each version of your documentation should point to the same URL, so that as new
 versions are added to the JSON file all the older versions of the docs will
 gain switcher dropdown entries linking to the new versions. This could be done
-a few different ways:
+in a few different ways:
 
 - The location could be one that is always associated with the most recent
   documentation build (i.e., if your docs server aliases "latest" to the most
@@ -93,7 +93,7 @@ a few different ways:
           }
       }
 
-  In this case the JSON is versioned alongside the rest of the docs pages but
+  In this case, the JSON is versioned alongside the rest of the docs pages but
   only the most recent version is ever loaded (even by older versions of the
   docs).
 
@@ -115,7 +115,7 @@ a few different ways:
           }
       }
 
-By default the theme is testing the :code:`.json` file provided and outputs warnings in the Sphinx build. If this test breaks the pipeline of your docs, the test can be disabled by configuring the :code:`check_switcher` parameter in :code:`conf.py`:
+By default, the theme is testing the :code:`.json` file provided and outputs warnings in the Sphinx build. If this test breaks the pipeline of your docs, the test can be disabled by configuring the :code:`check_switcher` parameter in :code:`conf.py`:
 
 .. code-block:: python
 
@@ -132,7 +132,7 @@ being viewed, and is used to style the switcher (i.e., to highlight the current
 docs version in the switcher's dropdown menu, and to change the text displayed
 on the switcher button).
 
-Typically you can re-use one of the sphinx variables ``version``
+Typically, you can re-use one of the sphinx variables ``version``
 or ``release`` as the value of ``switcher['version_match']``; which one you use
 depends on how granular your docs versioning is. See
 `the Sphinx "project info" documentation
@@ -229,4 +229,4 @@ version, you could use the following CSS selector:
 .. seealso::
 
    See the `MDN documentation on dataset properties <https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/dataset>`_
-   for more information on using and styling with these properties.
+   for more information on using and styling these properties.

From 58aceaf6d902cea0d361e98654cd8d150fa1c6db Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Sun, 16 Apr 2023 19:10:01 +0100
Subject: [PATCH 46/64] Minor edits to docs

---
 docs/_templates/custom-template.html  | 2 +-
 docs/user_guide/keyboard-shortcuts.md | 2 +-
 docs/user_guide/styling.rst           | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/_templates/custom-template.html b/docs/_templates/custom-template.html
index 0ed45ec1c..f6757f9d4 100644
--- a/docs/_templates/custom-template.html
+++ b/docs/_templates/custom-template.html
@@ -1,6 +1,6 @@
 <div class="sidebar-message">
   This is a community-supported theme.
   If you'd like to contribute,
-  <a href="https://github.com/pydata/pydata-sphinx-theme">check out our GitHub repository</a>
+  <a href="https://github.com/pydata/pydata-sphinx-theme">check out our GitHub repository.</a>
   Your contributions are welcome!
 </div>
diff --git a/docs/user_guide/keyboard-shortcuts.md b/docs/user_guide/keyboard-shortcuts.md
index 89e67770e..e317f2dca 100644
--- a/docs/user_guide/keyboard-shortcuts.md
+++ b/docs/user_guide/keyboard-shortcuts.md
@@ -2,7 +2,7 @@
 
 ## Trigger the search bar
 
-You can trigger the search bar pop-up with <kbd>ctrl</kbd>/<kbd>cmd</kbd> + <kbd>K</kbd>.
+You can trigger the search bar pop-up with <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>K</kbd>.
 
 ## Change pages
 
diff --git a/docs/user_guide/styling.rst b/docs/user_guide/styling.rst
index c14d3a473..b20aea03b 100644
--- a/docs/user_guide/styling.rst
+++ b/docs/user_guide/styling.rst
@@ -13,7 +13,7 @@ Custom CSS Stylesheets
 ======================
 
 You can customize the theme's CSS by creating a custom stylesheet. This stylesheet will be used by Sphinx while building your site.
-Any rules in this style-sheet will over-ride the default theme rules.
+Any rules in this style sheet will override the default theme rules.
 
 .. seealso::
 

From c11e0c33403eba96c3345b5c1463616c69127e2d Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Sun, 16 Apr 2023 19:10:37 +0100
Subject: [PATCH 47/64] Fix colour in code blocks

---
 .../assets/styles/components/_toc-inpage.scss              | 3 +++
 src/pydata_sphinx_theme/assets/styles/content/_code.scss   | 7 ++++---
 .../assets/styles/extensions/_sphinx_design.scss           | 5 ++++-
 .../assets/styles/variables/_color.scss                    | 2 +-
 4 files changed, 12 insertions(+), 5 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/components/_toc-inpage.scss b/src/pydata_sphinx_theme/assets/styles/components/_toc-inpage.scss
index 2f2fc76ca..f26eb92f4 100644
--- a/src/pydata_sphinx_theme/assets/styles/components/_toc-inpage.scss
+++ b/src/pydata_sphinx_theme/assets/styles/components/_toc-inpage.scss
@@ -25,6 +25,9 @@ nav.page-toc {
 // Each entry of the in-page TOC
 .toc-entry {
   display: block;
+  a > code {
+    color: var(--pst-color-text-muted);
+  }
 
   a.nav-link {
     display: block;
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_code.scss b/src/pydata_sphinx_theme/assets/styles/content/_code.scss
index e1b8d9120..1945d77ad 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_code.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_code.scss
@@ -53,7 +53,8 @@ code.literal {
   background-color: var(--pst-color-surface);
   border: 1px solid var(--pst-color-border);
   border-radius: 0.25rem;
-  a {
-    color: var(--pst-color-inline-code-links);
-  }
+}
+
+a > code {
+  color: var(--pst-color-inline-code-links);
 }
diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 90b1d7afb..534e97631 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -209,7 +209,7 @@ details.sd-dropdown {
     // Set a variable that we can re-use for colors later
     // We must set this in the current and content sibling container
     // so that it is defined in both places
-    --pst-sd-dropdown-color: var(--sd-color-card-border);
+    --pst-sd-dropdown-color: var(--pst-gray-500);
     --pst-sd-dropdown-bg-color: var(--pst-color-surface);
     & + div.sd-summary-content {
       --pst-sd-dropdown-color: var(--sd-color-card-border);
@@ -245,6 +245,9 @@ details.sd-dropdown {
       display: inline-flex;
       align-items: center;
       color: var(--pst-sd-dropdown-color) !important;
+      svg {
+        opacity: 1;
+      }
     }
 
     // Positioning of the caret
diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index dcdf32aa8..77b08cb3a 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -196,7 +196,7 @@ $pst-semantic-colors: (
   "inline-code-links": (
     // need to make sure there is enough contrast agains the code bg
     "light": #{map-deep-get($color-palette, "teal", "700")},
-    "dark": #{map-deep-get($color-palette, "teal", "300")},
+    "dark": #{map-deep-get($color-palette, "teal", "500")},
   ),
   "target": (
     "light": #8b6e31,

From 6702fc23096c26d148d166bab1f8cb68f17a60cb Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 17 Apr 2023 18:54:12 +0100
Subject: [PATCH 48/64] :zap: Use math.pow - we use dart sass now

---
 .../assets/styles/abstracts/_mixins.scss      | 31 +++----------------
 1 file changed, 4 insertions(+), 27 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
index a851aaa33..082d0e9db 100644
--- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
+++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -63,6 +63,8 @@
     top: 0;
     background-color: var(#{$color-variable});
     z-index: -1;
+    // TODO: check for colour contrast bg vs text
+    // color: #{a11y-combination($color-variable)};
 
     // So that hovering over the text within background is still possible.
     // Otherwise the background overlays the text and you cannot click or select easily.
@@ -168,32 +170,6 @@
   @return $dec;
 }
 
-// A list of pre-calculated numbers of pow(divide((divide($value, 255) + .055), 1.055), 2.4). (from 0 to 255)
-$_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
-  0.0027 0.003 0.0033 0.0037 0.004 0.0044 0.0048 0.0052 0.0056 0.006 0.0065
-  0.007 0.0075 0.008 0.0086 0.0091 0.0097 0.0103 0.011 0.0116 0.0123 0.013
-  0.0137 0.0144 0.0152 0.016 0.0168 0.0176 0.0185 0.0194 0.0203 0.0212 0.0222
-  0.0232 0.0242 0.0252 0.0262 0.0273 0.0284 0.0296 0.0307 0.0319 0.0331 0.0343
-  0.0356 0.0369 0.0382 0.0395 0.0409 0.0423 0.0437 0.0452 0.0467 0.0482 0.0497
-  0.0513 0.0529 0.0545 0.0561 0.0578 0.0595 0.0612 0.063 0.0648 0.0666 0.0685
-  0.0704 0.0723 0.0742 0.0762 0.0782 0.0802 0.0823 0.0844 0.0865 0.0887 0.0908
-  0.0931 0.0953 0.0976 0.0999 0.1022 0.1046 0.107 0.1095 0.1119 0.1144 0.117
-  0.1195 0.1221 0.1248 0.1274 0.1301 0.1329 0.1356 0.1384 0.1413 0.1441 0.147
-  0.15 0.1529 0.1559 0.159 0.162 0.1651 0.1683 0.1714 0.1746 0.1779 0.1812
-  0.1845 0.1878 0.1912 0.1946 0.1981 0.2016 0.2051 0.2086 0.2122 0.2159 0.2195
-  0.2232 0.227 0.2307 0.2346 0.2384 0.2423 0.2462 0.2502 0.2542 0.2582 0.2623
-  0.2664 0.2705 0.2747 0.2789 0.2831 0.2874 0.2918 0.2961 0.3005 0.305 0.3095
-  0.314 0.3185 0.3231 0.3278 0.3325 0.3372 0.3419 0.3467 0.3515 0.3564 0.3613
-  0.3663 0.3712 0.3763 0.3813 0.3864 0.3916 0.3968 0.402 0.4072 0.4125 0.4179
-  0.4233 0.4287 0.4342 0.4397 0.4452 0.4508 0.4564 0.4621 0.4678 0.4735 0.4793
-  0.4851 0.491 0.4969 0.5029 0.5089 0.5149 0.521 0.5271 0.5333 0.5395 0.5457
-  0.552 0.5583 0.5647 0.5711 0.5776 0.5841 0.5906 0.5972 0.6038 0.6105 0.6172
-  0.624 0.6308 0.6376 0.6445 0.6514 0.6584 0.6654 0.6724 0.6795 0.6867 0.6939
-  0.7011 0.7084 0.7157 0.7231 0.7305 0.7379 0.7454 0.7529 0.7605 0.7682 0.7758
-  0.7835 0.7913 0.7991 0.807 0.8148 0.8228 0.8308 0.8388 0.8469 0.855 0.8632
-  0.8714 0.8796 0.8879 0.8963 0.9047 0.9131 0.9216 0.9301 0.9387 0.9473 0.956
-  0.9647 0.9734 0.9823 0.9911 1;
-
 /**
 * Get color combinations that meet a minimum contrast ratio as per WCAG 2
 */
@@ -262,7 +238,8 @@ $_luminance-list: 0.0008 0.001 0.0011 0.0013 0.0015 0.0017 0.002 0.0022 0.0025
       $rgb-col: map-merge(
         $rgb-col,
         (
-          $channel: nth($_luminance-list, $value + 1),
+          $channel:
+            math.pow(math.div((math.div($value, 255) + 0.055), 1.055), 2.4),
         )
       );
     }

From 17b0e35f2a18b745d3ce17360b47709969dbd533 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 17 Apr 2023 19:32:35 +0100
Subject: [PATCH 49/64] :zap: Use math.pow

---
 .../assets/styles/abstracts/_mixins.scss      | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
index 082d0e9db..cb915d77d 100644
--- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
+++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -6,7 +6,7 @@
 * ref: https://www.nngroup.com/articles/scrolling-and-scrollbars/
 */
 
-// loading the math module
+// loading the math module - needed for a11y-combination
 @use "sass:math";
 
 @mixin scrollbar-style() {
@@ -63,13 +63,21 @@
     top: 0;
     background-color: var(#{$color-variable});
     z-index: -1;
-    // TODO: check for colour contrast bg vs text
-    // color: #{a11y-combination($color-variable)};
-
     // So that hovering over the text within background is still possible.
     // Otherwise the background overlays the text and you cannot click or select easily.
     // ref: https://developer.mozilla.org/en-US/docs/Web/CSS/pointer-events
     pointer-events: none;
+    color: is-color(var(#{$color-variable}));
+  }
+}
+
+@function is-color($value) {
+  @if type-of($value) == "color" {
+    @return #{a11y-combination($value)};
+    @debug "is a color: #{$value}✨ ";
+  } @else {
+    @debug "not a color: #{$value}";
+    @return --pst-color-text-base;
   }
 }
 
@@ -100,6 +108,7 @@
 /**
 * Function to check if the color needs converting to a "color" type
 * if it is a string we cannot use other color manipulation functions
+* It is used to create the sphinx-design colours as these are often interpolated
 */
 // @param {String/Color} $color - Color definition from map
 // @return {Color} - Color type (in hex)
@@ -202,7 +211,7 @@
   @return $max-ratio-color;
 }
 
-@function get-contrast-ratio($bg, $foreground: #ced6dd) {
+@function get-contrast-ratio($bg, $foreground) {
   $l1: luminance($bg);
   $l2: luminance($foreground);
 

From f5f3795e0fa27c54c2cb2dac57467ab40de70073 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 18 Apr 2023 10:02:37 +0100
Subject: [PATCH 50/64] :zap: Update mixins

---
 .../assets/styles/abstracts/_mixins.scss              | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
index cb915d77d..feaab5e63 100644
--- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
+++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -67,17 +67,6 @@
     // Otherwise the background overlays the text and you cannot click or select easily.
     // ref: https://developer.mozilla.org/en-US/docs/Web/CSS/pointer-events
     pointer-events: none;
-    color: is-color(var(#{$color-variable}));
-  }
-}
-
-@function is-color($value) {
-  @if type-of($value) == "color" {
-    @return #{a11y-combination($value)};
-    @debug "is a color: #{$value}✨ ";
-  } @else {
-    @debug "not a color: #{$value}";
-    @return --pst-color-text-base;
   }
 }
 

From 659eccabda6c1d90bdefd275108f64caf8f78059 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 13 Jun 2023 18:01:20 +0100
Subject: [PATCH 51/64] :heavy_plus_sign: Add math import in mixins

---
 src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
index 39c4af9c8..2eb97d8f5 100644
--- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
+++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -1,6 +1,10 @@
 /*********************************************
 * SASS Mixins
 *********************************************/
+
+// loading the math module
+@use "sass:math";
+
 /**
  * A consistent box shadow style we apply across elements.
  */

From 85c14645d566c8919256007654ee70bd2e7373e7 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 13 Jun 2023 19:25:34 +0100
Subject: [PATCH 52/64] Fix highlight colour - pygments

---
 src/pydata_sphinx_theme/assets/styles/content/_code.scss | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/pydata_sphinx_theme/assets/styles/content/_code.scss b/src/pydata_sphinx_theme/assets/styles/content/_code.scss
index 1945d77ad..c2d05ac7f 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_code.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_code.scss
@@ -58,3 +58,10 @@ code.literal {
 a > code {
   color: var(--pst-color-inline-code-links);
 }
+
+// Fix for Sphinx's "highlight" directive - this is an issue with our accessible pygments theme
+// and the colour we are using for the background of the code blocks.
+
+html[data-theme="light"] .highlight .nf {
+  color: #0078a1 !important;
+}

From 1330c74b4407470b28857bbd39227dd3474dcdb2 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 13 Jun 2023 19:32:39 +0100
Subject: [PATCH 53/64] Fix inline code links contrast

---
 src/pydata_sphinx_theme/assets/styles/variables/_color.scss | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index 77b08cb3a..1cfa10c8a 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -194,9 +194,9 @@ $pst-semantic-colors: (
     "dark": #{map-deep-get($color-palette, "pink", "300")},
   ),
   "inline-code-links": (
-    // need to make sure there is enough contrast agains the code bg
-    "light": #{map-deep-get($color-palette, "teal", "700")},
-    "dark": #{map-deep-get($color-palette, "teal", "500")},
+    // need to make sure there is enough contrast against the code bg
+    "light": #{map-deep-get($color-palette, "teal", "600")},
+    "dark": #{map-deep-get($color-palette, "teal", "400")},
   ),
   "target": (
     "light": #8b6e31,

From 856657851991bb420ce4b080e73d399d46646713 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 13 Jun 2023 19:46:35 +0100
Subject: [PATCH 54/64] Add selector to print - a11y tests

---
 tests/test_a11y.py                | 2 +-
 tests/utils/pretty_axe_results.py | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/tests/test_a11y.py b/tests/test_a11y.py
index e4a6821a0..0f07cea90 100644
--- a/tests/test_a11y.py
+++ b/tests/test_a11y.py
@@ -111,4 +111,4 @@ def test_axe_core_kitchen_sink(
     results = page.evaluate(f"axe.run('{selector}')")
 
     # Expect Axe-core to have found 0 accessibility violations
-    assert len(results["violations"]) == 0, pretty_axe_results(results)
+    assert len(results["violations"]) == 0, pretty_axe_results(results, selector)
diff --git a/tests/utils/pretty_axe_results.py b/tests/utils/pretty_axe_results.py
index 698d42efd..c5929e087 100644
--- a/tests/utils/pretty_axe_results.py
+++ b/tests/utils/pretty_axe_results.py
@@ -10,7 +10,7 @@
 # assert(len(results["violations"])) == 0, pretty_axe_results(results)
 
 
-def pretty_axe_results(results: dict) -> str:
+def pretty_axe_results(results: dict, selector: str) -> str:
     """Create readable string that can be printed to console from the Axe-core results object.
 
     :param results: The object promised by `axe.run()`.
@@ -30,6 +30,7 @@ def pretty_axe_results(results: dict) -> str:
         )
         for tag in violation["tags"]:
             string += f" {tag}"
+        string += f"\n\tTested selector: {selector}"
         string += "\n\tElements Affected:"
         i = 1
         for node in violation["nodes"]:

From 181ed571b6a9f39ee27dbc2b26e75e3a8cb83473 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 13 Jun 2023 20:05:26 +0100
Subject: [PATCH 55/64] Fix line numbers contrast

---
 src/pydata_sphinx_theme/assets/styles/base/_base.scss     | 3 ++-
 src/pydata_sphinx_theme/assets/styles/content/_hacks.scss | 5 +++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/base/_base.scss b/src/pydata_sphinx_theme/assets/styles/base/_base.scss
index 12a26ac9c..9970ec12e 100644
--- a/src/pydata_sphinx_theme/assets/styles/base/_base.scss
+++ b/src/pydata_sphinx_theme/assets/styles/base/_base.scss
@@ -169,7 +169,8 @@ pre {
   border-radius: $admonition-border-radius;
 
   .linenos {
-    opacity: 0.5;
+    // minimum opacity to make the line numbers WCAG AA conformant
+    opacity: 0.8;
     padding-right: 10px;
   }
 }
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_hacks.scss b/src/pydata_sphinx_theme/assets/styles/content/_hacks.scss
index 054403d8b..c725ba246 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_hacks.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_hacks.scss
@@ -14,3 +14,8 @@ div.doctest > div.highlight span.gp {
   -moz-user-select: none; /* Firefox */
   -ms-user-select: none; /* IE10+ */
 }
+
+// Minimum opacity needed for linenos to be WCAG AA conformant
+span.linenos {
+  opacity: 0.8;
+}

From 6dedf8e2b29c7e4b0ba5899c78933d8f0d5f339f Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Tue, 13 Jun 2023 20:23:47 +0100
Subject: [PATCH 56/64] Fix announcement link colours

---
 .../assets/styles/sections/_announcement.scss                 | 4 ++++
 src/pydata_sphinx_theme/assets/styles/variables/_color.scss   | 1 +
 2 files changed, 5 insertions(+)

diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss b/src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss
index aa59a6bf2..34f983c13 100644
--- a/src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss
+++ b/src/pydata_sphinx_theme/assets/styles/sections/_announcement.scss
@@ -33,4 +33,8 @@
   &:empty {
     display: none;
   }
+
+  a {
+    color: var(--pst-color-inline-code-links);
+  }
 }
diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index 1cfa10c8a..d5c63b7a1 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -196,6 +196,7 @@ $pst-semantic-colors: (
   "inline-code-links": (
     // need to make sure there is enough contrast against the code bg
     "light": #{map-deep-get($color-palette, "teal", "600")},
+    // keep primary color for dark mode
     "dark": #{map-deep-get($color-palette, "teal", "400")},
   ),
   "target": (

From 0f1ffb9f2b6f2f22ffa09dcbfbdf8a12ca316f0e Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Thu, 15 Jun 2023 19:53:19 +0100
Subject: [PATCH 57/64] Adjust background colours - light theme

---
 .../assets/styles/content/_code.scss          |  6 ++++-
 .../assets/styles/content/_hacks.scss         |  5 -----
 .../assets/styles/variables/_color.scss       | 22 +++++++++----------
 3 files changed, 16 insertions(+), 17 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/content/_code.scss b/src/pydata_sphinx_theme/assets/styles/content/_code.scss
index c2d05ac7f..8f4a264d3 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_code.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_code.scss
@@ -61,7 +61,11 @@ a > code {
 
 // Fix for Sphinx's "highlight" directive - this is an issue with our accessible pygments theme
 // and the colour we are using for the background of the code blocks.
-
 html[data-theme="light"] .highlight .nf {
   color: #0078a1 !important;
 }
+
+// Minimum opacity needed for linenos to be WCAG AA conformant
+span.linenos {
+  opacity: 0.8 !important;
+}
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_hacks.scss b/src/pydata_sphinx_theme/assets/styles/content/_hacks.scss
index c725ba246..054403d8b 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_hacks.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_hacks.scss
@@ -14,8 +14,3 @@ div.doctest > div.highlight span.gp {
   -moz-user-select: none; /* Firefox */
   -ms-user-select: none; /* IE10+ */
 }
-
-// Minimum opacity needed for linenos to be WCAG AA conformant
-span.linenos {
-  opacity: 0.8;
-}
diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index d5c63b7a1..10c8f57d1 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -38,9 +38,9 @@ $color-palette: (
   "violet":
     (
       "50": #f4eefb,
-      "100": #e1cafe,
-      "200": #cda5ff,
-      "300": #b680ff,
+      "100": #e0c7ff,
+      "200": #d5b4fd,
+      "300": #b780ff,
       "400": #9c5ffd,
       "500": #8045e5,
       "600": #6432bd,
@@ -117,7 +117,7 @@ $foundation-dark-gray: #222832;
 $pst-semantic-colors: (
   "primary": (
     "light": #{map-deep-get($color-palette, "teal", "500")},
-    "bg-light": #{map-deep-get($color-palette, "teal", "100")},
+    "bg-light": #{map-deep-get($color-palette, "teal", "200")},
     "dark": #{map-deep-get($color-palette, "teal", "400")},
     "bg-dark": #{map-deep-get($color-palette, "teal", "800")},
   ),
@@ -129,25 +129,25 @@ $pst-semantic-colors: (
   ),
   "accent": (
     "light": #{map-deep-get($color-palette, "pink", "500")},
-    "bg-light": #{map-deep-get($color-palette, "pink", "100")},
+    "bg-light": #{map-deep-get($color-palette, "pink", "200")},
     "dark": #{map-deep-get($color-palette, "pink", "400")},
     "bg-dark": #{map-deep-get($color-palette, "pink", "800")},
   ),
   "info": (
     "light": #276be9,
-    "bg-light": #eff4fd,
+    "bg-light": #dce7fc,
     "dark": #79a3f2,
     "bg-dark": #06245d,
   ),
   "warning": (
     "light": #f66a0a,
-    "bg-light": #fff8f2,
+    "bg-light": #f8e3d0,
     "dark": #ff9245,
     "bg-dark": #652a02,
   ),
   "success": (
     "light": #00843f,
-    "bg-light": #ecf6f1,
+    "bg-light": #d6ece1,
     "dark": #5fb488,
     "bg-dark": #002f17,
   ),
@@ -161,7 +161,7 @@ $pst-semantic-colors: (
     ),
   "danger": (
     "light": #d72d47,
-    "bg-light": #fcf1f2,
+    "bg-light": #f9e1e4,
     "dark": #e78894,
     "bg-dark": #4e111b,
   ),
@@ -183,11 +183,11 @@ $pst-semantic-colors: (
   ),
   "border": (
     "light": #{map-deep-get($color-palette, "gray", "300")},
-    "dark": #{map-deep-get($color-palette, "gray", "500")},
+    "dark": #{map-deep-get($color-palette, "gray", "600")},
   ),
   "border-muted": (
     "light": rgba(23, 23, 26, 0.2),
-    "dark": #{map-deep-get($color-palette, "gray", "600")},
+    "dark": #{map-deep-get($color-palette, "gray", "700")},
   ),
   "inline-code": (
     "light": #{map-deep-get($color-palette, "pink", "600")},

From 4c17a23a97b2fdc520bdc6f7b41e50d88b9ec5cb Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 16 Jun 2023 11:46:54 +0100
Subject: [PATCH 58/64] Update search highlight colours

---
 src/pydata_sphinx_theme/assets/styles/variables/_color.scss | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
index 10c8f57d1..e658ae062 100644
--- a/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/variables/_color.scss
@@ -200,8 +200,8 @@ $pst-semantic-colors: (
     "dark": #{map-deep-get($color-palette, "teal", "400")},
   ),
   "target": (
-    "light": #8b6e31,
-    "dark": #c79d41,
+    "light": #f3cf95,
+    "dark": #675c04,
   ),
   // DEPTH COLORS - you can see the elevation colours and shades
   // in the Figma file https://www.figma.com/file/rUrrHGhUBBIAAjQ82x6pz9/PyData-Design-system---proposal-for-implementation-(2)?node-id=1492%3A922&t=sQeQZehkOzposYEg-1

From 4687c7dc787a0cbee890dcd80be3285dffa790dd Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 16 Jun 2023 15:19:46 +0100
Subject: [PATCH 59/64] :wheelchair: Change hover colour to improve contrast

---
 .jupyterlite.doit.db                            | Bin 0 -> 57344 bytes
 .../assets/styles/extensions/_copybutton.scss   |   1 +
 2 files changed, 1 insertion(+)
 create mode 100644 .jupyterlite.doit.db

diff --git a/.jupyterlite.doit.db b/.jupyterlite.doit.db
new file mode 100644
index 0000000000000000000000000000000000000000..017884d61ece3a5e0204a951625777b2a11be0d3
GIT binary patch
literal 57344
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

literal 0
HcmV?d00001

diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_copybutton.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_copybutton.scss
index ce8ebb6d0..be6c887f7 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_copybutton.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_copybutton.scss
@@ -22,6 +22,7 @@ div.highlight button.copybtn {
   &:hover {
     &:not(.success) {
       color: var(--pst-color-text);
+      background-color: var(--pst-color-shadow);
     }
   }
 

From 9405a855fedee531cc3b01004b9d0c4deb3460b4 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Fri, 16 Jun 2023 17:39:07 +0100
Subject: [PATCH 60/64] Update docs to align with system

---
 docs/user_guide/branding.rst  | 3 ++-
 docs/user_guide/extending.rst | 7 ++++---
 docs/user_guide/styling.rst   | 7 ++++---
 3 files changed, 10 insertions(+), 7 deletions(-)

diff --git a/docs/user_guide/branding.rst b/docs/user_guide/branding.rst
index 2154b67dd..46e22b0e1 100644
--- a/docs/user_guide/branding.rst
+++ b/docs/user_guide/branding.rst
@@ -90,7 +90,8 @@ To do so, customize the ``html_teme_options["logo"]["alt_text"]`` configuration
 
    html_theme_options = {
        "logo": {
-           "alt_text": "foo",
+           # It is a good practice to indicate where the logo links to using the alt text such as - Home
+           "alt_text": "foo - Home",
        }
    }
 
diff --git a/docs/user_guide/extending.rst b/docs/user_guide/extending.rst
index 0bc02a842..1e98f29e3 100644
--- a/docs/user_guide/extending.rst
+++ b/docs/user_guide/extending.rst
@@ -69,7 +69,7 @@ The title is specified on the same line as the ``.. admonition::`` directive:
 Styling with semantic color names
 ---------------------------------
 
-You can re-style any admonition to match any of the built-in admonition types using any of the semantic color names as a class (this is most useful for custom-titled admonitions):
+You can re-style any admonition to match any of the built-in admonition types using any of the :ref:`theme's semantic color names <color-variables>` as a class (this is most useful for custom-titled admonitions):
 
 .. begin-example-semantic
 .. admonition:: Custom title with "warning" style
@@ -78,7 +78,7 @@ You can re-style any admonition to match any of the built-in admonition types us
     Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 .. end-example-semantic
 
-Note that it updates both the color and the icon.
+Note that it updates both the color and the icon. See :doc:`./styling` for a list of all semantic color names.
 
 .. tab-set::
 
@@ -104,7 +104,8 @@ Besides the pre-defined semantic color classes (see previous section) you can al
     Lorem ipsum dolor sit amet, consectetur adipiscing elit.
 .. end-example-color
 
-Add the new class to your `custom.css <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files>`__ file. As in the example below, be sure to use the same color for ``border-color``, ``background-color``, and ``color`` (the transparency effect is handled automatically by the theme).
+To do this, you will need to add a class to your `custom.css <https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files>`__ file, as in the example below.
+Be sure to use the same color for ``border-color`` and ``color`` and a different shade for ``background-color``:
 
 .. tab-set::
 
diff --git a/docs/user_guide/styling.rst b/docs/user_guide/styling.rst
index b20aea03b..89ca1eb71 100644
--- a/docs/user_guide/styling.rst
+++ b/docs/user_guide/styling.rst
@@ -17,7 +17,7 @@ Any rules in this style sheet will override the default theme rules.
 
 .. seealso::
 
-   For a more in-depth guide in linking static CSS and JS assets in your site, see {doc}`static_assets`.
+   For a more in-depth guide in linking static CSS and JS assets in your site, see :doc:`static_assets`.
 
 
 To add a custom stylesheet, follow these steps:
@@ -63,9 +63,8 @@ Follow these steps to update the base variables:
    Note that the theme is defined with `CSS variables <css-variable-help_>`_
    and **not** `SASS variables <https://sass-lang.com/documentation/variables>`_.
 
-   Refer to the previous section if
+   Refer to :ref:`the managing themes section in this documentation <manage-themes>`
    you desire a different behavior between the light and dark theme.
-.. TODO: add correct reference to light and dark theme @trallard
 
 For a complete list of the theme variables that you may override, see the
 `theme variables defaults CSS file <pydata-css-variables_>`_:
@@ -85,6 +84,8 @@ For a complete list of the theme variables that you may override, see the
 .. literalinclude:: ../../src/pydata_sphinx_theme/assets/styles/variables/_versionmodified.scss
   :language: scss
 
+.. _color-variables:
+
 Color variables
 ---------------
 

From c0e54db5dd5ae9bfec74d6063ae7f25bce1d2c4f Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 19 Jun 2023 11:33:48 +0100
Subject: [PATCH 61/64] :see_no_evil: Update gitignore file

---
 .gitignore           |   3 +++
 .jupyterlite.doit.db | Bin 57344 -> 0 bytes
 2 files changed, 3 insertions(+)
 delete mode 100644 .jupyterlite.doit.db

diff --git a/.gitignore b/.gitignore
index 8483ed852..a4d763580 100644
--- a/.gitignore
+++ b/.gitignore
@@ -121,3 +121,6 @@ profile.svg
 
 # Compiled translation files (are compiled at build time)
 src/pydata_sphinx_theme/locale/*/*/*.mo
+
+# jupyterlite db
+.jupyterlite.doit.db
diff --git a/.jupyterlite.doit.db b/.jupyterlite.doit.db
deleted file mode 100644
index 017884d61ece3a5e0204a951625777b2a11be0d3..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001

literal 57344
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


From e5830a28fb760cc15688fcfa4dc4e8a4600225d7 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 19 Jun 2023 12:05:25 +0100
Subject: [PATCH 62/64] Apply suggestions from code review

Co-authored-by: Daniel McCloy <dan@mccloy.info>
---
 docs/community/practices/versions.md  |  2 +-
 docs/community/topics/bootstrap.rst   |  2 +-
 docs/user_guide/accessibility.rst     | 11 +++++------
 docs/user_guide/branding.rst          |  6 +++---
 docs/user_guide/fonts.rst             |  2 +-
 docs/user_guide/header-links.rst      |  4 ++--
 docs/user_guide/keyboard-shortcuts.md |  2 +-
 docs/user_guide/layout.rst            |  2 +-
 docs/user_guide/light-dark.rst        |  2 +-
 docs/user_guide/navigation.rst        |  2 +-
 docs/user_guide/styling.rst           |  6 +++---
 docs/user_guide/version-dropdown.rst  |  2 +-
 12 files changed, 21 insertions(+), 22 deletions(-)

diff --git a/docs/community/practices/versions.md b/docs/community/practices/versions.md
index 917d08e2a..18d7a7364 100644
--- a/docs/community/practices/versions.md
+++ b/docs/community/practices/versions.md
@@ -14,7 +14,7 @@ We define "support" as testing against each of these versions so that users can
 For example, if we made a minor release tomorrow, we'd [look at the EOL schedule for Python](https://endoflife.date/python) and support all the versions that fall within a 3.5-year window.
 
 [^1]: Our support for Python versions is inspired by [NEP 029](https://numpy.org/neps/nep-0029-deprecation_policy.html).
-[^2]: These policies are goals, but no promises. We are a volunteer-led community with limited time. Consider these sections to be our intention, but we recognize that we may not always be able to meet these criteria if we cannot do so. We welcome contributions from others to help us more sustainably meet these goals!
+[^2]: These policies are goals, not promises. We are a volunteer-led community with limited time. Consider these sections to be our intention, but we recognize that we may not always be able to meet these criteria if we cannot do so. We welcome contributions from others to help us more sustainably meet these goals!
 
 ## Supported Sphinx versions
 
diff --git a/docs/community/topics/bootstrap.rst b/docs/community/topics/bootstrap.rst
index 3a61ef249..c8e87aa6b 100644
--- a/docs/community/topics/bootstrap.rst
+++ b/docs/community/topics/bootstrap.rst
@@ -57,4 +57,4 @@ Utilities
 JavaScript
 ^^^^^^^^^^
 
--   Data attributes for all JavaScript plugins are now name spaced to help distinguish Bootstrap functionality from third parties and your code. For example, we use ``data-bs-toggle`` instead of ``data-toggle``.
+-   Data attributes for all JavaScript plugins are now namespaced to help distinguish Bootstrap functionality from third parties and your code. For example, we use ``data-bs-toggle`` instead of ``data-toggle``.
diff --git a/docs/user_guide/accessibility.rst b/docs/user_guide/accessibility.rst
index 09e616fba..5e4a26d00 100644
--- a/docs/user_guide/accessibility.rst
+++ b/docs/user_guide/accessibility.rst
@@ -66,7 +66,7 @@ identify if the content is in a language the reader understands.
 
 .. Hint::
 
-    Specifying a ``language`` will propagate to the top-level `HTML` tag.
+    Specifying a ``language`` will propagate to the top-level ``HTML`` tag.
 
     .. code-block:: Python
 
@@ -114,7 +114,7 @@ If you have a logo, you can add alt-text to it by adding the following to your
       "alt_text": "PyData Theme home",
   },
 
-Note the use of `home` to indicate that the logo is also a link to the home page.
+Note the use of "home" in the alt text to indicate that the logo is also a link to the home page.
 
 In the Browser
 ==============
@@ -128,10 +128,9 @@ Built-in tools
 
 
 Most major browsers, including `Firefox <https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector>`__
-and `Chrome <https://developers.google.com/web/tools/chrome-devtools/accessibility/reference>`__
-include significant accessibility tooling in their development experience. Exploring
-these, and the modes they offer can help to quickly pinpoint issues and often
-include links to standards.
+and `Chrome <https://developers.google.com/web/tools/chrome-devtools/accessibility/reference>`__,
+have accessibility tools built-in as part of their web developer tools.
+These tools can help to quickly identify accessibility issues and often include links to standards.
 
 
 tota11y
diff --git a/docs/user_guide/branding.rst b/docs/user_guide/branding.rst
index 46e22b0e1..43402e8b6 100644
--- a/docs/user_guide/branding.rst
+++ b/docs/user_guide/branding.rst
@@ -83,15 +83,15 @@ Customize logo alternative text
 You may set a custom ``alt text`` for your logo to replace the default ``"logo image"`` generic description.
 Adding a descriptive ``alt text`` can help make your documentation more accessible to readers using screen readers or another assistive tech.
 
-To do so, customize the ``html_teme_options["logo"]["alt_text"]`` configuration option as in the following example:
+To do so, customize the ``html_theme_options["logo"]["alt_text"]`` configuration option as in the following example:
 
 .. code-block:: python
    :caption: conf.py
 
    html_theme_options = {
        "logo": {
-           # It is a good practice to indicate where the logo links to using the alt text such as - Home
-           "alt_text": "foo - Home",
+           # Because the logo is also a homepage link, including "home" in the alt text is good practice
+           "alt_text": "My Project Name - Home",
        }
    }
 
diff --git a/docs/user_guide/fonts.rst b/docs/user_guide/fonts.rst
index 0b36f3f94..eafb4b323 100644
--- a/docs/user_guide/fonts.rst
+++ b/docs/user_guide/fonts.rst
@@ -9,7 +9,7 @@ available system fonts for normal body text and headers.
 
 The default body and header fonts can be changed as follows:
 
-- Using:ref:`custom-css`, you can specify which fonts to use for the body, header,
+- Using :ref:`custom-css`, you can specify which fonts to use for the body, header,
   and monospaced text. For example, the following can be added to a custom
   CSS file:
 
diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst
index be2e72238..6b410f1ce 100644
--- a/docs/user_guide/header-links.rst
+++ b/docs/user_guide/header-links.rst
@@ -30,7 +30,7 @@ It will place the remaining header links in a **dropdown menu** titled "More".
 This prevents the header links from taking up so much space that they crowd out the UI components or spill off-screen.
 
 To control how many header links are displayed before being placed in the dropdown, use the ``header_links_before_dropdown`` theme configuration variable.
-For example, to change the number of displayed header links to be ``4`` instead of ``5``:abbr:
+For example, to change the number of displayed header links to be ``4`` instead of ``5``:
 
 .. code-block:: python
 
@@ -116,7 +116,7 @@ Here are several examples:
                "name": "Twitter",
                "url": "https://twitter.com/<your-handle>",
                "icon": "fa-brands fa-square-twitter",
-               # The default for `type` is `fontawesome`, so it is not required in any of the above examples as it shown here
+               # The default for `type` is `fontawesome`, so it is not required in the above examples
            },
            {
                "name": "Mastodon",
diff --git a/docs/user_guide/keyboard-shortcuts.md b/docs/user_guide/keyboard-shortcuts.md
index e317f2dca..c163d47d4 100644
--- a/docs/user_guide/keyboard-shortcuts.md
+++ b/docs/user_guide/keyboard-shortcuts.md
@@ -2,7 +2,7 @@
 
 ## Trigger the search bar
 
-You can trigger the search bar pop-up with <kbd>Ctrl</kbd>/<kbd>⌘</kbd> + <kbd>K</kbd>.
+You can trigger the search bar pop-up with {kbd}`Ctrl`/{kbd}`⌘` + {kbd}`K`.
 
 ## Change pages
 
diff --git a/docs/user_guide/layout.rst b/docs/user_guide/layout.rst
index 8f3596fd8..018f32679 100644
--- a/docs/user_guide/layout.rst
+++ b/docs/user_guide/layout.rst
@@ -212,7 +212,7 @@ Templates and components
 ========================
 
 There are a few major theme sections that you can customize to add/remove
-components or add your components. Each section is configured with a
+built-in components or add your own components. Each section is configured with a
 list of *HTML templates* — these are snippets of HTML that are inserted into
 the section by Sphinx.
 
diff --git a/docs/user_guide/light-dark.rst b/docs/user_guide/light-dark.rst
index 58d64ed0d..bfb6ea88f 100644
--- a/docs/user_guide/light-dark.rst
+++ b/docs/user_guide/light-dark.rst
@@ -4,7 +4,7 @@
 Light and dark themes
 =====================
 
-You can change the major background/foreground colors of this theme according to the "dark" and "light" modes.
+You can change the major background/foreground colors of this theme using built-in "dark" and "light" modes.
 These are controlled by a button in the navigation header, with the following options:
 
 - A ``light`` theme with a bright background and dark text / UI elements
diff --git a/docs/user_guide/navigation.rst b/docs/user_guide/navigation.rst
index 8d219d5b4..ee59cb424 100644
--- a/docs/user_guide/navigation.rst
+++ b/docs/user_guide/navigation.rst
@@ -3,7 +3,7 @@
 Navigation depth and collapsing sidebars
 ========================================
 
-By default, this theme enables to expand/collapse of subsections in the primary
+By default, this theme allows expanding/collapsing subsections in the primary
 sidebar navigation (without actually navigating to the page itself), and this extends
 up to 4 levels deep:
 
diff --git a/docs/user_guide/styling.rst b/docs/user_guide/styling.rst
index 89ca1eb71..3e2df90a2 100644
--- a/docs/user_guide/styling.rst
+++ b/docs/user_guide/styling.rst
@@ -63,7 +63,7 @@ Follow these steps to update the base variables:
    Note that the theme is defined with `CSS variables <css-variable-help_>`_
    and **not** `SASS variables <https://sass-lang.com/documentation/variables>`_.
 
-   Refer to :ref:`the managing themes section in this documentation <manage-themes>`
+   Refer to :ref:`the managing themes section in this documentation <manage-themes>` if
    you desire a different behavior between the light and dark theme.
 
 For a complete list of the theme variables that you may override, see the
@@ -119,7 +119,7 @@ Here is an overview of the colors available in the theme (change theme mode to s
     <p>
       <span class="sd-sphinx-override sd-badge pst-badge pst-primary sd-bg-text-primary">primary</span>
       <span class="sd-sphinx-override sd-badge pst-badge pst-secondary sd-bg-text-secondary">secondary</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-accent sd-bg-text-secondary">secondary</span>
+      <span class="sd-sphinx-override sd-badge pst-badge pst-accent sd-bg-text-secondary">accent</span>
       <span class="sd-sphinx-override sd-badge pst-badge pst-success sd-bg-text-success">success</span>
       <span class="sd-sphinx-override sd-badge pst-badge pst-info sd-bg-text-info">info</span>
       <span class="sd-sphinx-override sd-badge pst-badge pst-warning sd-bg-text-warning">warning</span>
@@ -128,7 +128,7 @@ Here is an overview of the colors available in the theme (change theme mode to s
       <span class="sd-sphinx-override sd-badge pst-badge pst-on-background">on-background</span>
       <span class="sd-sphinx-override sd-badge pst-badge pst-surface">surface</span>
       <span class="sd-sphinx-override sd-badge pst-badge pst-on-surface sd-bg-text-primary">on-surface</span>
-      <span class="sd-sphinx-override sd-badge pst-badge pst-target sd-bg-text-primary">target</span>
+      <span class="sd-sphinx-override sd-badge pst-badge pst-target">target</span>
     </p>
 
 
diff --git a/docs/user_guide/version-dropdown.rst b/docs/user_guide/version-dropdown.rst
index 7bbf6dcbf..2502a99c4 100644
--- a/docs/user_guide/version-dropdown.rst
+++ b/docs/user_guide/version-dropdown.rst
@@ -7,7 +7,7 @@ switcher will differ depending on which page of the docs is being viewed. For
 example, on the page ``https://mysite.org/en/v2.0/changelog.html``, the
 switcher links will go to ``changelog.html`` in the other versions of your
 docs. When clicked, the switcher will check for the existence of that page, and
-if it doesn't exist, redirect to the homepage of that docs' version instead.
+if it doesn't exist, will redirect to the homepage instead (in the requested version of the docs).
 
 The switcher requires the following configuration steps:
 

From 559b1f789df45b1ce7783f3d02e64840ce3d14b8 Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 19 Jun 2023 14:36:22 +0100
Subject: [PATCH 63/64] :bug: Use correct variable names

---
 .../assets/styles/content/_admonitions.scss                   | 2 +-
 .../assets/styles/extensions/_sphinx_design.scss              | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss b/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
index e1822c721..a71490580 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
@@ -162,7 +162,7 @@ div.admonition,
     border-color: var(--pst-color-attention);
     > .admonition-title {
       &:before {
-        background-color: var(--pst-color-warning-bg);
+        background-color: var(--pst-color-attention-bg);
       }
 
       &:after {
diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
index 534e97631..c18935846 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_sphinx_design.scss
@@ -69,12 +69,12 @@ $all-colors: map-merge($pst-semantic-colors, $extra-semantic-colors);
   // we are now using a11y-combination to calculate the text color - this is based
   // on the WCAG color contrast guidelines
   --pst-color-#{$name}-text: #{a11y-combination($value)};
-  // // TODO: check where highlight is used
+  //TODO: highlight seems to be used for buttons @trallard to fix on a11y follow-up work
   --pst-color-#{$name}-highlight: #{darken($value, 15%)};
   // override the sphinx-design variables
   --sd-color-#{$name}: var(--pst-color-#{$name});
   --sd-color-#{$name}-text: var(--pst-color-#{$name}-text);
-  // TODO: check where highlight is used
+  //TODO: highlight seems to be used for buttons @trallard to fix on a11y follow-up work
   --sd-color-#{$name}-highlight: var(--pst-color-#{$name}-highlight);
 }
 

From d3cdc27463c75202dabb0046b78a46171778f36b Mon Sep 17 00:00:00 2001
From: Tania Allard <taniar.allard@gmail.com>
Date: Mon, 19 Jun 2023 19:50:26 +0100
Subject: [PATCH 64/64] Fix title colour in custom admonitions

---
 docs/_static/custom.css | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/_static/custom.css b/docs/_static/custom.css
index 9c7671efe..dea2ff828 100644
--- a/docs/_static/custom.css
+++ b/docs/_static/custom.css
@@ -33,6 +33,9 @@ div.admonition.admonition-olive > .admonition-title:before {
 div.admonition.admonition-olive > .admonition-title:after {
   color: hsl(60, 100%, 25%);
 }
+div.admonition.admonition-olive > .admonition-title {
+  color: white;
+}
 /* end-custom-color */
 
 /* begin-custom-icon/* <your static path>/custom.css */
@@ -54,4 +57,7 @@ div.admonition.admonition-youtube > .admonition-title:after {
   color: hsl(0, 100%, 50%);
   content: "\f26c"; /* fa-solid fa-tv */
 }
+div.admonition.admonition-youtube > .admonition-title {
+  color: white;
+}
 /* end-custom-youtube */