ENH: simplify color variables

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,19 +141,21 @@ 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:
 
 1. :ref:`Add a custom CSS stylesheet <custom-css>`. This is where we'll configure the variables.
 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::

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;
   }
 

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,19 +122,25 @@ 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);
 }
 
 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();