@josueavalosjim/taste-check 0.7.0 → 0.9.0

package/README.md

@@ -342,6 +342,23 @@ Point your editor at `schema/config.schema.json` for completion and inline
 docs. Paths inside a config resolve against the config file, so it can be run
 from anywhere.
 
+Unknown keys are rejected, because a misspelled key that silently does nothing
+is a config that looks like it is working. `$comment` is the exception: it is
+allowed wherever an object is, ignored, and takes a string or an array of them.
+A config you are expected to live with for years should let you write down why
+it is the way it is.
+
+```json
+{
+  "$comment": "Guards the ramp itself. The browser suite only covers tokens some selector reaches.",
+  "contrast": {
+    "pairs": [
+      { "$comment": "Documented at 6.13:1 in tokens.css.", "fg": "--ink-muted", "bg": "--bg", "min": 4.5 }
+    ]
+  }
+}
+```
+
 | Key | Meaning |
 | --- | --- |
 | `contrast.tokens` | CSS files holding the custom properties. Later files override earlier ones. |
@@ -457,10 +474,11 @@ component are all invisible here. What this gives you is that the
 values in your token file relate to each other the way you said they should. It
 does not prove what a visitor sees.
 
-**Only some colour formats parse.** Hex in 3, 4, 6 and 8 digits; `rgb()`,
-`rgba()`, `hsl()`, `hsla()`, `hwb()`, `oklch()` and `oklab()`; and `white` /
-`black` / `transparent`. `lab()`, `lch()` and `color-mix()` are not parsed yet.
-A value it cannot parse fails, so you hear about it immediately.
+**Not every colour format parses.** What does: hex in 3, 4, 6 and 8 digits;
+`rgb()`, `rgba()`, `hsl()`, `hsla()`, `hwb()`, `oklch()`, `oklab()`, `lab()`
+and `lch()`; and `white` / `black` / `transparent`. `color-mix()` and
+`color()` do not. A value it cannot parse fails, so you hear about it
+immediately.
 
 An `oklch()` outside the sRGB gamut is clipped rather than gamut-mapped, which
 is what a browser canvas does with it. That was checked rather than assumed:
@@ -482,10 +500,9 @@ Not built. Written down so the shape is clear.
 
 **YAML configs**, once there is a reason to take on a parser.
 
-**`lab()` and `lch()`**, which need the D50 white point and a chromatic
-adaptation step that `oklch()` does not. Completeness rather than reach, so
-it sits behind the others. Worth doing the same way when it happens: derive it,
-then check every case against a browser rather than trusting the matrices.
+**`color-mix()` and `color()`**, which are a different shape of problem: one
+needs an interpolation model and the other a colour space argument, so neither
+is another conversion function.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josueavalosjim/taste-check",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Design review in CI with a line down the middle: measured checks that gate the build (WCAG contrast from your tokens or from a real rendered page, one-off values in your markup) and a fresh-eyes model judge whose verdicts stay advisory. Zero dependencies. Ships no design rules of its own.",
   "keywords": [
     "accessibility",

package/schema/config.schema.json

@@ -89,11 +89,39 @@
                         "atRule": {
                           "type": "string",
                           "description": "Opt into declarations nested in a matching at-rule prelude, for example \"prefers-color-scheme: dark\". Conditional at-rules (@media, @supports, @container, @scope) are ignored without this. Grouping at-rules like @layer are always transparent, so you only name one to narrow a scope to it."
+                        },
+                        "$comment": {
+                          "oneOf": [
+                            {
+                              "type": "string"
+                            },
+                            {
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            }
+                          ],
+                          "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
                         }
                       }
                     }
                   ]
                 }
+              },
+              "$comment": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                ],
+                "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
               }
             }
           }
@@ -137,9 +165,37 @@
                 "items": {
                   "type": "string"
                 }
+              },
+              "$comment": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                ],
+                "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
               }
             }
           }
+        },
+        "$comment": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
         }
       }
     },
@@ -187,6 +243,20 @@
           "items": {
             "type": "string"
           }
+        },
+        "$comment": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
         }
       }
     },
