Improve Sassdoc for colour related functions and settings

[36degrees]

Improving the usage documentation for these functions should allow us to remove detail from the release notes, as we can instead link out to the Sass API reference.

[github-actions]

Other changes to npm package

diff --git a/packages/govuk-frontend/dist/govuk/helpers/_colour.scss b/packages/govuk-frontend/dist/govuk/helpers/_colour.scss
index 19b4cfc36..52c8e6bac 100644
--- a/packages/govuk-frontend/dist/govuk/helpers/_colour.scss
+++ b/packages/govuk-frontend/dist/govuk/helpers/_colour.scss
@@ -6,7 +6,12 @@
 /// @group helpers/colour
 ////
 
-/// Get colour
+/// Get a colour from the palette
+///
+/// Before using this function, check if there is a functional colour that
+/// matches your use case. For example, you should use the `link` functional
+/// colour for links rather than using this function to get `blue` from the
+/// palette.
 ///
 /// @param {String | Colour} $colour - Name of colour from the colour palette
 ///   (`$_govuk-palette`)
@@ -14,6 +19,16 @@
 ///   (`$_govuk-palette`)
 /// @return {Colour} Representation of named colour
 ///
+/// @example scss - Getting the primary variant of a colour
+///   .my-component {
+///     color: govuk-colour("blue");
+///   }
+///
+/// @example scss - Getting a 50% shade of blue
+///   .my-component {
+///     color: govuk-colour("blue", $variant: "shade-50")
+///   }
+///
 /// @throw if `$colour` is not a colour from the colour palette
 /// @throw if `$variant` is not a variant of the `$colour` in the colour palette
 /// @throw if the palette is misformatted and doesn't associate a colour or map to `$colour`
@@ -84,11 +99,26 @@
 
 /// Get a functional colour
 ///
-/// @param {String|Colour} $colour - Name of the colour amongst the functional colours
-/// @return {Colour} Representation of the named colour
+/// @param {String|Colour} $colour - Name of the colour amongst the [functional colours](https://design-system.service.gov.uk/styles/colour/)
+/// colours
+/// @return {String} A reference to the functional colour's custom property
+/// wrapped in a var function, with the functional colour's hex value as a
+/// fallback value.
+///
+/// @example scss - Getting a functional colour
+///   .branded-element {
+///     color: govuk-functional-colour('brand');
+///   }
+///
+/// @example css - Output from getting a functional colour
+///   .branded-element {
+///     /* Assuming the 'brand' colour is hotpink */
+///     color: var(--_govuk-brand-colour, hotpink);
+///   }
 ///
 /// @throw if `$colour` is not an functional colour of GOV.UK Frontend
 /// @access public
+/// @see $govuk-functional-colours
 @function govuk-functional-colour($colour) {
   // Sass parses unquoted colours as colours, so we need to turn them into
   // strings before looking them up in the colour palette
diff --git a/packages/govuk-frontend/dist/govuk/settings/_colours-functional.scss b/packages/govuk-frontend/dist/govuk/settings/_colours-functional.scss
index ff6f18182..efbfed471 100644
--- a/packages/govuk-frontend/dist/govuk/settings/_colours-functional.scss
+++ b/packages/govuk-frontend/dist/govuk/settings/_colours-functional.scss
@@ -104,12 +104,34 @@ $govuk-default-functional-colours: (
 
 /// Functional colours for the GOV.UK palette.
 ///
-/// Each functional colour is represented by a friendly name (for example `'brand'`)
-/// to which the map associates either:
+/// Each functional colour is represented by a name (for example `'brand'`) to
+/// which the map associates either:
 ///
 ///   - a Sass colour (like `#1d70b8`)
-///   - a Sass map with a `name` and an optional `variant` properties, referring to one of the colours in the colour palette
-///     (like `(name: 'blue', variant: 'primary')`). `variant` defaults to `'primary'` if omitted.
+///   - a Sass map with a `name` and an optional `variant` properties, referring
+///     to one of the colours in the colour palette (like `(name: 'blue',
+///     variant: 'primary')`). `variant` defaults to `'primary'` if omitted.
+///
+/// Use the `govuk-functional-colour` function to access these colours.
+///
+/// Customise functional colours by defining $govuk-functional-colours with a
+/// map of the colours that you want to change before importing GOV.UK Frontend.
+/// These will then be merged with the default colours. Note that you can only
+/// redefine existing colours.
+///
+/// @example scss – Redefining functional colours by setting them before import
+///
+///   // These will be merged with the default functional colours
+///   $govuk-functional-colours: (
+///     // set the 'brand' colour to the 'primary' variant of 'purple'
+///     brand: (name: 'purple'),
+///     // set the 'template-background' colour to the 'tint-95' variant of 'purple'
+///     template-background: (name: 'purple', variant: 'tint-95'),
+///     // set the 'text' colour to an arbitrary colour `#221133`
+///     text: #221133
+///   );
+///
+/// @see {function} govuk-functional-colour
 ///
 /// @type Map
 ///
@@ -128,9 +150,8 @@ $govuk-functional-colours: _govuk-define-functional-colours(
 // breakage as teams upgrade
 // =============================================================================
 
-// Because the file may be imported multiple times,
-// subsequent imports will see the legacy variable
-// and warn when they shouldn't so we need to track those
+// Because the file may be imported multiple times, subsequent imports will see
+// the legacy variable and warn when they shouldn't so we need to track those
 $_govuk-deprecated-applied-colour-variables: () !default;
 
 @mixin deprecate-applied-colour-variable($functional-colour-name) {

---

Action run for 5b2649e

[github-actions]

📋 Stats

File sizes

File	Size	Percentage change
dist/govuk-frontend-development.min.css	123.17 KiB	-0.2%
packages/govuk-frontend/dist/govuk/govuk-frontend.min.css	123.15 KiB	-0.2%

No changes to module sizes.

---

Action run for 5b2649e

[romaricpascal]

Looks neat to me! Only offered a little suggestion for govuk-functional-colour's docs, though I'm not sure if the Frontend docs do anything with @see tags 🤔

Worth noting that this PR will likely interact with the changes removing the leading _ of the functional colour custom properties.