diff --git a/docs/user_guide/customizing.rst b/docs/user_guide/customizing.rst
index 4cea9bcd7b..23c40d63cf 100644
--- a/docs/user_guide/customizing.rst
+++ b/docs/user_guide/customizing.rst
@@ -27,7 +27,7 @@ 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``
 
-   .. code-block:: rst
+   .. code-block:: python
 
        html_static_path = ['_static']
 
@@ -141,11 +141,13 @@ CSS Theme variables
 ===================
 
 This theme defines several `CSS variables <css-variable-help_>`_ that can be
-used to quickly control behavior across your documentation.
+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. An overview of all variables and
-every default is defined in `the pydata default CSS variables file <pydata-css-variables_>`_.
+extended with some theme specific variables.
+
+base variables
+--------------
 
 In order to change a variable, follow these steps:
 
@@ -153,7 +155,7 @@ In order to change a variable, follow these steps:
 2. Underneath a ``:root`` section, add the variables you wish to update. For example, to update
    the base font size, you might add this to ``custom.css``:
 
-   .. code-block:: none
+   .. code-block:: css
 
        :root {
            --pst-font-size-base: 17px;
@@ -172,6 +174,31 @@ For a complete list of the theme variables that you may override, see the
 .. literalinclude:: ../../src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static/styles/theme.css
   :language: CSS
 
+Color variables
+---------------
+
+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.
+
+You can control the colors used for these variables for each theme by
+:ref:`adding a custom CSS stylesheet <custom-css>` and adding a structure like so:
+
+.. code-block:: css
+
+    html[data-theme="light"] {
+        --pst-color-primary: black;
+    }
+
+    html[data-theme="dark"] {
+        --pst-color-primary: white;
+    }
+
+For a complete list of the theme colors that you may override, see the
+`color variables defaults CSS file <pydata-css-colors_>`_:
+
+.. literalinclude:: ../../src/pydata_sphinx_theme/assets/styles/base/_color.scss
+  :language: scss
+
 Change footer display
 =====================
 
@@ -253,7 +280,7 @@ The default body and header fonts can be changed as follows:
     before waiting for the CSS to be parsed, but should be used with care.
 
 .. _pydata-css-variables: https://github.com/pydata/pydata-sphinx-theme/blob/master/src/pydata_sphinx_theme/theme/pydata_sphinx_theme/static/styles/theme.css
-.. _pydata-css-colors: https://github.com/pydata/pydata-sphinx-theme/blob/master/src/pydata_sphinx_theme/assets/style/color.scss
+.. _pydata-css-colors: https://github.com/pydata/pydata-sphinx-theme/blob/master/src/pydata_sphinx_theme/assets/styles/base/_color.scss
 .. _css-variable-help: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
 
 .. meta::
diff --git a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
index a443016800..8acab804f1 100644
--- a/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
+++ b/src/pydata_sphinx_theme/assets/styles/abstracts/_mixins.scss
@@ -11,7 +11,7 @@
   }
 
   &::-webkit-scrollbar-thumb {
-    background: var(--pst-color-deactivate);
+    background: var(--pst-color-text-muted);
     border-radius: 0.25rem;
   }
 
