Color Module

Overview

The sasses/color generates new colors based on existing ones, making it easy to build color themes.

See: @forward · @import · @use

Variables

Color Contrast Dark

color.$color-contrast-dark  //=> color

Returns a dark color if the background is light.

Example:

Sass

@use 'sasses/color'

@debug color.$color-contrast-dark  //=> black

Color Contrast Light

color.$color-contrast-light  //=> color

Returns a light color if the background is dark.

Example:

Sass

@use 'sasses/color'

@debug color.$color-contrast-light  //=> white

Minimal Contrast Ratio

color.$min-contrast-ratio  //=> number

The contrast ratio to reach against white, to determine if color changes from "light" to "dark". Acceptable values for WCAG 2.0 are 3, 4.5 and 7.

See Visual Audio Contrast

Example:

Sass

@use 'sasses/color'

@debug color.$min-contrast-ratio  //=> 4.5

Functions

Adjust

color.adjust($color, $red: null, $green: null, $blue: null, $hue: null, $saturation: null, $lightness: null, $whiteness: null, $blackness: null, $alpha: null)  //=> color

Increases or decreases one or more properties of $color by fixed amounts.

Adds the value passed for each keyword argument to the corresponding property of the color, and returns the adjusted color. It’s an error to specify an RGB property ($red, $green, and/or $blue) at the same time as an HSL property ($hue, $saturation, and/or $lightness), or either of those at the same time as a HWB property ($hue, $whiteness, and/or $blackness).

All optional arguments must be numbers. The $red, $green, and $blue arguments must be unitless and between -255 and 255 (inclusive). The $hue argument must have either the unit deg or no unit. The $saturation, $lightness, $whiteness, and $blackness arguments must be between -100% and 100% (inclusive), and may not be unitless. The $alpha argument must be unitless and between -1 and 1 (inclusive).

Example:

Sass

@use "sasses/color"

