synthesisui 0.16.13 → 0.16.15

package/dist/claude-md.js

@@ -118,6 +118,32 @@ 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.
+ */
+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 +156,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 +164,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.
  *
@@ -226,6 +252,12 @@ YOURSELF. It materializes that component as real typed code in this project, and
 extend that. The person who asked you for a feature should never have to know these command
 names or type them; finding the right component is your job, not theirs.
 
+When you override a style a component already sets, add \`!\` to your class:
+\`className="text-info!"\`, not \`className="text-info"\`. Both are plain utilities at the
+same specificity, so which one wins is decided by the order Tailwind writes the stylesheet -
+not by the order of the class names, which is what the code looks like it controls. This
+applies to the Tailwind flavour only; the CSS one is layered and needs no marker.
+
 Only write something new when nothing in the manifest covers the purpose - and when you do,
 say which entry you considered and why it did not fit. To review a
 component, create an isolated sample page (e.g. \`app/synthesisui-samples/<component>/\`) - do not

package/dist/commands/add.js

@@ -150,7 +150,19 @@ export async function add(slug, opts) {
     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/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/dist/component-codegen.js

@@ -345,8 +345,38 @@ function header(slug, name, version, mode) {
         `// On-system by construction: every style resolves to the DS tokens.`,
         `// Global setup (once per app): ${setup}`,
         `// and put data-ds="${slug}" on a root element (e.g. <body data-ds="${slug}">).`,
+        ...(mode === "tailwind" ? [OVERRIDE_WARNING] : []),
     ].join("\n");
 }
+/**
+ * THE OVERRIDE THAT LOSES WITHOUT SAYING SO.
+ *
+ * `className` is appended last in the string below, which looks like it wins
+ * and does not. Two plain utilities setting the same property have the same
+ * specificity, so the winner is decided by the order Tailwind emits them into
+ * the stylesheet - which depends on the order of names in the theme, not on
+ * anything visible from here.
+ *
+ * Found by an agent building against these components: it wanted a blue title
+ * on a `CardTitle` whose base carries `text-foreground`, and only got it by
+ * reaching for `!` - which it knew about because it had written the trip-up
+ * into its own project memory on an earlier run (my-test4, 27/07).
+ *
+ * CSS mode does not have this. Its rules live in `@layer components`, which
+ * Tailwind's utilities outrank by construction, so an override there just
+ * works. This warning is emitted for the Tailwind flavour only.
+ *
+ * A real fix has to resolve utility conflicts - knowing that `text-info`
+ * collides with `text-foreground` but not with `text-lg`, though all three
+ * start with `text-`. That needs the system's own colour and size vocabulary,
+ * which this generator has. Until it is built, the failure at least stops
+ * being silent, which is the part that actually costs people time.
+ */
+const OVERRIDE_WARNING = `//
+// Overriding a style this component already sets? Add \`!\`:
+//   <Thing className="text-info!" />   not   className="text-info"
+// Both are plain utilities at the same specificity, so which one wins is
+// decided by the stylesheet's order, not by this string's.`;
 const joinCls = (parts) => `[${parts.join(", ")}].filter(Boolean).join(" ")`;
 /** JSDoc showing how to compose the component with its parts + content, so the
  *  materialized code doesn't read as "a bare shell renders nothing" (dogfood

package/package.json

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