@josueavalosjim/taste-check 0.1.1 → 0.3.0

package/README.md

@@ -50,6 +50,8 @@ Each of these exits 1 rather than passing quietly:
 - a pair naming a token that does not exist
 - a file pattern matching no files
 - a theme whose scopes resolve no tokens
+- a single scope inside a theme that selects nothing, even when the theme has
+  tokens from its other scopes
 - a colour value the parser does not understand
 - an unknown key in the config, which is usually a typo doing nothing
 
@@ -85,16 +87,24 @@ in code, because the floor for a decorative hairline and the floor for body
 text are different decisions and both are yours.
 
 A theme is an ordered list of scopes and later scopes win, which is the cascade
-for equal specificity. Declarations inside an at-rule are ignored unless a
-scope opts in:
+for equal specificity.
+
+`@layer` is transparent. A `:root` inside `@layer tokens` resolves exactly as a
+top-level `:root` does, because a layer changes cascade priority rather than
+whether the declarations apply at all.
+
+Conditional at-rules are different. `@media`, `@supports`, `@container` and
+`@scope` only apply when their condition holds, so their declarations are
+ignored unless a scope opts in by name:
 
 ```json
 { "name": "dark-system", "scopes": [":root", { "selector": ":root", "atRule": "prefers-color-scheme: dark" }] }
 ```
 
-Without that rule a `@media (prefers-color-scheme: dark)` block containing
-`:root` would overwrite the light theme, and the light checks would silently
-measure against colours the light theme never paints.
+Without that, a `@media (prefers-color-scheme: dark)` block containing `:root`
+would overwrite the light theme, and the light checks would measure against
+colours the light theme never paints. You can also name a layer this way to
+narrow a scope to it, but you should never need to just to see your tokens.
 
 Two details make the numbers match a browser rather than approximate it.
 Translucent foregrounds are composited over their background before measuring,
@@ -142,6 +152,69 @@ direction to be wrong in.
 Template literal holes are read into rather than blanked, so a class written
 inside `` `card ${on ? 'card--on' : ''}` `` is seen.
 
+## The judge
+
+Everything above measures. This asks the question a measurement cannot: not
+whether the screen is correct, but whether it is any good.
+
+That question cannot be put to whoever just built the thing. The context that
+made the choices is the worst placed to find them wanting, because the
+reasoning that justified each one is still there ready to justify it again. So
+the judge is a separate process that sees your screenshots and your checklist
+and nothing else.
+
+```json
+{
+  "judge": {
+    "checklist": "design-checklist.md",
+    "shots": ["shots/*.png"],
+    "shotCommand": "node scripts/shots.mjs",
+    "command": "claude -p",
+    "failOn": "never"
+  }
+}
+```
+
+```bash
+taste-check judge
+```
+
+Your `command` receives the prompt on stdin and the image paths as arguments,
+so any model CLI works and no API key ever touches this tool. It must reply
+with JSON:
+
+```json
+{ "findings": [ { "line": "<the checklist line, verbatim>", "verdict": "pass|fail|unsure", "why": "..." } ] }
+```
+
+taste-check supplies the framing: you are seeing this cold, you have not been
+told what changed, answer every line, prefer unsure to a guess, do not be
+agreeable, and name the specific thing you are looking at. That part is method
+and it is the same for everyone.
+
+The checklist is yours. taste-check ships none, and there is a test asserting
+the framing mentions no design vocabulary at all, because a rule that arrives
+inside a tool is somebody else's taste with the tool's authority behind it.
+Checklist lines are list items in your file; a heading or a paragraph is prose
+and is not judged.
+
+### What the exit code means here
+
+A verdict is an opinion, so a `fail` prints as a note and the command exits 0.
+Set `failOn` to `"fail"` if you want it to block, knowing that two runs on the
+same screenshot can disagree.
+
+Whether the judge ran is not an opinion, and never advisory. Each of these
+exits 1 whatever `failOn` says:
+
+- no screenshots were produced or matched
+- the command exited non-zero
+- the reply was not parseable JSON
+- the reply skipped a checklist line, invented one, or answered one twice
+
+Without that split, "the judge did not run" and "the judge found nothing" print
+the same thing.
+
 ## Config
 
 Point your editor at `schema/config.schema.json` for completion and inline
@@ -160,9 +233,15 @@ from anywhere.
 | `treatments.approvedClasses` | Every class allowed to appear. |
 | `treatments.allowPrefixes` | Prefixes that are always allowed, as a deliberate escape hatch. |
 | `treatments.approvedValues` | Literal values allowed inside inline styles. |
+| `judge.checklist` | Your checklist file. List items are judged, prose is not. |
+| `judge.shots` | Screenshots to hand the judge. Matching nothing is a failure. |
+| `judge.shotCommand` | Optional command run first to produce those screenshots. |
+| `judge.command` | The model command. Prompt on stdin, image paths as arguments. |
+| `judge.failOn` | `"never"` (default) or `"fail"`. Whether a verdict blocks. |
 
 ```
-taste-check [options]
+taste-check [options]         Run the deterministic checks
+taste-check judge [options]   Ask a fresh-eyes judge about your screenshots
 
   -c, --config <path>   Config file (default: tastecheck.config.json)
       --only <name>     Run one check: contrast or treatments
@@ -170,7 +249,8 @@ taste-check [options]
       --version         Print the version
 ```
 
-Exit code is 1 if any check fails, 0 if every check ran and passed.
+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.
 
 ## What this does not do
 
