src/theme/check.ts

Functions

Imports

It imports src/theme/color.ts, src/theme/types.ts. Imported by src/index.ts.

Source

1import { type ColorVision, colorDifference, contrastRatio, labelColor } from "./color.js";
2import type { ColorScheme, HexColor, Theme } from "./types.js";
3
4/** Thresholds {@link checkTheme} measures against. Every field has a documented default. */
5export interface CheckThresholds {
6  /** Minimum contrast for text on the background. Default 4.5, WCAG 2.2 success criterion 1.4.3. */
7  readonly text: number;
8  /**
9   * Minimum contrast for marks (series, status, focus ring, the darkest sequential step) on the
10   * background. Default 3, WCAG 2.2 success criterion 1.4.11.
11   */
12  readonly graphics: number;
13  /**
14   * Minimum CIEDE2000 difference between any two series colors, with typical vision and under
15   * each simulated color vision deficiency. Default 10: about ten just-noticeable differences,
16   * enough to tell two small marks apart at a glance.
17   */
18  readonly seriesDifference: number;
19}
20
21/** The thresholds used when none are given. */
22export const DEFAULT_THRESHOLDS: CheckThresholds = {
23  text: 4.5,
24  graphics: 3,
25  seriesDifference: 10,
26};
27
28/**
29 * One finding. `error` means the theme fails an accessibility minimum; `warning` means two colors
30 * may be confused by some readers, so charts using both should label series directly.
31 */
32export interface CheckIssue {
33  readonly severity: "error" | "warning";
34  readonly scheme: "light" | "dark";
35  readonly check:
36    | "text-contrast"
37    | "graphics-contrast"
38    | "label-contrast"
39    | "series-difference"
40    | "sequential-order";
41  readonly message: string;
42  readonly colors: readonly HexColor[];
43  /** The measured value: a contrast ratio or a CIEDE2000 difference. */
44  readonly measured: number;
45}
46
47/** The result of {@link checkTheme}. `ok` is true when there are no errors; warnings may remain. */
48export interface CheckReport {
49  readonly theme: string;
50  readonly ok: boolean;
51  readonly issues: readonly CheckIssue[];
52}
53
54const VISIONS: readonly (ColorVision | undefined)[] = [
55  undefined,
56  "protanopia",
57  "deuteranopia",
58  "tritanopia",
59];
60
61const round = (n: number): number => Math.round(n * 100) / 100;
62
63function checkScheme(
64  which: "light" | "dark",
65  scheme: ColorScheme,
66  t: CheckThresholds,
67): CheckIssue[] {
68  const issues: CheckIssue[] = [];
69  const bg = scheme.background;
70
71  const contrast = (
72    name: string,
73    color: HexColor,
74    minimum: number,
75    check: "text-contrast" | "graphics-contrast",
76  ): void => {
77    const ratio = contrastRatio(color, bg);
78    if (ratio < minimum) {
79      issues.push({
80        severity: "error",
81        scheme: which,
82        check,
83        message: `${which} ${name} ${color} has contrast ${round(ratio)}:1 on ${bg}; needs ${minimum}:1`,
84        colors: [color, bg],
85        measured: round(ratio),
86      });
87    }
88  };
89
90  contrast("text", scheme.text, t.text, "text-contrast");
91  contrast("mutedText", scheme.mutedText, t.text, "text-contrast");
92  contrast("focus", scheme.focus, t.graphics, "graphics-contrast");
93  scheme.series.forEach((c, i) => {
94    contrast(`series ${i + 1}`, c, t.graphics, "graphics-contrast");
95  });
96  contrast("status.good", scheme.status.good, t.graphics, "graphics-contrast");
97  contrast("status.warning", scheme.status.warning, t.graphics, "graphics-contrast");
98  contrast("status.bad", scheme.status.bad, t.graphics, "graphics-contrast");
99  contrast("sequential step 5", scheme.sequential[4], t.graphics, "graphics-contrast");
100
101  // Text printed on marks (heatmap values, genome feature names, bar labels) takes the color
102  // labelColor picks for each fill; it must reach body-text contrast there (F8).
103  const fills: [string, HexColor][] = [
104    ...scheme.series.map((c, i): [string, HexColor] => [`series ${i + 1}`, c]),
105    ...scheme.sequential.map((c, i): [string, HexColor] => [`sequential step ${i + 1}`, c]),
106  ];
107  for (const [name, fill] of fills) {
108    const label = labelColor(fill, scheme.text, scheme.background);
109    const ratio = contrastRatio(label, fill);
110    if (ratio < t.text) {
111      issues.push({
112        severity: "error",
113        scheme: which,
114        check: "label-contrast",
115        message: `${which} labels on ${name} ${fill} (${label}) have contrast ${round(ratio)}:1; needs ${t.text}:1`,
116        colors: [label, fill],
117        measured: round(ratio),
118      });
119    }
120  }
121
122  // Each step must stand further from the background than the one before, or "more" reads as less.
123  for (let i = 1; i < scheme.sequential.length; i += 1) {
124    const previous = scheme.sequential[i - 1] as HexColor;
125    const current = scheme.sequential[i] as HexColor;
126    if (contrastRatio(current, bg) <= contrastRatio(previous, bg)) {
127      issues.push({
128        severity: "error",
129        scheme: which,
130        check: "sequential-order",
131        message: `${which} sequential step ${i + 1} ${current} does not contrast more with the background than step ${i} ${previous}`,
132        colors: [previous, current],
133        measured: round(contrastRatio(current, bg)),
134      });
135    }
136  }
137
138  for (let i = 0; i < scheme.series.length; i += 1) {
139    for (let j = i + 1; j < scheme.series.length; j += 1) {
140      const a = scheme.series[i] as HexColor;
141      const b = scheme.series[j] as HexColor;
142      // One finding per pair, at the vision under which the two are hardest to tell apart.
143      let worst = {
144        difference: Number.POSITIVE_INFINITY,
145        vision: undefined as ColorVision | undefined,
146      };
147      for (const vision of VISIONS) {
148        const difference = colorDifference(a, b, vision);
149        if (difference < worst.difference) worst = { difference, vision };
150      }
151      if (worst.difference < t.seriesDifference) {
152        issues.push({
153          severity: "warning",
154          scheme: which,
155          check: "series-difference",
156          message: `${which} series ${i + 1} ${a} and ${j + 1} ${b} differ by ${round(worst.difference)} (CIEDE2000) with ${worst.vision ?? "typical vision"}; needs ${t.seriesDifference}`,
157          colors: [a, b],
158          measured: round(worst.difference),
159        });
160      }
161    }
162  }
163  return issues;
164}
165
166/**
167 * Measures a theme against accessibility minimums, in light and dark: text and mark contrast on
168 * the background, the order of the sequential ramp, and whether any two series colors could be
169 * confused with typical vision or with protanopia, deuteranopia or tritanopia (simulated after
170 * Machado et al. 2009, compared with CIEDE2000).
171 *
172 * It reports rather than throws, so a site can decide which findings block its build.
173 */
174export function checkTheme(theme: Theme, thresholds: Partial<CheckThresholds> = {}): CheckReport {
175  const t: CheckThresholds = { ...DEFAULT_THRESHOLDS, ...thresholds };
176  const issues = [...checkScheme("light", theme.light, t), ...checkScheme("dark", theme.dark, t)];
177  return { theme: theme.name, ok: issues.every((i) => i.severity !== "error"), issues };
178}