Button component background colour

Button component text colour

Inverted button component background colour

Inverted button component text colour

Get tag text colour Almost all tags should use the 50% shade of their colour for their text

Get tag background colour Almost all tags should use the 80% tint of their colour for their background

Generate colour CSS for tag and tag modifiers Applies standard rules from the tag colour functions

Media query for retina images (device-pixel-ratio)

Font Face - GDS Transport

Outputs the font-face declaration for GDS Transport at the root of the CSS document the first time it is called.

Focused text

Provides an outline to clearly indicate when the target element is focused. Used for interactive text-based elements.

Focused box

Provides an outline to clearly indicate when the target element is focused. Unlike govuk-focused-text, which only draws an underline below the element, govuk-focused-box draws an outline around all sides of the element. Best used for non-text content contained within links.

Focused form input

Provides an outline to clearly indicate when the target element is focused. Used for form inputs.

Helper function containing the common code for the following two mixins

Hide an element visually, but have it available for screen readers

Hide an element visually, but have it available for screen readers whilst allowing the element to be focused when navigated to via the keyboard (e.g. for the skip link)

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.

Get a functional colour

Resolves the given reference to a colour in the palette

Get the colour for a government organisation

Converts a colour with potential float values for its RGB channels into hexadecimal notation

This ensures the colour is rendered properly by Safari < 12

Clear floated content within a container using a pseudo element

Generate grid column styles

Creates a grid column with standard gutter between the columns.

Grid widths are defined in the $govuk-grid-widths map.

By default the column width changes from 100% to specified width at the 'tablet' breakpoint, but other breakpoints can be specified using the $at parameter.

Media query

Grid width percentage

Get the value of a breakpoint by name.

Generate the min-width segment of a media query given a breakpoint key

Pixel values are converted to ems for backwards compatibility with sass-mq. Unlike sass-mq, non-px and em values can be used as well.

Generate the max-width segment of a media query given a breakpoint key

sass-mq converted pixel values to ems, and only performed subtractions on named breakpoints. These have been retained for backwards compatibility, though unlike sass-mq, this also supports using non-px and em values.

Common link styles

Provides the typography and focus state, regardless of link style.

Link decoration

Provides the text decoration for links, including thickness and underline offset. Use this mixin only if you cannot use the govuk-link-common mixin.

Link hover decoration

Provides the text decoration for links in their hover state, for you to use within a :hover pseudo-selector. Use this mixin only if you cannot use the govuk-link-common mixin.

Default link styles

Makes links use the default unvisited, visited, hover and active colours.

If you use this mixin in a component, you must also include the govuk-link-common mixin to get the correct focus and hover states.

Error link styles

Makes links use the error colour. The link will darken if it's active or a user hovers their cursor over it.

If you use this mixin in a component, you must also include the govuk-link-common mixin to get the correct focus and hover states.

Success link styles

Makes links use the success colour. The link will darken if it's active or a user hovers their cursor over it.

If you use this mixin in a component, you must also include the govuk-link-common mixin to get the correct focus and hover states.

Muted link styles

Makes links use the secondary text colour. The link will darken if it's active or a user hovers their cursor over it.

If you use this mixin in a component, you must also include the govuk-link-common mixin to get the correct focus and hover states.

Text link styles

Makes links use the primary text colour, in all states. Use this mixin for navigation components, such as breadcrumbs or the back link.

If you use this mixin in a component, you must also include the govuk-link-common mixin to get the correct focus and hover states.

Inverse link styles

Makes links white, in all states. Use this mixin if you're displaying links against a dark background.

If you use this mixin in a component, you must also include the govuk-link-common mixin to get the correct focus and hover states.

Default link styles, without a visited state

Makes links use the default unvisited, hover and active colours, with no distinct visited state.

Use this mixin when it's not helpful to distinguish between visited and non-visited links. For example, when you link to pages with frequently-changing content, such as the dashboard for an admin interface.

If you use this mixin in a component, you must also include the govuk-link-common mixin to get the correct focus and hover states.

Remove underline from links

Remove underlines from links unless the link is active or a user hovers their cursor over it.

Include link destination when printing the page

