better-color-tools

better-color-tools

Better color manipulation for Sass and JavaScript/TypeScript.

Installing

npm install better-color-tools

Sass

Sass has built-in color functions, but they aren’t as usable as they could be. Here’s why this library exists as an alternative.

Mix

Let’s compare this library’s mix function to Sass’ (Sass on top; better-color-tools on bottom):

Blend	Comparison
red–lime
red–yellow
blue–yellow
blue–fuchsia
blue–lime

It may be hard to tell a difference at first, but upon closer inspection you’ll see better results with the bottom colors in each row:

• better-color-utils produces brighter, more vibrant colors when mixing complementary colors, while Sass results in dark, muddy colors (compare mid tones in all examples)
• better-color-utils gives better spacing between colors while Sass inconsistently clumps certain hues together (compare blues in all examples)
• better-color-utils produces more expected colors than Sass (compare how better-color-tools passes through teal in blue–lime while Sass doesn’t)

Usage

@use 'better-color-tools' as color;

$mix: color.mix(#1a7f37, #cf222e, 0); // 100% color 1, 0% color 2
$mix: color.mix(#1a7f37, #cf222e, 0.25); // 75%, 25%
$mix: color.mix(#1a7f37, #cf222e, 0.5); // 50%, 50%
$mix: color.mix(#1a7f37, #cf222e, 0.75); // 25%, 75%
$mix: color.mix(#1a7f37, #cf222e, 1); // 0%, 100%

Lighten / Darken

⚠️ Still in development. It’s important to note that Sass’ new color.scale() utility is now a fantastic way to lighten / darken colors (previous attempts had been lacking). color.scale() produces better results than this library, currently, and I’m not happy with that 🙂.

@use 'better-color-tools' as color;

$lighter: color.lighten(#cf222e, 0); // 0% lighter (original color)
$lighter: color.lighten(#cf222e, 0.25); // 25% lighter
$lighter: color.lighten(#cf222e, 1); // 100% lighter (pure white)

$darker: color.darken(#cf222e, 0); // 0% darker (original color)
$darker: color.darken(#cf222e, 0.25); // 25% darker
$darker: color.darken(#cf222e, 1); // 100% darker (pure black)

JavaScript / TypeScript

Mix

View comparison (Sass’ mix function is a generic implementation of mixing you’ll find with other libraries in JavaScript)

Note: you’ll see 0xcf222e in the examples which is just another way of writing '#cf222e'. It’s just replacing the # with 0x. Use what you prefer!

import color from 'better-color-tools';

const mix = color.mix(0x1a7f37, 0xcf222e, 0); // 100% color 1, 0% color 2
const mix = color.mix(0x1a7f37, 0xcf222e, 0.25); // 75%, 25%
const mix = color.mix(0x1a7f37, 0xcf222e, 0.5); // 50%, 50%
const mix = color.mix(0x1a7f37, 0xcf222e, 0.75); // 25%, 75%
const mix = color.mix(0x1a7f37, 0xcf222e, 1); // 0%, 100%

Lighten / Darken

⚠️ In development (see note)

import color from 'better-color-tools';

color.lighten(0xcf222e, 0); // 0% lighter (original color)
color.lighten(0xcf222e, 0.25); // 25% lighter
color.lighten(0xcf222e, 1); // 100% lighter (pure white)

color.darken(0xcf222e, 0); // 0% darker (original color)
color.darken(0xcf222e, 0.25); // 25% darker
color.darken(0xcf222e, 1); // 100% darker (pure black)

Conversion

Color conversion between RGB and hexadecimal is a trivial 1:1 conversion, so this library isn’t better than any other in that regard.

It’s in HSL handling where approaches differ. Because HSL is a smaller color space than RGB, in order to use it, it requires at least 1 decimal place. So any library that rounds out-of-the-box will produce inaccurate results (compare this library to color-convert converting from RGB -> HSL and back again):

color.from(color.from([167, 214, 65]).hsl).rgbVal; // ✅ [167, 214, 65]
convert.hsl.rgb(convert.rgb.hsl(167, 214, 65)); // ❌ [168, 215, 66]

The reason, again, is rounding by default. This is a known limitation of HSL, so many libraries can disable rounding with overrides, but in addition to that not being default behavior it also produces noisy results:

color.from([167, 214, 65]).hsl; // hsl(78.93, 64.5%, 54.71%)
convert.rgb.hsl.raw([167, 214, 65]); // hsl(78.9261744966443, 64.50216450216452%, 54.70588235294118%)

This library takes the opinion that HSL should have RGB precision by default. So this library generates values that support infinite conversions without quality loss that are still readable.

Usage

import color from 'better-color-tools';

// convert color to hex
color.from('rgb(196, 67, 43)').hex; // '#c4432b'
color.from([196, 67, 43]).hex; // '#c4432b'
color.from('rgb(196, 67, 43)').hexVal; // 0xc4432b

// convert color to rgb
color.from('#C4432B').rgb; // 'rgb(196, 67, 43)'
color.from(0xc4432b).rgb; // 'rgb(196, 67, 43)'
color.from('#C4432B').rgbVal; // [196, 67, 43, 1]

// convert color to rgba
color.from('#C4432B').rgba; // 'rgba(196, 67, 43, 1)'
color.from(0xc4432b).rgba; // 'rgba(196, 67, 43, 1)'
color.from('#C4432B').rgbaVal; // [196, 67, 43, 1]

// convert color to hsl
color.from('#C4432B').hsl; // 'hsl(9.41, 64.02%, 46.86%, 1)'
color.from(0xc4432b).hsl; // 'hsl(9.41, 64.02%, 46.86%, 1)'
color.from('#C4432B').hslVal; // [9.41, 0.6402, 0.4686, 1]

// convert color names to hex
color.from('rebeccapurple').hex; // '#663399'

TODO / Roadmap

• Adding color spaces like Adobe and Rec 709 to allow color mixing and lightening/darkening to use different perceptual color algorithms
• This library currently only supports 8-bit RGB (web & apps); is 16-bit useful? (create an issue!)

Changelog

0.0.2

Patch Changes

• 181de13: Improve HSL accuracy by standardizing to 2 decimal places for all 3 values (before, hue had 3; saturation & lightness had 1)