APCA for W3 & WCAG_3

apca-w3

The APCA version in this repositiory is licensed to the W3/AGWG per the collaborative agreement.

Advanced ... Accessible Perceptual Contrast Algorithm

The "Advanced" was originally part of an internal code name "SAPC" that eventually becasme "APCA"... and the word "advanced" moved along with that... realized that first "A" should - almost has to — be "Accessibility." And it's shockingly obvious now, LOL.

Thus, from here on, APCA stands for:

Accessible
Perceptual
Contrast
Algorithm

Current Version: 0.1.1 G (w3) beta

CHANGE for 0.1.1:

NEW!! Alpha channels! AdobeRGB!!

CHANGE for 0.1.0:

NEW! displayP3!
colorParsley() is now in its own package and must be imported separately.

APCA is a contrast assessment method for predicting the perceived contrast between sRGB colors on a computer monitor. It has been developed as an assessment method for W3 Silver/WCAG3 accessibility standards relating to content for computer displays and mobile devices, with a focus on readability and understandability.

Font Lookup Table

Current as of January 11, 2022

QuickStart

Install

    npm i apca-w3

Import

<script type="module">
 import { APCAcontrast, sRGBtoY, displayP3toY, adobeRGBtoY, alphaBlend, calcAPCA } from './apca-w3';
 import { colorParsley } from '../node_modules/colorparsley/dist/colorparsley';  // optional string parsing
</script>

Usage:

PARSE: If you need to parse a color string or 24bit number, use the colorParsley() function:

    let rgbaArray = colorParsley('aliceblue');

ALPHA BLEND Intended for blending the foreground color into the background. Only the foreground has an alpha. There is no conversion to linear space, so blending takes place is the working colorspace, as is standard.

                       // Send 0-255 arrays alphaBlend(FG, BG)
    let alphaBlended = alphaBlend([0,0,0,0.6],colorParsley([255,255,255])),

                       // Send 0-1.0 float arrays for displayP3toY, 5th element
                      // is bool (false for floats): alphaBlend(FG, BG, false)
    let alphaBlended = alphaBlend([0.7,1.0,1.0,0.33],colorParsley([0,0,0]),false);

CONVERT TO Ys Send rgba INT array [123,123,123,1.0] to sRGBtoY() — this is a slightly different luminance Y that the IEC piecewise.

    let Ys = sRGBtoY([123,123,123,1.0]);

FIND Lc CONTRAST First color must be text, second color must be the background.

    let textColor = [17,17,17,1.0];
    let backgroundColor = [232,230,221,1.0];
    
    let contrastLc = APCAcontrast( sRGBtoY( textColor ), sRGBtoY( backgroundColor ) );

Example using everything together, including alphaBlend:

  let colorTEXT =  rgb(12,23,34,0.65);
  let colorBG =  #e6e0dd;
  
  let Lc = APCAcontrast(sRGBtoY( alphaBlend(colorParsley(colorTEXT), colorParsley(colorBG)) ),
                        sRGBtoY( colorParsley(colorBG) ));

SHORTCUT ALIAS

The long complete line shown above is aliased into a function calcAPCA(). Alpha for the text is automatically detected, and ignored if 1 or ''. The input type is also auto detected (string, king of string, number, array, object). By default returns a signed float -108.0 to 106.0 (approx)

    let Lc = calcAPCA(colorTEXT,colorBG);

String Theory

The following are the available input types for colorParsley(), HSL is not implemented at the moment. All are automatically recognized:

INPUT as STRINGS:

No Alpha
- '#abc' or 'abc' (interpreted as 'aabbcc')
- '#abcdef' or 'abcdef' (hash is ignored)
- 'rgb(123, 45, 67)'
- 'aquamarine' or 'magenta' (full CSS4 named colors list)
With Alpha (alpha is NOT presently calculated, and assumed as fully opaque)
- '#abcf' or 'abcf' (interpreted as 'aabbccff')
- '#123456ff' or '123456ff' (hash is ignored)
- 'rgba(123, 45, 67,1.0)'

INPUT as NUMBER:

As hex
- 0xabcdef
As integer
- 11259375

No alpha parsing for numbers in part as there are big and little endian issues that need to be resolved.

colorParsley() string Parsing Removed, now a dependency

The function is called "colorParsley()" because what is that useless leafy thing the restaurant puts on the plate? Well, most mature software already has good parsing, and you may want to minimize the file leaving all that "parsley" at the restaurant...

So, colorParsley() is removed from the APCA-W3 file, and is now its own package, listed as a dependency here.

colorParsley() is required for the shorthand calcAPCA()

Two Secret Parameters

There are two extra parameters for calcAPCA(), and one extra for APCAcontrast.

calcAPCA( text, BG, places, isInt )
APCAcontrast ( txYs, bgYs, places )
alphaBlend( txt, BG, isInt )

places defaults to -1, but you can send it 0 and the Lc is returned as a rounded value, and instead of a minus sign for polarity, 'WoB' for white on black is returned.

isInt defaults to true, as we assume the RGB tuples are 0-255. If you are sending float such as for displayP3, then set ` isInt = false ``

NOTE: neither of these are "official" and may change, move, or vanish.

EXTRAS

Additional documentation, including a plain language walkthrough, LaTeX math, and more are available at the main SAPC repo.

Current APCA Constants ( 0.1.1 G - W3 )

These constants are for use with the web standard sRGB colorspace.

 // 0.1.1 - W3 constants (W3 license only):
    
  Exponents =  { mainTRC: 2.4,       normBG: 0.56,       normTXT: 0.57,     revTXT: 0.62,     revBG: 0.65, };
  
  ColorSpace = { sRco: 0.2126729,    sGco: 0.7151522,    sBco: 0.0721750, };
    
  Clamps =     { blkThrs: 0.022,     blkClmp: 1.414,     loClip: 0.1,     deltaYmin: 0.0005, };
        
  Scalers =    { scaleBoW: 1.14,     loBoWoffset: 0.027, 
                 scaleWoB: 1.14,     loWoBoffset: 0.027, };

LIVE VERSION

There is a working version with examples and reference material on the APCA site

bobbysebolao/apca-w3