roast-my-design-system 9.1.2 → 9.2.1

package/README.md

@@ -17,7 +17,7 @@ npx roast-my-design-system@latest
 Run it at the root of a UI repo. One second later, a report opens.
 No account. No network. No telemetry. Nothing in your repo changes.
 
-**Current release: 9.1.** Version history in [CHANGELOG.md](CHANGELOG.md).
+**Current release: 9.2.** Version history in [CHANGELOG.md](CHANGELOG.md).
 
 ## The idea
 
@@ -245,7 +245,7 @@ Four calls, under 800 tokens, and the new component reads the theme instead of a
 
 Charts get their own rule, because a chart needs several colours that differ from each other and most design systems never name them. Where a repo keeps a chart palette, a colour written by hand in a chart file is a finding that names the palette. Where a repo has charts but no palette, a new chart that paints by hand gets one warning that names the existing chart doing the same and asks for the palette once. That warning is the gap report, live.
 
-The server reads the repo the way the report does. On a product built on MUI, Mantine, Chakra UI or Ant Design, the context names the theme file and the kit's own way of reading it, `roast_find_token` answers in spacing steps, and the checks flag a colour or a pixel size written onto a kit component where the theme has a value. On a Tailwind theme or a shadcn repo they flag a palette class such as `text-gray-500` where the theme names a colour of that kind.
+The server reads the repo the way the report does. On a product built on MUI, Mantine, Chakra UI or Ant Design, the context names the theme file and the kit's own way of reading it, `roast_find_token` answers in spacing steps, and the checks flag a colour or a pixel size written onto a kit component where the theme has a value. On a Tailwind theme or a shadcn repo they flag a palette class such as `text-gray-500` where the theme names a colour of that kind. A token's raw value pasted into a component is flagged with the token's name, and a button built from scratch where the repo already has a well-used Button gets a warning that names the import line to use.
 
 The `roast-fix` prompt serves the top Where-to-start move from a fresh scan, byte-identical to the report's copy buttons. In Claude Code type `/mcp__roast__roast-fix`, add a number to jump the queue. Fix it, ask again, and the next move has risen to the top: the scan is the progress bar.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "9.1.2",
+  "version": "9.2.1",
   "mcpName": "io.github.gregkozakiewicz/roast-my-design-system",
   "description": "Your AI can write the UI. This makes sure it writes your UI. A deterministic scanner scores your design system 0-100 against 112 public repos, reads React and web components (Stencil, Lit), hands you a copy-paste fix prompt for each top finding, writes rules for Claude, Cursor, Copilot and Windsurf with --apply, and runs as a local MCP server with --mcp.",
   "keywords": [

package/skills/roast-my-design-system/scripts/harvest/components.mjs

@@ -6,6 +6,37 @@
  */
 import { join, basename, posix } from 'node:path';
 import { readSource } from './walk.mjs';
+import { resolveWorkspaces } from '../lib/workspaces.mjs';
+
+/**
+ * Import aliases a tsconfig declares: "@sentry/scraps/*": ["./static/app/
+ * components/core/*"] means a file importing @sentry/scraps/button means the
+ * copy under static/app/components/core. Read tolerantly (tsconfig is JSON
+ * with comments and trailing commas); a bare "*" catch-all is not an alias.
+ * @returns [{ prefix, dir }] longest prefix first
+ */
+export function tsconfigAliases(root) {
+  let text;
+  try { text = readSource(join(root, 'tsconfig.json')); } catch { return []; }
+  if (!text) return [];
+  let cfg;
+  try {
+    cfg = JSON.parse(text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '').replace(/,(\s*[}\]])/g, '$1'));
+  } catch { return []; }
+  const paths = cfg?.compilerOptions?.paths;
+  if (!paths || typeof paths !== 'object') return [];
+  const base = (cfg.compilerOptions.baseUrl ?? '.').replace(/^\.\/?/, '').replace(/\/$/, '');
+  const out = [];
+  for (const [key, targets] of Object.entries(paths)) {
+    if (key === '*' || !Array.isArray(targets) || typeof targets[0] !== 'string') continue;
+    const prefix = key.replace(/\/?\*$/, '');
+    if (!prefix) continue;
+    const target = targets[0].replace(/^\.\/?/, '').replace(/\/?\*$/, '').replace(/\/$/, '');
+    const dir = posix.normalize(base ? `${base}/${target}` : target).replace(/^\.\/?/, '');
+    if (dir && dir !== '.') out.push({ prefix, dir });
+  }
+  return out.sort((a, b) => b.prefix.length - a.prefix.length);
+}
 
 const QUOTES = new Set(['"', "'", '`']);
 
@@ -127,7 +158,10 @@ export function definedComponents(src) {
   return [...names];
 }
 
-const looksLikeJSXFile = (src) => /<[A-Za-z][\w.]*[\s/>]/.test(src);
+// A file with no markup defines no component the report can count: a stub
+// returning null, a wrapper built with a factory call. Asked by the harvest
+// and by the live checks, so both read the same files as component files.
+export const looksLikeJSXFile = (src) => /<[A-Za-z][\w.]*[\s/>]/.test(src);
 
 // ---------- web components: the tag-registered world ----------
 // Stencil, Lit and raw customElements.define register components by TAG, and
@@ -169,7 +203,7 @@ const stripExt = (f) => f.replace(/\.[cm]?[jt]sx?$/, '');
  * (`../ui` → ui/index.ts) resolves to the copy inside that folder. A file that
  * defines the name itself means its own. Returns [def] or null when unsure.
  */
