contrastAPCA

function contrastAPCA(
  textColor: Color,
  bgColor: Color,
  options?: ContrastOptions,
): number;

Positive values mean dark text on a light background (normal polarity); negative values mean light text on a dark background (reverse polarity). Very low contrasts are clipped to 0 (APCA's low-contrast clip), so any nonzero result has a magnitude of at least 0.073. Unlike contrastRatio, argument order matters.

Implements APCA-W3 0.0.98G-4g (APCAcontrast(sRGBtoY(text), sRGBtoY(bg))). Colors are measured from unrounded channels clipped to the display gamut, as in relativeLuminance; the result is continuous in the inputs. Pass { precision: '8bit' } to measure the 8-bit hex values instead.

Parameters

textColorColor

Foreground (text) color.

bgColorColor

Background color.

options?ContrastOptions

Display gamut and channel precision.

Returns

numberNormalized Lc contrast.

Throws

• When options.gamut is not 'srgb' or 'display-p3'.

Example

import { contrastAPCA, parse } from '@pbroom/color-kit';

contrastAPCA(parse('#777'), parse('#fff')); // → ≈ 0.7111 (Lc 71.1)
contrastAPCA(parse('#fff'), parse('#000')); // → ≈ -1.0788 (reverse polarity)

See also