🌈 Color manipulation functions for JavaScript.
Fantasy Color provides types for the various color formats. These types are used throughout the @fantasy-color packages, and they are available in the @fantasy-color/types package:
yarn add @fantasy-color/types
type TWithAlpha = {
alpha: number,
}
type TRgb = {
red: number,
green: number,
blue: number,
}
type TRgba = TRgb & TWithAlpha
type THsv = {
hue: number,
saturation: number,
value: number,
}
type THsva = THsv & TWithAlpha
type THcl = {
hue: number,
chroma: number,
luminance: number,
}
type THcla = THcl & TWithAlpha
type TLab = {
luminance: number,
a: number,
b: number,
}
type TLaba = TLab & TWithAlpha@fantasy-color/contrast-ratio-luminance: Calculate the contrast ratio of two relative luminances@fantasy-color/contrast-ratio-rgb: Calculate contrast ratio based on RGB input
@fantasy-color/from-hex: Parse HEX CSS strings intoRGBobjects@fantasy-color/from-rgb: Parse RGB CSS strings intoRGBobjects@fantasy-color/from-rgba: Parse RGBA CSS strings intoRGBAobjects
@fantasy-color/hcl-to-lab: TransformHCLobjects toLABobjects@fantasy-color/hcl-to-rgb: TransformHCLobjects toRGBobjects@fantasy-color/hsv-to-hsva: TransformHSVobjects toHSVAobjects@fantasy-color/hsv-to-rgb: TransformHSVobjects toRGBobjects@fantasy-color/hsva-to-hsv: TransformHSVAobjects toHSVobjects@fantasy-color/hsva-to-rgba: TransformHSVAobjects toRGBAobjects@fantasy-color/lab-to-hcl: TransformLABobjects toHCLobjects@fantasy-color/lab-to-rgb: TransformLABobjects toRGBobjects@fantasy-color/rgb-to-hcl: TransformRGBobjects toHCLobjects@fantasy-color/rgb-to-hsv: TransformRGBobjects toHSVobjects@fantasy-color/rgb-to-lab: TransformRGBobjects toLABobjects@fantasy-color/rgb-to-rgba: TransformRGBobjects toRGBAobjects@fantasy-color/rgb-to-srgb: TransformRGBobjects to sRGB objects (coded in theRGBtype)@fantasy-color/rgba-to-hsva: TransformRGBAobjects toHSVAobjects@fantasy-color/rgba-to-rgb: TransformRGBAobjects toRGBobjects
@fantasy-color/map-color-space-polynomial: Transform a three-tuple from one color space into another passing the coefficients and degree of the transformation
@fantasy-color/normalize-rgb: Transform fromRGBobjects from the 0-255 range to 0-1 decimal points@fantasy-color/normalize-rgba: Transform fromRGBAobjects from the 0-255 range to 0.1 decimal points
@fantasy-color/luminance-for-contrast-ratio: For a given contrast ratio and a relative luminance, give a relative luminance that will match this contrast ratio. If the given relative luminance is above 0.5, the returned relative luminance will be lower; if the given relative luminance is below of 0.5, the returned luminance will be higher.@fantasy-color/luminance-rgb: For a givenRGBcolor, return its relative luminance.@fantasy-color/luminance-srgb: For a given sRGB color (coded as anRGBobject), return its relative luminance.
This library is to a big extent a partial reimplementation of several other libraries that operate with color and luminosity. The main acknowledgement goes to d3-color, from which much of the code has been adapted. The motivation for the partial reimplementation is to deliver the code in a way that each transformation can be requested as an independent, small package, in order to minimize the impact on bundle size.
The contrast ratio calculation is taken from the WCAG contrast ratio calculation, so this library is useful to automatically check for accessibility compliance.
The relative luminance calculation is done based on the WCAG sRGB relative luminance calculation
- Online WCAG contrast ratio calculator
- HCL Color Picker (based on
d3-color)
Turns out that sRGB is the color space in which it was specificed the formula for relative luminance used by WCAG for the contrast ratio calculation. https://www.w3.org/TR/2008/REC-WCAG20-20081211/#relativeluminancedef
This seems to be a historical accident. sRGB appears to be explicitly deprecated by the w3c https://www.w3.org/Graphics/Color/sRGB.html , raising the question on why would WCAG be specified in a way that makes it actually harder to calculate from the standard CSS RGB.
In order to get colors with equivalent hue and saturation but different perceptual luminance, none of the most widespread color spaces (rgb, hsl, hsv) are useful. There is the need for a color space that corrects for brightness by hue.
This is what both CIE L*a*b* and HCL achieve.