Update .yml brand examples and org colours docs

app/views/govuk_publishing_components/components/docs/contents_list.yml

@@ -181,9 +181,9 @@ examples:
     context:
       right_to_left: true
   with_branding:
-    description: Where this component could be used on an organisation page (such as the [Attorney General's Office](https://www.gov.uk/government/organisations/attorney-generals-office)) branding can be applied for link colours and border colours. See the [branding documentation](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) for more details.
+    description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown.
     data:
-      brand: 'department-for-environment-food-rural-affairs'
+      brand: 'prime-ministers-office-10-downing-street'
       format_numbers: true
       contents:
         - href: "#first-thing"

app/views/govuk_publishing_components/components/docs/document_list.yml

@@ -131,9 +131,9 @@ examples:
           public_updated_at: 2017-07-19 15:01:48
           document_type: 'Statutory guidance'
   with_branding:
-    description: Where this component could be used on an organisation page (such as the [Attorney General's Office](https://www.gov.uk/government/organisations/attorney-generals-office)) branding can be applied for link colours and border colours. See the [branding documentation](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) for more details.
+    description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown.
     data:
-      brand: 'attorney-generals-office'
+      brand: 'prime-ministers-office-10-downing-street'
       items:
       - link:
           text: 'School behaviour and attendance: parental responsibility measures'

app/views/govuk_publishing_components/components/docs/image_card.yml

@@ -175,7 +175,7 @@ examples:
   with_branding:
     description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown.
     data:
-      brand: "department-for-work-pensions"
+      brand: 'prime-ministers-office-10-downing-street'
       href: "/again-not-a-page"
       image_src: "https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/62756/s300_courts-of-justice.JPG"
       image_alt: "some meaningful alt text please"

app/views/govuk_publishing_components/components/docs/subscription_links.yml

@@ -48,7 +48,7 @@ examples:
   with_branding:
     description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown.
     data:
-      brand: 'attorney-generals-office'
+      brand: 'prime-ministers-office-10-downing-street'
       email_signup_link: '/foreign-travel-advice/singapore/email-signup'
       feed_link: '/foreign-travel-advice/singapore.atom'
   with_data_attributes_on_links:

app/views/govuk_publishing_components/components/docs/translation_nav.yml

@@ -64,7 +64,7 @@ examples:
   with_branding:
     description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown.
     data:
-      brand: 'wales-office'
+      brand: 'prime-ministers-office-10-downing-street'
       translations:
       - locale: 'en'
         base_path: '/en'

docs/component_branding.md

@@ -2,15 +2,19 @@
 
 ## Overview
 
-Organisation pages in whitehall ([example](https://www.gov.uk/government/organisations/attorney-generals-office)) have department-specific branding on them. This includes specific colours for links and borders. These pages are being migrated out of whitehall and will use components for their frontend, which means some components need a sensible way of displaying these colours.
+Organisation pages in `collections` have some department-specific branding on them. Custom border colours are used on all organisation pages ([example](https://www.gov.uk/government/organisations/attorney-generals-office)), and custom colours for links are used on [Prime Minister's Office, 10 Downing Street](https://www.gov.uk/government/organisations/prime-ministers-office-10-downing-street).
+
+[Most colours now come from govuk-frontend](https://github.com/alphagov/govuk-frontend/blob/main/packages/govuk-frontend/src/govuk/settings/_colours-organisations.scss), however custom colours can be added to [_brand_colours.scss](https://github.com/alphagov/govuk_publishing_components/blob/main/app/assets/stylesheets/govuk_publishing_components/components/helpers/_brand-colours.scss) if required.
 
 This work follows [this RFC](https://github.com/alphagov/govuk_publishing_components/pull/287) to discuss the approach taken.
 
+**Note: as of October 2024, the use of brand colours for styling was reduced to just borders and accents for most organisations. Brand colours should not be added to text or links, except for in specific agreed circumstances. Text and links should ideally always use our default styles for accessibility and to ensure that the user journey across GOV.UK is consistent from a design perspective.**
+
 ## Adding to a component
 
 To add colours to a component, modify the component to follow the example below.
 
-```
+```erb
 <%
   brand ||= false
   brand_helper = GovukPublishingComponents::AppHelpers::BrandHelper.new(brand)
@@ -22,12 +26,43 @@ To add colours to a component, modify the component to follow the example below.
   </div>
 
   <a href="#" class="<%= brand_helper.color_class %>">
-    Example element that requires coloured text
+    Obscure use case where a link requires coloured text
   </a>
 </div>
 ```
 
-Note that the helper must be called for each element that needs a border or link colour applying. This allows for flexibility if one is required but not the other.
+The above will style borders with colours from the design system automatically, as we have a SASS mixin for this in `_brand_colours.scss` that will map the class to its colour in the design system.
+
+If your use case fits one of these scenarios:
+- you need to use `brand_helper.color_class`
+- a new brand name or colour outside of the design system needs to be used
+- styles other than the border colour are needed
+
+Then a new class in `_brand_colours.scss` will need to be created, that is namespaced to the brand name:
+
+```scss
+.brand--your-brand-name-here {
+  .brand__color {
+    &:link,
+    &:visited,
+    &:active {
+      color: govuk-colour("black"); // link colours ideally shouldn't be changed, so this is only shown here for demonstration purposes.
+    }
+
+    &:hover,
+    &:focus {
+      color: $govuk-focus-text-colour;
+    }
+  }
+
+  &.brand__border-color,
+  .brand__border-color {
+    border-color: govuk-colour("black"); // your border colour here
+  }
+}
+```
+
+Note that the helper must be called for each element that needs a border or other brand-specific colour applied. This allows for flexibility if one is required but not the other.
 
 The `border_color_class` method/class can also be applied to the main element of a component if needed, for example where the component is only one element. This is currently not possible with `color_class` as there is no requirement for this.
 
@@ -49,6 +84,6 @@ The component can then be passed a string matching the required brand, for examp
 
 ```
 <%= render "govuk_publishing_components/components/example-component", {
-  brand: 'attorney-generals-office'
+  brand: 'prime-ministers-office-10-downing-street'
 } %>
 ```