@josueavalosjim/taste-check 0.9.0 → 0.11.0

package/README.md

@@ -3,9 +3,9 @@
 Design review in CI, with a line down the middle of it.
 
 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, either from your token file or from a page it renders in a
-real browser.
+been tokens, tokens that were never real, class names nobody approved.
+taste-check measures those and fails your build on them, either from your token
+file or from a page it renders in a real browser.
 
 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
@@ -32,6 +32,9 @@ contrast ok, 10 pairs across 2 themes
 treatments FAILED
   FAIL  src/Promo.jsx:7 class "promo-huge" on <div> is not approved
   FAIL  src/Promo.jsx:8 inline value "#ff0055" on <a> is a one-off. Use a token, or add it to approvedValues.
+
+tokens FAILED
+  FAIL  src/Promo.jsx:8 "--color-primary-500" is referenced here but declared in no token file. Check the name, or add it to allow.
 ```
 
 ```bash
@@ -63,15 +66,18 @@ 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.
+It also enforces no rule it wrote. Not a palette, not a class list, not a
+contrast floor. It will scaffold you a starter checklist, and that file lands
+in your repo: what runs is the copy you edited, never its own.
 
 ## What counts as a failure
 
 Each of these exits 1 rather than passing quietly:
 
 - a pair naming a token that does not exist
+- markup referencing a token that is declared nowhere
 - a file pattern matching no files
+- a token file that declares no custom properties at all
 - 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
@@ -181,6 +187,55 @@ 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 tokens check
+
+Give it the stylesheet that declares your tokens and the markup that uses them.
+It reports every `var(--x)` in your markup where `--x` is declared nowhere.
+
+```json
+{
+  "tokens": {
+    "declaredIn": ["src/styles/tokens.css"],
+    "files": ["src/**/*.jsx"],
+    "allow": ["--scroll-progress"],
+    "allowPrefixes": ["--radix-"]
+  }
+}
+```
+
+The failure it is built for is a token name that was never real:
+`var(--color-primary-500)` in a system that says `--brand-action-bg`. A name
+like that is not a typo. It is what gets written when the code is produced
+without the token file open, which is most of what a model does, and it looks
+correct in review because it looks like a token.
+
+**It scans markup, not stylesheets, and that is deliberate.** See
+[where it sits](#where-it-sits-next-to-other-tools). Stylelint already owns the
+CSS side and does it better.
+
+For markup the scan is the whole file rather than the tags, because `var(--`
+means one thing everywhere it appears. So a reference in an object declared
+above the `return`, in a styled-components template, or in a constant in
+another module is found, and nesting comes free: both names in
+`var(--a, var(--b))` are checked, not only the outer one.
+
+`allow` and `allowPrefixes` are the escape hatch, and you will need them. A
+custom property set from JavaScript with `setProperty`, or one owned by a
+library's stylesheet, is legitimately absent from your token file.
+
+Two things it does not treat as failures. A bare `--x` written where you meant
+`var(--x)` is stylelint's `custom-property-no-missing-var-function`, not this.
+And a run that finds no references at all is reported in the summary rather
+than failed, because a codebase that keeps its styling in stylesheets has none
+and is not broken:
+
+```
+tokens ok, 1 token file, 84 declared, 41 files scanned, 0 references
+```
+
+If that zero is a surprise, your `files` pattern is pointed at the wrong tree.
+A pattern matching no files at all is a failure, as everywhere else here.
+
 ## Measuring the rendered page
 
 The contrast check above reads your token file, which tells you what a colour
@@ -284,11 +339,13 @@ 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.
+The checklist is yours, and there is a test asserting the framing mentions no
+design vocabulary at all, because a rule that arrives at the moment of judgment
+carries the tool's authority rather than its author's. Checklist lines are list
+items in your file; a heading or a paragraph is prose and is not judged.
+
+Starting from nothing is its own problem, so there is a scaffold and a linter
+for the lines you write. Both are in the next section.
 
 ### Letting an agent carry the call
 
@@ -336,6 +393,48 @@ exits 1 whatever `failOn` says:
 Without that split, "the judge did not run" and "the judge found nothing" print
 the same thing.
 
+## Starting a checklist
+
+An empty file is the hardest part of the judge, so:
+
+```bash
+taste-check checklist --new
+```
+
+It writes a starter into your repo. Six lines, and every one is about whether
+the screen is broken rather than whether it is good, because that is the only
+kind of line that is not somebody's taste. It refuses to overwrite a file that
+exists, since the moment it lands it is yours.
+
+That is a scaffold and not a default, and the difference is the whole reason it
+is allowed to exist here. A default judges every user who never opened the file
+against opinions they did not choose. A scaffold is a file you edited and
+committed, and taste-check never reads its own copy. eslint is the same shape:
+it ships rules and no default configuration, and `--init` writes you one.
+
+```bash
+taste-check checklist --lint
+```
+
+This checks your lines and never their content. It has no opinion about what
+you ask for, only about whether asking it produces a verdict:
+
+```
+checklist, 3 to look at
+  unfalsifiable   design-checklist.md:12  "Does it feel premium and modern"
+                  "premium", "modern", "feel" describes a feeling rather than
+                  something visible. A judge answers unsure, every run.
+  not-in-a-still  design-checklist.md:13  "Is the hover animation smooth"
+                  "animation", "hover" cannot be seen in a screenshot.
+  measurable      design-checklist.md:14  "Body copy hits at least 4.5:1"
+                  this asks for a number. Put it in a contrast pair instead.
+```
+
+It also flags a line asking two things at once, since one verdict cannot answer
+both. "The primary action reads as the primary action" passes: it is an opinion,
+a strong one, and none of the linter's business, because it can be settled by
+looking.
+
 ## Config
 
 Point your editor at `schema/config.schema.json` for completion and inline
@@ -371,6 +470,10 @@ it is the way it is.
 | `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. |
+| `tokens.declaredIn` | Stylesheets declaring the tokens. Every custom property in them counts, in any scope. |
+| `tokens.files` | Markup to scan for `var()` references. |
+| `tokens.allow` | Names that need no declaration, for ones set from JavaScript. Must start with `--`. |
+| `tokens.allowPrefixes` | Name prefixes that are always allowed, for a family a library owns. |
 | `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. |
@@ -388,7 +491,7 @@ taste-check runtime [options] Measure contrast on a rendered page
 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
+      --only <name>     Run one check: contrast, treatments or tokens
       --format <kind>   text (default), json, or sarif
       --json            Alias for --format json
       --version         Print the version
@@ -448,6 +551,16 @@ tool, run axe.
 **stylelint, eslint.** General code quality, with an enormous rule ecosystem.
 Nothing here replaces them.
 
+**stylelint for tokens in CSS specifically.** Its core
+`no-unknown-custom-properties` reports a `var()` naming a custom property
+nothing declares, and its `referenceFiles` option covers the case that matters,
+where the tokens live in one file and the uses live in another. That is the
+same check taste-check runs, done first-party, so run stylelint on your
+stylesheets. taste-check only scans markup, where stylelint does not go: its
+CSS-in-JS syntax is deprecated, and a `style={{ color: open ? 'var(--a)' :
+'var(--b)' }}` prop is a JavaScript object literal that no CSS parser reads at
+all.
+
 **@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
@@ -455,8 +568,9 @@ 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.
+opinions supplied, take theirs, and they are good. taste-check scaffolds six
+lines about whether a screen is broken and expects the rest to be yours, which
+is more work and a different bargain.
 
 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
@@ -490,6 +604,11 @@ within one channel unit.
 them. If your tokens rely on `.a.b` beating `.b`, list the scopes in the order
 you want.
 
+**It does not lint your stylesheets.** The tokens check reads your CSS to learn
+what is declared and then never looks at it again. A `var()` in a `.css` file
+naming nothing is not reported here. That is stylelint's
+`no-unknown-custom-properties`, named above.
+
 **Component indirection is invisible.** Classes applied by a helper
 function, a `clsx` call importing names from elsewhere, or CSS-in-JS are
 invisible to it.
@@ -518,10 +637,11 @@ 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
+171 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
-hole, a file pattern pointed at nothing.
+hole, a fabricated token hidden in a ternary, a file pattern pointed at
+nothing.
 
 ## License
 

package/bin/taste-check.mjs

@@ -7,10 +7,13 @@
  * exist, or scopes a pair to a theme that is not defined is a failure here,
  * not a quiet skip.
  */
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { load } from '../src/config.mjs';
+import { STARTER, lintChecklist } from '../src/checklist.mjs';
+import { checklistEntries } from '../src/judge.mjs';
 import { gradeVerdict, judge, prepareJudge, run, runtime } from '../src/index.mjs';
 import { failed, toJson, toText } from '../src/report.mjs';
 import { toSarif } from '../src/sarif.mjs';
@@ -20,10 +23,15 @@ const USAGE = `taste-check
   taste-check [options]         Run the deterministic checks over your files
   taste-check runtime [options] Measure contrast on a rendered page
   taste-check judge [options]   Ask a fresh-eyes judge about your screenshots
+  taste-check checklist --new   Write a starter checklist you then own
+  taste-check checklist --lint  Check your checklist lines can be answered
 
 Options:
   -c, --config <path>   Config file (default: tastecheck.config.json)
-      --only <name>     Run one check: contrast or treatments
+      --only <name>     Run one check: contrast, treatments or tokens
+      --new [path]      checklist only: scaffold a starter, refusing to
+                        overwrite one that exists
+      --lint            checklist only: report lines a judge cannot answer
       --emit            judge only: print the prompt and stop, for an agent
                         to carry to a model itself
       --verdict <path>  judge only: grade a reply from a file, or - for stdin
@@ -48,6 +56,16 @@ is already up. It measures what is actually painted, compositing every
 background layer behind an element rather than stopping at the first opaque
 one, and it can put the page into a state first.
 
+checklist --new scaffolds; it does not default. The file it writes is yours,
+and taste-check never reads its own copy of it. The six lines in it are about
+whether a screen is broken rather than whether it is good, because that is the
+only kind of line that is not somebody's taste.
+
+checklist --lint is about the form of your lines and never their content. It
+reports a line a judge will answer "unsure" to every run, a line asking two
+things at once, a line about something a still image cannot show, and a line
+asking for a number that belongs in a contrast pair instead.
+
 An agent can carry the model call instead of a shell command. --emit prints
 the prompt and the images; the agent asks a fresh context and pipes the JSON
 back to --verdict -, which checks it against the checklist the same way. Run
@@ -68,10 +86,12 @@ function parseArgs(argv) {
     emit: false,
     verdict: null,
     skill: false,
+    lint: false,
+    scaffold: null,
   };
   // One positional, and only in first position, so a stray argument is an
   // error rather than something silently ignored.
-  if (argv[0] === 'judge' || argv[0] === 'runtime') {
+  if (argv[0] === 'judge' || argv[0] === 'runtime' || argv[0] === 'checklist') {
     options.command = argv[0];
     argv = argv.slice(1);
   }
@@ -92,11 +112,16 @@ function parseArgs(argv) {
     else if (arg === '-c' || arg === '--config') options.config = next();
     else if (arg === '--only') {
       options.only = next();
-      if (options.only !== 'contrast' && options.only !== 'treatments') {
-        throw new Error(`--only takes "contrast" or "treatments", not "${options.only}"`);
+      if (!['contrast', 'treatments', 'tokens'].includes(options.only)) {
+        throw new Error(`--only takes "contrast", "treatments" or "tokens", not "${options.only}"`);
       }
     } else if (arg === '--json') options.format = 'json';
-    else if (arg === '--emit') options.emit = true;
+    else if (arg === '--lint') options.lint = true;
+    else if (arg === '--new') {
+      // The path is optional, so peek rather than demanding a value.
+      const value = argv[i + 1];
+      options.scaffold = value !== undefined && !value.startsWith('-') ? (i += 1, value) : true;
+    } else if (arg === '--emit') options.emit = true;
     else if (arg === '--skill') options.skill = true;
     else if (arg === '--verdict') options.verdict = next();
     else if (arg === '--format') {
@@ -138,6 +163,26 @@ if (options.skill) {
   process.exit(0);
 }
 
+// checklist --new is the one command that has to work before a config exists,
+// because not having anything yet is the situation it is for.
+if (options.command === 'checklist' && options.scaffold) {
+  const named = typeof options.scaffold === 'string' ? options.scaffold : null;
+  const fromConfig = (() => {
+    const loadedForPath = load(options.config);
+    return loadedForPath.ok ? loadedForPath.config.judge?.checklist : null;
+  })();
+  const target = resolve(named ?? fromConfig ?? 'design-checklist.md');
+  if (existsSync(target)) {
+    die(`${target} already exists. It is yours now, so this will not overwrite it.`);
+  }
+  writeFileSync(target, STARTER);
+  const lines = checklistEntries(STARTER).length;
+  console.log(`wrote ${target}`);
+  console.log(`${lines} lines, all of them about whether a screen is broken. The ones worth`);
+  console.log('having are the ones you add. Run taste-check checklist --lint after editing.');
+  process.exit(0);
+}
+
 for (const flag of ['emit', 'verdict']) {
   if (options[flag] && options.command !== 'judge') {
     die(`--${flag} applies to \`taste-check judge\`, not to ${options.command}`);
