Document themeing approach

Sums up and adds to the comments made in #1175.

I wasn't sure where to put these kinds of docs, as tehy are code related and not end user facing. Let's discuss whether or not this fits in here or should become part of the docs repo.

fix

BTCPayServer/wwwroot/main/themes/casa.css

@@ -6,6 +6,7 @@
   --btcpay-brand-darker:  #19154B;
   --btcpay-brand-darkest: #02000C;
 
+  /* Color definitions for specific purposes - map the general colors or define additional ones */
   --btcpay-color-white:    #fff;
   --btcpay-color-black:    #000;
 
@@ -19,7 +20,6 @@
   --btcpay-color-neutral-800: #181334;
   --btcpay-color-neutral-900: #100d20;
 
-  /* Color definitions for specific purposes - map the general colors or define additional ones */
   --btcpay-color-primary:            var(--btcpay-brand-medium); /* Usage: Text color */
   --btcpay-color-primary-backdrop:   #baa4fd;                    /* Usage: Backgrounds, borders, shadows */
   --btcpay-color-primary-accent:     #4b3bc0;                    /* Usage: Background on Focus/Hover */

BTCPayServer/wwwroot/main/themes/classic.css

@@ -6,6 +6,7 @@
   --btcpay-brand-darker:  #0F3B21;
   --btcpay-brand-darkest: #05120a;
 
+  /* Color definitions for specific purposes - map the general colors or define additional ones */
   --btcpay-color-white: #fff;
   --btcpay-color-black: #000;
 
@@ -19,10 +20,9 @@
   --btcpay-color-neutral-800: #343a40;
   --btcpay-color-neutral-900: #212529;
 
-  /* Color definitions for specific purposes - map the general colors or define additional ones */
-  --btcpay-color-primary:            #329f80;
-  --btcpay-color-primary-backdrop:   rgba(81, 173, 147, 0.25);
-  --btcpay-color-primary-accent:     #267861;
+  --btcpay-color-primary:            #329f80;                    /* Usage: Text color */
+  --btcpay-color-primary-backdrop:   rgba(81, 173, 147, 0.25);   /* Usage: Backgrounds, borders, shadows */
+  --btcpay-color-primary-accent:     #267861;                    /* Usage: Background on Focus/Hover */
   --btcpay-color-secondary:          var(--btcpay-color-neutral-600);
   --btcpay-color-secondary-backdrop: rgba(130, 138, 145, 0.25);
   --btcpay-color-secondary-accent:   var(--btcpay-color-neutral-800);

Docs/Themes.md

@@ -0,0 +1,51 @@
+# Developing and extending themes
+
+The BTCPay Server user interface is built on a customized version of Bootstrap that supports [CSS custom properties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*).
+This allows us to change theme related settings like fonts and colors without affecting the [`bootstrap.css`](#Notes-on-bootstrapcss).
+Also we can provide just the relevant customized parts instead of shipping a whole `bootstrap.css` file for each theme.
+
+Take a look at the [predefined themes](../BTCPayServer/wwwroot/main/themes) to get an overview of this approach.
+
+## Modifying existing themes
+
+The custom property definitions in the `:root` selector are divided into several sections, that can be seen as a cascade:
+
+- The first section contains general definitions (i.e. for custom brand and neutral colors).
+- The second section defines variables for specific purposes.
+  Here you can map the general definitions or create additional ones.
+- The third section contains definitions for specific parts of the page, sections or components.
+  Here you should try to reuse definitions from above as much as possible to provide a consistent look and feel.
+
+The variables defined in a theme file get used in the [`site.css`](../BTCPayServer/wwwroot/main/site.css) and [`creative.css`](../BTCPayServer/wwwroot/main/bootstrap4-creativestart/creative.css) files.
+
+### Overriding Bootstrap selectors
+
+In addition to the variables you can also provide styles by directly adding CSS selectors to this file.
+This can be seen as a last resort in case there is no variable for something you want to change or some minor tweaking.
+
+### Adding theme variables
+
+In general it is a good idea to introduce specific variables for special purposes (like setting the link colors of a specific section).
+This allows us to address individual portions of the styles without affecting other parts which might be tight to a general variable.
+
+For cases in which you want to introduce new variables that are used across all themes, add them to the `site.css` file.
+This file contains our modifications of the Bootstrap styles.
+Refrain from modifying `bootstrap.css` directly – see the [additional notes](#Notes-on-bootstrapcss) for the reasoning behind this.
+
+## Adding a new theme
+
+You should copy one of our predefined themes and change the variables to fit your needs.
+
+To test and play around with the adjustments, you can also use the developer tools of the browser:
+Inspect the `<html>` element and modify the variables in the `:root` section of the styles inspector.
+
+## Notes on bootstrap.css
+
+The `bootstrap.css` file itself is generated based on what the original vendor `bootstrap.css` provides.
+
+Right now [Bootstrap](https://getbootstrap.com/docs/4.3/getting-started/theming/) does not use custom properties, but in the future it is likely that they might switch to this approach as well.
+Until then we created a build script [in this repo](https://github.com/dennisreimann/btcpayserver-ui-prototype) which generates the `bootstrap.css` file we are using here.
+
+The general approach should be to not modify the `bootstrap.css`, so that we can keep it easily updatable.
+The initial modifications of this file were made in order to allow for this themeing approach.
+Because bootstrap has colors spread all over the place we'd otherwise have to override mostly everything, that's why these general modifications are in the main `bootstrap.css` file.

README.md

@@ -7,7 +7,7 @@
 
 # BTCPay Server
 
-## Introduction 
+## Introduction
 
 BTCPay Server is a free and open-source cryptocurrency payment processor which allows you to receive payments in Bitcoin and altcoins directly, with no fees, transaction cost or a middleman.
 
@@ -58,13 +58,13 @@ Thanks to the [apps](https://github.com/btcpayserver/btcpayserver-doc/blob/maste
 
 ## Getting Started
 
-Firstly, decide if you want to host an instance yourself or use a [third-party host](https://docs.btcpayserver.org/deployment/thirdpartyhosting). If you've chosen to self-host, we documented plenty [ways to deploy BTCPay Server](https://docs.btcpayserver.org/deployment/deployment). 
+Firstly, decide if you want to host an instance yourself or use a [third-party host](https://docs.btcpayserver.org/deployment/thirdpartyhosting). If you've chosen to self-host, we documented plenty [ways to deploy BTCPay Server](https://docs.btcpayserver.org/deployment/deployment).
 
 After successful deployment, make sure to check our [getting started](https://docs.btcpayserver.org/getting-started/registeraccount) and [walkthrough](https://docs.btcpayserver.org/btcpay-basics/walkthrough) guides. In case you would like to use Lightning Network, see [Lightning guide](https://docs.btcpayserver.org/features/lightningnetwork).
 
 ## Documentation
 
-Please check out our [official website](https://btcpayserver.org/), our [complete documentation](https://github.com/btcpayserver/btcpayserver-doc) and [FAQ](https://github.com/btcpayserver/btcpayserver-doc/tree/master/FAQ#btcpay-frequently-asked-questions-and-common-issues) for more details. 
+Please check out our [official website](https://btcpayserver.org/), our [complete documentation](https://github.com/btcpayserver/btcpayserver-doc) and [FAQ](https://github.com/btcpayserver/btcpayserver-doc/tree/master/FAQ#btcpay-frequently-asked-questions-and-common-issues) for more details.
 
 If you have trouble using BTCPay, consider joining [communities listed on official website](https://btcpayserver.org/#communityCTA) to get help from BTCPay community members. Only file [Github issue](https://github.com/btcpayserver/btcpayserver/issues) for technical issues you can't resolve through other channels or feature requests you've validated with other members of community.
 
@@ -82,6 +82,8 @@ Contributors looking to do something a bit more challenging, before opening a pu
 
 You also have an awesome video of our contributors which explains how to get started.[![Rockstar Dev and Britt Kelly - Btc Pay Server Code Along](https://img.youtube.com/vi/ZePbMPSIvHM/sddefault.jpg)](https://www.youtube.com/embed/VNMnd-dX9Q8)
 
+Here is some info about [how to extend the themes](Docs/Themes.md)
+
 ## How to build
 
 While the documentation advises to use docker-compose, you may want to build BTCPay yourself.
@@ -183,4 +185,4 @@ The BTCPay Server Project is proudly supported by these entities through the [BT
   </tbody>
 </table>
 
-If you'd like to support the project, please visit the [donation page](https://btcpayserver.org/donate/).
+If you'd like to support the project, please visit the [donation page](https://btcpayserver.org/donate/).