Merge pull request #1684 from junpataleta/MDL-68037-dark-mode

Document the Boost theme colour modes

Author: safatshahin

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

@@ -38,3 +38,13 @@ API routes can now declare the scopes required to call them, using the `#[scopes
 Every API route **must** now declare its scope requirements, either with one or more `#[scopeset]` attributes, or by explicitly opting out with `#[unscoped_resource]`. This is enforced by a core PHPUnit test that scans all routes in the `route\api` namespace, so any new route which omits this declaration will fail the test suite.
 
 For details on declaring scopes on a route, and on defining new scope classes for a subsystem, see [Scopes](./apis/subsystems/routing/scopes.md) and [Defining Scopes](./apis/subsystems/routing/defining-scopes.md).
+
+## 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. 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, and the default mode is `Light` while it is experimental.
+
+**A plugin only follows the mode if its own styles take their colours from the theme.** A literal colour in a plugin's `styles.css` keeps its value in both modes, so use the Moodle Design System tokens or the Bootstrap utility classes instead. The Behat `init.php` and `util.php --enable` commands also take a `--colourmode` option, so that a whole run can be exercised in one mode.
+
+See the [Colour modes guide](./guides/colourmodes/index.md) for what to check in your plugin and how to test it in both modes.

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)