synthesisui 0.10.1 → 0.11.0

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { findFrozenBindings } from "../doctor/frozen.js";
 import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
 import { diagnose, scanSource, } from "../doctor/scan.js";
 import { findSelfConflicts, forbiddenProps, isReset, propMatchesLabel, } from "../doctor/self-conflict.js";
@@ -352,6 +353,28 @@ export async function doctor(opts) {
         console.log(body("Whoever wrote the law and whoever wrote the recipe disagree."));
         console.log(body("Until they do not, no code here can be correct."));
     }
+    // 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.
+    const frozen = documents
+        .flatMap((doc) => findFrozenBindings(doc))
+        .filter((f) => used.has(f.component));
+    if (frozen.length > 0) {
+        console.log(section("These will not follow your other scheme"));
+        console.log(body(frozen.length === 1
+            ? "One recipe names a primitive where a role holds the same value."
+            : `${frozen.length} recipes name a primitive where a role holds the same value.`));
+        console.log("");
+        for (const f of frozen) {
+            console.log(body(`ds-${f.component} · ${f.where}`));
+            console.log(`          binds ${f.wrote}`);
+            console.log(`          {color.semantic.${f.role}} holds that, and becomes ${f.becomes}`);
+            console.log("");
+        }
+        console.log(body("The value resolves and the CSS compiles, so nothing"));
+        console.log(body("complains - the surface just stays put when the scheme"));
+        console.log(body("moves around it."));
+    }
     if (overrides.length > 0) {
         // An override on a property the component's own law FORBIDS, written as a
         // reset, is not drift - it is the author keeping a promise the recipe

package/dist/doctor/frozen.js

@@ -0,0 +1,104 @@
+/**
+ * DOCTOR · bindings that will not follow the scheme.
+ *
+ * A system with two schemes keeps the flip in ONE place: the semantic layer.
+ * `surface` points at navy-800 in dark and navy-50 in light, and every recipe
+ * that binds `{color.semantic.surface}` flips for free.
+ *
+ * A recipe that reaches past the role and names the shelf - `{color.navy.800}` -
+ * is frozen. It looks identical in the authored scheme and wrong in the other
+ * one, and nothing in the pipeline says so: the value is a legitimate token,
+ * the reference resolves, the CSS compiles.
+ *
+ * Vesper does this in five places. Its chip binds `{color.navy.800}` for a
+ * background where `semantic.surface` holds the same value and becomes navy-50
+ * in light mode - so the chip stays dark on a light page (found by reading the
+ * doctor's own output on a real project, investidorez, 25/07).
+ *
+ * This is a correctness check, not a style one. It fires only when the role
+ * actually differs between the two schemes; a role that is the same in both
+ * costs nothing to spell either way, and this stays quiet about it.
+ */
+const PRIMITIVE = /^\{color\.([a-z0-9]+)\.([a-z0-9]+)\}$/i;
+const BACKGROUND = /^background(-color)?$/;
+const kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+function* colorBindings(node, where) {
+    if (!node || typeof node !== "object")
+        return;
+    for (const [k, v] of Object.entries(node)) {
+        if (typeof v === "string") {
+            // Backgrounds only. A FOREGROUND bound to a primitive is usually right:
+            // white on an indigo button must stay white, because the fill it sits on
+            // does not flip either. Deciding that needs the sibling fill and the
+            // author's intent, so this lens does not try - a wrong accusation here
+            // would have someone invert readable text.
+            if (BACKGROUND.test(kebab(k)) && PRIMITIVE.test(v))
+                yield { prop: kebab(k), value: v, where };
+        }
+        else if (v && typeof v === "object") {
+            yield* colorBindings(v, where);
+        }
+    }
+}
+export function findFrozenBindings(document) {
+    const doc = (document ?? {});
+    const foundations = (doc.foundations ?? {});
+    const color = (foundations.color ?? {});
+    const semantic = (color.semantic ?? {});
+    const alt = (color.semanticAlt ?? {});
+    // Only roles that actually MOVE between schemes. A role spelled the same in
+    // both is not a correctness problem, and this lens does not do taste.
+    //
+    // Several roles can hold one primitive (Vesper's navy-700 is raised, overlay
+    // AND border). Surfaces are preferred, because this only ever reports a
+    // background - naming "border" for a background reads like a bug in the tool.
+    const RANK = ["surface", "raised", "canvas", "overlay", "border"];
+    const roleOf = new Map();
+    for (const [role, ref] of Object.entries(semantic)) {
+        const other = alt[role];
+        if (typeof ref !== "string" || typeof other !== "string")
+            continue;
+        if (other === ref)
+            continue;
+        const m = PRIMITIVE.exec(ref);
+        if (!m)
+            continue;
+        const key = `${m[1]}.${m[2]}`.toLowerCase();
+        const held = roleOf.get(key);
+        const better = !held ||
+            (RANK.indexOf(role) !== -1 &&
+                (RANK.indexOf(held.role) === -1 ||
+                    RANK.indexOf(role) < RANK.indexOf(held.role)));
+        if (better)
+            roleOf.set(key, { role, becomes: other });
+    }
+    if (roleOf.size === 0)
+        return [];
+    const out = [];
+    const components = (doc.components ?? {});
+    for (const [name, raw] of Object.entries(components)) {
+        const recipe = (raw ?? {});
+        const found = [
+            ...colorBindings(recipe.base, "base"),
+            ...colorBindings(recipe.states, "a state"),
+            ...colorBindings(recipe.variants, "a variant"),
+            ...colorBindings(recipe.parts, "a part"),
+        ];
+        for (const b of found) {
+            const m = PRIMITIVE.exec(b.value);
+            if (!m)
+                continue;
+            const hit = roleOf.get(`${m[1]}.${m[2]}`.toLowerCase());
+            if (!hit)
+                continue;
+            out.push({
+                component: name,
+                where: `${b.where} · ${b.prop}`,
+                wrote: b.value,
+                role: hit.role,
+                becomes: hit.becomes,
+            });
+        }
+    }
+    return out;
+}

package/package.json

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