roast-my-design-system 9.2.3 → 9.2.5

package/README.md

@@ -135,18 +135,18 @@ Eleven reports, hosted exactly as the tool writes them. Every number determinist
 - **[Apache Airflow](https://gregkozakiewicz.github.io/roast-my-design-system/examples/airflow-chakra.html)** (Chakra UI): no colours written onto components, 4 spacings per 100 kit files as pixel strings where a space step exists. Score 43.
 - **[vercel/ai-chatbot](https://gregkozakiewicz.github.io/roast-my-design-system/examples/vercel-ai-chatbot.html)** (shadcn install): 74 values like [13px] written outside the Tailwind scale, and 66 palette colours per 100 files where a theme variable exists; Claude's notes embedded. Score 80.
 - **[excalidraw/excalidraw](https://gregkozakiewicz.github.io/roast-my-design-system/examples/excalidraw-excalidraw.html)**: 78 off-scale spacing values and 90 !important declarations. Score 55.
-- **[dubinc/dub](https://gregkozakiewicz.github.io/roast-my-design-system/examples/dubinc-dub.html)**: 624 arbitrary bracket values, 22 duplicated components, and the chart-palette gap named. Score 20.
+- **[dubinc/dub](https://gregkozakiewicz.github.io/roast-my-design-system/examples/dubinc-dub.html)**: 624 arbitrary bracket values, 21 duplicated components, and the chart-palette gap named. Score 20.
 - **[telekom/scale](https://gregkozakiewicz.github.io/roast-my-design-system/examples/telekom-scale.html)** (Stencil): 95 Stencil components read by tag; 66 spacing values outside the scale where about 12 would do; Claude's notes embedded. Score 55.
 - **[magicuidesign/magicui](https://gregkozakiewicz.github.io/roast-my-design-system/examples/magicui.html)** (registry): counted on the components it publishes, 52 off-theme colours per 100 files in the code it ships, its docs site kept out and named. Score 78.
 - **[adobe/spectrum-web-components](https://gregkozakiewicz.github.io/roast-my-design-system/examples/adobe-spectrum.html)** (Lit): hardcoded colours sitting beside 744 colour tokens, and 37 !important declarations. Score 66.
 
 The full report for vercel/ai-chatbot. The verdict answers what the agent will learn here, the gap section comes first, then "What the repo teaches the agent", Claude's read of the scan:
 
-![The full diagnosis report for vercel/ai-chatbot in dark mode: a fixed side panel with the health score and what it measures, the stack, how the repo was read as a shadcn install, an index of every section and what is not the team's and not counted; then where the agent will have to guess, the fixes you can make right now, each with what it is worth and its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, 3-yardstick tiles including the 2 shadcn tiles, the adoption map treemap, palette forensics, the shadcn theme variable by variable, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](assets/report-full-dark.png?v=9.2.2)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: a fixed side panel with the health score and what it measures, the stack, how the repo was read as a shadcn install, an index of every section and what is not the team's and not counted; then where the agent will have to guess, the fixes you can make right now, each with what it is worth and its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, 3-yardstick tiles including the 2 shadcn tiles, the adoption map treemap, palette forensics, the shadcn theme variable by variable, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](assets/report-full-dark.png?v=9.2.4)
 
 The same report in light mode (one file, built-in toggle):
 
-![The diagnosis report in light mode](assets/report-light-hero.png?v=9.2.2)
+![The diagnosis report in light mode](assets/report-light-hero.png?v=9.2.4)
 
 ## Why the numbers hold
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "9.2.3",
+  "version": "9.2.5",
   "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/diagnose/index.mjs

@@ -1066,8 +1066,9 @@ function whereToStartSection() {
     c.push({ score: 40, metric: null, title: `Delete the ${dead.length} theme variable${dead.length === 1 ? '' : 's'} nothing uses`,
       sub: `${dead.slice(0, 3).map((r) => `--${esc(r)}`).join(', ')}${dead.length > 3 ? ' and more' : ''} sit in ${esc(P.shadcn.sheet.file)} next to the real theme, and nothing in the repo reads them. An agent opening that file sees 2 colour systems and can not tell which one is dead. ${dead.length * 2} lines to delete; the cheapest fix on this page.` });
   }
-  if (agentFiles.length === 0) c.push({ score: 60, metric: null, title: 'Write the agent rules file',
-    sub: `No CLAUDE.md, no AGENTS.md. One page naming the canonical components and the tokens file stops your agent guessing on every UI change. Cheapest fix on this list.` });
+  // The agent rules file is not a fix here: it has its own section ("Give the
+  // agent the answers") and must not compete with fixes for the three places
+  // (Greg, 2026-09-30).
   if (componentsMeasured && hardDupes.length > 0) {
     // Pick the pair with the strongest copy-paste evidence: sibling files in
     // app code (same basename, neither in a shared package) are true
@@ -1206,6 +1207,9 @@ function whereToStartSection() {
   // already green, or the move lands inside the band it started in.
   for (const item of c) {
     item.delta = 0; item.target = null; item.why = 'not part of the score';
+    // No score, no points: an unscored report promised "+10" and "raises the
+    // score, by 5" on commerce, strapi and three more (2026-09-30).
+    if (healthScore === null) { item.why = 'no score here'; continue; }
     if (!item.metric) continue;
     const tile = bigStats.find((st) => st.metric === item.metric);
     const now = tile?.healthValue;
@@ -1218,7 +1222,12 @@ function whereToStartSection() {
     if (nb && nb.gain > 0) item.target = nb;
     else item.why = healthOf(item.metric, now) === 'good' ? 'already green' : 'no points on its own';
   }
-  const top3 = c.sort((a, b) => (b.delta - a.delta) || (b.score - a.score)).slice(0, 3);
+  // A fix that pays only once finished still outranks one that never pays:
+  // sorting on delta alone put shadcn-admin's one paying fix second, behind a
+  // fix worth nothing (2026-09-30).
+  const tier = (item) => (item.delta > 0 ? 2 : item.target ? 1 : 0);
+  const top3 = c.sort((a, b) => (tier(b) - tier(a)) || (b.delta - a.delta)
+    || ((b.target?.gain ?? 0) - (a.target?.gain ?? 0)) || (b.score - a.score)).slice(0, 3);
   if (!top3.length) return '';
   // The headline is the score with every move applied together, not the sum of
   // the parts: two moves on the same tile must not be counted twice.
@@ -1244,7 +1253,9 @@ function whereToStartSection() {
     ? `${ofThese(paying.length)} could raise the design system health score from <b class="proj">${healthScore} to ${after}</b>.${later.length ? ` ${cap(COUNT[later.length - 1])} more ${later.length === 1 ? 'pays' : 'pay'} ${inFull(later.length)}.` : ''}${rest}`
     : later.length
       ? `${ofThese(later.length)} ${later.length === 1 ? `raises the score, by ${later[0].target.gain},` : 'raise the score'} ${inFull(later.length)}.${rest}`
-      : `${total === 1 ? 'It does' : 'They do'} not move the score. ${total === 1 ? 'It is' : 'They are'} here because ${total === 1 ? 'it stops' : 'each one stops'} the agent guessing.`;
+      : healthScore === null
+        ? `This repo gets no score, so there is no score to raise. ${total === 1 ? 'This fix is' : 'These fixes are'} here because ${total === 1 ? 'it stops' : 'each one stops'} the agent guessing.`
+        : `${total === 1 ? 'It does' : 'They do'} not move the score. ${total === 1 ? 'It is' : 'They are'} here because ${total === 1 ? 'it stops' : 'each one stops'} the agent guessing.`;
   const title = paying.length || later.length ? 'Fixes you can make right now to increase the health score' : 'Fixes you can make right now';
   const chip = (item) => item.delta > 0
     ? `<span class="delta" title="once all of them are done">+${item.delta}</span>`

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

@@ -7,6 +7,7 @@
 import { join, basename, posix } from 'node:path';
 import { readSource } from './walk.mjs';
 import { resolveWorkspaces } from '../lib/workspaces.mjs';
+import { isDrawing, SVG_MARKUP_RE } from '../lib/exempt.mjs';
 
 /**
  * Import aliases a tsconfig declares: "@sentry/scraps/*": ["./static/app/
@@ -285,11 +286,15 @@ export function harvestComponents(root, codeFiles) {
   for (const [file, src] of sources) {
     if (!looksLikeJSXFile(src)) continue;
     const isPage = isPageFile(file);
+    const drawing = isDrawing(file, src);
+    const draws = SVG_MARKUP_RE.test(src);
     for (const name of definedComponents(src)) {
       components.push({
         name,
         file,
         isPage,
+        drawing,
+        draws,
         variants: extractVariants(src),
         propsHint: extractPropsHint(src, name),
         usageCount: 0,

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

@@ -69,6 +69,23 @@ const EMAIL_PATH_RE = /(^|\/)(?:[a-z0-9]+[-_.])*emails?(?:[-_][a-z0-9]+)*(?:\/|\
 // 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;
+// The icon folder a file belongs to, up to and including icons/. Names that
+// repeat inside ONE icon folder are variants of one set (likec4's aws/, gcp/
+// and tech/ batch icons; nodejs.org's Logo and Favicon for each partner), not
+// two sets colliding: 121 of 180 icon collisions on 205 repos (2026-09-30).
+const iconSetOf = (f) => { const m = f.match(/^(.*?(?:^|\/)icons?\/)/i); return m ? m[1] : null; };
+// An icon is left out of a name's copies when nothing else of that name
+// draws: a Switch icon is not a second Switch component (teable), a Setting
+// icon not a second settings page (cloudreve). When another copy draws too, the
+// icon stays in: the same checkmark or logo drawn twice is two copies
+// (remotion's Checkmark, Typebot's logo in four places). Measured 2026-09-30.
+// A copy with no answer (a guard that does not say) leaves the set as it is.
+export function competing(defs) {
+  if (defs.some((d) => d.drawing === undefined)) return defs;
+  const icons = defs.filter((d) => d.drawing);
+  const rest = defs.filter((d) => !d.drawing);
+  return icons.length && rest.length && !rest.some((d) => d.draws) ? rest : defs;
+}
 
 /**
  * Whether a definition can be a duplicate at all. The report's finder and the
@@ -99,9 +116,12 @@ export function canBeDuplicate({ name, file = '', isPage = false }) {
  *                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) {
+export function duplicateCopies({ name, file = '', isPage = false, drawing, draws }, 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 }));
+  const self = { name, file, isPage, drawing, draws };
+  const pool = competing([self, ...(copies ?? []).filter((c) => !same(c.file, file) && canBeDuplicate({ ...c, name }))]);
+  if (!pool.includes(self)) return [];
+  const others = pool.filter((c) => c !== self);
   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 [];
@@ -126,6 +146,7 @@ export function findDuplicates(components, uiDir = null, root = null, uiDirs = n
     byName.get(c.name).push(c);
   }
   let exactDuplicates = [...byName.entries()]
+    .map(([name, defs]) => [name, competing(defs)])
     .filter(([, defs]) => new Set(defs.map((d) => d.file)).size > 1)
     .map(([name, defs]) => ({
       name,
@@ -134,8 +155,9 @@ export function findDuplicates(components, uiDir = null, root = null, uiDirs = n
     }))
     .sort((a, b) => b.files.length - a.files.length);
 
-  const iconCollisions = exactDuplicates.filter((d) => d.files.every((f) => ICON_DIR_RE.test(f)));
-  exactDuplicates = exactDuplicates.filter((d) => !iconCollisions.includes(d));
+  const inIcons = exactDuplicates.filter((d) => d.files.every((f) => ICON_DIR_RE.test(f)));
+  exactDuplicates = exactDuplicates.filter((d) => !inIcons.includes(d));
+  const iconCollisions = inIcons.filter((d) => new Set(d.files.map(iconSetOf)).size > 1);
 
   // A "duplicate" where one file imports the same identifier from the other is
   // a wrapper/composition (memoized variant, styled passthrough) — still an

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

@@ -15,7 +15,9 @@
  * enough though, or every Badge component would walk free: the contents must
  * actually draw SVG. A Badge that is plain styled UI gets judged like anything
  * else. A file that is mostly SVG earns it on contents alone, whatever it is
- * called.
+ * called. So does a file that draws SVG inside an icons, logos or
+ * illustrations folder: an icon set names its files after what they show
+ * (ActionSendEmail.tsx, Server.tsx), not after being an icon.
  *
  * Render-to-image: an OG card or a PDF invoice is a picture drawn with code.
  * satori and react-pdf accept nothing but inline styles, so there is no
@@ -105,6 +107,11 @@ export function isEmail(file, text = '', email = null) {
 export const CRASH_PAGE_RE = /(^|\/)global-error\.(tsx|jsx)$/;
 export const ARTWORK_NAME_RE = /(^|\/)[\w.-]*(icon|logo|badge|illustration|shield|artwork|graphic|background)[\w.-]*\.(tsx|jsx)$/i;
 export const SVG_MARKUP_RE = /<(svg|path|rect|circle|ellipse|polygon|defs|mask)\b/i;
+// An icon set's folder. Measured on 205 repos (2026-09-30): 1,252 files freed
+// in 20 repos, every one an icon, a logo or a loader; none held state or a
+// click handler. teable fell 28 to 24: its 250 icons had padded the files
+// that the per-100-files rates divide by.
+export const ARTWORK_DIR_RE = /(^|\/)(icons?|logos?|illustrations?)\//i;
 // A picture drawn from the DOM (a shareable card, a receipt) is the same
 // medium: the tool reads the styling off the element (2026-09-17).
 export const RENDER_TO_IMAGE_RE = /ImageResponse|from ['"]satori['"]|from ['"]@react-pdf|next\/og|from ['"](?:html-to-image|html2canvas(?:-pro)?|dom-to-image(?:-more)?|modern-screenshot)['"]/;
@@ -115,6 +122,15 @@ export const RENDERER_PATH_RE = /(^|\/)(renderers?|scene|canvas)\/|renderElement
 export const svgHeavy = (text) =>
   (text.match(/<(?:svg|path|rect|circle|ellipse|polygon|mask|defs)\b/g) ?? []).length >= 15;
 
+/**
+ * Whether a file is a drawing kept in an icons, logos or illustrations folder.
+ * The duplicate finder uses it: a Switch icon is not a second Switch component
+ * (teable, 2026-09-30). The folder, not the name: two files called Logo or
+ * Badge are two versions of one thing (dub, cal.com), and not "mostly SVG": a
+ * demo page full of drawings still defines real Buttons (json-render).
+ */
+export const isDrawing = (file, text = '') => ARTWORK_DIR_RE.test(file) && SVG_MARKUP_RE.test(text);
+
 /**
  * Why this file is exempt from judgement, as a sentence, or null when it is
  * fair game. Needs the text as well as the name: the artwork exemption is
@@ -129,7 +145,7 @@ export function exemptReason(file, text = '', { email = null } = {}) {
   if (RENDERER_PATH_RE.test(file)) return 'a renderer draws pixels, so its colours are the picture rather than the interface';
   if (OG_ROUTE_RE.test(file) || RENDER_TO_IMAGE_RE.test(text)) return 'a render-to-image surface accepts nothing but inline styling, so there is no on-system way to write one';
   if (svgHeavy(text)) return 'the file is mostly drawing rather than styling';
-  if (ARTWORK_NAME_RE.test(file) && SVG_MARKUP_RE.test(text)) return 'the colours belong to the artwork, not to the interface';
+  if ((ARTWORK_NAME_RE.test(file) || ARTWORK_DIR_RE.test(file)) && SVG_MARKUP_RE.test(text)) return 'the colours belong to the artwork, not to the interface';
   return null;
 }
 

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

@@ -53,7 +53,7 @@ export { isPageFile, looksLikeJSXFile, componentNamesIn } from '../harvest/compo
 
 // The files no checker should judge. Exported so a guard reads the same list
 // as the engine rather than keeping a copy that drifts.
-export { EMAIL_PRINT_RE, ARTWORK_NAME_RE, SVG_MARKUP_RE, exemptReason, isEmail } from './exempt.mjs';
+export { EMAIL_PRINT_RE, ARTWORK_NAME_RE, ARTWORK_DIR_RE, SVG_MARKUP_RE, exemptReason, isEmail, isDrawing } from './exempt.mjs';
 // !important as the medium (7.5): a widget stylesheet that must beat its host
 // page, and a selector aimed at a library's own class names. The guard reads
 // the same patterns, so the two checkers agree about the same declaration.

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.2.3';
+export const VERSION = '9.2.5';
 // 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/mcp/engine.mjs

@@ -14,7 +14,7 @@ import { extractStyling } from '../harvest/tokens.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 { exemptReason, isDrawing, SVG_MARKUP_RE } from '../lib/exempt.mjs';
 import { extraDeclarations, fontDeclarations } from '../lib/declarations.mjs';
 import { typefaceOf, GENERIC_FONTS } from '../lib/typefaces.mjs';
 import { kitPaintFindings } from '../lib/kitpaint.mjs';
@@ -94,7 +94,7 @@ 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);
+    const existing = duplicateCopies({ name, file: file ?? '', isPage: !!file && isPageFile(file), drawing: isDrawing(file ?? '', text), draws: SVG_MARKUP_RE.test(text) }, 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;