npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

a11y-color-contrast

v0.2.0

Published

A simple utility package for working with WCAG 2.2/3.0 color contrasts

Downloads

12,734

Readme

  • a11y: Built for checking how readable colors are together
  • Simple: Parsing of hex strings, contrast checks
  • WCAG: Support for checking both WCAG 2.0 and WCAG 3.0 contrasts
  • APCA: Support for the upcoming APCA contrast algorithm

Installation

Deno

import { apcaContrastValue, hex, wcagContrastValue } from "https://deno.land/x/a11y_color_contrast/mod.ts";

const wcag = wcagContrastValue(hex("#e1e1e1"), hex("#fff"));
const apca = apcaContrastValue(hex("#e1e1e1"), hex("#fff"));

Node

Install the module with your favorite manager: npm add a11y-color-contrast

import { apcaContrastValue, hex, wcagContrastValue } from "a11y-color-contrast";

const wcag = wcagContrastValue(hex("#e1e1e1"), hex("#fff"));
const apca = apcaContrastValue(hex("#e1e1e1"), hex("#fff"));

Getting started

You can also read the documentation on Deno docs.

hex

hex is a utility function to parse a hex string to a [number, number, number], useful if your colors are not in the RBG format. Supports both short and long hex colors, and will strip out the alpha channel when the hex string contains it. Note, the returned tripled will contain NaN if the string cannot be parsed. Use isValidColor to check if the input can be invalid.

// import { hex } from "a11y-color-contrast";
import { hex } from "https://deno.land/x/a11y_color_contrast/mod.ts";

hex("#fff");
hex("#e1e1e1");

// Also support hex4/hex8
hex("#1234");
hex("#11ff0000");

// And missing #
hex("fff");

wcag

Based on the WCAG 2.2 algorithm to calculate how readable two colors are when used together. The first argument is the foreground color and the second the background. By default, the function defaults to checking whether the colors pass the WCAG AAA standard (7:1 contrast ratio) for normal text.

// import { hex, wcag } from "a11y-color-contrast";
import { hex, wcag } from "https://deno.land/x/a11y_color_contrast/mod.ts";

wcag(hex("#fff"), hex("#e1e1e1"));
// { level: "AAA", size: "normal", score: 1.3076906134240802, pass: false }

wcag(hex("#0f0f0f"), hex("#fff"));
// { level: "AAA", size: "normal", score: 19.168645448127652, pass: true }

wcag(hex("#0f0f0f"), hex("#f4f"), { level: "AA" });
// { level: "AA", size: "normal", score: 6.8668010864317885, pass: true }

wcag(hex("#0f0f0f"), hex("#f4f"), { level: "AA", size: "large" });
// { level: "AA", size: "large", score: 6.8668010864317885, pass: true }

wcagContrastValue

A simpler version of the wcag function, this returns the contrast value between two colors based on the WCAG 2.2 algorithm.

// import { hex, wcagContrastValue } from "a11y-color-contrast";
import { hex, wcagContrastValue } from "https://deno.land/x/a11y_color_contrast/mod.ts";

wcagContrastValue(hex("#fff"), hex("#e1e1e1"));
// 1.3076906134240802

wcagContrastValue(hex("#0f0f0f"), hex("#fff"));
// 19.168645448127652

wcagIsReadable

A simpler version of the wcag function, this checks whether two colors used together are readable based on the WCAG parameters passed.

// import { hex, wcagIsReadable } from "a11y-color-contrast";
import { hex, wcagIsReadable } from "https://deno.land/x/a11y_color_contrast/mod.ts";

wcagIsReadable(hex("#fff"), hex("#e1e1e1"));
// false

wcagIsReadable(hex("#0f0f0f"), hex("#fff"));
// true

wcagIsReadable(hex("#0f0f0f"), hex("#f4f"), { level: "AAA" });
// false

wcagIsReadable(hex("#0f0f0f"), hex("#f4f"), { level: "AA" });
// true

apcaContrastValue

Based on the upcoming WCAG 3.0 standard, this function is based on the APCA algorithm to calculate how readable two colors are when used together. The first argument is the foreground color and the second the background. It is highly recommended reading the linked article and resources to get an overview over the differences between the WCAG and APCA standard.

// import { apcaContrastValue, hex } from "a11y-color-contrast";
import { apcaContrastValue, hex } from "https://deno.land/x/a11y_color_contrast/mod.ts";

apcaContrastValue(hex("#fff"), hex("#e1e1e1"));
// -17.5

apcaContrastValue(hex("#0f0f0f"), hex("#fff"));
// 105.5

apcaContrastValue(hex("#0f0f0f"), hex("#f4f"));
// 51.2

apcaToInterpolatedFont

Based on a Lc between two colors, this will find the appropriate font sizes for it. The returned array will show "placeholder" for when the contrast is too low for text and "prohibited" when the contrast is unusable and otherwise a font size. If no font size can be calculated it will return null.

The returned array contains nine values, corresponding to the font useable at font weight 100 at index 0, and so on until weight 900 at index 8.

// import { apcaToInterpolatedFont, hex } from "a11y-color-contrast";
import { apcaToInterpolatedFont, hex } from "https://deno.land/x/a11y_color_contrast/mod.ts";

apcaToInterpolatedFont(-17.5);
//  100 200 300 400 500 600 700 800 900
// [ "placeholder", ...]

apcaToInterpolatedFont(105.5);
//  100  200 300 400   500 600 700 800 900
// [ 39, 25, 18, 14.5, 14, 13, 12, 16, 18 ]

apcaToInterpolatedFont(51.2);
//  100  200 300 400 500 600   700   800   900
// [ 92, 69, 57, 31, 27, 23.5, 20.5, 20.5, 20.5 ]

apcaValidateFont

Based on a Lc value, this function allows you to check whether a given font and weight combination passes the required minimum contrast based on the APCA contrast table.

The first parameter is the Lc value, the second is either a single font size or an array of them and the third, optional parameter is either a single font weight or an array of them. If the weight parameter is undefined, it will default to all the font weights.

// import { apcaValidateFont, hex } from "a11y-color-contrast";
import { apcaValidateFont, hex } from "https://deno.land/x/a11y_color_contrast/mod.ts";

apcaValidateFont(-17.5, 36, 800);
// { "36": { "800": false } }

apcaValidateFont(105.5, [14, 16, 18], [400, 600, 800]);
// {
//   "14": { "400": true, "600": true, "800": false },
//   "16": { "400": true, "600": true, "800": true },
//   "18": { "400": true, "600": true, "800": true }
// }

apcaValidateFont(51.2, [18, 32]);
// {
//   "18": { "100": false, "200": false, ..., "700": false, "800": false, "900": false },
//   "32": { "100": false, "200": false, ..., "500": true, "600": true, "700": true, "800": true, "900": true }
// }

Utility functions

toHex

Converts an RGB triplet to its hex string representation.

// import { toHex } from "a11y-color-contrast";
import { toHex } from "https://deno.land/x/a11y_color_contrast/mod.ts";

toHex([0, 0, 0]);
// "#000000"

isValidColor

Checks whether a color parsed via hex is valid.

// import { isValidColor } from "a11y-color-contrast";
import { isValidColor } from "https://deno.land/x/a11y_color_contrast/mod.ts";

isValidColor([0, 0, 0]);
// true

isValidColor([NaN, 0, 0]);
// false

colorFromObject

Converts an RGB object into an RGB triplet.

// import { colorFromObject } from "a11y-color-contrast";
import { colorFromObject } from "https://deno.land/x/a11y_color_contrast/mod.ts";

colorFromObject({ r: 0, g: 0, b: 0 });
// [0, 0, 0]

Inspiration and resources

  • APCA homepage: https://git.apcacontrast.com/
  • APCA calculator: https://www.myndex.com/APCA/
  • APCA/WCAG calculator: https://www.myndex.com/BPCA/
  • Contrast Calculator: https://contrast.tools/
  • Accessible Palette: https://accessiblepalette.com/
  • It’s time for a more sophisticated color contrast check for data visualizations: https://blog.datawrapper.de/color-contrast-check-data-vis-wcag-apca/

License

MIT