Fix colour variables (#2058)

While working on the design system documentation, we noticed some fixes
needed:

- **Fix heading colour definition**: Use same colour as body
- **Add note about zindex**: Closes
#1953
- **Replace the undefined variable with PST variable**: we were using
`--pst-color-panel-background` for the background of the card
(introduced in #641,
but it seems this was removed later and it was not properly replaced).
Since cards are meant to give some sense of elevation, I replaced this
with `--pst-color-on-background`, which mostly applies to the `dark`
theme (see screenshots below)

Current colour:

![image](https://github.com/user-attachments/assets/1b87a693-20b7-4d2c-b06f-806483b11d61)

In this PR:

![image](https://github.com/user-attachments/assets/5127025f-2012-43e4-b9b0-8c3f3107b953)

`light theme` - it's the same before and after as we rely on shadows for
elevation

![image](https://github.com/user-attachments/assets/2c779919-40fa-409a-aa49-8a4082618c58)

cc @smeragoel

docs/community/design-system.md

@@ -128,28 +128,6 @@ Semantic colors (such as for success, warning, or error messages) can be used to
 convey meaning, but color should not be the only indicator.
 Pair these colors with icons or text labels to ensure clarity.
 
-### Relevant Links
-
-For further reference, you can access the following resources related to the
-typography in the PyData Sphinx theme:
-
-1. **GitHub Repository:** The source code for the PyData Sphinx theme is available on GitHub.
-   You can find the specific file that defines the typography settings,
-   including font stacks, sizes, and weights in the
-   [`fonts.scss` file](https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/variables/_fonts.scss).
-2. **Figma Design File:** The Figma file contains the visual design and specifications
-   for the typography styles, including font sizes, line heights,
-   and spacing used throughout the theme.
-   You can access it [through this link to the Figma file](https://www.figma.com/design/BHkBFxg1Qg0h5RApUw1ZrR/PyData-Design-System---Ongoing?node-id=2-7).
-
-### References
-
-1. [https://carbondesignsystem.com/elements/typography/overview/](https://carbondesignsystem.com/elements/typography/overview/)
-2. [https://canvas.workday.com/styles/tokens/type](https://canvas.workday.com/styles/tokens/type)
-3. [https://atlassian.design/foundations/typography-beta](https://atlassian.design/foundations/typography-beta)
-
----
-
 ## Color
 
 The PyData Sphinx theme uses a well-defined color palette to ensure consistency,
@@ -179,12 +157,29 @@ are provided for success, errors, warnings, and information.
 Using these colors as named ensures users can easily understand system feedback
 through visual cues.
 
-### Relevant Links
+## Relevant Links
 
-For further reference, you can access the following resources related to colors
-in the PyData Sphinx theme:
+For further reference, you can access the following resources related to the
+color and typography in the PyData Sphinx theme:
 
-1. **GitHub Repository:** You find all the PyData Sphinx theme colors in the
-   [`color.scss` file](https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/variables/_color.scss)
-2. **Figma Design File:** For specific color codes and detailed use cases,
+1. **GitHub Repository:** The source code for the PyData Sphinx theme is available on GitHub.
+   1. You can find the specific file that defines the typography settings,
+      including font stacks, sizes, and weights in the
+      [`fonts.scss` file](https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/variables/_fonts.scss).
+   2. You can find all the PyData Sphinx theme colors in the
+      [`color.scss` file](https://github.com/pydata/pydata-sphinx-theme/blob/main/src/pydata_sphinx_theme/assets/styles/variables/_color.scss)
+2. **Figma Design File:** The Figma file contains the visual design and specifications
+   for the typography styles, including font sizes, line heights,
+   and spacing used throughout the theme. It also includes our color palette and its use cases, as well as details on interactive components and their states.
+   You can access it [through this link to the Figma file][figma-library].
+
+### References
+
+1. [https://carbondesignsystem.com/elements/typography/overview/](https://carbondesignsystem.com/elements/typography/overview/)
+2. [https://canvas.workday.com/styles/tokens/type](https://canvas.workday.com/styles/tokens/type)
+3. [https://atlassian.design/foundations/typography-beta](https://atlassian.design/foundations/typography-beta)
    refer to the [Figma Design File](https://www.figma.com/design/BHkBFxg1Qg0h5RApUw1ZrR/PyData-Design-System---Ongoing?node-id=2-160).
+
+<!-- reusable links -->
+
+[figma-library]: https://www.figma.com/community/file/1443191723065200671

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

@@ -77,28 +77,28 @@ h1 {
 
   margin-top: 0;
   font-size: var(--pst-font-size-h1);
-  color: var(--pst-heading-color);
+  color: var(--pst-color-heading);
 }
 
 h2 {
   @extend %heading-style;
 
   font-size: var(--pst-font-size-h2);
-  color: var(--pst-heading-color);
+  color: var(--pst-color-heading);
 }
 
 h3 {
   @extend %heading-style;
 
   font-size: var(--pst-font-size-h3);
-  color: var(--pst-heading-color);
+  color: var(--pst-color-heading);
 }
 
 h4 {
   @extend %heading-style;
 
   font-size: var(--pst-font-size-h4);
-  color: var(--pst-heading-color);
+  color: var(--pst-color-heading);
 }
 
 h5 {
@@ -168,6 +168,7 @@ pre {
 
 // the back to top btn
 #pst-back-to-top {
+  // zindex-tooltip comes from Bootstrap https://getbootstrap.com/docs/5.2/layout/z-index/
   z-index: $zindex-tooltip;
   position: fixed;
   display: none;

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

@@ -151,19 +151,18 @@ 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);
+    background-color: var(--pst-color-on-background);
     border-bottom: 1px solid var(--pst-color-border);
   }
 
   .sd-card-footer {
-    background-color: var(--pst-color-panel-background);
+    background-color: var(--pst-color-on-background);
     border-top: 1px solid var(--pst-color-border);
   }
 
   .sd-card-body {
-    background-color: var(--pst-color-panel-background);
+    background-color: var(--pst-color-on-background);
   }
 
   // Focus ring for link-cards

src/pydata_sphinx_theme/assets/styles/variables/_color.scss

@@ -182,10 +182,6 @@ $pst-semantic-colors: (
     "light": #{map-deep-get($color-palette, "gray", "600")},
     "dark": #{map-deep-get($color-palette, "gray", "400")},
   ),
-  "heading-color": (
-    "light": #{$foundation-white},
-    "dark": #{$foundation-black},
-  ),
   "shadow": (
     "light": rgba(0, 0, 0, 0.1),
     "dark": rgba(0, 0, 0, 0.2),
@@ -290,6 +286,7 @@ $pst-semantic-colors: (
 
   // assign the "duplicate" colors (ones that just reference other variables)
   & {
+    --pst-color-heading: var(--pst-color-text-base);
     --pst-color-link: var(--pst-color-primary);
     --pst-color-link-hover: var(--pst-color-secondary);
     --pst-color-table-outer-border: var(--pst-color-surface);