The purpose of this package is to provide all necessary functions for working with CSS colors as well as additional useful utilities for real-world use-cases.

Installation

yarn add @adeira/css-colors

Usage

Get color keywords

import { cssColorNames } from '@adeira/css-colors';

cssColorNames.get('rebeccapurple'); // => #663399

The imported cssColorNames is a Map of all CSS keywords, so you can use any available Map methods.

Is it a color?

import { isColor } from '@adeira/css-colors';

isColor('#663399'); // true
isColor('rebeccapurple'); // true
isColor('rgb(255, 255, 128)'); // true
isColor('transparent'); // true
isColor('currentcolor'); // true
isColor('hsl(50, 33%, 25)'); // false (last number should be 25%)

What is the color contrast ratio?

This function takes triplet of colors for foreground and background colors and calculates their contrast ratio (from 1:1 for no contrast up to 25:1 for excellent contrast):

import { calculateContrastRatio } from '@adeira/css-colors';

calculateContrastRatio([130, 242, 75], [119, 46, 242]); // 4.27 (4.27:1)

See: https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast

Is the pair of colors accessible?

Allows you to decide whether a pair of two colors (typically foreground and background) is accessible:

import { isAccessible } from '@adeira/css-colors';

isAccessible([0, 0, 0], [255, 255, 255]); // true (black and white combo)

// optionally, you can specify context of these colors and success criteria for accessibility:
isAccessible([64, 32, 17], [201, 120, 136], 'NORMAL_TEXT', 'AAA'); // false
isAccessible([64, 32, 17], [201, 120, 136], 'NORMAL_TEXT', 'AA'); // true
isAccessible([64, 32, 17], [201, 120, 136], 'LARGE_TEXT', 'AAA'); // true
isAccessible([64, 32, 17], [201, 120, 136], 'GRAPHICAL_OBJECTS'); // true

Note on colors accessibility: it can happen that some backgrounds are never accessible under AAA criteria. For example #FF1A1A always fails "normal text" test for AAA criteria (no matter whether you choose completely white or completely black font).

What color is the best for this background?

import { chooseHigherContrast } from '@adeira/css-colors';

chooseHigherContrast(
  [255, 255, 255], // foreground color 1 ✅
  [128, 128, 128], // foreground color 2 ❌
  [0, 0, 0], // background
);

The function above returns [255, 255, 255] because white is better on a black background than grey.

Normalize colors

import { normalizeColor } from '@adeira/css-colors';

normalizeColor('#639'); // #639
normalizeColor('#663399'); // #639
normalizeColor('rebeccapurple'); // #639

HEX to HEX

import { hex3ToHex6, hex6ToHex3 } from '@adeira/css-colors';

hex3ToHex6('#639'); // #663399
hex6ToHex3('#663399'); // #639

convertToRGBTriplet

TKTK