SCSS helpers for color CSS variables

_color-helpers.scss

/// Creates CSS var and some additional CSS vars for the hue, saturation
/// and lightness values of the given color.
/// Inspired by https://codyhouse.co/blog/post/how-to-combine-sass-color-functions-and-css-variables
///
/// @param {string} $css-var-name: The name of the CSS var.
/// @param {string} $hex-color-value: The hex color value.
/// @example scss - Usage
///   :root {
///     @include declare-hsl-color(--color-primary, #ff0000);
///   }
@mixin declare-hsl-color($css-var-name, $hex-color-value) {
  #{$css-var-name}: #{$hex-color-value};
  #{$css-var-name}-h: color.hue($hex-color-value);
  #{$css-var-name}-s: color.saturation($hex-color-value);
  #{$css-var-name}-l: color.lightness($hex-color-value);
}

/// Use this when you used declare-color() to declare the color you want to reuse. This function
/// will copy the main CSS variable, but also the -h, -s and -l variants.
///
/// @param {string} $target-css-var-name: The name of the CSS var to copy to.
/// @param {string} $source-css-var-name: The name of the CSS var to copy from.
/// @example scss - Usage
///   :root {
///     @include declare-hsl-color(--color-primary, #ff0000);
///     @include reuse-hsl-color(--color-error, --color-primary);
///   }
@mixin reuse-hsl-color($target-css-var-name, $source-css-var-name) {
  #{$target-css-var-name}: var(#{$source-css-var-name});
  #{$target-css-var-name}-h: var(#{$source-css-var-name}-h);
  #{$target-css-var-name}-s: var(#{$source-css-var-name}-s);
  #{$target-css-var-name}-l: var(#{$source-css-var-name}-l);
}

/// Use a CSS var declared with declare-hsl-color() with opacity.
///
/// @param {string} $css-var-name: The name of the CSS var.
/// @param {number} $a: The alpha to apply (percentage), e.g. 10%.
/// @return {string} A hsl() based on the given CSS var, with the applied alpha.
/// @example scss - Usage
///   :root {
///     @include declare-hsl-color(--color-primary, #ff0000);
///   }
///   body {
///     background-color: hsla-css-var(--color-primary, 10%);
///   }
@function hsla-css-var($css-var-name, $a) {
  $h: var(#{$css-var-name}-h);
  $s: var(#{$css-var-name}-s);
  $l: var(#{$css-var-name}-l);

  @return hsl(#{$h} #{$s} #{$l} / #{$a});
}

/// Sass darken() function, but with CSS variables.
/// See: https://sass-lang.com/documentation/modules/color/#darken
///
/// @param {string} $css-var-name: The name of the CSS var.
/// @param {number} $amount: The amount of darkening to apply (percentage), e.g. 10%.
/// @return {string} A hsl() based on the given CSS var, with the applied darkening.
/// @example scss - Usage
///   :root {
///     @include declare-hsl-color(--color-primary, #ff0000);
///     --primary-dark: #{darken-css-var(--color-primary, 10%)};
///   }
///   body {
///     color: darken-css-var(--color-primary, 20%);
///   }
@function darken-css-var($css-var-name, $amount) {
  $h: var(#{$css-var-name}-h);
  $s: var(#{$css-var-name}-s);
  $l: var(#{$css-var-name}-l);

  @return hsl(#{$h} #{$s} calc(#{$l} - #{$amount}));
}

/// Sass lighten() function, but with CSS variables.
/// See: https://sass-lang.com/documentation/modules/color/#lighten
///
/// @param {string} $css-var-name: The name of the CSS var.
/// @param {number} $amount: The amount of lightening to apply (percentage), e.g. 10%.
/// @return {string} A hsl() based on the given CSS var, with the applied lightening.
/// @example scss - Usage
///   :root {
///     @include declare-hsl-color(--color-primary, #ff0000);
///     --primary-dark: #{lighten-css-var(--color-primary, 10%)};
///   }
///   body {
///     color: lighten-css-var(--color-primary, 20%);
///   }
@function lighten-css-var($css-var-name, $amount) {
  $h: var(#{$css-var-name}-h);
  $s: var(#{$css-var-name}-s);
  $l: var(#{$css-var-name}-l);

  @return hsl(#{$h} #{$s} calc(#{$l} + #{$amount}));
}