synthesisui 0.16.71 → 0.16.73

package/dist/commands/import.js

@@ -2,6 +2,7 @@ import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { basename, dirname, join, relative } from "node:path";
 import { readCredentials, readToken, resolveRegistry, sameRegistry, } from "../config.js";
 import { findBrokenRefs } from "../doctor/broken-refs.js";
+import { describeClassStyle, detectClassStyle, } from "../doctor/class-style.js";
 import { isNearDuplicate, isNeutral, lightness, } from "../doctor/color-distance.js";
 import { emptyTally, internalSpecifiers, scanComponentsInto, tallyToInventory, } from "../doctor/components-scan.js";
 import { crosswalk, observedRules } from "../doctor/crosswalk.js";
@@ -10,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";
 /**
@@ -407,12 +408,14 @@ export async function takeCensus(root) {
     }
     const brokenRefs = findBrokenRefs(sources, declaredNames);
     const conventions = detectConventions(sources);
+    const classStyle = detectClassStyle(sources);
     return {
         census: 1,
         project: { name, stack: await detectStack(root) },
         declared: Object.fromEntries(table.byName),
         ...(brokenRefs.length > 0 ? { brokenRefs } : {}),
         ...(conventions.length > 0 ? { conventions } : {}),
+        classStyle,
         ...(Object.keys(looks).length > 0 ? { looks } : {}),
         ...(schemes.alt.size > 0
             ? { declaredAlt: Object.fromEntries(schemes.alt) }
@@ -496,6 +499,10 @@ function sayConventions(c) {
         if (remainder)
             console.log(body(paint.faint(`  ${remainder}`)));
     }
+    if (c.classStyle) {
+        console.log("");
+        console.log(body(describeClassStyle(c.classStyle)));
+    }
     console.log("");
     console.log(body(paint.faint("Nothing here is a rule we brought - it is what your own files already do, and the system now knows it. None of the rest has to move today: this is a complement, not a correction.")));
 }
@@ -951,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();
     /**
@@ -986,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/class-style.js

@@ -0,0 +1,127 @@
+/**
+ * HOW THIS PROJECT NAMES A CLASS - and whether it names one at all.
+ *
+ * A compiled `.ds-metric-card` attaches to their markup, and a project whose own
+ * convention is `.metric-card__title` should not get a new name in its house for
+ * no reason it chose (dono, 01/08). So the convention has to be read, not
+ * assumed.
+ *
+ * Reading a real project first changed what this had to answer. Measured on a
+ * 670-stylesheet monorepo: 536 files are `*.module.scss` and 134 are not, and the
+ * class names inside them are `root`, `wrapper`, `editorText` - LOCAL names that
+ * a bundler hashes into `RootWrapper_root__x7f2a`.
+ *
+ * Which means there is no global convention there to follow, and our global
+ * class cannot collide with anything of theirs. The honest answer for that
+ * project is "nothing to change", and saying so is worth more than a concession
+ * nobody needed - inventing a problem is its own kind of dishonesty.
+ *
+ * Three worlds, and only the third asks anything of us:
+ *
+ *   modules   classes are local and hashed - ours are safe, and separate
+ *   utility   no component classes at all - ours are the only global ones
+ *   global    they DO name global classes, and we follow their shape
+ */
+const MODULE_FILE = /\.module\.(css|scss|sass|less)$/i;
+const STYLESHEET = /\.(css|scss|sass|less)$/i;
+/** A class selector at the start of a rule: `.metric-card__title {`. */
+const CLASS_DECL = /^\s*\.([a-zA-Z][a-zA-Z0-9_-]*)\s*[,{:]/gm;
+/** A Tailwind-shaped utility in markup - enough to know they exist. */
+const UTILITY = /\b(?:bg|text|border|p|px|py|m|mx|my|gap|flex|grid|rounded|shadow)-[a-z0-9[\]./-]+/g;
+/**
+ * Below this many global class declarations, a "convention" is a handful of
+ * one-off selectors rather than a house style - and adopting one from noise
+ * would rename everything we compile on the strength of three sightings.
+ */
+const MIN_GLOBAL_DECLS = 20;
+/**
+ * Prefixes worth honouring have to be shared by most of what they declare.
+ * A project with `app-header` and `admin-nav` has two words, not a prefix.
+ */
+const PREFIX_SHARE = 0.6;
+export function detectClassStyle(files) {
+    let moduleFiles = 0;
+    let globalFiles = 0;
+    let utilities = 0;
+    const globalDecls = [];
+    for (const { file, source } of files) {
+        if (MODULE_FILE.test(file)) {
+            moduleFiles += 1;
+            continue;
+        }
+        if (STYLESHEET.test(file)) {
+            globalFiles += 1;
+            // Only a non-module stylesheet can hold a class anybody else must match.
+            for (const m of source.matchAll(CLASS_DECL))
+                globalDecls.push(m[1]);
+            continue;
+        }
+        utilities += source.match(UTILITY)?.length ?? 0;
+    }
+    // Their own global classes come first - but only if they have a SHAPE.
+    //
+    // Counting them was not enough. A real repo returned `global` on the strength
+    // of a syntax-highlighting theme: `hll`, `field-name`, `document` cleared the
+    // threshold with no convention between them, and we would have renamed every
+    // class we compile to match vendor CSS (dono, 01/08). Many global classes with
+    // nothing in common is not a house style, it is a stylesheet.
+    if (globalDecls.length >= MIN_GLOBAL_DECLS) {
+        const shape = shapeOf(globalDecls);
+        if (shape) {
+            return {
+                kind: "global",
+                ...shape,
+                agreed: globalDecls.length,
+                samples: [...new Set(globalDecls)].slice(0, 3),
+            };
+        }
+    }
+    if (moduleFiles > globalFiles && moduleFiles > 0) {
+        return { kind: "modules", moduleFiles, globalFiles };
+    }
+    return { kind: "utility", utilities };
+}
+/**
+ * The shape their global classes share.
+ *
+ * BEM's `__` is unmistakable when present, so it is checked first and only
+ * accepted on a real share - two `__` selectors in a thousand is somebody's
+ * exception, not the house style.
+ */
+function shapeOf(decls) {
+    // BEM's `__` is unmistakable when it is the house style, and meaningless as
+    // somebody's two exceptions.
+    const bem = decls.filter((c) => c.includes("__")).length;
+    const isBem = bem / decls.length > 0.2;
+    // A prefix is the first delimited segment, when most of them share it. A
+    // project with `app-header` and `admin-nav` has two words, not a prefix.
+    const heads = new Map();
+    for (const c of decls) {
+        const head = c.split(/[-_]/)[0];
+        if (!head || head === c)
+            continue;
+        heads.set(head, (heads.get(head) ?? 0) + 1);
+    }
+    const top = [...heads.entries()].sort((a, b) => b[1] - a[1])[0];
+    const hasPrefix = top != null && top[1] / decls.length >= PREFIX_SHARE;
+    // Neither established: there is nothing here for us to follow, and adopting
+    // "unprefixed, hyphenated" from a grab-bag would rename everything we compile
+    // for no reason anybody chose.
+    if (!isBem && !hasPrefix)
+        return null;
+    return {
+        prefix: hasPrefix ? `${top[0]}-` : "",
+        partSeparator: isBem ? "__" : "-",
+    };
+}
+/** One line for the report, in their vocabulary and without asking for anything. */
+export function describeClassStyle(style) {
+    if (style.kind === "modules") {
+        return `your components style themselves through CSS Modules (${style.moduleFiles} module stylesheets) - those class names are local and hashed, so ours stay global and cannot collide with yours`;
+    }
+    if (style.kind === "utility") {
+        return "your components style themselves with utilities, so there are no component class names of yours for ours to match";
+    }
+    const named = style.prefix ? `prefixed \`${style.prefix}\`` : "unprefixed";
+    return `your global classes are ${named} and join parts with \`${style.partSeparator}\` (e.g. ${style.samples.join(", ")}) - what we compile will be spelled the same way`;
+}

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,15 @@ 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",
+  "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 +175,34 @@ 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.
 
+**\`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.71",
+  "version": "0.16.73",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {