_colour.scss

@import "../settings/compatibility";
@import "../settings/colours-palette";
@import "../settings/colours-organisations";

////
/// @group helpers/colour
////

/// Get colour
///
/// @param {String} $colour - Name of colour from the colour palette
///   (`$govuk-colours`)
/// @param {String} $legacy - Either the name of colour from the legacy palette
///   or a colour literal, to return instead when in 'legacy mode' - matching
///   the palette from GOV.UK Template, Elements or Frontend Toolkit
/// @return {Colour} Representation of named colour
///
/// @example scss - Using legacy colours from the palette
///  .foo {
///    background-colour: govuk-colour("mid-grey", $legacy: "grey-2");
///  }
///
/// @example scss - Using legacy colour literals
///  .foo {
///    background-colour: govuk-colour("green", $legacy: #BADA55);
///  }
///
/// @throw if `$colour` is not a colour from the colour palette
/// @access public

@function govuk-colour($colour, $legacy: false) {
  @if ($govuk-use-legacy-palette and $legacy) {
    @if (type-of($legacy) == "color") {
      @return $legacy;
    }
    $colour: $legacy;
  }

  $colour: quote($colour);

  @if not map-has-key($govuk-colours, $colour) {
    @error "Unknown colour `#{$colour}`";
  }

  @return map-get($govuk-colours, $colour);
}

/// 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, don't use the non-websafe 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) {
  @if not map-has-key($govuk-colours-organisations, $organisation) {
    @error "Unknown organisation `#{$organisation}`";
  }

  $org-colour: map-get($govuk-colours-organisations, $organisation);

  @if ($websafe and map-has-key($org-colour, colour-websafe)) {
    @return map-get($org-colour, colour-websafe);
  } @else {
    @return map-get($org-colour, colour);
  }
}

/// Make a colour darker by mixing it with black
///
/// @param {Colour} $colour - colour to shade
/// @param {Number} $percentage - percentage of `$colour` in returned color
/// @return {Colour}
/// @access public

@function govuk-shade($colour, $percentage) {
  @return mix(#000000, $colour, $percentage);
}

/// Make a colour lighter by mixing it with white
///
/// @param {Colour} $colour - colour to tint
/// @param {Number} $percentage - percentage of `$colour` in returned color
/// @return {Colour}
/// @access public

@function govuk-tint($colour, $percentage) {
  @return mix(govuk-colour("white"), $colour, $percentage);
}