synthesisui 0.13.0 → 0.14.0

package/dist/commands/add.js

@@ -206,6 +206,12 @@ export async function add(slug, opts) {
         console.log(line(`   Prefer next/font or self-hosting? Fine - just register these exact families: ${customFontFamilies(families).join(", ")}.`));
     }
     console.log(section("Next"));
+    // FIRST, and before anything that assumes the setup worked. The block above
+    // is four manual edits across two files, one of them with a relative path
+    // the command itself has to warn about. Without a way to check, the person
+    // does not know whether they finished - and the next thing they see is a
+    // coverage number that reads 0% when an import is missing.
+    console.log(line(`synthesisui doctor                    confirm the setup above actually took`));
     console.log(line(`synthesisui component ${payload.slug} button    bring a component in as YOUR code`));
     console.log(line(`synthesisui template ${payload.slug} landing    materialize a whole page`));
     console.log("");

package/dist/commands/doctor.js

@@ -257,11 +257,32 @@ export async function doctor(opts) {
     const overrides = [];
     const used = new Map();
     const known = new Set(recipes.keys());
+    /**
+     * INSTALLED IS NOT THE SAME AS WORKING.
+     *
+     * `init` ends in four manual edits across two files. Skip them - or get the
+     * relative path in the import wrong, which the command itself warns about -
+     * and the next run reports "Token coverage 0%" with no explanation
+     * (reproduced 27/07 on a fresh project). The tool knows the system is
+     * installed, because it just read 85 tokens out of it, and reports a number
+     * that reads as failure when the truth is an unfinished setup.
+     *
+     * Nobody debugs from 0%. They conclude the product does not work.
+     */
+    const wiring = { imported: false, scoped: false };
     for await (const file of scopes.length > 0 ? walkAll(scopes) : walk(root)) {
         const src = await readFile(file, "utf8").catch(() => "");
         if (!src)
             continue;
         const rel = relative(root, file);
+        // The two facts that decide whether an installed system reaches the
+        // browser at all. Free: these files are already open and in memory.
+        if (table.slug) {
+            if (src.includes(`_synthesisui/ds/${table.slug}/tokens.css`))
+                wiring.imported = true;
+            if (src.includes(`data-ds="${table.slug}"`))
+                wiring.scoped = true;
+        }
         reports.push(scanSource(rel, src, table));
         if (recipes.size > 0) {
             for (const o of findOverrides(src, recipes))
@@ -329,6 +350,25 @@ export async function doctor(opts) {
     // 0 of 0 is not a perfect score, it is an empty measurement - printing a
     // full bar there would be the report's first lie.
     const measurable = d.tokenUses + d.findings.length > 0;
+    // Before the number, because the number is the thing that misleads. An
+    // installed-but-unwired system reads 0%, and 0% reads as "broken product"
+    // rather than "one import missing".
+    const unwired = table.source === "installed" && (!wiring.imported || !wiring.scoped);
+    if (unwired) {
+        console.log("");
+        console.log(body(`${table.name ?? table.slug} is installed - but not wired up yet.`));
+        console.log("");
+        console.log(body(wiring.imported
+            ? `  ✓ some stylesheet imports _synthesisui/ds/${table.slug}/tokens.css`
+            : `  ✗ no stylesheet imports _synthesisui/ds/${table.slug}/tokens.css`));
+        console.log(body(wiring.scoped
+            ? `  ✓ data-ds="${table.slug}" found`
+            : `  ✗ no element carries data-ds="${table.slug}"`));
+        console.log("");
+        console.log(body(`Until both are true, none of the ${table.byName.size} tokens reach the browser`));
+        console.log(body("and the number below cannot mean anything."));
+        console.log(body("The exact snippets are in the output of `init`."));
+    }
     if (hasSystem && measurable) {
         console.log("");
         console.log(body(`Token coverage  ${meter(d.coverage)}  ${String(d.coverage).padStart(3)}%`));
@@ -661,6 +701,42 @@ export async function doctor(opts) {
         }
         console.log("");
         console.log(body("synthesisui doctor --verbose   every finding, file by file"));
+        /**
+         * THE READER WHO GOT A NUMBER AND NOWHERE TO GO.
+         *
+         * Someone with no system at all is told to start one. Someone running OUR
+         * system has commands everywhere. The person in between - who already owns
+         * a design system, which is precisely the ICP - got the report and silence,
+         * and closed the terminal (walked 27/07).
+         *
+         * The sentence follows from THEIR number rather than pitching: the value
+         * is not that we would name these, it is that their agent has no way to
+         * know they should be named. That is also the line worth pasting into a
+         * thread, which is the other job this paragraph does.
+         */
+        if (table.source === "yours") {
+            const named = d.findings.filter((f) => f.token).length;
+            const anonymous = d.findings.length - named;
+            console.log("");
+            console.log(body(named > 0
+                ? `${named} of these already have a name in your own system.`
+                : "None of these have a name in your system yet."));
+            if (anonymous > 0) {
+                console.log(body(`The other ${anonymous} do not - and your coding agent has no way to know they should.`));
+            }
+            console.log("");
+            // Careful about what is being offered. This reader ALREADY has a design
+            // system, so "install ours" would mean replacing theirs, and a CTA that
+            // pretends otherwise is the kind of confident overclaim that costs
+            // trust the first time somebody follows it. What they are missing is
+            // not tokens - it is a contract their agent reads before writing UI.
+            console.log(body("Your tokens exist. What your agent is missing is a contract:"));
+            console.log(body("rules it reads BEFORE writing UI, and a manifest of what exists."));
+            console.log("");
+            console.log(snippet(["npx synthesisui@latest init --ds <slug>"]));
+            console.log(body("starts you on a system that ships one - browse them at"));
+            console.log(body("https://www.synthesisui.com/gallery"));
+        }
         console.log("");
     }
     if (opts.strict) {

package/package.json

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