synthesisui 0.16.14 → 0.16.16

package/dist/claude-md.js

@@ -118,6 +118,61 @@ If it reports a value with no token, do NOT invent one. Say which value and what
 you would call it, and let a person decide. An agent that quiets the report by
 adding a token is growing the system unsupervised, which is worse than the
 drift because it looks solved.`;
+/**
+ * TWO THINGS AN AGENT GOT WRONG ON 28/07, BOTH CHEAP TO SAY OUT LOUD.
+ *
+ * It started a dev server to look at its work and left it running. The owner
+ * found it by trying to start his own and getting "Another next dev server is
+ * already running", with a PID to kill. Nothing in any contract had said to
+ * clean up, and a build proves the same thing without holding a port.
+ *
+ * And it offered to rebuild the create-next-app landing page by hand, on
+ * `ds-button` and `ds-card`, when a command already resets it in two seconds.
+ * It had found `clean` while exploring the CLI, so this is not a discovery
+ * problem - it is that nothing told it the command answers that situation.
+ *
+ * `--force` needs a person because it deletes. The dry run does not, so the
+ * agent is pointed at the harmless half and told to ask for the other.
+ */
+/**
+ * THE ONE THING MOST LIKELY TO ALREADY BE IN THE PROJECT.
+ *
+ * Every system compiles a `shadcn.css` mapping shadcn's whole variable contract
+ * onto its own tokens. It has been generated into every project since it was
+ * built and nothing ever mentioned it, so the feature that answers "why not just
+ * use shadcn" was sitting unimported in the repo of the person who asked.
+ *
+ * Told to the AGENT and not only to the person, because the agent is who reaches
+ * for a shadcn block. Left to guess, it installs `dashboard-01` and gets a
+ * sidebar on shadcn's defaults next to components wearing the system, which
+ * reads as a broken product rather than a missing import.
+ *
+ * Conditional on `components.json`: a project without shadcn must not carry a
+ * paragraph about it.
+ */
+const SHADCN = (slug) => `
+
+**This project has shadcn, and this system already speaks its language.** A
+generated bridge maps shadcn's whole variable contract - colour, charts, radius,
+the sidebar family - onto this system's tokens, in both schemes:
+
+    @import "_synthesisui/ds/${slug}/shadcn.css";
+
+after the tokens.css import, in the same stylesheet. With that line in place,
+shadcn components wear this system and need no edits from you. Without it they
+stay on shadcn's defaults, which looks like the design system failing rather than
+one import missing - so check for it before you add a shadcn component, and add
+it if it is not there.`;
+const VERIFY = `
+
+**Verify with a build, not a running server.** If you do start a dev server, stop
+it before you finish - one left running holds a port the next person needs.
+
+If \`create-next-app\` boilerplate is in your way (the default page, the README,
+the SVGs in \`public/\`), do not rebuild those files by hand. Run
+\`npx synthesisui@latest clean\` to see what it would remove: it only touches files
+nobody has edited. Ask the person before running it with \`--force\`, because that
+one deletes.`;
 const SELF_CHECK_MANUAL = `
 
 **After writing or editing any UI file, check it before moving on:**
@@ -130,7 +185,7 @@ a component checked while you still have its context is a two-line fix; the same
 component found in a repo-wide audit next week is an archaeology exercise.${REFUSAL}
 
 Better than remembering: \`npx synthesisui@latest connect\` installs the check as
-an editor hook, so it runs on its own and this paragraph stops being your job.`;
+an editor hook, so it runs on its own and this paragraph stops being your job.${VERIFY}`;
 const SELF_CHECK_HOOKED = `
 
 **The check runs by itself.** A hook reports on every file you write, naming the
@@ -138,7 +193,7 @@ token this project already has for anything hardcoded. You do not need to run
 \`doctor\` by hand, and you should not wait for a final pass.
 
 When it names something, fix it in that file before moving to the next one -
-you still have the context, so it is a two-line change.${REFUSAL}`;
+you still have the context, so it is a two-line change.${REFUSAL}${VERIFY}`;
 /**
  * THE INTERFACE LANGUAGE, READ FROM THE PROJECT RATHER THAN ASKED FOR.
  *
@@ -251,9 +306,16 @@ element. Write every user-facing string in that language - labels, empty states,
 \`alt\`. A screen reader pronounces \`aria-label\` using \`lang\`, so a mixed-language interface is
 worse than an untranslated one. If the attribute is wrong, change it rather than writing against
 it.`;
+    // Named for the first installed system: the bridge is per-system, and a
+    // project with two of them has already chosen which one dresses the app.
+    const bridgeable = installed.find((d) => !d.adopted);
+    const shadcn = bridgeable &&
+        (await readFile(join(projectRoot, "components.json"), "utf8").then(() => true, () => false))
+        ? SHADCN(bridgeable.slug)
+        : "";
     const body = `## Design Systems (via SynthesisUI)
 
-This project uses design system(s) tracked by the \`synthesisui\` CLI. ${rule}${language}
+This project uses design system(s) tracked by the \`synthesisui\` CLI. ${rule}${language}${shadcn}
 
 ${sections.join("\n")}
 

package/dist/commands/add.js

@@ -138,19 +138,51 @@ export async function add(slug, opts) {
     console.log(line(`1. Import the system in your GLOBAL stylesheet, e.g. ${appDir}/globals.css`));
     console.log(line(`   (the path is relative to that file - hence the leading ${importPrefix}):`));
     console.log("");
-    console.log(snippet(hasTheme
-        ? [
-            `@import "tailwindcss";`,
-            `@import "${importPrefix}_synthesisui/ds/${payload.slug}/tokens.css";`,
-            `@import "${importPrefix}_synthesisui/ds/${payload.slug}/theme.css";  /* Tailwind utilities on your tokens */`,
-        ]
-        : [
-            `@import "${importPrefix}_synthesisui/ds/${payload.slug}/tokens.css";`,
-        ]));
+    // THE BRIDGE ONLY EXISTS FOR PEOPLE WHO ALREADY HAVE SHADCN, so it only
+    // appears for them. Every system compiles a `shadcn.css` mapping shadcn's
+    // whole variable contract onto its own tokens, and until 28/07 nothing said
+    // so - not this output, not the managed block, not the GUIDE beyond a filename
+    // in a list. The person it mattered most to asked "I don't get the use case, I
+    // can just build a design system with shadcn", with the answer sitting
+    // unimported in his own repo. Naming it to everybody would be noise; naming it
+    // to whoever has `components.json` is the whole feature arriving.
+    const hasShadcn = await access(join(projectRoot, "components.json")).then(() => true, () => false);
+    console.log(snippet([
+        ...(hasTheme ? [`@import "tailwindcss";`] : []),
+        `@import "${importPrefix}_synthesisui/ds/${payload.slug}/tokens.css";`,
+        ...(hasTheme
+            ? [
+                `@import "${importPrefix}_synthesisui/ds/${payload.slug}/theme.css";  /* Tailwind utilities on your tokens */`,
+            ]
+            : []),
+        ...(hasShadcn
+            ? [
+                `@import "${importPrefix}_synthesisui/ds/${payload.slug}/shadcn.css";  /* your shadcn components, wearing this system */`,
+            ]
+            : []),
+    ]));
+    if (hasShadcn) {
+        console.log("");
+        console.log(line(`   You have shadcn here. That third line maps its whole variable contract`));
+        console.log(line(`   onto this system - colour, charts, radius and the sidebar - so its`));
+        console.log(line(`   components stop using shadcn's defaults. Both schemes included.`));
+    }
     console.log("");
     console.log(line(`2. Scope your app: add data-ds="${payload.slug}" to a ROOT element, e.g. ${appDir}/layout.tsx:`));
     console.log("");