@@ -227,6 +297,20 @@
           ],
           "default": "never",
           "description": "Whether a \"fail\" verdict affects the exit code. Defaults to never: a model's verdict is not reproducible, so it does not gate a build unless you decide it should. Independent of this, a judge that could not run always exits 1."
+        },
+        "$comment": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
         }
       }
     },
@@ -282,6 +366,20 @@
               "waitFor": {
                 "type": "string",
                 "description": "A selector to wait for before measuring."
+              },
+              "$comment": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                ],
+                "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
               }
             }
           }
@@ -318,11 +416,53 @@
               "againstParent": {
                 "type": "boolean",
                 "description": "Measure against what is behind the element rather than its own background. Use when the thing being measured is a fill: measuring a fill against itself scores 1.00 and means nothing."
+              },
+              "$comment": {
+                "oneOf": [
+                  {
+                    "type": "string"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "string"
+                    }
+                  }
+                ],
+                "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
               }
             }
           }
+        },
+        "$comment": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          ],
+          "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
         }
       }
+    },
+    "$comment": {
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      ],
+      "description": "Ignored. Somewhere to write down why this config, or this pair, is the way it is."
     }
   }
 }

package/src/color.mjs

@@ -25,7 +25,7 @@ const NAMED = {
 };
 
 /** Formats deliberately not supported in v1, named so the error is useful. */
-const KNOWN_UNSUPPORTED = ['lab', 'lch', 'color-mix', 'color'];
+const KNOWN_UNSUPPORTED = ['color-mix', 'color'];
 
 const NUMBER = /^[+-]?(?:\d+\.?\d*|\.\d+)%?$/;
 
@@ -94,6 +94,45 @@ function oklabToRgb(L, a, b) {
   });
 }
 
