@josueavalosjim/taste-check 0.3.1 → 0.4.1

package/README.md

@@ -1,22 +1,27 @@
 # taste-check
 
-Two deterministic checks for a design system you already have. It computes WCAG
-contrast ratios from your own custom properties, and flags class names and
-literal values that are not on your own approved list.
+Design review in CI, with a line down the middle of it.
 
-It has no opinion about which colours you use or which classes are allowed.
-You supply both.
+Some of design review is measurable. Contrast ratios, values that should have
+been tokens, class names nobody approved. taste-check measures those and fails
+your build on them.
 
-```bash
-npx @josueavalosjim/taste-check --config tastecheck.config.json
-```
+The rest is judgment, and it cannot be measured. For that it sends your
+screenshots and your checklist to a model, and reports what comes back as an
+opinion rather than a result.
 
-Installed as a dependency, the command is just `taste-check`:
+Keeping those two apart is the whole design. A tool that blurs them either
+blocks your pipeline on a coin flip or quietly downgrades a real failure to a
+suggestion.
 
 ```bash
 npm i -D @josueavalosjim/taste-check
 ```
 
+```bash
+npx @josueavalosjim/taste-check
+```
+
 ```
 contrast ok, 10 pairs across 2 themes
     ok  17.76:1  needs 4.5  light  --text-strong on --surface  body text
@@ -28,20 +33,37 @@ treatments FAILED
   FAIL  src/Promo.jsx:8 inline value "#ff0055" on <a> is a one-off. Use a token, or add it to approvedValues.
 ```
 
+```bash
+npx @josueavalosjim/taste-check judge
+```
+
+```
+judge ok, 5 lines against 2 screenshots, 1 to read
+  NOTE  fail   Nothing important is cut off at the edge: the third card runs
+                past the right edge of the frame at roughly x=798 of 800.
+```
+
 Zero runtime dependencies. Node 22 or newer.
 
 ## Why this exists
 
-Most quality tooling checks compliance and has no point of view. axe tells you
-an element fails 4.5:1. It cannot tell you that your borders answer to 3:1
-while your captions answer to 4.5:1, because that distinction is yours, not the
-spec's.
+Linters have a gate and no taste. They enforce what someone could write down
+as a rule, which is why they can tell you an element fails 4.5:1 but not that
+your borders answer to 3:1 while your captions answer to 4.5:1. That
+distinction is yours, not the spec's.
+
+The newer AI design reviewers have taste and no gate. They will tell you what
+is wrong with a screen, in prose, in a chat window, and some of them arrive
+with a few hundred opinions already loaded about what good looks like.
 
-Design systems drift in a specific way: a value gets hardcoded because the
-token did not quite fit, a class gets invented because nobody knew the approved
-one existed. Written rules do not stop it. A rule in a stylesheet comment is
-enforced by people re-reading stylesheets, and nobody re-reads a stylesheet
-while writing markup. So the rules get a check that runs instead.
+Both halves are useful and they need to stay separable. Run the same model
+twice over the same unchanged screen and you can get two different answers,
+which is fine for advice and disqualifying for a build gate. So the measured
+half here gates, the judged half does not, and the tool will not let you
+confuse one for the other by accident.
+
+It also ships no design rules of its own. Not a palette, not a class list, not
+a contrast floor, not a checklist. You supply all of it.
 
 ## What counts as a failure
 
@@ -58,6 +80,12 @@ Each of these exits 1 rather than passing quietly:
 A check that cannot fail is worse than no check, because it goes green and gets
 quoted as evidence.
 
+The judge is held to the same rule from the other side. Its verdicts never
+affect the exit code by default, but a judge that could not run does: no
+screenshots, a command that died, a reply that was not JSON or that skipped a
+checklist line. "Did not run" and "found nothing" must not print the same
+thing.
+
 ## The contrast check
 
 Give it your custom properties, describe your themes, and list what must clear
@@ -252,6 +280,33 @@ taste-check judge [options]   Ask a fresh-eyes judge about your screenshots
 Exit code is 1 if any check fails, 0 if every check ran and passed. The judge
 plays by the rules in its own section above.
 
+## Where it sits next to other tools
+
+This is a small tool with a narrow claim, and several of these are better than
+it at the thing they do. Reach for them.
+
+**axe, pa11y.** They run against a real rendered page and catch far more than
+contrast. taste-check checks pairs you declare in a config, before a page
+exists and without a browser. Use both. If you only run one accessibility
+tool, run axe.
+
+**stylelint, eslint.** General code quality, with an enormous rule ecosystem.
+Nothing here replaces them.
+
+**@lapidist/design-lint.** More thorough than taste-check on the token and
+component side: it parses properly rather than scanning, knows about
+frameworks, autofixes, and manages deprecations. If enforcing tokens in code is
+the whole of your problem, it is the better fit.
+
+**Checklist Design and similar agent skills.** They arrive with a hundred or
+more published checklists and review conversationally. If you want good
+opinions supplied, take theirs. taste-check supplies none on purpose and runs
+in CI with an exit code instead.
+
+What is left, and the reason this exists: nothing above draws a line between
+the part that can gate a build and the part that cannot. The linters have no
+judgment, the judges have no gate.
+
 ## What this does not do
 
 Read this before trusting a green run.
@@ -265,10 +320,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
@@ -283,13 +343,22 @@ invisible to it.
 Not built. Written down so the shape is clear.
 
 **A runtime mode**, closing the gap named above by measuring `getComputedStyle`
-in a real browser, as an optional peer dependency so the core stays free of one.
+in a real browser, as an optional peer dependency so the core stays free of
+one. This is the one that matters most. An advisory judge is only worth
+listening to if the measured half beside it is genuinely measured, and reading
+a token file is the weaker version of that.
 
 **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.
+**SARIF output**, so findings land in a code scanning tab rather than only in
+a log.
+
+**A way to run the judge from an agent skill**, not only from a shell.
+
+**`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.
 
 ## Development
 

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@josueavalosjim/taste-check",
-  "version": "0.3.1",
-  "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.",
+  "version": "0.4.1",
+  "description": "Design review in CI with a line down the middle: measured checks that gate the build (WCAG contrast over your own tokens, one-off values in your own markup) and a fresh-eyes model judge whose verdicts stay advisory. Ships no design rules of its own.",
   "keywords": [
     "accessibility",
     "cli",
     "contrast",
+    "design-review",
     "design-system",
     "design-tokens",
     "lint",

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