synthesisui 0.16.16 → 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,54 @@
-import { mkdir, writeFile } from "node:fs/promises";
+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.
+ *
+ * It decides whether the generated components can take a `ref`: from 19 that is
+ * an ordinary prop, before it a function component needs `forwardRef`. Guessing
+ * high on an older project would emit a type that accepts a ref React then
+ * silently drops, so anything unreadable falls back to the ref-less type.
+ */
+async function reactMajorOf(root) {
+    const raw = await readFile(join(root, "package.json"), "utf8").catch(() => "");
+    if (!raw)
+        return null;
+    try {
+        const pkg = JSON.parse(raw);
+        const spec = pkg.dependencies?.react ?? pkg.devDependencies?.react;
+        const major = /(\d+)/.exec(spec ?? "")?.[1];
+        return major ? Number(major) : null;
+    }
+    catch {
+        return null;
+    }
+}
 /** Slugs/names are kebab-case by contract; reject anything else before it ever
  *  reaches a filesystem path (defense-in-depth against `../` traversal). */
 const SAFE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -59,10 +103,12 @@ export async function component(slug, name, opts) {
             filenames = [`${res.name}.tsx`, `${res.name}.css`, "index.ts"];
         }
         else {
-            const files = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, config.styles);
+            const files = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, config.styles, await reactMajorOf(root));
             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

@@ -8,6 +8,28 @@ const camel = (name) => {
     const p = pascal(name);
     return p[0].toLowerCase() + p.slice(1);
 };
+/**
+ * A PART THAT STYLES FOCUS IS A CONTROL, AND EVERY ONE OF THEM SHIPPED AS A DIV.
+ *
+ * Found by an agent building a carousel (27/07). `PaginationItem` came out as a
+ * `<div>` carrying `cursor-pointer`, `hover:text-foreground`,
+ * `focus-visible:[outline:2px]` and `disabled:[opacity:0.4]` - every affordance
+ * of a button on an element that is not focusable, is not announced as a
+ * control, and where `disabled:` can never match. It worked around us by
+ * putting the class on a real `<button>` instead of using the component.
+ *
+ * The recipe already knew. Nobody writes a focus ring on a div by accident, so
+ * `focus`/`focusVisible`/`disabled` in a part's states IS the declaration that
+ * it is operable. `hover` deliberately does not count: a card that lifts under
+ * the cursor is still a card.
+ *
+ * Conservative by construction. Across the shipped catalogue this promotes
+ * three parts of fifty - stepper.button, tabs.trigger, pagination.item - and
+ * all three are buttons that were wearing the wrong tag.
+ */
+export function partIsInteractive(part) {
+    return Object.keys(part.states ?? {}).some((s) => /^(focus|focusVisible|focus-visible|disabled)$/i.test(s));
+}
 /** Intrinsic element + extra attrs per component, chosen like the platform
  *  renderer does (name first, then preview.kind). Fallback: div + children. */
 function elementFor(name, recipe) {
@@ -82,13 +104,36 @@ function axesOf(variants) {
     }
     return axes;
 }
