tokens/chart.mjs

Functions

Imports

It imports tokens/palette.mjs. Imported by tokens/palette.mjs.

Source

1// The chart pieces of the palette (0.3): eight series colours and a five-step sequential
2// ramp, for Enarratio's charts and anything else that draws categories or quantities.
3// Imported by tokens/palette.mjs, which writes them into the colour files and the Enarratio
4// theme, and which checks them with the rest of the palette.
5//
6// The series: purple, fox and teal first (step 9 of each family, exactly as shipped: #8c5fd2,
7// #cc4f0c, #008489), then five companions of the same weight, found by a search over hue,
8// chroma and lightness (once, offline; the result is the parameters below, so the hexes are
9// computed here, never typed). What the search held fixed:
10//   - each colour is at least 3:1 against the surface, the ground and the raised surface, in
11//     both themes (WCAG 2.2 non-text contrast), at about the lightness of the three seeds;
12//   - every pair differs by at least SERIES_MIN_DE (CIEDE2000) with typical vision and under
13//     simulated protanopia, deuteranopia and tritanopia (Machado et al. 2009, the model
14//     Enarratio's own checkTheme uses);
15//   - no companion sits within STATUS_MIN_DE of ok, warning, critical or info, so a series is
16//     never read as a status;
17//   - each slot keeps its hue from light to dark, with lightness set per theme.
18// Order, so a chart with few series uses the most distinct ones first: purple, fox, teal,
19// then sage, indigo, pine, orchid, rose.
20import { contrast, oklch } from "./palette.mjs";
21
22export const SERIES_SEEDS = ["purple", "fox", "teal"];
23export const SERIES_MIN_DE = 8;
24export const STATUS_MIN_DE = 6;
25export const RAMP_STEP_MIN_DE = 6;
26
27// [hue, chroma, light-theme lightness, dark-theme lightness]; chroma is pulled in to fit sRGB.
28export const COMPANIONS = [
29  { name: "sage", h: 130.6, c: 0.096, light: 0.628, dark: 0.783 },
30  { name: "indigo", h: 273.9, c: 0.11, light: 0.498, dark: 0.787 },
31  { name: "pine", h: 178.3, c: 0.101, light: 0.48, dark: 0.775 },
32  { name: "orchid", h: 343.4, c: 0.143, light: 0.636, dark: 0.63 },
33  { name: "rose", h: 5.1, c: 0.114, light: 0.502, dark: 0.73 },
34];
35
36// The sequential ramp: one hue (the family's), five steps from least to most. In light the
37// most is the darkest; in dark the most is the lightest, so each step stands further from
38// the surface than the one before (Enarratio's check). [lightness, share of the seed chroma].
39const RAMP = {
40  light: [[0.91, 0.22], [0.81, 0.45], [0.7, 0.7], [0.57, 0.95], [0.43, 0.9]],
41  dark: [[0.3, 0.4], [0.42, 0.6], [0.54, 0.8], [0.68, 0.85], [0.82, 0.7]],
42};
43
44export function rampColours(seedHue, seedChroma, scheme) {
45  return RAMP[scheme].map(([l, share]) => oklch(l, seedChroma * share, seedHue));
46}
47
48export function companionColours(scheme) {
49  return COMPANIONS.map((c) => oklch(c[scheme], c.c, c.h));
50}
51
52// The label colour that reads best on a mark (Enarratio's labelColor): the theme's text or
53// surface colour when either reaches 4.5:1 on the fill, else black or white.
54export function labelOn(fill, text, surface) {
55  const best = (a, b) => (contrast(fill, a) >= contrast(fill, b) ? a : b);
56  const themed = best(text, surface);
57  return contrast(fill, themed) >= 4.5 ? themed : best("#000000", "#ffffff");
58}
59
60// ---- colour-vision simulation and CIEDE2000 (the same model as Enarratio's checkTheme) -----
61
62const MATRICES = {
63  protanopia: [[0.152286, 1.052583, -0.204868], [0.114503, 0.786281, 0.099216], [-0.003882, -0.048116, 1.051998]],
64  deuteranopia: [[0.367322, 0.860646, -0.227968], [0.280085, 0.672501, 0.047413], [-0.01182, 0.04294, 0.968881]],
65  tritanopia: [[1.255528, -0.076749, -0.178779], [-0.078411, 0.930809, 0.147602], [0.004733, 0.691367, 0.3039]],
66};
67export const VISIONS = [undefined, "protanopia", "deuteranopia", "tritanopia"];
68const rgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16) / 255);
69const lin = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
70const gam = (c) => {
71  const v = Math.min(1, Math.max(0, c));
72  return v <= 0.0031308 ? v * 12.92 : 1.055 * v ** (1 / 2.4) - 0.055;
73};
74function seen(hex, vision) {
75  const c = rgb(hex);
76  if (!vision) return c;
77  const l = c.map(lin);
78  return MATRICES[vision].map((r) => gam(r[0] * l[0] + r[1] * l[1] + r[2] * l[2]));
79}
80function lab(c) {
81  const [r, g, b] = c.map(lin);
82  const x = (0.4124564 * r + 0.3575761 * g + 0.1804375 * b) / 0.95047;
83  const y = 0.2126729 * r + 0.7151522 * g + 0.072175 * b;
84  const z = (0.0193339 * r + 0.119192 * g + 0.9503041 * b) / 1.08883;
85  const f = (t) => (t > 216 / 24389 ? Math.cbrt(t) : (24389 / 27 / 116) * t + 16 / 116);
86  return [116 * f(y) - 16, 500 * (f(x) - f(y)), 200 * (f(y) - f(z))];
87}
88const rad = (d) => (d * Math.PI) / 180;
89const deg = (r) => (r * 180) / Math.PI;
90function deltaE2000([L1, a1, b1], [L2, a2, b2]) {
91  const c1 = Math.hypot(a1, b1);
92  const c2 = Math.hypot(a2, b2);
93  const cb7 = ((c1 + c2) / 2) ** 7;
94  const g = 0.5 * (1 - Math.sqrt(cb7 / (cb7 + 25 ** 7)));
95  const a1p = (1 + g) * a1;
96  const a2p = (1 + g) * a2;
97  const c1p = Math.hypot(a1p, b1);
98  const c2p = Math.hypot(a2p, b2);
99  const hue = (b, a) => (a === 0 && b === 0 ? 0 : (deg(Math.atan2(b, a)) + 360) % 360);
100  const h1 = hue(b1, a1p);
101  const h2 = hue(b2, a2p);
102  let dh = 0;
103  if (c1p * c2p !== 0) {
104    dh = h2 - h1;
105    if (dh > 180) dh -= 360;
106    else if (dh < -180) dh += 360;
107  }
108  const dH = 2 * Math.sqrt(c1p * c2p) * Math.sin(rad(dh / 2));
109  const lb = (L1 + L2) / 2;
110  const cb = (c1p + c2p) / 2;
111  let hb = h1 + h2;
112  if (c1p * c2p !== 0) hb = Math.abs(h1 - h2) <= 180 ? (h1 + h2) / 2 : h1 + h2 < 360 ? (h1 + h2 + 360) / 2 : (h1 + h2 - 360) / 2;
113  const t = 1 - 0.17 * Math.cos(rad(hb - 30)) + 0.24 * Math.cos(rad(2 * hb)) + 0.32 * Math.cos(rad(3 * hb + 6)) - 0.2 * Math.cos(rad(4 * hb - 63));
114  const dTheta = 30 * Math.exp(-(((hb - 275) / 25) ** 2));
115  const cb7b = cb ** 7;
116  const rC = 2 * Math.sqrt(cb7b / (cb7b + 25 ** 7));
117  const sL = 1 + (0.015 * (lb - 50) ** 2) / Math.sqrt(20 + (lb - 50) ** 2);
118  const sC = 1 + 0.045 * cb;
119  const sH = 1 + 0.015 * cb * t;
120  const rT = -Math.sin(rad(2 * dTheta)) * rC;
121  const lt = (L2 - L1) / sL;
122  const ct = (c2p - c1p) / sC;
123  const ht = dH / sH;
124  return Math.sqrt(lt * lt + ct * ct + ht * ht + rT * ct * ht);
125}
126// CIEDE2000 between two hex colours, with typical vision or a simulated deficiency.
127export const colourDifference = (a, b, vision) => deltaE2000(lab(seen(a, vision)), lab(seen(b, vision)));
128// The smallest difference over typical vision and the three deficiencies, and where it was.
129export function worstDifference(a, b) {
130  let worst = { de: Infinity, vision: undefined };
131  for (const vision of VISIONS) {
132    const de = colourDifference(a, b, vision);
133    if (de < worst.de) worst = { de, vision };
134  }
135  return worst;
136}
137
138// Everything the chart palette must satisfy for one family's theme `t` (the token map for
139// one scheme). Returns { what, value, min, pass, detail } rows, like pairs() in palette.mjs.
140export function chartChecks(t) {
141  const out = [];
142  const add = (what, value, min, detail) => out.push({ what, value, min, pass: value >= min, detail });
143  const series = Array.from({ length: 8 }, (_, i) => t[`series-${i + 1}`]);
144  for (let i = 0; i < 8; i++) {
145    for (const bg of ["surface", "ground", "raised"]) add(`series ${i + 1} against --${bg}`, contrast(series[i], t[bg]), 3, `${series[i]} on ${t[bg]}`);
146  }
147  for (let i = 0; i < 8; i++) {
148    for (let j = i + 1; j < 8; j++) {
149      const w = worstDifference(series[i], series[j]);
150      add(`series ${i + 1} and ${j + 1} differ (${w.vision ?? "typical vision"})`, w.de, SERIES_MIN_DE, `${series[i]} and ${series[j]}`);
151    }
152  }
153  for (let i = 3; i < 8; i++) {
154    for (const s of ["ok", "warn", "crit", "info"]) add(`series ${i + 1} is clear of --${s}`, colourDifference(series[i], t[s]), STATUS_MIN_DE, `${series[i]} and ${t[s]}`);
155  }
156  const ramp = Array.from({ length: 5 }, (_, i) => t[`ramp-${i + 1}`]);
157  add("ramp step 5 against --surface", contrast(ramp[4], t.surface), 3, `${ramp[4]} on ${t.surface}`);
158  for (let i = 1; i < 5; i++) {
159    // Each step must stand further from the surface than the one before: "more" never reads as less.
160    add(`ramp step ${i + 1} stands out more than step ${i}`, contrast(ramp[i], t.surface) - contrast(ramp[i - 1], t.surface), 0.01, `${ramp[i - 1]} then ${ramp[i]}`);
161    add(`ramp steps ${i} and ${i + 1} differ`, colourDifference(ramp[i - 1], ramp[i]), RAMP_STEP_MIN_DE, `${ramp[i - 1]} and ${ramp[i]}`);
162  }
163  for (let i = 0; i < 8; i++) add(`label on series ${i + 1}`, contrast(t[`series-text-${i + 1}`], series[i]), 4.5, `${t[`series-text-${i + 1}`]} on ${series[i]}`);
164  for (let i = 0; i < 5; i++) add(`label on ramp step ${i + 1}`, contrast(t[`ramp-text-${i + 1}`], ramp[i]), 4.5, `${t[`ramp-text-${i + 1}`]} on ${ramp[i]}`);
165  return out;
166}