If the user prints the page, add the destination URL after the link text, if the URL starts with /, http:// or https://.

Image link styles

Prepares and provides the focus state for links that only contain images with no accompanying text.

Calculate the height of an equilateral triangle

Multiplying half the length of the base of an equilateral triangle by the square root of three gives us its height. We use 1.732 as an approximation.

Arrow mixin

Generate Arrows (triangles) by using a mix of transparent (1) and coloured borders. The coloured borders inherit the text colour of the element (2).

Ensure the arrow is rendered correctly if browser colours are overridden by providing a clip path (3). Without this the transparent borders are overridden to become visible which results in a square.

We need both because older browsers do not support clip-path.

Single point spacing

Returns measurement corresponding to the spacing point requested.

Responsive spacing

Adds responsive spacing (either padding or margin, depending on $property) by fetching a 'spacing map' from the responsive spacing scale, which defines different spacing values at different breakpoints.

To generate responsive spacing, use 'govuk-responsive-margin' or 'govuk-responsive-padding' mixins

Responsive margin

Adds responsive margin by fetching a 'spacing map' from the responsive spacing scale, which defines different spacing values at different breakpoints. Wrapper for the _govuk-responsive-spacing mixin.

Responsive padding

Adds responsive padding by fetching a 'spacing map' from the responsive spacing scale, which defines different spacing values at different breakpoints. Wrapper for the _govuk-responsive-spacing mixin.

'Common typography' helper

Sets the font family and associated properties, such as font smoothing. Also overrides the font for print.

Text colour helper

Sets the text colour, including a suitable override for print.

Regular font weight helper

Bold font weight helper

Tabular number helper

Switches numerical glyphs (0–9) to use alternative forms with a monospaced bounding box. This ensures that columns of numbers, such as those in tables, remain horizontally aligned with one another. This also has the useful side effect of making numbers more legible in some situations, such as reference codes, as the numbers are more distinct and visually separated from one another.

Word break helper

Forcibly breaks long words that lack spaces, such as email addresses, across multiple lines when they wouldn't otherwise fit.

Font size and line height helper

Takes a point from the responsive 'font map' as an argument (the size as it would appear on tablet and above), and uses it to create font-size and line-height declarations for different breakpoints, and print.

Example font map:

19: (
  null: (
    font-size: 16px,
    line-height: 20px
  ),
  tablet: (
    font-size: 19px,
    line-height: 25px
  ),
  print: (
    font-size: 14pt,
    line-height: 1.15
  )
);

Font helper

Convert line-heights specified in pixels into a relative value, unless they are already unit-less (and thus already treated as relative values) or the units do not match the units used for the font size.

Width container mixin

Used to create page width and custom width container classes.

Directions for spacing

Generate responsive spacing override classes

Generate spacing override classes for the given property (e.g. margin) for each point in the responsive spacing scale.

Generate static spacing override classes

Generate spacing override classes for the given property (e.g. margin) for each point in the non-responsive spacing scale.

Path to the assets directory, with trailing slash.

This is the directory where the images and fonts subdirectories live. You will need to make this directory available via your application – see the README for details.

Path to the images folder, with trailing slash.

Path to the fonts folder, with trailing slash.

Custom image URL function

If the built-in image URL helper does not meet your needs, you can specify the name of a custom handler – either built in or by writing your own function.

If you are writing your own handler, ensure that it returns a string wrapped with url()

Custom font URL function

If the built-in font URL helper does not meet your needs, you can specify the name of a custom handler – either built in or by writing your own function.

If you are writing your own handler, ensure that it returns a string wrapped with url()

Default definitions of the functional colours

Functional colours for the GOV.UK palette.

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.

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.

Organisation colour palette

Organisation colour aliases

Some organisations have been renamed within our code over time. Here we map the prior key to the new equivalent key.

Note: This is for internal renames only. If a department has changed name or brand colour in a machinery of government change, it should be added to $govuk-colours-organisations as a new entry with any superseded organisations marked deprecated.

Colour palette

Pre-brand colours correspondence table

Output CSS custom properties

Whether to output CSS Custom Properties in the compiled stylesheet.