@@ -155,11 +200,42 @@ if (!loaded.ok) {
 if (options.command !== 'check' && options.only) {
   die(`--only applies to the deterministic checks, not to ${options.command}`);
 }
+if (options.lint && options.command !== 'checklist') {
+  die('--lint applies to `taste-check checklist`, not to ' + options.command);
+}
 
-if (options.command !== 'check' && !loaded.config[options.command]) {
+// checklist is the exception: its file lives under judge.checklist rather than
+// in a block of its own, and it says so itself below.
+if (options.command !== 'check' && options.command !== 'checklist' && !loaded.config[options.command]) {
   die(`${options.config} defines no "${options.command}" block.`);
 }
 
+if (options.command === 'checklist') {
+  if (!options.lint) die('taste-check checklist takes --new or --lint');
+  const path = loaded.config.judge?.checklist;
+  if (!path) die(`${options.config} defines no judge.checklist to lint.`);
+  let entries;
+  try {
+    entries = checklistEntries(readFileSync(resolve(loaded.dir, path), 'utf8'));
+  } catch {
+    die(`cannot read the checklist at ${path}`);
+  }
+  if (!entries.length) {
+    die(`${path} has no checklist lines in it. Lines are list items ("- ..." or "1. ...").`);
+  }
+  const findings = lintChecklist(entries);
+  if (!findings.length) {
+    console.log(`checklist ok, ${entries.length} ${entries.length === 1 ? 'line' : 'lines'} a judge can answer`);
+    process.exit(0);
+  }
+  console.log(`checklist, ${findings.length} to look at`);
+  for (const f of findings) {
+    console.log(`  ${f.kind.padEnd(16)}${path}:${f.line}  ${JSON.stringify(f.text)}`);
+    console.log(`  ${' '.repeat(16)}${f.detail}`);
+  }
+  process.exit(1);
+}
+
 // --emit stops before any model is involved, so it has no findings to report
 // and no exit code to earn. It still refuses to hand back a prompt when the
 // screenshots or the checklist are missing.
@@ -192,7 +268,7 @@ else if (options.command === 'runtime') results = await runtime(loaded.config, l
 else results = 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.`);
+  die(`nothing to run. ${options.config} defines no ${options.only ?? 'contrast, treatments or tokens'} check.`);
 }
 
 if (options.format === 'sarif') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josueavalosjim/taste-check",
-  "version": "0.9.0",
+  "version": "0.11.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

@@ -17,6 +17,11 @@
         "treatments"
       ]
     },
+    {
+      "required": [
+        "tokens"
+      ]
+    },
     {
       "required": [
         "runtime"
@@ -260,6 +265,62 @@
         }
       }
     },
+    "tokens": {
+      "type": "object",
+      "description": "Custom properties referenced by var() in markup, against the tokens the system declares.",
+      "additionalProperties": false,
+      "required": [
+        "declaredIn",
+        "files"
+      ],
+      "properties": {
+        "declaredIn": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Stylesheets that declare the tokens. Every custom property declared anywhere in them counts, in any scope or at-rule.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "files": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Markup to scan for var() references. A pattern matching nothing is a failure, never a clean run.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "allow": {
+          "type": "array",
+          "description": "Custom property names that are fine to reference without being declared, for ones set from JavaScript or by a third-party stylesheet.",
+          "items": {
+            "type": "string",
+            "pattern": "^--"
+          }
+        },
+        "allowPrefixes": {
+          "type": "array",
+          "description": "Name prefixes that are always allowed, for a whole family a library owns.",
+          "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."
+        }
+      }
+    },
     "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.",

package/skills/taste-check-judge/SKILL.md

@@ -78,5 +78,11 @@ old screenshots is not a verdict on the new ones.
 ## What this skill does not contain
 
 Any design rules. The checklist is the user's file, named in their config, and
-if it is empty then this reports nothing and that is correct. A checklist that
-arrived with a tool is somebody else's taste wearing the tool's authority.
+if it is empty then this reports nothing and that is correct.
+
+`taste-check checklist --new` will scaffold a starter into their repo, six
+lines about whether a screen is broken rather than whether it is good. Once it
+is written it is theirs, and what gets judged is whatever they edited it into.
+Do not add lines to it yourself, and do not judge against a rule that is not in
+it. A rule that arrives at the moment of judgment, from the tool or from you,
+is somebody else's taste wearing borrowed authority.

package/src/checklist.mjs

@@ -0,0 +1,147 @@
+/**
+ * Starting a checklist, and checking that the lines in one can be answered.
+ *
+ * Neither of these says what to value. The starter contains only lines about
+ * whether a screen is broken, which is not taste, and the linter is about the
+ * form of a line rather than its content.
+ *
+ * ── Why a starter at all, given this ships no design rules ──────────────
+ *
+ * There is a real difference between a tool that defaults to a checklist and a
+ * tool that writes one into your repo once. A default arrives with the tool's
+ * authority at the moment of judgment: every user who never opened the file is
+ * being judged against opinions they did not choose. A scaffold is a file you
+ * own, edited and committed by you, and what runs is yours. The tool never
+ * reads its own copy.
+ *
+ * eslint is the precedent. It ships rules and no default configuration, and
+ * `--init` writes you one. Nobody thinks eslint has opinions about their code
+ * until they enable some.
+ */
+
+/**
+ * The starter.
+ *
+ * Six lines, and every one of them is about whether the screen is broken
+ * rather than whether it is good. That is deliberate and the header says so:
+ * these are the ones that are not anybody's taste, which means the lines worth
+ * having are the ones you add.
+ */
+export const STARTER = `# Design checklist
+
+Lines here are judged one at a time against a screenshot, and each gets one
+verdict: pass, fail, or unsure.
+
+Everything below is about whether the screen is broken. None of it is taste,
+which is the only reason it could ship inside a tool. The lines worth having
+are the ones you add, and they should be the specific things your work gets
+wrong, in your words.
+
+Two things make a line answerable. It has to be settleable by looking, so
+"nothing is cut off" works where "looks expensive" comes back unsure every
+run. And it has to ask one thing, because a line joining two claims cannot be
+answered by a single verdict.
+
+Anything you can measure belongs in a contrast pair or a runtime target
+instead, where the answer is a number rather than an opinion.
+
+Note that only list items are judged. Everything above this is prose and is
+ignored, so there is room here to write down why these lines and not others.
+
+Run \`taste-check checklist --lint\` after editing.
+
+- Nothing important is cut off at an edge of the frame
+- Every piece of text is legible against what is directly behind it
+- Nothing overlaps something it was not meant to overlap
+- Nothing is obviously misaligned with the things beside it
+- Nothing is still showing a loading, empty, or placeholder state
+- Nothing appears twice that was meant to appear once
+`;
+
+/** Words that describe a feeling rather than something visible in an image. */
+const UNFALSIFIABLE = [
+  'premium', 'modern', 'clean', 'professional', 'polished', 'elegant',
+  'beautiful', 'delightful', 'intuitive', 'slick', 'crisp', 'tasteful',
+  'cohesive', 'harmonious', 'balanced', 'pleasing', 'appealing', 'nice',
+  'good', 'bad', 'ugly', 'feel', 'feels', 'vibe', 'aesthetic',
+];
+
+/** Things a still image cannot show. */
+const NOT_IN_A_STILL = [
+  'animation', 'animate', 'transition', 'hover', 'scroll', 'scrolling',
+  'load time', 'performance', 'sound', 'audio', 'click', 'tap', 'drag',
+  'keyboard', 'focus ring', 'video plays',
+];
+
+const MEASURABLE = /\b\d+(\.\d+)?\s*(:\s*1|px|rem|em|%|pt)\b|\bcontrast ratio\b|\b\d+:\d+\b/i;
+const COMPOUND = /\b(and|or)\b/i;
+
+/**
+ * Check a single line for whether a judge could answer it.
+ *
+ * Never about content. A line can ask for anything at all; these findings are
+ * about whether asking it produces a verdict or a shrug.
+ */
+export function lintLine(text) {
+  const findings = [];
+  const lower = text.toLowerCase();
+  const words = text.trim().split(/\s+/);
+
+  const vague = UNFALSIFIABLE.filter((w) => new RegExp(`\\b${w}\\b`, 'i').test(lower));
+  if (vague.length) {
+    findings.push({
+      kind: 'unfalsifiable',
+      detail:
+        `"${vague.join('", "')}" describes a feeling rather than something visible. ` +
+        `A judge answers unsure, every run.`,
+    });
+  }
+
+  const unseen = NOT_IN_A_STILL.filter((w) => lower.includes(w));
+  if (unseen.length) {
+    findings.push({
+      kind: 'not-in-a-still',
+      detail: `"${unseen.join('", "')}" cannot be seen in a screenshot. The judge only gets images.`,
+    });
+  }
+
+  if (MEASURABLE.test(text)) {
+    findings.push({
+      kind: 'measurable',
+      detail:
+        'this asks for a number. Put it in a contrast pair or a runtime target, ' +
+        'where the answer is measured rather than judged.',
+    });
+  }
+
+  // Only compound when both halves look like claims, so "black and white" or
+  // "cut off at the top or bottom" are left alone.
+  if (COMPOUND.test(text)) {
+    // Three words a side, so "black and white" and "the top or bottom" are
+    // left alone while two real claims are caught.
+    const halves = text.split(/\b(?:and|or)\b/i).map((h) => h.trim().split(/\s+/).filter(Boolean).length);
+    if (halves.length > 1 && halves.every((n) => n >= 3)) {
+      findings.push({
+        kind: 'compound',
+        detail: 'two claims in one line. One verdict cannot answer both, so split it.',
+      });
+    }
+  }
+
+  if (words.length < 4) {
+    findings.push({ kind: 'too-short', detail: 'too short to say what is being asked.' });
+  }
+
+  return findings;
+}
+
+/** Lint every line of a checklist, keeping the line numbers. */
+export function lintChecklist(entries) {
+  const findings = [];
+  for (const entry of entries) {
+    for (const finding of lintLine(entry.text)) {
+      findings.push({ ...finding, line: entry.line, text: entry.text });
+    }
+  }
+  return findings;
+}

package/src/config.mjs

@@ -151,6 +151,19 @@ function validateTreatments(treatments, errors) {
   }
 }
 
+function validateTokens(tokens, errors) {
+  rejectUnknown(tokens, ['declaredIn', 'files', 'allow', 'allowPrefixes'], 'tokens', errors);
+  stringArray(tokens.declaredIn, 'tokens.declaredIn', errors);
+  stringArray(tokens.files, 'tokens.files', errors);
+  stringArray(tokens.allow, 'tokens.allow', errors, { required: false });
+  stringArray(tokens.allowPrefixes, 'tokens.allowPrefixes', errors, { required: false });
+  for (const name of tokens.allow ?? []) {
+    if (typeof name === 'string' && !name.startsWith('--')) {
+      errors.push(`tokens.allow has "${name}", which is not a custom property name. Names start with "--".`);
+    }
+  }
+}
+
 function validateJudge(judge, errors) {
   rejectUnknown(judge, ['checklist', 'shots', 'shotCommand', 'command', 'failOn'], 'judge', errors);
   if (typeof judge.checklist !== 'string' || !judge.checklist) {
@@ -246,15 +259,18 @@ function validateRuntime(runtime, errors) {
 export function validate(config) {
   const errors = [];
   if (!isPlainObject(config)) return ['the config must be a JSON object'];
-  rejectUnknown(config, ['$schema', 'contrast', 'treatments', 'judge', 'runtime'], 'the config', errors);
+  rejectUnknown(config, ['$schema', 'contrast', 'treatments', 'tokens', 'judge', 'runtime'], 'the config', errors);
 
   if (
     config.contrast === undefined &&
     config.treatments === undefined &&
+    config.tokens === undefined &&
     config.judge === undefined &&
     config.runtime === undefined
   ) {
-    errors.push('the config must define at least one of "contrast", "treatments", "runtime" or "judge"');
+    errors.push(
+      'the config must define at least one of "contrast", "treatments", "tokens", "runtime" or "judge"',
+    );
   }
   if (config.contrast !== undefined) {
     if (isPlainObject(config.contrast)) validateContrast(config.contrast, errors);
@@ -264,6 +280,10 @@ export function validate(config) {
     if (isPlainObject(config.treatments)) validateTreatments(config.treatments, errors);
     else errors.push('treatments must be an object');
   }
+  if (config.tokens !== undefined) {
+    if (isPlainObject(config.tokens)) validateTokens(config.tokens, errors);
+    else errors.push('tokens must be an object');
+  }
   if (config.judge !== undefined) {
     if (isPlainObject(config.judge)) validateJudge(config.judge, errors);
     else errors.push('judge must be an object');

package/src/index.mjs

@@ -4,6 +4,7 @@
  */
 export { runContrast } from './contrast.mjs';
 export { runTreatments } from './treatments.mjs';
+export { runTokens, varRefs } from './tokens.mjs';
 export { runJudge, prepareJudge, gradeVerdict, buildPrompt, checklistLines, checklistEntries, extractJson } from './judge.mjs';
 export { runRuntime } from './runtime.mjs';
 export { connect, findBrowser } from './cdp.mjs';
@@ -15,6 +16,7 @@ export { openTags, classesOf } from './treatments.mjs';
 
 import { runContrast } from './contrast.mjs';
 import { runTreatments } from './treatments.mjs';
+import { runTokens } from './tokens.mjs';
 import { runJudge } from './judge.mjs';
 import { runRuntime } from './runtime.mjs';
 
@@ -34,6 +36,9 @@ export function run(config, cwd, { only = null } = {}) {
   if (config.treatments && (!only || only === 'treatments')) {
     results.push(runTreatments(config.treatments, cwd));
   }
+  if (config.tokens && (!only || only === 'tokens')) {
+    results.push(runTokens(config.tokens, cwd));
+  }
   return results;
 }
 

package/src/judge.mjs

@@ -18,9 +18,12 @@
  * 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.
+ * The CHECKLIST is yours. taste-check enforces no rule it wrote: what runs is
+ * the file in your repo. `checklist --new` will scaffold you a starting point,
+ * and the distinction is not a dodge, it is the difference between a default
+ * and a scaffold. A default judges every user who never opened the file
+ * against opinions they did not choose. A scaffold is a file you edited and
+ * committed, and this never reads its own copy of it.
  *
  * ── Where the determinism line falls ────────────────────────────────────
  *

package/src/report.mjs

@@ -54,6 +54,10 @@ function judgeLines(result) {
 export const linesFor = (result) => {
   if (result.name === 'contrast' || result.name === 'runtime') return contrastLines(result);
   if (result.name === 'judge') return judgeLines(result);
+  // tokens and treatments both report {file, line, message} failures, so they
+  // render the same way. Named rather than left to the fallthrough: a check
+  // that renders by accident is a check that stops rendering by accident.
+  if (result.name === 'tokens') return treatmentLines(result);
   return treatmentLines(result);
 };
 

package/src/sarif.mjs

@@ -32,6 +32,8 @@ const RULES = [
   ['treatments/unapproved-class', 'error', 'A class name that is not on the approved list.'],
   ['treatments/one-off-value', 'error', 'A literal colour or length hardcoded into an inline style.'],
   ['treatments/unscannable', 'error', 'No markup matched, so nothing was checked.'],
+  ['tokens/undefined', 'error', 'Markup references a custom property that no token file declares.'],
+  ['tokens/unscannable', 'error', 'The tokens check could not run: no token file, no markup, or a token file that declares nothing.'],
   ['runtime/below-floor', 'error', 'A target on the rendered page is under the ratio it was given.'],
   ['runtime/unmeasurable', 'error', 'A target could not be measured: no element, nothing rendered, an edge with no width, or no browser.'],
   ['judge/verdict', 'note', 'A checklist line the judge did not pass. Advisory: a model verdict is not reproducible.'],
@@ -118,7 +120,7 @@ function resultsFor(check, ctx) {
     return out;
   }
 
-  if (check.name === 'treatments') {
+  if (check.name === 'treatments' || check.name === 'tokens') {
     for (const failure of check.failures ?? []) {
       out.push({
         ruleId: failure.rule,
@@ -130,7 +132,7 @@ function resultsFor(check, ctx) {
     }
     for (const problem of check.problems ?? []) {
       out.push({
-        ruleId: 'treatments/unscannable',
+        ruleId: `${check.name}/unscannable`,
         key: problem,
         level: 'error',
         message: { text: problem },

package/src/tokens.mjs

@@ -0,0 +1,128 @@
+/**
+ * The undefined-token check: every `var(--x)` in markup, against the tokens
+ * the system actually declares.
+ *
+ * ── Why markup and not stylesheets ──────────────────────────────────────
+ *
+ * Stylelint's core `no-unknown-custom-properties` already does this for CSS,
+ * and its `referenceFiles` option covers the case that matters, where tokens
+ * are declared in one file and consumed in another. Rebuilding that would be
+ * a worse copy of a first-party rule.
+ *
+ * What nothing covers is markup. Stylelint's CSS-in-JS syntax is deprecated,
+ * and `style={{ color: open ? 'var(--a)' : 'var(--b)' }}` is not CSS-in-JS
+ * anyway: it is a JavaScript object literal that no CSS parser reads. That is
+ * the gap, and it is the one a model writing plausible off-system code falls
+ * into, reaching for `--color-primary-500` when the system says `--brand-ink`.
+ *
+ * ── Why a plain scan and not the tag walker ─────────────────────────────
+ *
+ * `treatments.mjs` walks tags because a class name is only a class name in an
+ * attribute, and a bare word elsewhere is noise. `var(--` is not like that.
+ * The string is unambiguous wherever it appears, so scanning the whole file
+ * costs nothing in false positives and picks up references the tag walker
+ * cannot see: a styled-components template, an object of styles declared above
+ * the return, a constant in a helper module.
+ *
+ * Nesting comes free. `var(--a, var(--b))` matches twice, so both names are
+ * checked rather than only the outer one.
+ */
+import { readFileSync } from 'node:fs';
+import { lineAt, parseDeclarations } from './css.mjs';
+import { expand, label } from './files.mjs';
+
+/**
+ * The name is `[\w-]+` for the same reason `resolveValue` in css.mjs uses it:
+ * escapes and non-ASCII in a custom property name are legal and vanishingly
+ * rare, and inventing a fuller grammar here would only disagree with the
+ * resolver next door.
+ */
+const VAR_REF = /var\(\s*(--[\w-]+)\s*(,?)/g;
+
+const count = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+/**
+ * Every custom property referenced through `var()`, with the offset of the
+ * name and whether the reference carries a fallback.
+ *
+ * A bare `--x` written outside a `var()` is deliberately not a reference. That
+ * is a different mistake, and stylelint's `custom-property-no-missing-var-function`
+ * is the rule for it.
+ */
+export function varRefs(source) {
+  const found = [];
+  for (const m of source.matchAll(VAR_REF)) {
+    found.push({ name: m[1], index: m.index + m[0].indexOf(m[1]), fallback: m[2] === ',' });
+  }
+  return found;
+}
+
+/** Every custom property name declared anywhere in the token files. */
+function declaredNames(files) {
+  const names = new Set();
+  for (const file of files) {
+    for (const decl of parseDeclarations(readFileSync(file, 'utf8'))) names.add(decl.prop);
+  }
+  return names;
+}
+
+export function runTokens(config, cwd) {
+  const failures = [];
+  const problems = [];
+  const { declaredIn, files: patterns, allow = [], allowPrefixes = [] } = config;
+
+  const quoted = (list) => list.map((p) => `"${p}"`).join(', ');
+  const tokenFiles = expand(declaredIn, cwd);
+  const files = expand(patterns, cwd);
+
+  if (!tokenFiles.length) problems.push(`no token files matched ${quoted(declaredIn)}`);
+  const declared = declaredNames(tokenFiles);
+  if (tokenFiles.length && !declared.size) {
+    problems.push(
+      `${count(tokenFiles.length, 'token file')} matched ${quoted(declaredIn)}, ` +
+        `but none of them declares a custom property. Every reference would read as undefined.`,
+    );
+  }
+  if (!files.length) problems.push(`no markup files matched ${quoted(patterns)}`);
+
+  // Without a trustworthy declared set there is nothing to compare against,
+  // and reporting every reference in the codebase as undefined would bury the
+  // one line that says why.
+  if (problems.length) return { name: 'tokens', failures, problems, summary: '' };
+
+  const allowed = new Set(allow);
+  let references = 0;
+
+  for (const file of files) {
+    const source = readFileSync(file, 'utf8');
+    for (const { name, index, fallback } of varRefs(source)) {
+      references += 1;
+      if (declared.has(name)) continue;
+      if (allowed.has(name)) continue;
+      if (allowPrefixes.some((p) => name.startsWith(p))) continue;
+      failures.push({
+        rule: 'tokens/undefined',
+        file: label(file, cwd),
+        line: lineAt(source, index),
+        subject: name,
+        message:
+          `"${name}" is referenced here but declared in no token file.` +
+          (fallback ? ' It has a fallback, so it degrades rather than breaks.' : '') +
+          ' Check the name, or add it to allow.',
+      });
+    }
+  }
+
+  // `references` is in the summary rather than a failure on purpose. A zero
+  // can mean a glob pointing at the wrong tree, but it can equally mean a
+  // codebase that keeps its styling in stylesheets, which is not a fault. The
+  // wrong-glob case that can be told apart is the one above: no files matched.
+  return {
+    name: 'tokens',
+    failures,
+    problems,
+    summary:
+      `${count(tokenFiles.length, 'token file')}, ${declared.size} declared, ` +
+      `${count(files.length, 'file')} scanned, ${count(references, 'reference')}`,
+  };
+}

package/src/treatments.mjs

@@ -20,6 +20,7 @@
  * positive is a conversation while a false negative is the bug shipping.
  */
 import { readFileSync } from 'node:fs';
+import { lineAt } from './css.mjs';
 import { expand, label } from './files.mjs';
 
 /** Literal value shapes worth flagging when they are not on the list. */
@@ -178,8 +179,6 @@ function inlineValues(attrs) {
   return found;
 }
 
-const lineOf = (source, index) => source.slice(0, index).split('\n').length;
-
 export function runTreatments(config, cwd) {
   const failures = [];
   const problems = [];
@@ -202,7 +201,7 @@ export function runTreatments(config, cwd) {
 
   for (const file of files) {
     const source = readFileSync(file, 'utf8');
-    const where = (at) => ({ file: label(file, cwd), line: lineOf(source, at) });
+    const where = (at) => ({ file: label(file, cwd), line: lineAt(source, at) });
 
     for (const tag of openTags(source, elements)) {
       for (const { name, at } of classesOf(tag.attrs)) {