synthesisui 0.16.86 → 0.16.88

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

@@ -799,6 +799,31 @@ export async function takeCensus(root, opts) {
             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("");
@@ -1590,6 +1615,7 @@ async function resolveReadParts(census, root) {
                 dark: {},
                 states: {},
                 skipped: [],
+                unreadable: [],
                 literals: [],
                 fromToken: 0,
                 fromLiteral: 0,

package/dist/doctor/css-modules.js

@@ -527,6 +527,11 @@ function tokenRefFor(name) {
         return `{spacing.${bare.slice(8)}}`;
     if (bare.startsWith("shadow-"))
         return `{shadow.${bare.slice(7)}}`;
+    if (bare.startsWith("background-image-gradient-")) {
+        return `{gradients.${bare.slice("background-image-gradient-".length)}}`;
+    }
+    if (bare.startsWith("gradient-"))
+        return `{gradients.${bare.slice(9)}}`;
     if (bare.startsWith("text-"))
         return `{typography.scale.${bare.slice(5)}.fontSize}`;
     if (bare.startsWith("font-"))

package/dist/doctor/transcribe.js

@@ -271,8 +271,22 @@ export function readUtility(utility, declared) {
     const bracket = core.indexOf("-[");
     if (bracket !== -1 && core.endsWith("]")) {
         const head = core.slice(0, bracket);
-        const inner = core.slice(bracket + 2, -1);
+        let inner = core.slice(bracket + 2, -1);
+        /**
+         * `bg-[image:var(--gradient-ui)]` - the datatype hint says which property, in
+         * Tailwind's own syntax. Two real usages of the signature gradient wear exactly
+         * this spelling (dono, 01/08).
+         */
+        let hinted = null;
+        const hint = /^(image|color|length|size|position|url):/.exec(inner);
+        if (hint) {
+            hinted = hint[1] === "image" ? "backgroundImage" : null;
+            inner = inner.slice(hint[0].length);
+        }
         const value = resolveArbitrary(inner, declared);
+        if (hinted && value) {
+            return { property: hinted, value: value.value, token: value.token };
+        }
         /**
          * `text-[…]` IS AMBIGUOUS AND THE VALUE DECIDES.
          *
@@ -299,6 +313,24 @@ export function readUtility(utility, declared) {
     const rest = core.slice(dash + 1);
     const colorProp = COLOR_PROPERTY[prefix];
     if (colorProp) {
+        /**
+         * `bg-gradient-ui` is the utility Tailwind v4 mints from their
+         * `--background-image-gradient-ui`, and the colour path read `gradient-ui` as a
+         * colour name and found nothing. The token they declared is the answer - and
+         * `bg-gradient-to-r` must NOT land here, because nobody declares `--gradient-to-r`;
+         * it falls through to the stop composer below.
+         */
+        if (prefix === "bg" && rest.startsWith("gradient-")) {
+            const name = rest.slice(9);
+            if (declared.has(`--background-image-gradient-${name}`) ||
+                declared.has(`--gradient-${name}`)) {
+                return {
+                    property: "backgroundImage",
+                    value: `{gradients.${name}}`,
+                    token: `--gradient-${name}`,
+                };
+            }
+        }
         // Their own token first: `--color-ocean-500` for `bg-ocean-500`, which is
         // exactly how Tailwind v4's `@theme` publishes it.
         const own = `--color-${rest}`;
@@ -447,6 +479,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 };
     }
@@ -472,6 +520,14 @@ function tokenRefFor(name) {
         return `{spacing.${bare.slice(8)}}`;
     if (bare.startsWith("shadow-"))
         return `{shadow.${bare.slice(7)}}`;
+    // `--gradient-ui` and `--background-image-gradient-ui` are one token in two
+    // spellings - Tailwind v4's utility namespace wraps the first. Both reach
+    // `{gradients.ui}`, which is where the census files them.
+    if (bare.startsWith("background-image-gradient-")) {
+        return `{gradients.${bare.slice("background-image-gradient-".length)}}`;
+    }
+    if (bare.startsWith("gradient-"))
+        return `{gradients.${bare.slice(9)}}`;
     if (bare.startsWith("text-")) {
         return `{typography.scale.${bare.slice(5)}.fontSize}`;
     }
@@ -540,18 +596,110 @@ 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/;
+/** `to-r` → `to right`: Tailwind's eight directions, spelled as CSS reads them. */
+const GRADIENT_DIRECTION = {
+    "to-t": "to top",
+    "to-tr": "to top right",
+    "to-r": "to right",
+    "to-br": "to bottom right",
+    "to-b": "to bottom",
+    "to-bl": "to bottom left",
+    "to-l": "to left",
+    "to-tl": "to top left",
+};
+/** A colour stop's value: their token first, Tailwind's table second, a literal last. */
+function stopValue(raw, declared) {
+    if (declared.has(`--color-${raw}`))
+        return refFor(raw);
+    if (TAILWIND_COLOR[raw])
+        return TAILWIND_COLOR[raw];
+    if (/^#[0-9a-fA-F]{3,8}$/.test(raw) ||
+        raw === "transparent" ||
+        raw === "white" ||
+        raw === "black") {
+        return raw;
+    }
+    return null;
+}
+/**
+ * A COMPOSED GRADIENT is one decision spread across four classes.
+ *
+ * `bg-gradient-to-r from-ocean-500 via-vivid-pink-500 to-purple-400` is nine real
+ * elements in one repo, and every piece read as nothing - `from-` is not a property
+ * table's prefix. Composed here because only the whole class list can see all the
+ * pieces at once; the stops resolve to their own tokens, so the gradient re-themes.
+ *
+ * `from-bottom-2` taught the guard: `slide-in-from-bottom-2` fragments wear the same
+ * prefix, so stops only count when a `bg-gradient-to-*` sits in the SAME class list -
+ * and a direction whose stops do not resolve is reported, never half-built.
+ */
+function composeGradient(utilities, declared) {
+    const dir = utilities.find((u) => GRADIENT_DIRECTION[u.replace(/^bg-gradient-/, "")] &&
+        u.startsWith("bg-gradient-"));
+    if (!dir)
+        return { value: null, consumed: new Set(), broken: [] };
+    const direction = GRADIENT_DIRECTION[dir.replace(/^bg-gradient-/, "")];
+    const consumed = new Set([dir]);
+    const broken = [];
+    const stops = [];
+    for (const kind of ["from", "via", "to"]) {
+        const cls = utilities.find((u) => u.startsWith(`${kind}-`));
+        if (!cls)
+            continue;
+        consumed.add(cls);
+        const value = stopValue(cls.slice(kind.length + 1), declared);
+        if (value)
+            stops.push(value);
+        else
+            broken.push(cls);
+    }
+    if (stops.length < 2 || broken.length > 0) {
+        return {
+            value: null,
+            consumed,
+            broken: broken.length > 0 ? broken : [dir],
+        };
+    }
+    return {
+        value: `linear-gradient(${direction}, ${stops.join(", ")})`,
+        consumed,
+        broken,
+    };
+}
 export function transcribe(classes, declared) {
     const out = {
         base: {},
         states: {},
         dark: {},
         skipped: [],
+        unreadable: [],
         literals: [],
         fromToken: 0,
         fromLiteral: 0,
     };
+    /**
+     * The composed gradient first: it is one decision spread across four classes, and
+     * only the whole list sees all the pieces. Base-level only - a per-scheme stop
+     * (`dark:from-x`) is a condition this pass does not attempt, and it lands in
+     * `unreadable` below rather than half-composing.
+     */
+    const bareUtilities = classes
+        .filter((cls) => parseClass(cls).modifiers.length === 0)
+        .map((cls) => parseClass(cls).utility);
+    const gradient = composeGradient(bareUtilities, declared);
+    if (gradient.value)
+        out.base.backgroundImage = gradient.value;
+    for (const broke of gradient.broken)
+        out.unreadable.push(broke);
     for (const cls of classes) {
         const { modifiers, utility } = parseClass(cls);
+        if (gradient.consumed.has(utility) && modifiers.length === 0)
+            continue;
         const isDark = modifiers.includes("dark");
         const rest = modifiers.filter((m) => m !== "dark");
         // THE SLOT IS DECIDED BEFORE THE VALUE IS READ. Resolving first meant a
@@ -585,7 +733,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

@@ -543,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
 
 \`\`\`
@@ -658,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
+- **their gradients**, as tokens: \`--gradient-ui\` and its Tailwind-namespace twin land on
+  \`{gradients.ui}\`, composed \`bg-gradient-to-r from-x to-y\` stops become one gradient in
+  their own colour tokens, and a signature gradient is no longer a string trapped in class
+  names
 - **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
@@ -669,6 +687,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.86",
+  "version": "0.16.88",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {