add js build tool and demo page

[alexkrolick]

Proposal This is a rough draft

• Sets up some JS build tooling to support all the current JS package format. Outputs multiple files in dist, under dist/cjs, dist/esm, dist/umd to support CommonJS, ESModules, and UMD (browser/script) usage.
• Split up the src files into a few helpers so they can be imported separately by consumer packages
• Adds a level function that uses the rough thresholds described on the https://www.myndex.com/APCA/ page.
• Adds a demo page that is similar in spirit to https://contrastchecker.com, that is, you tell it what you want to do, and it tells you if it's OK. This is just a proof of concept. It uses the level computation above, but it should probably use the grid interpolation instead if that's more precise.

Screen.Recording.2021-12-11.at.11.09.31.PM.mov

[Myndex]

Hi Alex @alexkrolick

I love this!! Thank you, it's brilliant!

• Adds a demo page that is similar in spirit to https://contrastchecker.com, that is, you tell it what you want to do, and it tells you if it's OK. This is just a proof of concept. It uses the level computation above, but it should probably use the grid interpolation instead if that's more precise.

Okay, so here's the rub, relating to the lookup tables AND the current constants.

We have "some stuff" going on in the lab that involves a slight change of constants and a bit on the lookup table.

One of the things is to get things to "line up" better around 16px as that is the established standard for standard vision. But also am looking to see if the LUT can be simplified at all. Also the LUT as shown does not distinguish the spot reading from fluent reading... that's my fault, there are actually 5 LUTs, for different use cases, and I've tried to combine them into one which has probably only cause confusion....

The use cases are:

• Fluent body text (columns of block text)
  • Target is Lc 90, minimum is Lc 75
• Fluent other text (headlines, menus, other)
  • Target is Lc 75, minimum is Lc 60
• Semi-fluent text (very large headlines, non-content, this category may be deleted)
  • Target is Lc 45 to Lc 60, minimum is Lc 30 to Lc 45
• Spot reading text (copyright, byline, footer matter, non-content)
  • Minimum is Lc 30
• Non-text, understandable (uniquely identifiable icons and non-lexical symbols)
  • Target is Lc 60, minimum is Lc 30
• Non-text, discernible (items like buttons or form fields or focus indicators, but not the text therein)
  • Minimum is Lc 15 (possibly Lc 20 or Lc 30, depending on some pending studies)

What I am thinking, to keep things simple, is just consider the top two fluent text types, and just lump them into one grid:

export const apcaFluentGrid = [
   ["min", "min", "min", "min", "min", "min", "min", "min", "min"],
   ["min", "min", "min", "min", "min", "min", "min", "min", "min"],
   ["min", "min", "min", 95, 90, 85, 80, "min", "min"],
   ["min", "min", "min", 90, 85, 80, 75, "min", "min"],
   ["min", "min", 95, 75, 70, 65, 60, 55, "min"],
   ["min", "min", 90, 70, 65, 60, 55, 50, 45],
   ["min", 95, 85, 65, 60, 55, 50, 45, 40],
   ["min", 90, 75, 60, 55, 50, 45, 40, 35],
   ["min", 85, 70, 55, 50, 45, 40, 35, 30],
   [90, 75, 60, 50, 45, 40, 35, 30, "max"],
   [85, 70, 55, 45, 40, 35, 30, "max", "max"],
   [75, 60, 50, 40, 35, 30, "max", "max", "max"],
   [70, 55, 45, 35, 30, "max", "max", "max", "max"],
   [60, 45, 40, 30, "max", "max", "max", "max", "max"],
 ];

And for now, I am thinking we should remove spot reading and non text things from the math for simplicity.

Thank you again so much!

Andy

[alexkrolick]

What I am thinking, to keep things simple, is just consider the top two fluent text types

This maps roughly onto the WCAG AA 4.5:1 for body text and 3:1 for headlines and icons, which seems like a good alignment between the versions.

Remove spot reading and non text things

It's good to have guidance on contrast for icons. It sounds like the guidelines are about the same as headlines so they might be able be grouped together, as they are in WCAG 2.

---

Regarding the lookup table - I am not sure I understand how to use it. Is it like this?

• The text and headline recommended Lc contrast levels are for a reference font size of 16px, 400 weight.
• The lookup table shows the corrected minimum contrast for a given font size & weight. There are different lookup tables for headline and body text use cases because they are not equally affected by font choices, and they start out with different reference values anyways.
• The recommended contrast level isn't really actionable unless you are exactly at the reference size - it's really just a point in the middle of the grid. If this is the case talking about the recommended contrast level without mentioning the correction factor seems like it will cause confusion.

