Documentation and MR template updates relating to light mode

.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

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.

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
 

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'

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) {