From 212161c1b3f890d56cbfda0e1422e2cec06f3fcd Mon Sep 17 00:00:00 2001 From: hedy Date: Tue, 13 Feb 2024 14:26:23 +0800 Subject: Add docs on Bulma, colors, dark mode, and CSS for development --- pydis_site/settings.py | 7 +++++++ pydis_site/static/css/README.md | 28 ++++++++++++++++++++++++++++ pydis_site/static/images/README.md | 14 ++++++++++++++ 3 files changed, 49 insertions(+) create mode 100644 pydis_site/static/css/README.md create mode 100644 pydis_site/static/images/README.md 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"]`. -- cgit v1.2.3 From ac57518820203e89178f59d3bc707e3bd43ac789 Mon Sep 17 00:00:00 2001 From: hedy Date: Tue, 13 Feb 2024 14:27:33 +0800 Subject: Fix pydis_site/README.md reference to static directory structure --- pydis_site/README.md | 4 +--- 1 file changed, 1 insertion(+), 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 -- cgit v1.2.3