-function importedDef(src, file, name, defs) {
+function importedDef(src, file, name, defs, workspaces = [], aliases = []) {
   const own = defs.find((d) => d.file === file);
   if (own) return [own];
   for (const m of src.matchAll(/import\s+(?:type\s+)?([^'";]*?)\s+from\s*['"]([^'"]+)['"]/g)) {
@@ -181,7 +215,25 @@ function importedDef(src, file, name, defs) {
     const spec = m[2];
     let target = null, suffix = null;
     if (spec.startsWith('.')) target = posix.normalize(posix.join(posix.dirname(file), spec));
-    else { const a = /^(?:@|~|#)\/(.+)$/.exec(spec); if (a) suffix = a[1]; else return null; }
+    else {
+      const a = /^(?:@|~|#)\/(.+)$/.exec(spec);
+      // a tsconfig alias first: it is the repo's own statement of where the
+      // specifier points, and it can name a folder no workspace declares
+      const al = aliases.find((x) => spec === x.prefix || spec.startsWith(`${x.prefix}/`));
+      if (al) {
+        const rest = spec === al.prefix ? '' : spec.slice(al.prefix.length + 1);
+        target = posix.normalize(rest ? `${al.dir}/${rest}` : al.dir).replace(/\.[cm]?[jt]sx?$/, '');
+      } else if (a) suffix = a[1];
+      else {
+        // A workspace package by name (twenty-ui/input, @calcom/ui): the copy
+        // inside that package's folder. Until now every copy was credited,
+        // so Twenty's marketing-site Button carried the app's 274 uses too.
+        const ws = workspaces.find((w) => spec === w.name || spec.startsWith(`${w.name}/`));
+        if (!ws) return null;
+        const inside = defs.filter((d) => d.file.startsWith(`${ws.dir}/`));
+        return inside.length === 1 ? inside : null;
+      }
+    }
     const hit = defs.filter((d) => {
       const f = stripExt(d.file);
       if (target !== null) return f === target || f === `${target}/index` || d.file.startsWith(`${target}/`);
@@ -192,6 +244,28 @@ function importedDef(src, file, name, defs) {
   return null;
 }
 
+const JSX_FILE_RE = /\.(tsx|jsx|js)$/;
+
+/**
+ * Every component a file defines, by either door the harvest reads: a React
+ * component in a file with markup in it, and a web component registered by
+ * tag (Stencil, Lit, customElements.define), generated bindings left out.
+ * The live checks ask here, so a file defines for them what it defines for
+ * the report.
+ */
+export function componentNamesIn(src, file = null) {
+  // .js too, never .ts: a TypeScript generic reads like a tag, and the
+  // harvest takes React components from the same three extensions
+  const react = (!file || JSX_FILE_RE.test(file)) && looksLikeJSXFile(src) ? definedComponents(src) : [];
+  const web = GENERATED_RE.test(src.slice(0, 2000)) ? [] : webComponentDefs(src).map((d) => d.name);
+  return [...new Set([...react, ...web])];
+}
+
+// A page is a route, not a reusable part. Asked by the harvest for every file
+// it reads and by the live checks for the one file under review.
+export const isPageFile = (file) => /(^|\/)(app\/.*page|pages\/(?!_app|_document|api))/.test(file)
+  || /(^|\/)app\/.*\/(layout|template|error|loading)\.(tsx|jsx)$/.test(file);
+
 /**
  * Harvest all components: definitions (with variants/props) + usages across the
  * repo. `codeFiles` are relative paths; returns { components, totalDefined }.
@@ -199,7 +273,7 @@ function importedDef(src, file, name, defs) {
 export function harvestComponents(root, codeFiles) {
   // .js too — CRA-era repos (a big slice of the messy-repo audience) put JSX in
   // plain .js files; requiring .tsx/.jsx made whole repos read as empty.
-  const jsxFiles = codeFiles.filter((f) => /\.(tsx|jsx|js)$/.test(f));
+  const jsxFiles = codeFiles.filter((f) => JSX_FILE_RE.test(f));
   const sources = new Map();
   for (const f of jsxFiles) {
     const src = readSource(join(root, f));
@@ -210,8 +284,7 @@ export function harvestComponents(root, codeFiles) {
   const components = [];
   for (const [file, src] of sources) {
     if (!looksLikeJSXFile(src)) continue;
-    const isPage = /(^|\/)(app\/.*page|pages\/(?!_app|_document|api))/.test(file)
-      || /(^|\/)app\/.*\/(layout|template|error|loading)\.(tsx|jsx)$/.test(file);
+    const isPage = isPageFile(file);
     for (const name of definedComponents(src)) {
       components.push({
         name,
@@ -226,6 +299,8 @@ export function harvestComponents(root, codeFiles) {
   }
 
   // Pass 2: usages (skip the defining file's own render of itself is fine to count)
+  const workspaces = resolveWorkspaces(root);
+  const aliases = tsconfigAliases(root);
   const byName = new Map();
   for (const c of components) {
     if (!byName.has(c.name)) byName.set(c.name, []);
@@ -244,7 +319,7 @@ export function harvestComponents(root, codeFiles) {
       // features/invoices each "used 12x" (8 and 4 in truth), so neither read
       // as the canon (Ledgerly, 2026-09-24). Unresolved imports keep the old
       // rule and credit every copy.
-      const owners = defs.length > 1 ? importedDef(src, file, name, defs) ?? defs : defs;
+      const owners = defs.length > 1 ? importedDef(src, file, name, defs, workspaces, aliases) ?? defs : defs;
       for (const def of owners) {
         if (def.file === file) continue; // internal render/recursion, not adoption
         def.usageCount += n;

package/skills/roast-my-design-system/scripts/harvest/duplicates.mjs

@@ -54,8 +54,59 @@ const ROUTE_FRAGMENT_RE = /(^|\/)app\/.*\/(form|header|footer|nav|page|layout|lo
 // and _dashboard.analytics.tsx both export Page, 2026-09-17). A story is a
 // demo of a component, not a second implementation of it (medplum keeps a
 // MockDateWrapper in two stories folders).
-const ROUTE_FILE_RE = /(^|\/)routes\/[^/]+\.[jt]sx?$|(^|\/)(page|layout|route|loading|error|not-found|template|default)\.[jt]sx?$/;
+// Next.js's crash page is one more of these: every app in a monorepo has its
+// own global-error, and a starter keeps a second one in its templates folder
+// (9.2.1).
+const ROUTE_FILE_RE = /(^|\/)routes\/[^/]+\.[jt]sx?$|(^|\/)(page|layout|route|loading|error|global-error|not-found|template|default)\.[jt]sx?$/;
 const STORY_FILE_RE = /(^|\/)(stories|__stories__|\.storybook)\/|\.stories\.[jt]sx?$/;
+// Email templates legitimately mirror web component names (email Footer !=
+// web Footer); cross-matching them manufactures duplicates. An email folder
+// or file is one whose name carries "email" as a word of its own: emails/,
+// email-templates/, twenty-emails/, welcome-email.tsx. A screen about email
+// (ConfirmUserEmail, EmailInput) is interface and stays in (9.2.1: the rule
+// asked for the word at the start of the name and missed twenty-emails/).
+const EMAIL_PATH_RE = /(^|\/)(?:[a-z0-9]+[-_.])*emails?(?:[-_][a-z0-9]+)*(?:\/|\.[jt]sx?$)/i;
+// Same-name components living in different icons/ directories are ONE
+// problem — two icon libraries colliding — not N separate duplicates.
+const ICON_DIR_RE = /(^|\/)icons?\//i;
+
+/**
+ * Whether a definition can be a duplicate at all. The report's finder and the
+ * live checks both ask here, so a name the report lets repeat by design is
+ * never a finding on the file an agent just wrote (9.2.1: every TanStack
+ * route file was told its Route already existed in 40 places).
+ */
+export function canBeDuplicate({ name, file = '', isPage = false }) {
+  return !isPage && !NOT_DUPLICATES.has(name)
+    && !ROUTE_FRAGMENT_RE.test(file) && !ROUTE_FILE_RE.test(file)
+    && !STORY_FILE_RE.test(file) && !EMAIL_PATH_RE.test(file);
+}
+
+/**
+ * The other copies that make one definition a duplicate, or none. The live
+ * checks and the guard ask here, so their answer is the report's answer.
+ *
+ * A file the scan has read is settled by the report: the definition is a
+ * duplicate when the report counts the name and this file is one of the
+ * copies it counts. A wrapper, shadcn's own overlap inside the catalogue and
+ * two icon libraries colliding are listed by the report and never counted,
+ * so they are not findings on the file either. A file the scan has not read
+ * (content validated before it is saved) is judged on the copies that exist.
+ *
+ * @param def     { name, file, isPage } the definition under review
+ * @param copies  the ledger's entries for the name: [{ file, isPage, usageCount }]
+ * @param counted the files of the duplicate the report counts under the name,
+ *                or null when it counts none
+ * @param same    how two paths are compared (a guard matches on path tails)
+ */
+export function duplicateCopies({ name, file = '', isPage = false }, copies, counted = null, same = (a, b) => a === b) {
+  if (!canBeDuplicate({ name, file, isPage })) return [];
+  const others = (copies ?? []).filter((c) => !same(c.file, file) && canBeDuplicate({ ...c, name }));
+  if (!others.length) return [];
+  if ((copies ?? []).some((c) => same(c.file, file))) return (counted ?? []).some((f) => same(f, file)) ? others : [];
+  if (ICON_DIR_RE.test(file) && others.every((c) => ICON_DIR_RE.test(c.file))) return [];
+  return others;
+}
 
 /**
  * @param components output of harvestComponents (non-page components matter most)
@@ -66,12 +117,7 @@ const STORY_FILE_RE = /(^|\/)(stories|__stories__|\.storybook)\/|\.stories\.[jt]
  */
 export function findDuplicates(components, uiDir = null, root = null, uiDirs = null) {
   const catalogueDirs = uiDirs ?? (uiDir ? [uiDir] : []);
-  // Email templates legitimately mirror web component names (email Footer !=
-  // web Footer); cross-matching them manufactures duplicates.
-  const EMAIL_PATH_RE = /(^|\/)emails?(\/|-)/i;
-  const comps = components.filter((c) => !c.isPage && !NOT_DUPLICATES.has(c.name)
-    && !ROUTE_FRAGMENT_RE.test(c.file) && !ROUTE_FILE_RE.test(c.file)
-    && !STORY_FILE_RE.test(c.file) && !EMAIL_PATH_RE.test(c.file));
+  const comps = components.filter(canBeDuplicate);
 
   // 1. exact same component name defined in >1 file
   const byName = new Map();
@@ -88,9 +134,6 @@ export function findDuplicates(components, uiDir = null, root = null, uiDirs = n
     }))
     .sort((a, b) => b.files.length - a.files.length);
 
-  // Same-name components living in different icons/ directories are ONE
-  // problem — two icon libraries colliding — not N separate duplicates.
-  const ICON_DIR_RE = /(^|\/)icons?\//i;
   const iconCollisions = exactDuplicates.filter((d) => d.files.every((f) => ICON_DIR_RE.test(f)));
   exactDuplicates = exactDuplicates.filter((d) => !iconCollisions.includes(d));
 

package/skills/roast-my-design-system/scripts/harvest/tokens.mjs

@@ -377,6 +377,7 @@ export function harvestTokens(root, styleFiles, codeFiles) {
     return owner;
   };
   const paletteFiles = new Set();
+  const tailwindConfigs = new Set();
   const listShare = new Map();   // code file → share of its colour literals inside 8+ colour arrays
   const nsDefs = new Map();  // --telekom-x: value  → 'telekom' (definitions)
   const nsRefs = new Map();  // var(--telekom-x)    → 'telekom' (references)
@@ -536,6 +537,7 @@ export function harvestTokens(root, styleFiles, codeFiles) {
     // equivalent of --var definitions). Its fontFamily block is the typeface
     // declaration for the whole app.
     if (/(^|\/)tailwind\.config\.[mc]?[jt]s$/.test(f)) {
+      tailwindConfigs.add(f);
       for (const m of src.matchAll(HEX_RE)) { tokenDefined.add(normalizeHex(m[0])); colors.add(normalizeHex(m[0]), f); }
       const famBlock = src.match(/fontFamily\s*:\s*\{([\s\S]*?)\n\s*\}/);
       if (famBlock) {
@@ -708,6 +710,11 @@ export function harvestTokens(root, styleFiles, codeFiles) {
   // stylesheet is never a list, whatever shape its values take.
   const isList = (f) => /\.[jt]sx?$/.test(f) && !/(^|\/)tailwind\.config\.[mc]?[jt]s$/.test(f) && (listShare.get(f) ?? 0) >= 0.5;
   const candidates = new Set([...tokenColorDefsPerFile.keys(), ...paletteFiles]);
+  // Every file that states a token colour: a stylesheet defining --vars, a
+  // Tailwind config, a palette file. A checker reading one of these must not
+  // tell it to use itself; anywhere else a token's raw value is a paste of
+  // the value where the name belongs (Twenty, Haiku with the hook, 2026-09-29).
+  const tokenSources = [...new Set([...candidates, ...tailwindConfigs])].sort();
   const tokenFile = [...candidates]
     .map((f) => ({ f, tokens: tokenColoursIn.get(f) ?? 0, strays: straysIn.get(f) ?? 0, list: isList(f) ? 1 : 0 }))
     .filter((c) => c.tokens >= 3)
@@ -773,6 +780,7 @@ export function harvestTokens(root, styleFiles, codeFiles) {
   }
   return {
     tokenFile,
+    tokenSources,
     foreignStyles,
     namespaces,
     colors: colorList,

package/skills/roast-my-design-system/scripts/lib/guard-api.mjs

@@ -19,12 +19,14 @@ import { KITS } from '../profiles/kit-common.mjs';
 import { kitPaintFindings } from './kitpaint.mjs';
 import { PALETTE_CLASS_RE, blankComments } from '../harvest/paint.mjs';
 import { harvestTokens, extractStyling, normalizeHex, isGrey } from '../harvest/tokens.mjs';
-import { harvestComponents, definedComponents } from '../harvest/components.mjs';
+import { harvestComponents, definedComponents, tsconfigAliases } from '../harvest/components.mjs';
 import { findDuplicates } from '../harvest/duplicates.mjs';
 import { repoTokenDefs } from './tokentwins.mjs';
 import { dupeCopiesOf } from './avoidedimports.mjs';
 import { loadExclusions } from './exclusions.mjs';
 import { WIDGET_CONFIG_RE } from './exempt.mjs';
+import { buttonCandidates } from './handmade.mjs';
+import { resolveWorkspaces } from './workspaces.mjs';
 import { hexRgb } from './nearpairs.mjs';
 import { typefaceOf, GENERIC_FONTS } from './typefaces.mjs';
 
@@ -33,6 +35,21 @@ export { extractStyling, normalizeHex, isGrey, hexRgb, typefaceOf, GENERIC_FONTS
 // The components a piece of text defines. With the ledger below, a guard can
 // tell a second <Button> from an edit to the first one.
 export { definedComponents };
+// Duplicates, by the report's own answer (9.2.1). duplicateCopies(def,
+// copies, counted, same) returns the other copies that make one definition a
+// duplicate, or none: `copies` is the ledger's entries for the name
+// (learnSystem's components), `counted` the files of the duplicate the report
+// counts under it (the copies in learnSystem's duplicates), `same` how two
+// paths compare. canBeDuplicate({ name, file, isPage }) is the first question
+// it asks: a framework's Route, a page, a route file, the crash page, a story
+// and an email template repeat by design. isPageFile(file) answers isPage for
+// a file not in the ledger. componentNamesIn(text, file) lists what a whole
+// file defines for the report: React components in a .tsx, .jsx or .js file
+// with markup in it, and web components registered by tag. The exemptions
+// (exemptReason) are about styling, so a duplicate is still a duplicate in
+// an exempt file.
+export { canBeDuplicate, duplicateCopies } from '../harvest/duplicates.mjs';
+export { isPageFile, looksLikeJSXFile, componentNamesIn } from '../harvest/components.mjs';
 
 // The files no checker should judge. Exported so a guard reads the same list
 // as the engine rather than keeping a copy that drifts.
@@ -63,6 +80,9 @@ export { kitPaintFindings };
 export { tokenTwinFindings, tokenDefsOf } from './tokentwins.mjs';
 export { avoidedImportFindings, canonicalCopy } from './avoidedimports.mjs';
 export { isChartFile, chartSystemOf, chartTier, chartFindings } from './charts.mjs';
+// a button from scratch where the repo has a Button (9.2.0); learnSystem
+// hands over `buttons`, `workspaces` and `packageDeps` for buttonFor
+export { handmadeButtons, handmadeButtonFindings, buttonCandidates, buttonFor, BUTTON_MIN_USES } from './handmade.mjs';
 
 // Radius, font size, shadow and typeface: the patterns, so both checkers agree
 // on what a declaration is and what counts as a disciplined value.
@@ -110,7 +130,7 @@ export function learnSystem(repoRoot, { exclude = [] } = {}) {
   // the same two lists the MCP knowledge builds (mcp/knowledge.mjs), from the
   // same helpers, for tokenTwinFindings and avoidedImportFindings (8.6.1)
   const read = (f) => readSource(join(repoRoot, f));
-  const hardDupes = (findDuplicates(ledger, profile.uiDir, repoRoot).exactDuplicates ?? []).filter((d) => !d.wrapped);
+  const hardDupes = (findDuplicates(ledger, profile.uiDir, repoRoot, profile.uiDirs ?? null).exactDuplicates ?? []).filter((d) => !d.wrapped);
   const P = profileOf(profile);
   const installedNow = installedDirs(P);
   const charts = chartSystemOf(files, read, { own: (f) => !installedNow.some((d) => f === d || f.startsWith(`${d}/`)) });
@@ -137,8 +157,26 @@ export function learnSystem(repoRoot, { exclude = [] } = {}) {
     }
   }
 
+  // the Button the repo answers with, per package (lib/handmade.mjs)
+  const workspaces = resolveWorkspaces(repoRoot);
+  const buttons = buttonCandidates(ledger, read, workspaces, tsconfigAliases(repoRoot));
+  const packageDeps = new Map();
+  for (const w of workspaces) {
+    let pj = null;
+    try { pj = JSON.parse(read(`${w.dir}/package.json`) ?? 'null'); } catch { /* not a package after all */ }
+    packageDeps.set(w.dir, new Set(Object.keys({ ...pj?.dependencies, ...pj?.devDependencies, ...pj?.peerDependencies })));
+  }
+
   return {
     tokenFile: t.tokenFile,
+    buttons,
+    workspaces,
+    packageDeps,
+    // The files that state the palette: token stylesheets, a Tailwind config,
+    // palette data, a kit theme. Only there is a token's raw value the
+    // definition; in any other file it is a paste of the value where the
+    // name belongs, and a guard should say so (9.1.3).
+    tokenSources: [...new Set([...(t.tokenSources ?? []), ...(kit?.themeFiles ?? []), t.tokenFile].filter(Boolean))],
     colors: t.colors,
     // Every named colour, variants included — not the counted palette. The
     // report counts a token's base statement only, because a dark theme is

package/skills/roast-my-design-system/scripts/lib/handmade.mjs

@@ -0,0 +1,216 @@
+/**
+ * Hand-made buttons where the repo already has a Button.
+ *
+ * The bad-neighbour tests on Twenty (2026-09-29): with the edit hook on,
+ * Haiku reached zero value findings and still hand-made the button four
+ * times in five, with clean token colours. The value checks cannot see the
+ * choice; this one does. Buttons only, for now.
+ *
+ * Fleet probe, 204 clones (2026-09-29): 52 have a Button, 38 of those still
+ * hand-make buttons in page files, but most of those are clickable rows,
+ * tabs, toggles and "show more" links on a button tag for keyboard access,
+ * which nobody wants replaced. So the trigger is narrow: an element DRESSED
+ * as a button (a real background plus padding, a border or a radius), or
+ * one that calls itself a button by name and renders the raw tag. A reset
+ * (background: none; border: 0) is a row, not a button, and stays silent.
+ *
+ * The Button it points at must be visible from the file's own package. In
+ * Twenty the most-used Button is the marketing site's (313 uses); the app
+ * imports its own from twenty-ui. Pointing the app at the website's button
+ * would be worse than silence.
+ */
+
+import { posix } from 'node:path';
+
+const stripExt = (f) => f.replace(/\.[jt]sx?$/, '').replace(/\/index$/, '');
+
+/** Imports of a Button below this are a stray, not the repo's answer. */
+export const BUTTON_MIN_USES = 20;
+
+const NOT_OWN_CODE_RE = /(^|\/)(stories|__stories__|__tests__|__mocks__|test|tests|spec|docs?|examples?|playground|storybook|showcase|sandbox|demo|fixtures?)\/|\.(stories|test|spec)\.[jt]sx?$|(Sandbox|Showcase|Demo|Playground)\.[jt]sx?$/;
+// the system's own layer: a Button-ish thing here is the system being built
+const SYSTEM_LAYER_RE = /(^|\/)(ui|design-system|primitives|core)\/|[\w.-]*button[\w.-]*\.[jt]sx?$/i;
+// A name that says the element is not the action button: a close cross, a
+// chevron, a tab, a chip, a row that happens to be focusable. The fleet
+// probe (five repos, 2026-09-29) found these were most of the styled
+// buttons in page files, and none of them wants the Button.
+const OTHER_ROLE_RE = /(Icon|Close|Toggle|Expand|Collapse|Tab|Pill|Chip|Row|Item|Menu|Delete|Remove|Clear|Trigger|Header|Segment|Switch|Mode|Dot|Hidden|Tooltip|Info|Avatar|Handle|Link|Nav|Thumb|Step|Card|Tile|Option|Cell|Accordion|Summary|Tree|Folder|Image|Query|Checkbox|Radio|Swatch|Uploader|Container|Place|Bar|Control|Filter|Select|Value|Indicator)/;
+
+// Dressed as a button: real padding, and a real background or a real border.
+// A reset (background: none; border: 0; padding: 0) is a row, not a button.
+// An outline button has a border and padding but no background, so either
+// paint counts (Twenty's wizard SecondaryButton, 2026-09-29).
+// `\s*(?!\s)` pins the value's start: without it the regex backtracks past
+// the space after the colon and reads "background: none" as paint
+const REAL_BG = /(?:^|[\s;{])background(?:-color)?\s*:\s*(?!\s)(?!(?:none|transparent|inherit|unset|initial)\s*[;}])[^;}]*[;}]/i;
+const REAL_BORDER = /(?:^|[\s;{])border(?:-(?:top|bottom|left|right))?\s*:\s*(?!\s)(?!(?:none|0|0px|unset)\s*[;}])[^;}]*[;}]/i;
+const REAL_PAD = /(?:^|[\s;{])padding(?:-(?:top|bottom|left|right|inline|block))?\s*:\s*(?!\s)(?!0(?:px)?\s*[;}])[^;}]*[;}]/i;
+// a pseudo-state block (&:hover { background: ... }) is a state, not the
+// resting paint; a class variant block (&.primary { ... }) still counts
+// `${...}` interpolations carry braces of their own (arrow functions,
+// destructured props), so they are blanked first, by brace count, and each
+// reads as a value, not as an empty one
+const blankInterpolations = (body) => {
+  let out = '', i = 0;
+  while (i < body.length) {
+    if (body[i] === '$' && body[i + 1] === '{') {
+      let depth = 0, j = i + 1;
+      for (; j < body.length; j++) { if (body[j] === '{') depth++; else if (body[j] === '}' && --depth === 0) break; }
+      out += '_'; i = j + 1;
+    } else out += body[i++];
+  }
+  return out;
+};
+const stripStates = (body) => blankInterpolations(body).replace(/&?(?::[\w-]+(?:\([^)]*\))?|\[[^\]]*\])+\s*\{[^{}]*\}/g, ' ');
+// An action button carries a label the designer set (a weight, a size, a
+// transform). A card, a select trigger or a list row on a button tag reads
+// differently: text to the left, content spread apart, a column, a stretch
+// to fill the row, or a fixed position. Fleet probe, fifteen repos
+// (2026-09-29): those tells were nearly every innocent hit.
+const LABEL_CSS = /(?:^|[\s;{])(?:font-weight|font-size|text-transform|font-family|letter-spacing)\s*:/i;
+const OTHER_SHAPE_CSS = /(?:^|[\s;{])(?:text-align\s*:\s*left|justify-content\s*:\s*space-between|flex-direction\s*:\s*column|flex\s*:\s*1\b|width\s*:\s*100%|position\s*:\s*(?:absolute|fixed))/i;
+const dressedCss = (raw) => {
+  const body = stripStates(raw);
+  return REAL_PAD.test(body) && (REAL_BG.test(body) || REAL_BORDER.test(body)) && LABEL_CSS.test(body) && !OTHER_SHAPE_CSS.test(body);
+};
+
+// class strings: a bare bg- or border class (a hover: or focus: variant is a
+// state, not the resting paint) plus non-zero padding
+const TW_BG = /(?:^|\s)bg-(?!transparent|inherit|none)[\w[\]#/.-]/;
+const TW_BORDER = /(?:^|\s)border(?:\s|$|-(?!none|0(?:\s|$)|transparent)[\w[\]#/.-]*)/;
+// vertical padding of a full step or more: a badge (py-0.5), an avatar ring
+// (p-0.5) or a select trigger sized by height alone is not a button
+const TW_PAD = /(?:^|\s)p(?:y)?-(?:[1-9]\d*(?:\.\d+)?|\[)/;
+const TW_LABEL = /(?:^|\s)(?:font-(?:medium|semibold|bold|black)|text-white|text-[\w-]*foreground|uppercase)(?:\s|$)/;
+const TW_OTHER_SHAPE = /(?:^|\s)(?:text-left|justify-between|flex-col|items-start|placeholder:[\w-]+|absolute|fixed|hidden|invisible|border-dashed|rounded-full|(?:h|w|size)-(?:\d+|\[[^\]]*\])(?=\s|$))/;
+const dressedClasses = (cls) => TW_PAD.test(cls) && (TW_BG.test(cls) || TW_BORDER.test(cls)) && TW_LABEL.test(cls) && !TW_OTHER_SHAPE.test(cls);
+
+const INLINE_BG = /background(?:Color)?\s*:\s*(?!\s)['"`](?!transparent|none|inherit)/;
+const INLINE_BORDER = /border(?:Top|Bottom|Left|Right)?\s*:\s*(?!\s)['"`](?!none|0)/;
+const INLINE_PAD = /padding(?:Top|Bottom|Left|Right)?\s*:\s*(?!\s)(?!0(?:[,\s}]|$)|['"`]0(?:px)?['"`])/;
+const INLINE_LABEL = /(?:fontWeight|fontSize|textTransform|fontFamily)\s*:/;
+const dressedInline = (style) => INLINE_PAD.test(style) && (INLINE_BG.test(style) || INLINE_BORDER.test(style)) && INLINE_LABEL.test(style);
+
+/**
+ * The hand-made buttons in a piece of component code, each with where it
+ * starts and how it gave itself away.
+ * @returns [{ index, name, how }]  how: 'styled' | 'tag'
+ */
+export function handmadeButtons(text) {
+  const out = [];
+  const src = String(text ?? '');
+
+  // const StyledX = styled.button`...`  /  styled('button')({...})
+  for (const m of src.matchAll(/(?:const|let|var)\s+(\w+)\s*=\s*styled(?:\.button|\(\s*['"]button['"]\s*\))(?:<[^`(]*?>)?\s*(?:`([\s\S]*?)`|\(\s*\{([\s\S]*?)\}\s*\))/g)) {
+    const name = m[1];
+    if (OTHER_ROLE_RE.test(name)) continue;
+    // an object style ({ backgroundColor: '#fff', padding: 8 }) read as CSS
+    const body = m[2] ?? `${(m[3] ?? '').replace(/,/g, ';').replace(/([A-Z])/g, (c) => `-${c.toLowerCase()}`)};`;
+    if (dressedCss(body)) out.push({ index: m.index, name, how: 'styled' });
+  }
+
+  // <button className="bg-brand px-4 py-2">  /  <button style={{ background: ..., padding: ... }}>
+  for (const m of src.matchAll(/<button\b([^>]*)>/g)) {
+    const attrs = m[1];
+    const cls = /className\s*=\s*(?:"([^"]*)"|'([^']*)'|\{`([^`]*)`\})/.exec(attrs);
+    const style = /style\s*=\s*\{\{([^}]*)\}\}/.exec(attrs);
+    if ((cls && dressedClasses(cls[1] ?? cls[2] ?? cls[3] ?? '')) || (style && dressedInline(style[1]))) out.push({ index: m.index, name: null, how: 'tag' });
+  }
+  return out.sort((a, b) => a.index - b.index);
+}
+
+/**
+ * How the repo imports THIS Button, read from the files that use it: the
+ * most common specifier that resolves to the definition. A relative path
+ * resolves by position, an alias (@/ui/Button) by its tail, a package name
+ * by the workspace it names. The harvest credits every same-named copy when
+ * it cannot resolve a package import, so its usedIn for the website's
+ * Button holds app files importing twenty-ui/input; asking "which spec
+ * resolves to this file" is what keeps the answer honest.
+ */
+function importSpecOf(def, read, workspaces, aliases = []) {
+  const counts = new Map();
+  const stem = stripExt(def.file);
+  const resolves = (spec, from) => {
+    if (spec.startsWith('.')) {
+      const target = posix.normalize(posix.join(posix.dirname(from), spec));
+      return stem === target || stem === `${target}/index` || def.file.startsWith(`${target}/`);
+    }
+    // a tsconfig path alias (@sentry/scraps/button → static/app/components/core/button)
+    const al = aliases.find((x) => spec === x.prefix || spec.startsWith(`${x.prefix}/`));
+    if (al) {
+      const target = posix.normalize(spec === al.prefix ? al.dir : `${al.dir}/${spec.slice(al.prefix.length + 1)}`).replace(/\.[cm]?[jt]sx?$/, '');
+      return stem === target || stem === `${target}/index` || def.file.startsWith(`${target}/`);
+    }
+    const alias = /^[@~#]\/(.+)$/.exec(spec);
+    if (alias) return stem.endsWith(`/${alias[1]}`) || stem.endsWith(`/${alias[1]}/index`) || def.file.includes(`/${alias[1]}/`);
+    const ws = (workspaces ?? []).find((w) => spec === w.name || spec.startsWith(`${w.name}/`));
+    return !!ws && def.file.startsWith(`${ws.dir}/`);
+  };
+  for (const f of def.usedIn ?? []) {
+    const text = read(f);
+    if (!text) continue;
+    for (const m of text.matchAll(/import\s+(?:type\s+)?([^'";]*?)\s+from\s+['"]([^'"]+)['"]/g)) {
+      if (!/\bButton\b/.test(m[1])) continue;
+      if (resolves(m[2], f)) counts.set(m[2], (counts.get(m[2]) ?? 0) + 1);
+      break;
+    }
+  }
+  return [...counts.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
+}
+
+/**
+ * The Buttons a repo could answer with: every reusable component called
+ * Button, in the team's own code, imported at least BUTTON_MIN_USES times.
+ * @returns [{ file, usageCount, spec }]  spec: how the repo imports it, proven
+ */
+export function buttonCandidates(components, read, workspaces = [], aliases = []) {
+  return components
+    .filter((c) => c.name === 'Button' && !c.isPage && c.usageCount >= BUTTON_MIN_USES && !NOT_OWN_CODE_RE.test(c.file))
+    .map((c) => ({ file: c.file, usageCount: c.usageCount, spec: importSpecOf(c, read, workspaces, aliases) }))
+    // no file provably imports it (an alias the repo resolves elsewhere, or a
+    // name the harvest credited from other copies): no answer to point at
+    .filter((c) => c.spec)
+    .sort((a, b) => b.usageCount - a.usageCount);
+}
+
+/** The workspace package a file belongs to, or null. */
+export const packageOf = (file, workspaces) =>
+  (workspaces ?? []).filter((w) => file === w.dir || file.startsWith(`${w.dir}/`)).sort((a, b) => b.dir.length - a.dir.length)[0] ?? null;
+
+/**
+ * The Button a file should reach for: the most-used candidate visible from
+ * the file's package (its own, one it depends on, or code outside every
+ * package). Null when the repo has no answer for this file.
+ */
+export function buttonFor(file, { buttons = [], workspaces = [], packageDeps = new Map() } = {}) {
+  if (!buttons.length) return null;
+  const mine = file ? packageOf(file, workspaces) : null;
+  const deps = mine ? packageDeps.get(mine.dir) ?? new Set() : new Set();
+  const visible = buttons.filter((b) => {
+    const theirs = packageOf(b.file, workspaces);
+    if (!mine || !theirs) return true;
+    return theirs.dir === mine.dir || deps.has(theirs.name);
+  });
+  return visible[0] ?? null;
+}
+
+/**
+ * Findings for the hand-made buttons in a file, against the Button the repo
+ * answers with. Warnings: the check has not yet earned a violation.
+ */
+export function handmadeButtonFindings(text, { file = null } = {}, k) {
+  if (!file || SYSTEM_LAYER_RE.test(file) || NOT_OWN_CODE_RE.test(file)) return [];
+  const button = buttonFor(file, k);
+  if (!button) return [];
+  const out = [];
+  for (const h of handmadeButtons(text)) {
+    const what = h.how === 'styled' ? `A styled button (${h.name})` : 'A button tag styled by hand';
+    out.push({
+      rule: 'handmade-button', severity: 'warning', index: h.index,
+      message: `${what} where the repo already has <Button> (imported ${button.usageCount}x${button.spec ? ` from ${button.spec}` : `, ${button.file}`}).`,
+      fix: `Use ${button.spec ? `import { Button } from '${button.spec}'` : `the Button in ${button.file}`}. If it needs a kind the Button lacks, add a variant there rather than a new button here.`,
+    });
+  }
+  return out;
+}

package/skills/roast-my-design-system/scripts/lib/version.mjs

@@ -1,7 +1,7 @@
 // Single version constant for the engine — imported by diagnose (report
 // footer) and rules (generated-by line). This is the bump spot that used to
 // live as a const inside diagnose/index.mjs.
-export const VERSION = '9.1.2';
+export const VERSION = '9.2.1';
 // The shape of harvest.json and summary.json. Bumped only when a field is
 // renamed, removed or changes meaning; a new field is not a new schema. A
 // tool comparing two scans compares like with like by this number, not by VERSION.

package/skills/roast-my-design-system/scripts/lib/workspaces.mjs

@@ -57,14 +57,37 @@ const memo = new Map();
 const mtime = (p) => { try { return statSync(p).mtimeMs; } catch { return 0; } };
 
 export function resolveWorkspaces(root) {
-  const key = `${mtime(join(root, 'package.json'))}:${mtime(join(root, 'pnpm-workspace.yaml'))}`;
+  const sub = workspaceSubroot(root);
+  const at = sub ? join(root, sub) : root;
+  const key = `${sub ?? ''}:${mtime(join(at, 'package.json'))}:${mtime(join(at, 'pnpm-workspace.yaml'))}`;
   const hit = memo.get(root);
   if (hit && hit.key === key) return hit.value.map((w) => ({ ...w }));
-  const value = resolveWorkspacesUncached(root);
+  const value = resolveWorkspacesUncached(at).map((w) => (sub ? { ...w, dir: `${sub}/${w.dir}` } : w));
   memo.set(root, { key, value });
   return value.map((w) => ({ ...w }));
 }
 
+const declaresWorkspaces = (dir) => {
+  const pkg = readJSON(join(dir, 'package.json'));
+  return !!(Array.isArray(pkg?.workspaces) || Array.isArray(pkg?.workspaces?.packages) || existsSync(join(dir, 'pnpm-workspace.yaml')));
+};
+/**
+ * A polyglot repo keeps its JavaScript one level down: Mattermost's root is
+ * Go and webapp/package.json declares the workspaces (2026-09-29). When the
+ * root declares none, the first immediate subfolder that does is the
+ * workspace root, and every package dir is reported under it.
+ */
+function workspaceSubroot(root) {
+  if (declaresWorkspaces(root)) return null;
+  let entries;
+  try { entries = readdirSync(root, { withFileTypes: true }); } catch { return null; }
+  for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    if (!e.isDirectory() || e.name.startsWith('.') || e.name === 'node_modules') continue;
+    if (declaresWorkspaces(join(root, e.name))) return e.name;
+  }
+  return null;
+}
+
 function resolveWorkspacesUncached(root) {
   const patterns = [];
   const pkg = readJSON(join(root, 'package.json'));

package/skills/roast-my-design-system/scripts/mcp/engine.mjs

@@ -11,7 +11,8 @@
  *    in the repo means saying so, not inventing one.
  */
 import { extractStyling } from '../harvest/tokens.mjs';
-import { definedComponents } from '../harvest/components.mjs';
+import { componentNamesIn, isPageFile } from '../harvest/components.mjs';
+import { duplicateCopies } from '../harvest/duplicates.mjs';
 import { hexRgb } from '../lib/nearpairs.mjs';
 import { exemptReason } from '../lib/exempt.mjs';
 import { extraDeclarations, fontDeclarations } from '../lib/declarations.mjs';
@@ -23,6 +24,7 @@ import { oklab } from '../lib/color.mjs';
 import { tokenTwinFindings } from '../lib/tokentwins.mjs';
 import { avoidedImportFindings } from '../lib/avoidedimports.mjs';
 import { isChartFile, chartFindings } from '../lib/charts.mjs';
+import { handmadeButtonFindings } from '../lib/handmade.mjs';
 
 // What this engine measures — shipped with every result, clean or not.
 export const CHECKS = [
@@ -43,10 +45,11 @@ export const CHECKS = [
 // MUI repo says the kit check ran.
 export const KIT_CHECK = 'colours and pixel sizes written onto kit components where the theme has a value';
 export const PALETTE_CHECK = 'palette classes where the theme names a colour';
+export const BUTTON_CHECK = 'hand-made buttons where the repo has a Button';
 export function checksFor(k) {
-  if (k?.kit) return [...CHECKS, KIT_CHECK];
-  if (k?.tailwind || k?.shadcn) return [...CHECKS, PALETTE_CHECK];
-  return CHECKS;
+  const list = k?.kit ? [...CHECKS, KIT_CHECK] : (k?.tailwind || k?.shadcn) ? [...CHECKS, PALETTE_CHECK] : [...CHECKS];
+  if (k?.buttons?.length) list.push(BUTTON_CHECK);
+  return list;
 }
 // "an MUI component", "an Ant Design component", "a Mantine component"
 
@@ -81,6 +84,29 @@ function nearestToken(value, k) {
   return best;
 }
 
+/**
+ * The report's answer on duplicates, asked of one file: a name that repeats
+ * by design, a pair the report lists without counting and a file that
+ * defines nothing the report reads are not duplicates here either
+ * (harvest/duplicates.mjs).
+ */
+function duplicateFindings({ text, file, k, add }) {
+  for (const name of componentNamesIn(text, file)) {
+    const dupe = k.dupeByName.get(name);
+    const counted = dupe ? dupe.files.map((f) => (typeof f === 'string' ? f : f.file)) : null;
+    const existing = duplicateCopies({ name, file: file ?? '', isPage: !!file && isPageFile(file) }, k.byName.get(name), counted);
+    if (!existing.length) continue;
+    // the scan may already include this very file — count the OTHER copies
+    const otherCopies = counted ? counted.filter((f) => f !== file) : null;
+    const best = [...existing].sort((a, b) => b.usageCount - a.usageCount)[0];
+    add('duplicate-component', 'violation', text.indexOf(name),
+      otherCopies && otherCopies.length > 1
+        ? `Defines <${name}>, which already exists in ${otherCopies.length} other places. This makes ${otherCopies.length + 1} competing copies, and every wrong pick becomes the example the next agent copies.`
+        : `Defines <${name}>, but ${best.file} already defines it${best.usageCount ? ` (used ${best.usageCount}x)` : ''}.`,
+      `Import ${best.file} instead of creating a copy.`);
+  }
+}
+
 /**
  * Validate one piece of content against the repo's knowledge.
  * @param content { text, file?, before? } — file name decides css-vs-code
@@ -89,7 +115,8 @@ function nearestToken(value, k) {
  *   unknown), so a token or an import the change ADDS can be told from one
  *   that was already there
  * @returns { findings: [{ rule, severity, line, message, fix? }], checked,
- *   exempt? } — exempt is a sentence saying why the file was not judged
+ *   exempt? } — exempt is a sentence saying why the file's styling was not
+ *   judged; its findings are then duplicates only, and checked says so
  */
 export function validateContent(content, k) {
   const { text, file = null, before } = content;
@@ -97,13 +124,20 @@ export function validateContent(content, k) {
   // checker earns its reputation for crying wolf, and a checker people
   // distrust gets switched off. Say nothing, and say why nothing was said.
   const exempt = exemptReason(file, text);
-  if (exempt) return { findings: [], checked: checksFor(k), exempt };
   const css = file ? CSS_FILE_RE.test(file) : looksLikeCss(text);
-  const got = extractStyling(text, { css });
   const findings = [];
   const add = (rule, severity, index, message, fix) => findings.push({
     rule, severity, line: lineOf(text, index), message, ...(fix ? { fix } : {}),
   });
+  // The exemption is about styling: what an email, a drawing or a crash page
+  // cannot take from the system. A second copy of a component is a second
+  // copy in any medium, and the report counts it, so that one check still
+  // runs and the result says it was the only one.
+  if (exempt) {
+    if (!css) duplicateFindings({ text, file, k, add });
+    return { findings, checked: css ? [] : ['duplicate component definitions'], exempt };
+  }
+  const got = extractStyling(text, { css });
 
   // The knowledge scan includes the working tree, so a file under review has
   // already leaked its own values into the repo counts — without a discount,
@@ -197,18 +231,27 @@ export function validateContent(content, k) {
 
   // ---------- colours ----------
   const seenHere = new Set();
+  const statesTokens = !!file && k.tokenSources?.has(file);
   for (const c of got.colors) {
     if (seenHere.has(`${c.value}:${c.index}`)) continue;
     seenHere.add(`${c.value}:${c.index}`);
     if (kitOwnsColours || chartFile) continue; // the kit judge or the chart rule said it, or judged it not paint
     const info = k.colorInfo.get(c.value);
-    if (info?.isToken) continue; // it IS the token's value — the system can see it
+    // A token's raw value is the definition only inside a file that states
+    // the palette (a token stylesheet, a Tailwind config, a kit theme). In a
+    // component it is the value pasted where the name belongs: the system
+    // cannot see it, and the next reader copies the hex. Until 9.1.3 every
+    // exact match walked free, and hooked agents on Twenty wrote
+    // background: #4a38f5 with a clean bill (2026-09-29).
+    if (info?.isToken && statesTokens) continue;
     const near = nearestToken(c.value, k);
     const priors = discount(info?.count, localColor, c.value);
     if (near && near.d === 0) {
+      const names = k.tokenNames?.get(c.value) ?? [];
+      const by = names.length ? `${css ? `var(${names[0]})` : names[0]}` : `the token that already holds ${near.value}`;
       add('hardcoded-colour', 'violation', c.index,
         `Hardcoded colour ${c.value} duplicates an existing token value.`,
-        `Use the token that already holds ${near.value}${k.tokens.tokenFile ? ` (defined in ${k.tokens.tokenFile})` : ''}.`);
+        `Use ${by}${k.tokens.tokenFile ? ` (defined in ${k.tokens.tokenFile})` : ''}.`);
     } else if (near && near.d <= 8) {
       add('near-token-twin', 'violation', c.index,
         `${c.value} is visually identical to the token ${near.value}.`,
@@ -224,6 +267,11 @@ export function validateContent(content, k) {
     }
   }
 
+  // ---------- the choice, not the value: a button from scratch ----------
+  // The value checks above cannot see it. Hooked agents on Twenty passed
+  // them and still hand-made the button four times in five (2026-09-29).
+  if (!css) for (const f of handmadeButtonFindings(text, { file }, k)) add(f.rule, f.severity, f.index, f.message, f.fix);
+
   // ---------- spacing ----------
   for (const s of got.spacing) {
     if (kitPx.has(s.value)) continue; // the kit line above said it
@@ -242,9 +290,13 @@ export function validateContent(content, k) {
     // a raw value the repo already uses, in a non-Tailwind repo, is consistency,
     // not a new offence — silence
   }
+  // Bracket values inside installed code (the shadcn catalogue, kit blocks,
+  // registries) are the kit's own choices. The report names them and keeps
+  // them out of the count; a file under review is judged by the same line.
+  const installed = !!file && (k.installedDirs ?? []).some((d) => file === d || file.startsWith(`${d}/`));
   const localArb = new Map();
   for (const a of got.arbitrary) localArb.set(a.value, (localArb.get(a.value) ?? 0) + 1);
-  for (const a of got.arbitrary) {
+  for (const a of installed ? [] : got.arbitrary) {
     const repoArb = (k.tokens.tailwind?.arbitrary ?? []).find((x) => x.value === a.value);
     const priorArb = discount(repoArb?.count, localArb, a.value);
     add('arbitrary-value', 'violation', a.index,
@@ -329,23 +381,7 @@ export function validateContent(content, k) {
   }
 
   // ---------- duplicate components ----------
-  if (!css) {
-    for (const name of definedComponents(text)) {
-      const existing = (k.byName.get(name) ?? []).filter((c) => !file || c.file !== file);
-      if (!existing.length) continue;
-      const dupe = k.dupeByName.get(name);
-      // the scan may already include this very file — count the OTHER copies
-      const otherCopies = dupe
-        ? dupe.files.map((f) => (typeof f === 'string' ? f : f.file)).filter((f) => f !== file)
-        : null;
-      const best = [...existing].sort((a, b) => b.usageCount - a.usageCount)[0];
-      add('duplicate-component', 'violation', text.indexOf(name),
-        otherCopies && otherCopies.length > 1
-          ? `Defines <${name}>, which already exists in ${otherCopies.length} other places. This makes ${otherCopies.length + 1} competing copies, and every wrong pick becomes the example the next agent copies.`
-          : `Defines <${name}>, but ${best.file} already defines it${best.usageCount ? ` (used ${best.usageCount}x)` : ''}.`,
-        `Import ${best.file} instead of creating a copy.`);
-    }
-  }
+  if (!css) duplicateFindings({ text, file, k, add });
 
   // ---------- an import of the copy the canon replaces ----------
   if (!css) {

package/skills/roast-my-design-system/scripts/mcp/hook.mjs

@@ -114,7 +114,8 @@ function judge(real, root, k, warned = new Set()) {
   const text = readFileSync(real, 'utf8');
   const before = beforeOf(k, rel);
   const { findings: all, exempt } = validateContent({ text, file: rel, before }, k);
-  if (exempt || !all.length) return null;
+  // an exempt file is judged on duplicates only; with none, there is nothing to say
+  if (!all.length) return null;
   // Only what this edit added. A legacy file carries its old findings on
   // every touch; repeating them after each edit is noise, and the review
   // (--check, roast_review) already reports them once at the end. Same rule
@@ -129,5 +130,5 @@ function judge(real, root, k, warned = new Set()) {
     return true;
   });
   if (!findings.length) return null;
-  return { text: `Design-system check of ${rel} (roast-my-design-system, the same engine as roast_validate): ${findingLines(findings, k).join('\n')}`, total: findings.length };
+  return { text: `Design-system check of ${rel} (roast-my-design-system, the same engine as roast_validate): ${findingLines(findings, k, exempt).join('\n')}`, total: findings.length };
 }

package/skills/roast-my-design-system/scripts/mcp/knowledge.mjs

@@ -19,6 +19,8 @@ import { findDuplicates } from '../harvest/duplicates.mjs';
 import { harvestContext } from '../harvest/context.mjs';
 import { loadExclusions } from '../lib/exclusions.mjs';
 import { resolveWorkspaces } from '../lib/workspaces.mjs';
+import { buttonCandidates } from '../lib/handmade.mjs';
+import { tsconfigAliases } from '../harvest/components.mjs';
 import { neverImportedComponents } from '../lib/neverimported.mjs';
 import { typefaceOf } from '../lib/typefaces.mjs';
 import { hexRgb } from '../lib/nearpairs.mjs';
@@ -72,7 +74,10 @@ export function loadKnowledge(root) {
     // same shape as a harvested colour, so every reader of `files` keeps working
     for (const v of themeSet) if (!tokens.colors.some((c) => c.value === v)) tokens.colors.push({ value: v, count: 1, files: [{ file: kit.themeFiles[0] ?? '', count: 1 }], isToken: true });
   }
-  const duplicates = findDuplicates(components, profile.uiDir, root);
+  // every catalogue folder, as the report passes them (harvest/index.mjs): a
+  // monorepo with two installs has two, and shadcn's own overlap in the
+  // second is no more the team's than in the first
+  const duplicates = findDuplicates(components, profile.uiDir, root, profile.uiDirs ?? null);
   const context = harvestContext(root);
   const workspaces = resolveWorkspaces(root);
 
@@ -80,6 +85,14 @@ export function loadKnowledge(root) {
   const colorInfo = new Map(); // value → { count, isToken }
   for (const c of tokens.colors) colorInfo.set(c.value, { count: c.count, isToken: c.isToken });
   const tokenColors = [...colorInfo.entries()].filter(([, i]) => i.isToken).map(([v]) => v);
+  // value → the custom-property names that hold it, so a check can say
+  // "use var(--color-brand)" rather than only "use the token"
+  const tokenNames = new Map();
+  for (const c of tokens.colors) if (c.names?.length) tokenNames.set(c.value, c.names);
+  // the files that state the palette (token stylesheets, a Tailwind config,
+  // a kit theme, palette data): the only files where a token's raw value is
+  // the definition rather than a paste of it
+  const tokenSources = new Set([...(tokens.tokenSources ?? []), ...(kit?.themeFiles ?? []), tokens.tokenFile].filter(Boolean));
 
   // spacing the repo already uses: raw CSS values with counts, plus whether
   // the repo styles spacing through Tailwind at all (decides what "on-scale" means)
@@ -123,6 +136,18 @@ export function loadKnowledge(root) {
 
   const neverImported = neverImportedComponents(components, profile.uiDir);
 
+  // The Button the repo answers with, per package: the candidates, and what
+  // each workspace package depends on, so a file is pointed at a Button it
+  // can actually import (lib/handmade.mjs).
+  const readK = (f) => readSource(join(root, f));
+  const buttons = buttonCandidates(components, readK, workspaces, tsconfigAliases(root));
+  const packageDeps = new Map();
+  for (const w of workspaces) {
+    let pj = null;
+    try { pj = JSON.parse(readK(`${w.dir}/package.json`) ?? 'null'); } catch { /* not a package after all */ }
+    packageDeps.set(w.dir, new Set(Object.keys({ ...pj?.dependencies, ...pj?.devDependencies, ...pj?.peerDependencies })));
+  }
+
   // The copies of each duplicated name with their usage, and the colours each
   // copy hard-codes: what the avoided-import check names (lib/avoidedimports).
   const read = (file) => readSource(join(root, file));
@@ -152,6 +177,10 @@ export function loadKnowledge(root) {
     workspaces,
     // indexes
     colorInfo,
+    buttons,
+    packageDeps,
+    tokenNames,
+    tokenSources,
     tokenColors,
     tokenColorRgb: tokenColors.map((v) => ({ value: v, rgb: hexRgb(v) })).filter((t) => t.rgb),
     spacingSeen,
@@ -170,6 +199,10 @@ export function loadKnowledge(root) {
     neverImported,
     // stock, not debt: see profiles/index.mjs
     vendoredUi: P.vendoredUi,
+    // folders the team did not write, by the same line the guard doorway
+    // draws (lib/guard-api.mjs): only a shadcn kit has installed code, and a
+    // registry's published folders are its own work
+    installedDirs: P.isShadcn && !P.isRegistry ? installed : [],
     // the kit the product is built on, and the Tailwind theme it names its
     // colours in: null when the repo is neither (see profiles/)
     kit,

package/skills/roast-my-design-system/scripts/mcp/tools.mjs

@@ -306,19 +306,22 @@ export function validate(k, { code, file = null } = {}) {
   if (file != null && typeof file !== 'string') return invalidInput('file is optional, but when sent it must be a repo-relative path as a string.');
   if (code.length > MAX_VALIDATE_CHARS) return invalidInput(`That is ${Math.round(code.length / 1000)}k characters; send the part you changed (up to ${MAX_VALIDATE_CHARS / 1000}k).`);
   const { findings, exempt } = validateContent({ text: code, file, before: beforeOf(k, file) }, k);
-  if (exempt) return `Not judged: ${file} is exempt because ${exempt}. Nothing here was checked.`;
+  if (exempt && !findings.length) return `Not judged: ${file} is exempt because ${exempt}. Nothing here was checked.`;
   if (!findings.length) return cleanResultText(k);
-  return findingLines(findings, k).join('\n');
+  return findingLines(findings, k, exempt).join('\n');
 }
 
 /** The finding list as roast_validate prints it; the edit hook prints the same. */
-export function findingLines(findings, k) {
+export function findingLines(findings, k, exempt = null) {
   const L = [`${findings.length} finding${findings.length === 1 ? '' : 's'}:`];
   for (const f of findings.slice(0, 12)) {
     L.push(`${f.severity === 'violation' ? '✕' : '⚠'} L${f.line} ${f.message}${f.fix ? `\n   Fix: ${f.fix}` : ''}`);
   }
   if (findings.length > 12) L.push(`(+${findings.length - 12} more of the same kinds)`);
-  L.push(`Checked: ${checksFor(k).join(', ')}.`);
+  // an exempt file is judged on one thing, and the reader is told which
+  L.push(exempt
+    ? `Checked: duplicate component definitions. The styling was not judged, because ${exempt}.`
+    : `Checked: ${checksFor(k).join(', ')}.`);
   return L;
 }
 
@@ -355,12 +358,12 @@ export function reviewData(k) {
     try { text = readFileSync(join(gitRoot, f), 'utf8'); } catch { continue; }
     // knowledge paths are scanned-root-relative; git paths are toplevel-relative
     const { findings, exempt } = validateContent({ text, file: relative(realRoot, join(gitRoot, f)), before: headVersion(gitRoot, f) }, k);
-    if (exempt) { exemptCount++; continue; }
+    if (exempt) exemptCount++;
     if (findings.length) { perFile.push({ f, findings }); total += findings.length; }
   }
   // Skipped is not the same as clean, and the reader is owed the difference.
   const exemptNote = exemptCount
-    ? ` ${exemptCount} file${exemptCount === 1 ? ' was' : 's were'} left unjudged: email, print, artwork or pictures drawn with code.`
+    ? ` The styling of ${exemptCount} file${exemptCount === 1 ? ' was' : 's were'} left unjudged: email, print, artwork or pictures drawn with code.`
     : '';
   if (!total) {
     return { text: `Reviewed ${changed.length} changed file${changed.length === 1 ? '' : 's'}. ${cleanResultText(k)}${exemptNote}`, total: 0 };