synthesisui 0.16.65 → 0.16.66

package/dist/commands/import.js

@@ -10,6 +10,7 @@ import { describeConvention, detectConventions, IDIOM_LABEL, } from "../doctor/i
 import { diagnose, scanSource } from "../doctor/scan.js";
 import { parseSchemeBlocks } from "../doctor/scheme-blocks.js";
 import { buildTable } from "../doctor/tokens.js";
+import { rootClasses, transcribe, } from "../doctor/transcribe.js";
 import { body, paint, section } from "../output.js";
 import { walk, walkAll } from "./doctor.js";
 /**
@@ -278,6 +279,14 @@ export async function takeCensus(root) {
     // Kept for the reference check below, which needs every file at once: a name
     // is only broken if NOTHING declares it, anywhere.
     const sources = [];
+    // Name → value for every custom property their CSS declares, which is what
+    // turns `bg-ocean-500` into a token ref instead of a hex we looked up.
+    const declaredValues = new Map();
+    for (const m of css.matchAll(/(--[a-zA-Z0-9_-]+)\s*:\s*([^;}]+)/g)) {
+        if (!declaredValues.has(m[1]))
+            declaredValues.set(m[1], m[2].trim());
+    }
+    const looks = {};
     for await (const file of walk(root)) {
         const src = await readFile(file, "utf8").catch(() => "");
         if (!src)
@@ -292,7 +301,20 @@ export async function takeCensus(root) {
             scanComponentsInto(tally, rel, src, internal);
             // The other half: what this file EXPORTS, with the axes its types
             // declare. A library composes almost nothing and exports everything.
-            defined.push(...scanDefinitions(rel, src));
+            const found = scanDefinitions(rel, src);
+            defined.push(...found);
+            // THE LOOK, from their own class names. One transcription per file, keyed
+            // by the component it defines - the root element's classes are the
+            // component's own look, and everything below it is a part this slice does
+            // not attempt.
+            if (found.length > 0) {
+                const t = transcribe(rootClasses(src), declaredValues);
+                const size = Object.keys(t.base).length +
+                    Object.keys(t.dark).length +
+                    Object.keys(t.states).length;
+                if (size > 0)
+                    looks[found[0].name] = t;
+            }
         }
     }
     const d = diagnose(reports);
@@ -389,6 +411,7 @@ export async function takeCensus(root) {
         declared: Object.fromEntries(table.byName),
         ...(brokenRefs.length > 0 ? { brokenRefs } : {}),
         ...(conventions.length > 0 ? { conventions } : {}),
+        ...(Object.keys(looks).length > 0 ? { looks } : {}),
         ...(schemes.alt.size > 0
             ? { declaredAlt: Object.fromEntries(schemes.alt) }
             : {}),

package/dist/doctor/transcribe.js

@@ -0,0 +1,323 @@
+/**
+ * TRANSCRIBE A COMPONENT'S LOOK - deterministically, from their own class names.
+ *
+ * The import brings exclusive components in as contracts: axes declared, every
+ * style block empty. That was right when the alternative was inventing a look
+ * from a name. It is not right when the look is sitting in the file, spelled in
+ * a vocabulary we can read exactly.
+ *
+ * Measured before building any of this (dono, 01/08): across 23 exclusive
+ * components, 217 of 326 colour values resolve directly against their own
+ * declared tokens, and another 106 are Tailwind defaults - a fixed, published
+ * table. 99% is arithmetic. Nine of the 23 are entirely resolvable, and a single
+ * `TextEditor` holds 72% of all the ambiguity there is.
+ *
+ * So this is a transcriber, not a generator. No AI, no cost, no quota, and no
+ * chance of a value nobody wrote: every declaration it emits either points at a
+ * token they declared or carries a literal they typed.
+ *
+ * WHY NOT `refit`. That endpoint already turns arbitrary component code into a
+ * token-only recipe, and it is the right tool for its own job - bringing in
+ * code from OUTSIDE and dressing it in a system. But it maps every value to the
+ * NEAREST allowed token and never emits a raw one, which is normalisation, and
+ * v1 is a mirror. It also costs credits and has a daily quota, and a first
+ * import would spend 23 of them before anybody has seen value. It stays where
+ * it is; this runs first, for free, on what is already theirs.
+ *
+ * THE MODIFIER SAYS WHERE THE VALUE GOES, which is what makes this tractable:
+ *
+ *     bg-white                  → base
+ *     dark:bg-darkgray-500      → the dark side of base
+ *     hover:shadow-md           → states.hover
+ *     data-[checked]:bg-ocean-50 → states.checked
+ */
+/**
+ * Utility prefix → CSS property. Only the ones that carry DESIGN, which is the
+ * whole point: `flex`, `items-center` and `w-full` are structure, they are
+ * identical in every design system, and a recipe carrying them would be
+ * transcribing layout rather than a look.
+ */
+const COLOR_PROPERTY = {
+    bg: "background-color",
+    text: "color",
+    border: "border-color",
+    ring: "outline-color",
+    fill: "fill",
+    stroke: "stroke",
+    decoration: "text-decoration-color",
+};
+/** Tailwind's own spacing scale, in rem - the fixed part of the fixed table. */
+const SPACING = {
+    "0": "0",
+    px: "1px",
+    "0.5": "0.125rem",
+    "1": "0.25rem",
+    "1.5": "0.375rem",
+    "2": "0.5rem",
+    "2.5": "0.625rem",
+    "3": "0.75rem",
+    "3.5": "0.875rem",
+    "4": "1rem",
+    "5": "1.25rem",
+    "6": "1.5rem",
+    "7": "1.75rem",
+    "8": "2rem",
+    "9": "2.25rem",
+    "10": "2.5rem",
+    "11": "2.75rem",
+    "12": "3rem",
+    "14": "3.5rem",
+    "16": "4rem",
+    "20": "5rem",
+    "24": "6rem",
+};
+const SPACING_PROPERTY = {
+    p: "padding",
+    px: "padding-inline",
+    py: "padding-block",
+    pt: "padding-top",
+    pr: "padding-right",
+    pb: "padding-bottom",
+    pl: "padding-left",
+    m: "margin",
+    mx: "margin-inline",
+    my: "margin-block",
+    gap: "gap",
+};
+/** Tailwind's radius scale. */
+const RADIUS = {
+    none: "0",
+    sm: "0.125rem",
+    "": "0.25rem",
+    md: "0.375rem",
+    lg: "0.5rem",
+    xl: "0.75rem",
+    "2xl": "1rem",
+    "3xl": "1.5rem",
+    full: "9999px",
+};
+/** Tailwind's own colour table, for the values a project uses without declaring.
+ *  Only the ones that actually turn up: white, black, and the neutral ramp a
+ *  real project reached for 106 times. */
+const TAILWIND_COLOR = {
+    white: "#ffffff",
+    black: "#000000",
+    transparent: "transparent",
+    "neutral-50": "#fafafa",
+    "neutral-100": "#f5f5f5",
+    "neutral-200": "#e5e5e5",
+    "neutral-300": "#d4d4d4",
+    "neutral-400": "#a3a3a3",
+    "neutral-500": "#737373",
+    "neutral-600": "#525252",
+    "neutral-700": "#404040",
+    "neutral-800": "#262626",
+    "neutral-900": "#171717",
+    "neutral-950": "#0a0a0a",
+};
+/** States we recognise. Anything else is skipped rather than invented. */
+const STATE = /^(hover|focus|focus-visible|active|disabled|checked)$/;
+const DATA_STATE = /^data-\[([a-z-]+)\]$/;
+/**
+ * Split a class into its modifiers and the utility itself.
+ *
+ * Arbitrary values can contain colons (`bg-[url(a:b)]`), so the split stops at
+ * the first bracket - a naive split on `:` would shred them.
+ */
+export function parseClass(cls) {
+    // Bracket-aware, because BOTH sides use them: `data-[checked]:` is a modifier
+    // that contains one and `bg-[url(a:b)]` is a value that contains a colon. A
+    // first attempt stopped at the first `[`, which swallowed every `data-[…]:`
+    // modifier whole and dropped the state it named.
+    const modifiers = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < cls.length; i++) {
+        const ch = cls[i];
+        if (ch === "[")
+            depth += 1;
+        else if (ch === "]")
+            depth -= 1;
+        else if (ch === ":" && depth === 0) {
+            modifiers.push(cls.slice(start, i));
+            start = i + 1;
+        }
+    }
+    return { modifiers, utility: cls.slice(start) };
+}
+/**
+ * One utility → one declaration, or nothing.
+ *
+ * `declared` maps a token NAME to its value, so a resolved colour can be
+ * reported in their vocabulary rather than as a hex we looked up.
+ */
+export function readUtility(utility, declared) {
+    // An opacity modifier changes the value, not the property, and honouring it
+    // would mean computing a colour they never wrote. The property still belongs
+    // in the recipe, so the base colour travels and the alpha does not.
+    const [core] = utility.split("/");
+    const dash = core.indexOf("-");
+    if (dash === -1)
+        return null;
+    const prefix = core.slice(0, dash);
+    const rest = core.slice(dash + 1);
+    const colorProp = COLOR_PROPERTY[prefix];
+    if (colorProp) {
+        // Their own token first: `--color-ocean-500` for `bg-ocean-500`, which is
+        // exactly how Tailwind v4's `@theme` publishes it.
+        const own = `--color-${rest}`;
+        if (declared.has(own)) {
+            return { property: colorProp, value: refFor(rest), token: own };
+        }
+        const builtin = TAILWIND_COLOR[rest];
+        if (builtin)
+            return { property: colorProp, value: builtin };
+        return null;
+    }
+    const spaceProp = SPACING_PROPERTY[prefix];
+    if (spaceProp && SPACING[rest]) {
+        return { property: spaceProp, value: SPACING[rest] };
+    }
+    if (prefix === "rounded") {
+        const own = `--radius-${rest}`;
+        if (declared.has(own)) {
+            return {
+                property: "border-radius",
+                value: `{radius.${rest}}`,
+                token: own,
+            };
+        }
+        if (RADIUS[rest])
+            return { property: "border-radius", value: RADIUS[rest] };
+    }
+    return null;
+}
+/**
+ * A colour token ref in the document's own spelling.
+ *
+ * `ocean-500` → `{color.ocean.500}`. The step is the trailing number; anything
+ * before it is the family, hyphens intact, because `royal-blue-500` is one
+ * family called `royal-blue`.
+ */
+function refFor(name) {
+    const m = /^(.*)-(\d{2,4})$/.exec(name);
+    if (!m)
+        return `{color.${name}}`;
+    return `{color.${m[1]}.${m[2]}}`;
+}
+/**
+ * Read every class in a component's root element and route each declaration by
+ * its modifier.
+ *
+ * Unknown modifiers are skipped, not flattened into `base`: a `sm:` or
+ * `group-data-[checked]:` value written into the resting state would be a look
+ * the component never has.
+ */
+export function transcribe(classes, declared) {
+    const out = {
+        base: {},
+        states: {},
+        dark: {},
+        skipped: [],
+        fromToken: 0,
+        fromLiteral: 0,
+    };
+    for (const cls of classes) {
+        const { modifiers, utility } = parseClass(cls);
+        const isDark = modifiers.includes("dark");
+        const rest = modifiers.filter((m) => m !== "dark");
+        // THE SLOT IS DECIDED BEFORE THE VALUE IS READ. Resolving first meant a
+        // `dark:hover:` whose colour happened to be undeclared vanished in silence
+        // rather than being reported as a look we have nowhere to put - two
+        // different problems, and only one of them is theirs to hear about.
+        let target = null;
+        let unslotted = false;
+        if (rest.length === 0) {
+            target = isDark ? out.dark : out.base;
+        }
+        else if (rest.length === 1 && !isDark) {
+            const state = STATE.test(rest[0])
+                ? rest[0]
+                : (DATA_STATE.exec(rest[0])?.[1] ?? null);
+            if (state)
+                target = out.states[state] ?? (out.states[state] = {});
+            else
+                unslotted = true;
+        }
+        else {
+            // A state under `dark:` is the dark scheme's version of that state, and a
+            // recipe has no slot for it.
+            unslotted = true;
+        }
+        const decl = readUtility(utility, declared);
+        if (unslotted) {
+            // Only worth saying when it IS a design value; an unslotted `sm:flex` is
+            // layout and nobody needs to hear about it.
+            if (decl)
+                out.skipped.push(cls);
+            continue;
+        }
+        if (!decl || !target)
+            continue;
+        // First write wins, matching how a class list resolves for the properties
+        // we read: later duplicates in the same list are almost always a merge
+        // artefact rather than an override.
+        if (target[decl.property] != null)
+            continue;
+        target[decl.property] = decl.value;
+        if (decl.token)
+            out.fromToken += 1;
+        else
+            out.fromLiteral += 1;
+    }
+    return out;
+}
+/**
+ * THE ROOT ELEMENT'S CLASSES, from a component file.
+ *
+ * A component's look lives on the outermost element it returns, and everything
+ * below it is a part - which a recipe has slots for and this slice does not
+ * attempt. Finding the root without an AST: the first JSX tag after `return (`
+ * is it, and its class list runs to the first `>` at depth zero.
+ *
+ * Deliberately conservative. A file this cannot read confidently returns
+ * nothing, and nothing is a contract with an empty base - which is exactly what
+ * the import already produces, so failing here costs no ground.
+ */
+export function rootClasses(source) {
+    const ret = source.search(/return\s*\(/);
+    if (ret === -1)
+        return [];
+    const open = source.indexOf("<", ret);
+    if (open === -1)
+        return [];
+    // Walk to the end of the opening tag, tracking brackets so a `className={cn(
+    // "a", cond ? "b" : "c")}` block is read whole rather than cut at its first
+    // `>` inside a comparison.
+    let depth = 0;
+    let end = -1;
+    for (let i = open + 1; i < source.length; i++) {
+        const ch = source[i];
+        if (ch === "{" || ch === "(" || ch === "[")
+            depth += 1;
+        else if (ch === "}" || ch === ")" || ch === "]")
+            depth -= 1;
+        else if (ch === ">" && depth <= 0) {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1)
+        return [];
+    const tag = source.slice(open, end);
+    const at = tag.search(/className\s*=/);
+    if (at === -1)
+        return [];
+    // Every string literal inside the className expression. Template literals and
+    // computed values are skipped on purpose: a class we cannot see in full is a
+    // class we would be guessing at.
+    const expr = tag.slice(at);
+    return [...expr.matchAll(/["']([^"']+)["']/g)]
+        .flatMap((m) => m[1].split(/\s+/))
+        .filter((c) => c.length > 0 && !c.includes("${"));
+}

package/package.json

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