synthesisui 0.16.17 → 0.16.18

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/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/package.json

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