charts.contrast

export function contrastRatio(foreground: string, background: string): number

import { contrastRatio } from "#fune/charts.contrast@^1";

import { parseHex } from "./charts_color_parse_hex.ts";
import { srgbToLinear } from "./charts_color_srgb_to_linear.ts";
import { roundFloat } from "./math_round_float.ts";  ← from math.round-float ^1.0.0 · built alongside by fune

/** WCAG 2.x relative luminance: linear-light R, G, B weighted 0.2126, 0.7152, 0.0722. */
export function relativeLuminance(hex: string): number {
  const c = parseHex(hex);
  return 0.2126 * srgbToLinear(c.r) + 0.7152 * srgbToLinear(c.g) + 0.0722 * srgbToLinear(c.b);
}

/** (lighter + 0.05) / (darker + 0.05), unrounded, for readableTextColor to compare. */
export function luminanceContrast(a: string, b: string): number {
  const la = relativeLuminance(a);
  const lb = relativeLuminance(b);
  return la > lb ? (la + 0.05) / (lb + 0.05) : (lb + 0.05) / (la + 0.05);
}

/**
 * The WCAG 2.x contrast ratio, from 1 (identical) to 21 (black on white).
 * Luminance comes from linear light, not the stored channel numbers: pure red
 * on white is 4.0:1 and mid grey #808080 is 5.3:1 against black but only
 * 3.9:1 against white.
 */
export function contrastRatio(foreground: string, background: string): number {
  return roundFloat(luminanceContrast(foreground, background), 6);
}

export function readableTextColor(background: string, candidates: readonly string[]): string

import { readableTextColor } from "#fune/charts.contrast@^1";

import { luminanceContrast } from "./charts_contrast_contrast_ratio.ts";  ← contrastRatio, another function of this group · built into the same file, even by a slim install

/**
 * The candidate that contrasts most with the background: the label colour for
 * a bar or a heatmap cell. Ties go to the earlier candidate, so the caller's
 * order is the preference.
 */
export function readableTextColor(background: string, candidates: readonly string[]): string {
  if (candidates.length === 0) throw new RangeError("candidates must not be empty");
  let best = candidates[0];
  let bestRatio = luminanceContrast(best, background);
  for (let i = 1; i < candidates.length; i++) {
    const ratio = luminanceContrast(candidates[i], background);
    if (ratio > bestRatio) {
      best = candidates[i];
      bestRatio = ratio;
    }
  }
  return best;
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and its 2 dependencies, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add charts.contrast

That builds the whole group. To build only what you call, and whatever it uses inside the group:

fune add charts.contrast --only contrastRatio

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./charts.contrast-1.0.0-typescript.fune, or fetch it from a terminal with fune pull charts.contrast@1.0.0:typescript.

The whole function, every language, is one file too: charts.contrast-1.0.0.fune, 13,998 bytes, sha256 8df0a1cc226f71b52191a6179462ce49d8e1b679809122fe20ee84efe740755b. It installs into a project of any language.

// fune: before charts.contrast.contrastRatio
// fune: before charts.contrast.readableTextColor

// fune: after charts.contrast.contrastRatio
// fune: after charts.contrast.readableTextColor

// fune: replace charts.color in charts.contrast
// fune: replace math.round-float in charts.contrast

// fune: step charts.contrast.<fn> after <n|label>

More from the author

Relative luminance L = 0.2126 R + 0.7152 G + 0.0722 B, where R, G and B are the channels converted to linear light by the sRGB transfer function (`charts.color`'s `srgbToLinear`). The ratio is (L1 + 0.05) / (L2 + 0.05) with L1 the lighter of the two, so the order of the arguments does not matter.

WCAG 2.0's text gives the linearisation threshold as 0.03928; the sRGB standard, and WCAG 2.2's note, say 0.04045. No 8-bit channel lies between them (10/255 = 0.0392 and 11/255 = 0.0431), so for hex colours the two agree exactly.

Because luminance is linear light, intuition from the channel numbers misleads: pure red on white is only 4.0:1, and mid grey `#808080` contrasts more with black (5.3:1) than with white (3.9:1), so a "lightness below 50% means white text" rule picks the wrong colour.

## Rounding and thresholds

`contrastRatio` is rounded to 6 decimal places. WCAG says the ratio must not be rounded up to meet a threshold: `#777777` on white is 4.478089, which fails AA (4.5 for body text, 3 for large text; AAA needs 7 and 4.5). Compare the result directly; do not round it to one place first. `readableTextColor` compares unrounded ratios, and a tie goes to the earlier candidate, which is returned exactly as written.

Sources: W3C, Web Content Accessibility Guidelines (WCAG) 2.2, definitions of "contrast ratio" and "relative luminance", and Success Criteria 1.4.3 and 1.4.6 (https://www.w3.org/TR/WCAG22/); IEC 61966-2-1 (sRGB).

Files