@josueavalosjim/taste-check 0.3.0 → 0.4.0

package/README.md

@@ -265,10 +265,15 @@ 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()` and `hwb()`, each in both the comma and the space
-syntax; and `white` / `black` / `transparent`. The perceptual spaces
-(`oklch()`, `lab()`, `lch()`) and `color-mix()` are not parsed yet. A value it
-cannot parse fails, so you hear about it immediately.
+`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.
+
+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:
+the test corpus has fifty deliberately out-of-gamut colours painted in a real
+browser and read back as pixels, and the parser agrees with all of them to
+within one channel unit.
 
 **There is no specificity resolution.** Scopes apply in the order you list
 them. If your tokens rely on `.a.b` beating `.b`, list the scopes in the order
@@ -287,9 +292,9 @@ in a real browser, as an optional peer dependency so the core stays free of one.
 
 **YAML configs**, once there is a reason to take on a parser.
 
-**The perceptual colour spaces**, `oklch()` first, which needs real colour
-space conversion and browser-checked tests rather than a formula taken on
-trust.
+**`lab()` and `lch()`**, which need the D50 white point and a chromatic
+adaptation step that `oklch()` does not. Worth doing the same way: derive it,
+then check every case against a browser rather than trusting the matrices.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josueavalosjim/taste-check",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Deterministic design-system checks: WCAG contrast over your own tokens, and a one-off value linter over your own approved list. No palette, no class list, no opinions shipped.",
   "keywords": [
     "accessibility",

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', 'oklab', 'oklch', 'color-mix', 'color'];
+const KNOWN_UNSUPPORTED = ['lab', 'lch', 'color-mix', 'color'];
 
 const NUMBER = /^[+-]?(?:\d+\.?\d*|\.\d+)%?$/;
 
@@ -65,6 +65,35 @@ function percent(token) {
   return parseFloat(token) / 100;
 }
 
+/**
+ * OKLab to sRGB, via linear sRGB.
+ *
+ * The matrices are Björn Ottosson's, which is what CSS Color 4 specifies.
+ * They are checked against a browser rather than trusted: see the oklch corpus
+ * in the tests, generated by painting each colour on a canvas and reading the
+ * pixel back.
+ */
+function oklabToRgb(L, a, b) {
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+  const l = l_ * l_ * l_;
+  const m = m_ * m_ * m_;
+  const q = s_ * s_ * s_;
+  const linear = [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * q,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * q,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * q,
+  ];
+  // Linear to gamma-encoded sRGB, then clipped into gamut. Clipping is the
+  // simple choice and it is not what a browser does for wildly out-of-gamut
+  // colours, which is why parseColor reports whether it had to clip.
+  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) => {
@@ -124,6 +153,49 @@ 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') {
+      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;
+      if (L === null) return err(`"${text}" has a lightness that is not a number`);
+
+      let a;
+      let b;
+      if (name === 'oklab') {
+        // a and b are roughly -0.4 to 0.4; a percentage is relative to 0.4.
+        const ab = [parts[1], parts[2]].map((t) =>
+          t.endsWith('%') ? percent(t) * 0.4 : 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
+          : NUMBER.test(parts[1])
+            ? parseFloat(parts[1])
+            : null;
+        if (C === null) return err(`"${text}" has a chroma that is not a number`);
+        const h = hue(parts[2]);
+        if (h === null) return err(`"${text}" has a hue that is not an angle`);
+        const radians = h * 2 * Math.PI;
+        a = Math.max(C, 0) * Math.cos(radians);
+        b = Math.max(C, 0) * Math.sin(radians);
+      }
+
+      let alphaValue = 1;
+      if (alphaToken !== undefined) {
+        const parsed = alpha(alphaToken);
+        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 polar = name === 'hsl' || name === 'hsla' || name === 'hwb';
     if (polar) {
       // Same two syntaxes as rgb(): comma separated, or space separated with a

package/src/contrast.mjs

@@ -119,6 +119,8 @@ export function runContrast(config, cwd) {
     name: 'contrast',
     samples,
     problems,
-    summary: `${samples.length} pairs across ${themes.length} ${themes.length === 1 ? 'theme' : 'themes'}`,
+    summary: `${samples.length} ${samples.length === 1 ? 'pair' : 'pairs'} across ${
+      themes.length
+    } ${themes.length === 1 ? 'theme' : 'themes'}`,
   };
 }

package/src/css.mjs

@@ -66,10 +66,15 @@ export function parseDeclarations(css) {
     if (colon === -1) return;
     const prop = text.slice(0, colon).trim();
     if (!prop.startsWith('--')) return;
+    // !important is cascade information, not part of the value. A browser
+    // strips it before anyone reads the property back, and leaving it on
+    // would hand "#111 !important" to the colour parser as if it were a
+    // colour. Found by diffing this parser against a real CSSOM.
+    const value = text.slice(colon + 1).trim().replace(/\s*!\s*important\s*$/i, '').trim();
     const selector = [...stack].reverse().find((s) => !s.startsWith('@')) ?? '';
     decls.push({
       prop,
-      value: text.slice(colon + 1).trim(),
+      value,
       selector,
       atRules: stack.filter((s) => s.startsWith('@')),
       index: bufferStart + (source.slice(bufferStart, end).length - source.slice(bufferStart, end).trimStart().length),