assets/sass/bourbon/bourbon/library/_contrast-switch.scss

   1 @charset "UTF-8";
   2
   3 /// Switches between two colors based on the contrast to another color. It’s
   4 /// like a [ternary operator] for color contrast and can be useful for building
   5 /// a button system.
   6 ///
   7 /// The calculation of the contrast ratio is based on the [WCAG 2.0
   8 /// specification]. However, we cannot guarantee full compliance, though all of
   9 /// our manual testing passed.
  10 ///
  11 ///   [ternary operator]: https://goo.gl/ccfLqi
  12 ///   [WCAG 2.0 specification]: https://goo.gl/zhQuYA
  13 ///
  14 /// @argument {color} $base-color
  15 ///   The color to evaluate lightness against.
  16 ///
  17 /// @argument {color} $dark-color [#000]
  18 ///   The color to be output when `$base-color` is light. Can also be set
  19 ///   globally using the `contrast-switch-dark-color` key in the
  20 ///   Bourbon settings.
  21 ///
  22 /// @argument {color} $light-color [#fff]
  23 ///   The color to be output when `$base-color` is dark. Can also be set
  24 ///   globally using the `contrast-switch-light-color` key in the
  25 ///   Bourbon settings.
  26 ///
  27 /// @return {color}
  28 ///
  29 /// @example scss
  30 ///   .element {
  31 ///     color: contrast-switch(#bae6e6);
  32 ///   }
  33 ///
  34 ///   // CSS Output
  35 ///   .element {
  36 ///     color: #000;
  37 ///   }
  38 ///
  39 /// @example scss
  40 ///   .element {
  41 ///     $button-color: #2d72d9;
  42 ///     background-color: $button-color;
  43 ///     color: contrast-switch($button-color, #222, #eee);
  44 ///   }
  45 ///
  46 ///   // CSS Output
  47 ///   .element {
  48 ///     background-color: #2d72d9;
  49 ///     color: #eee;
  50 ///   }
  51 ///
  52 /// @require {function} _fetch-bourbon-setting
  53 ///
  54 /// @require {function} _is-color
  55 ///
  56 /// @require {function} _contrast-ratio
  57 ///
  58 /// @since 5.0.0
  59
  60 @function contrast-switch(
  61   $base-color,
  62   $dark-color: _fetch-bourbon-setting("contrast-switch-dark-color"),
  63   $light-color: _fetch-bourbon-setting("contrast-switch-light-color")
  64 ) {
  65   @if not _is-color($base-color) {
  66     @error "`#{$base-color}` is not a valid color for the `$base-color` " +
  67       "argument in the `contrast-switch` function.";
  68   } @else if not _is-color($dark-color) {
  69     @error "`#{$dark-color}` is not a valid color for the `$dark-color` " +
  70       "argument in the `contrast-switch` function.";
  71   } @else if not _is-color($light-color) {
  72     @error "`#{$light-color}` is not a valid color for the `$light-color` " +
  73       "argument in the `contrast-switch` function.";
  74   } @else {
  75     $-contrast-to-dark: _contrast-ratio($base-color, $dark-color);
  76     $-contrast-to-light: _contrast-ratio($base-color, $light-color);
  77     $-prefer-dark: $-contrast-to-dark >= $-contrast-to-light;
  78
  79     @return if($-prefer-dark, $dark-color, $light-color);
  80   }
  81 }