Side notes:

• Even though 16px is the recommended base font size for body text on the web, in practice it's more like 12-15px on most sites. Not sure if this should be taken into account.
• I am not sure if it is possible, but it would greatly simplify implementation if the lookup tables could be replaced with replicated by a polynomial curve approximating the required contrast adjustment (or other straightforward computation).

[Myndex]

Hi Alex @alexkrolick

This maps roughly onto the WCAG AA 4.5:1 for body text and 3:1 for headlines and icons, which seems like a good alignment between the versions.

That was the general idea...

It's good to have guidance on contrast for icons. It sounds like the guidelines are about the same as headlines so they might be able be grouped together, as they are in WCAG 2.

Probably good in the interim. There are some subtle differences that are on the "future study list" to explore. The processing of words (VFWA) and lexical is separate from object recognition... There are assumptions that they have different requirements, but the "degree" of difference is an unknown factor to be investigated.

Regarding the lookup table - I am not sure I understand how to use it. Is it like this?

The LUT is the minimums for a given use case, font size and weight. The table may be interpolated. Linear interpolation is permitted, always round up to nearest 0.5px for fonts under 24px and round up to next 1px for larger fonts.

Side notes:

• Even though 16px is the recommended base font size for body text on the web, in practice it's more like 12-15px on most sites. Not sure if this should be taken into account.

Which is too small. 14px is a reasonable brickwall minimum. 16px is the assumed minimum, the target is an wx-height of no less than 8px, with an x-height of 10px being somewhat ideal.

I need to revise this chart to some more recent research, but it's still instructive:

• I am not sure if it is possible, but it would greatly simplify implementation if the lookup tables could be replaced with replicated by a polynomial curve approximating the required contrast adjustment (or other straightforward computation).

That is the idea... the LUTs are there during the research phase (when will we ever be done, LOL)... but yes, a parametric curve is the plan. Here are things that need to happen to make it a parametric curve:

• Create a special reference font in all weights, and a 0.5 x-height to body ratio.
• Finish certain empirical studies.
• the curve vs size is relative to x-height and is log.
• the curve for weight is a power curve, with the "knee" at 300-400.
• the interaction between the two curves is as yet undefined, probably additive but that's what the studies are for.

[alexkrolick]

How does "minimum for a given use case" translate to the guideline "75 Lc for body text"? Is there an implied font weight/size in the use case? I don't get it if the guideline is meant to be used independently of the lookup table or not.

[alexkrolick]

Graph of the surface defined by the lookup table. I found it rather informative to see the shape of the curve with real axes instead of constant-sized table rows.

[Justineo]

We may get rid of these gcc configs now.

[Justineo]

I'm looking for ESM version and found this PR. It looks great!

[Myndex]

Graph of the surface defined by the lookup table. I found it rather informative to see the shape of the curve with real axes instead of constant-sized table rows.

That is REALLY cool... it looks like the contrast sensitivity chart, rotated 180degrees....

Am actually getting ready to push a new LUT, it's available as a tab delimited, or an array, in the main repo:

https://github.com/Myndex/SAPC-APCA/blob/master/DATA/LUT-GseriesJan112021.js

Thank you!!!

[Myndex]

Hey Alex @alexkrolick

Firstly, I am really sorry it has taken this long to get to this pull request. In December I had literally just started working with npm and Node, and at the same time there was a lot going on for the last many months in terms of continued development.

I've created a brand "BuildTools" and merged your PR into that branch, and then updated to the current master, and have started to rework things...

Questions:

• how granular should the .mjs file be? Right now everything except colorparsley is in apca-w3
• It's been suggested that for various builds to include the colorparsley functions, do I just add an include from the node modules folder in the index.mjs file?
• And while we're on the topic, I've been thinking colors should be passed around as objects, which is how I has it in the pre-release versions. I changed it to a simple array for the npm.
• And finally, with all the above, I am concerned about breaking things...

[alexkrolick]

• ES Modules should be able to be tree-shaken (removing unused exports) by bundlers so you can break up the index files as needed
• Re-exporting a dependency could look like one of these options:

export * from 'colorparsley' // export everything from that module as if part of this module
export * as parse from 'colorparsley' // put everything from 'colorparsley' module in the 'parse' export of this module

• changing to objects should be fine
• maybe time to write some unit tests?