🤹 color-math

ColorMath is an expression parser and evaluator dealing with color representations. Using special grammar it supports various color models, mixing, blending, channels manipulation, scaling, bezier interpolation and more. It also supports transpiling most of the expressions to less.js.

Install

npm i color-math -S

Usage Example

import * as ColorMath from "color-math"

// will return color which is result of mixing red and green colors
const result = ColorMath.evaluate("red | green")
// prints "#804000" ('result.result' is a chroma.js instance; see link below)
console.log(result.result.hex())

// set color's alpha channel to 30%
result = ColorMath.evaluate("red @a 30%")
console.log(result.result.css()) // prints "rgba(255, 0, 0, 0.3)"

// arithmetic operations with colors and numbers
result = ColorMath.evaluate("(#222 + #444) / 2")
console.log(result.resultStr) // prints "#333333"

// transpile to Less
result = ColorMath.evaluate("rgb 165 42 42 >> .2", { evaluator: new ColorMath.Evaluators.LessEvaluator() })
console.log(result.result) // prints "saturate(rgb(165, 42, 42), 20%, relative)"

chroma.js color library is used internally to manipulate colors and wrap results.

Expressions Cheatsheet

Click on expression to visualize result in ColorMath online parser.

Use parenthesis to control evaluation order and build complex expressions.

Ways to Define Color

Expression	Description
`#ffcc00`	hexadecimal color representation
`ffcc00`	hexadecimal color representation without hash symbol
`#fc0`	short hexadecimal color representation
`fc0`	short hexadecimal color representation without hash symbol
`skyblue`	color literals from W3C/X11 specification
`rand`	generate random color
`num 33023`	color from number
`temp 3500`	color by temperature in Kelvin
`wl 560`	color from wavelength value

Color Models

Expression	Description
`rgb 127 255 212`	RGB color model
`rgba 135 206 235 75%`	RGB color model with alpha channel
`argb .7 255 99 71`	RGB color model with alpha channel (first)
`cmyk .43 .12 0 .8`	CMYK color model
`cmyka 0 .61 .72 0 60%`	CMYK color model with alpha channel
`cmy .5 0 .17`	CMY color model
`cmya 0 .61 .72 .65`	CMY color model with alpha channel
`hsl 159.8 100% 75%`	HSL color model
`hsla 197 .71 .73 55%`	HSL color model with alpha channel
`hsv 160 .5 1`	HSV (also known as HSB) color model
`hsb 197 .43 .92`	HSB color model (alias for HSV)
`hsva 9 .72 1 50%`	HSV color model with alpha channel
`hsi 161 .36 .78`	HSI color model
`hsia 196 .30 .75 45%`	HSI color model with alpha channel
`lab 92 (-46) 9.7`	LAB color model
`laba 79 (-14.8) (-21) 40%`	LAB color model with alpha channel
`lch 92 46.5 168`	LCH color model
`lcha 79 26 235 35%`	LCH color model with alpha channel
`hcl 168 46.5 92`	HCL color model (reversed LCH)
`hcla 235 26 79 35%`	HCL color model with alpha channel

Color Operations

Expression	Description
`#444 * 2`	arithmetic operations with numbers
`skyblue - 0xf`	arithmetic operations with numbers
`~red`	invert color
`red \| green`	mix colors
`red \| {25%} green`	mix colors in variable proportion
`red \| {25% hsl} green`	mix colors in variable proportion and specific color model
`red \| {hsl} green`	mix colors in specific color model
`hotpink << 50%`	desaturate color
`rgb 165 42 42 >> .2`	saturate color
`temp 4000 <<< 30%`	darken color
`#fc0 >>> 70%`	lighten color
`pink %% hotpink`	compute WCAG contrast ratio between two colors

Color Blending

Expression	Description
`#222 + #444`	add
`#ccc - #111`	subtract
`#ff6600 * #ccc`	multiply
`#222 / #444`	divide
`skyblue <<< tomato`	darken
`skyblue >>> tomato`	lighten
`#ff6600 !* #00ff00`	screen
`#ff6600 ** #999`	overlay
`olive <* pink`	hard light
`olive *> pink`	soft light
`ffcc00 ^* ccc`	difference
`ffcc00 ^^ ccc`	exclusion
`ffcc00 !^ ccc`	negate
`indigo << red`	burn
`indigo >> red`	dodge

Color Channels Manipulation

Expression	Description
`brown @red`	get channel's value using its name or synonym
`#ffcc00 @g`	get channel's value using its name or synonym
`t 5000 @cmyk.y`	get channel's value using its name or synonym
`aquamarine @a = .3`	set channel's absolute value
`rgb 5 7 9 @hsl.h 90`	set channel's absolute value
`#000 @lightness 50%`	set channel's absolute value
`red @a /= 2`	set relative channel's value
`ffcc00 @rgb.r -= 50`	set relative channel's value
`tomato @s *= 30%`	set relative channel's value
`olive @n`	get color's numeric value
`fff @n 0`	set color's absolute numeric value
`#0080ff @n /= 2`	set color's relative numeric value
`#ffe3cd @t`	get color's temperature in Kelvin
`red @t 3500`	set color's absolute temperature
`ffe3cd @t += 500`	set color's relative temperature

Color Scales

Expression	Description
`scale (red 0f0 blue)`	scale list of colors (make gradient)
`scale (yellow 008ae5) -> 20`	grab n equi-distant colors from a color scale
`scale (t 2000 t 6000)`	scale list of colors
`bezier (ff0 red #000)`	perform bezier interpolate of list of colors
`bezier (red 0f0)`	perform bezier interpolate of list of colors
`scale (red:.2 0f0:50%)`	set position of each color (inline)
`scale (red 0f0) @domain (.2 .5)`	set position of each color (as a parameter)
`scale (red 0f0) @pad .25`	cut off a fraction of the gradient on both sides
`bezier (red 0f0) @pad (.1 .3)`	cut off a fraction of the gradient on both sides
`cubehelix`	Dave Green's cubehelix scaled color scheme
`cubehelix @pad (0 .2)`	cut off a fraction of the gradient on both sides
`cubehelix @start 200`	start for hue rotation
`cubehelix @rot (-.5)`	number of rotations
`cubehelix @hue .5`	controls how saturated colors of all hues are
`cubehelix @hue (1 0)`	controls how saturated colors of all hues are
`cubehelix @gamma .7`	emphasize low or high intensity values
`cubehelix @lt (.3 .8)`	adjust lightness (black to white)
`cubehelix @start 200 @rot .5`	parameters can be chained
`+scale (black red yellow)`	auto-correct lightness of a scale
`+bezier (yellow 0f0 blue) -> 10`	auto-correct lightness and grab n equi-distant colors

Numbers

Expression	Description
`0b01101001`	binary
`0o151`	octal
`105`	decinal
`0x69`	hexadecimal
`55%`	percent value
`5 + 10`	add numbers
`-360 * 0.5 + (100 - 40)`	arithmetic operations
`0xf / 0b1010`	division
`4 ^ (2 / 4)`	take expression to a specified power

Lists

Expression	Description
`red 0f0 blue`	define list of three colors
`(pink >> .5) gold`	define list of two colors

Brewer Constants

OrRd, PuBu, BuPu, Oranges, BuGn, YlOrBr, YlGn, Reds, RdPu, Greens, YlGnBu, Purples, GnBu, Greys, YlOrRd, PuRd, Blues, PuBuGn, Spectral, RdYlGn, RdBu, PiYG, PRGn, RdYlBu, BrBG, RdGy, PuOr, Set2, Accent, Set1, Set3, Dark2, Paired, Pastel2, Pastel1

Variables and Statements

Expression	Description
`$col = rgb 255 204 0`	assign color value to a variable
`$num = 2^8 - 1`	assign number value to a variable
`$lst = #444 #888`	assign list value to a variable
`$my = yellow black; bezier $my`	separate statements with semicolon

A read–eval–print loop (REPL)

npm start

Interpreter will start. Now you can type your expressions.

Demo and documentation

Please go to http://colormath.net/ to test your expressions, visualize results and read about all available features with examples.

mezzario/color-math