Skip to content

Commit

Permalink
Update .yml brand examples and org colours docs
Browse files Browse the repository at this point in the history
  • Loading branch information
AshGDS committed Oct 21, 2024
1 parent 5fc6f14 commit d2be6e5
Show file tree
Hide file tree
Showing 6 changed files with 47 additions and 12 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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'
Expand Down
45 changes: 40 additions & 5 deletions docs/component_branding.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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.

Expand All @@ -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'
} %>
```

0 comments on commit d2be6e5

Please sign in to comment.