synthesisui 0.16.76 → 0.16.78

package/dist/project-facts.js

@@ -0,0 +1,89 @@
+/**
+ * TWO FACTS ABOUT THE PROJECT THE CODEGEN CANNOT GUESS.
+ *
+ * Both were being read by exactly one of the four commands that generate code, so
+ * the other three emitted something subtly wrong and nothing failed:
+ *
+ *   the React major     decides whether a component can take a `ref`
+ *   the class convention decides whether its classes exist at all
+ *
+ * The second is the serious one. A compiled class attaches to THEIR markup, so an
+ * imported system keeps its own spelling - `.metric-card__title`, not
+ * `.ds-metric-card-title`. The codegen hardcoded ours, so `synthesisui component`
+ * handed somebody a React component wearing classes their own stylesheet never
+ * emits. It renders completely unstyled, and nothing anywhere reports a problem.
+ */
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { DEFAULT_CONVENTION, } from "./component-codegen.js";
+/**
+ * Which React the consumer is on, for the ref-carrying prop type.
+ *
+ * From 19 a `ref` is an ordinary prop; before it a function component needs
+ * `forwardRef`. Guessing high on an older project would emit a type that accepts a
+ * ref React then silently drops, so anything unreadable falls back to the
+ * ref-less type.
+ */
+export async function reactMajorOf(root) {
+    const raw = await readFile(join(root, "package.json"), "utf8").catch(() => "");
+    if (!raw)
+        return null;
+    try {
+        const pkg = JSON.parse(raw);
+        const spec = pkg.dependencies?.react ?? pkg.devDependencies?.react;
+        const major = /(\d+)/.exec(spec ?? "")?.[1];
+        return major ? Number(major) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The pinned version of an installed system, from its `.lock`. */
+async function pinnedVersion(dir) {
+    const raw = await readFile(join(dir, ".lock"), "utf8").catch(() => "");
+    if (!raw)
+        return null;
+    try {
+        const lock = JSON.parse(raw);
+        return typeof lock.version === "number" ? lock.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * HOW THE INSTALLED SYSTEM SPELLS A CLASS, read off the document on disk.
+ *
+ * The document is the same one the compiled CSS came from, so this can never
+ * disagree with the stylesheet sitting next to it - which is the property that
+ * matters. A response field would be fresher, and a caller that has one should
+ * prefer it; this is what every other caller can rely on.
+ *
+ * Absent, unreadable or never declared all mean OURS, to the character, so no
+ * project that exists has to change.
+ */
+export async function readInstalledConvention(root, slug) {
+    const dir = join(root, "_synthesisui", "ds", slug);
+    const version = await pinnedVersion(dir);
+    const raw = version
+        ? await readFile(join(dir, `v${version}`, "design-system.json"), "utf8").catch(() => "")
+        : "";
+    if (!raw)
+        return DEFAULT_CONVENTION;
+    try {
+        const doc = JSON.parse(raw);
+        const declared = doc.meta?.classNames;
+        if (!declared ||
+            typeof declared.prefix !== "string" ||
+            typeof declared.partSeparator !== "string") {
+            return DEFAULT_CONVENTION;
+        }
+        return {
+            prefix: declared.prefix,
+            partSeparator: declared.partSeparator,
+        };
+    }
+    catch {
+        return DEFAULT_CONVENTION;
+    }
+}

package/dist/skill-import.js

@@ -153,10 +153,39 @@ Open the project and answer the questions below. Then add a \`reading\` object t
   ],
   "components": {
     "MetricCard": {
-      "parts": [
-        { "name": "icon", "classes": "size-8 text-ocean-500" },
-        { "name": "label", "classes": "text-xs uppercase text-lightgray-500" },
-        { "name": "value", "classes": "text-2xl font-bold" }
+      "anatomy": [
+        { "as": "icon", "name": "icon", "classes": "size-8 text-ocean-500" },
+        {
+          "as": "stack",
+          "name": "body",
+          "classes": "flex flex-col gap-1",
+          "children": [
+            { "as": "text", "name": "label", "classes": "text-xs uppercase text-lightgray-500" },
+            { "as": "heading", "name": "value", "classes": "text-2xl font-bold" }
+          ]
+        }
+      ]
+    },
+    "ArticleCard": {
+      "anatomy": [
+        { "as": "image", "name": "cover", "classes": "aspect-video w-full rounded-t-lg" },
+        { "as": "heading", "name": "title", "classes": "text-lg font-semibold" },
+        { "as": "component", "ref": "TextEditor" },
+        {
+          "as": "row",
+          "name": "footer",
+          "classes": "flex items-center gap-2 border-t p-3",
+          "children": [
+            { "as": "button", "name": "publish", "classes": "btn btn-primary" },
+            { "as": "button", "name": "discard", "classes": "btn btn-ghost" }
+          ]
+        }
+      ]
+    },
+    "TextEditor": {
+      "anatomy": [
+        { "as": "row", "name": "toolbar", "classes": "flex gap-1 border-b p-2" },
+        { "as": "external", "from": "@tiptap/react" }
       ]
     }
   },
@@ -250,40 +279,119 @@ Things worth looking for, none of them guessable from tokens:
 If you cannot say where a rule came from, do not send it. An invented law is worse than a
 missing one, because it will be obeyed.
 
-**\`components[Name].parts\` - what each component is MADE OF.** This is the field that decides
-whether a component previews as itself or as a grey box with a sentence in it, and only you can
-fill it.
+**\`components[Name].anatomy\` - what each component is MADE OF, and in what shape.** This is the
+field that decides whether a component previews as itself or as a grey box with a sentence in it,
+and only you can fill it.
 
 The census reads the ROOT element's classes and stops there, on purpose: descending a fixed
-number of levels picks a layout wrapper as often as a semantic part. **You decide how far down a
-part lives**, because you read the component. Send a name and the classes on it; the CLI turns
-those classes into declarations and the platform turns declarations into roles.
+number of levels picks a layout wrapper as often as a semantic part. **You read the component, so
+you decide the shape.** Send a tree; the CLI turns the classes into declarations and the platform
+turns declarations into roles.
+
+### The three frontiers
+
+Every node you send is one of three things, and knowing which is the whole job:
+
+\`\`\`
+a PART       an element of theirs        it has styles, and we draw it
+a COMPONENT  a component of theirs       it has a recipe of its own → named block + a RULE
+an EXTERNAL  a third-party library       we do not have it and never will → block + rules
+\`\`\`
+
+**Depth is not a number, it is where the frontier sits.** Descend until you meet another
+component or a library, stop there, and record the edge. That is why no parameter tells you how
+deep to go: a \`Divider\` is one node deep and a dashboard shell is five, and both are complete.
+
+### The nine forms
+
+\`as\` says what a node IS, and the renderer draws that. Nothing else is accepted:
+
+\`\`\`
+image     a picture region: cover, thumbnail, media
+heading   the title line
+text      body copy, a label, a value
+button    an action
+field     an input somebody types into
+icon      a glyph, or a bare shape with no text
+row       arranges its children ACROSS
+stack     arranges its children DOWN
+component their component  → needs "ref": the name as their code spells it
+external  a library        → needs "from": the package name
+\`\`\`
+
+Only \`row\` and \`stack\` take \`children\`. Everything else is a leaf.
 
-**The name is load-bearing, not a label.** The renderer infers a part's role from it:
+**\`name\` is the part name**, and it is what carries the styles - flat, lowercase, kebab. Never
+nested: \`"actions.generate"\` compiles to two CSS classes and is invalid, so name it
+\`"generate-action"\`. Name what it IS - \`label\`, \`value\`, \`delta\`, \`cover\`, \`toolbar\` - because the
+name becomes a class in their stylesheet and \`div2\` is a name somebody has to live with.
 
-- \`root\`, \`wrapper\`, \`container\`, \`base\`, \`content\` - the element itself, and **skipped**. Do not
-  send these; their styles already sit on the component.
-- anything matching \`icon\`, \`dot\`, \`indicator\`, \`bar\`, \`avatar\`, \`media\`, \`swatch\` - renders as a
-  bare span, sized and coloured by its own styles
-- anything matching \`button\`, \`action\`, \`cta\` - renders as a real button carrying the label
-- everything else - carries text
+\`root\`, \`wrapper\`, \`container\`, \`base\` and \`content\` are the element itself: **do not send them as
+nodes.** Their styles already sit on the component, and a node for them draws a box inside its own
+box.
 
-So a part named \`div2\` previews as a text node reading "Div2". Name what it IS: \`label\`, \`value\`,
-\`delta\`, \`icon\`, \`action\`, \`title\`, \`meta\`.
+A node with no \`classes\` is fine - it still carries structure, which is most of the value. A
+\`component\` or \`external\` node takes no \`name\` and no \`classes\`: the styles there are not theirs
+to hold.
 
-Send them **in the order they appear**, because that is the order they render. Three or four
-named parts is a recognisable component; twelve is a transcription of their DOM, and nobody
-needs the layout divs.
+### A component of theirs is a NAMED BLOCK, not an expansion
 
-**Send parts for every component that has visible structure**, which is nearly all of them. A
+When you hit \`<TextEditor>\` inside \`<ArticleCard>\`, send
+\`{ "as": "component", "ref": "TextEditor" }\` and **stop**. Do not inline what TextEditor is made
+of. It previews as a block carrying its name, and it becomes a **rule** - \`ArticleCard\` +
+\`TextEditor\`, a relation, which is the one thing a flat list of prose could never say.
+
+That edge is a **fact, not a habit**: you saw it in the definition, so it is true once and for
+all, and it arrives active without waiting for a third sighting.
+
+Two things that are NOT edges, and sending them as such would be wrong:
+
+- \`motion.div\`, \`Dialog.Root\`, \`Radio.Item\` - a library's namespace, not a component of theirs
+- an HTML element with a capital in a variable name
+
+If the component came from a package, it is \`external\`, not \`component\`.
+
+### An external dependency does not render, and that is the answer
+
+A \`TextEditor\` built on tiptap cannot be previewed: the editable region is tiptap's, and drawing
+a fake one would be inventing. So it previews as a block naming the package, and the value moves
+into the **rules** - which is where an agent will read it anyway.
+
+A library is never one rule, it is a family, and you are reading the file so you can see all of
+them. Send them as normal \`rules\` with \`applies: ["TextEditor"]\` and
+\`kind: "implementation"\`:
+
+\`\`\`
+requires @tiptap/react
+the editable region is <EditorContent> - never render children into it directly
+toolbar buttons go through editor.chain().focus()
+extensions are configured at construction, not toggled later
+\`\`\`
+
+**Name the package in the rule; leave the version to the evidence.** The CLI reads the version out
+of their manifest and attaches it (\`"^2.1.0 in packages/ui"\`), so the rule does not go stale the
+day they upgrade and the information is not lost either.
+
+### How much to send
+
+Send an anatomy for **every component with visible structure**, which is nearly all of them. A
 \`Chat\` has a message list and a composer; a \`MetricCard\` has a label and a value; a
-\`CircularProgress\` has a track and a fill. Sending none is the right answer only for something
-genuinely undivided - a \`Divider\`, a \`Spacer\`.
+\`CircularProgress\` has a track and a fill. Sending none is right only for something genuinely
+undivided - a \`Divider\`, a \`Spacer\`.
+
+Three to six nodes is a recognisable component. Twelve is a transcription of their DOM, and
+nobody needs the layout divs - collapse a wrapper whose only job is \`flex\` into the \`row\` it
+already is.
+
+The cost of sending none is not neutral. A component with no anatomy previews as a grey box with
+a sentence in it, or - if its kind is \`indicator\` - as a small blank shape. A component with a
+real tree previews as itself, and its spec view shows what the system understood. That is the
+whole reason this field exists, and skipping it quietly is how a real library came back looking
+empty (dono, 01/08).
 
-The cost of sending none is not neutral. A component with no parts previews as a grey box with a
-sentence in it, or - if its anatomy is \`indicator\` - as a small blank shape. A component with
-three named parts previews as itself. That difference is the whole reason this field exists, and
-skipping it quietly is how a real library came back looking empty (dono, 01/08).
+The older flat form - \`"parts": [{ "name": "label", "classes": "..." }]\` - still works and still
+styles correctly. It just carries no shape, so the preview lays the parts out in a row and the
+spec view has no nesting to draw.
 
 ### 3. Walk them through the decisions, one at a time
 
@@ -411,10 +519,15 @@ proposal. Say all of this in your own words - do not just print the link:
 
 - the scheme it opens in, and whether a second one was built
 - their ramps under their own family names
-- their exclusive components as contracts - **axes declared, every style block empty.** Say
-  this out loud, because a component list full of blank recipes looks like a failure until
-  someone explains it was deliberate. The platform shows them as *Not written yet*, not as a
+- their exclusive components as contracts - **the axes their types declare, the look transcribed
+  out of their own class names where it was readable, and the anatomy you sent.** Say what is
+  still empty out loud, because a half-written recipe looks like a failure until someone explains
+  which half was deliberate: nothing was invented, so a component whose classes named no token
+  arrives with structure and no colour. The platform shows that as *Not written yet*, not as a
   zero.
+- **the shape of each component**, if you sent one: its parts nested as they nest in their code,
+  the components of theirs it composes, and the libraries it needs. Each edge is also a rule now,
+  which is what makes it survive being looked at once.
 
 **What is waiting in v2**, which only they can approve: near-duplicate colours collapsed,
 unnamed heavy hitters given a place. Point at the link the CLI printed and name the two or
@@ -444,8 +557,10 @@ The user should end up with a system that reads like theirs and not like ours:
 - **their names travel** - \`vivid-pink\`, \`darkgray-900\`, whatever they called it
 - **their default face** - a dark product opens dark
 - **no borrowed colour** - if it is in the system, it is in their code
-- **their exclusive components arrive as contracts** - axes declared, every style block empty,
-  because a contract says what may vary and a recipe would be us redesigning their component
+- **their exclusive components arrive as contracts** - the axes declared, the look transcribed and
+  never invented, and the anatomy read out of their own JSX
+- **a component previews as itself** - an \`ArticleCard\` shows a cover, a title and a footer of
+  buttons, and says out loud that the editor in the middle is their \`TextEditor\` on tiptap
 - **the duplicates are named out loud** - three components that all read as a badge, a brand
   colour painted 275 times with no token
 

package/package.json

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