diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index f0707c83..496483f3 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -45,6 +45,11 @@ - [ ] Not relevant - [ ] This adds new sources of PII and documents it and modifies Birdbath processors accordingly +#### Light and dark mode + +- [ ] I have tested the changes in both light and dark mode +- [ ] The change is not relevant to dark and light mode + #### Accessibility - [ ] Automated WCAG 2.1 tests pass diff --git a/docs/custom-features/modes.md b/docs/custom-features/modes.md new file mode 100644 index 00000000..3e1c9b83 --- /dev/null +++ b/docs/custom-features/modes.md @@ -0,0 +1,29 @@ +# Light and dark mode + +The approach we use closely follows that used on the RNIB site. + +## Dark mode by default + +For sustainability reasons, we have a 'dark-mode-first' approach and serve up the site in dark mode by default. + +This means that we do not check the user's preference using `prefers-color-scheme`, because there is no way to distinguish between 'light' and setting no preference - see https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme#syntax. If we could detect a specific preference for light mode we could serve light mode up to those users - but if we serve it to users who have not set a preference as well then we are no longer serving dark mode by default. + +## torchbox-mode cookie + +The user can switch to light mode, and their preference will be saved in a `torchbox-mode` cookie. This always has a value of either `light` or `dark` - if it is set to anything different the site will be served in dark mode. If it is not present the site will be served in dark mode. + +The cookie is set via JavaScript when the user clicks the toggle in the header area of the site. If JavaScript is disabled for any reason, the toggle submits a form, which will set the cookie on the server side, and refresh the page with the new mode enabled. + +The cookie is always read on the server-side, which allows us to avoid a FOUC that might happen with reading the cookie with JavaScript. The page will be served up with a class of `mode-light` or `mode-dark` on the html class depending on the value of the cookie. + +## Styling + +See [themes and modes](/front-end/themes_and_modes). + +## Incident form + +The incident form is embedded in an iframe at https://torchbox.com/incident/. It also reads the `torchbox-mode` cookie and will render in dark or light mode accordingly - it also has some JavaScript that will watch for the cookie change and dynamically update the theme if it is switched whilst the incident form page is being viewed. + +The `torchbox-mode` cookie therefore explicitly sets a `domain` value in order to be read by `incident-form.torchbox.com` where the form is hosted. + +Note that there isn't any easy way to test the incident form's reading of the `torchbox-mode` cookie locally, as the domains won't match. diff --git a/docs/front-end/themes_and_modes.md b/docs/front-end/themes_and_modes.md index 1ff45525..6e928fff 100644 --- a/docs/front-end/themes_and_modes.md +++ b/docs/front-end/themes_and_modes.md @@ -2,7 +2,7 @@ ## Modes -The site has been initially built in dark-mode only, but the longer-term plan is to introduce a toggle switch where the user can opt to display it in light mode. The CSS to set the mode is an html class of either `.mode-dark` or `.mode-light`. +The CSS to set the mode is an html class of either `.mode-dark` or `.mode-light`. ## Themes diff --git a/mkdocs.yml b/mkdocs.yml index fc51b8e0..104f9337 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -83,6 +83,7 @@ nav: - 'Custom features': - 'Migration-friendly StreamFields': 'custom-features/migration-friendly-streamfields.md' - 'Theme': 'custom-features/theme.md' + - 'Modes': 'custom-features/modes.md' - 'Contact': 'custom-features/contact.md' - 'Continuous integration': 'continuous-integration.md' - 'Anonymised data': 'anonymised-data.md' diff --git a/tbx/static_src/sass/config/_mixins.scss b/tbx/static_src/sass/config/_mixins.scss index 05c7192a..27b7b623 100755 --- a/tbx/static_src/sass/config/_mixins.scss +++ b/tbx/static_src/sass/config/_mixins.scss @@ -215,6 +215,8 @@ /* ============================================ High Contrast mode in dark mode prefers-color-scheme: dark + forced-colors: active + + Note that this is unrelated to the 'dark mode' option on the site. */ @mixin high-contrast-dark-mode() { @media (prefers-color-scheme: dark) and (forced-colors: active) { @@ -225,6 +227,8 @@ /* ============================================ High Contrast mode in light mode prefers-color-scheme: light + forced-colors: active + + Note that this is unrelated to the 'light mode' option on the site. */ @mixin high-contrast-light-mode() { @media (prefers-color-scheme: light) and (forced-colors: active) {