synthesisui 0.16.78 → 0.16.80

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.
 
-\`--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
+**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.
+
+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
@@ -133,6 +153,7 @@ Open the project and answer the questions below. Then add a \`reading\` object t
   "themes": { "default": "dark", "has": ["dark"] },
   "roles": { "canvas": "#050505", "foreground": "#f9fafb", "primary": "#4A90E2" },
   "fonts": { "display": "Inter", "body": "Inter" },
+  "typeRoles": { "base": "body-m", "display": "h1", "xs": "caption" },
   "concept": "one paragraph on what this product is",
   "rules": [
     {
@@ -149,6 +170,13 @@ Open the project and answer the questions below. Then add a \`reading\` object t
       "kind": "limit",
       "files": 1,
       "evidence": "one dashboard page; may just be how it happened"
+    },
+    {
+      "text": "TextEditor's editable region is <EditorContent> - never render children into it directly",
+      "applies": ["TextEditor"],
+      "kind": "implementation",
+      "fact": true,
+      "evidence": "read in TextEditor itself: useEditor() feeds a single <EditorContent>"
     }
   ],
   "components": {
@@ -167,6 +195,7 @@ Open the project and answer the questions below. Then add a \`reading\` object t
       ]
     },
     "ArticleCard": {
+      "root": "Card",
       "anatomy": [
         { "as": "image", "name": "cover", "classes": "aspect-video w-full rounded-t-lg" },
         { "as": "heading", "name": "title", "classes": "text-lg font-semibold" },
@@ -184,7 +213,12 @@ Open the project and answer the questions below. Then add a \`reading\` object t
     },
     "TextEditor": {
       "anatomy": [
-        { "as": "row", "name": "toolbar", "classes": "flex gap-1 border-b p-2" },
+        {
+          "as": "row",
+          "name": "toolbar",
+          "classes": "flex gap-1 border-b p-2",
+          "children": [{ "as": "component", "ref": "ToolbarButton" }]
+        },
         { "as": "external", "from": "@tiptap/react" }
       ]
     }
@@ -221,6 +255,26 @@ about which one is the page. Read a screen and see.
 **\`fonts\` and \`concept\`** - the voice, and one paragraph on what this product is. The concept
 feeds every recommendation downstream, so a real one beats a generic one by a wide margin.
 
+**\`typeRoles\` - which of THEIR type steps plays each of our seven slots.**
+
+Their scale arrives under their own names now - \`h1\`, \`body-m\`, \`caption\`, \`overline\` - read
+straight off their \`--text-*\` declarations. What arithmetic cannot know is which of those steps
+is *body copy* and which is *the display size*, and our own components ask for it by slot:
+
+\`\`\`json
+"typeRoles": {
+  "xs": "caption", "sm": "body-s", "base": "body-m", "lg": "body-l",
+  "xl": "h3", "2xl": "h2", "display": "h1"
+}
+\`\`\`
+
+Leave it out and we pick by size, which is usually right and occasionally silly - a project whose
+\`overline\` is tiny and whose \`caption\` is tinier gets them the wrong way round. One line from you
+fixes it, and a person can correct it later in the studio either way.
+
+**Do not rename their steps to match ours.** \`h1\` stays \`h1\`. The whole point is that editing
+\`body-m\` in the studio moves the text in their app.
+
 **\`rules\` - how this company BUILDS, which is half of what they actually made.**
 
 A design system that arrives as tokens and recipes is only the vocabulary. The other half is the
@@ -258,12 +312,39 @@ Use it only when the rule genuinely depends on the environment. Most rules do no
 a Sidebar loose"* is true about their design regardless of framework, and pinning it to \`next\`
 would quietly drop it the day they add a second app.
 
-**Report \`files\` honestly - it decides whether the rule governs.** Three or more files is a
-habit and the rule arrives active; one file is a coincidence and it arrives as a candidate,
+**Report \`files\` honestly - it decides whether an OBSERVED rule governs.** Three or more files
+is a habit and the rule arrives active; one file is a coincidence and it arrives as a candidate,
 inactive, waiting for the person to promote it. You do not make that call; you report the
 evidence and a threshold makes it. So a pattern you saw once should say \`"files": 1\` even when
 you are confident - being wrong about a law is worse than being slow about one.
 
+**\`fact: true\` - for a rule you read in the DEFINITION, where counting is the wrong question.**
+
+Three of these were reported as \`files: 1\` and arrived inactive, which was correct arithmetic on
+the wrong kind of claim (dono, 01/08):
+
+\`\`\`
+the editable region is <EditorContent>
+toolbar actions go through editor.chain().focus()
+extensions are configured at construction
+\`\`\`
+
+None of those is a coincidence waiting for a second sighting. They are how the component IS
+built, read off its own source, and they are true the moment somebody wrote it. Counting how many
+files agree would leave every construction law in the codebase inactive forever.
+
+So the test is **where you read it**, not how sure you feel:
+
+\`\`\`
+fact: true    you read it inside the component's own definition - its imports, its
+              JSX, how its state is wired. True by construction.
+files: N      you inferred it from how the component is USED across the project.
+              An observation, and the count is what makes it a habit.
+\`\`\`
+
+A rule can carry \`fact\` OR \`files\`, never both. If you find yourself wanting both, it is an
+observation - use \`files\`.
+
 **Write \`evidence\` as what you actually saw.** "All three app shells wrap them; none renders
 them loose" lets somebody disagree with a fact. "Best practice" lets them disagree only with
 you.
@@ -302,7 +383,42 @@ an EXTERNAL  a third-party library       we do not have it and never will → bl
 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
+**You decide the depth, and nothing downstream caps it.** The platform follows a
+\`component\` edge into that component's own anatomy, and then into ITS edges, as far as the chain
+goes - \`Chat → Message → TypingIndicator\` renders all three. So a frontier is not a dead end you
+are apologising for; it is how the chain gets walked. Record the edge and stop, and the whole
+depth appears anyway.
+
+### The ROOT is a frontier too
+
+\`\`\`json
+"components": {
+  "ArticleCard": {
+    "root": "Card",
+    "anatomy": [ … ]
+  },
+  "Modal": {
+    "root": "BaseDialog.Root",
+    "anatomy": [ … ]
+  }
+}
+\`\`\`
+
+**Say what the component RETURNS when it is not a plain tag.** Measured on a real library
+(dono, 01/08): 14 of 23 components return one of their own - \`ArticleCard\` returns a \`<Card>\`,
+\`Button\` and \`Text\` return a \`<Component>\` - and 17 of 23 have no style of their own at all,
+because the surface belongs to the root.
+
+Without \`root\`, an \`ArticleCard\` previewed as floating text: the background, the border, the
+radius and the padding had nowhere to come from. With it, the card wears \`Card\`'s recipe as its
+shell and its own parts inside.
+
+- **their component** - the name, as their code spells it: \`"root": "Card"\`
+- **a library** - the dotted namespace, verbatim: \`"root": "Radio.Root"\`,
+  \`"root": "BaseDialog.Root"\`, \`"root": "Popover.Root"\`
+- **a plain tag** - leave it out. \`<div>\`, \`<td>\`, \`<button>\` are not frontiers.
+
+### The ten forms
 
 \`as\` says what a node IS, and the renderer draws that. Nothing else is accepted:
 
@@ -317,10 +433,40 @@ 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.
+
 **\`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
@@ -344,10 +490,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\`.
 
@@ -379,9 +537,15 @@ Send an anatomy for **every component with visible structure**, which is nearly
 \`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.
+**There is no node budget, and the one I gave you was wrong.** "Three to six nodes is a
+recognisable component" cost a real \`ArticleCard\` most of itself: it has a carousel with arrows,
+three image buttons, a source chip, a refresh, a rich body, a source line and a "Similar
+published content" region with two selects and two buttons - about fourteen regions - and the
+reading came back with six because the guidance said so (dono, 01/08).
+
+**One node per region a person can point at.** If they can say "that part", it is a node. What
+you still collapse is a wrapper whose only job is \`flex\` - fold it into the \`row\` it already is,
+because that is not a region, it is plumbing.
 
 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
@@ -395,7 +559,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
+Five 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.
 
@@ -479,6 +643,36 @@ 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.
+
 **3f. Fonts** - do not ask at all. Report and move on:
 
 \`\`\`
@@ -493,7 +687,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>]
@@ -501,7 +695,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
@@ -525,6 +719,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.78",
+  "version": "0.16.80",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {