synthesisui 0.13.0 → 0.15.0

package/dist/claude-md.js

@@ -18,7 +18,12 @@ async function readInstalled(projectRoot) {
         try {
             const raw = await readFile(join(dsDir, slug, ".lock"), "utf8");
             const lock = JSON.parse(raw);
-            locks.push({ slug: lock.slug, name: lock.name, version: lock.version });
+            locks.push({
+                slug: lock.slug,
+                name: lock.name,
+                version: lock.version,
+                adopted: lock.adopted === true,
+            });
         }
         catch {
             // folder without a valid .lock - ignore
@@ -87,24 +92,41 @@ async function renderRegion(projectRoot, installed) {
     }
     const sections = [];
     for (const ds of installed) {
-        const head = `- **${ds.name}** (\`${ds.slug}\`, v${ds.version}) - guide: \`_synthesisui/ds/${ds.slug}/v${ds.version}/GUIDE.md\``;
+        // An adopted system has no published version and therefore no `v<n>/`
+        // folder - pointing the agent at one points it at a file that does not
+        // exist (caught by running it, 27/07).
+        const head = ds.adopted
+            ? `- **${ds.name}** (\`${ds.slug}\`, adopted from this repo) - guide: \`_synthesisui/ds/${ds.slug}/GUIDE.md\``
+            : `- **${ds.name}** (\`${ds.slug}\`, v${ds.version}) - guide: \`_synthesisui/ds/${ds.slug}/v${ds.version}/GUIDE.md\``;
         const manifest = await readManifest(projectRoot, ds);
         sections.push(manifest ? `${head}\n${manifest}` : head);
     }
-    const body = `## Design Systems (via SynthesisUI)
-
-This project uses design system(s) brought in by the \`synthesisui\` CLI. **When creating or editing
-components, read the system's GUIDE.md and follow it:** use only semantic tokens
+    // Two truths, and asserting the wrong one misleads the agent every time it
+    // writes a line. An INSTALLED system speaks `--ds-*` and is scoped with
+    // `data-ds`; an ADOPTED one is the project's own vocabulary, already wired,
+    // with no `data-ds` anywhere to scope to.
+    const onlyAdopted = installed.every((d) => d.adopted);
+    const rule = onlyAdopted
+        ? `**When creating or editing components, read the system's GUIDE.md and follow it:** use the
+project's OWN custom properties, exactly as the guide lists them. Do not write raw colours,
+spacings or radii that a token already covers, and do not invent a new token silently - say so
+instead, because a new token is a decision for a person to make. There is no component
+manifest for an adopted system - the tokens ARE the contract. Run \`synthesisui doctor\` to see
+how much of the shipped UI already resolves to them.`
+        : `**When creating or editing components, read the system's GUIDE.md and follow it:** use only semantic tokens
 (\`var(--ds-color-semantic-*)\`, \`--ds-spacing-*\`, etc.), scope the UI with \`data-ds="<slug>"\`,
 and reuse the \`.ds-*\` classes. Do not use raw values outside the system's scale. **Before
 creating any UI element, check the component manifest below - if it exists, use or extend
 it (\`synthesisui component <slug> <name>\` materializes it as your code).** To review a
 component, create an isolated sample page (e.g. \`app/synthesisui-samples/<component>/\`) - do not
-apply it to real production pages unless asked.
+apply it to real production pages unless asked.`;
+    const body = `## Design Systems (via SynthesisUI)
+
+This project uses design system(s) tracked by the \`synthesisui\` CLI. ${rule}
 
 ${sections.join("\n")}
 
-_Block managed by the CLI - do not edit by hand; run \`synthesisui add <slug>\` to update._`;
+_Block managed by the CLI - do not edit by hand; run \`synthesisui ${onlyAdopted ? "adopt --write" : "add <slug>"}\` to update._`;
     return `${START}\n${body}\n${END}`;
 }
 /**

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/adopt.js

@@ -0,0 +1,207 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { syncClaudeMd } from "../claude-md.js";
+import { parseRootTokens } from "../doctor/tokens.js";
+import { body, section, snippet } from "../output.js";
+import { walk } from "./doctor.js";
+/**
+ * `synthesisui adopt` - the system somebody ALREADY has, made legible.
+ *
+ * The whole product assumed you start from nothing. `init` installs OUR tokens
+ * and therefore needs four manual edits - import, scope with data-ds, wire
+ * fonts - which is where people give up (walked 27/07, the next run reads 0%).
+ *
+ * The reader who feels our pitch hardest does not need any of that. Their
+ * `--acme-*` tokens are already in `:root` and already painting the screen.
+ * What is missing is not code, it is the CONTRACT: the file their coding agent
+ * reads before writing UI.
+ *
+ * So this command writes NO CSS, and that is the point rather than a
+ * limitation:
+ *
+ *     init     writes CSS  → needs wiring → 4 edits → 0% if one is wrong
+ *     adopt    writes none → no wiring    → works on the first command
+ *
+ * THE PROMISE, printed rather than buried in docs: it reads your code and
+ * rewrites none of it; everything it creates lives in `_synthesisui/` and
+ * leaves with `clean`; your tokens keep your names.
+ *
+ * Dry by default. A command that edits somebody's repository on first run is
+ * not a command that people with a system in production ever try.
+ */
+const SCOPE_HINT = ":root, html, :host and @theme";
+/** Group by the prefix an author actually used, which is how they think of it. */
+function byKind(tokens) {
+    const kinds = new Map();
+    const guess = (n) => /color|colour|bg|background|fg|foreground|surface|canvas|ink|brand/.test(n)
+        ? "colour"
+        : /space|spacing|gap|inset/.test(n)
+            ? "spacing"
+            : /radius|round|corner/.test(n)
+                ? "radius"
+                : /font|type|text|leading|tracking|weight/.test(n)
+                    ? "type"
+                    : /shadow|elevation/.test(n)
+                        ? "shadow"
+                        : /duration|ease|motion|transition/.test(n)
+                            ? "motion"
+                            : "other";
+    for (const name of tokens.keys()) {
+        const k = guess(name);
+        kinds.set(k, (kinds.get(k) ?? 0) + 1);
+    }
+    return [...kinds.entries()].sort((a, b) => b[1] - a[1]);
+}
+/** The commonest `--<prefix>-` in their own names - the slug they already use. */
+function guessSlug(tokens, pkgName) {
+    const counts = new Map();
+    for (const n of tokens.keys()) {
+        const m = /^--([a-z0-9]+)-/.exec(n);
+        if (m)
+            counts.set(m[1], (counts.get(m[1]) ?? 0) + 1);
+    }
+    const top = [...counts.entries()].sort((a, b) => b[1] - a[1])[0];
+    // Only trust the prefix when it actually dominates; a repo whose tokens are
+    // `--color-*`, `--space-*` has no brand prefix and the package name is the
+    // better answer.
+    if (top &&
+        top[1] >= tokens.size * 0.5 &&
+        !/^(color|space|font|size)$/.test(top[0])) {
+        return top[0];
+    }
+    return (pkgName
+        .replace(/^@[^/]+\//, "")
+        .replace(/[^a-z0-9]+/gi, "-")
+        .replace(/^-|-$/g, "")
+        .toLowerCase() || "my-system");
+}
+async function findTokens(root, only) {
+    let files = 0;
+    const from = [];
+    const all = new Map();
+    const take = async (file) => {
+        const css = await readFile(file, "utf8").catch(() => "");
+        if (!css)
+            return;
+        files++;
+        const found = parseRootTokens(css);
+        if (found.size === 0)
+            return;
+        from.push(`${relative(root, file)} (${found.size})`);
+        for (const [k, v] of found)
+            if (!all.has(k))
+                all.set(k, v);
+    };
+    if (only) {
+        await take(resolve(root, only));
+    }
+    else {
+        for await (const f of walk(root)) {
+            if (/\.(css|scss|sass|less)$/i.test(f))
+                await take(f);
+        }
+    }
+    return { tokens: all, files, from };
+}
+/** The contract. Names THEIR tokens - there is no translation layer. */
+function guide(name, slug, tokens) {
+    const lines = [...tokens.entries()].map(([k, v]) => `  ${k}: ${v};`);
+    return `# ${name} - the contract your agent follows
+
+Adopted from this repository by \`synthesisui adopt\`. These are YOUR tokens,
+under YOUR names - nothing was renamed and no stylesheet was rewritten.
+
+## The rule
+
+When writing or editing UI in this project, use these custom properties.
+Do not write raw colours, spacings or radii that a token already covers.
+
+    ✗  background: #3b82f6
+    ✓  background: var(--${slug}-color-primary)
+
+If a value has no token, say so instead of inventing one silently - a new
+token is a decision for a person to make.
+
+## The tokens (${tokens.size})
+
+\`\`\`css
+:root {
+${lines.join("\n")}
+}
+\`\`\`
+
+## Checking your work
+
+    npx synthesisui@latest doctor
+
+Reports how much of the shipped UI resolves to these tokens, and names the
+token for any hardcoded value that already has one.
+`;
+}
+export async function adopt(opts) {
+    const root = resolve(opts.dir ?? process.cwd());
+    const pkg = await readFile(join(root, "package.json"), "utf8")
+        .then((r) => JSON.parse(r))
+        .catch(() => ({ name: undefined }));
+    const found = await findTokens(root, opts.tokens);
+    console.log(section("Adopt"));
+    if (found.tokens.size === 0) {
+        // Never "failed to adopt". Always: what was looked for, where, and the
+        // next thing to type. Being stuck with no move is the worst outcome.
+        console.log(body(`Looked in ${SCOPE_HINT} across ${found.files} stylesheet${found.files === 1 ? "" : "s"} and found no custom properties.`));
+        console.log("");
+        console.log(body("If your tokens live somewhere this did not reach:"));
+        console.log(snippet(["npx synthesisui@latest adopt --tokens <path/to.css>"]));
+        console.log("");
+        console.log(body("If you do not have a system yet, start from one:"));
+        console.log(body("https://www.synthesisui.com/gallery"));
+        return;
+    }
+    const slug = opts.slug ?? guessSlug(found.tokens, pkg.name ?? "");
+    const name = (pkg.name ?? slug).replace(/^@[^/]+\//, "");
+    const dir = join(root, "_synthesisui", "ds", slug);
+    console.log(body(`Reading your system … ${found.files} stylesheet${found.files === 1 ? "" : "s"}, ${found.tokens.size} tokens found`));
+    console.log("");
+    for (const [kind, n] of byKind(found.tokens)) {
+        console.log(body(`  ${kind.padEnd(10)} ${String(n).padStart(3)}`));
+    }
+    console.log("");
+    for (const f of found.from.slice(0, 4))
+        console.log(body(`  from ${f}`));
+    if (found.from.length > 4)
+        console.log(body(`  and ${found.from.length - 4} more`));
+    if (!opts.write) {
+        console.log("");
+        console.log(body("Would create (nothing written yet):"));
+        console.log(body(`  _synthesisui/ds/${slug}/system.json    your system, described`));
+        console.log(body(`  _synthesisui/ds/${slug}/GUIDE.md       what your agent reads`));
+        console.log(body("  CLAUDE.md                              a managed block pointing at it"));
+        console.log("");
+        console.log(body("Your stylesheets are not touched. Nothing outside"));
+        console.log(body("_synthesisui/ is written, and `clean` removes all of it."));
+        console.log("");
+        console.log(snippet([
+            `npx synthesisui@latest adopt --write${opts.slug ? ` --slug ${slug}` : ""}`,
+        ]));
+        console.log(body(`writes it as "${slug}" - pass --slug to name it differently`));
+        return;
+    }
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, "system.json"), `${JSON.stringify({
+        meta: { name, slug, adopted: true, source: "repository" },
+        tokens: Object.fromEntries(found.tokens),
+    }, null, 2)}\n`, "utf8");
+    await writeFile(join(dir, "GUIDE.md"), guide(name, slug, found.tokens), "utf8");
+    // `version: 0` marks a system nobody published - the doctor and CLAUDE.md
+    // read this to know it is adopted rather than installed.
+    await writeFile(join(dir, ".lock"), `${JSON.stringify({ slug, name, version: 0, adopted: true }, null, 2)}\n`, "utf8");
+    await syncClaudeMd(root);
+    console.log("");
+    console.log(body(`✓ _synthesisui/ds/${slug}/  written`));
+    console.log(body("✓ CLAUDE.md              managed block added"));
+    console.log("");
+    console.log(body("Your agent now knows your system. Nothing of yours changed."));
+    console.log("");
+    console.log(snippet(["npx synthesisui@latest doctor"]));
+    console.log(body("see what it makes measurable"));
+}

package/dist/commands/doctor.js

@@ -40,7 +40,7 @@ const SKIP = new Set([
     // Our own installed artifacts are the answer, not the problem.
     "_synthesisui",
 ]);
-async function* walk(dir) {
+export async function* walk(dir) {
     // `readdir`'s overloads infer a Buffer-named Dirent without an explicit
     // encoding; naming it keeps `e.name` a string.
     const entries = await readdir(dir, {
@@ -63,7 +63,7 @@ async function* walk(dir) {
 }
 /** The same walk over several roots, in the order the caller named them. A
  *  single file passed as a scope is read as itself. */
-async function* walkAll(roots) {
+export async function* walkAll(roots) {
     for (const r of roots) {
         if (EXTS.some((x) => r.endsWith(x))) {
             yield r;
@@ -91,6 +91,7 @@ async function loadSystem(root) {
     // reading them all is both correct and what the running app actually sees.
     let css = "";
     let lock = null;
+    let adopted = false;
     const recipes = new Map();
     const documents = [];
     for (const slug of slugs) {
@@ -118,6 +119,24 @@ async function loadSystem(root) {
             }
         }
         css += `\n${real || root}`;
+        // An ADOPTED system has no tokens.css of ours - `adopt` deliberately
+        // writes no CSS, because the project's own stylesheet already works. Its
+        // vocabulary lives in system.json, and without this the doctor falls
+        // through to harvesting and then offers to install a system to somebody
+        // who just adopted one (caught running it, 27/07).
+        if (mine?.adopted) {
+            const raw = await readFile(join(dir, "system.json"), "utf8").catch(() => "");
+            try {
+                const parsed = JSON.parse(raw);
+                for (const [k, v] of Object.entries(parsed.tokens ?? {})) {
+                    css += `\n:root { ${k}: ${v}; }`;
+                }
+                adopted = true;
+            }
+            catch {
+                // Unreadable system.json costs the naming, not the run.
+            }
+        }
         const docRaw = mine?.version
             ? await readFile(join(dir, `v${mine.version}`, "design-system.json"), "utf8").catch(() => "")
             : "";
@@ -135,7 +154,11 @@ async function loadSystem(root) {
             }
         }
     }
-    return { table: buildTable({ css, lock }), recipes, documents };
+    return {
+        table: buildTable({ css, lock, source: adopted ? "adopted" : "installed" }),
+        recipes,
+        documents,
+    };
 }
 /**
  * The project's OWN vocabulary, when we did not put one there.
@@ -257,11 +280,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))
@@ -300,9 +344,11 @@ export async function doctor(opts) {
     // possible first line.
     table.source === "installed"
         ? `${table.name ?? table.slug} v${table.version ?? "?"} - ${plural(table.byName.size, "token")}, ${plural(d.scanned, "file")} read`
-        : table.source === "yours"
-            ? `Your own tokens - ${plural(table.byName.size, "token")} found, ${plural(d.scanned, "file")} read`
-            : `No system installed - ${plural(d.scanned, "file")} read`));
+        : table.source === "adopted"
+            ? `${table.name ?? table.slug} (adopted) - ${plural(table.byName.size, "token")}, ${plural(d.scanned, "file")} read`
+            : table.source === "yours"
+                ? `Your own tokens - ${plural(table.byName.size, "token")} found, ${plural(d.scanned, "file")} read`
+                : `No system installed - ${plural(d.scanned, "file")} read`));
     if (scopes.length > 0) {
         console.log(body(`scope: ${opts.scopes?.join(", ")}`));
     }
@@ -329,6 +375,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 +726,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/dist/doctor/tokens.js

@@ -212,7 +212,9 @@ export function parseRootTokens(css) {
 }
 export function buildTable(input) {
     const source = input.source ?? "installed";
-    const byName = source === "yours" ? parseRootTokens(input.css) : parseTokens(input.css);
+    const byName = source === "installed"
+        ? parseTokens(input.css)
+        : parseRootTokens(input.css);
     const byValue = new Map();
     for (const [name, value] of byName) {
         const key = normalizeValue(value);

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { add } from "./commands/add.js";
+import { adopt } from "./commands/adopt.js";
 import { advise } from "./commands/advise.js";
 import { clean } from "./commands/clean.js";
 import { component } from "./commands/component.js";
@@ -123,6 +124,15 @@ async function main() {
     const registry = typeof flags.registry === "string" ? flags.registry : undefined;
     const dir = typeof flags.dir === "string" ? flags.dir : undefined;
     switch (command) {
+        case "adopt":
+            // Dry by default: `--write` is the only way anything lands on disk.
+            await adopt({
+                dir,
+                write: flags.write === true,
+                tokens: typeof flags.tokens === "string" ? flags.tokens : undefined,
+                slug: typeof flags.slug === "string" ? flags.slug : undefined,
+            });
+            break;
         case "doctor":
             // positional paths scope the READING (the system is still found from the
             // root): `doctor apps/web packages/ui` in a monorepo

package/package.json

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