synthesisui 0.16.84 → 0.16.87

package/dist/anatomy-read.js

@@ -194,6 +194,15 @@ root) {
                     : [];
                 const t = transcribe(classes, declared);
                 parts[key] = { base: t.base, dark: t.dark, states: t.states };
+                /**
+                 * A drop on a PART is still a drop. The root path already says these out loud;
+                 * this one silently swallowed `p-spacing-sm` on a real menu popup, so the part
+                 * arrived with no padding and the not-expressed file had to discover it from
+                 * the outside (dono, 01/08).
+                 */
+                for (const cls of t.unreadable) {
+                    notes.push(`part \`${key}\`: \`${cls}\` starts like a design decision and reads as nothing - usually a typo in the source, and the element renders without it today`);
+                }
                 node_.part = key;
             }
             const text = typeof node.text === "string" ? node.text.trim() : "";

package/dist/commands/import.js

@@ -17,6 +17,7 @@ import { reconcile, scanDefinitions, } from "../doctor/definitions-scan.js";
 import { describeConvention, describeRemainder, detectConventions, } from "../doctor/idiom.js";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
+import { describeSignals, emptySignals, finishSignals, readSignalsInto, } from "../doctor/signals.js";
 import { buildTable } from "../doctor/tokens.js";
 import { readInlineStyle, rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
 import { transcribeVariants } from "../doctor/variant-read.js";
@@ -272,6 +273,17 @@ export async function takeCensus(root, opts) {
     const dirs = new Map();
     /** Parent → child → the files that put one inside the other. */
     const nesting = new Map();
+    /**
+     * WHAT IS COUNTABLE, COUNTED - so the reader decides instead of searching.
+     *
+     * The skill's theme section said "go and look" and listed five places to grep; a real run
+     * swept for motion and icon libraries too, which it never asked for (dono, 01/08).
+     * Searching is a tool call, its whole output lands in the context, and two readers
+     * sweeping the same repo bring back different slices. All of this is one more pass over
+     * files already open. See `signals.ts`.
+     */
+    const signals = emptySignals();
+    const importTally = new Map();
     /** Component → what its own definition names and whether it forwards the rest. */
     const propsOf = new Map();
     /**
@@ -317,6 +329,7 @@ export async function takeCensus(root, opts) {
             }
         }
         sources.push({ file: rel, source: src });
+        readSignalsInto(signals, importTally, rel, src);
         reports.push(scanSource(rel, src, table));
         // Stories and tests compose components to SHOW them; counting those as the
         // product's own composition is the same lie the colour census told before
@@ -389,6 +402,15 @@ export async function takeCensus(root, opts) {
                  * paid for twice already.
                  */
                 const v = transcribeVariants(src, declaredValues);
+                /**
+                 * THE RESTING OPTION, from the definition itself. `cva` says it in
+                 * `defaultVariants`; a lookup-record component says it in the destructuring -
+                 * `{ variant = "body-md" }` - and reading past that left every style behind a
+                 * `[data-variant]` selector nothing sets, so a real Text previewed as bare
+                 * unstyled words (dono, 01/08).
+                 */
+                const destructured = readDefinitionProps(found[0].name, src).defaults;
+                const defaults = { ...destructured, ...v.defaults };
                 /**
                  * THE CSS MODULE, if this component styles that way.
                  *
@@ -461,9 +483,7 @@ export async function takeCensus(root, opts) {
                         ...(tag ? { rootTag: tag } : {}),
                         ...(layers.length > 0 ? { layers } : {}),
                         ...(Object.keys(v.axes).length > 0 ? { declaredAxes: v.axes } : {}),
-                        ...(Object.keys(v.defaults).length > 0
-                            ? { defaults: v.defaults }
-                            : {}),
+                        ...(Object.keys(defaults).length > 0 ? { defaults } : {}),
                     };
                 }
                 // Their variant DEFINITION beats what usage happened to pick, and it is the
@@ -766,6 +786,44 @@ export async function takeCensus(root, opts) {
         console.log("");
         console.log(body(describeFallback(fetched, floorSize())));
     }
+    /**
+     * THE SIGNALS, said as EVIDENCE. "189 dark utilities across 30 files, bound to
+     * `[data-theme=dark]`, opening dark with the OS overruled" is something a person can
+     * confirm or correct; "this is a dark product" is a claim they take on faith.
+     */
+    const signalLines = describeSignals(signals);
+    if (signalLines.length > 0) {
+        console.log("");
+        console.log(section("What was countable, counted"));
+        for (const line of signalLines)
+            console.log(body(line));
+        console.log(body(paint.faint("Do not go looking for any of this - it is measured, and a sweep would bring back a different slice than the next one.")));
+    }
+    /**
+     * THE DROPS, SAID OUT LOUD. `p-spacing-sm` on a real menu popup read as nothing and
+     * the popup shipped with no padding, invisibly - "if the compiler drops them, the drop
+     * is invisible from here" was the not-expressed file calling this exact hole (dono,
+     * 01/08). More often than not the class is malformed in THEIR source, which makes this
+     * a defect report about their code, not an apology about ours.
+     */
+    const unreadableByComponent = Object.entries(looks)
+        .filter(([, look]) => (look.unreadable ?? []).length > 0)
+        .map(([component, look]) => ({
+        component,
+        classes: look.unreadable ?? [],
+    }));
+    if (unreadableByComponent.length > 0) {
+        const total = unreadableByComponent.reduce((n, u) => n + u.classes.length, 0);
+        console.log("");
+        console.log(section("Design classes that read as nothing"));
+        console.log(body(`${total} class${total === 1 ? "" : "es"} start like a design decision and resolve to nothing - usually a typo in the source, and the element renders without that decision today. Nothing was guessed on their behalf:`));
+        for (const u of unreadableByComponent.slice(0, 8)) {
+            console.log(body(paint.faint(`  ${u.component}: ${u.classes.slice(0, 4).join(", ")}`)));
+        }
+        if (unreadableByComponent.length > 8) {
+            console.log(body(paint.faint(`  and ${unreadableByComponent.length - 8} more components`)));
+        }
+    }
     const coverageLines = describeCoverage(coverage);
     if (coverageLines.length > 0) {
         console.log("");
@@ -847,14 +905,19 @@ export async function takeCensus(root, opts) {
     }));
     const pkgRaw = await readFile(join(root, "package.json"), "utf8").catch(() => null);
     let name = null;
+    /** Their pinned ranges, so a library signal cites the version rather than going stale. */
+    let versions = {};
     if (pkgRaw) {
         try {
-            name = JSON.parse(pkgRaw).name ?? null;
+            const pkg = JSON.parse(pkgRaw);
+            name = pkg.name ?? null;
+            versions = { ...pkg.devDependencies, ...pkg.dependencies };
         }
         catch {
             // an unreadable package.json costs the name, not the run
         }
     }
+    finishSignals(signals, importTally, versions);
     // Every name their CSS defines, from the same harvest the token table came
     // from - so a reference is judged against what actually exists, not against
     // the subset we managed to read as a ramp.
@@ -891,6 +954,7 @@ export async function takeCensus(root, opts) {
          * printed it, and never turned it into a rule is a feature that does nothing (dono,
          * 01/08).
          */
+        signals,
         ...(coverage.components > 0
             ? {
                 coverage: {
@@ -1551,6 +1615,7 @@ async function resolveReadParts(census, root) {
                 dark: {},
                 states: {},
                 skipped: [],
+                unreadable: [],
                 literals: [],
                 fromToken: 0,
                 fromLiteral: 0,

package/dist/doctor/call-sites.js

@@ -49,12 +49,25 @@ const SPREAD_ONTO = /\{\s*\.\.\.\s*([A-Za-z_$][\w$]*)\s*\}/g;
  */
 export function readDefinitionProps(name, source) {
     const explicit = [];
+    const defaults = {};
     let restName = null;
+    /**
+     * EXACT NAME FIRST, THEN THE forwardRef SPELLING.
+     *
+     * `export const Label = forwardRef(LabelComponent)` defines its props on
+     * `LabelComponent`, and searching for `Label` alone read past the destructure - so a
+     * real Label's `variant = "body-md"` default never travelled (probe, 01/08). A prefix
+     * match (`LabelComponent` starts with `Label`) is the deterministic version of that
+     * idiom, and the exact name still wins when both exist.
+     */
     DESTRUCTURED.lastIndex = 0;
-    for (const m of source.matchAll(DESTRUCTURED)) {
+    const matches = [...source.matchAll(DESTRUCTURED)];
+    const exact = matches.filter((m) => (m[1] ?? m[3]) === name);
+    const prefixed = matches.filter((m) => {
         const found = m[1] ?? m[3];
-        if (found !== name)
-            continue;
+        return found !== name && found?.startsWith(name);
+    });
+    for (const m of exact.length > 0 ? exact : prefixed) {
         const body = m[2] ?? m[4] ?? "";
         for (const raw of body.split(",")) {
             const part = raw.trim();
@@ -69,6 +82,11 @@ export function readDefinitionProps(name, source) {
             if (/^[a-zA-Z_$][\w$]*$/.test(prop) && !explicit.includes(prop)) {
                 explicit.push(prop);
             }
+            // `variant = "body-md"` - the resting option, said by the definition itself.
+            // Only a string literal: a computed default is not in the source.
+            const def = /=\s*["']([^"']+)["']\s*$/.exec(part);
+            if (def && /^[a-zA-Z_$][\w$]*$/.test(prop))
+                defaults[prop] = def[1];
         }
         break;
     }
@@ -82,7 +100,7 @@ export function readDefinitionProps(name, source) {
             }
         }
     }
-    return { explicit, forwards };
+    return { explicit, defaults, forwards };
 }
 /**
  * WHICH COMPONENTS APPEAR INSIDE THIS ONE, at its call sites.

package/dist/doctor/crosswalk.js

@@ -196,6 +196,49 @@ export function canonicalName(name) {
     // WHOLE word is - a widget card is not a card, it is their own thing.
     return null;
 }
+/** The head of a name, the way `canonicalName` reads it. */
+function headOf(name) {
+    return name
+        .split(".")[0]
+        .toLowerCase()
+        .replace(/[^a-z]/g, "");
+}
+/**
+ * The canonical, kept only when the match is an identity or the axes back it up.
+ * See the note at the call site - this is the guard, not the policy.
+ */
+export function evidencedCanonical(component) {
+    const canonical = canonicalName(component.name);
+    if (!canonical)
+        return null;
+    // The name IS ours, spelled their way. `Text → text`, `Card → card`.
+    if (headOf(component.name) === canonical.replace(/-/g, ""))
+        return canonical;
+    // A synonym hop. Without live axes there is no evidence to weigh - old behaviour.
+    const target = live?.axes[canonical];
+    if (!target || Object.keys(target).length === 0)
+        return canonical;
+    // Their side has to DECLARE something for the disagreement to mean anything: a
+    // component with no axes offers no witness either way, and the name stands.
+    const theirOptions = new Set();
+    for (const values of Object.values(component.props)) {
+        for (const v of canonicalValues(values))
+            theirOptions.add(v);
+    }
+    if (theirOptions.size < 2)
+        return canonical;
+    const ourOptions = new Set();
+    for (const values of Object.values(target)) {
+        for (const v of canonicalValues(values))
+            ourOptions.add(v);
+    }
+    if (ourOptions.size === 0)
+        return canonical;
+    for (const v of theirOptions)
+        if (ourOptions.has(v))
+            return canonical;
+    return null;
+}
 export function canonicalAxes(props) {
     const out = new Set();
     for (const p of Object.keys(props)) {
@@ -398,7 +441,26 @@ opts) {
                     : "renders no UI - infrastructure, not a component",
             };
         }
-        const canonical = canonicalName(component.name);
+        /**
+         * A SYNONYM HOP NEEDS EVIDENCE; an identity match does not.
+         *
+         * `label → badge` was decided by the written table on the NAME alone, and their
+         * Label is a typography ladder - `variant: display|h1|h2|h3|body-sm|body-md|
+         * caption` - with nothing of a badge about it (dono, 01/08, "erros de match").
+         * Their `Text → text` is a different kind of claim: the name IS ours, spelled
+         * their way, and needs no second witness.
+         *
+         * So: a canonical reached through a synonym only stands when the axes agree -
+         * some shared option value (canonicalised, so `destructive` meets `danger`) with
+         * what the LIVE catalogue says that component offers. Their Tag's
+         * `color(danger|success|warning|neutral…)` overlaps our badge's intent options
+         * and survives; Label's heading ladder overlaps nothing and falls back to being
+         * exclusively theirs, which is what it was.
+         *
+         * Offline the live axes are absent and the old behaviour stands - the fallback
+         * message already says the answer is smaller.
+         */
+        const canonical = evidencedCanonical(component);
         const twins = mine
             .filter((o) => o.name !== component.name)
             .map((o) => ({

package/dist/doctor/signals.js

@@ -0,0 +1,286 @@
+/**
+ * WHAT IS COUNTABLE, COUNTED - so the reader decides instead of searching.
+ *
+ * The skill's theme section said "go and look" and listed five places to grep. Watching a
+ * real run, the agent swept for `framer-motion`, `lucide-react` and `@base-ui` too - things
+ * the skill never asked for - because "go and look" is an open invitation (dono, 01/08).
+ *
+ * Searching is expensive for three reasons that compound: every grep is a tool call, its
+ * whole output lands in the context, and the output is mostly noise - a `grep -rn "dark:"`
+ * over 2797 files returns hundreds of lines to answer a question that is one number.
+ *
+ * And it is worse than expensive: it is NOT DETERMINISTIC. Two readers sweeping the same
+ * repo bring back different slices, so the answer changes between runs.
+ *
+ * THE PRACTICE, and it holds for any system: give a reader the EVIDENCE and ask it to
+ * decide; never give it a question and ask it to search. Everything here is one more pass
+ * over files the census already walks - free on this side, and it deletes a handful of tool
+ * calls from the other.
+ *
+ * What is left for a person to judge after this is short and named: which grey is the page,
+ * what the product IS, and the anatomy of each component. Those are readings, not counts.
+ */
+/** A dark utility in a class name: `dark:bg-x`, and the `dark:` inside a longer chain. */
+const DARK_UTILITY = /(?:^|["'\s:])dark:/g;
+/** How a project says which theme is on. Ordered: the first hit is the one it uses. */
+const THEME_LIBRARY = [
+    [/from\s+["']next-themes["']/, "next-themes"],
+    [/from\s+["']@radix-ui\/themes["']/, "@radix-ui/themes"],
+    [/from\s+["']styled-components["'][\s\S]*ThemeProvider/, "styled-components"],
+    [/\buseColorScheme\b/, "react-native / useColorScheme"],
+    [/\bThemeProvider\b/, "a ThemeProvider of their own"],
+];
+/** `attribute="data-theme"` on the provider - the selector every dark rule then needs. */
+const THEME_ATTRIBUTE = /attribute\s*=\s*\{?["']([^"']+)["']/;
+/** `defaultTheme="dark"` - which face it opens in, said by the provider itself. */
+const DEFAULT_THEME = /defaultTheme\s*=\s*\{?["'](light|dark|system)["']/;
+/** `enableSystem={false}` - whether the OS gets a vote. */
+const ENABLE_SYSTEM = /enableSystem\s*=\s*\{(true|false)\}/;
+/** What `<html>` carries by default, which is what a dark rule matches against. */
+const HTML_ATTRS = /<html\b([^>]*)>/;
+const PACKAGE_FAMILIES = [
+    {
+        family: "motion",
+        test: /^(framer-motion|motion|@react-spring\/.+|gsap|popmotion|react-transition-group)$/,
+    },
+    {
+        family: "icons",
+        test: /^(lucide-react|react-icons|@heroicons\/react|@tabler\/icons-react|@phosphor-icons\/react|react-feather)$/,
+    },
+    {
+        family: "primitives",
+        test: /^(@radix-ui\/.+|@base-ui\/.+|@base-ui-components\/.+|@headlessui\/react|@ariakit\/react|@reach\/.+)$/,
+    },
+    {
+        family: "styling",
+        test: /^(class-variance-authority|tailwind-variants|clsx|tailwind-merge|styled-components|@emotion\/.+|@chakra-ui\/.+|@mui\/.+|@pandacss\/dev)$/,
+    },
+    {
+        family: "charts",
+        test: /^(recharts|victory|@nivo\/.+|chart\.js|react-chartjs-2|apexcharts|d3)$/,
+    },
+    {
+        family: "editors",
+        test: /^(@tiptap\/.+|slate|quill|react-quill|@lexical\/.+|lexical)$/,
+    },
+];
+export function emptySignals() {
+    return {
+        theme: {
+            darkUtilities: 0,
+            darkFiles: 0,
+            library: null,
+            attribute: null,
+            defaultTheme: null,
+            enableSystem: null,
+            prefersColorScheme: 0,
+            htmlCarries: [],
+        },
+        libraries: [],
+        conflicts: [],
+    };
+}
+const ANY_IMPORT = /(?:from\s+["']([^"'.][^"']*)["']|require\(\s*["']([^"'.][^"']*)["']\s*\))/g;
+/** The package a specifier belongs to: `@tiptap/react` and `motion/react` both keep the
+ *  part a manifest would name. */
+export function packageOf(specifier) {
+    if (specifier.startsWith("@")) {
+        const parts = specifier.split("/");
+        return parts.slice(0, 2).join("/");
+    }
+    return specifier.split("/")[0];
+}
+/**
+ * THE LIBRARY a package belongs to, which is not the same as the package.
+ *
+ * `@tiptap/react`, `@tiptap/starter-kit` and nineteen extensions are ONE library, and
+ * reporting them as twenty-one entries and a conflict is noise pretending to be a finding
+ * (probe, 01/08). A scope is a library; an unscoped name is its own.
+ */
+export function libraryOf(specifier) {
+    const pkg = packageOf(specifier);
+    return pkg.startsWith("@") ? `${pkg.split("/")[0]}/*` : pkg;
+}
+/**
+ * Fold one file into the signals. Called from the walk the census already does, so nothing
+ * here costs a second pass over the disk.
+ */
+export function readSignalsInto(into, imports, file, source) {
+    const isCode = /\.(tsx|jsx|ts|js|mjs|cjs|vue|svelte)$/i.test(file);
+    const isStyle = /\.(css|scss|sass|less)$/i.test(file);
+    if (isStyle) {
+        into.theme.prefersColorScheme += (source.match(/prefers-color-scheme/g) ?? []).length;
+        return;
+    }
+    if (!isCode)
+        return;
+    DARK_UTILITY.lastIndex = 0;
+    const dark = (source.match(DARK_UTILITY) ?? []).length;
+    if (dark > 0) {
+        into.theme.darkUtilities += dark;
+        into.theme.darkFiles += 1;
+    }
+    into.theme.prefersColorScheme += (source.match(/prefers-color-scheme/g) ?? []).length;
+    // The first library that matches wins, and the order is deliberate: an explicit
+    // dependency beats a `ThemeProvider` that could be anybody's.
+    if (!into.theme.library) {
+        for (const [test, name] of THEME_LIBRARY) {
+            if (test.test(source)) {
+                into.theme.library = name;
+                break;
+            }
+        }
+    }
+    into.theme.attribute ??= THEME_ATTRIBUTE.exec(source)?.[1] ?? null;
+    into.theme.defaultTheme ??= DEFAULT_THEME.exec(source)?.[1] ?? null;
+    if (into.theme.enableSystem === null) {
+        const enable = ENABLE_SYSTEM.exec(source);
+        if (enable)
+            into.theme.enableSystem = enable[1] === "true";
+    }
+    /**
+     * WHAT `<html>` CARRIES. Every dark rule in the project is written against this
+     * ancestor, so reading it is what turns "they have a dark theme" into "their dark rules
+     * match `[data-theme=dark]`, which is what ours must match too".
+     */
+    const html = HTML_ATTRS.exec(source);
+    if (html) {
+        for (const m of html[1].matchAll(/([a-zA-Z-]+)\s*=\s*(?:["']([^"']*)["']|\{["']([^"']*)["']\})/g)) {
+            const attr = `${m[1]}="${m[2] ?? m[3] ?? ""}"`;
+            if (!into.theme.htmlCarries.includes(attr)) {
+                into.theme.htmlCarries.push(attr);
+            }
+        }
+    }
+    ANY_IMPORT.lastIndex = 0;
+    const seen = new Set();
+    for (const m of source.matchAll(ANY_IMPORT)) {
+        const spec = m[1] ?? m[2];
+        if (!spec)
+            continue;
+        const pkg = packageOf(spec);
+        // `motion/react` and `motion` are one package, and a file importing both is one file.
+        const key = /^motion(\/|$)/.test(spec) ? spec : pkg;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        imports.set(key, (imports.get(key) ?? 0) + 1);
+    }
+}
+/**
+ * The libraries, and the conflicts, from the import tally and their manifest.
+ *
+ * `versions` is `dependencies` merged with `devDependencies`, so the rule can cite the
+ * range they pinned rather than going stale the day they upgrade.
+ */
+export function finishSignals(into, imports, versions) {
+    const byFamily = new Map();
+    for (const [name, files] of imports) {
+        const pkg = packageOf(name);
+        const family = PACKAGE_FAMILIES.find((f) => f.test.test(pkg) || f.test.test(name));
+        if (!family)
+            continue;
+        const version = versions[pkg] ?? versions[name];
+        const signal = {
+            family: family.family,
+            name,
+            files,
+            ...(version ? { version } : {}),
+        };
+        byFamily.set(family.family, [
+            ...(byFamily.get(family.family) ?? []),
+            signal,
+        ]);
+    }
+    /**
+     * COLLAPSED BY LIBRARY. Twenty-one `@tiptap/*` entries answer nothing a person wanted to
+     * know; `@tiptap/* (21 packages, 4 files)` answers it in one line. The file count is the
+     * WIDEST of the group rather than the sum: four files import tiptap, not fifty-two.
+     */
+    into.libraries = [...byFamily.entries()]
+        .flatMap(([family, signals]) => {
+        const byLibrary = new Map();
+        for (const signal of signals) {
+            const key = libraryOf(signal.name);
+            byLibrary.set(key, [...(byLibrary.get(key) ?? []), signal]);
+        }
+        return [...byLibrary.entries()].map(([library, group]) => ({
+            family,
+            name: group.length > 1 ? library : group[0].name,
+            files: Math.max(...group.map((g) => g.files)),
+            ...(group.length > 1 ? { packages: group.length } : {}),
+            ...(group[0].version ? { version: group[0].version } : {}),
+        }));
+    })
+        .sort((a, b) => b.files - a.files || a.name.localeCompare(b.name));
+    /**
+     * TWO IN ONE FAMILY IS A FINDING. `framer-motion` in four files and `motion/react` in
+     * three, in one package, is the same library under two names and one of them is dead
+     * weight in the bundle. A person should see it; we do not decide it.
+     *
+     * `styling` and `primitives` are exempt: `clsx` beside `tailwind-merge` is the normal
+     * pairing, and two primitive libraries in a large app is a migration in progress, not a
+     * mistake.
+     */
+    for (const [family, signals] of byFamily) {
+        if (family === "styling" || family === "primitives")
+            continue;
+        // By LIBRARY, not by package: `@tiptap/react` beside `@tiptap/starter-kit` is one
+        // library used correctly, and calling it a conflict was noise (probe, 01/08).
+        const names = [...new Set(signals.map((x) => libraryOf(x.name)))];
+        if (names.length > 1)
+            into.conflicts.push({ family, names });
+    }
+    return into;
+}
+/**
+ * The signals as the sentences the reader would otherwise have gone looking for.
+ *
+ * Written as EVIDENCE rather than as a verdict: "189 dark utilities across 30 files, bound
+ * to `[data-theme=dark]`, opening dark with the OS overruled" is something a person can
+ * confirm or correct. "This is a dark product" is a claim they have to take on faith.
+ */
+export function describeSignals(s) {
+    const out = [];
+    const t = s.theme;
+    if (t.darkUtilities > 0) {
+        out.push(`${t.darkUtilities} dark utilities across ${t.darkFiles} file${t.darkFiles === 1 ? "" : "s"} - so a second scheme is real here, not aspirational.`);
+    }
+    else if (t.prefersColorScheme > 0) {
+        out.push(`no dark utilities, but ${t.prefersColorScheme} \`prefers-color-scheme\` rule${t.prefersColorScheme === 1 ? "" : "s"} - the second scheme lives in CSS rather than in class names.`);
+    }
+    else {
+        out.push("no dark utilities and no `prefers-color-scheme` - one scheme, and adding a second is a decision rather than a discovery.");
+    }
+    if (t.library) {
+        const bits = [`switched by ${t.library}`];
+        if (t.attribute)
+            bits.push(`bound to \`${t.attribute}\``);
+        if (t.defaultTheme)
+            bits.push(`opening ${t.defaultTheme}`);
+        if (t.enableSystem === false)
+            bits.push("with the OS overruled");
+        if (t.enableSystem === true)
+            bits.push("with the OS allowed a vote");
+        out.push(`${bits.join(", ")}.`);
+    }
+    if (t.htmlCarries.length > 0) {
+        out.push(`\`<html>\` carries ${t.htmlCarries.map((a) => `\`${a}\``).join(" ")} - which is the ancestor every dark rule of theirs matches, and therefore the one ours must match.`);
+    }
+    for (const family of ["primitives", "motion", "icons", "charts", "editors"]) {
+        const found = s.libraries.filter((l) => l.family === family);
+        if (found.length === 0)
+            continue;
+        out.push(`${family}: ${found.map((l) => `${l.name}${l.version ? ` ${l.version}` : ""} (${l.packages ? `${l.packages} packages, ` : ""}${l.files} file${l.files === 1 ? "" : "s"})`).join(", ")}`);
+    }
+    for (const c of s.conflicts) {
+        // The count is read off the list rather than written into the sentence: it said "TWO"
+        // over three names, which is the kind of small lie that costs the next sentence its
+        // credibility (probe, 01/08).
+        const list = c.names.length === 2
+            ? c.names.join(" and ")
+            : `${c.names.slice(0, -1).join(", ")} and ${c.names[c.names.length - 1]}`;
+        out.push(`${c.names.length} ${c.family} LIBRARIES: ${list}. The same job under more than one name, and the extras are weight in the bundle for nothing. Worth your attention; not ours to decide.`);
+    }
+    return out;
+}

package/dist/doctor/transcribe.js

@@ -447,6 +447,22 @@ function resolveArbitrary(inner, declared) {
         return null;
     const v = /^var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,[^)]*)?\)$/.exec(raw);
     if (!v) {
+        /**
+         * `[--text-body-s]` IS the var() shorthand - Tailwind v3 defined it that way, so the
+         * author wrote a working thing once. v4 dropped the shorthand, which is why their
+         * inputs render at the inherited size today; the token they NAMED is still the
+         * intent, and a recipe is the rules to rebuild the component, not a photograph of
+         * the regression. Their own defect still gets reported - see `unreadable`.
+         *
+         * A bare `--name` they never declared resolves to nothing under either semantics,
+         * and carrying it would emit `font-size: --x`, which is invalid CSS.
+         */
+        if (raw.startsWith("--")) {
+            const name = raw.split(",")[0].trim();
+            return declared.has(name)
+                ? { value: tokenRefFor(name), token: name }
+                : null;
+        }
         // A literal in brackets is still a real value somebody typed.
         return /[<>{}@;]/.test(raw) ? null : { value: raw };
     }
@@ -540,12 +556,18 @@ export function readInlineStyle(source) {
 }
 /** Properties React leaves unitless, so a bare number is not pixels. */
 const UNITLESS = /^(opacity|zIndex|flex|flexGrow|flexShrink|order|lineHeight|fontWeight|zoom|columnCount|fillOpacity|strokeOpacity|animationIterationCount)$/;
+/**
+ * A prefix this reader claims to understand. A class that starts with one of these and
+ * still reads as nothing is a failed DESIGN read, not layout plumbing.
+ */
+const DESIGN_PREFIX = /^(?:p|px|py|pt|pr|pb|pl|m|mx|my|gap|rounded|text|font|bg|border|shadow|w|h|size|min-w|min-h|max-w|max-h|leading|tracking|opacity|fill|stroke)-\S/;
 export function transcribe(classes, declared) {
     const out = {
         base: {},
         states: {},
         dark: {},
         skipped: [],
+        unreadable: [],
         literals: [],
         fromToken: 0,
         fromLiteral: 0,
@@ -585,7 +607,16 @@ export function transcribe(classes, declared) {
                 out.skipped.push(cls);
             continue;
         }
-        if (!decl || !target)
+        if (!decl) {
+            // The prefix says design intent; the rest resolved to nothing. Malformed in their
+            // source more often than not - `p-spacing-sm` for `p-sm` - and a silent drop here
+            // is how a menu popup ships with no padding and nobody is told.
+            if (DESIGN_PREFIX.test(utility) && !out.unreadable.includes(cls)) {
+                out.unreadable.push(cls);
+            }
+            continue;
+        }
+        if (!target)
             continue;
         /**
          * EVERYTHING IT READS TRAVELS, literals included - as DATA.

package/dist/skill-import.js

@@ -237,13 +237,19 @@ This is the field that matters most and the one only you can fill. The ladder ca
 places no token reader sees. A real library declared nine near-blacks and five light greys in
 one \`:root\` block, and the import handed its near-black dashboard a white page.
 
-Go and look:
+**DO NOT GO LOOKING. It is already counted**, under "What was countable, counted" in the
+census output:
 
-- \`grep -rn "dark:" --include=*.tsx\` - Tailwind's dark variant, invisible to a token reader
-- a theme provider, \`useTheme\`, \`next-themes\`, a \`data-theme\` attribute, a toggle in the shell
-- \`prefers-color-scheme\` in the CSS
-- the root layout: what class or attribute does \`<html>\` or \`<body>\` carry by default
-- failing all of that, open the app's main page component and see what it paints
+\`\`\`
+782 dark utilities across 79 files - so a second scheme is real here, not aspirational.
+switched by a ThemeProvider of their own, bound to data-theme, opening dark, with the
+  OS overruled.
+html carries lang="en" data-theme="dark" - which is the ancestor every dark rule of
+  theirs matches, and therefore the one ours must match.
+\`\`\`
+
+That is a real run. Your job is to CONFIRM OR CORRECT it, not to reproduce it - and a sweep
+would bring back a different slice than the next one, which is the worse property of the two.
 
 \`has: ["dark"]\` on a dark-only product is the right answer. It is better than filling a light
 slot on their behalf, and it makes adding light a deliberate act they take later.
@@ -537,6 +543,20 @@ extensions are configured at construction, not toggled later
 of their manifest and attaches it (\`"^2.1.0 in packages/ui"\`), so the rule does not go stale the
 day they upgrade and the information is not lost either.
 
+### If \`recipe_vocabulary\` is missing, the MCP registration is stale
+
+A real run reported "recipe_vocabulary and validate_recipe do not exist on this server" and
+sent every anatomy unvalidated - the repo's \`.mcp.json\` pinned \`synthesisui@0.16.78\` while
+the import itself ran unpinned at latest: **two CLI versions in one repo, in one run** (dono,
+01/08). Before concluding a tool does not exist, check the registration:
+
+\`\`\`json
+"args": ["synthesisui@latest", "mcp"]
+\`\`\`
+
+Tell the person to fix the pin and restart the server. Do not work around a stale server by
+skipping validation - unvalidated is how correct work arrives as nothing.
+
 ### Ask what a recipe can hold, BEFORE you write one
 
 \`\`\`
@@ -634,6 +654,16 @@ what shows when it is missing a missing asset must never look broken
 
 ### What the CLI now reads for you, so do not spend a turn on it
 
+**The rule under all of this: you are given EVIDENCE and asked to DECIDE.** You are never
+given a question and asked to search. A grep is a tool call whose entire output lands in your
+context to answer something that is one number, and two readers sweeping the same repo bring
+back different slices - so the answer changes between runs, which is the part that actually
+costs.
+
+Measured on a real run: the census counts the theme signals, the libraries and their
+versions, and the conflicts. The reader that swept for them anyway spent a dozen shell calls
+to arrive at a subset of what was already on screen.
+
 Four things are read deterministically from the source. Reporting them back as if you
 found them wastes a turn and risks contradicting the measurement:
 
@@ -642,6 +672,10 @@ found them wastes a turn and risks contradicting the measurement:
 - **whether a component forwards the rest of its props**, and which it names
 - **which components appear inside which** at their call sites, as pairs
 - **the folder architecture**, and it will ask you which one has priority
+- **the theme**: how many dark utilities, in how many files, which library switches it, which
+  attribute it is bound to, what \`<html>\` carries, and how many \`prefers-color-scheme\` rules
+- **the libraries and their versions** - motion, icons, primitives, charts, editors - with the
+  file count for each, and a CONFLICT when one job is done by more than one of them
 - **which of your components are ours**, matched against the LIVE catalogue rather than a
   list baked into the CLI. If a run says it fell back to the built-in names, the match is a
   smaller answer than it should be and the reason is on screen
@@ -649,6 +683,26 @@ found them wastes a turn and risks contradicting the measurement:
 What is still yours: the anatomy tree, the part names, the frontiers, the roles, the
 concept, and the rules that are not about a class name.
 
+### A scale's INTENT is a rule, and their docs already wrote it
+
+A three-step spacing scale with documented meaning - sm "close UI relationships", md
+"standard internal padding", lg "layout gutters" - carries a law nothing else expresses:
+**this system has exactly three steps, and a fourth is a mistake.** A real import read the
+scale and lost the sentence (dono, 01/08).
+
+When their docs (a \`Geometry.mdx\`, a design-tokens page, comments beside the \`@theme\`)
+state what a step is FOR, send it as system-wide rules - \`applies: []\`, \`fact: true\`, the
+doc as evidence:
+
+\`\`\`
+this system's spacing has exactly three steps - sm for close relationships inside a
+control, md for standard internal padding, lg for layout gutters. A fourth step is a
+mistake, not a gap (Geometry.mdx)
+\`\`\`
+
+\`applies: []\` is what makes it reach CLAUDE.md and every prompt after - the same route the
+architecture rule travels.
+
 ### How much to send
 
 Send an anatomy for **every component with visible structure**, which is nearly all of them. A

package/package.json

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