diff --git a/src/pydata_sphinx_theme/assets/styles/base/_base.scss b/src/pydata_sphinx_theme/assets/styles/base/_base.scss
index 9eeb754c07..1375fce394 100644
--- a/src/pydata_sphinx_theme/assets/styles/base/_base.scss
+++ b/src/pydata_sphinx_theme/assets/styles/base/_base.scss
@@ -24,7 +24,7 @@ body {
 p {
   margin-bottom: 1.15rem;
   font-size: 1em;
-  color: var(--pst-color-paragraph);
+  color: var(--pst-color-text-base);
 
   /* section header in docstring pages */
   &.rubric {
@@ -46,7 +46,7 @@ a {
   }
 
   &.headerlink {
-    color: var(--pst-color-headerlink);
+    color: var(--pst-color-danger);
     opacity: 0.4;
     font-size: 0.8em;
     padding: 0 4px 0 4px;
@@ -72,37 +72,37 @@ h1 {
   @extend .heading-style;
   margin-top: 0;
   font-size: var(--pst-font-size-h1);
-  color: var(--pst-color-h1);
+  color: var(--pst-color-primary);
 }
 
 h2 {
   @extend .heading-style;
   font-size: var(--pst-font-size-h2);
-  color: var(--pst-color-h2);
+  color: var(--pst-color-primary);
 }
 
 h3 {
   @extend .heading-style;
   font-size: var(--pst-font-size-h3);
-  color: var(--pst-color-h3);
+  color: var(--pst-color-text-base);
 }
 
 h4 {
   @extend .heading-style;
   font-size: var(--pst-font-size-h4);
-  color: var(--pst-color-h4);
+  color: var(--pst-color-text-base);
 }
 
 h5 {
   @extend .heading-style;
   font-size: var(--pst-font-size-h5);
-  color: var(--pst-color-h5);
+  color: var(--pst-color-text-base);
 }
 
 h6 {
   @extend .heading-style;
   font-size: var(--pst-font-size-h6);
-  color: var(--pst-color-h6);
+  color: var(--pst-color-text-base);
 }
 
 small,
@@ -122,6 +122,12 @@ samp {
   font-family: var(--pst-font-family-monospace);
 }
 
+kbd {
+  // use theme negative
+  background-color: var(--pst-color-text-base);
+  color: var(--pst-color-background);
+}
+
 code {
   color: var(--pst-color-inline-code);
 }
@@ -129,12 +135,12 @@ code {
 pre {
   margin: 1.5em 0 1.5em 0;
   padding: 10px;
-  background-color: var(--pst-color-preformatted-background);
-  color: var(--pst-color-preformatted-text);
+  background-color: var(--pst-color-surface);
+  color: var(--pst-color-text-base);
   line-height: 1.2em;
-  border: 1px solid var(--pst-color-preformatted-border);
+  border: 1px solid var(--pst-color-border);
   border-radius: 0.2rem;
-  box-shadow: 1px 1px 1px var(--pst-color-preformatted-shadow);
+  box-shadow: 1px 1px 1px var(--pst-color-shadow);
 
   @include scrollbar-style();
   @include scrollbar-on-hover();
diff --git a/src/pydata_sphinx_theme/assets/styles/base/_color.scss b/src/pydata_sphinx_theme/assets/styles/base/_color.scss
index 94b2209396..68d3d1bb89 100644
--- a/src/pydata_sphinx_theme/assets/styles/base/_color.scss
+++ b/src/pydata_sphinx_theme/assets/styles/base/_color.scss
@@ -5,93 +5,30 @@
 */
 html[data-theme="light"] {
   /*****************************************************************************
-  * colors
+  * main colors
   */
-
-  // main colors
   --pst-color-primary: rgb(19, 6, 84);
   --pst-color-success: rgb(40, 167, 69);
-  --pst-color-info: rgb(0, 123, 255); /*23, 162, 184;*/
+  --pst-color-info: rgb(0, 123, 255);
   --pst-color-warning: rgb(255, 193, 7);
   --pst-color-danger: rgb(220, 53, 69);
   --pst-color-text-base: rgb(51, 51, 51);
-  --pst-color-background: rgb(255, 255, 255);
-  --pst-color-background-up: rgb(240, 240, 240); // for 3D effects
-  --pst-color-background-up-up: rgb(255, 255, 238); // for 3D effects
-  --pst-color-deactivate: rgb(77, 77, 77);
+  --pst-color-text-muted: rgb(77, 77, 77);
   --pst-color-border: rgb(201, 201, 201);
   --pst-color-shadow: rgb(216, 216, 216);
 
-  // headers
-  --pst-color-h1: var(--pst-color-primary);
-  --pst-color-h2: var(--pst-color-primary);
-  --pst-color-h3: var(--pst-color-text-base);
-  --pst-color-h4: var(--pst-color-text-base);
-  --pst-color-h5: var(--pst-color-text-base);
-  --pst-color-h6: var(--pst-color-text-base);
-  --pst-color-paragraph: var(--pst-color-text-base);
-
-  // links
-  --pst-color-link: rgb(0, 91, 129);
-  --pst-color-link-hover: rgb(227, 46, 0);
-  --pst-color-target: rgb(251, 229, 78);
-
-  // headerlinks (the anchors at the end of titles)
-  --pst-color-headerlink: rgb(198, 15, 15);
-
-  // navigation
-  --pst-color-active-navigation: var(--pst-color-primary);
-  --pst-color-deactive-navigation: var(--pst-color-deactivate);
-
-  /*****************************************************************************
-  * roles
-  */
-
-  // inline code
-  --pst-color-inline-code: rgb(232, 62, 140);
-
-  // guilabel
-  --pst-color-guilabel-background: rgb(231, 242, 250);
-  --pst-color-guilabel-border: rgb(127, 187, 227);
-  --pst-color-guilabel-text: var(--pst-color-guilabel-border);
-
-  // kbd
-  --pst-color-kbd-text: rgb(255, 255, 255);
-  --pst-color-kbd-background: rgb(33, 37, 41);
-
   /*****************************************************************************
-  * directives
+  * depth colors
+  *
+  * background: the more in depth color
+  * on-background: the object directly set on the background, use of shadows in light theme
+  * surface: object set on the background (without shadows)
+  * on_surface: object set on surface object (without shadows)
   */
-
-  // admonitions
-  --pst-color-admonition-default: var(--pst-color-info);
-  --pst-color-admonition-note: var(--pst-color-info);
-  --pst-color-admonition-attention: var(--pst-color-warning);
-  --pst-color-admonition-caution: var(--pst-color-warning);
-  --pst-color-admonition-warning: var(--pst-color-warning);
-  --pst-color-admonition-danger: var(--pst-color-danger);
-  --pst-color-admonition-error: var(--pst-color-danger);
-  --pst-color-admonition-hint: var(--pst-color-success);
-  --pst-color-admonition-tip: var(--pst-color-success);
-  --pst-color-admonition-important: var(--pst-color-success);
-  --pst-color-admonition-background: var(--pst-color-background);
-  --pst-color-admonition-shadow: var(--pst-color-shadow);
-
-  // viersion modified
-  --pst-color-versionmodified-default: var(--pst-color-info);
-  --pst-color-versionmodified-added: var(--pst-color-success);
-  --pst-color-versionmodified-changed: var(--pst-color-warning);
-  --pst-color-versionmodified-deprecated: var(--pst-color-danger);
-
-  // preformatted
-  --pst-color-preformatted-text: rgb(34, 34, 34);
-  --pst-color-preformatted-border: var(--pst-color-border);
-  --pst-color-preformatted-background: var(--pst-color-background-up);
-  --pst-color-preformatted-shadow: var(--pst-color-shadow);
-
-  // targeted viewcode
-  --pst-color-viewcode-target-border: rgb(170, 204, 153);
-  --pst-color-viewcode-target-background: rgb(244, 222, 191);
+  --pst-color-background: rgb(255, 255, 255);
+  --pst-color-on-background: rgb(255, 255, 255);
+  --pst-color-surface: rgb(240, 240, 240);
+  --pst-color-on-surface: rgb(255, 255, 238);
 
   /*****************************************************************************
   * extentions
@@ -103,52 +40,15 @@ html[data-theme="light"] {
   * layout
   */
 
-  // navbar
-  --pst-color-navbar-background: var(--pst-color-background);
-  --pst-color-navbar-link: var(--pst-color-deactivate);
-  --pst-color-navbar-link-hover: var(--pst-color-active-navigation);
-  --pst-color-navbar-link-active: var(--pst-color-active-navigation);
-
-  // toc
-  --pst-color-toc-link: var(--pst-color-deactivate);
-  --pst-color-toc-link-hover: var(--pst-color-active-navigation);
-  --pst-color-toc-link-active: var(--pst-color-active-navigation);
-  --pst-color-toc-border: var(--pst-color-border);
-
-  // sidebar
-  --pst-color-sidebar-link: var(--pst-color-deactivate);
-  --pst-color-sidebar-link-hover: var(--pst-color-active-navigation);
-  --pst-color-sidebar-link-active: var(--pst-color-active-navigation);
-  --pst-color-sidebar-expander-background-hover: var(--pst-color-background-up);
-  --pst-color-sidebar-caption: var(--pst-color-text-base);
-  --pst-color-sidebar-border: var(--pst-color-border);
-
-  // footer
-  --pst-color-footer-border: var(--pst-color-border);
-
-  // alert
-  // higher contrast of links in info boxes
-  --pst-color-alert-link: rgb(232, 62, 140);
-
-  // prev-next
-  --pst-color-prev-next: var(--pst-color-primary);
-  --pst-color-prev-next-btn: var(--pst-color-deactivate);
-
-  // search
-  --pst-color-search-background: var(--pst-color-background);
-  --pst-color-search: var(--pst-color-border);
-  --pst-color-search-border: var(--pst-color-border);
-
-  // ethical ad
-  --pst-color-ad-text: var(--pst-color-text-base);
-  --pst-color-ad-background: var(--pst-color-background);
-  --pst-color-ad-border: var(--pst-color-border);
+  // links
+  --pst-color-link: rgb(0, 91, 129);
+  --pst-color-link-hover: rgb(227, 46, 0);
 
-  // navbar-toogler
-  --pst-color-navbar-toggler: var(--pst-color-deactivate);
+  // inline code
+  --pst-color-inline-code: rgb(232, 62, 140);
 
-  // blockquote
-  --pst-color-blockquote-border: rgb(221, 221, 221);
+  // targeted content
+  --pst-color-target: rgb(251, 229, 78);
 
   // hide any content that should not be displayed in the light theme
   .only-dark {
@@ -163,93 +63,30 @@ html[data-theme="light"] {
 */
 html[data-theme="dark"] {
   /*****************************************************************************
-  * theme colors
+  * main colors
   */
-
-  // main colors
   --pst-color-primary: rgb(76, 145, 219);
   --pst-color-success: rgb(72, 135, 87);
   --pst-color-info: rgb(64, 125, 191);
   --pst-color-warning: rgb(193, 162, 69);
   --pst-color-danger: rgb(203, 70, 83);
   --pst-color-text-base: rgb(201, 209, 217);
-  --pst-color-background: rgb(18, 18, 18);
-  --pst-color-background-up: rgb(22, 22, 22); // for 3D effect in dark theme
-  --pst-color-background-up-up: rgb(55, 55, 55); // for 3D effects
-  --pst-color-deactivate: rgb(192, 192, 192);
-  --pst-color-border: var(--pst-color-deactivate);
+  --pst-color-text-muted: rgb(192, 192, 192);
+  --pst-color-border: rgb(192, 192, 192);
   --pst-color-shadow: var(--pst-color-background);
 
-  // headers
-  --pst-color-h1: var(--pst-color-primary);
-  --pst-color-h2: var(--pst-color-primary);
-  --pst-color-h3: var(--pst-color-text-base);
-  --pst-color-h4: var(--pst-color-text-base);
-  --pst-color-h5: var(--pst-color-text-base);
-  --pst-color-h6: var(--pst-color-text-base);
-  --pst-color-paragraph: var(--pst-color-text-base);
-
-  // links
-  --pst-color-link: var(--pst-color-primary);
-  --pst-color-link-hover: rgb(170, 103, 196);
-  --pst-color-target: rgb(71, 39, 0);
-
-  // headerlinks (the anchors at the end of titles)
-  --pst-color-headerlink: rgb(221, 90, 90);
-
-  // navigation
-  --pst-color-active-navigation: var(--pst-color-primary);
-  --pst-color-deactive-navigation: var(--pst-color-deactivate);
-
-  /*****************************************************************************
-  * roles
-  */
-
-  // inline code
-  --pst-color-inline-code: rgb(221, 158, 194);
-
-  // guilabel
-  --pst-color-guilabel-background: rgb(242, 196, 166);
-  --pst-color-guilabel-border: rgb(83, 56, 38);
-  --pst-color-guilabel-text: var(--pst-color-guilabel-border);
-
-  // kbd
-  --pst-color-kbd-text: rgb(33, 37, 41);
-  --pst-color-kbd-background: rgb(245, 245, 245);
-
   /*****************************************************************************
-  * directives
+  * depth colors
+  *
+  * background: the more in depth color
+  * on-background: the object directly set on the background, use of a light grey in dark theme
+  * surface: object set on the background (without shadows)
+  * on_surface: object set on surface object (without shadows)
   */
-
-  // admonitions
-  --pst-color-admonition-default: var(--pst-color-info);
-  --pst-color-admonition-note: var(--pst-color-info);
-  --pst-color-admonition-attention: var(--pst-color-warning);
-  --pst-color-admonition-caution: var(--pst-color-warning);
-  --pst-color-admonition-warning: var(--pst-color-warning);
-  --pst-color-admonition-danger: var(--pst-color-danger);
-  --pst-color-admonition-error: var(--pst-color-danger);
-  --pst-color-admonition-hint: var(--pst-color-success);
-  --pst-color-admonition-tip: var(--pst-color-success);
-  --pst-color-admonition-important: var(--pst-color-success);
-  --pst-color-admonition-background: var(--pst-color-background-up);
-  --pst-color-admonition-shadow: var(--pst-color-shadow);
-
-  // viersion modified
-  --pst-color-versionmodified-default: var(--pst-color-info);
-  --pst-color-versionmodified-added: var(--pst-color-success);
-  --pst-color-versionmodified-changed: var(--pst-color-warning);
-  --pst-color-versionmodified-deprecated: var(--pst-color-danger);
-
-  // preformatted
-  --pst-color-preformatted-text: rgb(210, 210, 210);
-  --pst-color-preformatted-border: rgb(83, 83, 83);
-  --pst-color-preformatted-background: var(--pst-color-background-up);
-  --pst-color-preformatted-shadow: var(--pst-color-shadow);
-
-  // targeted viewcode
-  --pst-color-viewcode-target-border: rgb(170, 204, 153);
-  --pst-color-viewcode-target-background: rgb(35, 55, 83);
+  --pst-color-background: rgb(18, 18, 18);
+  --pst-color-on-background: rgb(30, 30, 30);
+  --pst-color-surface: rgb(41, 41, 41);
+  --pst-color-on-surface: rgb(55, 55, 55);
 
   /*****************************************************************************
   * extentions
@@ -261,51 +98,15 @@ html[data-theme="dark"] {
   * layout
   */
 
-  // navbar
-  --pst-color-navbar-background: var(--pst-color-background-up);
-  --pst-color-navbar-link: var(--pst-color-deactivate);
-  --pst-color-navbar-link-hover: var(--pst-color-active-navigation);
-  --pst-color-navbar-link-active: var(--pst-color-active-navigation);
-
-  // toc
-  --pst-color-toc-link: var(--pst-color-deactivate);
-  --pst-color-toc-link-hover: var(--pst-color-active-navigation);
-  --pst-color-toc-link-active: var(--pst-color-active-navigation);
-  --pst-color-toc-border: var(--pst-color-border);
-
-  // sidebar
-  --pst-color-sidebar-link: var(--pst-color-deactivate);
-  --pst-color-sidebar-link-hover: var(--pst-color-active-navigation);
-  --pst-color-sidebar-link-active: var(--pst-color-active-navigation);
-  --pst-color-sidebar-expander-background-hover: var(--pst-color-background-up);
-  --pst-color-sidebar-caption: var(--pst-color-text-base);
-  --pst-color-sidebar-border: var(--pst-color-border);
-
-  // footer
-  --pst-color-footer-border: var(--pst-color-border);
-
-  // alert
-  --pst-color-alert-link: rgb(232, 62, 140); // higher contrast of links
-
-  // prev-next
-  --pst-color-prev-next: var(--pst-color-link);
-  --pst-color-prev-next-btn: var(--pst-color-deactivate);
-
-  // search
-  --pst-color-search-background: var(--pst-color-background);
-  --pst-color-search: var(--pst-color-border);
-  --pst-color-search-border: var(--pst-color-border);
-
-  // ethical ad
-  --pst-color-ad-text: var(--pst-color-text-base);
-  --pst-color-ad-background: var(--pst-color-background);
-  --pst-color-ad-border: var(--pst-color-border);
+  // links
+  --pst-color-link: var(--pst-color-primary);
+  --pst-color-link-hover: rgb(170, 103, 196);
 
-  // navbar-toogler
-  --pst-color-navbar-toggler: var(--pst-color-deactivate);
+  // inline code
+  --pst-color-inline-code: rgb(221, 158, 194);
 
-  // blockquote
-  --pst-color-blockquote-border: rgb(117, 117, 117);
+  // targeted content
+  --pst-color-target: rgb(71, 39, 0);
 
   // hide any content that should not be displayed in the dark theme
   .only-light {
diff --git a/src/pydata_sphinx_theme/assets/styles/components/_prev-next.scss b/src/pydata_sphinx_theme/assets/styles/components/_prev-next.scss
index d423e55182..a24cb91a07 100644
--- a/src/pydata_sphinx_theme/assets/styles/components/_prev-next.scss
+++ b/src/pydata_sphinx_theme/assets/styles/components/_prev-next.scss
@@ -19,11 +19,11 @@
     padding: 10px;
     max-width: 45%;
     overflow-x: hidden;
-    color: var(--pst-color-prev-next-btn);
+    color: var(--pst-color-text-muted);
     text-decoration: none;
 
     p.prev-next-title {
-      color: var(--pst-color-prev-next);
+      color: var(--pst-color-primary);
       font-weight: 600;
       font-size: 1.1em;
     }
diff --git a/src/pydata_sphinx_theme/assets/styles/components/_search.scss b/src/pydata_sphinx_theme/assets/styles/components/_search.scss
index 1cd2602e42..595327b092 100644
--- a/src/pydata_sphinx_theme/assets/styles/components/_search.scss
+++ b/src/pydata_sphinx_theme/assets/styles/components/_search.scss
@@ -6,27 +6,27 @@
 
   .icon {
     position: absolute;
-    color: var(--pst-color-search);
+    color: var(--pst-color-border);
     left: 25px;
   }
 
   input {
-    background-color: var(--pst-color-search-background);
+    background-color: var(--pst-color-background);
     border-radius: 0.2rem;
-    border: 1px solid var(--pst-color-search-border);
+    border: 1px solid var(--pst-color-border);
     padding-left: 35px;
     color: var(--pst-color-text-base);
 
     // Inner-text of the search bar
     &::placeholder {
-      color: var(--pst-color-search);
+      color: var(--pst-color-border);
     }
 
     // Background should always be same color regardless of active or nor
     &:active,
     &:focus {
-      background-color: var(--pst-color-search-background);
-      color: var(--pst-color-search);
+      background-color: var(--pst-color-background);
+      color: var(--pst-color-border);
     }
   }
 }
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 b77f7c6b12..1463cf7b00 100644
--- a/src/pydata_sphinx_theme/assets/styles/components/_switcher-theme.scss
+++ b/src/pydata_sphinx_theme/assets/styles/components/_switcher-theme.scss
@@ -1,19 +1,18 @@
 // the icons for theme change
 #theme-switch {
-  border-color: var(--pst-color-navbar-link-hover);
+  border-color: var(--pst-color-primary);
   margin-right: 0.4rem;
 
   a {
-    color: var(--pst-color-navbar-link-hover);
+    color: var(--pst-color-primary);
     display: none;
   }
 
   &:hover {
-    border-color: var(--pst-color-navbar-background);
-    background-color: var(--pst-color-navbar-link-hover);
+    background-color: var(--pst-color-primary);
 
     a {
-      color: var(--pst-color-navbar-background);
+      color: var(--pst-color-on-background);
     }
   }
 }
diff --git a/src/pydata_sphinx_theme/assets/styles/components/_switcher-version.scss b/src/pydata_sphinx_theme/assets/styles/components/_switcher-version.scss
index 6e93303d05..3189bf6a2c 100644
--- a/src/pydata_sphinx_theme/assets/styles/components/_switcher-version.scss
+++ b/src/pydata_sphinx_theme/assets/styles/components/_switcher-version.scss
@@ -1,4 +1,4 @@
 #version_switcher_button {
-  background-color: var(--pst-color-active-navigation);
-  border-color: var(--pst-color-active-navigation);
+  background-color: var(--pst-color-primary);
+  border-color: var(--pst-color-primary);
 }
diff --git a/src/pydata_sphinx_theme/assets/styles/components/_versionmodified.scss b/src/pydata_sphinx_theme/assets/styles/components/_versionmodified.scss
index 50408b3415..ba4fbee3ea 100644
--- a/src/pydata_sphinx_theme/assets/styles/components/_versionmodified.scss
+++ b/src/pydata_sphinx_theme/assets/styles/components/_versionmodified.scss
@@ -7,18 +7,19 @@ div.deprecated {
   overflow: hidden;
   page-break-inside: avoid;
   border-left: 0.2rem solid;
-  border-color: var(--pst-color-versionmodified-default);
+  border-color: var(--pst-color-info);
   border-radius: 0.2rem;
-  box-shadow: 0 0.2rem 0.5rem rgba(0, 0, 0, 0.05),
-    0 0 0.0625rem rgba(0, 0, 0, 0.1);
+  box-shadow: 0 0.2rem 0.5rem var(--pst-color-shadow),
+    0 0 0.0625rem var(--pst-color-shadow);
   transition: color 250ms, background-color 250ms, border-color 250ms;
   position: relative;
+  background-color: var(--pst-color-on-background);
 
   > p {
     margin-bottom: 0.6rem;
     margin-top: 0.6rem;
 
-    // This is a hack to control the opacity for admonitions with our color variables
+    // This is a hack to control the opacity for verson tags with our color variables
     // ref: https://stackoverflow.com/a/56951626/6734243
     &:before {
       content: "";
@@ -27,33 +28,33 @@ div.deprecated {
       position: absolute;
       left: 0;
       top: 0;
-      background-color: var(--pst-color-admonition-default);
+      background-color: var(--pst-color-info);
       opacity: 0.1;
     }
   }
 }
 
 div.versionadded {
-  border-color: var(--pst-color-versionmodified-added);
+  border-color: var(--pst-color-success);
 
   p:before {
-    background-color: var(--pst-color-versionmodified-added);
+    background-color: var(--pst-color-success);
   }
 }
 
 div.versionchanged {
-  border-color: var(--pst-color-versionmodified-changed);
+  border-color: var(--pst-color-warning);
 
   p:before {
-    background-color: var(--pst-color-versionmodified-changed);
+    background-color: var(--pst-color-warning);
   }
 }
 
 div.deprecated {
-  border-color: var(--pst-color-versionmodified-deprecated);
+  border-color: var(--pst-color-danger);
 
   p:before {
-    background-color: var(--pst-color-versionmodified-deprecated);
+    background-color: var(--pst-color-danger);
   }
 }
 
@@ -63,7 +64,7 @@ span.versionmodified {
   &:before {
     font-style: normal;
     margin-right: 0.6rem;
-    color: var(--pst-color-versionmodified-default);
+    color: var(--pst-color-info);
     font-family: "Font Awesome 5 Free";
     font-weight: 900;
     content: var(--pst-icon-versionmodified-default);
@@ -72,21 +73,21 @@ span.versionmodified {
 
 span.versionmodified.added {
   &:before {
-    color: var(--pst-color-versionmodified-added);
+    color: var(--pst-color-success);
     content: var(--pst-icon-versionmodified-added);
   }
 }
 
 span.versionmodified.changed {
   &:before {
-    color: var(--pst-color-versionmodified-changed);
+    color: var(--pst-color-warning);
     content: var(--pst-icon-versionmodified-changed);
   }
 }
 
 span.versionmodified.deprecated {
   &:before {
-    color: var(--pst-color-versionmodified-deprecated);
+    color: var(--pst-color-danger);
     content: var(--pst-icon-versionmodified-deprecated);
   }
 }
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss b/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
index cb5008d4ed..0b023a3662 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_admonitions.scss
@@ -7,12 +7,11 @@ div.admonition,
   overflow: hidden;
   page-break-inside: avoid;
   border-left: 0.2rem solid;
-  border-color: var(--pst-color-admonition-default);
+  border-color: var(--pst-color-info);
   border-radius: 0.2rem;
-  box-shadow: 0 0.2rem 0.5rem var(--pst-color-admonition-shadow),
-    0 0 0.0625rem var(--pst-color-admonition-shadow);
-  transition: color 250ms, background-color 250ms, border-color 250ms;
-  background-color: var(--pst-color-admonition-background);
+  box-shadow: 0 0.2rem 0.5rem var(--pst-color-shadow),
+    0 0 0.0625rem var(--pst-color-shadow);
+  background-color: var(--pst-color-on-background);
 
   // Last item should have no spacing since we'll control that w/ padding
   *:last-child {
@@ -43,7 +42,7 @@ div.admonition,
       left: 0.6rem;
       width: 1rem;
       height: 1rem;
-      color: var(--pst-color-admonition-default);
+      color: var(--pst-color-info);
       font-family: "Font Awesome 5 Free";
       font-weight: 900;
       content: var(--pst-icon-admonition-default);
@@ -59,7 +58,7 @@ div.admonition,
       position: absolute;
       left: 0;
       top: 0;
-      background-color: var(--pst-color-admonition-default);
+      background-color: var(--pst-color-info);
       opacity: 0.1;
     }
 
@@ -70,126 +69,126 @@ div.admonition,
   }
 
   &.attention {
-    border-color: var(--pst-color-admonition-attention);
+    border-color: var(--pst-color-warning);
     > .admonition-title {
       &:after {
-        background-color: var(--pst-color-admonition-attention);
+        background-color: var(--pst-color-warning);
       }
 
       &:before {
-        color: var(--pst-color-admonition-attention);
+        color: var(--pst-color-warning);
         content: var(--pst-icon-admonition-attention);
       }
     }
   }
 
   &.caution {
-    border-color: var(--pst-color-admonition-caution);
+    border-color: var(--pst-color-warning);
     > .admonition-title {
       &:after {
-        background-color: var(--pst-color-admonition-caution);
+        background-color: var(--pst-color-warning);
       }
 
       &:before {
-        color: var(--pst-color-admonition-caution);
+        color: var(--pst-color-warning);
         content: var(--pst-icon-admonition-caution);
       }
     }
   }
 
   &.warning {
-    border-color: var(--pst-color-admonition-warning);
+    border-color: var(--pst-color-warning);
     > .admonition-title {
       &:after {
-        background-color: var(--pst-color-admonition-warning);
+        background-color: var(--pst-color-warning);
       }
 
       &:before {
-        color: var(--pst-color-admonition-warning);
+        color: var(--pst-color-warning);
         content: var(--pst-icon-admonition-warning);
       }
     }
   }
 
   &.danger {
-    border-color: var(--pst-color-admonition-danger);
+    border-color: var(--pst-color-danger);
     > .admonition-title {
       &:after {
-        background-color: var(--pst-color-admonition-danger);
+        background-color: var(--pst-color-danger);
       }
 
       &:before {
-        color: var(--pst-color-admonition-danger);
+        color: var(--pst-color-danger);
         content: var(--pst-icon-admonition-danger);
       }
     }
   }
 
   &.error {
-    border-color: var(--pst-color-admonition-error);
+    border-color: var(--pst-color-danger);
     > .admonition-title {
       &:after {
-        background-color: var(--pst-color-admonition-error);
+        background-color: var(--pst-color-danger);
       }
 
       &:before {
-        color: var(--pst-color-admonition-error);
+        color: var(--pst-color-danger);
         content: var(--pst-icon-admonition-error);
       }
     }
   }
 
   &.hint {
-    border-color: var(--pst-color-admonition-hint);
+    border-color: var(--pst-color-success);
     > .admonition-title {
       &:after {
-        background-color: var(--pst-color-admonition-hint);
+        background-color: var(--pst-color-success);
       }
 
       &:before {
-        color: var(--pst-color-admonition-hint);
+        color: var(--pst-color-success);
         content: var(--pst-icon-admonition-hint);
       }
     }
   }
 
   &.tip {
-    border-color: var(--pst-color-admonition-tip);
+    border-color: var(--pst-color-success);
     > .admonition-title {
       &:after {
-        background-color: var(--pst-color-admonition-tip);
+        background-color: var(--pst-color-success);
       }
 
       &:before {
-        color: var(--pst-color-admonition-tip);
+        color: var(--pst-color-success);
         content: var(--pst-icon-admonition-tip);
       }
     }
   }
 
   &.important {
-    border-color: var(--pst-color-admonition-important);
+    border-color: var(--pst-color-success);
     > .admonition-title {
       &:after {
-        background-color: var(--pst-color-admonition-important);
+        background-color: var(--pst-color-success);
       }
 
       &:before {
-        color: var(--pst-color-admonition-important);
+        color: var(--pst-color-success);
         content: var(--pst-icon-admonition-important);
       }
     }
   }
 
   &.note {
-    border-color: var(--pst-color-admonition-note);
+    border-color: var(--pst-color-info);
     > .admonition-title {
       &:after {
-        background-color: var(--pst-color-admonition-note);
+        background-color: var(--pst-color-info);
       }
 
       &:before {
-        color: var(--pst-color-admonition-note);
+        color: var(--pst-color-info);
         content: var(--pst-icon-admonition-note);
       }
     }
@@ -198,12 +197,12 @@ div.admonition,
 
 // Similar content blocks that are not technically admonitions.
 .topic {
-  background-color: var(--pst-color-background-up);
+  background-color: var(--pst-color-surface);
   border-color: var(--pst-color-border);
 }
 
 aside.sidebar {
-  background-color: var(--pst-color-background-up-up);
+  background-color: var(--pst-color-on-surface);
   border-color: var(--pst-color-border);
 }
 
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_api.scss b/src/pydata_sphinx_theme/assets/styles/content/_api.scss
index 1416fbf533..9453505755 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_api.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_api.scss
@@ -13,7 +13,7 @@ table.field-list {
   th.field-name {
     padding: 1px 8px 1px 5px;
     white-space: nowrap;
-    background-color: var(--pst-color-background-up);
+    background-color: var(--pst-color-surface);
   }
 
   /* italic font for parameter types */
@@ -99,7 +99,8 @@ span.highlighted {
 }
 
 .viewcode-block:target {
-  background-color: var(--pst-color-viewcode-target-background);
-  border-top: 1px solid var(--pst-color-viewcode-target-border);
-  border-bottom: 1px solid var(--pst-color-viewcode-target-border);
+  border-top: 1px solid var(--pst-color-border);
+  border-bottom: 1px solid var(--pst-color-border);
+  position: relative;
+  background-color: var(--pst-color-target);
 }
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_quotes.scss b/src/pydata_sphinx_theme/assets/styles/content/_quotes.scss
index 8896c7deee..f1073e1738 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_quotes.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_quotes.scss
@@ -1,6 +1,6 @@
 // GitHub blockquote style
 blockquote {
   padding: 0 1em;
-  color: var(--pst-color-deactivate);
+  color: var(--pst-color-text-muted);
   border-left: 0.25em solid var(--pst-color-blockquote-border);
 }
diff --git a/src/pydata_sphinx_theme/assets/styles/content/_spans.scss b/src/pydata_sphinx_theme/assets/styles/content/_spans.scss
index 01011204e9..39a40d9733 100644
--- a/src/pydata_sphinx_theme/assets/styles/content/_spans.scss
+++ b/src/pydata_sphinx_theme/assets/styles/content/_spans.scss
@@ -3,12 +3,25 @@
  */
 
 span.guilabel {
-  border: 1px solid var(--pst-color-guilabel-border);
-  background: var(--pst-color-guilabel-background);
-  color: var(--pst-color-guilabel-text);
+  border: 1px solid var(--pst-color-info);
+  color: var(--pst-color-info);
   font-size: 80%;
   font-weight: 700;
   border-radius: 4px;
   padding: 2.4px 6px;
   margin: auto 2px;
+  position: relative;
+
+  // This is a hack to control the opacity for guilabel with our color variables
+  // ref: https://stackoverflow.com/a/56951626/6734243
+  &:before {
+    content: "";
+    width: 100%;
+    height: 100%;
+    position: absolute;
+    left: 0;
+    top: 0;
+    background-color: var(--pst-color-info);
+    opacity: 0.1;
+  }
 }
diff --git a/src/pydata_sphinx_theme/assets/styles/extensions/_ethical-ads.scss b/src/pydata_sphinx_theme/assets/styles/extensions/_ethical-ads.scss
index 6c01c7165c..3e9bf0cc33 100644
--- a/src/pydata_sphinx_theme/assets/styles/extensions/_ethical-ads.scss
+++ b/src/pydata_sphinx_theme/assets/styles/extensions/_ethical-ads.scss
@@ -8,15 +8,15 @@
   .ethical-footer a:visited,
   .ethical-footer a:hover,
   .ethical-footer a:active {
-    color: var(--pst-color-ad-text);
+    color: var(--pst-color-text-base);
   }
 
   .ethical-sidebar,
   .ethical-footer {
-    background-color: var(--pst-color-ad-background);
-    border: 1px solid var(--pst-color-ad-border);
+    background-color: var(--pst-color-background);
+    border: 1px solid var(--pst-color-border);
     border-radius: 5px;
-    color: var(--pst-color-ad-text);
+    color: var(--pst-color-text-base);
     font-size: 14px;
     line-height: 20px;
   }
diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_footer.scss b/src/pydata_sphinx_theme/assets/styles/sections/_footer.scss
index e9c1df1443..37b732fb73 100644
--- a/src/pydata_sphinx_theme/assets/styles/sections/_footer.scss
+++ b/src/pydata_sphinx_theme/assets/styles/sections/_footer.scss
@@ -1,6 +1,6 @@
 footer.bd-footer {
   width: 100%;
-  border-top: 1px solid var(--pst-color-footer-border);
+  border-top: 1px solid var(--pst-color-border);
   padding: 10px;
 
   .footer-item p {
diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_header.scss b/src/pydata_sphinx_theme/assets/styles/sections/_header.scss
index ee80fab51f..ff5755c65f 100644
--- a/src/pydata_sphinx_theme/assets/styles/sections/_header.scss
+++ b/src/pydata_sphinx_theme/assets/styles/sections/_header.scss
@@ -21,8 +21,8 @@
 
     button.navbar-toggler {
       margin-right: 1em;
-      border-color: var(--pst-color-navbar-toggler);
-      color: var(--pst-color-navbar-toggler);
+      border-color: var(--pst-color-text-muted);
+      color: var(--pst-color-text-muted);
     }
 
     #navbar-end {
@@ -40,26 +40,28 @@
 
 // If we want the shadow to only point downward in the future, set
 // box-shadow to: 0 0.125rem 0.25rem -0.125rem rgba(0, 0, 0, 0.11);
-.navbar-light {
-  box-shadow: 0 0.125rem 0.25rem 0 rgba(0, 0, 0, 0.11);
+.bd-header.navbar-light#navbar-main {
+  // Overrides bootstrap
+  background: var(--pst-color-on-background) !important;
+  box-shadow: 0 0.125rem 0.25rem 0 var(--pst-color-shadow); //rgba(0, 0, 0, 0.11);
 
   .navbar-nav {
     li a.nav-link {
       padding: 0 0.5rem;
-      color: var(--pst-color-navbar-link);
+      color: var(--pst-color-text-muted);
 
       &:hover {
-        color: var(--pst-color-navbar-link-hover);
+        color: var(--pst-color-primary);
       }
 
       &:focus {
-        color: var(--pst-color-navbar-link-hover);
+        color: var(--pst-color-primary);
       }
     }
 
     > .active > .nav-link {
       font-weight: 600;
-      color: var(--pst-color-navbar-link-active);
+      color: var(--pst-color-primary);
     }
   }
 }
@@ -82,9 +84,9 @@
 
 .toc-entry > .nav-link.active {
   font-weight: 600;
-  color: var(--pst-color-toc-link-active);
+  color: var(--pst-color-primary);
   background-color: transparent;
-  border-left: 2px solid var(--pst-color-toc-link-active);
+  border-left: 2px solid var(--pst-color-primary);
 }
 
 .nav-link:hover {
diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-primary.scss b/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-primary.scss
index a36814f897..48cd8875db 100644
--- a/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-primary.scss
+++ b/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-primary.scss
@@ -9,7 +9,7 @@
   flex-direction: column;
 
   @include media-breakpoint-up(md) {
-    border-right: 1px solid var(--pst-color-sidebar-border);
+    border-right: 1px solid var(--pst-color-border);
 
     @supports (position: -webkit-sticky) or (position: sticky) {
       position: -webkit-sticky;
@@ -61,7 +61,7 @@
     align-items: center;
 
     &:hover {
-      background: var(--pst-color-sidebar-expander-background-hover);
+      background: var(--pst-color-surface);
     }
 
     i {
@@ -69,7 +69,7 @@
       font-size: 0.75rem;
       text-align: center;
       &:hover {
-        color: var(--pst-color-sidebar-link-hover);
+        color: var(--pst-color-primary);
       }
     }
   }
@@ -100,10 +100,10 @@ nav.bd-links {
   li > a {
     display: block;
     padding: 0.25rem 1.5rem;
-    color: var(--pst-color-sidebar-link);
+    color: var(--pst-color-text-muted);
 
     &:hover {
-      color: var(--pst-color-sidebar-link-hover);
+      color: var(--pst-color-primary);
       text-decoration: none;
       background-color: transparent;
     }
@@ -123,7 +123,7 @@ nav.bd-links {
     > a,
     &:hover > a {
       font-weight: 600;
-      color: var(--pst-color-sidebar-link-active);
+      color: var(--pst-color-primary);
     }
   }
 
@@ -136,7 +136,7 @@ nav.bd-links {
     margin-top: 1.25em;
     margin-bottom: 0.5em;
     padding: 0 1.5rem;
-    color: var(--pst-color-sidebar-caption);
+    color: var(--pst-color-text-base);
     &:first-child {
       margin-top: 0;
     }
diff --git a/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-secondary.scss b/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-secondary.scss
index 3f7a1adf98..2c9fc2e7d5 100644
--- a/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-secondary.scss
+++ b/src/pydata_sphinx_theme/assets/styles/sections/_sidebar-secondary.scss
@@ -5,7 +5,7 @@
 // Each TOC item is wrapped in this
 .tocsection {
   padding-left: 10px;
-  border-left: 1px solid var(--pst-color-toc-border);
+  border-left: 1px solid var(--pst-color-border);
   padding: 0.3rem 1.5rem;
 
   i {
@@ -16,7 +16,7 @@
 // The list of in-page TOC
 .section-nav {
   padding-left: 0;
-  border-left: 1px solid var(--pst-color-toc-border);
+  border-left: 1px solid var(--pst-color-border);
   border-bottom: none;
 
   ul {
@@ -54,14 +54,14 @@
   a {
     display: block;
     padding: 0.125rem 1.5rem;
-    color: var(--pst-color-toc-link);
+    color: var(--pst-color-text-muted);
 
     @include media-breakpoint-up(xl) {
       padding-right: 0;
     }
 
     &:hover {
-      color: var(--pst-color-toc-link-hover);
+      color: var(--pst-color-primary);
       text-decoration: none;
     }
   }
@@ -85,6 +85,6 @@
   padding-top: 2rem;
 
   a {
-    color: var(--pst-color-sidebar-link-active);
+    color: var(--pst-color-primary);
   }
 }