Rename 'websafe' to 'contrast-safe'

Renames property in colour map from 'colour-websafe' to 'contrast-safe'.

Renames parameter on govuk-organisation-colour from `$websafe` to `$contrast-safe`. The old parameter name still works but is now deprecated.

packages/govuk-frontend/src/govuk/helpers/_colour.scss

@@ -44,29 +44,41 @@
 /// Get the colour for a government organisation
 ///
 /// @param {String} $organisation - Organisation name, lowercase, hyphenated
-/// @param {Boolean} $websafe [true] - By default a 'websafe' version of the
-///   colour will be returned which meets contrast requirements . If you want to
-///   use the non-websafe version you can set this to `false` but your should
-///   ensure that you still meets contrast requirements for accessibility - for
-///   example, do not use the non-websafe version for text.
+/// @param {Boolean} $websafe [false] - Deprecated. Use $contrast-safe instead.
+/// @param {Boolean} $contrast-safe [true] - By default a version of the colour
+///   will be returned which has a minimum 4.5:1 contrast ratio when used with
+///   white, as per the WCAG 2.1 Level AA guidelines. If you want to use the
+///   non-contrast safe version you can set this to `false` but your should
+///   ensure that you still meets contrast requirements for accessibility -
+///   for example, do not use the non-contrast safe version for text.
 ///
 /// @return {Colour} Representation of colour for organisation
 /// @throw if `$organisation` is not a known organisation
 /// @access public
 
-@function govuk-organisation-colour($organisation, $websafe: true) {
+@function govuk-organisation-colour($organisation, $websafe: false, $contrast-safe: true) {
   @if not map-has-key($govuk-colours-organisations, $organisation) {
     @error "Unknown organisation `#{$organisation}`";
   }
 
+  // Output a warning if $websafe is set.
+  @if $websafe and not index($govuk-suppressed-warnings, "organisation-colour-websafe-param") {
+    @warn "The `$websafe` parameter of `govuk-organisation-colour` has been " +
+      "renamed to `$contrast-safe`. The old parameter name will be removed in " +
+      "the next major version. To silence this warning, update " +
+      "$govuk-suppressed-warnings with key: " +
+      "\"organisation-colour-websafe-param\"";
+  }
+
   $org-colour: map-get($govuk-colours-organisations, $organisation);
 
   @if map-has-key($org-colour, deprecation-message) {
     @warn map-get($org-colour, deprecation-message);
   }
 
-  @if $websafe and map-has-key($org-colour, colour-websafe) {
-    @return map-get($org-colour, colour-websafe);
+  // stylelint-disable-next-line scss/at-rule-conditional-no-parentheses
+  @if ($websafe or $contrast-safe) and map-has-key($org-colour, contrast-safe) {
+    @return map-get($org-colour, contrast-safe);
   } @else {
     @return map-get($org-colour, colour);
   }

packages/govuk-frontend/src/govuk/settings/_colours-organisations.scss

@@ -7,9 +7,9 @@
 /// @type Map
 ///
 /// @prop $organisation.colour - Colour for the given `$organisation`
-/// @prop $organisation.colour-websafe - Websafe colour for the given
-///   `$organisation`. We use `websafe` to mean strong enough contrast against
-///   white to be used for copy and meet the AAA (large text) and AA (smaller
+/// @prop $organisation.contrast-safe - 'Contrast safe' colour for the given
+///   `$organisation`. This colour has at least a 4.5:1 contrast against
+///   white, to be used for copy and meet the AAA (large text) and AA (smaller
 ///   copy) WCAG guidelines.
 /// @prop $organisation.deprecation-message - Marks this organisation as
 ///   deprecated (usually because it has ceased to exist). Value is the
@@ -29,7 +29,7 @@ $govuk-colours-organisations: (
   ),
   "department-for-business-trade": (
     colour: #e52d13,
-    colour-websafe: #ce2911
+    contrast-safe: #ce2911
   ),
   "department-for-business-energy-industrial-strategy": (
     colour: #003479,
@@ -41,7 +41,7 @@ $govuk-colours-organisations: (
   ),
   "department-for-communities-local-government": (
     colour: #009999,
-    colour-websafe: #008383,
+    contrast-safe: #008383,
     deprecation-message: "`department-for-communities-local-government` became `ministry-of-housing-communities-local-government` in 2018. As of 2023, it is equivalent to `department-for-levelling-up-housing-communities`."
   ),
   "department-for-culture-media-sport": (
@@ -53,15 +53,15 @@ $govuk-colours-organisations: (
   ),
   "department-for-education": (
     colour: #003a69,
-    colour-websafe: #347ca9
+    contrast-safe: #347ca9
   ),
   "department-for-energy-security-net-zero": (
     colour: #00a33b,
-    colour-websafe: #008530
+    contrast-safe: #008530
   ),
   "department-for-environment-food-rural-affairs": (
     colour: #00a33b,
-    colour-websafe: #008530
+    contrast-safe: #008530
   ),
   "department-for-international-development": (
     colour: #002878,
@@ -76,28 +76,28 @@ $govuk-colours-organisations: (
   ),
   "department-for-science-innovation-technology": (
     colour: #00f9f8,
-    colour-websafe: #00807f
+    contrast-safe: #00807f
   ),
   "department-for-transport": (
     colour: #006c56
   ),
   "department-for-work-pensions": (
     colour: #00beb7,
-    colour-websafe: #007e7a
+    contrast-safe: #007e7a
   ),
   "department-of-energy-climate-change": (
     colour: #009ddb,
-    colour-websafe: #007aaa,
+    contrast-safe: #007aaa,
     deprecation-message: "`department-of-energy-climate-change` was merged into `department-for-business-energy-industrial-strategy` in 2016. As of 2023, it is equivalent to `department-for-energy-security-net-zero`."
   ),
   "department-of-health": (
     colour: #00ad93,
-    colour-websafe: #008672,
+    contrast-safe: #008672,
     deprecation-message: "`department-of-health` became `department-of-health-social-care` in 2018."
   ),
   "department-of-health-social-care": (
     colour: #00ad93,
-    colour-websafe: #008672
+    contrast-safe: #008672
   ),
   "foreign-commonwealth-office": (
     colour: #003e74,
@@ -115,7 +115,7 @@ $govuk-colours-organisations: (
   ),
   "hm-revenue-customs": (
     colour: #009390,
-    colour-websafe: #007e7b
+    contrast-safe: #007e7b
   ),
   "hm-treasury": (
     colour: #af292e
@@ -128,7 +128,7 @@ $govuk-colours-organisations: (
   ),
   "ministry-of-housing-communities-local-government": (
     colour: #009999,
-    colour-websafe: #008383,
+    contrast-safe: #008383,
     deprecation-message: "`ministry-of-housing-communities-local-government` became `department-for-levelling-up-housing-communities` in 2021."
   ),
   "ministry-of-justice": (