From 14550d59aabb2d47ed34f13797882d0345aa381e Mon Sep 17 00:00:00 2001
From: Chris Sewell <chrisj_sewell@hotmail.com>
Date: Sat, 24 Jul 2021 21:16:22 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20DOCS:=20Add=20CSS=20variables=20?=
 =?UTF-8?q?guide?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md     |  2 ++
 docs/css.md   | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/index.md | 14 +++++++++++++
 3 files changed, 71 insertions(+)
 create mode 100644 docs/css.md

diff --git a/README.md b/README.md
index ef57d96..fe51041 100644
--- a/README.md
+++ b/README.md
@@ -90,6 +90,8 @@ paragraph and tab-set in grid-item
 
 rtd PRs not working
 
+size octicons to 1rem etc
+
 [github-ci]: https://github.com/executablebooks/sphinx-design/workflows/continuous-integration/badge.svg?branch=main
 [github-link]: https://github.com/executablebooks/sphinx-design
 [codecov-badge]: https://codecov.io/gh/executablebooks/sphinx-design/branch/main/graph/badge.svg
diff --git a/docs/css.md b/docs/css.md
new file mode 100644
index 0000000..fe7167d
--- /dev/null
+++ b/docs/css.md
@@ -0,0 +1,55 @@
+# CSS Variables
+
+All colors used by sphinx-design are defined as [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).
+Therefore they can be overriden by adding a `.css` file in a `_static` folder in your projects source folder (see [the sphinx documentation](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files)):
+
+```python
+html_static_path = ['_static']
+html_css_files = ['custom.css']
+```
+
+The defaults are:
+
+```css
+:root {
+    --sd-color-primary: #007bff;
+    --sd-color-secondary: #6c757d;
+    --sd-color-success: #28a745;
+    --sd-color-info: #17a2b8;
+    --sd-color-warning: #f0b37e;
+    --sd-color-danger: #dc3545;
+    --sd-color-light: #f8f9fa;
+    --sd-color-muted: #6c757d;
+    --sd-color-dark: #212529;
+    --sd-color-primary-highlight: #0069d9;
+    --sd-color-secondary-highlight: #5c636a;
+    --sd-color-success-highlight: #228e3b;
+    --sd-color-info-highlight: #148a9c;
+    --sd-color-warning-highlight: #cc986b;
+    --sd-color-danger-highlight: #bb2d3b;
+    --sd-color-light-highlight: #d3d4d5;
+    --sd-color-muted-highlight: #5c636a;
+    --sd-color-dark-highlight: #1c1f23;
+    --sd-color-primary-text: #fff;
+    --sd-color-secondary-text: #fff;
+    --sd-color-success-text: #fff;
+    --sd-color-info-text: #fff;
+    --sd-color-warning-text: #212529;
+    --sd-color-danger-text: #fff;
+    --sd-color-light-text: #212529;
+    --sd-color-muted-text: #fff;
+    --sd-color-dark-text: #fff;
+    --sd-color-shadow: rgba(0, 0, 0, 0.15);
+    --sd-color-card-border: rgba(0, 0, 0, 0.125);
+    --sd-color-card-border-hover: hsla(231, 99%, 66%, 1);
+    --sd-color-card-background: transparent;
+    --sd-color-card-text: inherit;
+    --sd-color-card-header: transparent;
+    --sd-color-card-footer: transparent;
+    --sd-color-tabs-label-active: hsla(231, 99%, 66%, 1);
+    --sd-color-tabs-label-inactive: rgba(178, 206, 245, 0.62);
+    --sd-color-tabs-overline: rgb(207, 236, 238);
+    --sd-color-tabs-underline: rgb(207, 236, 238);
+    --sd-fontsize-tabs-label: 1rem
+}
+```
diff --git a/docs/index.md b/docs/index.md
index 9860abe..911168e 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -34,6 +34,13 @@ badges_buttons
 additional
 ```
 
+```{toctree}
+:caption: Styling
+:hidden:
+
+css
+```
+
 ```{toctree}
 :caption: Themes
 :hidden:
@@ -84,6 +91,13 @@ Synchronisable, tabbed content sets.
 Roles and directives for {bdg-primary}`badges` and other components.
 :::
 
+:::{grid-item-card} {octicon-16}`image` CSS Styling
+:link: css
+:link-type: doc
+
+Change the default colors and other CSS.
+:::
+
 ::::
 
 Created with inspiration from [Bootstrap](https://getbootstrap.com/) (v5), [Material Design](https://material.io) and [Material-UI](https://material-ui.com/) design frameworks.