Document the Boost theme colour modes

docs/apis/_files/styles-css.mdx

@@ -9,3 +9,9 @@ Plugins may define a '/styles.css' to provide plugin-specific styling. See the f
 Rather than writing custom CSS for your plugin, where possible apply Bootstrap classes to the DOM elements in your output. These will be easier to maintain and will adopt most colour, branding, and other customisations applied to a theme.
 
 :::
+
+:::warning[Check both colour modes]
+
+Boost can render a site in a light or a dark colour mode, and a stylesheet which hardcodes a colour will keep that colour in both. See [Colour modes](../../guides/colourmodes/index.md) for how to take your colours from the theme instead.
+
+:::

docs/apis/plugintypes/theme/styles.md

@@ -21,6 +21,12 @@ As theme designers, only the first method of introducing CSS will be used: addin
 
 :::
 
+:::info[Colour modes]
+
+Boost can render a site in a light or a dark colour mode. Any colour written as a literal keeps its value in both, so a theme or a plugin has to take its colours from the theme's custom properties in order to follow the mode. See [Colour modes](../../../guides/colourmodes/index.md).
+
+:::
+
 ## CSS pre-processors {/* #css-pre-processors */}
 
 Browsers understand CSS well, but it is hard to write and maintain. The language does not support inheritance and reuse. [Support for variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) exists in more modern browsers only.  This is why CSS pre-processors were invented. Moodle supports SASS, which is recommended by far.

docs/devupdate.md

@@ -28,3 +28,17 @@ The `moodle_page` class now includes `set_supplementary_content()` and `get_supp
 For instance, `mod_forum` uses this new mechanism to display a "Go to all discussions" link in the sticky footer when viewing an individual discussion.
 
 For more information, see the [Adding supplementary content to the sticky footer](./apis/plugintypes/format/linear_navigation.md#adding-supplementary-content-to-the-sticky-footer) section.
+
+## Light and dark colour modes in Boost
+
+<Since version="5.3" issueNumber="MDL-68037" />
+
+The Boost theme can now render a site in either a light or a dark colour mode, built on the Bootstrap 5.3 colour modes API. The mode in use is written to the `data-bs-theme` attribute of the `html` tag, and `theme_boost\colour_mode` is the entry point for reading or rendering it. People choose their own mode from a switcher in the navbar, offering Light, Dark and System.
+
+The feature is experimental, so it is off until a site turns on **Enable colour modes** on the new **Experimental settings** tab of the Boost settings, which is also where the site default mode is chosen. Nothing about an existing site changes on upgrade.
+
+Boost and the core interface follow the mode, but **a plugin only follows it if its own styles take their colours from the theme**. A colour written as a literal in a plugin's `styles.css` keeps that value in both modes, which usually means a light island on a dark page, or text which cannot be read against the surface behind it. Styles work in both modes if they take their colours from the Bootstrap custom properties, the Moodle Design System tokens, or the equivalent utility classes, all of which change with the mode.
+
+The Behat CLI tools also take a `--colourmode` option, so that a whole run can be exercised in a given mode.
+
+For what to check in your plugin, the properties and tokens to use, and how to test in both modes, see the [Colour modes guide](./guides/colourmodes/index.md).

docs/guides.md

@@ -12,3 +12,4 @@ Learn about key Moodle features for developers through our Developer Guides. The
 - Introduction to [JavaScript](./guides/javascript/index.md) in Moodle
 - Learn about how Moodle uses [Templates](./guides/templates/index.md) to render content
 - Distribute and install Moodle plugins using [Composer](./guides/composer/index.md)
+- Make your plugin render correctly in both [Colour modes](./guides/colourmodes/index.md)