synthesisui 0.16.17 → 0.16.19

package/dist/claude-md.js

@@ -281,11 +281,11 @@ YOURSELF. It materializes that component as real typed code in this project, and
 extend that. The person who asked you for a feature should never have to know these command
 names or type them; finding the right component is your job, not theirs.
 
-When you override a style a component already sets, add \`!\` to your class:
-\`className="text-info!"\`, not \`className="text-info"\`. Both are plain utilities at the
-same specificity, so which one wins is decided by the order Tailwind writes the stylesheet -
-not by the order of the class names, which is what the code looks like it controls. This
-applies to the Tailwind flavour only; the CSS one is layered and needs no marker.
+Overriding a style a component already sets just works - write
+\`className="text-info"\`, with no \`!\`. The generated components resolve your class
+against their own, so the last one written wins, which is what the call site reads like.
+If an override is ignored, that component predates the resolver: regenerate it with
+\`npx synthesisui@latest component <slug> <name>\` rather than reaching for \`!\`.
 
 Only write something new when nothing in the manifest covers the purpose - and when you do,
 say which entry you considered and why it did not fit. To review a

package/dist/cn-codegen.js

@@ -0,0 +1,168 @@
+/**
+ * `cn()`: the override the consumer writes has to actually win.
+ *
+ * THE BUG. Two plain Tailwind utilities that set the same property have the
+ * same specificity, so which one applies is decided by the order Tailwind emits
+ * them into the stylesheet - not by the order of names in the string, which is
+ * the only thing the call site appears to control. A component whose base says
+ * `text-foreground` therefore ignores `className="text-info"`, silently, and
+ * the code reads as if it should work.
+ *
+ * THE MITIGATION WE SHIPPED FIRST, and why it was not enough. On 27/07 the
+ * managed block started telling agents to write `text-info!`. It works, and the
+ * test on 28/07 measured what it costs: 61 exclamation marks in 1,885 generated
+ * lines, one forced escape every thirty lines. It also has a hole - two `!`
+ * utilities on the same property tie again, so it moves the coin flip up a
+ * level rather than removing it.
+ *
+ * WHY OURS CAN BE SMALLER THAN `tailwind-merge`. That library infers at runtime
+ * and cannot see your theme, so it carries a table of every Tailwind class group
+ * and still guesses at custom names. We generate the resolver next to the
+ * system, so it is not guessing: `text-foreground` is a colour because
+ * `foreground` is in this system's colour namespace, and `text-lg` is a size
+ * because `lg` is in its type scale. Those two families are the only genuinely
+ * ambiguous ones; everything else is decided by the prefix.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO. It resolves collisions on the SAME property
+ * key - `bg-a` against `bg-b`, `p-md` against `p-lg`. It does not model the
+ * hierarchy between `p` and `px` and `pt`, because Tailwind's own emission order
+ * already resolves those correctly, and pretending to solve more would be a
+ * second thing to be wrong about.
+ */
+/**
+ * Reads the `@theme` namespaces out of a compiled theme.css.
+ *
+ * `--color-foreground: …` means the project has a `text-foreground`,
+ * `bg-foreground` and `border-foreground`. Suffixes like
+ * `--text-lg--line-height` are declarations ABOUT a name, not names, so the
+ * double dash is what excludes them.
+ */
+export function readVocabulary(themeCss) {
+    const namesIn = (ns) => {
+        const out = new Set();
+        const re = new RegExp(`^\\s*--${ns}-([a-z0-9-]+)\\s*:`, "gm");
+        for (const m of themeCss.matchAll(re)) {
+            if (!m[1].includes("--"))
+                out.add(m[1]);
+        }
+        return [...out].sort();
+    };
+    const font = namesIn("font");
+    const weights = namesIn("font-weight");
+    return {
+        colors: namesIn("color"),
+        textSizes: namesIn("text"),
+        // `--font-weight-medium` also matches the `font` namespace as
+        // `weight-medium`; the real families are what is left after removing them.
+        fontFamilies: font.filter((f) => !f.startsWith("weight-")),
+        fontWeights: weights,
+    };
+}
+const set = (names) => `new Set([${names.map((n) => JSON.stringify(n)).join(", ")}])`;
+/** The `cn.ts` a project gets, written against ITS system's vocabulary. */
+export function emitCn(slug, vocab) {
+    return `/**
+ * Class resolver for the "${slug}" design system. Generated by SynthesisUI.
+ *
+ * Two plain Tailwind utilities setting the same property have the same
+ * specificity, so the winner is decided by the order Tailwind writes the
+ * stylesheet - not by the order in your className, which is what the code looks
+ * like it controls. A component whose base sets \`text-foreground\` would ignore
+ * \`className="text-info"\` without any error.
+ *
+ * This drops the earlier class when a later one sets the same property, so the
+ * last one wins, which is what the call site reads like. Pass the base first and
+ * the caller's className last.
+ *
+ * It resolves collisions on the same property key (\`bg-a\` vs \`bg-b\`, \`p-md\` vs
+ * \`p-lg\`). It does not model \`p\` against \`px\` against \`pt\`: Tailwind's own
+ * emission order already gets those right.
+ *
+ * Regenerated by \`synthesisui component\`. Safe to edit, but a new component
+ * will overwrite it.
+ */
+
+/** This system's own namespaces, so \`text-*\` and \`font-*\` are never a guess. */
+const COLORS = ${set(vocab.colors)};
+const TEXT_SIZES = ${set(vocab.textSizes)};
+const FONT_FAMILIES = ${set(vocab.fontFamilies)};
+const FONT_WEIGHTS = ${set(vocab.fontWeights)};
+
+/** Prefixes where the prefix alone decides the property. Longest first, so
+ *  \`border-t\` is read before \`border\`. */
+const PREFIXES = [
+  "bg",
+  "shadow",
+  "opacity",
+  "rounded-tl", "rounded-tr", "rounded-br", "rounded-bl",
+  "rounded-t", "rounded-r", "rounded-b", "rounded-l",
+  "rounded",
+  "border-t", "border-r", "border-b", "border-l", "border-x", "border-y",
+  "border",
+  "px", "py", "pt", "pr", "pb", "pl", "ps", "pe", "p",
+  "mx", "my", "mt", "mr", "mb", "ml", "ms", "me", "m",
+  "gap-x", "gap-y", "gap",
+  "w", "h", "min-w", "min-h", "max-w", "max-h",
+  "leading", "tracking",
+  "flex", "grid", "justify", "items", "self", "order", "z",
+];
+
+/**
+ * The property this class sets, or the class itself when we cannot tell.
+ *
+ * Returning the class itself is the safe answer: an unknown class then collides
+ * only with an identical one, so nothing is ever dropped by mistake.
+ */
+function groupOf(cls: string): string {
+  // A variant is part of the identity: \`hover:bg-x\` must not replace \`bg-y\`.
+  const cut = cls.lastIndexOf(":");
+  const variants = cut === -1 ? "" : cls.slice(0, cut + 1);
+  let base = cut === -1 ? cls : cls.slice(cut + 1);
+
+  // \`!\` marks importance, \`/40\` sets opacity. Neither changes the property.
+  base = base.replace(/^!|!$/g, "").replace(/\\/[^/]+$/, "");
+  const negative = base.startsWith("-");
+  if (negative) base = base.slice(1);
+
+  const dash = base.indexOf("-");
+  const head = dash === -1 ? base : base.slice(0, dash);
+  const rest = dash === -1 ? "" : base.slice(dash + 1);
+
+  // The two families a prefix cannot settle, answered by this system's names.
+  if (head === "text") {
+    if (TEXT_SIZES.has(rest)) return \`\${variants}font-size\`;
+    if (COLORS.has(rest) || rest.startsWith("[")) return \`\${variants}text-color\`;
+    return \`\${variants}\${cls}\`;
+  }
+  if (head === "font") {
+    if (FONT_WEIGHTS.has(rest)) return \`\${variants}font-weight\`;
+    if (FONT_FAMILIES.has(rest)) return \`\${variants}font-family\`;
+    return \`\${variants}\${cls}\`;
+  }
+
+  for (const p of PREFIXES) {
+    if (base === p || base.startsWith(\`\${p}-\`)) return \`\${variants}\${p}\`;
+  }
+  return \`\${variants}\${cls}\`;
+}
+
+export type ClassValue = string | false | null | undefined;
+
+export function cn(...parts: ClassValue[]): string {
+  const won = new Map<string, string>();
+  for (const part of parts) {
+    if (!part) continue;
+    for (const cls of part.split(/\\s+/)) {
+      if (!cls) continue;
+      const key = groupOf(cls);
+      // Delete before set so the winner also takes the later POSITION. The
+      // string order does not decide the cascade, but it is what a person reads
+      // in the DOM, and a stale leading class there is a lie.
+      won.delete(key);
+      won.set(key, cls);
+    }
+  }
+  return [...won.values()].join(" ");
+}
+`;
+}

package/dist/commands/component.js

@@ -1,10 +1,32 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
+import { emitCn, readVocabulary } from "../cn-codegen.js";
 import { generateComponentFiles } from "../component-codegen.js";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { hasInteractiveTemplate, interactiveTemplate, } from "../interactive-templates.js";
 import { body, section, snippet } from "../output.js";
 import { fetchComponent, RegistryError } from "../registry.js";
+/**
+ * Writes the shared `cn.ts` next to the components, built from THIS project's
+ * installed theme.
+ *
+ * Only the tailwind flavour needs it: in css mode the recipe lives in
+ * `@layer components` and every utility already outranks it. Generated from the
+ * theme on disk rather than from a table of Tailwind's own names, which is why
+ * it can tell `text-foreground` (a colour here) from `text-lg` (a size here)
+ * without guessing.
+ */
+async function writeCn(root, compDir, slug) {
+    const theme = await readFile(join(root, "_synthesisui", "ds", slug, "theme.css"), "utf8").catch(() => "");
+    // The root file is a pointer at the pinned version; follow it.
+    const inner = /@import\s+["']\.\/([^"']+)["']/.exec(theme)?.[1];
+    const real = inner
+        ? await readFile(join(root, "_synthesisui", "ds", slug, inner), "utf8").catch(() => theme)
+        : theme;
+    if (!real)
+        return;
+    await writeFile(join(compDir, "..", "cn.ts"), emitCn(slug, readVocabulary(real)), "utf8");
+}
 /**
  * The consumer's React major, or null when we cannot tell.
  *
@@ -85,6 +107,8 @@ export async function component(slug, name, opts) {
             for (const file of files) {
                 await writeFile(join(compDir, file.filename), file.code, "utf8");
             }
+            if (config.styles === "tailwind")
+                await writeCn(root, compDir, slug);
             filenames = files.map((f) => f.filename);
         }
         const flavor = wantInteractive ? "interactive" : `styles: ${config.styles}`;

package/dist/commands/doctor.js

@@ -1,5 +1,6 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
+import { findDivergences } from "../doctor/coherence.js";
 import { findFrozenBindings } from "../doctor/frozen.js";
 import { bindingsFromDocument, countComponents, findOverrides, } from "../doctor/overrides.js";
 import { diagnose, scanSource, siblingTokens, } from "../doctor/scan.js";
@@ -633,6 +634,32 @@ export async function doctor(opts) {
         say(body("Whoever wrote the law and whoever wrote the recipe disagree."));
         say(body("Until they do not, no code here can be correct."));
     }
+    /**
+     * THE FAILURE THAT SURVIVES A PERFECT SCORE.
+     *
+     * Coverage asks whether the vocabulary was used. It cannot ask whether the
+     * system says ONE thing, because every component here can reference the right
+     * token and still answer the same question differently. Measured on 28/07 in
+     * a system this tool had just graded 100%: the input shows focus by moving its
+     * border, the button by drawing an outline.
+     *
+     * Reported quietly and only against a clear house style. Hover is legitimately
+     * different per component, and a checker that flagged variety would be
+     * uninstalled the same day it shipped.
+     */
+    const divergences = findDivergences(documents);
+    if (divergences.length > 0) {
+        say(section("The system answers the same question two ways"));
+        for (const d of divergences) {
+            say(body(`${d.concern}: ${d.houseCount} components use ${d.house.join(" + ")}.`));
+            for (const o of d.outliers) {
+                say(`      ${o.component} uses ${o.props.join(" + ")} instead`);
+            }
+            say("");
+        }
+        say(body("Every one of these uses your tokens, so coverage says nothing"));
+        say(body("about them. A person meets the difference on screen."));
+    }
     // The other way a system fails itself: a recipe that names a SHELF where the
     // system has a ROLE. The value is legitimate, the reference resolves, the CSS
     // compiles - and the binding sits still while everything around it flips.

package/dist/component-codegen.js

@@ -417,12 +417,33 @@ function header(slug, name, version, mode) {
  * which this generator has. Until it is built, the failure at least stops
  * being silent, which is the part that actually costs people time.
  */
+/**
+ * This used to tell people to write `text-info!`, which worked and cost 61
+ * exclamation marks in 1,885 generated lines when it was measured (28/07). It
+ * also had a hole: two `!` utilities on the same property tie again.
+ *
+ * `cn()` removes the tie instead of moving it, so the instruction becomes a lie
+ * the moment it ships - and an instruction that asks for work the mechanism
+ * already did is the drift this product exists to catch.
+ */
 const OVERRIDE_WARNING = `//
-// Overriding a style this component already sets? Add \`!\`:
-//   <Thing className="text-info!" />   not   className="text-info"
-// Both are plain utilities at the same specificity, so which one wins is
-// decided by the stylesheet's order, not by this string's.`;
+// Overriding a style this component already sets just works: \`className\` is
+// resolved against the base by \`cn()\`, so the last one written wins.
+//   <Thing className="text-info" />   no \`!\` needed
+// If an override is ignored, this file predates that resolver - regenerate it
+// with \`npx synthesisui component <slug> <name>\`.`;
 const joinCls = (parts) => `[${parts.join(", ")}].filter(Boolean).join(" ")`;
+/**
+ * TAILWIND FLAVOUR ONLY, and the asymmetry is the point.
+ *
+ * In css mode the recipe compiles into `@layer components`, which every utility
+ * already outranks - so a caller's `className` wins by the cascade and a
+ * resolver would be dead weight. In tailwind mode the base IS utilities, tied
+ * with the caller's at the same specificity, and the winner is decided by
+ * stylesheet order. `cn()` drops the loser so the last one written actually
+ * applies, which is what the call site reads like.
+ */
+const resolveCls = (parts) => `cn(${parts.join(", ")})`;
 /** JSDoc showing how to compose the component with its parts + content, so the
  *  materialized code doesn't read as "a bare shell renders nothing" (dogfood
  *  #5). Built from the recipe's parts. */
@@ -528,6 +549,7 @@ function emitTailwindMode(slug, name, recipe, version, props) {
     return `${header(slug, name, version, "tailwind")}
 
 import type { ${props} } from "react";
+import { cn } from "../cn";
 
 const BASE = ${JSON.stringify(tailwindClassList(recipe, excluded))};
 ${[...variantConsts, ...booleanConsts].join("\n")}
@@ -538,7 +560,7 @@ ${compositionHint(comp, name, recipe, voidEl)}
 export function ${comp}({ ${destructure} }: ${comp}Props) {
   return (
     <${tag}${attrs}
-      className={${joinCls(clsParts)}}
+      className={${resolveCls(clsParts)}}
       {...props}
     />
   );
@@ -553,7 +575,7 @@ ${Object.entries(recipe.parts ?? {})
 /** Part "${partName}" of ${comp} - compose it inside <${comp}>. */
 export function ${partComp}({ className, ...props }: ${props}<"${partTag}">) {
   return (
-    <${partTag}${partAttrs} className={${joinCls([JSON.stringify(tailwindClassList(part)), "className"])}} {...props} />
+    <${partTag}${partAttrs} className={${resolveCls([JSON.stringify(tailwindClassList(part)), "className"])}} {...props} />
   );
 }`;
     })

package/dist/doctor/coherence.js

@@ -0,0 +1,117 @@
+/**
+ * DOES THE SYSTEM AGREE WITH ITSELF?
+ *
+ * Token coverage answers a different question than everybody assumes. It asks
+ * whether the vocabulary was used. It cannot ask whether the system says one
+ * thing, because every component can reference the correct token and still
+ * express the same idea in a different way.
+ *
+ * Measured on 28/07, in a system this tool had just graded at 100%: the input
+ * shows focus by moving its border, the button by drawing an outline. Same
+ * token, same toolbar, two answers to one question. Every deterministic
+ * assertion we had passed, and a person looking at the screen sees a system
+ * that has not decided what focus looks like.
+ *
+ * WHY IT LIVES IN CODE AND NOT IN THE DESIGN TOOL. A designer in the Design
+ * Systems Slack built a lint plugin that does this inside Figma. Asked whether
+ * it can compare across components rather than one at a time: "it can check one
+ * at a time or all, but this crashes figma most of the time". A plugin walks a
+ * document graph inside a sandbox; this reads recipes off disk, and the whole
+ * catalogue costs a few milliseconds. The check is feasible on this side and not
+ * on that one.
+ *
+ * WHAT MAKES IT HONEST RATHER THAN NOISY. Variety is not drift. Hover is
+ * legitimately different per component - a row tints, a link recolours, a chip
+ * moves its border - and a checker that flagged all of it would be uninstalled
+ * the same day. So it reports a MINORITY against a DOMINANT majority and says
+ * nothing at all when the catalogue has no majority to disagree with.
+ *
+ * Measured against the shipped catalogue, that rule reports the two real ones
+ * and neither of the false ones:
+ *
+ *   focus       9 use outline, 3 use border-color   → reported (75% dominant)
+ *   disabled   12 dim and change the cursor, 1 only dims → reported (92%)
+ *   hover       5 shapes across 11, none dominant  → silent
+ *   active      1 and 1                            → silent
+ */
+/**
+ * State names that answer the SAME question, folded together.
+ *
+ * Without this the check finds nothing here, because each name is unanimous on
+ * its own: `focusVisible` is nine-for-nine outline, `focus` is three-for-three
+ * border. The disagreement only exists once you know they are the same concern,
+ * which is exactly why it survived every per-name check anyone could write.
+ */
+const CONCERNS = {
+    focus: "focus",
+    focusvisible: "focus",
+    focuswithin: "focus",
+    active: "pressed",
+    pressed: "pressed",
+    checked: "selected",
+    selected: "selected",
+    disabled: "disabled",
+    hover: "hover",
+};
+/** Below this share, the catalogue has no house style to disagree with, and
+ *  every "outlier" is just the variety the concern is supposed to have. */
+const DOMINANT = 0.7;
+function collect(documents) {
+    const byConcern = new Map();
+    const visit = (label, node) => {
+        for (const [state, block] of Object.entries(node.states ?? {})) {
+            const concern = CONCERNS[state.toLowerCase()];
+            // An unrecognised state is not folded into anything. Guessing that two
+            // names mean the same thing is how a checker starts inventing findings.
+            if (!concern)
+                continue;
+            const props = Object.keys(block ?? {}).sort();
+            if (props.length === 0)
+                continue;
+            const list = byConcern.get(concern) ?? [];
+            list.push({ component: label, props });
+            byConcern.set(concern, list);
+        }
+    };
+    for (const raw of documents) {
+        const doc = raw;
+        for (const [name, recipe] of Object.entries(doc.components ?? {})) {
+            visit(name, recipe);
+            for (const [part, block] of Object.entries(recipe.parts ?? {})) {
+                visit(`${name}.${part}`, block);
+            }
+        }
+    }
+    return byConcern;
+}
+/** Every concern the system answers more than one way, with a clear majority. */
+export function findDivergences(documents) {
+    const out = [];
+    for (const [concern, entries] of collect(documents)) {
+        // One component cannot disagree with itself, and two cannot form a house
+        // style - the smallest catalogue this can speak about is three.
+        if (entries.length < 3)
+            continue;
+        const shapes = new Map();
+        for (const e of entries) {
+            const key = e.props.join("+");
+            shapes.set(key, [...(shapes.get(key) ?? []), e]);
+        }
+        if (shapes.size < 2)
+            continue;
+        const ranked = [...shapes.entries()].sort((a, b) => b[1].length - a[1].length);
+        const [houseKey, houseList] = ranked[0];
+        if (houseList.length / entries.length < DOMINANT)
+            continue;
+        out.push({
+            concern,
+            house: houseKey.split("+"),
+            houseCount: houseList.length,
+            outliers: ranked
+                .slice(1)
+                .flatMap(([, list]) => list)
+                .sort((a, b) => a.component.localeCompare(b.component)),
+        });
+    }
+    return out.sort((a, b) => b.outliers.length - a.outliers.length);
+}

package/package.json

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