Sass-Planifolia - Vanilla Sass helper functions
This is a collection of vanilla Sass helper functions, mostly centered around colors. It currently consists of only two modules:
- contrast for WCAG compatible color contrast functions
- color for color functions with supper for different color spaces, e.g. CIELAB, CIELUV, or HSLuv
These modules can be imported individually. The only define mixins and variables. They will not output any CSS. This means that importing them does not add a single byte to your CSS.
See the full documentation for more details.
Quick start
npm install sass-planifolia
Import it in your Sass files:
@use "node_modules/sass-planifolia/sass/contrast";
@use "node_modules/sass-planifolia/sass/color";
.test {
background-color: red;
// pick between two colors (default: black and white) to get good contrast
color: contrast.color(red);
// mix orange with black or white to get good contrast to red
border-color: contrast.stretch(red, orange);
// mix red with black in a perceptually uniform color space
box-shadow: 0 0 1em color.shade(red, 0.5, 'lab');
}
What is not included?
- Vendor prefixes, polyfills or browser hacks. There are plenty of librariers for that.
- pt/px/em/rem conversion. That is (a) not possible and (b) not helpful. Each unit has its specific use case. Learn to use the right units directly!
Similar libraries
- CSS Color Moudle Level 4 and CSS Color Module Level 5 are W3C Working Drafts (as of 2022-04-28) that would add similar features to CSS itself.
- PostCSS and Parcel both implement some of the functionality of CSS Color Module Level 4/5.
- oddbird/blend is yet another Sass library that implements similar features. The main difference is that the contrast function do not take transparency into account.
color
This module provides functions that 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')
.
variables
planifolia-colorspace
$planifolia-colorspace: 'lab' !default;
Type
String
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
lightness
@function 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
chroma
@function 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
hue
@function 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
@function adjust($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
@function change($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
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
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
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
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
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
distance
@function 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
contrast
Functions to help with contrast as defined by WCAG21
variables
planifolia-contrast-dark-default
$planifolia-contrast-dark-default: black !default;
Type
Color
planifolia-contrast-light-default
$planifolia-contrast-light-default: white !default;
Type
Color
functions
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]
color
- [function]
color
- [function]
stretch
- [function]
stretch
- [function]
stretch
- [function]
check
See
- [function]
contrast-min
color
@function 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
stretch
@function 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
check
@function 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