@debug color.adjust(#6b717f, $red: 15)  //=> #7a717f
@debug color.adjust(#d2e1dd, $red: -10, $blue: 10)  //=> #c8e1e7
@debug color.adjust(#998099, $lightness: -30%, $alpha: -0.4)  //=> rgba(71, 57, 71, 0.6)

Alpha

color.alpha($color)  //=> number

Returns the alpha channel of $color as a number between 0 and 1.

As a special case, this supports the Internet Explorer syntax alpha(opacity=20), for which it returns an unquoted string.

Example:

Sass

@use "sasses/color"

@debug color.alpha(#e1d7d2)  //=> 1
@debug color.alpha(rgba(210, 225, 221, 0.4))  //=> 0.4

Blackness

color.blackness($color)  //=> number

Returns the HWB blackness of $color as a number between 0% and 100%.

Example:

Sass

@use "sasses/color"

@debug color.blackness(#e1d7d2)  //=> 11.7647058824%
@debug color.blackness(white)  //=> 0%
@debug color.blackness(black)  //=> 100%

Blue

color.blue($color)  //=> number

Returns the blue channel of $color as a number between 0 and 255.

Example:

Sass

@use "sasses/color"

@debug color.blue(#e1d7d2)  //=> 210
@debug color.blue(white)  //=> 255
@debug color.blue(black)  //=> 0

Change

color.change($color, $red: null, $green: null, $blue: null, $hue: null, $saturation: null, $lightness: null, $whiteness: null, $blackness: null, $alpha: null)  //=> color

Sets one or more properties of a color to new values.

Uses the value passed for each keyword argument in place of the corresponding property of the color, and returns the changed color. It’s an error to specify an RGB property ($red, $green, and/or $blue) at the same time as an HSL property ($hue, $saturation, and/or $lightness), or either of those at the same time as an HWB property ($hue, $whiteness, and/or $blackness).

All optional arguments must be numbers. The $red, $green, and $blue arguments must be unitless and between 0 and 255 (inclusive). The $hue argument must have either the unit deg or no unit. The $saturation, $lightness, $whiteness, and $blackness arguments must be between 0% and 100% (inclusive), and may not be unitless. The $alpha argument must be unitless and between 0 and 1 (inclusive).

Example:

Sass

@use "sasses/color"

@debug color.change(#6b717f, $red: 100)  //=> #64717f
@debug color.change(#d2e1dd, $red: 100, $blue: 50)  //=> #64e132
@debug color.change(#998099, $lightness: 30%, $alpha: 0.5)  //=> rgba(85, 68, 85, 0.5)

Complement

color.complement($color)  //=> color

Returns the RGB complement of $color.

This is identical to color.adjust($color, $hue: 180deg).

Example:

Sass

@use "sasses/color"

// Hue 222deg becomes 42deg.
@debug color.complement(#6b717f)  //=> #7f796b

// Hue 164deg becomes 344deg.
@debug color.complement(#d2e1dd)  //=> #e1d2d6

// Hue 210deg becomes 30deg.
@debug color.complement(#036)  //=> #663300

Color Constrast

color.color-contrast($background, $color-dark, $color-light, $min-contrast) //=> color

How one color stands out from another color.

Example:

Sass

@use "sasses/color"

@debug color.color-contrast(#075298)  //=> white
@debug color.color-contrast(#6db8fe)  //=> black

Contrast Ratio

color.contrast-ratio($background, $foreground) //=> number

A measurement of the visual difference between two colors expressed mathematically.

Example:

Sass

@use "sasses/color"

@debug color.contrast-ratio(#075298, white)  //=> 7.8670801833
@debug color.contrast-ratio(#6db8fe, black)  //=> 9.9375893256

Grayscale

color.grayscale($color)  //=> color

Returns a gray color with the same lightness as $color.

This is identical to color.change($color, $saturation: 0%).

Example:

Sass

@use "sasses/color"

@debug color.grayscale(#6b717f)  //=> #757575
@debug color.grayscale(#d2e1dd)  //=> #dadada
@debug color.grayscale(#036)  //=> #333333

Green

color.green($color)  //=> number

Returns the green channel of $color as a number between 0 and 255.

Example:

Sass

@use "sasses/color"

@debug color.green(#e1d7d2)  //=> 215
@debug color.green(white)  //=> 255
@debug color.green(black)  //=> 0

Hue

color.hue($color)  //=> number

Returns the hue of $color as a number between 0deg and 360deg.

Example:

Sass

@use "sasses/color"

@debug color.hue(#e1d7d2)  //=> 20deg
@debug color.hue(#f2ece4)  //=> 34.2857142857deg
@debug color.hue(#dadbdf)  //=> 228deg

Hue Whiteness Blackness (HWB)

color.hwb($hue $whiteness $blackness)  //=> color

// or

color.hwb($hue $whiteness $blackness / $alpha)  //=> color

// or

color.hwb($hue, $whiteness, $blackness, $alpha: 1)  //=> color

Returns a color with the given hue, whiteness, and blackness and the given alpha channel.

The hue is a number between 0deg and 360deg (inclusive). The whiteness and blackness are numbers between 0% and 100% (inclusive). The hue may be unitless, but the whiteness and blackness must have unit %. The alpha channel can be specified as either a unitless number between 0 and 1 (inclusive), or a percentage between 0% and 100% (inclusive).

Example:

Sass

@use "sasses/color"

@debug color.hwb(210, 0%, 60%)  //=> #036
@debug color.hwb(34, 89%, 5%)  //=> #f2ece4
@debug color.hwb(210 0% 60% / 0.5)  //=> rgba(0, 51, 102, 0.5)

IE HEX Str

color.ie-hex-str($color)  //=> unquoted string

Returns an unquoted string that represents $color in the #AARRGGBB format expected by Internet Explorer’s -ms-filter property.

Example:

Sass

@use "sasses/color"

@debug color.ie-hex-str(#b37399)  //=> #FFB37399
@debug color.ie-hex-str(#808c99)  //=> #FF808C99
@debug color.ie-hex-str(rgba(242, 236, 228, 0.6))  //=> #99F2ECE4

Invert

color.invert($color, $weight: 100%)  //=> color

Returns the inverse or negative of $color.

The $weight must be a number between 0% and 100% (inclusive). A higher weight means the result will be closer to the negative, and a lower weight means it will be closer to $color. Weight 50% will always produce #808080.

Example:

Sass

@use "sasses/color"

@debug color.invert(#b37399)  //=> #4c8c66
@debug color.invert(black)  //=> white
@debug color.invert(#550e0c, 20%)  //=> #663b3a

Lightness

color.lightness($color)  //=> number

Returns the HSL lightness of $color as a number between 0% and 100%.

Example:

Sass

@use "sasses/color"

@debug color.lightness(#e1d7d2)  //=> 85.2941176471%
@debug color.lightness(#f2ece4)  //=> 92.1568627451%
@debug color.lightness(#dadbdf)  //=> 86.4705882353%

Lightness

color.luminance($color)  //=> number

Return WCAG2.1 relative luminance

See: DFN Relative Luminance · DFN Contrast Ratio

Example:

Sass

@use "sasses/color"

@debug color.luminance(#0B89FE)  //=> 0.2511822502
@debug color.luminance(#fe800b)  //=> 0.3653333554
@debug color.luminance(#89fe0b)  //=> 0.7622614911
@debug color.luminance(#fe0b89)  //=> 0.2311631764

Mix

color.mix($color1, $color2, $weight: 50%)  //=> color

Returns a color that’s a mixture of $color1 and $color2.

Both the $weight and the relative opacity of each color determines how much of each color is in the result. The $weight must be a number between 0% and 100% (inclusive). A larger weight indicates that more of $color1 should be used, and a smaller weight indicates that more of $color2 should be used.

Example:

Sass

@use "sasses/color"

@debug color.mix(#036, #d2e1dd)  //=> #698aa2
@debug color.mix(#036, #d2e1dd, 75%)  //=> #355f84
@debug color.mix(#036, #d2e1dd, 25%)  //=> #9eb6bf
@debug color.mix(rgba(242, 236, 228, 0.5), #6b717f)  //=> rgba(141, 144, 152, 0.75)

Opaque

color.opaque($background, $foreground)  //=> color

A paint that is opaque will give a solid colour.

Example:

Sass

@use "sasses/color"

@debug color.opaque(#e7f3ff, #010e19)  //=> #010e19
@debug color.opaque(#cee7ff, #021b33)  //=> #021b33
@debug color.opaque(#9dd0ff, #043766)  //=> #043766
@debug color.opaque(#6db8fe, #075298)  //=> #075298
@debug color.opaque(#3ca1fe, #096ecb)  //=> #096ecb
@debug color.opaque(#0B89FE, #000000)  //=> black
@debug color.opaque(#0B89FE, #ffffff)  //=> white

Red

color.red($color)  //=> number

Returns the red channel of $color as a number between 0 and 255.

Example:

Sass

@use "sasses/color"

@debug color.red(#e1d7d2)  //=> 225
@debug color.red(white)  //=> 255
@debug color.red(black)  //=> 0

Saturate

color.saturate($color, $amount)  //=> color

Makes $color more saturated.

The $amount must be a number between 0% and 100% (inclusive). Increases the HSL saturation of $color by that amount.

Example:

Sass

@use "sasses/color"

// Saturation 50% becomes 70%.
@debug color.saturate(#c69, 20%)  //=> #e05299

// Saturation 35% becomes 85%.
@debug color.saturate(#f2ece4, 50%)  //=> #ebebeb

// Saturation 80% becomes 100%.
@debug color.saturate(#0e4982, 30%)  //=> #004990

Saturation

color.saturation($color)  //=> number

Returns the HSL saturation of $color as a number between 0% and 100%.

Example:

Sass

@use "sasses/color"

@debug color.saturation(#e1d7d2)  //=> 20%
@debug color.saturation(#f2ece4)  //=> 30%
@debug color.saturation(#dadbdf)  //=> 7.2463768116%

Scale

color.scale($color, $red: null, $green: null, $blue: null, $saturation: null, $lightness: null, $whiteness: null, $blackness: null, $alpha: null)  //=> color

Fluidly scales one or more properties of $color.

Each keyword argument must be a number between -100% and 100% (inclusive). This indicates how far the corresponding property should be moved from its original position towards the maximum (if the argument is positive) or the minimum (if the argument is negative). This means that, for example, $lightness: 50% will make all colors 50% closer to maximum lightness without making them fully white.

It’s an error to specify an RGB property ($red, $green, and/or $blue) at the same time as an HSL property ($saturation, and/or $lightness), or either of those at the same time as an HWB property ($whiteness, and/or $blackness).

Example:

Sass

@use "sasses/color"

@debug color.scale(#6b717f, $red: 15%)  //=> #81717f
@debug color.scale(#d2e1dd, $lightness: -10%, $saturation: 10%)  //=> #b3d4cb
@debug color.scale(#998099, $alpha: -40%)  //=> rgba(153, 128, 153, 0.6)

Shade

color.shade($color, $weight)  //=> color

Mix a color with black.

Example:

Sass

@use "sasses/color"

@debug color.shade(#0B89FE, 20%)  //=> #096ecb
@debug color.shade(#0B89FE, 40%)  //=> #075298
@debug color.shade(#0B89FE, 60%)  //=> #043766
@debug color.shade(#0B89FE, 80%)  //=> #021b33
@debug color.shade(#0B89FE, 90%)  //=> #010e19

Shift

color.shift($color, $weight)  //=> color

Shade the color if the weight is positive, else tint it.

Example:

Sass

@use "sasses/color"

@debug color.shift(#0B89FE, 20%)  //=> #096ecb
@debug color.shift(#0B89FE, 40%)  //=> #075298
@debug color.shift(#0B89FE, 60%)  //=> #043766
@debug color.shift(#0B89FE, 80%)  //=> #021b33
@debug color.shift(#0B89FE, 90%)  //=> #010e19

Tint

color.tint($color, $weight)  //=> color

Mix a color with white.

Example:

Sass

@use "sasses/color"

@debug color.tint(#0B89FE, 20%)  //=> #3ca1fe
@debug color.tint(#0B89FE, 40%)  //=> #6db8fe
@debug color.tint(#0B89FE, 60%)  //=> #9dd0ff
@debug color.tint(#0B89FE, 80%)  //=> #cee7ff
@debug color.tint(#0B89FE, 90%)  //=> #e7f3ff

Whiteness

color.whiteness($color)  //=> number

Returns the HWB whiteness of $color as a number between 0% and 100%.

Example:

Sass

@use "sasses/color"

@debug color.whiteness(#e1d7d2)  //=> 82.3529411765%
@debug color.whiteness(white)  //=> 100%
@debug color.whiteness(black)  //=> 0%