Ekklesia/packages/design-tokens/tests/contrast.test.ts

import { describe, expect, it } from "vitest";
import {
  type DesignTokenColorScheme,
  type EkklesiaDesignTokenName,
  ekklesiaDesignTokens,
} from "../src/index.js";

/**
 * WCAG 2.2 AA contrast for every text, control, and focus pairing Ekklesia's elements actually use,
 * in both colour schemes (ADR 0060). 4.5:1 for text (§1.4.3); 3:1 for the boundary that identifies a
 * form control and for focus indication (§1.4.11). These are computed from the token values, which
 * is necessary but not sufficient: representative screens are also rendered in a real browser.
 */

function channels(hex: string): readonly [number, number, number] {
  const match = /^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/u.exec(hex);
  if (!match) {
    throw new Error(`not an opaque hex colour: ${hex}`);
  }
  return [match[1], match[2], match[3]].map((part) => Number.parseInt(part ?? "0", 16) / 255) as [
    number,
    number,
    number,
  ];
}

function luminance(hex: string): number {
  const [r, g, b] = channels(hex).map((value) =>
    value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4,
  ) as [number, number, number];
  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}

function contrastRatio(first: string, second: string): number {
  const [lighter, darker] = [luminance(first), luminance(second)].sort((a, b) => b - a) as [
    number,
    number,
  ];
  return (lighter + 0.05) / (darker + 0.05);
}

type Pairing = readonly [EkklesiaDesignTokenName, EkklesiaDesignTokenName, number, string];

const TEXT = 4.5;
const NON_TEXT = 3;

/** Foreground, background, required ratio, and where it appears. */
const PAIRINGS: readonly Pairing[] = [
  ["text.primary", "background.page", TEXT, "body text on the page"],
  ["text.primary", "background.canvas", TEXT, "sidebar and empty states"],
  ["text.primary", "background.surface", TEXT, "panels, inputs"],
  ["text.primary", "background.raised", TEXT, "dialogs, menus, toasts"],
  ["text.primary", "background.inset", TEXT, "technical details"],
  ["text.secondary", "background.page", TEXT, "descriptions on the page"],
  ["text.secondary", "background.canvas", TEXT, "quiet navigation items"],
  ["text.secondary", "background.surface", TEXT, "panel descriptions"],
  ["text.secondary", "background.raised", TEXT, "dialog descriptions, toast bodies"],
  ["text.secondary", "background.inset", TEXT, "technical detail text"],
  ["text.secondary", "state.hover-background", TEXT, "hovered quiet button"],
  ["text.primary", "state.pressed-background", TEXT, "pressed button"],
  ["text.muted", "background.page", TEXT, "hints and metadata on the page"],
  ["text.muted", "background.canvas", TEXT, "group labels in the sidebar"],
  ["text.muted", "background.surface", TEXT, "field hints, placeholders"],
  ["text.muted", "background.raised", TEXT, "menu captions, phrase status"],
  ["accent.foreground", "accent.base", TEXT, "primary button"],
  ["accent.foreground", "accent.hover", TEXT, "primary button, hovered"],
  ["accent.foreground", "accent.active", TEXT, "primary button, pressed"],
  ["accent.strong", "background.page", TEXT, "eyebrow and accent text"],
  ["accent.strong", "background.surface", TEXT, "accent text in a panel"],
  ["state.selected-foreground", "state.selected-background", TEXT, "the open page in navigation"],
  ["text.danger", "status.danger-background", TEXT, "danger button and badge"],
  ["text.danger", "background.surface", TEXT, "field error"],
  ["text.danger", "background.canvas", TEXT, "error state title"],
  ["text.danger", "background.raised", TEXT, "error in a dialog"],
  ["text.warning", "status.warning-background", TEXT, "warning badge and notice"],
  ["text.success", "status.success-background", TEXT, "success badge and notice"],
  ["text.primary", "status.info-background", TEXT, "information notice"],
  ["text.primary", "status.warning-background", TEXT, "warning notice body"],
  ["text.primary", "status.danger-background", TEXT, "danger notice body"],
  ["text.primary", "status.success-background", TEXT, "success notice body"],
  ["text.primary", "accent.subtle", TEXT, "selected tab"],
  ["border.control", "background.surface", NON_TEXT, "an input's boundary"],
  ["border.control", "background.page", NON_TEXT, "an input on the page"],
  ["border.control", "background.raised", NON_TEXT, "an input in a dialog"],
  ["text.danger", "background.surface", NON_TEXT, "an invalid input's boundary"],
  ["accent.focus", "background.page", NON_TEXT, "focus ring on the page"],
  ["accent.focus", "background.canvas", NON_TEXT, "focus ring in the sidebar"],
  ["accent.focus", "background.surface", NON_TEXT, "focus ring in a panel"],
  ["accent.focus", "background.raised", NON_TEXT, "focus ring in a dialog"],
  ["accent.base", "background.page", NON_TEXT, "the brand mark and a spinner on the page"],
  ["accent.base", "background.canvas", NON_TEXT, "the brand mark in the sidebar"],
  ["accent.base", "background.surface", NON_TEXT, "a selected tab's underline in a panel"],
  ["state.selected-foreground", "accent.subtle", TEXT, "a selected tab's label"],
  ["accent.strong", "background.raised", TEXT, "accent text in a dialog"],
  ["background.surface", "accent.strong", NON_TEXT, "the mark inside a checked box or radio"],
];

describe.each([
  "light",
  "dark",
] as const satisfies readonly DesignTokenColorScheme[])("WCAG 2.2 AA contrast, %s", (scheme) => {
  it.each(PAIRINGS)("%s on %s ≥ %s:1 (%s)", (foreground, background, required) => {
    const ratio = contrastRatio(
      ekklesiaDesignTokens.valueFor(foreground, scheme),
      ekklesiaDesignTokens.valueFor(background, scheme),
    );
    expect(Number(ratio.toFixed(2))).toBeGreaterThanOrEqual(required);
  });
});

describe("the default accent (ADR 0066)", () => {
  it("is anchored on #210050: the light primary action, with white on it", () => {
    expect(ekklesiaDesignTokens.valueFor("accent.base", "light")).toBe("#210050");
    expect(ekklesiaDesignTokens.valueFor("accent.foreground", "light")).toBe("#ffffff");
  });

  it("is lifted in dark rather than forced, and draws the anchor on it", () => {
    // #210050 on a dark surface would all but vanish; the dark accent is a lavender of its hue.
    expect(ekklesiaDesignTokens.valueFor("accent.base", "dark")).not.toBe("#210050");
    expect(ekklesiaDesignTokens.valueFor("accent.foreground", "dark")).toBe("#210050");
  });
});

describe("the contrast calculator", () => {
  it("agrees with WCAG's reference values", () => {
    expect(contrastRatio("#000000", "#ffffff")).toBeCloseTo(21, 5);
    expect(contrastRatio("#ffffff", "#ffffff")).toBeCloseTo(1, 5);
    expect(contrastRatio("#767676", "#ffffff")).toBeCloseTo(4.54, 2);
  });
});

describe("decorative placeholders stay visible in both schemes", () => {
  // A skeleton is hidden from assistive technology, so WCAG sets no ratio for it; it still has to be
  // seen against what it sits on, or it is a blank page rather than a shape of what is coming.
  it.each(["light", "dark"] as const)("%s", (scheme) => {
    for (const background of [
      "background.page",
      "background.surface",
      "background.canvas",
    ] as const) {
      const ratio = contrastRatio(
        ekklesiaDesignTokens.valueFor("background.placeholder", scheme),
        ekklesiaDesignTokens.valueFor(background, scheme),
      );
      expect(ratio, background).toBeGreaterThanOrEqual(1.1);
    }
  });
});