synthesisui 0.16.79 → 0.16.81

package/dist/progress.js

@@ -0,0 +1,71 @@
+/**
+ * WHAT IS HAPPENING RIGHT NOW, and how much is left.
+ *
+ * "While the design system import is running it would be good to have an animated
+ * progress and underneath the current component and a (10 of 1235)" (dono, 01/08).
+ *
+ * A census over a real monorepo reads 2797 files and the terminal said nothing for
+ * most of it. Twenty silent minutes is indistinguishable from twenty broken ones, and
+ * that is the difference this makes: not speed, but the ability to wait.
+ *
+ * TWO AUDIENCES, ONE API. A person at a terminal gets a bar that redraws in place; the
+ * skill runs the CLI with no TTY and pipes the output, so it gets a plain milestone
+ * line every so often. Neither has to know about the other, and the non-TTY path never
+ * writes a carriage return into a transcript.
+ */
+const BAR_WIDTH = 24;
+/** Every this-many items, the non-TTY path prints one line. Enough to see movement in
+ *  a piped log without turning it into the log. */
+const MILESTONE_EVERY = 25;
+/** A bar that reads as a bar at any width. Two glyphs, no colour: this line is
+ *  overwritten dozens of times a second and anything fancier flickers. */
+function bar(done, total) {
+    const ratio = total > 0 ? Math.min(1, done / total) : 0;
+    const filled = Math.round(ratio * BAR_WIDTH);
+    return `${"█".repeat(filled)}${"░".repeat(BAR_WIDTH - filled)}`;
+}
+/** Truncated from the LEFT, because the end of a path is the part that identifies it. */
+function tail(label, width) {
+    if (label.length <= width)
+        return label;
+    return `…${label.slice(-(width - 1))}`;
+}
+export function startProgress(title, opts) {
+    const write = opts?.write ?? ((s) => process.stdout.write(s));
+    const tty = opts?.isTty ?? Boolean(process.stdout.isTTY);
+    let total = opts?.total ?? 0;
+    let done = 0;
+    let last = "";
+    const paint = () => {
+        const count = total > 0 ? `${done} of ${total}` : String(done);
+        const line = `  ${bar(done, total)}  ${count}  ${tail(last, 40)}`;
+        // Pad to the previous width so a shorter label cannot leave the tail of a
+        // longer one behind on the line.
+        write(`\r${line.padEnd(80)}`);
+    };
+    return {
+        step(label) {
+            done += 1;
+            last = label;
+            if (tty) {
+                paint();
+                return;
+            }
+            // NO CARRIAGE RETURNS IN A TRANSCRIPT. A milestone line every so often, plus
+            // the first one so the reader knows the phase started at all.
+            if (done === 1 || done % MILESTONE_EVERY === 0) {
+                const count = total > 0 ? `${done} of ${total}` : `${done}`;
+                write(`  ${title}: ${count} - ${label}\n`);
+            }
+        },
+        total(n) {
+            total = n;
+        },
+        done(summary) {
+            if (tty)
+                write(`\r${" ".repeat(80)}\r`);
+            if (summary)
+                write(`  ${summary}\n`);
+        },
+    };
+}

package/dist/skill-import.js

@@ -105,22 +105,42 @@ This root holds several projects
   is the average of all of them. That is a fine DIAGNOSIS and a poor system: a
   light app and a dark one average into a palette that is neither.
 
