synthesisui 0.16.15 → 0.16.16

package/dist/claude-md.js

@@ -134,6 +134,35 @@ drift because it looks solved.`;
  * `--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
@@ -277,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,15 +138,35 @@ 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("");

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.15",
+  "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": {