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

3 files changed, 49 insertions, 0 deletions

diff --git a/pydis_site/settings.py b/pydis_site/settings.py
index a916ddb0..57ff1a15 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"]`.