This package contains all the functions for generating colors by target contrast ratio.
Using Leonardo Contrast Colors
Install the package:
npm i @adobe/leonardo-contrast-colors
Import the package:
CJS (Node 12.x)
const generateAdaptiveTheme = ;
ESM (Node 13.x)
Pass your colors and desired ratios (see additional options below):
// returns theme colors as JSONlet myTheme =;
Function used to create a fully adaptive contrast-based color palette/theme using Leonardo. Parameters are destructured and need to be explicitly called, such as
colorKeys: ["#f26322"]. Parameters can be passed as a config JSON file for modularity and simplicity.
; // returns function; // returns color objects
colorScales [array of objects]:
colorScales object with all options:
name: 'blue'colorKeys: '#5CDBFF' '#0000FF'colorSpace: 'LCH'ratios:'blue--largeText': 3'blue--normalText': 45
baseScale string (enum):
String value matching the
name of a
colorScales object to be used as a base scale (background color). This creates a scale of values from 0-100 in lightness, which is used for
brightness parameter. Ie.
brightness: 90 returns the 90% lightness value of the base scale.
Unique name for each color scale. This value refers to the entire color group (eg "blue") and will be used for the output color keys, ie
ratios array or object:
List of numbers to be used as target contrast ratios. If entered as an array, swatch names are incremented in
100s such as
blue200 based on the color scale name.
ratios can be an object with custom keys to name each color, such as
Optional value from 0-100 indicating the brightness of the base / background color. If undefined,
generateAdaptiveTheme will return a function
Optional value to increase contrast of your generated colors. This value is multiplied against all ratios defined for each color scale.
output string (enum):
String value of the desired color space and output format for the generated colors. Output formats conform to the W3C CSS Color Module Level 4 spec for the supported options.
|Output option||Sample value|
Function outputs and examples
generateAdaptiveTheme function returns an array of color objects. Each key is named by concatenating the user-defined color name (above) with a numeric value.
Colors with a positive contrast ratio with the base (ie, 2:1) will be named in increments of 100. For example,
Colors with a negative contrast ratio with the base (ie -2:1) will be named in increments less than 100 and based on the number of negative values declared. For example, if there are 3 negative values
[-1.4, -1.3, -1.2, 1, 2, 3], the name for those values will be incremented by 100/4 (length plus one to avoid a
0 value), such as
Here is an example output from a theme:
background: "#e0e0e0"name: 'gray'values:name: "gray100" contrast: 1 value: "#e0e0e0"name: "gray200" contrast: 2 value: "#a0a0a0"name: "gray300" contrast: 3 value: "#808080"name: "gray400" contrast: 45 value: "#646464"name: 'blue'values:name: "blue100" contrast: 2 value: "#b18cff"name: "blue200" contrast: 3 value: "#8d63ff"name: "blue300" contrast: 45 value: "#623aff"name: "blue400" contrast: 8 value: "#1c0ad1"
Creating your theme as a function
let myPalette =colorScales:name: 'gray'colorKeys: '#cacaca'colorspace: 'HSL'ratios: 1 2 3 45 8 12name: 'blue'colorKeys: '#5CDBFF' '#0000FF'colorspace: 'HSL'ratios: 3 45name: 'red'colorKeys: '#FF9A81' '#FF0000'colorspace: 'HSL'ratios: 3 45baseScale: 'gray'let myTheme = ;// outputs colors with background lightness of 95 and ratios increased by 1.2
Creating static instances of your theme
// theme on light graylet lightTheme = ;// theme on dark gray with increased contrastlet darkTheme = ;
Assigning output to CSS properties
let varPrefix = '--';// Iterate each color objectfor let i = 0; i < myThemelength; i++// Iterate each value object within each color objectforlet j = 0; j < myThemeivalueslength; j++// output "name" of color and prefixlet key = myThemeivaluesjname;let prop = varPrefix;// output value of colorlet value = myThemeivaluesjvalue;// create CSS property with name and valuedocumentdocumentElementstyle;
Primary function used to generate colors based on target contrast ratios. Parameters are destructured and need to be explicitly called, such as
List of colors referenced to generate a lightness scale. Much like key frames, key colors are single points by which additional colors will be interpolated between.
References the color value that the color is to be generated from.
List of numbers to be used as target contrast ratios.
The colorspace in which the key colors will be interpolated within. Below are the available options:
This function is used to generate a color scale tailored specifically for use as a brightness scale when using Leonardo for brightness and contrast controls. Colors are generated that match HSLuv lightness values from
100 and are output as hex values.
Only accepts colorKeys and colorspace parameters, as defined above for
Why are not all contrast ratios available?
You may notice the tool takes an input (target ratio) but most often outputs a contrast ratio slightly higher. This has to do with the available colors in the RGB color space, and the math associated with calculating these ratios.
For example let's look at blue and white. Blue: rgb(0, 0, 255) White: rgb(255, 255, 255) Contrast ratio: 8.59:1
If we change any one value in the RGB channel for either color, the ratio changes: Blue: rgb(0, 1, 255) White: rgb(255, 255, 255) Contrast ratio: 8.57:1
If 8.58 is input as the target ratio with the starting color of blue, the output will not be exact. This is exaggerated by the various colorspace interpolations.
Since the WCAG requirement is defined as a minimum contrast requirement, it should be fine to generate colors that are a little more accessible than the minimum.
This project is currently built using D3 color. Although functionality is comparable to Chroma.js, the choice of D3 color is based on the additional modules available for state-of-the-art color appearance models, such as CIE CAM02.
createScale() function is basically a wrapper function for creating a d3 linear scale for colors, with a few enhancements that aid in the
The Leonardo web app leverages d3 for additional features such as generating 2d and 3d charts.
Contributions are welcomed! Read the Contributing Guide for more information.
You can run tests and watch for changes with:
This project is licensed under the Apache V2 License. See LICENSE for more information.