synthesisui 0.16.18 → 0.16.19

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { findDivergences } from "../doctor/coherence.js";
 import { findFrozenBindings } from "../doctor/frozen.js";
 import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
 import { diagnose, scanSource, siblingTokens, } from "../doctor/scan.js";
@@ -633,6 +634,32 @@ export async function doctor(opts) {
         say(body("Whoever wrote the law and whoever wrote the recipe disagree."));
         say(body("Until they do not, no code here can be correct."));
     }
+    /**
+     * THE FAILURE THAT SURVIVES A PERFECT SCORE.
+     *
+     * Coverage asks whether the vocabulary was used. It cannot ask whether the
+     * system says ONE thing, because every component here can reference the right
+     * token and still answer the same question differently. Measured on 28/07 in
+     * a system this tool had just graded 100%: the input shows focus by moving its
+     * border, the button by drawing an outline.
+     *
+     * Reported quietly and only against a clear house style. Hover is legitimately
+     * different per component, and a checker that flagged variety would be
+     * uninstalled the same day it shipped.
+     */
+    const divergences = findDivergences(documents);
+    if (divergences.length > 0) {
+        say(section("The system answers the same question two ways"));
+        for (const d of divergences) {
+            say(body(`${d.concern}: ${d.houseCount} components use ${d.house.join(" + ")}.`));
+            for (const o of d.outliers) {
+                say(`      ${o.component} uses ${o.props.join(" + ")} instead`);
+            }
+            say("");
+        }
+        say(body("Every one of these uses your tokens, so coverage says nothing"));
+        say(body("about them. A person meets the difference on screen."));
+    }
     // The other way a system fails itself: a recipe that names a SHELF where the
     // system has a ROLE. The value is legitimate, the reference resolves, the CSS
     // compiles - and the binding sits still while everything around it flips.

package/dist/doctor/coherence.js

@@ -0,0 +1,117 @@
+/**
+ * DOES THE SYSTEM AGREE WITH ITSELF?
+ *
+ * Token coverage answers a different question than everybody assumes. It asks
+ * whether the vocabulary was used. It cannot ask whether the system says one
+ * thing, because every component can reference the correct token and still
+ * express the same idea in a different way.
+ *
+ * Measured on 28/07, in a system this tool had just graded at 100%: the input
+ * shows focus by moving its border, the button by drawing an outline. Same
+ * token, same toolbar, two answers to one question. Every deterministic
+ * assertion we had passed, and a person looking at the screen sees a system
+ * that has not decided what focus looks like.
+ *
+ * WHY IT LIVES IN CODE AND NOT IN THE DESIGN TOOL. A designer in the Design
+ * Systems Slack built a lint plugin that does this inside Figma. Asked whether
+ * it can compare across components rather than one at a time: "it can check one
+ * at a time or all, but this crashes figma most of the time". A plugin walks a
+ * document graph inside a sandbox; this reads recipes off disk, and the whole
+ * catalogue costs a few milliseconds. The check is feasible on this side and not
+ * on that one.
+ *
+ * WHAT MAKES IT HONEST RATHER THAN NOISY. Variety is not drift. Hover is
+ * legitimately different per component - a row tints, a link recolours, a chip
+ * moves its border - and a checker that flagged all of it would be uninstalled
+ * the same day. So it reports a MINORITY against a DOMINANT majority and says
+ * nothing at all when the catalogue has no majority to disagree with.
+ *
+ * Measured against the shipped catalogue, that rule reports the two real ones
+ * and neither of the false ones:
+ *
+ *   focus       9 use outline, 3 use border-color   → reported (75% dominant)
+ *   disabled   12 dim and change the cursor, 1 only dims → reported (92%)
+ *   hover       5 shapes across 11, none dominant  → silent
+ *   active      1 and 1                            → silent
+ */
+/**
+ * State names that answer the SAME question, folded together.
+ *
+ * Without this the check finds nothing here, because each name is unanimous on
+ * its own: `focusVisible` is nine-for-nine outline, `focus` is three-for-three
+ * border. The disagreement only exists once you know they are the same concern,
+ * which is exactly why it survived every per-name check anyone could write.
+ */
+const CONCERNS = {
+    focus: "focus",
+    focusvisible: "focus",
+    focuswithin: "focus",
+    active: "pressed",
+    pressed: "pressed",
+    checked: "selected",
+    selected: "selected",
+    disabled: "disabled",
+    hover: "hover",
+};
+/** Below this share, the catalogue has no house style to disagree with, and
+ *  every "outlier" is just the variety the concern is supposed to have. */
+const DOMINANT = 0.7;
+function collect(documents) {
+    const byConcern = new Map();
+    const visit = (label, node) => {
+        for (const [state, block] of Object.entries(node.states ?? {})) {
+            const concern = CONCERNS[state.toLowerCase()];
+            // An unrecognised state is not folded into anything. Guessing that two
+            // names mean the same thing is how a checker starts inventing findings.
+            if (!concern)
+                continue;
+            const props = Object.keys(block ?? {}).sort();
+            if (props.length === 0)
+                continue;
+            const list = byConcern.get(concern) ?? [];
+            list.push({ component: label, props });
+            byConcern.set(concern, list);
+        }
+    };
+    for (const raw of documents) {
+        const doc = raw;
+        for (const [name, recipe] of Object.entries(doc.components ?? {})) {
+            visit(name, recipe);
+            for (const [part, block] of Object.entries(recipe.parts ?? {})) {
+                visit(`${name}.${part}`, block);
+            }
+        }
+    }
+    return byConcern;
+}
+/** Every concern the system answers more than one way, with a clear majority. */
+export function findDivergences(documents) {
+    const out = [];
+    for (const [concern, entries] of collect(documents)) {
+        // One component cannot disagree with itself, and two cannot form a house
+        // style - the smallest catalogue this can speak about is three.
+        if (entries.length < 3)
+            continue;
+        const shapes = new Map();
+        for (const e of entries) {
+            const key = e.props.join("+");
+            shapes.set(key, [...(shapes.get(key) ?? []), e]);
+        }
+        if (shapes.size < 2)
+            continue;
+        const ranked = [...shapes.entries()].sort((a, b) => b[1].length - a[1].length);
+        const [houseKey, houseList] = ranked[0];
+        if (houseList.length / entries.length < DOMINANT)
+            continue;
+        out.push({
+            concern,
+            house: houseKey.split("+"),
+            houseCount: houseList.length,
+            outliers: ranked
+                .slice(1)
+                .flatMap(([, list]) => list)
+                .sort((a, b) => a.component.localeCompare(b.component)),
+        });
+    }
+    return out.sort((a, b) => b.outliers.length - a.outliers.length);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.18",
+  "version": "0.16.19",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {