burgee/contrast

Contrast, as a thing the package checks rather than a thing someone remembers.

A burgee is a mark whose charge sits ON its own field, and whose field sits on a page nobody here controls. Both of those are contrast relationships, and both are easy to get wrong in a way that looks fine at 512px and fails at 24. This module measures them, so burgee brand can refuse to emit a flag that would not clear the floor and CI can hold ours to the same line.

WCAG 2.2 sets 4.5:1 for body text and 3:1 for large text and for the parts of a graphic you need in order to understand it. A logo's bars are the latter, so 3:1 is the floor used here — see AA.

The measuring is roundel's, not ours. Colour is the layer below this one, and until 2026-09-09 both packages carried the same forty lines of WCAG luminance — identical constants, identical maths, differing only in which package name the hex error says. What is left here is the part that is actually about a burgee: which pairs of a flag's own colours have to clear the floor, and how to say so to a person running burgee brand.

import { mix, ratio, check, … } from 'burgee/contrast';

FunctionsCopy Anchor Link

auditBurgeeCopy Anchor Link

Every contrast relationship a burgee has to survive.

Two are intrinsic — each bar against the field beneath it — and hold wherever the flag is used. The rest depend on where it is placed, so pass the grounds the flag will actually fly on and they are checked too. A flag that passes the intrinsic pair and fails a ground has a page problem, not a logo problem.

function auditBurgee(brand: AuditInput, grounds?: readonly string[]): ContrastFinding[];

Returns ContrastFinding[]

checkCopy Anchor Link

function check(what: string, a: string, b: string, required?: 3): ContrastFinding;

Returns ContrastFinding

contrastCopy Anchor Link

The WCAG contrast ratio between two colours. Order does not matter.

function contrast(a: string, b: string): number;

Returns number

fieldColorAtCopy Anchor Link

The field colour at a point along the gradient axis, for stops given in order.

function fieldColorAt(stops: ReadonlyArray<{
    offset: number;
    color: string;
}>, at: number): string;

Returns string

luminanceCopy Anchor Link

WCAG relative luminance.

function luminance(hex: string): number;

Returns number

mixCopy Anchor Link

Mix two colours in sRGB. Enough for reading a gradient stop, not for colour science.

function mix(a: string, b: string, t: number): string;

Returns string

ratioCopy Anchor Link

Round to 2dp for reporting, without pretending to more precision than that — roundel's round2.

function ratio(a: string, b: string): number;

Returns number

reportCopy Anchor Link

One line per finding, aligned, for a terminal or a failing test.

function report(findings: readonly ContrastFinding[]): string;

Returns string

ConstantsCopy Anchor Link

AACopy Anchor Link

The floors WCAG 2.2 sets, as ratios.

const AA: {
    /** Body text against its background. */
    readonly TEXT: 4.5;
    /** Large text, UI components, and meaningful parts of a graphic. */
    readonly GRAPHIC: 3;
};

InterfacesCopy Anchor Link

AuditInputCopy Anchor Link

interface AuditInput {
    mark: {
        lead: string;
        follow: string;
    };
    field: ReadonlyArray<{
        offset: number;
        color: string;
    }>;
    bordure?: {
        color: string;
        width: number;
    } | ReadonlyArray<{
        color: string;
        width: number;
    }>;
}

ContrastFindingCopy Anchor Link

interface ContrastFinding {
    /** What was compared, in the words someone fixing it would use. */
    what: string;
    a: string;
    b: string;
    ratio: number;
    required: number;
    passes: boolean;
}