@johv/sass-labmix
This pure-Sass library provides an alternative to some of the features that will be added in CSS Color Module Level 5, namely mix
as an alternative to color-mix()
and support for Lab and LCh color spaces through the lab
and lch
functions.
When these functions become commonly available through CSS, this library will be deprecated. See the Alternatives section below for more information.
The library is a fork of Tobias Bengfort's sass-planifolia. The aim of this fork is to strip it down to just the color-manipulation functions and bring it up to date with the current version of Sass. Read this pull request to understand why this fork exists.
See the full documentation for more details.
Quick start
Install the library:
npm install --save-dev @johv/sass-labmix
Import it in your Sass files (most bundlers support the tilde-syntax; otherwise use node_modules/@johv/sass-labmix
explicitly):
@use "~@johv/sass-labmix" as labmix;
.test {
background-color: red;
// pick between two colors (default: black and white) to get good contrast
color: labmix.contrast-color(red);
// mix orange with black or white to get good contrast to red
border-color: labmix.contrast-stretch(red, orange);
// mix red with black in a perceptually uniform color space
box-shadow: 0 0 1em labmix.shade(red, 0.5, 'lab');
}
Alternatives
- CSS Color Module Level 5 will provide native support for Lab and related color spaces and will support color mixing with
colox-mix()
. However, as of May 2022, it is not yet widely available. - Parcel's CSS transformer implements some of the functionality of CSS Color Module Level 5, including
color-mix()
andlch()
. If you're already using Parcel, just use that instead! - PostCSS supports Lab and related color spaces through postcss-preset-env, but as of May 2022, it does not support
color-mix()
. - This library is a fork of sass-planifolia. This fork has less functionality, but aims to be compatible with Dart Sass (without triggering any deprecation warnings). Changes made here may or may not be upstreamed into Planifolia in the future.
- oddbird/blend also provides early access to some of the functionality of the CSS Color Module Level 5 features, but unless I'm missing something, there is no equivalent of
mix
.
index
These functions can be used as drop-in replacements for some of the HSL based functions included in Sass.
The implementations use sRGB for input colors (including the whitepoint D65) and converts them to CIELAB by default, but CIELUV, HSL or YUV are also possible.
CIELAB and CIELUV both try to be close to human perception, so they may give nicer results in many cases than simple RGB/HSL.
HSLab and HSLuv are variants of CIELAB and CIELUV that scale the chroma instead of clipping. With CIELAB, you know that lch(40, 50, 10deg, 'lab')
and lch(70, 50, 90deg, 'lab')
have the same chroma (except when clipping is applied). With HSLab, you know that lch(40, 50, 10deg, 'hslab')
always has half the chroma of lch(40, 100, 10deg, 'hslab')
.
We also provide functions to help with contrast as defined by WCAG21
variables
default-colorspace
$default-colorspace: 'lab' !default;
Type
String
contrast-dark-default
$contrast-dark-default: black !default;
Type
Color
contrast-light-default
$contrast-light-default: white !default;
Type
Color
functions
lch
@function lch($lightness, $chroma, $hue, $colorspace: 'lab') { ... }
Description
Create a color from lightness, chroma, and hue values.
Note that the chroma is reduced if the result would otherwise be outside of the sRGB colorspace.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$lightness | 0 .. 100 | Number | — none |
$chroma | 0 .. 100 (some colorspaces may go beyond) | Number | — none |
$hue | — none | Angle | — none |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Color
Used by
lcha
@function lcha($lightness, $chroma, $hue, $alpha, $colorspace: 'lab') { ... }
Description
Create a color from lightness, chroma, hue, and alpha values.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$lightness | — none | Number | — none |
$chroma | — none | Number | — none |
$hue | — none | Angle | — none |
$alpha | — none | Number | — none |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Color
Requires
- [function]
lch
Used by
- [function]
adjust-color
- [function]
change-color
get-lightness
@function get-lightness($color, $colorspace: 'lab') { ... }
Description
Get the lightness component of a color.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color | — none | Color | — none |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Number
get-chroma
@function get-chroma($color, $colorspace: 'lab') { ... }
Description
Get the chroma component of a color.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color | — none | Color | — none |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Number
get-hue
@function get-hue($color, $colorspace: 'lab') { ... }
Description
Get the hue component of a color.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color | — none | Color | — none |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Angle
adjust-color
@function adjust-color($color, $lightness: 0, $chroma: 0, $hue: 0, $colorspace: 'lab') { ... }
Description
Increase or decrease one or more components of a color.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color | — none | Color | — none |
$lightness | — none | Number | 0 |
$chroma | — none | Number | 0 |
$hue | — none | Angle | 0 |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Color
Requires
- [function]
lcha
Used by
- [function]
adjust-hue
- [function]
lighten
- [function]
darken
- [function]
saturate
- [function]
desaturate
change-color
@function change-color($color, $lightness: null, $chroma: null, $hue: null, $colorspace: 'lab') { ... }
Description
Change one or more properties of a color.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color | — none | Color | — none |
$lightness | — none | Number | null |
$chroma | — none | Number | null |
$hue | — none | Angle | null |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Color
Requires
- [function]
lcha
Used by
- [function]
grayscale
adjust-hue
@function adjust-hue($color, $angle, $colorspace: 'lab') { ... }
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color | — none | Color | — none |
$angle | — none | Number | — none |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Color
Requires
- [function]
adjust-color
Used by
- [function]
complement
lighten
@function lighten($color, $amount, $colorspace: 'lab') { ... }
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color | — none | Color | — none |
$amount | — none | Number | — none |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Color
Requires
- [function]
adjust-color
darken
@function darken($color, $amount, $colorspace: 'lab') { ... }
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color | — none | Color | — none |
$amount | — none | Number | — none |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Color
Requires
- [function]
adjust-color
tint
@function tint($color, $weight, $colorspace: 'lab') { ... }
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color | — none | Color | — none |
$weight | — none | Number | — none |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Color
Requires
- [function]
mix
shade
@function shade($color, $weight, $colorspace: 'lab') { ... }
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color | — none | Color | — none |
$weight | — none | Number | — none |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Color
Requires
- [function]
mix
saturate
@function saturate($color, $amount, $colorspace: 'lab') { ... }
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color | — none | Color | — none |
$amount | — none | Number | — none |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Color
Requires
- [function]
adjust-color
desaturate
@function desaturate($color, $amount, $colorspace: 'lab') { ... }
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color | — none | Color | — none |
$amount | — none | Number | — none |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Color
Requires
- [function]
adjust-color
complement
@function complement($color, $colorspace: 'lab') { ... }
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color | — none | Color | — none |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Color
Requires
- [function]
adjust-hue
grayscale
@function grayscale($color, $colorspace: 'lab') { ... }
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color | — none | Color | — none |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Color
Requires
- [function]
change-color
color-distance
@function color-distance($color1, $color2) { ... }
Description
Get the euclidean distance between two colors.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color1 | — none | Color | — none |
$color2 | — none | Color | — none |
Returns
Number
mix
@function mix($color1, $color2, $weight: 50%, $colorspace: 'lab') { ... }
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color1 | — none | Color | — none |
$color2 | — none | Color | — none |
$weight | — none | Number | 50% |
$colorspace | one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv' | String | 'lab' |
Returns
Color
Requires
- [function]
lch
Used by
- [function]
tint
- [function]
shade
- [function]
contrast-stretch
contrast-min
@function contrast-min($fg, $bg) { ... }
Description
Calculate the minimum possible contrast between two colors.
Note that the "minimum" part of this is only relevant if $bg
is transparent. In that case, a backdrop color is chosen so that the resulting contrast is minimal.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$fg | foreground color | Color | — none |
$bg | background color | Color | — none |
Returns
Number
—between 1 and 21
Used by
contrast
@function contrast($color1, $color2) { ... }
Description
Calculate the contrast between two colors.
This function is different from contrast-min
by not caring about the order of inputs. This is achieved by calculating the average of both possible results of contrast-min
.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$color1 | — none | Color | — none |
$color2 | — none | Color | — none |
Returns
Number
—between 1 and 21
Requires
- [function]
contrast-min
- [function]
contrast-min
Used by
- [function]
contrast-color
- [function]
contrast-color
- [function]
contrast-stretch
- [function]
contrast-stretch
- [function]
contrast-stretch
- [function]
contrast-check
See
- [function]
contrast-min
contrast-color
@function contrast-color($base, $color1: $planifolia-contrast-dark-default, $color2: $planifolia-contrast-light-default) { ... }
Description
Pick the higher contrast option for a given base color.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$base | the base color to compare to | Color | — none |
$color1 | first option | Color | $planifolia-contrast-dark-default |
$color2 | second option | Color | $planifolia-contrast-light-default |
Returns
Color
—either $color1
or $color2
Requires
contrast-stretch
@function contrast-stretch($base, $color, $threshold: 4.5) { ... }
Description
Mix color with black or white to increase contrast for a given base color.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$base | — none | Color | — none |
$color | — none | Color | — none |
$threshold | (can also be 'AA', 'AALG', 'AAA', or 'AAALG') | Number | 4.5 |
Returns
Color
Requires
contrast-check
@function contrast-check($base, $color, $threshold: 4.5) { ... }
Description
Warn if the contrast is below a threshold.
Parameters
parameter Name | parameter Description | parameter Type | parameter Default value |
---|---|---|---|
$base | — none | Color | — none |
$color | — none | Color | — none |
$threshold | (can also be 'AA', 'AALG', 'AAA', or 'AAALG') | Number | 4.5 |
Returns
Color
—unchanged $color
Requires
- [function]
contrast