-    console.log(snippet([`<body data-ds="${payload.slug}">{children}</body>`]));
+    console.log(snippet([
+        `<body data-ds="${payload.slug}" className="bg-canvas">{children}</body>`,
+    ]));
+    // THE SCOPE DELIBERATELY DOES NOT PAINT A BACKGROUND, and every project hits
+    // it. `[data-ds]` sets ink and body family only, because scopes NEST: a dark
+    // contrast section over a photograph carries its own nested `data-ds` so its
+    // tokens remap, and a background on every scope would paint over the picture.
+    // So the page background is the root element's job, and saying so here is the
+    // fix - an agent found this by reading rendered CSS on 28/07 and had to
+    // deduce it.
+    console.log(line(`   \`bg-canvas\` is not optional: the scope sets text colour and type, not the page`));
+    console.log(line(`   background. Scopes nest (a dark section carries its own), so painting every one`));
+    console.log(line(`   would cover whatever is behind it.`));
     // 3. Load the type - the DS ships token NAMES, not the fonts themselves.
     //    Next apps get fonts.ts MATERIALIZED (deterministic does, not teaches):
     //    next/font = self-hosted + preloaded + adjusted fallback, no FOUT

package/dist/commands/doctor.js

@@ -287,15 +287,37 @@ async function readWiring(root, slug) {
         fontsWritten: false,
         /** …and the stylesheet actually maps it onto the system's type tokens. */
         fontsMapped: false,
+        /**
+         * THE FEATURE NOBODY KNEW WE SHIPPED.
+         *
+         * Every system compiles a `shadcn.css` mapping shadcn's whole variable
+         * contract onto its own tokens, so shadcn components wear the system instead
+         * of shadcn's defaults. It has been generated into every project since it
+         * was built, and until 28/07 nothing mentioned it: not `add`, not the
+         * managed block, not the GUIDE except as a filename in a list. The only
+         * documentation was a comment inside the file, which is the same as none.
+         *
+         * The person it mattered most to is the one who asked "I don't get the use
+         * case, I can just build a design system with shadcn" - and the answer was
+         * sitting unimported in his own repo.
+         *
+         * Reported only when the project HAS shadcn. Telling everybody about a
+         * bridge they will never use is how a report earns the skim.
+         */
+        hasShadcn: false,
+        bridged: false,
     };
     if (!slug)
         return w;
