tmcw / wcag-contrast

WCAG contrast ratio measurement and scoring

wcag color contrast

This module produces WCAG contrast ratio measurement and scoring. It's an accessibility standard, intended to make sure websites have high enough contrast to be readable by everyone, including people with low vision and age-related vision problems. This module is a low-level utility, useful for its implementation of the underlying math: to test a page, you'll want to use something like Google Chrome’s Lighthouse tools, or the axe extension for Chrome and Firefox.

I (personally, speaking as Tom) have doubts about the universality, accuracy, and application of this particular standard. High contrast is a good value, but I argue that the standard is over-strict and doesn't precisely match human perception.

API

luminance

Get the contrast ratio between two relative luminance values

Parameters

• a number luminance value
• b number luminance value

Examples

luminance(1, 1); // = 1

Returns number contrast ratio

rgb

Get a score for the contrast between two colors as rgb triplets

Parameters

• a array
• b array

Examples

rgb([0, 0, 0], [255, 255, 255]); // = 21

Returns number contrast ratio

hex

Get a score for the contrast between two colors as hex strings

Parameters

• a string hex value
• b string hex value

Examples

hex('#000', '#fff'); // = 21

Returns number contrast ratio

score

Get a textual score from a numeric contrast value

Parameters

• contrast number

Examples

score(10); // = 'AAA'

Returns string score

wcag-contrast's Issues

Gulp

Hey, how about turning this into a gulp package that scans your css tells you about contrasts?

Vers 3.0, comments RE: perceptual uniformity, and WCAG 3 & APCA

Hi Tom,

I just happened upon your site, and read this on the readme:

I (personally, speaking as Tom) have doubts about the universality, accuracy, and application of this particular standard. High contrast is a good value, but I argue that the standard is over-strict and doesn't precisely match human perception.

Regarding WCAG 2.x contrast, you are correct: it is not perceptually uniform nor accurate. And you're not the first to notice. Circa April 2019 I started a thread on W3 WCAG GitHub pointing out that "um... this is the wrong math..." and that any standard dependent on that math is therefore somewhat meaningless.

As a result, this led me to the multi-year research project that created ACPA, the Advanced Perceptual Contrast Algorithm.

APCA is the method we are using for the emerging WCAG 3.0

APCA is perceptually uniform and accurate, processes reverse polarity differently than for normal (dark text on light), and takes into account other psychophysical attributes like spatial frequency (i.e. small thin fonts).

You might be interested in clicking "research mode" at the SAPC live demonstrator site, it has some interactive experiments that demonstrate some of the concepts.

I also saw on your blog post:

Compliance with A should be the first step

Here's a funny thing, there is literally no contrast requirement for A. None whatsoever. And like I said, the issues with WCAG 2 contrast are well known, hence my involvement in creating the fix.

One other thing (the actual issue)

The actual reason I stumbled by was I saw this code listed as a dependency listed as "wcag-contrast 3.0.0" and then saw that it was released about the time we created a first editor's draft of WCAG 3.0, so for a moment I thought you were using the new APCA, but in fact your code is still using the WCAG 2 math.

So.... I am concerned about confusion as WCAG 3 does not use the WCAG 2 method at all. My concern is if someone wants the WCAG contrast and they see yours at version 3.0.0 they might wrongly think that it is the new APCA method, which is incompatible as it is a new science based paradigm.

Here are links to brief comparisons of WCAG 2 and APCA.

Part I:Orange You Wondering About Contrast? Answering some contrast questions, and demonstrating a real solution to the infamous orange conundrum.

Part II:The Lighter Side of Dark Backgrounds An article comparing some parts of APCA with the old WCAG 2 contrast methods.

Part III: WCAG 2 vs APCA Contrast Shootout
Answering some recent questions regarding APCA, and comparisons and examples of the old (WCAG 2 1.4.3) and the new WCAG 3 with APCA.

Thank you!

Andy

Andrew Somers
W3 AGWG Invited Expert
Senior Color Science Researcher
Myndex Perception Research
Inventor of APCA

THE REVOLUTION WILL BE READABLE™

Switch to JSDoc

Cannot read property 'startsWith' of undefined

Getting this error when trying to use this library via browserify/frontend.

esm.js:1 Uncaught TypeError: Cannot read property 'startsWith' of undefined

I'm in latest Chrome so it does support string startsWith(), my first guess is that the problem lies with esm which is an unusual and non-standard way of bundling up modules (I've run into the same problem with esm before in other modules).

esm broke my tests

just wanted to put this here in case someone else runs into the issue:

I've upgraded to 1.1.0 and everything went fine when running my project but when i ran my tests (using jest+babel) all tests of modules that were importing wcag-contrast broke with error saying that it couldnt find esm module.

Apparently during build, webpack went directly to index.mjs but during test run Jest wasnt.
Configuring Jest to load index.mjs instead didnt help because of the import statements.
esm being a dev-dep of this lib isnt being installed of course.

in the end my quick-win solution was to install esm as a dev-dep of my project.

I'd recommend moving to something like rollup to build your package. this way users of this lib wont have to install anything else.

Version 10 of node.js has been released

Version 10 of Node.js (code name Dubnium) has been released! 🎊

To see what happens to your code in Node.js 10, Greenkeeper has created a branch with the following changes:

• Added the new Node.js version to your .travis.yml

If you’re interested in upgrading this repo to Node.js 10, you can open a PR with these changes. Please note that this issue is just intended as a friendly reminder and the PR as a possible starting point for getting your code running on Node.js 10.

More information on this issue

Greenkeeper has checked the engines key in any package.json file, the .nvmrc file, and the .travis.yml file, if present.

• engines was only updated if it defined a single version, not a range.
• .nvmrc was updated to Node.js 10
• .travis.yml was only changed if there was a root-level node_js that didn’t already include Node.js 10, such as node or lts/*. In this case, the new version was appended to the list. We didn’t touch job or matrix configurations because these tend to be quite specific and complex, and it’s difficult to infer what the intentions were.

For many simpler .travis.yml configurations, this PR should suffice as-is, but depending on what you’re doing it may require additional work or may not be applicable at all. We’re also aware that you may have good reasons to not update to Node.js 10, which is why this was sent as an issue and not a pull request. Feel free to delete it without comment, I’m a humble robot and won’t feel rejected 🤖

---

FAQ and help

There is a collection of frequently asked questions. If those don’t help, you can always ask the humans behind Greenkeeper.

---

Your Greenkeeper Bot 🌴

Can this module be integrated with wcag-validator? if yes please guide me how. I want to use it for accessibility testing.

Can this module be integrated with wcag-validator? if yes please guide me how. I want to use it for accessibility testing.
Wcag-validator does not have the contrast module in it so this seems to be the best fit but I have no idea how to build a js project so need guidance.

Possible to use on client-side web page?

I'm looking for a tool to work on a test page I've made of all my company's various branding colors. Is it possible to run this script client-side so that I can just include all the needed code in my web page? I'm looping through all our text-color/bg-color combinations and would like to use this to output the compliance pass/fail with each combination.