+/**
+ * CIELAB to sRGB.
+ *
+ * Longer than the OKLab path because CSS specifies lab() and lch() against the
+ * D50 white point while sRGB is D65, so a chromatic adaptation sits in the
+ * middle. The matrix below folds the adaptation and the XYZ-to-sRGB step
+ * together, which is how CSS Color 4 publishes it.
+ *
+ * Every constant here is checked against a browser rather than trusted. See
+ * the lab corpus in the tests: recalling a colour matrix correctly and
+ * recalling it confidently feel identical from the inside.
+ */
+const D50 = [0.3457 / 0.3585, 1, (1 - 0.3457 - 0.3585) / 0.3585];
+const XYZ_D50_TO_LINEAR_SRGB = [
+  [3.1341359569958707, -1.6173863321612538, -0.4906619460083532],
+  [-0.9787684456108496, 1.9161415707653082, 0.03344273116131949],
+  [0.07203000098937905, -0.22898208700867398, 1.4053851622747988],
+];
+
+function labToRgb(L, a, b) {
+  const e = 216 / 24389;
+  const k = 24389 / 27;
+  const fy = (L + 16) / 116;
+  const fx = a / 500 + fy;
+  const fz = fy - b / 200;
+  const xr = fx ** 3 > e ? fx ** 3 : (116 * fx - 16) / k;
+  const yr = L > k * e ? fy ** 3 : L / k;
+  const zr = fz ** 3 > e ? fz ** 3 : (116 * fz - 16) / k;
+  const xyz = [xr * D50[0], yr * D50[1], zr * D50[2]];
+  const linear = XYZ_D50_TO_LINEAR_SRGB.map((row) => row.reduce((sum, m, i) => sum + m * xyz[i], 0));
+  return linear.map((c) => {
+    const v =
+      c <= 0.0031308
+        ? 12.92 * c
+        : 1.055 * Math.abs(c) ** (1 / 2.4) * Math.sign(c) - 0.055 * Math.sign(c);
+    return clamp(v, 0, 1) * 255;
+  });
+}
+
 /** HSL to sRGB. h in turns, s and l in 0-1. */
 function hslToRgb(h, s, l) {
   const f = (n) => {
@@ -153,29 +192,39 @@ export function parseColor(input) {
   const fn = text.match(/^([a-zA-Z-]+)\s*\(([\s\S]*)\)$/);
   if (fn) {
     const name = fn[1].toLowerCase();
-    if (name === 'oklch' || name === 'oklab') {
+    if (name === 'oklch' || name === 'oklab' || name === 'lab' || name === 'lch') {
+      const cie = name === 'lab' || name === 'lch';
+      const polarSpace = name === 'oklch' || name === 'lch';
       const [head, ...tail] = fn[2].split('/');
       if (tail.length > 1) return err(`"${text}" has more than one slash`);
       const parts = head.trim().split(/[,\s]+/).filter(Boolean);
       const alphaToken = tail.length ? tail[0].trim() : undefined;
       if (parts.length !== 3) return err(`"${text}" needs three components`);
 
-      // Lightness is 0-1, or a percentage of that.
-      const L = parts[0].endsWith('%') ? percent(parts[0]) : NUMBER.test(parts[0]) ? parseFloat(parts[0]) : null;
+      // Lightness runs 0-1 in the OK spaces and 0-100 in the CIE ones. A
+      // percentage means the same thing in both, scaled to whichever.
+      const top = cie ? 100 : 1;
+      const L = parts[0].endsWith('%')
+        ? percent(parts[0]) * top
+        : NUMBER.test(parts[0])
+          ? parseFloat(parts[0])
+          : null;
       if (L === null) return err(`"${text}" has a lightness that is not a number`);
+      // What 100% means for the other two components, per CSS Color 4.
+      const abFull = cie ? 125 : 0.4;
+      const chromaFull = cie ? 150 : 0.4;
 
       let a;
       let b;
-      if (name === 'oklab') {
-        // a and b are roughly -0.4 to 0.4; a percentage is relative to 0.4.
+      if (!polarSpace) {
         const ab = [parts[1], parts[2]].map((t) =>
-          t.endsWith('%') ? percent(t) * 0.4 : NUMBER.test(t) ? parseFloat(t) : null,
+          t.endsWith('%') ? percent(t) * abFull : NUMBER.test(t) ? parseFloat(t) : null,
         );
         if (ab.some((v) => v === null)) return err(`"${text}" has a component that is not a number`);
         [a, b] = ab;
       } else {
         const C = parts[1].endsWith('%')
-          ? percent(parts[1]) * 0.4
+          ? percent(parts[1]) * chromaFull
           : NUMBER.test(parts[1])
             ? parseFloat(parts[1])
             : null;
@@ -193,7 +242,8 @@ export function parseColor(input) {
         if (parsed === null) return err(`"${text}" has an alpha that is not a number`);
         alphaValue = parsed;
       }
-      return ok([...oklabToRgb(clamp(L, 0, 1), a, b), clamp(alphaValue, 0, 1)]);
+      const rgb = cie ? labToRgb(clamp(L, 0, 100), a, b) : oklabToRgb(clamp(L, 0, 1), a, b);
+      return ok([...rgb, clamp(alphaValue, 0, 1)]);
     }
 
     const polar = name === 'hsl' || name === 'hsla' || name === 'hwb';

package/src/config.mjs

@@ -27,8 +27,28 @@ function stringArray(value, where, errors, { required = true } = {}) {
   return value;
 }
 
+/**
+ * Allowed anywhere an object is, and ignored.
+ *
+ * The validator rejects keys it does not know, which is right: a misspelled
+ * key that silently does nothing is a config that looks like it is working.
+ * The cost is that a config had nowhere to say why it exists. Per-pair labels
+ * carry the reasoning for a pair, and nothing carried the reasoning for the
+ * file. A format people are expected to live with for years should let them
+ * write that down.
+ */
+const COMMENT = '$comment';
+
 function rejectUnknown(object, allowed, where, errors) {
   for (const key of Object.keys(object)) {
+    if (key === COMMENT) {
+      const value = object[key];
+      const ok =
+        typeof value === 'string' ||
+        (Array.isArray(value) && value.every((v) => typeof v === 'string'));
+      if (!ok) errors.push(`${where}.${COMMENT} must be a string, or an array of them`);
+      continue;
+    }
     if (!allowed.includes(key)) {
       errors.push(`${where} has an unknown key "${key}". Allowed: ${allowed.join(', ')}.`);
     }