Welcome to CssColor

Introduction

CssColor is a Typescript package. It helps you work with popular color models.

It is released under the 3-clause New BSD license. See LICENSE.md for details.

Quick Start

# run this from your Terminal
npm install @safelytyped/css-color

1// add this import to your Typescript code
2import { makeCssColor } from "@safelytyped/css-color"
3
4const myColor = makeCssColor("red");

Table of Contents

• Introduction
• Quick Start
• Why Use CssColor?
  • Who Is CssColor For?
  • Why Use CssColor?
• How Does It Work?
  • Getting Started
• CssColor
  • What Is A CssColor Object?
  • Creating A CssColor Object
  • Assigning A Name To A CssColor Object
  • Getting The Individual Color Channels
  • Converting Between Color Models and Color Spaces
  • Getting the CSS Hex Value
  • Getting The CSS Named Color
  • Getting The CSS For Different Color Models
• Color Models and Color Spaces
  • What Are Color Models and Color Spaces?
  • Why We Need To Keep Track Of Both
  • Color Models Are Not Always Unique
  • Converting Between Color Spaces Gets Funky Real Quick
• CssCmykColor
  • How To Create A CssCmykColor
  • Color Channels
  • Channel Data
• CssHexColor
  • How To Create A CssHexColor
  • Color Channels
  • Channel Data
• CssHslColor
  • How To Create A CssHslColor
  • Color Channels
  • Channel Data
• CssHsvColor
  • How To Create A CssHsvColor
  • Color Channels
  • Channel Data
• CssHwbColor
  • How To Create A CssHwbColor
  • Color Channels
  • Channel Data
• CssOklchColor
  • How To Create A CssOklchColor
  • Color Channels
  • Channel Data
• CssRgbColor
  • How To Create A CssRgbColor
  • Color Channels
  • Channel Data
• Inspectors
  • contrastRatio()
  • darkModeContrastRatio()
  • hasClearContrast()
  • isDark()
  • isLight()
  • isMidtone()
  • isMonochrome()
  • lightModeContrastRatio()
  • luma()
  • relativeLuminance()
  • tonality()
  • wcagContrast()
• CSS Named Colors
  • What Are CSS Named Colors?
  • CssNamedColor
  • CSS_NAMED_COLOR_TO_HEX
  • CSS_HEX_TO_NAMED_COLOR
  • isCssNamedColor()
  • mustBeCssNamedColor()
  • validateCssNamedColor()

Why Use CssColor?

Who Is CssColor For?

We've built CssColor for anyone who wants to work with popular CSS color formats (aka color models) in their Typescript code.

We're using CssColor to produce the documentation for Imprint CSS, our upcoming Tailwind CSS plugin.

Why Use CssColor?

There are plenty of well-established Javascript packages for working with CSS colors. So what makes CssColor different?

• Smart constructors (such as makeCssColor()) ensure that CssColor objects always contain valid colors.
• Need to convert a color to another format? Each CssColor object has conversion built in.
• Need to analyse a color pair for accessibility compliance? WCAG 2.2 compliance is available for every supported CssColor.

It's basically safer and easier to use than many other packages.

How Does It Work?

Getting Started

Install the CssPackage into your Typescript project:

# run this from your Terminal
npm install @safelytyped/css-color

Import makeCssColor() into your Typescript file:

1import { makeCssColor } from "@safelytyped/css-color";

and then call makeCssColor() to create a CssColor object:

1const red = makeCssColor("red");

Once you have your CssColor object, you can do things like:

• get its individual components (e.g. get the red channel on its own)
• convert it to different color models (e.g. convert from RGB to OKLCH)
  • and then convert that back into CSS (e.g. generate the CSS for oklch() after converting from RGB to OKLCH)
• analyse it for accessibility

CssColor

What Is A CssColor Object?

A CssColor object represents a CSS color:

1// a summary of what's available in all CssColor objects
2type CssColor = {
3    // a name that you have assigned to your color
4    name: string;
5
6    // the original CSS used to create this color
7    //
8    // the definition field remains the same, even if you convert
9    // your color to another format
10    definition: string;
11
12    // the CSS string to define your color
13    // this will always match the current color format
14    css: string;
15
16    // your color, in #RRGGBB format
17    hex: string;
18
19    // the format that this color is in (e.g. 'rgb' or 'oklch')
20    colorModel: string;
21
22    // the color space that this color is defined within
23    colorSpace: string;
24
25    // your color, as a CSS named color
26    // will be undefined if your color doesn't match a CSS named color
27    cssName: string|undefined;
28
29    // your color, in CMYK format
30    cmyk: CssCmykColor;
31
32    // your color, in HSL format
33    hsl: CssHslColor;
34
35    // your color, in HSV format
36    hsv: CssHsvColor;
37
38    // your color, in HWB format
39    hwb: CssHwbColor;
40
41    // your color, in OKLCH format
42    oklch: CssOklchColor;
43
44    // your color, in RGB format
45    rgb: CssRgbColor;
46}

Creating A CssColor Object

To create a CSS color object, call makeCssColor():

1import { makeCssColor } from "@safelytyped/css-color";
2
3const red = makeCssColor("red");
4const black = makeCssColor("#000");
5const white = makeCssColor("#ffffff");
6const mutedGreen = makeCssColor("oklch(55% 0.15 141deg)");
7const navyBlue = makeCssColor("color(--device-cmyk 100 100 0 50)");
8const paleGreen = makeCssColor("hwb(100 76% 12%)");
9const skyBlue = makeCssColor("hsl(196, 100%, 64%)");

Assigning A Name To A CssColor Object

If you want to give the color a name and store it in the CssColor object, you can pass that into makeCssColor():

1import { makeCssColor } from "@safelytyped/css-color";
2
3const mutedGreen = makeCssColor(
4    "oklch(55% 0.15 141deg)",
5    {
6        colorName: "mutedGreen"
7    }
8);
9
10// outputs: mutedGreen
11console.log(mutedGreen.name);

Getting The Individual Color Channels

You can get the individual color channels out of your CssColor object. Just convert it to the right color model first:

1import { makeCssColor } from "@safelytyped/css-color";
2
3const mutedGreen = makeCssColor("oklch(55% 0.15 141deg)");
4
5// get the red channel
6console.log(mutedGreen.rgb.red);
7
8// get the cyan channel
9console.log(mutedGreen.cmyk.cyan);
10
11// get all the RGB channels as a plain object
12//
13// useful if you want the smallest possible object for logging,
14// storage or debugging
15console.log(mutedGreen.rgb.channelsData);
16
17// get all the RGB channels as an array
18//
19// can be useful for passing colors into other Javascript color packages :)
20console.log(mutedGreen.rgb.channelsTuple);

Converting Between Color Models and Color Spaces

Every CssColor object can be converted to a different color model / color space.

CssColor property	Converts To	Color Model / Color Space
.cmyk	CssCmykColor	cmyk/CMYK
.hsl	CssHslColor	hsl/sRGB
.hsv	CssHsvColor	hsv/sRGB
.hwb	CssHwbColor	hwb/sRGB
.oklch	CssOklchColor	oklch/OKLAB
.rgb	CssRgbColor	rgb/sRGB

This then gives you access to the individual color channels of that color model.

Getting the CSS Hex Value