If you are compiling multiple stylesheets that will be used together on a page, set this to false in any secondary stylesheets to avoid including the Custom Properties multiple times.

Include 'global' styles

Whether to style paragraphs (<p>) and links (<a>) without explicitly having to apply the govuk-body and govuk-link classes.

Width of main container

Map of grid column widths

Width of gutter between grid columns

Width of half the gutter between grid columns

Standard border width

Wide border width

Narrow border width

Form control border width

Form group border width when in error state

Border width of focus outline

Hover width for form controls with a hover state

Breakpoint definitions

Thickness of link underlines

The default will be either:

• 1px
• 0.0625rem, if it's thicker than 1px because the user has changed the text size in their browser

Set this variable to false to avoid setting a thickness.

Offset of link underlines from text baseline

The default is 3px expressed as ems, as calculated against the default body font size (on desktop) of 19px. 3 ÷ 19 = 0.1578

Set this variable to false to avoid setting an offset.

Thickness of link underlines in hover state

The default for each link will be the thickest of the following:

• 3px
• 0.1875rem, if it's thicker than 3px because the user has changed the text size in their browser
• 0.12em (relative to the link's text size)

Set this variable to false to avoid setting a thickness.

Single point spacing variables. Access using govuk-spacing() (see helpers/spacing).

Responsive spacing maps

These definitions are used to generate responsive spacing that adapts according to the breakpoints (see 'helpers/spacing'). These maps should be used wherever possible to standardise responsive spacing.

You can define different behaviour on tablet and desktop. The 'null' breakpoint is for mobile.

Access responsive spacing with govuk-responsive-margin or govuk-responsive-padding mixins (see helpers/spacing).

Font families to use for all typography on screen media

Font families to use for print media

We recommend that you use system fonts when printing. This will avoid issues with some printer drivers and operating systems.

Include the default @font-face declarations

Defaults to true if "GDS Transport" appears in the $govuk-font-family setting.

Font weight for regular typography

Font weight for bold typography

Root font size

This is used to calculate rem sizes for the typography, and should match the effective font-size of your root (or html) element.

Ideally you should not be setting the font-size on the html or root element in order to allow it to scale with user-preference, in which case this should be set to 16px.

Responsive typography font map

This is used to generate responsive typography that adapts according to the breakpoints.

Font size and font weight can be defined for each breakpoint. You can define different behaviour on tablet and desktop. The 'null' breakpoint is for mobile.

Line-heights will automatically be converted from pixel measurements into relative values. For example, with a font-size of 16px and a line-height of 24px, the line-height will be converted to 1.5 before output.

You can also specify a separate font size and line height for print media.

Suppressed warnings map

This map is used to determine which deprecation warnings to not show to users when compiling sass. This is in place for codebases that do not have the necessary capacity to upgrade and remove the deprecation, particularly if the deprecation is significant. For example, the removal of mixins and functions that were previously available to users of Frontend.

You can add to this map and define which warnings to suppress by appending to it using the warning key, found in the warning message. For example:

Warnings

Acts as a wrapper for the built in @warn sass function

We use this instead of using @warn for 3 reasons:

• To check if a warning is being suppressed through $govuk-suppressed-warnings, in which case we don't call @warn and printing the warning to the user
• To format the passed warning $message with the warning key at the end
• To prevent duplicate warnings by adding the passed $key to $govuk-suppressed-warnings after @warn is called to ensure it only runs once per sass compilation (unless $silence-further-warnings is false)

Check whether a key is present in the suppressed warnings list.

Format a warning by appending information on how to suppress it.

List of modules which have already been exported

Export module

Ensure that the modules of CSS that we define throughout Frontend are only included in the generated CSS once, no matter how many times they are imported across the individual components.

Font URL

If a custom font-url handler is defined ($govuk-font-url-function) then it will be called, otherwise a url will be returned with the filename appended to the font path.

Image URL

If a custom image-url handler is defined ($govuk-image-url-function) then it will be called, otherwise a url will be returned with the filename appended to the image path.

Convert pixels to em

Convert pixels to rem

The $govuk-root-font-size (defined in settings/_typography-responsive.scss) must be configured to match the font-size of your root (html) element