synthesisui 0.12.1 → 0.14.0

package/dist/commands/add.js

@@ -206,6 +206,12 @@ export async function add(slug, opts) {
         console.log(line(`   Prefer next/font or self-hosting? Fine - just register these exact families: ${customFontFamilies(families).join(", ")}.`));
     }
     console.log(section("Next"));
+    // FIRST, and before anything that assumes the setup worked. The block above
+    // is four manual edits across two files, one of them with a relative path
+    // the command itself has to warn about. Without a way to check, the person
+    // does not know whether they finished - and the next thing they see is a
+    // coverage number that reads 0% when an import is missing.
+    console.log(line(`synthesisui doctor                    confirm the setup above actually took`));
     console.log(line(`synthesisui component ${payload.slug} button    bring a component in as YOUR code`));
     console.log(line(`synthesisui template ${payload.slug} landing    materialize a whole page`));
     console.log("");

package/dist/commands/doctor.js

@@ -137,12 +137,38 @@ async function loadSystem(root) {
     }
     return { table: buildTable({ css, lock }), recipes, documents };
 }
+/**
+ * The project's OWN vocabulary, when we did not put one there.
+ *
+ * Measured 27/07 against a repo holding eight `--acme-*` tokens in `:root`, a
+ * button correctly on `var(--acme-color-primary)` and a banner hardcoding the
+ * same `#3b82f6`: the report said "No system installed" and counted five
+ * anonymous values. That is the exact reader the landing page invites - the
+ * one who already owns a system and wants to know whether the code still
+ * obeys it - and the tool was blind to them because `parseTokens` only ever
+ * looked for our own `--ds-` prefix.
+ *
+ * Reads stylesheets only, and only when nothing of ours is installed, so the
+ * common path pays nothing for it.
+ */
+async function harvestOwnTokens(roots) {
+    let css = "";
+    for await (const file of walkAll(roots)) {
+        if (!/\.(css|scss|sass|less)$/i.test(file))
+            continue;
+        css += `\n${await readFile(file, "utf8").catch(() => "")}`;
+    }
+    return buildTable({ css, source: "yours" });
+}
 const KIND_LABEL = {
     color: "colour",
     radius: "radius",
     spacing: "spacing",
     font: "type",
 };
