Merge pull request #1231 from python-discord/docs/dark-theme-dev

Add docs for development on Bulma, CSS, and dark mode colors

4 files changed, 50 insertions, 3 deletions

diff --git a/pydis_site/README.md b/pydis_site/README.md
index db402743..7faa1593 100644
--- a/pydis_site/README.md
+++ b/pydis_site/README.md
@@ -15,9 +15,7 @@ for all logic powering our website. Let's go over the directories in detail:
   more about our specific apps, see the README inside the app folder itself.
 
 - [`static`](./static) contains our **static files**, such as CSS, JavaScript,
-  images, and anything else that isn't either content or Python code. Static
-  files relevant for a specific application are put into subdirectories named
-  after the application. For example, static files used by the `resources` app go in `static/resources`.
+  images, and anything else that isn't either content or Python code.
 
 - [`templates`](./templates) contains our **[Django
   templates](https://docs.djangoproject.com/en/dev/topics/templates/)**. Like
diff --git a/pydis_site/settings.py b/pydis_site/settings.py
index dfde9cef..f7574153 100644
--- a/pydis_site/settings.py
+++ b/pydis_site/settings.py
@@ -299,6 +299,10 @@ LOGGING = {
 
 # Custom settings for django-simple-bulma
 BULMA_SETTINGS = {
+    # NOTE: Due to limitations with Bulma + CSS, it is not possible to
+    # reference these color variables in our custom CSS files. When changing
+    # colors here, please do a project-wise grep and make sure other places
+    # that uses the old color is updated as appropriate.
     "variables": {
         "primary": "#7289DA",    # PyDis blurple
         "green": "#32ac66",      # Colour picked after Discord discussion
@@ -330,6 +334,9 @@ BULMA_SETTINGS = {
 
         "body-background-color": "#252629",
 
+        # These black and white colors are flipped so that when using
+        # has-background-white class for example, a white background is used in
+        # light mode whereas a dark background is applied in dark mode.
         "white": "#2C2F33",
         "white-bis": "#23272A ",
         "white-ter": "#36393F",
diff --git a/pydis_site/static/css/README.md b/pydis_site/static/css/README.md
new file mode 100644
index 00000000..24b81435
--- /dev/null
+++ b/pydis_site/static/css/README.md
@@ -0,0 +1,28 @@
+# Static CSS files
+
+When styling components, oftentimes you can make good use of Bulma classes
+rather than hardcoding CSS rules:
+
+- [Bulma color helpers](https://bulma.io/documentation/helpers/color-helpers/):
+  Classes that can be added to pretty much all Bulma components to give them a
+  text or background color which are defined in [`BULMA_SETTINGS`](../settings.py).
+- [Bulma typography helpers](https://bulma.io/documentation/helpers/typography-helpers/):
+  Classes you can add to divs and text elements to adjust the text properties
+  and alignment.
+- [Bulma visibility helpers](https://bulma.io/documentation/helpers/visibility-helpers/):
+  Rather than hardcoding screen width cutoffs just to adjust visibility, use
+  these classes instead as they are more descriptive and provide more
+  flexibility.
+
+To adjust Bulma variables (including color, sizes, margins) for a Bulma class
+everywhere, adjust the variables in [`BULMA_SETTINGS`](../../settings.py) where
+applicable. The [Bulma
+Variables](https://bulma.io/documentation/customize/variables/) page describes
+the list of all variables and their default values.
+
+That said, however, sometimes Bulma does not provide a good generalized
+solution for a specific use case or for a specific element. In that case, use
+CSS selectors to ensure that other elements that should not be styled are not
+affected by the rule, and when working with colors, ensure both light and dark
+modes are supported. Use `[data-theme="light"]` and `[data-theme="dark"]` to
+style elements for specific themes.
diff --git a/pydis_site/static/images/README.md b/pydis_site/static/images/README.md
new file mode 100644
index 00000000..1d51e8ee
--- /dev/null
+++ b/pydis_site/static/images/README.md
@@ -0,0 +1,14 @@
+# Image assets
+
+The names of each directory correspond to the pages from which apps they are
+used, except for the homepage, which uses `frontpage`, `waves`, `waves_dark`,
+`sponsors`, and `sponsors_dark`.
+
+Directories with the `_dark` suffix store alternate images to the ones in the
+corresponding directory without the `_dark` suffix. When using these alternate
+images, use the `light-image` class for the normal image and the `dark-image`
+class for the image intended for dark mode.
+
+The exception to this is the `waves_dark`, which is used in the homepage hero
+section and the images are set by CSS using `[data-theme="light"]` and
+`[data-theme="dark"]`.