roundel/contrast

The WCAG 2.2 contrast maths (R5).

import { channels, luminance, contrast, … } from 'roundel/contrast';

FunctionsCopy Anchor Link

channelsCopy Anchor Link

#abc and #aabbcc both parse, to sRGB channels in 0..1. Anything else is a mistake worth throwing on.

function channels(hex: string): [number, number, number];

Returns [number, number, number]

contrastCopy Anchor Link

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

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

Returns number

luminanceCopy Anchor Link

WCAG relative luminance.

function luminance(hex: string): number;

Returns number

reportThemeCopy Anchor Link

One line per finding, aligned, for a terminal or a failing test. Mirrors burgee/contrast's report — the same shape in both packages, because somebody reading a theme audit and a brand audit on the same day should not have to learn two layouts.

function reportTheme(findings: readonly ThemeFinding[]): 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;
};

AAACopy Anchor Link

The stricter conformance level, for a caller who needs it: low-vision users, a CLI run on a projector, a terminal in daylight, or an organisation whose accessibility policy says AAA and does not care that this is a terminal.

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

floorsCopy Anchor Link

The floors for a conformance level, so a caller names a standard rather than a number.

const floors: (level?: Conformance) => typeof AA | typeof AAA;

round2Copy Anchor Link

const round2: (value: number) => number;

InterfacesCopy Anchor Link

ThemeFindingCopy Anchor Link

One token's verdict at one colour level, in the words somebody fixing it would use.

interface ThemeFinding {
    /** The token name — `error`, `ok`, `command`. */
    token: string;
    /** `truecolor` or `256`. Never `16`: those values are the user's terminal theme. */
    at: 'truecolor' | '256';
    /** What the terminal is actually sent at this level, which is not always the hex written. */
    colour: string;
    ground: string;
    ratio: number;
    required: number;
    passes: boolean;
}

TypesCopy Anchor Link

ConformanceCopy Anchor Link

Which WCAG conformance level a theme is held to. AA unless a caller asks for more.

type Conformance = 'AA' | 'AAA';