+/** "1 file", "2 files" - a report that says "1 files read" on its very first
+ *  line spends credibility before it has said anything. */
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
 /** A bar you can read at a glance, in a font that is always monospace. */
 function meter(pct, width = 24) {
     const filled = Math.round((pct / 100) * width);
@@ -217,18 +243,46 @@ function verdict(d, hasSystem, overruled, conflicts) {
 }
 export async function doctor(opts) {
     const root = resolve(opts.dir ?? process.cwd());
-    const { table, recipes, documents } = await loadSystem(root);
-    const hasSystem = table.byName.size > 0;
     const scopes = (opts.scopes ?? []).map((s) => resolve(root, s));
+    const installed = await loadSystem(root);
+    const { recipes, documents } = installed;
+    let table = installed.table;
+    // Nothing of ours here does not mean nothing to measure against. Fall back
+    // to whatever vocabulary the project already declares for itself.
+    if (table.byName.size === 0) {
+        table = await harvestOwnTokens(scopes.length > 0 ? scopes : [root]);
+    }
+    const hasSystem = table.byName.size > 0;
     const reports = [];
     const overrides = [];
     const used = new Map();
     const known = new Set(recipes.keys());
+    /**
+     * INSTALLED IS NOT THE SAME AS WORKING.
+     *
+     * `init` ends in four manual edits across two files. Skip them - or get the
+     * relative path in the import wrong, which the command itself warns about -
+     * and the next run reports "Token coverage 0%" with no explanation
+     * (reproduced 27/07 on a fresh project). The tool knows the system is
+     * installed, because it just read 85 tokens out of it, and reports a number
+     * that reads as failure when the truth is an unfinished setup.
+     *
+     * Nobody debugs from 0%. They conclude the product does not work.
+     */
+    const wiring = { imported: false, scoped: false };
     for await (const file of scopes.length > 0 ? walkAll(scopes) : walk(root)) {
         const src = await readFile(file, "utf8").catch(() => "");
         if (!src)
             continue;
         const rel = relative(root, file);
+        // The two facts that decide whether an installed system reaches the
+        // browser at all. Free: these files are already open and in memory.
+        if (table.slug) {
+            if (src.includes(`_synthesisui/ds/${table.slug}/tokens.css`))
+                wiring.imported = true;
+            if (src.includes(`data-ds="${table.slug}"`))
+                wiring.scoped = true;
+        }
         reports.push(scanSource(rel, src, table));
         if (recipes.size > 0) {
             for (const o of findOverrides(src, recipes))
@@ -261,9 +315,15 @@ export async function doctor(opts) {
             console.log(line);
     };
     console.log(section("Doctor"));
-    console.log(body(hasSystem
-        ? `${table.name ?? table.slug} v${table.version ?? "?"} - ${table.byName.size} tokens, ${d.scanned} files read`
-        : `No system installed - ${d.scanned} files read`));
+    console.log(body(
+    // Three states, not two. "yours" has no lock to name it, and printing
+    // `null v?` for a project that DOES have a system would be the worst
+    // possible first line.
+    table.source === "installed"
+        ? `${table.name ?? table.slug} v${table.version ?? "?"} - ${plural(table.byName.size, "token")}, ${plural(d.scanned, "file")} read`
+        : table.source === "yours"
+            ? `Your own tokens - ${plural(table.byName.size, "token")} found, ${plural(d.scanned, "file")} read`
+            : `No system installed - ${plural(d.scanned, "file")} read`));
     if (scopes.length > 0) {
         console.log(body(`scope: ${opts.scopes?.join(", ")}`));
     }
@@ -281,15 +341,34 @@ export async function doctor(opts) {
     const asideTotal = [...aside.values()].reduce((n, v) => n + v, 0);
     if (verbose) {
         for (const [reason, count] of aside) {
-            console.log(body(`set aside: ${count} value(s) in ${reason}`));
+            console.log(body(`set aside: ${plural(count, "value")} in ${reason}`));
         }
     }
     else if (asideTotal > 0) {
-        console.log(body(`set aside ${asideTotal} value(s) a token could never hold (--verbose for why)`));
+        console.log(body(`set aside ${plural(asideTotal, "value")} a token could never hold (--verbose for why)`));
     }
     // 0 of 0 is not a perfect score, it is an empty measurement - printing a
     // full bar there would be the report's first lie.
     const measurable = d.tokenUses + d.findings.length > 0;
+    // Before the number, because the number is the thing that misleads. An
+    // installed-but-unwired system reads 0%, and 0% reads as "broken product"
+    // rather than "one import missing".
+    const unwired = table.source === "installed" && (!wiring.imported || !wiring.scoped);
+    if (unwired) {
+        console.log("");
+        console.log(body(`${table.name ?? table.slug} is installed - but not wired up yet.`));
+        console.log("");
+        console.log(body(wiring.imported
+            ? `  ✓ some stylesheet imports _synthesisui/ds/${table.slug}/tokens.css`
+            : `  ✗ no stylesheet imports _synthesisui/ds/${table.slug}/tokens.css`));
+        console.log(body(wiring.scoped
+            ? `  ✓ data-ds="${table.slug}" found`
+            : `  ✗ no element carries data-ds="${table.slug}"`));
+        console.log("");
+        console.log(body(`Until both are true, none of the ${table.byName.size} tokens reach the browser`));
+        console.log(body("and the number below cannot mean anything."));
+        console.log(body("The exact snippets are in the output of `init`."));
+    }
     if (hasSystem && measurable) {
         console.log("");
         console.log(body(`Token coverage  ${meter(d.coverage)}  ${String(d.coverage).padStart(3)}%`));
@@ -595,7 +674,7 @@ export async function doctor(opts) {
     else if (!verbose) {
         if (conflictsInUse.length + frozen.length > 0) {
             console.log("");
-            console.log(body(`${conflictsInUse.length + frozen.length} problem(s) in the SYSTEM - not fixable from this repo`));
+            console.log(body(`${plural(conflictsInUse.length + frozen.length, "problem")} in the SYSTEM - not fixable from this repo`));
             for (const c of conflictsInUse) {
                 console.log(`      ds-${c.component}    the law forbids ${c.forbids}, the recipe binds it`);
             }
@@ -605,8 +684,8 @@ export async function doctor(opts) {
         }
         if (d.findings.length > 0 || overrides.length > 0) {
             console.log("");
-            console.log(body(`${d.findings.length} value(s) by hand · ${d.named} already have a name`));
-            console.log(body(`${overrides.length - lawKeepingCount} override(s) · ${offSystemCount} left the system` +
+            console.log(body(`${plural(d.findings.length, "value")} by hand · ${d.named} already ${d.named === 1 ? "has" : "have"} a name`));
+            console.log(body(`${plural(overrides.length - lawKeepingCount, "override")} · ${offSystemCount} left the system` +
                 (lawKeepingCount > 0
                     ? ` · ${lawKeepingCount} more kept a law`
                     : "")));
@@ -622,6 +701,42 @@ export async function doctor(opts) {
         }
         console.log("");
         console.log(body("synthesisui doctor --verbose   every finding, file by file"));
+        /**
+         * THE READER WHO GOT A NUMBER AND NOWHERE TO GO.
+         *
+         * Someone with no system at all is told to start one. Someone running OUR
+         * system has commands everywhere. The person in between - who already owns
+         * a design system, which is precisely the ICP - got the report and silence,
+         * and closed the terminal (walked 27/07).
+         *
+         * The sentence follows from THEIR number rather than pitching: the value
+         * is not that we would name these, it is that their agent has no way to
+         * know they should be named. That is also the line worth pasting into a
+         * thread, which is the other job this paragraph does.
+         */
+        if (table.source === "yours") {
+            const named = d.findings.filter((f) => f.token).length;
+            const anonymous = d.findings.length - named;
+            console.log("");
+            console.log(body(named > 0
+                ? `${named} of these already have a name in your own system.`
+                : "None of these have a name in your system yet."));
+            if (anonymous > 0) {
+                console.log(body(`The other ${anonymous} do not - and your coding agent has no way to know they should.`));
+            }
+            console.log("");
+            // Careful about what is being offered. This reader ALREADY has a design
+            // system, so "install ours" would mean replacing theirs, and a CTA that
+            // pretends otherwise is the kind of confident overclaim that costs
+            // trust the first time somebody follows it. What they are missing is
+            // not tokens - it is a contract their agent reads before writing UI.
+            console.log(body("Your tokens exist. What your agent is missing is a contract:"));
+            console.log(body("rules it reads BEFORE writing UI, and a manifest of what exists."));
+            console.log("");
+            console.log(snippet(["npx synthesisui@latest init --ds <slug>"]));
+            console.log(body("starts you on a system that ships one - browse them at"));
+            console.log(body("https://www.synthesisui.com/gallery"));
+        }
         console.log("");
     }
     if (opts.strict) {
@@ -633,11 +748,11 @@ export async function doctor(opts) {
         // authors their own system wants the opposite, and asks for it.
         const theirs = conflictsInUse.length + frozen.length;
         if (opts.strictSystem && theirs > 0) {
-            console.log(body(`--strict-system: ${theirs} problem(s) in the system itself. Failing.`));
+            console.log(body(`--strict-system: ${plural(theirs, "problem")} in the system itself. Failing.`));
             process.exitCode = 1;
         }
         else if (theirs > 0) {
-            console.log(body(`${theirs} problem(s) above are in the system, not this repo - not failing.`));
+            console.log(body(`${plural(theirs, "problem")} above ${theirs === 1 ? "is" : "are"} in the system, not this repo - not failing.`));
             console.log(body("Run with --strict-system if the system is yours."));
         }
         if (mine)

package/dist/doctor/scan.js

@@ -38,23 +38,53 @@ const RADIUS = /(?:border-radius\s*:\s*|rounded(?:-[a-z]+)?-\[)(-?\d*\.?\d+)(px|
 const SPACING = /(?:\b[pmg](?:[trblxy])?-\[|gap-\[|(?:padding|margin|gap)\s*:\s*)(-?\d*\.?\d+)(px|rem)/g;
 /** A font stack written by hand rather than taken from the type scale. */
 const FONT = /font-family\s*:\s*([^;}\n]+)/g;
-/** Uses of the system. Coverage is meaningless without them. */
-const TOKEN_USE = /var\(\s*--ds-[a-z0-9-]+/gi;
+/**
+ * Uses of the system. Coverage is meaningless without them.
+ *
+ * Both of these used to be pinned to our own `--ds-` prefix, which quietly
+ * decided that only OUR systems count. A project with `--acme-color-primary`
+ * in `:root` and `var(--acme-color-primary)` in a button was reported at 0%
+ * coverage while doing everything right (measured 27/07). The rule now: our
+ * prefix always counts, and any other custom property counts once we have
+ * seen it declared - which is exactly what the token table knows.
+ */
+const ANY_VAR_USE = /var\(\s*(--[a-z0-9_-]+)/gi;
+const ANY_VAR_FALLBACK = /var\(\s*(--[a-z0-9_-]+)\s*,([^()]*)\)/gi;
+const isKnownToken = (name, table) => name.startsWith("--ds-") || table.byName.has(name);
+function countTokenUses(line, table) {
+    let n = 0;
+    for (const m of line.matchAll(ANY_VAR_USE)) {
+        if (isKnownToken(m[1].toLowerCase(), table))
+            n++;
+    }
+    return n;
+}
 /**
  * `var(--ds-color-semantic-primary, #5266eb)` - the literal is the TOKEN'S OWN
  * fallback, written for safety, and reporting it as drift told an author to
  * tokenize something they had already tokenized (investidorez, 25/07). The
  * spans below are the fallback arguments on a line.
  */
-const VAR_FALLBACK = /var\(\s*--ds-[a-z0-9-]+\s*,([^()]*)\)/gi;
-function fallbackSpans(line) {
+function fallbackSpans(line, table) {
     const out = [];
-    for (const m of line.matchAll(VAR_FALLBACK)) {
+    for (const m of line.matchAll(ANY_VAR_FALLBACK)) {
+        if (!isKnownToken(m[1].toLowerCase(), table))
+            continue;
         const start = (m.index ?? 0) + m[0].indexOf(",") + 1;
-        out.push([start, start + m[1].length]);
+        out.push([start, start + m[2].length]);
     }
     return out;
 }
+/**
+ * The line that DEFINES a token is not a line that drifted from it.
+ *
+ * Our own tokens.css lives under `_synthesisui`, which the walk skips, so this
+ * never came up. A project's own stylesheet does not have that luxury: on the
+ * first run against one, every `--acme-color-primary: #3b82f6` came back as a
+ * hardcoded colour, which is the tool accusing the author of the very thing it
+ * is measuring them against.
+ */
+const DECLARES_TOKEN = /^\s*(--[a-z0-9_-]+)\s*:/i;
 /** Under this, a radius or spacing value is idiom rather than a decision. */
 const IDIOM = new Set(["0", "0px", "1px", "9999px", "100%", "50%"]);
 export function scanSource(file, source, table) {
@@ -81,7 +111,7 @@ export function scanSource(file, source, table) {
     source.split("\n").forEach((raw, i) => {
         const line = raw.trim();
         const at = i + 1;
-        tokenUses += (line.match(TOKEN_USE) ?? []).length;
+        tokenUses += countTokenUses(line, table);
         // Depth at the START of this line, carried before the early return so a
         // blank line inside an <svg> cannot close the region by accident. The
         // per-match depth is recomputed below, because an icon is often written on
@@ -93,11 +123,18 @@ export function scanSource(file, source, table) {
             (line.match(/<\/svg>/g) ?? []).length);
         if (!line || IGNORE_LINE.test(line))
             return;
+        // The declaration of a token we are measuring against is the definition,
+        // not drift. Scoped to tokens the table already knows, so a one-off
+        // `--card-shadow: 0 2px 8px #0002` invented inside a component is still
+        // reported - that one really is a decision made outside the system.
+        const declares = DECLARES_TOKEN.exec(line);
+        if (declares && table.byName.has(declares[1].toLowerCase()))
+            return;
         // `rgba(${r}, ${g}, ${b}, ${a})` is code computing a colour, not a colour
         // written by hand - flagging it would be telling someone to tokenize a
         // variable. And the same literal twice in one declaration (a two-stop
         // shadow) is one decision, so it is reported once.
-        const spans = fallbackSpans(line);
+        const spans = fallbackSpans(line, table);
         const inFallback = (at) => spans.some(([a, b]) => at >= a && at <= b);
         const seen = new Set();
         // NOT named `at`: that is the line number in this scope, and shadowing it

package/dist/doctor/tokens.js

@@ -12,6 +12,7 @@
  * returns data, so the whole diagnosis is testable without a filesystem.
  */
 export const EMPTY_TABLE = {
+    source: null,
     name: null,
     slug: null,
     version: null,
@@ -21,6 +22,62 @@ export const EMPTY_TABLE = {
 const hex2 = (n) => Math.max(0, Math.min(255, Math.round(n)))
     .toString(16)
     .padStart(2, "0");
+/** Linear-light channel to the sRGB byte a screen actually paints. */
+const gamma = (c) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055) * 255;
+/**
+ * `oklch(0.648 0.2 131.684)` → the same key as the hex somebody pasted.
+ *
+ * Measured 27/07 against shadcn/ui, 3846 files: 48 tokens found, 1383 values
+ * written by hand, and **zero** matched - because shadcn declares in oklch and
+ * the code hardcodes hex. Tailwind v4 emits oklch by default too, so the one
+ * thing this tool does that a linter cannot - say what your system already
+ * calls the value - silently returned nothing on the most common modern stack.
+ *
+ * This is not fuzzy matching, which the exact-match rule below rightly
+ * forbids. It is finishing the job `normalizeValue` already claims to do:
+ * every dialect lands on one key. Rounding to 8 bits is precisely what the
+ * browser does on an sRGB display, and out-of-gamut coordinates clamp the same
+ * way they would on screen.
+ */
+function oklchToBytes(l, c, hDeg) {
+    const h = (hDeg * Math.PI) / 180;
+    const a = c * Math.cos(h);
+    const b = c * Math.sin(h);
+    const l_ = (l + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+    const m_ = (l - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+    const s_ = (l - 0.0894841775 * a - 1.291485548 * b) ** 3;
+    return [
+        gamma(4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_),
+        gamma(-1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_),
+        gamma(-0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_),
+    ];
+}
+/** `hsl(222 47% 11%)`, the dialect shadcn used before it moved to oklch. */
+function hslToBytes(h, s, l) {
+    const k = (n) => (n + h / 30) % 12;
+    const a = s * Math.min(l, 1 - l);
+    const f = (n) => (l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)))) * 255;
+    return [f(0), f(8), f(4)];
+}
+/** The numbers inside a colour function, in any of CSS's separator dialects. */
+function args(body) {
+    const parts = body.split(/[\s,/]+/).filter(Boolean);
+    if (parts.length < 3)
+        return null;
+    const nums = parts.slice(0, 3).map((p) => {
+        const n = Number.parseFloat(p);
+        return p.endsWith("%") ? n / 100 : n;
+    });
+    if (!nums.every(Number.isFinite))
+        return null;
+    const rawA = parts[3];
+    const alpha = rawA === undefined
+        ? 1
+        : rawA.endsWith("%")
+            ? Number.parseFloat(rawA) / 100
+            : Number.parseFloat(rawA);
+    return { nums, alpha: Number.isFinite(alpha) ? alpha : 1 };
+}
 /**
  * One key per colour, whatever dialect it was written in.
  *
@@ -41,6 +98,29 @@ export function normalizeValue(raw) {
     const long = /^#([0-9a-f]{6})([0-9a-f]{2})?$/.exec(v);
     if (long)
         return `#${long[1]}${long[2] ?? "ff"}`;
+    const ok = /^oklch\(([^)]+)\)$/.exec(v);
+    if (ok) {
+        const a = args(ok[1]);
+        // The hue is an angle, not a fraction: `131.684` must not be read as a
+        // percentage the way lightness is.
+        if (a) {
+            const hue = /%$/.test(ok[1].split(/[\s,/]+/).filter(Boolean)[2] ?? "")
+                ? a.nums[2] * 100
+                : a.nums[2];
+            const [r, g, b] = oklchToBytes(a.nums[0], a.nums[1], hue);
+            return `#${hex2(r)}${hex2(g)}${hex2(b)}${hex2(a.alpha * 255)}`;
+        }
+    }
+    const hsl = /^hsla?\(([^)]+)\)$/.exec(v);
+    if (hsl) {
+        const a = args(hsl[1]);
+        if (a) {
+            const raw = hsl[1].split(/[\s,/]+/).filter(Boolean);
+            const hue = Number.parseFloat(raw[0]);
+            const [r, g, b] = hslToBytes(((hue % 360) + 360) % 360, a.nums[1], a.nums[2]);
+            return `#${hex2(r)}${hex2(g)}${hex2(b)}${hex2(a.alpha * 255)}`;
+        }
+    }
     const rgb = /^rgba?\(([^)]+)\)$/.exec(v);
     if (rgb) {
         const parts = rgb[1].split(/[\s,/]+/).filter(Boolean);
@@ -86,8 +166,53 @@ export function parseTokens(css) {
     }
     return out;
 }
+/**
+ * Custom properties the project declares AT THE ROOT, whatever it calls them.
+ *
+ * This is what lets the tool answer the only question its sharpest reader has:
+ * not "do you use SynthesisUI" but "does my own code still obey my own
+ * system". Someone with `--acme-color-primary: #3b82f6` in `:root` and
+ * `#3b82f6` hardcoded in a banner has drift, and until now we told them no
+ * system was installed and counted their values as anonymous.
+ *
+ * SCOPE IS THE HEURISTIC, not a prefix allow-list. A design token is declared
+ * once at the root; a runtime variable is set per element. That single rule
+ * keeps `:root`, `html`, `:host` and Tailwind v4's `@theme` - all places an
+ * author writes their vocabulary - and drops Tailwind v3's `--tw-*` defaults
+ * (declared on `*, ::before, ::after`) and Radix's `--radix-*` (set on the
+ * component) without naming a single vendor.
+ *
+ * The flat brace regex is deliberate and handles one level of nesting for
+ * free: against `@media x { :root { ... } }` the outer selector fails to match
+ * because its body contains a brace, so the scan moves on and finds the inner
+ * block on its own.
+ */
+export function parseRootTokens(css) {
+    const out = new Map();
+    for (const block of css.matchAll(/([^{}]*)\{([^{}]*)\}/g)) {
+        const selector = block[1].trim();
+        const isRoot = /^@theme\b/i.test(selector) ||
+            /(^|[\s,>+~])(:root|html|:host)\b/i.test(selector);
+        if (!isRoot)
+            continue;
+        for (const m of block[2].matchAll(/(--[a-z0-9_-]+)\s*:\s*([^;}]+)/gi)) {
+            const name = m[1].toLowerCase();
+            // Belt and braces: v4 emits some `--tw-*` bookkeeping into @theme, and
+            // it is machinery, not somebody's design vocabulary.
+            if (name.startsWith("--tw-"))
+                continue;
+            const value = m[2].trim();
+            if (!value || value.startsWith("var("))
+                continue;
+            if (!out.has(name))
+                out.set(name, value);
+        }
+    }
+    return out;
+}
 export function buildTable(input) {
-    const byName = parseTokens(input.css);
+    const source = input.source ?? "installed";
+    const byName = source === "yours" ? parseRootTokens(input.css) : parseTokens(input.css);
     const byValue = new Map();
     for (const [name, value] of byName) {
         const key = normalizeValue(value);
@@ -98,6 +223,7 @@ export function buildTable(input) {
             byValue.set(key, [name]);
     }
     return {
+        source: byName.size > 0 ? source : null,
         name: input.lock?.name ?? null,
         slug: input.lock?.slug ?? null,
         version: input.lock?.version ?? null,

package/package.json

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