@pawells/colors-apca

@pawells/colors-apca

Description

APCA (Accessible Perceptual Contrast Algorithm) contrast calculation, extracted from @pawells/colors core into its own opt-in package. See "Why is this separate?" below.

Why is this separate?

APCA is licensed to W3/AGWG under the W3 Cooperative License Agreement for use with WCAG accessibility guidelines on web-delivered/web-based content only — a field-of-use restriction that does not apply to plain MIT code. @pawells/colors core must remain fully MIT-compatible with no special restrictions on any subpath, so APCA lives here instead. See THIRD_PARTY_NOTICES.md for full license terms.

Requirements

• Node.js >=22.0.0
• @pawells/colors ^2.0.0 (peer dependency)

Installation

yarn add @pawells/colors @pawells/colors-apca

Quick Start

import { apcaContrast } from '@pawells/colors-apca';

apcaContrast([0, 0, 0], [255, 255, 255]);   // ≈ +106.05 (black text on white)
apcaContrast('#ffffff', '#000000');          // ≈ -107.89 (white text on black)

API Reference

apcaContrast(textColor, backgroundColor): number

Calculates APCA contrast (Lc) between two colors per the APCA SA98G specification. Accepts an RGB instance, [r, g, b] tuple, { r, g, b } interface, or hex string for each argument. Positive values indicate dark text on a light background; negative values indicate light text on a dark background.

Throws ColorError (INVALID_COLOR) if either input cannot be parsed.

License

MIT for this package's code. The APCA algorithm itself carries additional field-of-use restrictions — see THIRD_PARTY_NOTICES.md.