src/theme/color.ts

Functions

Imports

It imports src/theme/types.ts. Imported by src/index.ts, src/theme/check.ts, src/theme/define.ts, src/theme/stylesheet.ts.

Source

1/**
2 * Color measurement: WCAG 2 contrast, color-vision-deficiency simulation and CIEDE2000 color
3 * difference. Pure functions over hex strings, so they run the same on a server, in CI and in a
4 * browser.
5 */
6
7import type { HexColor } from "./types.js";
8
9/** Red, green and blue in the range 0 to 1, gamma-encoded (sRGB) unless a name says linear. */
10export type Rgb = readonly [number, number, number];
11
12const HEX = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
13
14/** Whether a string is a hex color Enarratio can measure. */
15export function isHexColor(value: string): value is HexColor {
16  return HEX.test(value);
17}
18
19/** Parses `#rgb` or `#rrggbb` into sRGB channels from 0 to 1. Throws on anything else. */
20function parseHex(color: string): Rgb {
21  if (!isHexColor(color)) {
22    throw new Error(`"${color}" is not a hex color (#rgb or #rrggbb)`);
23  }
24  const digits =
25    color.length === 4
26      ? color
27          .slice(1)
28          .split("")
29          .map((d) => d + d)
30          .join("")
31      : color.slice(1);
32  const channel = (i: number): number => Number.parseInt(digits.slice(i, i + 2), 16) / 255;
33  return [channel(0), channel(2), channel(4)];
34}
35
36function toLinear(c: number): number {
37  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
38}
39
40function linearize(rgb: Rgb): Rgb {
41  return [toLinear(rgb[0]), toLinear(rgb[1]), toLinear(rgb[2])];
42}
43
44function fromLinear(c: number): number {
45  const clamped = Math.min(1, Math.max(0, c));
46  return clamped <= 0.0031308 ? clamped * 12.92 : 1.055 * clamped ** (1 / 2.4) - 0.055;
47}
48
49/** WCAG 2 relative luminance, from 0 (black) to 1 (white). */
50function relativeLuminance(color: string): number {
51  const [r, g, b] = linearize(parseHex(color));
52  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
53}
54
55/** WCAG 2 contrast ratio between two colors, from 1 to 21. Order does not matter. */
56export function contrastRatio(a: string, b: string): number {
57  const la = relativeLuminance(a);
58  const lb = relativeLuminance(b);
59  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
60}
61
62/** The kinds of color vision deficiency Enarratio simulates, each at full severity. */
63export type ColorVision = "protanopia" | "deuteranopia" | "tritanopia";
64
65type Matrix = readonly [Rgb, Rgb, Rgb];
66
67/**
68 * Machado, Oliveira and Fernandes (2009), "A physiologically-based model for simulation of color
69 * vision deficiency", IEEE TVCG 15(6), severity 1.0. Applied to linear RGB.
70 */
71const CVD_MATRICES: Readonly<Record<ColorVision, Matrix>> = {
72  protanopia: [
73    [0.152286, 1.052583, -0.204868],
74    [0.114503, 0.786281, 0.099216],
75    [-0.003882, -0.048116, 1.051998],
76  ],
77  deuteranopia: [
78    [0.367322, 0.860646, -0.227968],
79    [0.280085, 0.672501, 0.047413],
80    [-0.01182, 0.04294, 0.968881],
81  ],
82  tritanopia: [
83    [1.255528, -0.076749, -0.178779],
84    [-0.078411, 0.930809, 0.147602],
85    [0.004733, 0.691367, 0.3039],
86  ],
87};
88
89/** How a color appears under a color vision deficiency, as sRGB channels from 0 to 1. */
90export function simulateColorVision(color: string, vision: ColorVision): Rgb {
91  const [r, g, b] = linearize(parseHex(color));
92  const m = CVD_MATRICES[vision];
93  const row = (i: 0 | 1 | 2): number => {
94    const [mr, mg, mb] = m[i];
95    return fromLinear(mr * r + mg * g + mb * b);
96  };
97  return [row(0), row(1), row(2)];
98}
99
100/** CIE L*a*b* under the D65 white point. */
101export type Lab = readonly [number, number, number];
102
103/** Converts sRGB channels (0 to 1) to CIE L*a*b*. */
104function rgbToLab(rgb: Rgb): Lab {
105  const [r, g, b] = linearize(rgb);
106  const x = (0.4124564 * r + 0.3575761 * g + 0.1804375 * b) / 0.95047;
107  const y = 0.2126729 * r + 0.7151522 * g + 0.072175 * b;
108  const z = (0.0193339 * r + 0.119192 * g + 0.9503041 * b) / 1.08883;
109  const f = (t: number): number =>
110    t > 216 / 24389 ? Math.cbrt(t) : (24389 / 27 / 116) * t + 16 / 116;
111  const fx = f(x);
112  const fy = f(y);
113  const fz = f(z);
114  return [116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)];
115}
116
117const degrees = (radians: number): number => (radians * 180) / Math.PI;
118const radians = (deg: number): number => (deg * Math.PI) / 180;
119
120/**
121 * CIEDE2000 color difference (Sharma, Wu and Dalal 2005). About 1 is a just-noticeable
122 * difference; categorical palettes want well over 10 between any two colors.
123 */
124export function deltaE2000(lab1: Lab, lab2: Lab): number {
125  const [l1, a1, b1] = lab1;
126  const [l2, a2, b2] = lab2;
127  const c1 = Math.hypot(a1, b1);
128  const c2 = Math.hypot(a2, b2);
129  const cBar7 = ((c1 + c2) / 2) ** 7;
130  const g = 0.5 * (1 - Math.sqrt(cBar7 / (cBar7 + 25 ** 7)));
131  const a1p = (1 + g) * a1;
132  const a2p = (1 + g) * a2;
133  const c1p = Math.hypot(a1p, b1);
134  const c2p = Math.hypot(a2p, b2);
135  const hue = (b: number, a: number): number => {
136    if (a === 0 && b === 0) return 0;
137    const h = degrees(Math.atan2(b, a));
138    return h >= 0 ? h : h + 360;
139  };
140  const h1p = hue(b1, a1p);
141  const h2p = hue(b2, a2p);
142
143  const dLp = l2 - l1;
144  const dCp = c2p - c1p;
145  let dhp = 0;
146  if (c1p * c2p !== 0) {
147    dhp = h2p - h1p;
148    if (dhp > 180) dhp -= 360;
149    else if (dhp < -180) dhp += 360;
150  }
151  const dHp = 2 * Math.sqrt(c1p * c2p) * Math.sin(radians(dhp / 2));
152
153  const lBarP = (l1 + l2) / 2;
154  const cBarP = (c1p + c2p) / 2;
155  let hBarP = h1p + h2p;
156  if (c1p * c2p !== 0) {
157    if (Math.abs(h1p - h2p) <= 180) hBarP = (h1p + h2p) / 2;
158    else if (h1p + h2p < 360) hBarP = (h1p + h2p + 360) / 2;
159    else hBarP = (h1p + h2p - 360) / 2;
160  }
161  const t =
162    1 -
163    0.17 * Math.cos(radians(hBarP - 30)) +
164    0.24 * Math.cos(radians(2 * hBarP)) +
165    0.32 * Math.cos(radians(3 * hBarP + 6)) -
166    0.2 * Math.cos(radians(4 * hBarP - 63));
167  const dTheta = 30 * Math.exp(-(((hBarP - 275) / 25) ** 2));
168  const cBarP7 = cBarP ** 7;
169  const rC = 2 * Math.sqrt(cBarP7 / (cBarP7 + 25 ** 7));
170  const sL = 1 + (0.015 * (lBarP - 50) ** 2) / Math.sqrt(20 + (lBarP - 50) ** 2);
171  const sC = 1 + 0.045 * cBarP;
172  const sH = 1 + 0.015 * cBarP * t;
173  const rT = -Math.sin(radians(2 * dTheta)) * rC;
174  const lTerm = dLp / sL;
175  const cTerm = dCp / sC;
176  const hTerm = dHp / sH;
177  return Math.sqrt(lTerm ** 2 + cTerm ** 2 + hTerm ** 2 + rT * cTerm * hTerm);
178}
179
180/**
181 * The perceived difference between two colors as seen with typical vision or a simulated color
182 * vision deficiency, in CIEDE2000 units.
183 */
184export function colorDifference(a: string, b: string, vision?: ColorVision): number {
185  const see = (c: string): Rgb => (vision ? simulateColorVision(c, vision) : parseHex(c));
186  return deltaE2000(rgbToLab(see(a)), rgbToLab(see(b)));
187}
188
189/**
190 * The color for text printed on a mark: the scheme's text or background color when either reaches
191 * 4.5:1 on the mark (the better of the two), otherwise black or white, one of which always does
192 * (F8).
193 */
194export function labelColor(fill: string, text: HexColor, background: HexColor): HexColor {
195  const best = (a: HexColor, b: HexColor): HexColor =>
196    contrastRatio(fill, a) >= contrastRatio(fill, b) ? a : b;
197  const themed = best(text, background);
198  return contrastRatio(fill, themed) >= 4.5 ? themed : best("#000000", "#ffffff");
199}