@@ -184,11 +264,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()` and
-`rgba()` in both the comma and the space syntax, and `white` / `black` /
-`transparent`. `hsl()`, `oklch()` and `color-mix()` are not parsed yet, and a
-value it cannot parse is a failure rather than a skip, so you will hear about
-it immediately.
+**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.
 
 **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
@@ -202,22 +282,14 @@ invisible to it.
 
 Not built. Written down so the shape is clear.
 
-**A fresh-eyes checklist hook.** The deterministic checks here cover what can
-be measured. The judgment half of design review cannot be, and the useful
-pattern for it is a fresh context: a separate model call that sees a screenshot
-and a checklist, and nothing else. Judging in the same context that produced
-the work is unreliable, because the reasoning that justified a choice is still
-sitting there to justify it again. The plan is a plugin hook that takes your
-screenshot command and your checklist file and reports back in the same format
-as the checks above. The checklist stays yours: a shipped one would just be
-somebody else's taste.
-
 **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.
 
 **YAML configs**, once there is a reason to take on a parser.
 
-**More colour formats**, `hsl()` first.
+**The perceptual colour spaces**, `oklch()` first, which needs real colour
+space conversion and browser-checked tests rather than a formula taken on
+trust.
 
 ## Development
 
@@ -225,6 +297,14 @@ in a real browser, as an optional peer dependency so the core stays free of one.
 npm test
 ```
 
+Releases are automated. `npm run release` runs the suite, bumps the patch
+version, tags it and pushes. The tag triggers a workflow that runs the suite
+again, checks both fixtures still produce the exit codes they should, verifies
+the tag matches `package.json`, and publishes. Publishing uses npm's trusted
+publisher over OIDC, so no npm token is stored in the repository and every
+release carries a provenance attestation. For a minor or major bump, run
+`npm version minor` or `npm version major` and `git push --follow-tags`.
+
 34 tests. Most of them plant a violation into a fixture that was passing a
 moment earlier and demand it gets caught: a token darkened below its floor, an
 unapproved class added to a clean file, a class buried in a template literal

package/bin/taste-check.mjs

@@ -8,12 +8,13 @@
  * not a quiet skip.
  */
 import { load } from '../src/config.mjs';