You can get the CSS hex definition (#RRGGBB) for every CssColor object, even if it wasn't originally created using a CSS hex value:

1import { makeCssColor } from "@safelytyped/css-color";
2
3const mutedGreen = makeCssColor("oklch(55% 0.15 141deg)");
4
5// outputs: #368629
6console.log(mutedGreen.hex);

Getting The CSS Named Color

CSS named colors are colors that are baked into every browser. At the time of writing, all named colors are defined in the sRGB color space.

You can get the CSS name for your color from your CssColor object:

1import { makeCssColor } from "@safelytyped/css-color";
2
3const myColor = makeCssColor("#000080");
4
5// outputs: navy
6console.log(myColor.cssName);

If your color doesn't match any of the CSS named colors, you'll get an undefined value back:

1import { makeCssColor } from "@safelytyped/css-color";
2
3const myColor = makeCssColor("oklch(70% 0.187 60)");
4
5// outputs: undefined
6console.log(myColor.cssName);

Getting The CSS For Different Color Models

You can get the CSS for any color model. Just convert your CssColor object into the format you want, and then get the .css property:

1import { makeCssColor } from "@safelytyped/css-color";
2
3const myColor = makeCssColor("#000080");
4
5// outputs: hsl(240, 100%, 25%)
6console.log(myColor.hsl.css);

Color Models and Color Spaces

What Are Color Models and Color Spaces?

Every CssColor represents a color using a color model within a color space.

First off, some definitions:

• A color model is the notation that's used to define a color.
• A color space defines the range of colors that can be created.

But what does that mean?

If you've worked with CSS colors before, you're probably familiar with defining colors like this:

1.alert {
2    color: rgb(34 34 34);
3    background-color: #ff0000;
4}

There are two color models used in that CSS snippet:

• rgb(34 34 34) is the RGB color model, and
• #ff0000 is the hex color model.

In CSS, both the RGB and hex color models define colors in the same color space: the sRGB color space.

Why We Need To Keep Track Of Both

There's two reasons why CssColor objects keep track of both the color model and color space.

1. Some color models aren't unique to a single color space.
2. Converting colors between color spaces is handled differently to converting colors within the same color space.

Let's expand on that a bit.

Color Models Are Not Always Unique

Some color models are supported in more than one color space. For example, you can use the RGB color model in both the sRGB color space (which is what CSS uses) and in the lRGB color space.

However, an RGB color in the sRGB color space isn't the same color in the lRGB color space, even if it has the same values. That's because it's the color space that defines what the RGB values actually look like.

That's one reason why each CssColor object keeps track of both the color model and the color space: the color only makes sense if we know them both.

Converting Between Color Spaces Gets Funky Real Quick

It's very straight-forward to convert a color within the same color space (e.g. convert RGB to HSL in the sRGB color space). But converting between color spaces (e.g. HSL in sRGB to OKLCH in OKLAB)? That gets funky.

The problem is that there aren't established algorithms to directly convert every color model / color space pair to every other color model / color space pair. For example, there isn't an established algorithm to go directly from HSL/sRGB to OKLCH/OKLAB.

But there is an established algorithm to convert RGB/sRGB to OKLCH/OKLAB.

So, if we're converting HSL/sRGB to OKLCH/OKLAB, we have to add an intermediate step: we need to convert HSL/sRGB to RGB/sRGB first.

That's the other reason why each CssColor object keeps track of both the color model and the color space: it simplifies the code for converting between color spaces when there's no direct conversion available.

CssCmykColor

How To Create A CssCmykColor

You can convert other CssColor objects to a CssCmykColor object:

1import { makeCssColor } from "@safelytyped/css-color";
2
3const cmykColor = makeCssColor("red").cmyk;

You can call makeCssCmykColor() directly to create a CssCmykColor object.

1import { makeCssCmykColor } from "@safelytyped/css-color";
2
3// works with CMYK definitions
4const cmykColor1 = makeCssCmykColor("color(--device-cmyk 100 100 0 50)");
5
6// also works with other valid CSS color definitions!
7const cmykColor2 = makeCssCmykColor("#000080");

Color Channels

CssCmykColor has four color channels:

CssCmykColor Property	Color Channel	Valid Range
.cyan	C	0-100
.magenta	M	0-100
.yellow	Y	0-100
.key	K	0-100

Channel Data

CssCmykColor.channelsData returns the channels as a plain object:

1// smart constructor for creating CssCmykColor objects directly
2import { makeCssCmykColor } from "@safelytyped/css-color";
3
4// create a CMYK color to inspect
5const cmykColor = makeCssCmykColor("color(--device-cmyk 100 100 0 50)");
6
7// outputs:
8//
9// {
10//     colorModel: "cmyk",
11//     colorSpace: "CMYK",
12//     cyan: 100,
13//     magenta: 100,
14//     yellow: 0,
15//     key: 50,
16// }
17console.log(cmykColor.channelsData);

If you ever need to, you can create a CssCmykColor from its channel data:

1import {
2    makeCssCmykColor,
3    makeCssCmykColorFromCmykColorModel
4} from "@safelytyped/css-color";
5
6const cmykColor1 = makeCssCmykColor("color(--device-cmyk 100 100 0 50)");
7const channelData = cmykColor1.channelsData;
8
9// recreate the color at a later date
10const cmykColor2 = makeCssCmykColorFromCmykColorModel(channelData);

CssHexColor

How To Create A CssHexColor

CssHexColor is special. You cannot convert other colors to it. Mostly because there's no need to: we already add the .hex property to all CssColor objects.

You can call makeCssHexColor() directly to create a CssHexColor object.

1import { makeCssHexColor } from "@safelytyped/css-color";
2
3// works with HEX definitions
4const hexColor1 = makeCssHexColor("#000080");
5
6// also works with other valid CSS color definitions!
7const hexColor2 = makeCssHexColor("hsl(240 100% 25%)");

Color Channels

CssHexColor has no color channels of its own. Convert CssHexColor objects to other formats to access their color channels instead.

Channel Data

CssHexColor.channelsData returns the hex definition as a plain object:

1// smart constructor for creating CssHexColor objects directly
2import { makeCssHexColor } from "@safelytyped/css-color";
3
4// create a HEX color to inspect
5const hexColor1 = makeCssHexColor("#000080");
6
7// outputs:
8//
9// {
10//     colorModel: "hex",
11//     colorSpace: "sRGB",
12//     hex: "#000080",
13// }
14console.log(hexColor.channelsData);

If you ever need to, you can create a CssHexColor from its channel data:

1import {
2    makeCssHexColor,
3    makeCssHexColorFromHexColorModel
4} from "@safelytyped/css-color";
5
6const hexColor1 = makeCssHexColor("#000080");
7const channelData = hexColor1.channelsData;
8
9// recreate the color at a later date
10const hexColor2 = makeCssHexColorFromHexColorModel(channelData);

CssHslColor

How To Create A CssHslColor

You can convert other CssColor objects to a CssHslColor object:

1import { makeCssColor } from "@safelytyped/css-color";
2
3const hslColor = makeCssColor("red").hsl;

You can call makeCssHslColor() directly to create a CssHslColor object.

1import { makeCssHslColor } from "@safelytyped/css-color";
2
3// works with HSL definitions
4const hslColor1 = makeCssHslColor("hsl(196, 100%, 64%)");
5
6// also works with other valid CSS color definitions!
7const hslColor2 = makeCssHslColor("#47ceff");

Color Channels

CssHslColor has four color channels:

CssHslColor Property	Color Channel	Valid Range
.hue	H	0-360
.saturation	S	0-100
.luminosity	L	0-100
.alpha	A	0-1

Channel Data

CssHslColor.channelsData returns the channels as a plain object:

1// smart constructor for creating CssHslColor objects directly
2import { makeCssHslColor } from "@safelytyped/css-color";
3
4// create a HSL color to inspect
5const hslColor = makeCssHslColor("hsl(196, 100%, 64%)");
6
7// outputs:
8//
9// {
10//     colorModel: "hsl",
11//     colorSpace: "sRGB",
12//     hue: 196,
13//     saturation: 100,
14//     luminosity: 64,
15//     alpha:1,
16// }
17console.log(hslColor.channelsData);

If you ever need to, you can create a CssHslColor from its channel data:

1import {
2    makeCssHslColor,
3    makeCssHslColorFromHslColorModel
4} from "@safelytyped/css-color";
5
6const hslColor1 = makeCssHslColor("hsl(196, 100%, 64%)");
7const channelData = hslColor1.channelsData;
8
9// recreate the color at a later date
10const hslColor2 = makeCssHslColorFromHslColorModel(channelData);

CssHsvColor

How To Create A CssHsvColor

You can convert other CssColor objects to a CssHsvColor object:

1import { makeCssColor } from "@safelytyped/css-color";
2
3const hsvColor = makeCssColor("red").hsv;

You can call makeCssHsvColor() directly to create a CssHsvColor object.

1import { makeCssHsvColor } from "@safelytyped/css-color";
2
3// works with HSV definitions
4const hsvColor1 = makeCssHsvColor("color(--hsv 240 100% 50%)");
5
6// also works with other valid CSS color definitions!
7const hsvColor2 = makeCssHsvColor("#000080");

Color Channels

CssHsvColor has four color channels:

CssHsvColor Property	Color Channel	Valid Range
.hue	H	0-360
.saturation	S	0-100
.value	V	0-100
.alpha	A	0-1

Channel Data

CssHsvColor.channelsData returns the channels as a plain object:

1// smart constructor for creating CssHsvColor objects directly
2import { makeCssHsvColor } from "@safelytyped/css-color";
3
4// create a HSV color to inspect
5const hsvColor = makeCssHsvColor("color(--hsv 240 100% 50%)");
6
7// outputs:
8//
9// {
10//     colorModel: "hsv",
11//     colorSpace: "sRGB",
12//     hue: 240,
13//     saturation: 100,
14//     value: 50,
15//     alpha:1,
16// }
17console.log(hsvColor.channelsData);

If you ever need to, you can create a CssHsvColor from its channel data:

1import {
2    makeCssHsvColor,
3    makeCssHsvColorFromHsvColorModel
4} from "@safelytyped/css-color";
5
6const hsvColor1 = makeCssHsvColor("color(--hsv 240 100% 50%)");
7const channelData = hsvColor1.channelsData;
8
9// recreate the color at a later date
10const hsvColor2 = makeCssHsvColorFromHsvColorModel(channelData);

CssHwbColor

How To Create A CssHwbColor

You can convert other CssColor objects to a CssHwbColor object:

1import { makeCssColor } from "@safelytyped/css-color";
2
3const hwbColor = makeCssColor("red").hwb;

You can call makeCssHwbColor() directly to create a CssHwbColor object.

1import { makeCssHwbColor } from "@safelytyped/css-color";
2
3// works with HWB definitions
4const hwbColor1 = makeCssHwbColor("hwb(100 76% 12%)");
5
6// also works with other valid CSS color definitions!
7const hwbColor2 = makeCssHwbColor("#000080");

Color Channels

CssHwbColor has four color channels:

CssHwbColor Property	Color Channel	Valid Range
.hue	H	0-360
.whiteness	W	0-100
.blackness	B	0-100
.alpha	A	0-1

Channel Data

CssHwbColor.channelsData returns the channels as a plain object:

1// smart constructor for creating CssHwbColor objects directly
2import { makeCssHwbColor } from "@safelytyped/css-color";
3
4// create a HWB color to inspect
5const hwbColor = makeCssHwbColor("hwb(100 76% 12%)");
6
7// outputs:
8//
9// {
10//     colorModel: "hwb",
11//     colorSpace: "sRGB",
12//     hue: 240,
13//     whiteness: 76,
14//     blackness: 12,
15//     alpha:1,
16// }
17console.log(hwbColor.channelsData);

If you ever need to, you can create a CssHwbColor from its channel data:

1import {
2    makeCssHwbColor,
3    makeCssHwbColorFromHwbColorModel
4} from "@safelytyped/css-color";
5
6const hwbColor1 = makeCssHsvColor("hwb(100 76% 12%)");
7const channelData = hwbColor1.channelsData;
8
9// recreate the color at a later date
10const hwbColor2 = makeCssHwbColorFromHwbColorModel(channelData);

CssOklchColor

How To Create A CssOklchColor

You can convert other CssColor objects to a CssOklchColor object:

1import { makeCssColor } from "@safelytyped/css-color";
2
3const oklchColor = makeCssColor("red").oklch;

You can call makeCssOklchColor() directly to create a CssOklchColor object.

1import { makeCssOklchColor } from "@safelytyped/css-color";
2
3// works with OKLCH definitions
4const oklchColor1 = makeCssOklchColor("oklch(70% 0.187 60)");
5
6// also works with other valid CSS color definitions!
7const oklchColor2 = makeCssOklchColor("#ef7b00");

Color Channels

CssOklchColor has four color channels:

CssOklchColor Property	Color Channel	Valid Range
.lightness	L	0-1
.chroma	C	0-0.4
.hue	H	0-360
.alpha	A	0-1

Channel Data

CssOklchColor.channelsData returns the channels as a plain object:

1// smart constructor for creating CssOklchColor objects directly
2import { makeCssOklchColor } from "@safelytyped/css-color";
3
4// create a OKLCH color to inspect
5const oklchColor = makeCssOklchColor("oklch(70% 0.187 60)");
6
7// outputs:
8//
9// {
10//     colorModel: "oklch",
11//     colorSpace: "OKLAB",
12//     lightness: 0.70,
13//     chroma: 0.187,
14//     hue: 60,
15//     alpha:1,
16// }
17console.log(oklchColor.channelsData);

If you ever need to, you can create a CssOklchColor from its channel data:

1import {
2    makeCssOklchColor,
3    makeCssOklchColorFromOklchColorModel
4} from "@safelytyped/css-color";
5
6const oklchColor1 = makeCssHsvColor("oklch(70% 0.187 60)");
7const channelData = oklchColor1.channelsData;
8
9// recreate the color at a later date
10const oklchColor2 = makeCssOklchColorFromOklchColorModel(channelData);

CssRgbColor

How To Create A CssRgbColor

You can convert other CssColor objects to a CssRgbColor object:

1import { makeCssColor } from "@safelytyped/css-color";
2
3const rgbColor = makeCssColor("red").rgb;

You can call makeCssRgbColor() directly to create a CssRgbColor object.

1import { makeCssRgbColor } from "@safelytyped/css-color";
2
3// works with RGB definitions
4const rgbColor1 = makeCssRgbColor("rgb(100,100,100)");
5
6// also works with other valid CSS color definitions!
7const rgbColor2 = makeCssRgbColor("#646464");

Color Channels

CssRgbColor has four color channels:

CssRgbColor Property	Color Channel	Valid Range
.red	R	0-255
.green	G	0-255
.blue	B	0-255
.alpha	A	0-1

Channel Data

CssRgbColor.channelsData returns the channels as a plain object:

1// smart constructor for creating CssRgbColor objects directly
2import { makeCssRgbColor } from "@safelytyped/css-color";
3
4// create a RGB color to inspect
5const rgbColor = makeCssRgbColor("rgb(100,100,100)");
6
7// outputs:
8//
9// {
10//     colorModel: "rgb",
11//     colorSpace: "sRGB",
12//     red: 100,
13//     green: 100,
14//     blue: 100,
15//     alpha:1,
16// }
17console.log(rgbColor.channelsData);

If you ever need to, you can create a CssRgbColor from its channel data:

1import {
2    makeCssRgbColor,
3    makeCssRgbColorFromRgbColorModel
4} from "@safelytyped/css-color";
5
6const rgbColor1 = makeCssHsvColor("rgb(100,100,100)");
7const channelData = rgbColor1.channelsData;
8
9// recreate the color at a later date
10const rgbColor2 = makeCssRgbColorFrRgbColorModel(channelData);

Inspectors

contrastRatio()

contrastRatio() calculates the WCAG 2.2 relative contrast between two colors.

You don't need to pass in the the colors in any set order. This function will work regardless.

1import { makeCssColor, contrastRatio } from "@safelytyped/css-color";
2
3// outputs: 14.7
4console.log(
5    contrastRatio(
6        makeCssColor("#222"),
7        makeCssColor("#f6f6f6f"),
8    )
9);

darkModeContrastRatio()

darkModeContrastRatio() calculates the WCAG 2.2 relative contrast of the given input color against a black (#000) background.

1import { makeCssColor, darkModeContrastRatio } from "@safelytyped/css-color";
2
3console.log(
4    darkModeContrastRatio(
5        makeCssColor("#f6f6f6")
6    )
7);

Using a different color as your dark mode background? You can pass that color in as an optional named parameter:

1import { makeCssColor, darkModeContrastRatio } from "@safelytyped/css-color";
2
3console.log(
4    darkModeContrastRatio(
5        makeCssColor("#f6f6f6"),
6        { darkModeBg: makeCssColor("#222") }
7    )
8);

hasClearContrast()

hasClearContrast() determines whether or not two given colors are truly different from each other on a black-and-white scale.

Combine this with contrastRatio() to catch the color pairs that the WCAG 2.2 formula alone doesn't catch.

1import { makeCssColor, hasClearContrast } from "@safelytyped/css-color";
2
3// outputs: true
4console.log(
5    hasClearContrast(
6        makeCssColor("#222"),
7        makeCssColor("#f6f6f6")
8    )
9);
10
11// outputs: false
12console.log(
13    hasClearContrast(
14        makeCssColor("#222"),
15        makeCssColor("#fd7e14")
16    )
17);

isDark()

isDark() returns true if the given input color is a dark color. It uses tonality() to determine this.

1import { makeCssColor, isDark } from "@safelytyped/css-color";
2
3// outputs: true
4console.log(
5    isDark(
6        makeCssColor("#222")
7    )
8);

isLight()

isLight() returns true if the given input color is a light color. It uses tonality() to determine this.

1import { makeCssColor, isLight } from "@safelytyped/css-color";
2
3// outputs: true
4console.log(
5    isLight(
6        makeCssColor("#f6f6f6")
7    )
8);

isMidtone()

isMidtone() returns true if the given input color is not a light color, and is not a dark color either. It uses tonality() to determine this.

1import { makeCssColor, isMidtone } from "@safelytyped/css-color";
2
3// outputs: true
4console.log(
5    isMidtone(
6        makeCssColor("#fd7e14")
7    )
8);

isMonochrome()

isMonochrome() returns true if the given input color is black, white, or a pure gray color.

1import { makeCssColor, isMonochrome } from "@safelytyped/css-color";
2
3// outputs: true
4console.log(
5    isMidtone(
6        makeCssColor("#222")
7    )
8);
9
10// outputs: false
11console.log(
12    isMidtone(
13        makeCssColor("#9CA3AF")
14    )
15);

lightModeContrastRatio()

lightModeContrastRatio() calculates the WCAG 2.2 relative contrast of the given input color against a white (#fff) background.

1import { makeCssColor, lightModeContrastRatio } from "@safelytyped/css-color";
2
3console.log(
4    lightModeContrastRatio(
5        makeCssColor("#222")
6    )
7);

Using a different color as your light mode background? You can pass that color in as an optional named parameter:

1import { makeCssColor, lightModeContrastRatio } from "@safelytyped/css-color";
2
3console.log(
4    lightModeContrastRatio(
5        makeCssColor("#222"),
6        { lightModeBg: makeCssColor("#f6f6f6") }
7    )
8);

luma()

luma() calculates the given color's "Y" component from the YIQ color space.

YIQ is the old NTSC color space used on American TVs back in the day.

This is based on Brian Suda's formula.

1import { makeCssColor, luma } from "@safelytyped/css-color";
2
3// outputs: 71.772
4console.log(
5    luma(
6        makeCssColor("#234f83")
7    )
8);

relativeLuminance()

relativeLuminance() calculates the WCAG 2.2 relative luminance of the given input color.

This is an alternative to the luma() value.

This value is used in determining the WCAG contrast ratings.

1import { makeCssColor, relativeLuminance } from "@safelytyped/css-color";
2
3// outputs: 0.075
4console.log(
5    relativeLuminance(
6        makeCssColor("#234f83")
7    )
8);

tonality()

tonality() uses the given color's luma() to work out whether the color is light, dark, or midtone.

1import { makeCssColor, tonality } from "@safelytyped/css-color";
2
3// outputs: light
4console.log(
5    tonality(
6        makeCssColor("#f6f6f6")
7    )
8);
9
10// outputs: dark
11console.log(
12    tonality(
13        makeCssColor("#222")
14    )
15);
16
17// outputs: midtone
18console.log(
19    tonality(
20        makeCssColor("#fd7e14")
21    )
22);

wcagContrast()

wcagContrast() works out whether the given contrast ratio meets the WCAG 2.2 success criteria for accessibility.

Here's the structure of the object returned by wcagContrast():

1/**
2 * WcagContrastRatings is a map of known WCAG contrast criteria in their
3 * context:
4 *
5 * - A_normal - is this good enough for people with healthy vision? (based on ISO-9241)
6 * - AA_normal - is this good enough for AA rating for body text?
7 * - AA_large - is this good enough for AA rating for headlines?
8 * - AA_ui - is this good enough for AA rating for UI controls?
9 * - AAA_normal - is this good enough for AAA rating for body text?
10 * - AAA_large - is this good enough for AAA rating for headlines?
11 *
12 * NOTE that there is no AAA rating for UI controls at this time.
13 *
14 * See:
15 *
16 * - https://developer.mozilla.org/en-US/docs/Web/Accessibility/Understanding_WCAG/Perceivable/Color_contrast
17 * - https://www.w3.org/TR/WCAG21/#contrast-minimum
18 * - https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html
19 */
20export type WcagContrastRatings = {
21    /**
22     * is this good enough for people with healthy vision? (based on ISO-9241)
23     */
24    "A_normal": boolean,
25
26    /**
27     * is this good enough for the WCAG AA rating for body text?
28     */
29    "AA_normal": boolean,
30
31    /**
32     * is this good enough for the WCAG AA rating for headlines?
33     */
34    "AA_large": boolean,
35
36    /**
37     * is this good enough for the WCAG AA rating for UI controls?
38     */
39    "AA_ui": boolean,
40
41    /**
42     * is this good enough for the WCAG AAA rating for body text?
43     */
44    "AAA_normal": boolean,
45
46    /**
47     * is this good enough for the WCAG AAA rating for headlines?
48     */
49    "AAA_large": boolean,
50
51    /**
52     * what is the WCAG rating for headlines?
53     */
54    large: "AAA" | "AA" | "not accessible",
55
56    /**
57     * what is the WCAG rating for body text?
58     */
59    normal: "AAA" | "AA" | "A" | "not accessible",
60
61    /**
62     * what is the WCAG rating for UI controls?
63     */
64    ui: "AA" | "A" | "not accessible",
65};

Here's an example of how to use wcagContrast():

1import {
2    makeCssColor,
3    contrastRatio,
4    wcagContrast
5} from "@safelytyped/css-color";
6
7// calculate the contrast ratio between our two colors
8const contrast = contrastRatio(
9    makeCssColor("#222"),
10    makeCssColor("#f6f6f6")
11);
12
13// outputs: {
14//     "A_normal": true,
15//     "AA_normal": true,
16//     "AA_large": true,
17//     "AA_ui": true,
18//     "AAA_normal": true,
19//     "AAA_large": true,
20//     "large": "AAA",
21//     "normal": "AAA",
22//     "ui": "AA"
23// },
24console.log(
25    wcagContrast(contrast)
26);

CSS Named Colors

What Are CSS Named Colors?

CSS named colors are the color names supported by all browsers.

For example: "black", "white", "rebeccapurple" are all CSS named colors.

(You may have seen these referred to as "CSS extended colors" in the past. This term has been dropped in the latest CSS Color Module Level 4 draft spec).

CssNamedColor

CssNamedColor is a string literal type. It contains all the known CSS color names.

Use it whenever you want to force someone to pass a CSS named color as a parameter into a function.

CSS_NAMED_COLOR_TO_HEX

CSS_NAMED_COLOR_TO_HEX is a map. Use it to find the CSS hex value of any given CSS named color.

1import {
2    type CssNamedColor,
3    CSS_NAMED_COLOR_TO_HEX
4} from "@safelytyped/css-color";
5
6// outputs: #ff0000
7console.log(
8    CSS_NAMED_COLOR_TO_HEX(mustBeCssNamedColor("red"))
9);

CSS_HEX_TO_NAMED_COLOR

CSS_HEX_TO_NAMED_COLOR is a map. Use it to find the named CSS color that matches the given CSS hex definition.

1import {
2    mustBeCssHexDefinition,
3    CSS_HEX_TO_NAMED_COLOR
4} from "@safelytyped/css-color";
5
6// outputs: white
7console.log(
8    CSS_HEX_TO_NAMED_COLOR(
9        mustBeCssHexDefinition("#ffffff")
10    )
11);

If two or more CSS named colors have the same hex definition, we don't guarantee which named color we'll return.

isCssNamedColor()

isCssNamedColor() is a data guard. Use it to prove to the Typescript compiler that the given input is a CSS named color.

1import { isCssNamedColor } from "@safelytyped/css-color";
2
3const myColor = "red";
4if (isCssNamedColor(myColor)) {
5    // tsc now treats `myColor` as a `CssNamedColor`
6}

mustBeCssNamedColor()

mustBeCssNamedColor() is a data guarantee. Use it to ensure that the given input is a CSS named color.

Throws an error if the given input is not a valid CSS named color.

1import { mustBeCssNamedColor } from "@safelytyped/css-color";
2
3// myColor has the type: CssNamedColor
4const myColor = mustBeCssNamedColor("red");
5
6// throws an error
7const badColor = mustBeCssNamedColor("amaranth");

validateCssNamedColor()

validateCssNamedColor() is a data validator. It's used by both isCssNamedColor() and mustBeCssNamedColor() to determine if the given input is a CSS named color or not.

Only call this directly from other validators.