-function propsType(axes, tag) {
+/**
+ * THE COMPONENTS COULD NOT TAKE A REF, AND SOME UI CANNOT BE BUILT WITHOUT ONE.
+ *
+ * `ComponentPropsWithoutRef` is the correct type under React 18, where a
+ * function component needs `forwardRef` to receive one. Under React 19 `ref` is
+ * an ordinary prop, so the same code works and the type is simply lying about
+ * what the component accepts.
+ *
+ * It costs real things. An agent building a dense screen (28/07) had to address
+ * rows by DOM id and reach for `document.getElementById`, because roving focus
+ * needs a ref. And `indeterminate` on a checkbox is a DOM property with no HTML
+ * attribute: a partial select-all is impossible without one.
+ *
+ * Read from the consumer's own package.json, never assumed. Unknown or older
+ * keeps today's behaviour, because emitting a ref-taking type onto React 18
+ * trades a missing feature for a silent one - the ref is quietly undefined and
+ * only a dev-mode warning says so.
+ */
+export function propsTypeName(reactMajor) {
+    return reactMajor !== null && reactMajor >= 19
+        ? "ComponentProps"
+        : "ComponentPropsWithoutRef";
+}
+function propsType(axes, tag, base) {
     const extras = axes.map((a) => a.boolean
         ? `  ${a.prop}?: boolean;`
         : `  ${a.prop}?: ${a.options.map((o) => `"${o}"`).join(" | ")};`);
     if (extras.length === 0)
-        return `ComponentPropsWithoutRef<"${tag}">`;
-    return `ComponentPropsWithoutRef<"${tag}"> & {\n${extras.join("\n")}\n}`;
+        return `${base}<"${tag}">`;
+    return `${base}<"${tag}"> & {\n${extras.join("\n")}\n}`;
 }
 function dataAttrLines(axes) {
     return axes
@@ -372,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. */
@@ -403,7 +469,7 @@ ${inner}
  *   </${comp}>
  */`;
 }
-function emitCssMode(slug, name, recipe, version) {
+function emitCssMode(slug, name, recipe, version, props) {
     const { tag, attrs, voidEl } = elementFor(name, recipe);
     const axes = axesOf(recipe.variants);
     const comp = pascal(name);
@@ -418,11 +484,14 @@ function emitCssMode(slug, name, recipe, version) {
             "className",
             "...props",
         ].join(", ");
+        const control = partIsInteractive(part);
+        const partTag = control ? "button" : "div";
+        const partAttrs = control ? '\n      type="button"' : "";
         return `
 /** Part "${partName}" of ${comp} - compose it inside <${comp}>. */
-export function ${partComp}({ ${partDestructure} }: ${propsType(partAxes, "div")}) {
+export function ${partComp}({ ${partDestructure} }: ${propsType(partAxes, partTag, props)}) {
   return (
-    <div
+    <${partTag}${partAttrs}
       className={${joinCls([`"ds-${name}-${kebab(partName)}"`, "className"])}}
 ${dataAttrLines(partAxes)}${partAxes.length ? "\n" : ""}      {...props}
     />
@@ -432,9 +501,9 @@ ${dataAttrLines(partAxes)}${partAxes.length ? "\n" : ""}      {...props}
     return `${header(slug, name, version, "css")}
 import "./${name}.css";
 
-import type { ComponentPropsWithoutRef } from "react";
+import type { ${props} } from "react";
 
-type ${comp}Props = ${propsType(axes, tag)};
+type ${comp}Props = ${propsType(axes, tag, props)};
 
 ${compositionHint(comp, name, recipe, voidEl)}
 export function ${comp}({ ${destructure} }: ${comp}Props) {
@@ -444,7 +513,7 @@ ${rootJsx}
 }
 ${parts.join("\n")}`;
 }
-function emitTailwindMode(slug, name, recipe, version) {
+function emitTailwindMode(slug, name, recipe, version, props) {
     const { tag, attrs, voidEl } = elementFor(name, recipe);
     const axes = axesOf(recipe.variants);
     const comp = pascal(name);
@@ -479,18 +548,19 @@ function emitTailwindMode(slug, name, recipe, version) {
     ].join(", ");
     return `${header(slug, name, version, "tailwind")}
 
-import type { ComponentPropsWithoutRef } from "react";
+import type { ${props} } from "react";
+import { cn } from "../cn";
 
 const BASE = ${JSON.stringify(tailwindClassList(recipe, excluded))};
 ${[...variantConsts, ...booleanConsts].join("\n")}
 
-type ${comp}Props = ${propsType(axes, tag)};
+type ${comp}Props = ${propsType(axes, tag, props)};
 
 ${compositionHint(comp, name, recipe, voidEl)}
 export function ${comp}({ ${destructure} }: ${comp}Props) {
   return (
     <${tag}${attrs}
-      className={${joinCls(clsParts)}}
+      className={${resolveCls(clsParts)}}
       {...props}
     />
   );
@@ -498,31 +568,38 @@ export function ${comp}({ ${destructure} }: ${comp}Props) {
 ${Object.entries(recipe.parts ?? {})
         .map(([partName, part]) => {
         const partComp = `${comp}${pascal(partName)}`;
+        const control = partIsInteractive(part);
+        const partTag = control ? "button" : "div";
+        const partAttrs = control ? ' type="button"' : "";
         return `
 /** Part "${partName}" of ${comp} - compose it inside <${comp}>. */
-export function ${partComp}({ className, ...props }: ComponentPropsWithoutRef<"div">) {
+export function ${partComp}({ className, ...props }: ${props}<"${partTag}">) {
   return (
-    <div className={${joinCls([JSON.stringify(tailwindClassList(part)), "className"])}} {...props} />
+    <${partTag}${partAttrs} className={${resolveCls([JSON.stringify(tailwindClassList(part)), "className"])}} {...props} />
   );
 }`;
     })
         .join("\n")}`;
 }
 /** All files for one component, under `<componentsDir>/<name>/`. */
-export function generateComponentFiles(slug, name, recipe, css, version, styles) {
+export function generateComponentFiles(slug, name, recipe, css, version, styles, 
+/** Consumer's React major, read from its package.json. Null = unknown, which
+ *  keeps the ref-less type rather than guessing in the unsafe direction. */
+reactMajor = null) {
     const comp = pascal(name);
     const files = [];
+    const props = propsTypeName(reactMajor);
     if (styles === "css") {
         files.push({
             filename: `${name}.tsx`,
-            code: `${emitCssMode(slug, name, recipe, version)}\n`,
+            code: `${emitCssMode(slug, name, recipe, version, props)}\n`,
         });
         files.push({ filename: `${name}.css`, code: `${css}\n` });
     }
     else {
         files.push({
             filename: `${name}.tsx`,
-            code: `${emitTailwindMode(slug, name, recipe, version)}\n`,
+            code: `${emitTailwindMode(slug, name, recipe, version, props)}\n`,
         });
     }
     files.push({

package/dist/doctor/scan.js

@@ -31,11 +31,32 @@ const IGNORE_LINE = /^\s*(import|@import|\/\/|\*|\/\*)/;
  * 3/6/8 digit run terminated by a non-hex character.
  */
 const COLOR = /#[0-9a-fA-F]{8}\b|#[0-9a-fA-F]{6}\b|#[0-9a-fA-F]{3}\b|rgba?\([^)]*\)|hsla?\([^)]*\)/g;
-/** `rounded-[14px]`, `border-radius: 14px`. Zero and full pills are idiom,
- *  not drift - nobody tokenizes `0` or `9999px`. */
-const RADIUS = /(?:border-radius\s*:\s*|rounded(?:-[a-z]+)?-\[)(-?\d*\.?\d+)(px|rem|em)/g;
-/** Arbitrary spacing: `p-[18px]`, `gap-[7px]`, `margin: 18px`. */
-const SPACING = /(?:\b[pmg](?:[trblxy])?-\[|gap-\[|(?:padding|margin|gap)\s*:\s*)(-?\d*\.?\d+)(px|rem)/g;
+/**
+ * THE QUOTE THAT MADE HALF THE DRIFT INVISIBLE.
+ *
+ * Both patterns below used to require `property:` followed directly by a digit.
+ * CSS writes `padding: 2rem` and matches. JSX writes `padding: "2rem"`, and the
+ * quote ends the match before it starts - so a component built with an inline
+ * style object was scanned for colour and nothing else.
+ *
+ * Colour escaped it by luck: that pattern hunts `#hex` anywhere and never
+ * needed a property in front. Which is exactly why nobody noticed, because
+ * every test file had a colour in it and the colour always came back.
+ *
+ * Found 28/07 writing a file with `gap: "1.25rem"` and `padding: "2rem"` on
+ * purpose - both exact tokens of the system - and being told six colours, zero
+ * spacings.
+ *
+ * JSX also camelCases, so `borderRadius` has to be as welcome as
+ * `border-radius`.
+ */
+const OPEN = `["']?`;
+/** `rounded-[14px]`, `border-radius: 14px`, `borderRadius: "14px"`. Zero and
+ *  full pills are idiom, not drift - nobody tokenizes `0` or `9999px`. */
+const RADIUS = new RegExp(`(?:border-?[Rr]adius\\s*:\\s*${OPEN}|rounded(?:-[a-z]+)?-\\[)(-?\\d*\\.?\\d+)(px|rem|em)`, "g");
+/** Arbitrary spacing: `p-[18px]`, `gap-[7px]`, `margin: 18px`, `gap: "18px"`.
+ *  The JSX side also writes `paddingLeft`, `marginTop` and friends. */
+const SPACING = new RegExp(`(?:\\b[pmg](?:[trblxy])?-\\[|gap-\\[|(?:padding|margin|gap)(?:[A-Z][a-z]+)?\\s*:\\s*${OPEN})(-?\\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;
 /**
@@ -252,7 +273,9 @@ export function scanSource(file, source, table) {
                 kind,
                 line: at,
                 literal,
-                token: tokenFor(table, literal),
+                // The kind is already known here, and without passing it the lookup
+                // answers a `gap` with a radius token.
+                token: tokenFor(table, literal, kind),
                 excerpt: clip(line),
             });
         };

package/dist/doctor/tokens.js

@@ -416,11 +416,35 @@ export function nearestToken(table, literal) {
     const limit = unit === "rem" ? Math.max(n * 0.25, 0.5) : Math.max(n * 0.25, 8);
     return best.delta <= limit ? best : null;
 }
-export function tokenFor(table, literal) {
+/**
+ * The family a token belongs to, from the drift it was found in.
+ *
+ * Without this the lookup is by VALUE alone, and a value belongs to more than
+ * one family: `1.25rem` is both `--ds-spacing-sm` and `--ds-radius-lg` in the
+ * same system. Measured 28/07 on `gap-[1.25rem]`, which was correctly counted as
+ * spacing and then told to use a radius token.
+ *
+ * That is worse than saying nothing. A tool that answers a gap with a corner
+ * radius is one a person stops reading, and this one has exactly one job that
+ * nobody else does: naming the right token.
+ */
+const FAMILY = {
+    color: "--ds-color-",
+    radius: "--ds-radius-",
+    spacing: "--ds-spacing-",
+    font: "--ds-typography-",
+};
+export function tokenFor(table, literal, kind) {
     const hit = table.byValue.get(normalizeValue(literal));
     if (!hit || hit.length === 0)
         return null;
+    // Narrow to the family first, and only fall back to the whole set when the
+    // system has no token of that kind holding this value - a fallback is still
+    // better than silence, it just stops being a recommendation.
+    const prefix = kind ? FAMILY[kind] : undefined;
+    const family = prefix ? hit.filter((n) => n.startsWith(prefix)) : [];
+    const pool = family.length > 0 ? family : hit;
     // Semantic roles name intent; primitives name a shelf. Prefer intent.
-    const semantic = hit.find((n) => n.includes("-semantic-"));
-    return semantic ?? hit[0];
+    const semantic = pool.find((n) => n.includes("-semantic-"));
+    return semantic ?? pool[0];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.16",
+  "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": {