+    w.hasShadcn = await readFile(join(root, "components.json"), "utf8").then(() => true, () => false);
     for await (const file of walk(root)) {
         const src = await readFile(file, "utf8").catch(() => "");
         if (!src)
             continue;
         if (src.includes(`_synthesisui/ds/${slug}/tokens.css`))
             w.imported = true;
+        if (src.includes(`_synthesisui/ds/${slug}/shadcn.css`))
+            w.bridged = true;
         if (src.includes(`data-ds="${slug}"`))
             w.scoped = true;
         // The requirement that stayed invisible. `init` writes a fonts file and
@@ -306,7 +328,9 @@ async function readWiring(root, slug) {
             w.fontsWritten = true;
         if (/--ds-typography-families-\w+\s*:\s*var\(\s*--font-ds-/.test(src))
             w.fontsMapped = true;
-        if (w.imported && w.scoped && w.fontsMapped)
+        // The bridge joins the early exit, otherwise the walk can stop before the
+        // stylesheet that imports it and report a wired project as unbridged.
+        if (w.imported && w.scoped && w.fontsMapped && (!w.hasShadcn || w.bridged))
             break;
     }
     return w;
@@ -461,6 +485,37 @@ export async function doctor(opts) {
         }
         console.log(body("The exact snippets are in the output of `init`."));
     }
+    /**
+     * SHADCN IS THE MOST LIKELY THING ALREADY IN THE PROJECT, AND THE BRIDGE WAS
+     * INVISIBLE.
+     *
+     * Two states, and both are worth a line. Unimported is a real finding: the
+     * components a person spends all day looking at are on shadcn's defaults while
+     * everything around them wears the system, which reads as "this product does
+     * not work here" rather than "one import missing".
+     *
+     * Imported is worth saying too, and that is the unusual part. It is the only
+     * place we can answer "how do I know my shadcn is going through the system?"
+     * with something checked rather than claimed. A governance tool that cannot
+     * show its work is asking for trust it has not earned.
+     */
+    if (hasSystem && wiring.hasShadcn) {
+        console.log("");
+        if (wiring.bridged) {
+            console.log(body(`✓ shadcn is reading ${table.name ?? table.slug}, not its own`));
+            console.log(body("  defaults. Colour, charts, radius and the sidebar all resolve"));
+            console.log(body("  to this system's tokens, in both schemes."));
+        }
+        else {
+            console.log(body("This project has shadcn, and it is not wearing the"));
+            console.log(body("system yet - its components are still on shadcn's defaults."));
+            console.log("");
+            console.log(body(`  @import "_synthesisui/ds/${table.slug}/shadcn.css";`));
+            console.log("");
+            console.log(body("  after the tokens.css import, in the same stylesheet. One line,"));
+            console.log(body("  and every shadcn component switches over."));
+        }
+    }
     if (hasSystem && measurable) {
         console.log("");
         console.log(body(`Token coverage  ${meter(d.coverage)}  ${String(d.coverage).padStart(3)}%`));

package/dist/commands/hook.js

@@ -1,5 +1,5 @@
-import { readFile } from "node:fs/promises";
-import { relative, resolve } from "node:path";
+import { readFile, writeFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { loadSystem } from "./doctor.js";
 const pass = () => ({ continue: true });
@@ -13,6 +13,39 @@ const speak = (context) => ({
 /** Files where a design value can even appear. A hook that parses a README on
  *  every edit is paying for nothing. */
 const UI_FILE = /\.(tsx|jsx|ts|js|css|scss|vue|svelte)$/i;
+/** Written after the hook's first report of any kind, and never read for anything
+ *  else. Lives in our own directory, so removing the system removes the memory
+ *  too. It is committed with `_synthesisui/`, which means the greeting is
+ *  per-project and not per-teammate - a wart worth the simplicity, since the
+ *  second person to clone a wired repo is not the one wondering if it installed. */
+const GREETED = "_synthesisui/.hook-greeted";
+const markGreeted = (root) => writeFile(join(root, GREETED), "", "utf8").catch(() => { });
+/** One sentence, once per project. Addressed to the agent because the hook has
+ *  no way to reach the person, and the person is who needs to know. */
+async function greet(root, rel) {
+    const marker = join(root, GREETED);
+    try {
+        await readFile(marker, "utf8");
+        return null;
+    }
+    catch {
+        // Not greeted yet. Write first: a failed write must not produce a hook that
+        // greets on every single edit for the rest of the project's life.
+        try {
+            await writeFile(marker, "", "utf8");
+        }
+        catch {
+            return null;
+        }
+    }
+    return [
+        `${rel} - checked, nothing to name. Every value in it has a token.`,
+        "",
+        "That check now runs on every file you write, by itself. Tell the person once",
+        "that it is live, so they know it installed, and then stop mentioning it - from",
+        "here it only speaks when something needs a name.",
+    ].join("\n");
+}
 async function report(root, filePath) {
     const { table } = await loadSystem(root);
     if (table.byName.size === 0)
@@ -28,7 +61,11 @@ async function report(root, filePath) {
     // no token to move to, so the only honest advice is "ask a person" - and
     // saying that after every edit trains the reader to skip the block.
     if (named.length === 0 && phantoms.length === 0)
-        return null;
+        return greet(root, rel);
+    // A report IS the evidence the greeting exists to provide, so it counts as the
+    // introduction. Otherwise a project whose first file had drift would get the
+    // "it is live" sentence afterwards, telling somebody who just watched it work.
+    await markGreeted(root);
     const lines = [`${rel} - checked against ${table.name ?? table.slug}.`];
     if (named.length > 0) {
         lines.push("", "Values written by hand that this system already has a name for:", ...named

package/package.json

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