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 Nameparameter Descriptionparameter Typeparameter Default value
$lightness

0 .. 100

Number none
$chroma

0 .. 100 (some colorspaces may go beyond)

Number none
$hue noneAngle 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 Nameparameter Descriptionparameter Typeparameter Default value
$lightness noneNumber none
$chroma noneNumber none
$hue noneAngle none
$alpha noneNumber none
$colorspace

one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv'

String'lab'

Returns

Color

Requires

Used by

lightness

@function lightness($color, $colorspace: 'lab') { ... }

Description

Get the lightness component of a color.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$color noneColor 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 Nameparameter Descriptionparameter Typeparameter Default value
$color noneColor 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 Nameparameter Descriptionparameter Typeparameter Default value
$color noneColor 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 Nameparameter Descriptionparameter Typeparameter Default value
$color noneColor none
$lightness noneNumber0
$chroma noneNumber0
$hue noneAngle0
$colorspace

one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv'

String'lab'

Returns

Color

Requires

Used by

change

@function change($color, $lightness: null, $chroma: null, $hue: null, $colorspace: 'lab') { ... }

Description

Change one or more properties of a color.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$color noneColor none
$lightness noneNumbernull
$chroma noneNumbernull
$hue noneAnglenull
$colorspace

one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv'

String'lab'

Returns

Color

Requires

Used by

adjust-hue

@function adjust-hue($color, $angle, $colorspace: 'lab') { ... }

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$color noneColor none
$angle noneNumber none
$colorspace

one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv'

String'lab'

Returns

Color

Requires

Used by

lighten

@function lighten($color, $amount, $colorspace: 'lab') { ... }

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$color noneColor none
$amount noneNumber none
$colorspace

one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv'

String'lab'

Returns

Color

Requires

darken

@function darken($color, $amount, $colorspace: 'lab') { ... }

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$color noneColor none
$amount noneNumber none
$colorspace

one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv'

String'lab'

Returns

Color

Requires

tint

@function tint($color, $weight, $colorspace: 'lab') { ... }

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$color noneColor none
$weight noneNumber none
$colorspace

one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv'

String'lab'

Returns

Color

Requires

shade

@function shade($color, $weight, $colorspace: 'lab') { ... }

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$color noneColor none
$weight noneNumber none
$colorspace

one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv'

String'lab'

Returns

Color

Requires

saturate

@function saturate($color, $amount, $colorspace: 'lab') { ... }

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$color noneColor none
$amount noneNumber none
$colorspace

one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv'

String'lab'

Returns

Color

Requires

desaturate

@function desaturate($color, $amount, $colorspace: 'lab') { ... }

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$color noneColor none
$amount noneNumber none
$colorspace

one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv'

String'lab'

Returns

Color

Requires

complement

@function complement($color, $colorspace: 'lab') { ... }

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$color noneColor none
$colorspace

one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv'

String'lab'

Returns

Color

Requires

grayscale

@function grayscale($color, $colorspace: 'lab') { ... }

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$color noneColor none
$colorspace

one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv'

String'lab'

Returns

Color

Requires

distance

@function distance($color1, $color2) { ... }

Description

Get the euclidean distance between two colors.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$color1 noneColor none
$color2 noneColor none

Returns

Number

mix

@function mix($color1, $color2, $weight: 50%, $colorspace: 'lab') { ... }

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$color1 noneColor none
$color2 noneColor none
$weight noneNumber50%
$colorspace

one of 'lab', 'luv', 'hsl', 'yuv', 'hslab', 'hsluv'

String'lab'

Returns

Color

Requires

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 Nameparameter Descriptionparameter Typeparameter 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 Nameparameter Descriptionparameter Typeparameter Default value
$color1 noneColor none
$color2 noneColor none

Returns

Number

between 1 and 21

Requires

Used by

See

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 Nameparameter Descriptionparameter Typeparameter 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 Nameparameter Descriptionparameter Typeparameter Default value
$base noneColor none
$color noneColor none
$threshold

(can also be 'AA', 'AALG', 'AAA', or 'AAALG')

Number4.5

Returns

Color

Requires

check

@function check($base, $color, $threshold: 4.5) { ... }

Description

Warn if the contrast is below a threshold.

Parameters

parameter Nameparameter Descriptionparameter Typeparameter Default value
$base noneColor none
$color noneColor none
$threshold

(can also be 'AA', 'AALG', 'AAA', or 'AAALG')

Number4.5

Returns

Color

unchanged $color

Requires