synthesisui 0.16.72 → 0.16.74

package/dist/commands/import.js

@@ -11,7 +11,7 @@ import { describeConvention, describeRemainder, detectConventions, } from "../do
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { buildTable } from "../doctor/tokens.js";
-import { rootClasses, rootTag, transcribe, } from "../doctor/transcribe.js";
+import { rootClasses, rootTag, transcribe, transcribeParts, } from "../doctor/transcribe.js";
 import { body, paint, section } from "../output.js";
 import { walk, walkAll } from "./doctor.js";
 /**
@@ -958,6 +958,46 @@ function sayReach(c) {
         console.log(body(`Your neutrals only reach the ${has} end, so this system gets one scheme. A ${missing} mode would need surfaces you do not declare.`));
     }
 }
+/**
+ * Fold the skill's named parts into the transcription, in place.
+ *
+ * Their declared tokens come from the census itself, so a run that only sends a
+ * file it was handed still resolves a `bg-ocean-500` by their own name.
+ */
+function resolveReadParts(census) {
+    const read = census.reading?.components;
+    if (!read)
+        return;
+    const declared = new Map(Object.entries(census.declared));
+    const looks = census.looks ?? (census.looks = {});
+    let named = 0;
+    for (const [component, entry] of Object.entries(read)) {
+        const parts = entry?.parts;
+        if (!Array.isArray(parts) || parts.length === 0)
+            continue;
+        const resolved = transcribeParts(parts, declared);
+        if (Object.keys(resolved).length === 0)
+            continue;
+        const look = looks[component];
+        looks[component] = look
+            ? { ...look, parts: { ...(look.parts ?? {}), ...resolved } }
+            : {
+                base: {},
+                dark: {},
+                states: {},
+                skipped: [],
+                literals: [],
+                fromToken: 0,
+                fromLiteral: 0,
+                parts: resolved,
+            };
+        named += Object.keys(resolved).length;
+    }
+    if (named > 0) {
+        console.log("");
+        console.log(body(`${named} part${named === 1 ? "" : "s"} your reading named across ${Object.keys(read).length} component${Object.keys(read).length === 1 ? "" : "s"} - each previews as what it IS rather than as a text box`));
+    }
+}
 export async function runImport(opts) {
     const root = opts.root ?? process.cwd();
     /**
@@ -993,6 +1033,18 @@ export async function runImport(opts) {
             console.log(body("That file is not a census this version can send."));
             return;
         }
+        /**
+         * THE SKILL NAMED PARTS; THE CLI KNOWS WHAT THEIR CLASSES DO.
+         *
+         * A clean split of who knows what: only the skill can say that a span holds
+         * the title, and only this side can say that `text-ocean-500` is
+         * `{color.ocean.500}`. The platform then turns declarations into roles,
+         * because only it has the two palettes.
+         *
+         * Resolved here rather than at measure time because the reading arrives
+         * AFTER the census was taken - this is the first moment both halves exist.
+         */
+        resolveReadParts(census);
     }
     else {
         console.log(section("Reading your project"));

package/dist/doctor/transcribe.js

@@ -365,3 +365,20 @@ export function rootClasses(source) {
         .flatMap((m) => m[1].split(/\s+/))
         .filter((c) => c.length > 0 && !c.includes("${"));
 }
+/**
+ * Transcribe the parts a skill named, using the same reader the root used.
+ *
+ * `declared` comes from the census itself on the `--census` path, so a run that
+ * only sends a file it was handed still resolves their tokens by name.
+ */
+export function transcribeParts(parts, declared) {
+    const out = {};
+    for (const part of parts) {
+        const name = part.name?.trim();
+        if (!name || typeof part.classes !== "string")
+            continue;
+        const t = transcribe(part.classes.split(/\s+/).filter(Boolean), declared);
+        out[name] = { base: t.base, dark: t.dark, states: t.states };
+    }
+    return out;
+}

package/dist/skill-import.js

@@ -134,6 +134,31 @@ Open the project and answer the questions below. Then add a \`reading\` object t
   "roles": { "canvas": "#050505", "foreground": "#f9fafb", "primary": "#4A90E2" },
   "fonts": { "display": "Inter", "body": "Inter" },
   "concept": "one paragraph on what this product is",
+  "rules": [
+    {
+      "text": "A RootWrapper is what makes the app-shell components position correctly - never render a Sidebar or Topbar outside one",
+      "applies": ["RootWrapper", "Sidebar"],
+      "kind": "implementation",
+      "files": 3,
+      "evidence": "all three app shells wrap them; none renders them loose"
+    },
+    {
+      "text": "MetricCard is only used inside a grid, never on its own",
+      "applies": ["MetricCard"],
+      "kind": "limit",
+      "files": 1,
+      "evidence": "one dashboard page; may just be how it happened"
+    }
+  ],
+  "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" }
+      ]
+    }
+  },
   "by": "claude"
 }
 \`\`\`
@@ -166,6 +191,77 @@ 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.
 
+**\`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
+grammar: that a wrapper exists so the thing inside it works, that state arrives through a
+particular hook, that a card is never used loose. That is how the developer already thinks, and
+writing it down is what makes it survive them.
+
+Two dimensions, and they are independent:
+
+\`\`\`
+applies  []       the whole system
+         [a]      that component
+         [a, b]   a RELATION - two components that only work together
+
+kind     limit           a boundary, which the doctor can measure
+         implementation  how it is built, which no linter checks and an agent
+                         must be told
+\`\`\`
+
+The relation is the valuable one. \`[RootWrapper, Sidebar]\` says something neither name says
+alone, and it is exactly what an agent needs in order not to assemble it wrongly.
+
+**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,
+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.
+
+**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.
+
+Things worth looking for, none of them guessable from tokens:
+
+- a wrapper or provider whose whole purpose is to make something else work
+- an environment law - "this is Next, so the state comes through this hook" - which travels
+  with the system and only applies where that environment is
+- a component that is never used alone, or never used outside something
+- an axis that is always passed the same way in one place and never in another
+
+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.
+
+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.
+
+**The name is load-bearing, not a label.** The renderer infers a part's role from it:
+
+- \`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
+
+So a part named \`div2\` previews as a text node reading "Div2". Name what it IS: \`label\`, \`value\`,
+\`delta\`, \`icon\`, \`action\`, \`title\`, \`meta\`.
+
+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.
+
+If a component genuinely has no parts - a \`Divider\`, a \`Spinner\` - send none. An empty list is
+a real answer.
+
 ### 3. Walk them through the decisions, one at a time
 
 Four decisions are theirs. **Ask them as separate questions with selectable options** - use your

package/package.json

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