WCAG Color Constrast

A zero dependency library to check for WCAG compliant color contrasts.

Usage

Prerequisites

Node.js >= 22.x: This project leverages modern ESM features and ReScript generated patterns that perform best on recent V8 engines.

PNPM >= 9: PNPM is a fast, disk space efficient package manager.

This package is emitted as ES Modules (ESM) using the .mjs extension. Ensure your environment supports ESM or use a dynamic import() if calling from a CommonJS file.

Installation

pnpm add wcag-color-contrast

Basic example

import * as WCAG from "wcag-color-contrast";

// Get the raw contrast ratio
const ratio = WCAG.getContrastRatio("#ffffff", "#000000");
console.log(ratio); // 21.0

// Check compliance for normal text
const report = WCAG.isCompliant(ratio);
console.log(report);
/*
 { "WCAG 2.x": 
    {
        "AA": true,
        "AAA": true
    }
}
*/

Advanced Usage

// isCompliant(ratio, fontSize, bold)
const results = WCAG.isCompliant(3.5, 18, true);

/*
 { "WCAG 2.x": 
    {
        "AA": true,
        "AAA": true
    }
}
*/

Utility functions

WCAG.toRgba("#f00"); // "rgba(255, 0, 0, 1)"
WCAG.toRgba("#00000080"); // "rgba(0, 0, 0, 0.5)"

API Reference

| Function | Parameters | Returns | Description | | ------------------ | --------------------------------------- | ------- | --------------------------------------------- | | getContrastRatio | (color1: string, color2: string) | number | Calculates ratio between 1.0 and 21.0 | | isCompliant | (ratio: number, fontSize?, bold?: bool) | object | Returns { WCAG 2.x: { AAA: bool, AA: bool } } | | toRgba | (hex: string) | string | Converts hex to rgba() format. |

Development Installation

pnpm install

Build

It is recommended to use the build and test on change scripts in two separate terminal windows.

• Build on change: pnpm run res:dev
• Test on change: pnpm run test:watch
• Build: pnpm run res:build