Color Functions

/**
 * Mixes a color with white
 * @param $color - The base color to lighten
 * @param $percent - The amount of white to mix in (percentage)
 * @returns color - The lightened color
 * @throws Error if $color is not a valid CSS color
 */
@function tint($color, $percent): color;

.element {
  // Basic tint
  background-color: tint(#6ecaa6, 40%);
  // Result: #a8dfc9

  // Progressive tinting for hover states
  color: tint(#333, 20%);
  &:hover {
    color: tint(#333, 40%);
  }
}

// Creating a color palette
$primary: #007acc;
$primary-light: tint($primary, 20%);
$primary-lighter: tint($primary, 40%);
$primary-lightest: tint($primary, 60%);

/**
 * Mixes a color with black
 * @param $color - The base color to darken
 * @param $percent - The amount of black to mix in (percentage)
 * @returns color - The darkened color
 * @throws Error if $color is not a valid CSS color
 */
@function shade($color, $percent): color;

.element {
  // Basic shade
  background-color: shade(#ffbb52, 60%);
  // Result: #664a20

  // Creating depth with shadows
  background-color: #ff6b6b;
  box-shadow: 0 4px 8px shade(#ff6b6b, 30%);
}

// Button state variations
.button {
  background: #28a745;
  &:hover {
    background: shade(#28a745, 10%);
  }
  &:active {
    background: shade(#28a745, 20%);
  }
}

/**
 * Switches between two colors based on contrast ratio
 * @param $base-color - Color to evaluate lightness against
 * @param $dark-color - Dark color output (optional, uses setting default)
 * @param $light-color - Light color output (optional, uses setting default)
 * @returns color - Either the dark or light color based on contrast
 * @throws Error if $base-color is not a valid CSS color
 */
@function contrast-switch(
  $base-color,
  $dark-color: null,
  $light-color: null
): color;

.card {
  // Automatic text color based on background
  background-color: #bae6e6;
  color: contrast-switch(#bae6e6);
  // Result: #000 (dark text on light background)
}

.badge {
  // Custom light/dark colors
  background-color: #333;
  color: contrast-switch(#333, #222, #fff);
  // Result: #fff (light text on dark background)
}

// Dynamic theming
@each $color, $value in $theme-colors {
  .bg-#{$color} {
    background-color: $value;
    color: contrast-switch($value);
  }
}

$bourbon: (
  "contrast-switch-dark-color": #1a1a1a,   // Default dark color
  "contrast-switch-light-color": #f8f9fa   // Default light color
);

// This will cause a compilation error
.invalid {
  color: tint("not-a-color", 20%);
  // Error: "not-a-color" is not a valid color for the $color argument
}