-      synthesisui import --scope packages/ui   the system comes from here
+      synthesisui import --scope packages/ui --usage apps/web-dashboard
 \`\`\`
 
-Then measure again, narrowed:
+Then measure again, narrowed - and **name both roles**:
 
 \`\`\`
-npx synthesisui import --dry --scope packages/ui
+npx synthesisui import --dry --scope packages/ui --usage apps/web-dashboard
 \`\`\`
 
+### The two roles, and why one flag could not do both
+
+\`\`\`
+--scope   the SYSTEM     tokens, components, the way they name a class    ONE folder
+--usage   the EVIDENCE   how often, which values get picked, the laws     as many as they have
+\`\`\`
+
+\`--usage\` is repeatable and never contributes a token, a scale or a component. That split is
+not tidiness, it is the two mistakes this pipeline exists to avoid, and each one has been made:
+
 **Do not import the average.** Three apps measured together produce a palette that belongs to
 none of them, and it will look plausible - a real monorepo reported 36% coverage across 2797
 files at the root and 47% across 114 in its shared package. The second number is the system;
-the first is a diagnosis.
+the first is a diagnosis. Their scale is a DECLARATION; an app's average is a set of choices
+made from one.
+
+**Do not import a library alone either.** A law needs three files that agree, and a library has
+ONE file per component - so measured by itself, a real one came back with \`usage\` empty on all
+23 components and not a single observed law. Not because nothing is settled: because the
+agreeing happens in the app (dono, 01/08). If they have apps, name them.
+
+Point \`--usage\` at every app that consumes the system. A component that lives in an app and
+not in the system is reported and left out - the system is one place, and a union of two
+codebases is not a system.
 
-\`--scope\` narrows what is READ. The census still lands at \`<root>/_synthesisui/census.json\`
-and records what it measured, so you always send the same path and there is never a second
+The census still lands at \`<root>/_synthesisui/census.json\` and records both what it measured
+and where the evidence came from, so you always send the same path and there is never a second
 file to pick between. Nothing is sent by \`--dry\`. Read the file.
 
 ### 2. Read what arithmetic cannot
@@ -398,7 +418,7 @@ shell and its own parts inside.
   \`"root": "BaseDialog.Root"\`, \`"root": "Popover.Root"\`
 - **a plain tag** - leave it out. \`<div>\`, \`<td>\`, \`<button>\` are not frontiers.
 
-### The nine forms
+### The ten forms
 
 \`as\` says what a node IS, and the renderer draws that. Nothing else is accepted:
 
@@ -413,10 +433,47 @@ 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
+slot      the CALLER's content → takes "expects": what goes there, in their words
 \`\`\`
 
 Only \`row\` and \`stack\` take \`children\`. Everything else is a leaf.
 
+### \`{children}\` is a node, not an absence
+
+Four things decide what a component looks like on screen, and only the first is in its own source:
+
+\`\`\`
+its own classes          you are reading them
+what the caller passes   <tr>{children}</tr>          → slot
+its runtime state        value={62} drives the width  → a part with no static size
+a library drawing it     <EditorContent>              → external
+\`\`\`
+
+A component whose content is not its own had nothing to send, so it sent nothing and previewed as
+a blank box. A real \`DataTableRow\` is sixteen lines - a \`<tr>\` carrying a border, a hover and
+\`{children}\` - and it came back empty, which is not wrong so much as unreadable (dono, 01/08).
+
+So send the slot. \`expects\` is what the caller is supposed to put there, in the words their own
+code uses - read the prop type, the JSDoc, or a call site:
+
+\`\`\`json
+{ "as": "slot", "name": "row", "classes": "border-b hover:bg-ocean-50/30", "expects": "the cells" }
+\`\`\`
+
+It keeps its \`name\` and \`classes\` like any other node - the border and the hover are real and
+belong on that element. What it does not do is invent content: the preview says "the cells go
+here", which is exactly what the file says.
+
+Good \`expects\`: \`"the cells"\`, \`"one row per item"\`, \`"the form"\`, \`"the page body"\`. Leave it
+out rather than writing \`"children"\` - the field is for what a person would call it.
+
+**A part can carry its own variants and states**, not only a flat class string. Send
+\`classes\` for the resting look and let the prefixes travel inside it - \`hover:\`,
+\`focus-visible:\`, \`disabled:\`, \`group-hover:\`, \`md:\`, \`data-[state=open]:\` are all read
+and land where they belong. \`group-hover:\` in particular now has somewhere to go: it
+means "when the component around me is hovered", which is what a real table row is built
+on and what nothing could express before.
+
 **\`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
@@ -440,10 +497,22 @@ of. It previews as a block carrying its name, and it becomes a **rule** - \`Arti
 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:
+Three 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
+- **a name the file binds itself and does not export.** Capitalisation is React's rule for "not an
+  html tag", which is a different question from "is this a component of the system". Both of these
+  arrived as components of a real library and neither is one (dono, 01/08):
+
+\`\`\`tsx
+function Text({ as: Component = "p" })   // a prop rename - the polymorphic idiom
+const CustomLegend = () => (…)           // a closure inside LineChart
+\`\`\`
+
+  The test is reachability: a component of the system is imported from somewhere or exported to
+  somewhere. A name that only lives inside one function body is that function's private wiring,
+  and giving it a recipe invents a component nobody can import.
 
 If the component came from a package, it is \`external\`, not \`component\`.
 
@@ -468,6 +537,72 @@ extensions are configured at construction, not toggled later
 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.
 
+### The floor: what a preview needs before it can draw anything
+
+The owner asked this directly - "to render the button, what do I need to have?" - and the
+honest answer per kind is short. **Work the list for the component's kind and say which
+ones their code answers.** A reader holding this knows that a button read with no hover
+means the hover has not been found yet, and goes back for it.
+
+\`\`\`
+action    the resting fill and the text colour on it · padding and radius ·
+          text size and weight · hover, focus-visible AND disabled - three looks,
+          not one · gap and alignment if it can carry an icon
+field     the fill of the typing area and the text colour in it · the edge at rest
+          and the edge when focused · padding and radius · the placeholder colour
+          (a different decision) · the invalid look if their code has one
+control   the off look and the on look, which IS the component · the size · the
+          focus ring, since a control is reached by keyboard · the disabled look
+surface   the fill, and the edge or the elevation that separates it from the page ·
+          radius and inner padding · the gap between what it holds · whether it
+          changes at a breakpoint
+pill      the fill and text colour, per status if it has statuses · radius and
+          horizontal padding · the text size
+indicator the colour, or the two if it has a track and a fill · the size or ratio ·
+          WHAT DRIVES IT - which prop moves the number
+text      the colour · the size and line height, or a note that both are inherited ·
+          the weight and family if they differ from body
+\`\`\`
+
+**A component genuinely has none of something, and saying so is a real answer.** This is a
+list to work through, not a gate: nothing is blocked for failing it, and inventing a
+background to satisfy it would be the exact opposite of the point.
+
+There is one hard line under all of it: a recipe that declares NO colour, NO edge and NO
+size cannot be told apart from the page. The platform says so rather than printing a
+score, and it follows the root first - a component whose surface belongs to the \`Card\` it
+returns is complete.
+
+### Media is not a style question
+
+An \`image\` node draws a grey region and carries nothing about how to use it, so an agent
+composing with it invents the answer. Send these as \`rules\` on that component:
+
+\`\`\`
+a ratio or an explicit size    a region with neither collapses before the image loads,
+                              and the page jumps when it arrives
+an object-fit                 cover crops and contain letterboxes; which one is right
+                              is about the content, not a default
+a corner radius               an image inside a rounded surface has to say whether it
+                              follows the curve
+what shows while it loads     a skeleton, a blur, or the surface colour
+what shows when it is missing a missing asset must never look broken
+\`\`\`
+
+### What the CLI now reads for you, so do not spend a turn on it
+
+Four things are read deterministically from the source. Reporting them back as if you
+found them wastes a turn and risks contradicting the measurement:
+
+- **variant and state styles** out of \`cva\`, \`tv\` and \`cond === "x" && "classes"\` -
+  including a hover PER variant, compound variants, and \`[var(--their-token)]\`
+- **whether a component forwards the rest of its props**, and which it names
+- **which components appear inside which** at their call sites, as pairs
+- **the folder architecture**, and it will ask you which one has priority
+
+What is still yours: the anatomy tree, the part names, the frontiers, the roles, the
+concept, and the rules that are not about a class name.
+
 ### How much to send
 
 Send an anatomy for **every component with visible structure**, which is nearly all of them. A
@@ -497,7 +632,7 @@ spec view has no nesting to draw.
 
 ### 3. Walk them through the decisions, one at a time
 
-Four decisions are theirs. **Ask them as separate questions with selectable options** - use your
+Six decisions are theirs. **Ask them as separate questions with selectable options** - use your
 question tool, one call per decision, so they pick instead of reading a wall and composing a
 reply. A single block containing everything is a report, and a report gets read, not answered.
 
@@ -581,6 +716,56 @@ canvas  #222326  darkgray-500 - what DashboardLayout paints on <main>
 Say it and let them object. Offering five near-blacks to pick between is asking someone to
 re-decide something their code already decided.
 
+**3e-bis. Our kit, or theirs alone** - ask this ONLY when they already have a component library,
+which is when \`--scope\` pointed at one and the CLI said so. An app with no components of its own
+has nothing to weigh and should never see the question.
+
+\`\`\`
+Every system born here comes with 45 components of ours - button, card, input,
+table, the rest of a working toolkit. You already have 37.
+
+  add ours to yours (recommended)   68 components, and the 23 governed by your
+                                    own rules are the 23 you wrote
+  mine alone                        37 components, all of them yours. Our
+                                    layouts that need a component you do not
+                                    have stay out too. Add any of ours later
+                                    from the library, one at a time
+\`\`\`
+
+Send it as \`"standards": "none"\` in the reading when they choose the second, and leave the field
+out when they choose the first. **Recommend adding ours**, and say why in one line: a component of
+ours costs nothing until something composes it, and having a \`table\` the day somebody needs a
+table is worth more than a shorter list.
+
+Two things to be straight about, because both are true and neither is obvious:
+
+- **the foundations come from the seed either way.** Their palette, their scales, their type - all
+  theirs - but the seven type slots, the easing and the neutral floor arrive from ours, because
+  the alternative to a type scale is no components at all rather than their components.
+- **our layouts are written in our recipes.** A landing that composes \`button\`, \`card\` and
+  \`badge\` needs those to exist. Choosing *mine alone* keeps the layouts whose recipes they
+  happen to have and drops the rest - a layout pointing at a recipe nobody has renders as holes.
+
+**3e-ter. Which architecture has priority** - ask only when the CLI reported more than
+one, which it does under "How this project is organised".
+
+A project having two shapes is not a project with a mistake: a library organised
+atomically inside a monorepo whose apps are organised by feature is two true answers.
+Say that before you ask, or the question reads as an accusation.
+
+\`\`\`
+Two shapes, and neither is wrong:
+
+  atomic under packages/ui (recommended)   114 files - atoms/molecules/organisms,
+                                           and this is where the system comes from
+  feature under apps/web-dashboard         900 files - features/, where the app
+                                           consumes it
+\`\`\`
+
+The one they pick becomes a rule that reaches \`CLAUDE.md\`, so **every prompt after this
+knows where a new component goes** - not what the folders are called, but which rung or
+which feature a new file belongs to. Recommend the one the system came from.
+
 **3f. Fonts** - do not ask at all. Report and move on:
 
 \`\`\`
@@ -595,7 +780,7 @@ way. If it declares one, there is nothing to decide.
 carries the weight - \`ocean-500\` tells someone more than a square would. When they run
 \`npx synthesisui import\` themselves in a terminal, the CLI paints them.
 
-Then, and only after all four are answered:
+Then, and only after all of them are answered:
 
 \`\`\`
 npx synthesisui import --census _synthesisui/census.json --name "<the name>" [--registry <from step 0>]
@@ -603,7 +788,7 @@ npx synthesisui import --census _synthesisui/census.json --name "<the name>" [--
 
 **This is the one real write.** Everything before it is on their disk and costs nothing to redo.
 
-Pass every answer explicitly - \`--name\`, \`--scope\` if they changed it, and the reading rewritten
+Pass every answer explicitly - \`--name\`, \`--scope\` and \`--usage\` if they changed either, and the reading rewritten
 with their primary and their theme. The CLI cannot ask anything when you are the one running it:
 it has no terminal, so its own prompts are skipped by design. **Whatever you did not ask, nobody
 asked.** Skip 3a and the first time they learn where their system came from is when they open
@@ -627,6 +812,10 @@ proposal. Say all of this in your own words - do not just print the link:
   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.
+- **their own ladder**, if their repo has one. Components under \`atoms/\`, \`molecules/\` and
+  \`organisms/\` arrive grouped that way in the vitrine, read off the folder rather than guessed
+  from a name. You do not send this and you should not try to: a project that does not organise
+  itself this way gets one honest group instead of three invented ones.
 - **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.

package/package.json

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