-import { run } from '../src/index.mjs';
+import { judge, run } from '../src/index.mjs';
 import { failed, toJson, toText } from '../src/report.mjs';
 
 const USAGE = `taste-check
 
-  taste-check [options]
+  taste-check [options]         Run the deterministic checks
+  taste-check judge [options]   Ask a fresh-eyes judge about your screenshots
 
 Options:
   -c, --config <path>   Config file (default: tastecheck.config.json)
@@ -22,10 +23,22 @@ Options:
   -h, --help            This
       --version         Print the version
 
-Exit code is 1 if any check fails, 0 if every check ran and passed.`;
+Exit code is 1 if any check fails, 0 if every check ran and passed.
+
+The judge is a separate command because it runs a model, and a model's
+verdict is not reproducible. Its verdicts print as notes and do not affect
+the exit code unless judge.failOn is set to "fail". Whether the judge ran
+at all is a different question: no screenshots, a command that failed, or
+a reply that skipped a checklist line all exit 1 either way.`;
 
 function parseArgs(argv) {
-  const options = { config: 'tastecheck.config.json', only: null, json: false };
+  const options = { config: 'tastecheck.config.json', only: null, json: false, command: 'check' };
+  // One positional, and only in first position, so a stray argument is an
+  // error rather than something silently ignored.
+  if (argv[0] === 'judge') {
+    options.command = 'judge';
+    argv = argv.slice(1);
+  }
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     const next = () => {
@@ -43,6 +56,7 @@ function parseArgs(argv) {
         throw new Error(`--only takes "contrast" or "treatments", not "${options.only}"`);
       }
     } else if (arg === '--json') options.json = true;
+    else if (!arg.startsWith('-')) throw new Error(`unknown command "${arg}"`);
     else throw new Error(`unknown option "${arg}"`);
   }
   return options;
@@ -81,7 +95,19 @@ if (!loaded.ok) {
   process.exit(1);
 }
 
-const results = run(loaded.config, loaded.dir, { only: options.only });
+if (options.command === 'judge' && options.only) {
+  die('--only applies to the deterministic checks, not to judge');
+}
+
+if (options.command === 'judge' && !loaded.config.judge) {
+  die(`${options.config} defines no "judge" block.`);
+}
+
+const results =
+  options.command === 'judge'
+    ? judge(loaded.config, loaded.dir)
+    : run(loaded.config, loaded.dir, { only: options.only });
+
 if (!results.length) {
   die(`nothing to run. ${options.config} defines no ${options.only ?? 'contrast or treatments'} check.`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josueavalosjim/taste-check",
-  "version": "0.1.1",
+  "version": "0.3.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",
@@ -37,7 +37,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test \"test/**/*.test.mjs\""
+    "test": "node --test \"test/**/*.test.mjs\"",
+    "release": "npm test && npm version patch -m \"Release %s\" && git push --follow-tags"
   },
   "engines": {
     "node": ">=22"

package/schema/config.schema.json

@@ -6,20 +6,44 @@
   "type": "object",
   "additionalProperties": false,
   "minProperties": 1,
-  "anyOf": [{ "required": ["contrast"] }, { "required": ["treatments"] }],
+  "anyOf": [
+    {
+      "required": [
+        "contrast"
+      ]
+    },
+    {
+      "required": [
+        "treatments"
+      ]
+    },
+    {
+      "required": [
+        "judge"
+      ]
+    }
+  ],
   "properties": {
-    "$schema": { "type": "string" },
+    "$schema": {
+      "type": "string"
+    },
     "contrast": {
       "type": "object",
       "description": "WCAG contrast ratios computed from your own custom properties.",
       "additionalProperties": false,
-      "required": ["tokens", "themes", "pairs"],
+      "required": [
+        "tokens",
+        "themes",
+        "pairs"
+      ],
       "properties": {
         "tokens": {
           "type": "array",
           "minItems": 1,
           "description": "CSS files holding the custom properties. Paths resolve against this config file. Later files override earlier ones.",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "themes": {
           "type": "array",
@@ -28,24 +52,38 @@
           "items": {
             "type": "object",
             "additionalProperties": false,
-            "required": ["name", "scopes"],
+            "required": [
+              "name",
+              "scopes"
+            ],
             "properties": {
-              "name": { "type": "string", "minLength": 1 },
+              "name": {
+                "type": "string",
+                "minLength": 1
+              },
               "scopes": {
                 "type": "array",
                 "minItems": 1,
                 "items": {
                   "oneOf": [
-                    { "type": "string", "description": "A selector, matched exactly against one entry in a rule's selector list." },
+                    {
+                      "type": "string",
+                      "description": "A selector, matched exactly against one entry in a rule's selector list."
+                    },
                     {
                       "type": "object",
                       "additionalProperties": false,
-                      "required": ["selector"],
+                      "required": [
+                        "selector"
+                      ],
                       "properties": {
-                        "selector": { "type": "string", "minLength": 1 },
+                        "selector": {
+                          "type": "string",
+                          "minLength": 1
+                        },
                         "atRule": {
                           "type": "string",
-                          "description": "Opt into declarations nested in a matching at-rule prelude, for example \"prefers-color-scheme: dark\". Without this, at-rule declarations are ignored."
+                          "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."
                         }
                       }
                     }
@@ -62,17 +100,38 @@
           "items": {
             "type": "object",
             "additionalProperties": false,
-            "required": ["fg", "bg", "min"],
+            "required": [
+              "fg",
+              "bg",
+              "min"
+            ],
             "properties": {
-              "fg": { "type": "string", "minLength": 1, "description": "A token name like --text, or a literal colour." },
-              "bg": { "type": "string", "minLength": 1, "description": "As fg, but it must resolve to an opaque colour." },
-              "min": { "type": "number", "exclusiveMinimum": 0, "description": "The floor this pair must clear. No default: you decide what the rule is." },
-              "label": { "type": "string", "description": "Why this pair matters. Printed with the result." },
+              "fg": {
+                "type": "string",
+                "minLength": 1,
+                "description": "A token name like --text, or a literal colour."
+              },
+              "bg": {
+                "type": "string",
+                "minLength": 1,
+                "description": "As fg, but it must resolve to an opaque colour."
+              },
+              "min": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "description": "The floor this pair must clear. No default: you decide what the rule is."
+              },
+              "label": {
+                "type": "string",
+                "description": "Why this pair matters. Printed with the result."
+              },
               "themes": {
                 "type": "array",
                 "minItems": 1,
                 "description": "Limit the pair to these themes. Omit to check it in all of them.",
-                "items": { "type": "string" }
+                "items": {
+                  "type": "string"
+                }
               }
             }
           }
@@ -83,34 +142,86 @@
       "type": "object",
       "description": "Class names and literal values in markup, against a list you supply.",
       "additionalProperties": false,
-      "required": ["files"],
+      "required": [
+        "files"
+      ],
       "properties": {
         "files": {
           "type": "array",
           "minItems": 1,
           "description": "Markup to scan. A pattern matching nothing is a failure, never a clean run.",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "elements": {
           "type": "array",
           "minItems": 1,
           "description": "Element names to scan. Use [\"*\"] or omit for every element.",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "approvedClasses": {
           "type": "array",
           "description": "Every class name allowed to appear. Anything else is reported.",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "allowPrefixes": {
           "type": "array",
           "description": "Class name prefixes that are always allowed, for a deliberate escape hatch.",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
         },
         "approvedValues": {
           "type": "array",
           "description": "Literal values allowed in inline styles. Everything else that looks like a colour or a length is reported.",
-          "items": { "type": "string" }
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "judge": {
+      "type": "object",
+      "description": "A fresh-eyes review of your screenshots against your checklist, run by a model command you supply. Run with `taste-check judge`. Verdicts are advisory unless failOn says otherwise.",
+      "additionalProperties": false,
+      "required": [
+        "checklist",
+        "shots",
+        "command"
+      ],
+      "properties": {
+        "checklist": {
+          "type": "string",
+          "description": "A file of checklist lines. List items (\"- ...\" or \"1. ...\") are what gets judged; everything else is treated as prose. taste-check ships no checklist."
+        },
+        "shots": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Screenshots to hand the judge. Matching nothing is a failure: a judge with nothing to look at cannot fail, so it does not get to pass.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "shotCommand": {
+          "type": "string",
+          "description": "Optional command run before the judge to produce the screenshots. Runs from this config file's directory."
+        },
+        "command": {
+          "type": "string",
+          "description": "The model command. It receives the prompt on stdin and the image paths as arguments, and must reply with the documented JSON. Runs from this config file's directory."
+        },
+        "failOn": {
+          "enum": [
+            "never",
+            "fail"
+          ],
+          "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."
         }
       }
     }

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 = ['hsl', 'hsla', 'hwb', 'lab', 'lch', 'oklab', 'oklch', 'color-mix', 'color'];
+const KNOWN_UNSUPPORTED = ['lab', 'lch', 'oklab', 'oklch', 'color-mix', 'color'];
 
 const NUMBER = /^[+-]?(?:\d+\.?\d*|\.\d+)%?$/;
 
@@ -48,12 +48,55 @@ function alpha(token) {
 
 const clamp = (n, lo, hi) => Math.min(hi, Math.max(lo, n));
 
+const TURNS = { deg: 1 / 360, grad: 1 / 400, rad: 1 / (2 * Math.PI), turn: 1 };
+
+/** A hue token to a fraction of a turn, or null. A bare number is degrees. */
+function hue(token) {
+  const m = token.match(/^([+-]?(?:\d+\.?\d*|\.\d+))(deg|grad|rad|turn)?$/);
+  if (!m) return null;
+  const turns = parseFloat(m[1]) * TURNS[m[2] ?? 'deg'];
+  // Wrap into [0, 1). Hue is an angle, so 480deg and -240deg are both 120deg.
+  return ((turns % 1) + 1) % 1;
+}
+
+/** A percentage token to 0-1, or null. */
+function percent(token) {
+  if (!/^[+-]?(?:\d+\.?\d*|\.\d+)%$/.test(token)) return null;
+  return parseFloat(token) / 100;
+}
+
+/** HSL to sRGB. h in turns, s and l in 0-1. */
+function hslToRgb(h, s, l) {
+  const f = (n) => {
+    const k = (n + h * 12) % 12;
+    const a = s * Math.min(l, 1 - l);
+    return l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1));
+  };
+  return [f(0) * 255, f(8) * 255, f(4) * 255];
+}
+
+/**
+ * HWB to sRGB. h in turns, w and b in 0-1.
+ *
+ * When whiteness and blackness sum to 1 or more the hue drops out entirely and
+ * the result is the grey at w / (w + b). Missing that case is the usual bug,
+ * because every other input hides it.
+ */
+function hwbToRgb(h, w, b) {
+  if (w + b >= 1) {
+    const grey = (w / (w + b)) * 255;
+    return [grey, grey, grey];
+  }
+  return hslToRgb(h, 1, 0.5).map((c) => (c / 255) * (1 - w - b) * 255 + w * 255);
+}
+
 /**
  * Parse a CSS colour into [r, g, b, a] with r/g/b in 0-255 and a in 0-1.
  *
- * Supported: #rgb, #rgba, #rrggbb, #rrggbbaa; rgb()/rgba() in both the legacy
- * comma syntax and the modern space syntax with a slash alpha; and the three
- * named colours above. Anything else fails loudly.
+ * Supported: #rgb, #rgba, #rrggbb, #rrggbbaa; rgb(), rgba(), hsl(), hsla()
+ * and hwb(), each in both the legacy comma syntax and the modern space syntax
+ * with a slash alpha; and the three named colours above. Anything else fails
+ * loudly.
  */
 export function parseColor(input) {
   if (typeof input !== 'string') return err('not a string');
@@ -81,6 +124,40 @@ export function parseColor(input) {
   const fn = text.match(/^([a-zA-Z-]+)\s*\(([\s\S]*)\)$/);
   if (fn) {
     const name = fn[1].toLowerCase();
+    const polar = name === 'hsl' || name === 'hsla' || name === 'hwb';
+    if (polar) {
+      // Same two syntaxes as rgb(): comma separated, or space separated with a
+      // slash alpha. Split on the slash first so a modern alpha is never read
+      // as a fourth component.
+      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() : parts[3];
+      if (parts.length < 3) return err(`"${text}" needs a hue and two components`);
+      if (tail.length === 0 && parts.length > 4) return err(`"${text}" has too many components`);
+      if (tail.length === 1 && parts.length !== 3) return err(`"${text}" has too many components`);
+
+      const h = hue(parts[0]);
+      if (h === null) return err(`"${text}" has a hue that is not an angle`);
+      // hsl() allows bare numbers for s and l in the modern syntax; hwb()
+      // requires percentages, but accepting a bare number there costs nothing
+      // and refusing it would only ever reject something a browser renders.
+      const one = percent(parts[1]) ?? (NUMBER.test(parts[1]) ? parseFloat(parts[1]) / 100 : null);
+      const two = percent(parts[2]) ?? (NUMBER.test(parts[2]) ? parseFloat(parts[2]) / 100 : null);
+      if (one === null || two === null) return err(`"${text}" has a component that is not a number`);
+
+      let a = 1;
+      if (alphaToken !== undefined) {
+        const parsed = alpha(alphaToken);
+        if (parsed === null) return err(`"${text}" has an alpha that is not a number`);
+        a = parsed;
+      }
+      const rgb =
+        name === 'hwb'
+          ? hwbToRgb(h, clamp(one, 0, 1), clamp(two, 0, 1))
+          : hslToRgb(h, clamp(one, 0, 1), clamp(two, 0, 1));
+      return ok([...rgb.map((c) => clamp(c, 0, 255)), clamp(a, 0, 1)]);
+    }
     if (name !== 'rgb' && name !== 'rgba') {
       const hint = KNOWN_UNSUPPORTED.includes(name)
         ? `${name}() is not supported in v1. Convert the token to hex or rgb(), or open an issue.`

package/src/config.mjs

@@ -131,14 +131,34 @@ function validateTreatments(treatments, errors) {
   }
 }
 
+function validateJudge(judge, errors) {
+  rejectUnknown(judge, ['checklist', 'shots', 'shotCommand', 'command', 'failOn'], 'judge', errors);
+  for (const key of ['checklist', 'command']) {
+    if (typeof judge[key] !== 'string' || !judge[key]) {
+      errors.push(`judge.${key} must be a non-empty string`);
+    }
+  }
+  if (judge.shotCommand !== undefined && (typeof judge.shotCommand !== 'string' || !judge.shotCommand)) {
+    errors.push('judge.shotCommand must be a non-empty string');
+  }
+  stringArray(judge.shots, 'judge.shots', errors);
+  if (judge.failOn !== undefined && judge.failOn !== 'never' && judge.failOn !== 'fail') {
+    errors.push(
+      `judge.failOn must be "never" or "fail", not ${JSON.stringify(judge.failOn)}. ` +
+        `It defaults to "never": a model's verdict is an opinion, so it does not gate a build ` +
+        `unless you say it should.`,
+    );
+  }
+}
+
 /** Validate a parsed config, returning a list of human-readable problems. */
 export function validate(config) {
   const errors = [];
   if (!isPlainObject(config)) return ['the config must be a JSON object'];
-  rejectUnknown(config, ['$schema', 'contrast', 'treatments'], 'the config', errors);
+  rejectUnknown(config, ['$schema', 'contrast', 'treatments', 'judge'], 'the config', errors);
 
-  if (config.contrast === undefined && config.treatments === undefined) {
-    errors.push('the config must define "contrast", "treatments", or both');
+  if (config.contrast === undefined && config.treatments === undefined && config.judge === undefined) {
+    errors.push('the config must define at least one of "contrast", "treatments" or "judge"');
   }
   if (config.contrast !== undefined) {
     if (isPlainObject(config.contrast)) validateContrast(config.contrast, errors);
@@ -148,6 +168,10 @@ export function validate(config) {
     if (isPlainObject(config.treatments)) validateTreatments(config.treatments, errors);
     else errors.push('treatments must be an object');
   }
+  if (config.judge !== undefined) {
+    if (isPlainObject(config.judge)) validateJudge(config.judge, errors);
+    else errors.push('judge must be an object');
+  }
   return errors;
 }
 

package/src/contrast.mjs

@@ -18,7 +18,7 @@
  */
 import { readFileSync } from 'node:fs';
 import { contrastRatio, isOpaque, parseColor } from './color.mjs';
-import { parseDeclarations, resolveScopes, resolveValue } from './css.mjs';
+import { parseDeclarations, resolveScopes, resolveValue, unmatchedScopes } from './css.mjs';
 import { expand, label } from './files.mjs';
 
 /** A token name, or a literal colour, resolved to rgba for one theme. */
@@ -62,6 +62,20 @@ export function runContrast(config, cwd) {
       continue;
     }
 
+    // A scope that selects nothing is not a smaller theme, it is a typo. The
+    // theme above still has tokens, so nothing else here would notice.
+    const dead = unmatchedScopes(decls, theme.scopes);
+    if (dead.length) {
+      for (const scope of dead) {
+        const shown = typeof scope === 'string' ? scope : JSON.stringify(scope);
+        problems.push(
+          `theme "${theme.name}": the scope ${shown} matched no declaration. ` +
+            `Every token it was meant to contribute is coming from another scope instead.`,
+        );
+      }
+      continue;
+    }
+
     for (const pair of pairs) {
       if (pair.themes && !pair.themes.includes(theme.name)) continue;
       const where = `${pair.fg} on ${pair.bg}`;

package/src/css.mjs

@@ -13,11 +13,31 @@
  * relies on `.a.b` beating `.b`, list the scopes in the order you want them
  * applied and the result is the one you asked for.
  *
- * Declarations inside an at-rule are ignored unless a scope opts into that
- * at-rule by name. Without that rule, a `@media (prefers-color-scheme: dark)`
- * block containing `:root` would silently overwrite the light theme, and the
- * light theme would be checked against colours it never paints.
+ * At-rules split into two kinds, and they are treated differently because
+ * they mean different things.
+ *
+ * A CONDITIONAL at-rule (`@media`, `@supports`, `@container`, `@scope`) only
+ * applies when its condition holds, so its declarations are ignored unless a
+ * scope opts into it by name. Without that, a
+ * `@media (prefers-color-scheme: dark)` block containing `:root` would
+ * overwrite the light theme, and light would be checked against colours it
+ * never paints.
+ *
+ * A GROUPING at-rule, `@layer` above all, always applies. It changes cascade
+ * priority, not whether the declarations exist. So it is transparent here: a
+ * `:root` inside `@layer tokens` resolves exactly as a top-level `:root`
+ * would. A scope can still name a layer to narrow to it, but nobody should
+ * have to write that just to see their own tokens.
+ *
+ * Layer order is not modelled. Within the scopes a theme lists, the last
+ * declaration still wins, same as everywhere else here.
+ */
+
+/**
+ * At-rules whose contents are conditional, and so must be opted into.
+ * Anything else wrapping a rule is grouping, and is looked straight through.
  */
+const CONDITIONAL = /^@(media|supports|container|scope|document)\b/;
 
 /** Blank out comments, keeping every offset and newline so lines stay true. */
 function blankComments(css) {
@@ -104,22 +124,42 @@ function selectorMatches(list, scope) {
  * The token table for one theme: a Map of `--name` to { value, selector }.
  * Scopes are applied in order, later winning.
  */
+/** The declarations one scope selects, in source order. */
+function declsForScope(decls, scope) {
+  const selector = typeof scope === 'string' ? scope : scope.selector;
+  const atRule = typeof scope === 'string' ? null : (scope.atRule ?? null);
+  return decls.filter((d) => {
+    if (!selectorMatches(d.selector, selector)) return false;
+    if (atRule === null) {
+      // Only a conditional wrapper hides a declaration by default. A grouping
+      // one like @layer does not.
+      return !d.atRules.some((a) => CONDITIONAL.test(a));
+    }
+    return d.atRules.some((a) => a.includes(atRule));
+  });
+}
+
 export function resolveScopes(decls, scopes) {
   const table = new Map();
   for (const scope of scopes) {
-    const selector = typeof scope === 'string' ? scope : scope.selector;
-    const atRule = typeof scope === 'string' ? null : (scope.atRule ?? null);
-    for (const d of decls) {
-      if (!selectorMatches(d.selector, selector)) continue;
-      if (atRule === null) {
-        if (d.atRules.length) continue;
-      } else if (!d.atRules.some((a) => a.includes(atRule))) continue;
-      table.set(d.prop, d);
-    }
+    for (const d of declsForScope(decls, scope)) table.set(d.prop, d);
   }
   return table;
 }
 
+/**
+ * The scopes in a theme that selected nothing at all.
+ *
+ * A theme can resolve plenty of tokens while one of its scopes is quietly
+ * dead: write `[data-theme="dark"]` when the stylesheet says
+ * `:root[data-theme="dark"]` and the base scope still fills the table, so the
+ * dark theme gets measured against the light values and reports a pass. The
+ * numbers look right, they are just the wrong theme's numbers.
+ */
+export function unmatchedScopes(decls, scopes) {
+  return scopes.filter((scope) => declsForScope(decls, scope).length === 0);
+}
+
 /**
  * Follow `var(--other)` indirection to a concrete value.
  *

package/src/index.mjs

@@ -4,6 +4,7 @@
  */
 export { runContrast } from './contrast.mjs';
 export { runTreatments } from './treatments.mjs';
+export { runJudge, buildPrompt, checklistLines, extractJson } from './judge.mjs';
 export { load, validate } from './config.mjs';
 export { toText, toJson, failed } from './report.mjs';
 export { parseColor, contrastRatio, composite, luminance } from './color.mjs';
@@ -12,10 +13,15 @@ export { openTags, classesOf } from './treatments.mjs';
 
 import { runContrast } from './contrast.mjs';
 import { runTreatments } from './treatments.mjs';
+import { runJudge } from './judge.mjs';
 
 /**
- * Run the checks a config asks for. `only` narrows to one check by name.
- * Returns the raw results; formatting and exit codes are the caller's.
+ * Run the deterministic checks a config asks for. `only` narrows to one by
+ * name. Returns the raw results; formatting and exit codes are the caller's.
+ *
+ * The judge is deliberately not here. It runs a model, so it belongs behind
+ * its own subcommand rather than inside the run whose exit code people wire
+ * into CI.
  */
 export function run(config, cwd, { only = null } = {}) {
   const results = [];
@@ -27,3 +33,8 @@ export function run(config, cwd, { only = null } = {}) {
   }
   return results;
 }
+
+/** Run the judge. Separate from `run` on purpose: see the note above. */
+export function judge(config, cwd) {
+  return [runJudge(config.judge, cwd)];
+}

package/src/judge.mjs

@@ -0,0 +1,237 @@
+/**
+ * The fresh-eyes judge.
+ *
+ * Everything else in this tool measures. This part asks the question a
+ * measurement cannot answer: not whether the screen is correct, but whether it
+ * is any good. That question cannot be put to whoever just built the thing.
+ * The context that made the choices is the worst-placed context to find them
+ * wanting, because the reasoning that justified each one is still sitting
+ * there ready to justify it again.
+ *
+ * So the judge is a separate process that sees the screenshots and the
+ * checklist and nothing else. No summary of what changed, no statement of
+ * intent, no prior conversation. It should see what a stranger sees.
+ *
+ * ── What ships here and what does not ───────────────────────────────────
+ *
+ * This module ships the FRAMING: fresh context, do not lead the judge, answer
+ * every line, prefer unsure to a guess, quote what you actually see. That part
+ * is method and it is portable.
+ *
+ * The CHECKLIST is yours. taste-check contains no design rules and never will,
+ * because a shipped checklist is just somebody else's taste wearing the
+ * authority of a tool.
+ *
+ * ── Where the determinism line falls ────────────────────────────────────
+ *
+ * A model's verdict is an opinion and cannot gate a build by default, so a
+ * "fail" prints as a NOTE and the command still exits 0 unless failOn says
+ * otherwise.
+ *
+ * Whether the judge RAN is not an opinion. No screenshots, a command that
+ * exited non-zero, output that was not JSON, a reply that skipped a checklist
+ * line or invented one: each of those is a fact, each exits 1 regardless of
+ * failOn. Without that split, "the judge did not run" and "the judge found
+ * nothing" produce the same green output, which is the failure this whole
+ * tool exists to prevent, one level up.
+ */
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { expand, label } from './files.mjs';
+
+/**
+ * The instructions wrapped around the user's checklist.
+ *
+ * Every line here is about how to look, never about what to value. If you find
+ * yourself wanting to add a rule about spacing or colour or type, it belongs
+ * in a checklist file, not in this constant.
+ */
+const FRAMING_HEAD = `You are looking at these images for the first time.
+
+You have not been told what changed, what it is for, or what the author was
+trying to do, and none of that is coming. Judge only what is in front of you,
+the way someone landing on this screen cold would see it.
+
+Answer every line of the checklist below. For each one reply with exactly one
+verdict: "pass", "fail", or "unsure".
+
+Prefer "unsure" to a guess. An honest "I cannot tell from this image" is more
+useful than a confident answer that happens to be wrong, and you are not being
+asked to be agreeable. If a line does not apply to what you can see, that is
+"unsure", not "pass".
+
+For anything that is not a pass, name the specific thing you are looking at:
+which element, where on the screen, and what about it. A general impression is
+not enough to act on.
+
+`;
+
+const FRAMING_TAIL = `Reply with JSON and nothing else, in this shape:
+
+{"findings":[{"line":"<the checklist line, copied exactly>","verdict":"pass|fail|unsure","why":"<one or two sentences>"}]}
+
+Return exactly one finding per checklist line, with "line" copied verbatim.
+
+CHECKLIST:
+`;
+
+/**
+ * The lines a verdict is expected for: list items only.
+ *
+ * A checklist file is a document, not a list of strings. It will have a
+ * heading, and a paragraph saying what it is for, and probably a note to
+ * whoever edits it next. Treating every non-heading line as something to
+ * judge turns that prose into checklist items, and the judge then dutifully
+ * returns a verdict on your explanatory paragraph.
+ */
+export function checklistLines(text) {
+  return text
+    .split('\n')
+    .filter((l) => /^\s*(?:[-*+]|\d+[.)])\s+\S/.test(l))
+    .map((l) => l.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, '').trim());
+}
+
+/**
+ * The prompt handed to the judge: framing, the images, then the checklist.
+ *
+ * The image paths go in the prompt as well as on the command line, because
+ * the two families of tool want them in different places. Some accept image
+ * files as arguments; others read the prompt and open what it names. Naming
+ * them both ways costs a line and means the contract does not quietly exclude
+ * half the tools someone might reach for.
+ */
+export function buildPrompt(checklist, images = []) {
+  const shots = images.length
+    ? `IMAGES (open each one before answering):\n${images.map((i) => `- ${i}`).join('\n')}\n\n`
+    : '';
+  return `${FRAMING_HEAD}${shots}${FRAMING_TAIL}${checklist.map((l) => `- ${l}`).join('\n')}\n`;
+}
+
+/**
+ * Run a configured command from the config file's own directory, because
+ * every other path in a config resolves that way and a command that did not
+ * would be a trap: `node shots.mjs` would mean something different depending
+ * on where you happened to be standing.
+ */
+function runCommand(command, args, input, cwd) {
+  const [bin, ...rest] = command.split(/\s+/).filter(Boolean);
+  try {
+    const stdout = execFileSync(bin, [...rest, ...args], {
+      cwd,
+      input,
+      encoding: 'utf8',
+      maxBuffer: 32 * 1024 * 1024,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return { ok: true, stdout };
+  } catch (error) {
+    const detail = (error.stderr || error.message || '').toString().trim().split('\n')[0];
+    return { ok: false, reason: `\`${command}\` failed: ${detail}` };
+  }
+}
+
+/** Pull the JSON object out of a reply that may be fenced or padded with prose. */
+export function extractJson(stdout) {
+  const fenced = stdout.match(/```(?:json)?\s*([\s\S]*?)```/);
+  const candidate = fenced ? fenced[1] : stdout;
+  const start = candidate.indexOf('{');
+  const end = candidate.lastIndexOf('}');
+  if (start === -1 || end <= start) return { ok: false, reason: 'no JSON object in the reply' };
+  try {
+    return { ok: true, value: JSON.parse(candidate.slice(start, end + 1)) };
+  } catch (error) {
+    return { ok: false, reason: `the reply was not valid JSON: ${error.message}` };
+  }
+}
+
+const VERDICTS = new Set(['pass', 'fail', 'unsure']);
+
+export function runJudge(config, cwd) {
+  const findings = [];
+  const problems = [];
+  const { checklist: checklistPath, shots = [], shotCommand, command, failOn = 'never' } = config;
+
+  if (shotCommand) {
+    const made = runCommand(shotCommand, [], '', cwd);
+    if (!made.ok) {
+      problems.push(made.reason);
+      return { name: 'judge', findings, problems, failOn, summary: '' };
+    }
+  }
+
+  const images = expand(shots, cwd);
+  if (!images.length) {
+    problems.push(
+      `no screenshots matched ${shots.map((s) => `"${s}"`).join(', ')}. ` +
+        `A judge with nothing to look at cannot fail, so it does not get to pass either.`,
+    );
+    return { name: 'judge', findings, problems, failOn, summary: '' };
+  }
+
+  let lines;
+  try {
+    lines = checklistLines(readFileSync(resolve(cwd, checklistPath), 'utf8'));
+  } catch {
+    problems.push(`cannot read the checklist at ${checklistPath}`);
+    return { name: 'judge', findings, problems, failOn, summary: '' };
+  }
+  if (!lines.length) {
+    problems.push(
+      `${checklistPath} has no checklist lines in it. Lines to judge are list ` +
+        `items ("- ..." or "1. ..."); everything else is treated as prose.`,
+    );
+    return { name: 'judge', findings, problems, failOn, summary: '' };
+  }
+
+  const reply = runCommand(command, images, buildPrompt(lines, images.map((i) => label(i, cwd))), cwd);
+  if (!reply.ok) {
+    problems.push(reply.reason);
+    return { name: 'judge', findings, problems, failOn, summary: '' };
+  }
+
+  const parsed = extractJson(reply.stdout);
+  if (!parsed.ok) {
+    problems.push(`${parsed.reason}. The judge must reply with the documented JSON shape.`);
+    return { name: 'judge', findings, problems, failOn, summary: '' };
+  }
+  if (!Array.isArray(parsed.value.findings)) {
+    problems.push('the reply has no "findings" array');
+    return { name: 'judge', findings, problems, failOn, summary: '' };
+  }
+
+  // Cross-check both directions. A judge that quietly drops the hardest line
+  // is the failure mode to guard: the remaining verdicts all say pass, and
+  // the line nobody answered is the one that mattered.
+  const wanted = new Set(lines);
+  const answered = new Set();
+  for (const f of parsed.value.findings) {
+    if (!f || typeof f.line !== 'string' || !VERDICTS.has(f.verdict)) {
+      problems.push(`a finding is malformed: ${JSON.stringify(f)}`);
+      continue;
+    }
+    if (!wanted.has(f.line)) {
+      problems.push(`the judge answered a line that is not in the checklist: "${f.line}"`);
+      continue;
+    }
+    if (answered.has(f.line)) {
+      problems.push(`the judge answered "${f.line}" more than once`);
+      continue;
+    }
+    answered.add(f.line);
+    findings.push({ line: f.line, verdict: f.verdict, why: (f.why ?? '').trim() });
+  }
+  for (const line of lines) {
+    if (!answered.has(line)) problems.push(`the judge did not answer "${line}"`);
+  }
+
+  return {
+    name: 'judge',
+    findings,
+    problems,
+    failOn,
+    summary: `${lines.length} ${lines.length === 1 ? 'line' : 'lines'} against ${images.length} ${
+      images.length === 1 ? 'screenshot' : 'screenshots'
+    } (${images.map((i) => label(i, cwd)).join(', ')})`,
+  };
+}

package/src/report.mjs

@@ -33,17 +33,49 @@ function treatmentLines(result) {
   ];
 }
 
-export const linesFor = (result) =>
-  result.name === 'contrast' ? contrastLines(result) : treatmentLines(result);
+/**
+ * The judge's verdicts are opinions, so a "fail" is a note unless the config
+ * opted into blocking. Its problems are facts about whether it ran at all,
+ * and those stay errors either way.
+ */
+function judgeLines(result) {
+  const level = result.failOn === 'fail' ? 'fail' : 'note';
+  return [
+    ...result.findings
+      .filter((f) => f.verdict !== 'pass')
+      .map((f) => ({
+        level: f.verdict === 'fail' ? level : 'note',
+        text: `${f.verdict.padEnd(6)} ${f.line}${f.why ? `: ${f.why}` : ''}`,
+      })),
+    ...result.problems.map((text) => ({ level: 'error', text })),
+  ];
+}
+
+export const linesFor = (result) => {
+  if (result.name === 'contrast') return contrastLines(result);
+  if (result.name === 'judge') return judgeLines(result);
+  return treatmentLines(result);
+};
 
-const MARK = { ok: '  ok  ', ' fail': 'FAIL  ', fail: 'FAIL  ', error: 'ERROR ' };
+const MARK = { ok: '  ok  ', fail: 'FAIL  ', error: 'ERROR ', note: 'NOTE  ' };
 
 export function toText(results) {
   const out = [];
   for (const result of results) {
     const lines = linesFor(result);
-    const bad = lines.filter((l) => l.level !== 'ok');
-    if (!bad.length) {
+    const blocking = lines.filter((l) => l.level !== 'ok' && l.level !== 'note');
+    const notes = lines.filter((l) => l.level === 'note');
+
+    // Notes are worth printing and not worth failing over, so a run with only
+    // notes gets its own heading. Calling it FAILED would train people to
+    // ignore the word.
+    if (!blocking.length && notes.length) {
+      out.push(`${result.name} ok, ${result.summary}, ${notes.length} to read`);
+      for (const l of notes) out.push(`  ${MARK[l.level]}${l.text}`);
+      out.push('');
+      continue;
+    }
+    if (!blocking.length) {
       out.push(`${result.name} ok, ${result.summary}`);
       // A clean contrast run still shows its margins. Nothing else in the
       // report tells you which pair is one nudge away from failing.
@@ -58,8 +90,9 @@ export function toText(results) {
   return out.join('\n').trimEnd();
 }
 
+/** A note is something to read, not something to block on. */
 export const failed = (results) =>
-  results.some((r) => linesFor(r).some((l) => l.level !== 'ok'));
+  results.some((r) => linesFor(r).some((l) => l.level !== 'ok' && l.level !== 'note'));
 
 export function toJson(results) {
   return JSON.stringify(
@@ -68,7 +101,7 @@ export function toJson(results) {
       checks: results.map((r) => ({
         name: r.name,
         summary: r.summary,
-        ok: !linesFor(r).some((l) => l.level !== 'ok'),
+        ok: !linesFor(r).some((l) => l.level !== 'ok' && l.level !== 'note'),
         samples: r.samples ?? [],
         failures: r.failures ?? [],
         problems: r.problems ?? [],