roast-my-design-system 9.3.1 → 9.3.3

package/README.md

@@ -133,20 +133,20 @@ Eleven reports, hosted exactly as the tool writes them. Every number determinist
 - **[Metabase](https://gregkozakiewicz.github.io/roast-my-design-system/examples/metabase-mantine.html)** (Mantine): its own wrapper over Mantine counts as the kit, so 2,679 files are read instead of 392; nothing written onto components, 2 spacings per 100 kit files. Score 47.
 - **[SigNoz](https://gregkozakiewicz.github.io/roast-my-design-system/examples/signoz-antd.html)** (Ant Design): 2 colours and 7 spacings per 100 kit files written in style objects where a token exists. Score 51.
 - **[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.
+- **[vercel/ai-chatbot](https://gregkozakiewicz.github.io/roast-my-design-system/examples/vercel-ai-chatbot.html)** (shadcn install): 71 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, 21 duplicated components, and the chart-palette gap named. Score 20.
+- **[dubinc/dub](https://gregkozakiewicz.github.io/roast-my-design-system/examples/dubinc-dub.html)**: 642 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.6)
+![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.3.3)
 
 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.6)
+![The diagnosis report in light mode](assets/report-light-hero.png?v=9.3.3)
 
 ## Why the numbers hold
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "9.3.1",
+  "version": "9.3.3",
   "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/tokens.mjs

@@ -8,7 +8,7 @@
  */
 import { existsSync } from 'node:fs';
 import {
-  isEmail, EMAIL_KIT_RE, ARTWORK_NAME_RE, foreignStylesheet, RENDER_TO_IMAGE_RE, OG_ROUTE_RE, RENDERER_PATH_RE, CRASH_PAGE_RE, svgHeavy, exemptReason, isLibraryClass, WIDGET_CSS_RE, WIDGET_CONFIG_RE,
+  isEmail, foreignStylesheet, CRASH_PAGE_RE, exemptReason, isLibraryClass, WIDGET_CSS_RE, WIDGET_CONFIG_RE,
 } from '../lib/exempt.mjs';
 import { join } from 'node:path';
 import { canonical, parseColor } from '../lib/color.mjs';
@@ -25,7 +25,10 @@ class Tally {
     e.count++;
     e.files.set(file, (e.files.get(file) ?? 0) + 1);
   }
-  toJSON(limitFiles = 5) {
+  // `every` keeps the whole per-file tally beside the capped list shown in
+  // the report, for a caller that has to split the count by folder exactly
+  // (profiles/splitArbitrary: installed code against the team's own).
+  toJSON(limitFiles = 5, { every = false } = {}) {
     return [...this.map.values()]
       .sort((a, b) => b.count - a.count)
       .map((e) => ({
@@ -33,6 +36,7 @@ class Tally {
         count: e.count,
         files: [...e.files.entries()].sort((a, b) => b[1] - a[1]).slice(0, limitFiles)
           .map(([file, count]) => ({ file, count })),
+        ...(every ? { every: [...e.files.entries()].map(([file, count]) => ({ file, count })) } : {}),
       }));
   }
 }
@@ -500,7 +504,6 @@ export function harvestTokens(root, styleFiles, codeFiles, { email = null } = {}
   // reason to discredit the whole report.
   // Email, artwork, mostly-SVG files and pixel renderers: all imported from
   // lib/exempt.mjs, the one list every checker reads.
-  const ARTWORK_RE = ARTWORK_NAME_RE;
   // every file a check skipped, with the reason, so the report can name them
   const exemptFiles = [];
   const skip = (f, src) => { const r = exemptReason(f, src, { email }); if (r) exemptFiles.push({ file: f, reason: r }); return true; };
@@ -566,15 +569,14 @@ export function harvestTokens(root, styleFiles, codeFiles, { email = null } = {}
       paletteFiles.add(f);
       for (const m of src.matchAll(HEX_RE)) tokenDefined.add(normalizeHex(m[0]));
     }
-    if (ARTWORK_RE.test(f) || RENDERER_PATH_RE.test(f) || svgHeavy(src)) { skip(f, src); continue; }
-    // A render-to-image surface (OG card, PDF invoice) is artwork drawn with
-    // code: its colours are the picture's, not the product's palette. Until
-    // 5.10.0 they were the only "strays" a clean shadcn repo had, and they
-    // triggered the "every single one is hardcoded" banner on it.
-    const renderToImage = RENDER_TO_IMAGE_RE.test(src) || OG_ROUTE_RE.test(f);
-    if (renderToImage) { skip(f, src); continue; }
-    // an email written with an email kit, wherever it lives (react-email)
-    if (EMAIL_KIT_RE.test(src)) { skip(f, src); continue; }
+    // Artwork, renderers, render-to-image surfaces (OG cards, PDF invoices),
+    // pages a headless browser prints, emails written with a kit: one rule,
+    // lib/exempt.mjs, the same answer the live checks and the guard give.
+    // Until 9.3.3 this counter kept its own list, and the two had drifted: a
+    // file named Badge or IconButton walked free here on its name alone
+    // (2,321 files in 173 repos) while an icon in an icons folder was
+    // counted here and exempt everywhere else (likec4's 12,203 icon colours).
+    if (exemptReason(f, src, { email })) { skip(f, src); continue; }
 
     // Tailwind classes
     for (const cls of classStrings(src)) {
@@ -600,7 +602,7 @@ export function harvestTokens(root, styleFiles, codeFiles, { email = null } = {}
     // length inside them is still a hardcoded value — harvest those from every
     // non-trivial block; count only the all-literal blocks.
     const allBlocks = inlineStyleBlocks(src).filter((b) => !TRIVIAL_INLINE_RE.test(b.trim()));
-    const staticBlocks = renderToImage ? [] : allBlocks.filter(isStaticInline);
+    const staticBlocks = allBlocks.filter(isStaticInline);
     if (staticBlocks.length) {
       inlineStyleCount += staticBlocks.length;
       inlineStyleFiles.set(f, (inlineStyleFiles.get(f) ?? 0) + staticBlocks.length);
@@ -807,7 +809,7 @@ export function harvestTokens(root, styleFiles, codeFiles, { email = null } = {}
       spacing: twSpacing.toJSON(),
       radii: twRadii.toJSON(),
       textSizes: twTextSizes.toJSON(),
-      arbitrary: twArbitrary.toJSON(),
+      arbitrary: twArbitrary.toJSON(5, { every: true }),
     },
     important: {
       // aimed at a library's own class names: kept out, named at the top

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

@@ -4,7 +4,7 @@
  * stylesheets of any flavor, and config — not just a happy-path shadcn layout.
  */
 import { CATALOGUE } from '../profiles/shadcn-data.mjs';
-import { emailContextOf } from '../lib/exempt.mjs';
+import { emailContextOf, printedFilesOf } from '../lib/exempt.mjs';
 import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join, relative, extname } from 'node:path';
 
@@ -183,6 +183,9 @@ export function walkRepo(root, maxDepth = 14, exclusions = null, readAnyway = ne
   // where the repo keeps its emails, read once here so every checker that
   // is handed the walk judges an email the same way (lib/exempt.mjs)
   files.email = emailContextOf(files, (f) => readSource(join(root, f)));
+  // and the files a headless browser prints to a PDF, which ride in the same
+  // context so every checker that honours the email rule honours this too
+  files.email.printed = printedFilesOf(files, (f) => readSource(join(root, f)));
   return files;
 }
 

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

@@ -116,6 +116,73 @@ export const ARTWORK_DIR_RE = /(^|\/)(icons?|logos?|illustrations?)\//i;
 // 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)['"]/;
 export const OG_ROUTE_RE = /(^|\/)api\/og\//;
+
+// Printed by a headless browser: React turned into HTML (renderToStaticMarkup)
+// and handed to puppeteer or playwright for a PDF or a screenshot. The page
+// loads none of the app's stylesheets, so its styling is written inline, like
+// an email's. The templates carry no marker of their own; the file that
+// prints them does (rybbit's PDF reports: 31 of its 52 inline styles, score
+// 40 against 50 without them). Found in 1 of 205 repos (2026-09-30), and
+// nothing else has that shape: a file that renders React to HTML and drives
+// a headless browser is always making a picture or a PDF.
+const HEADLESS_DEP_RE = /^(?:puppeteer(?:-core)?|playwright(?:-core)?|@sparticuz\/chromium|chrome-aws-lambda)$/;
+const HEADLESS_IMPORT_RE = /(?:from\s+|require\(\s*|import\(\s*)['"](?:puppeteer(?:-core)?|playwright(?:-core)?|@sparticuz\/chromium|chrome-aws-lambda)['"]/;
+const SSR_RENDER_RE = /\brenderTo(?:StaticMarkup|String|StaticNodeStream)\s*\(/;
+const REL_IMPORT_RE = /(?:from\s+|import\(\s*)['"](\.{1,2}\/[^'"]+)['"]/g;
+
+/** A relative import, resolved against the walk's files, or null. */
+function resolveRelative(fromDir, spec, code) {
+  const parts = fromDir ? fromDir.split('/') : [];
+  for (const s of spec.split('/')) {
+    if (s === '.' || s === '') continue;
+    if (s === '..') parts.pop(); else parts.push(s);
+  }
+  const p = parts.join('/');
+  const stem = p.replace(/\.[cm]?[jt]sx?$/, '');
+  const exts = ['.tsx', '.ts', '.jsx', '.js'];
+  for (const c of [p, ...exts.map((e) => stem + e), ...exts.map((e) => `${stem}/index${e}`)]) if (code.has(c)) return c;
+  return null;
+}
+
+/**
+ * The component files a headless browser prints, for the exemption context.
+ * Only packages with a headless browser among their runtime dependencies are
+ * read (a test setup lists it as a devDependency), and only the printer's own
+ * folder is followed: a shared Button it imports from elsewhere stays judged.
+ * @param files  the walk's { code, other } (repo-relative paths)
+ * @param read   (file) => text or null
+ */
+export function printedFilesOf(files, read) {
+  const homes = [];
+  for (const f of (files.other ?? []).filter((x) => base(x) === 'package.json')) {
+    let pkg; try { pkg = JSON.parse(read(f) ?? ''); } catch { continue; }
+    if (Object.keys(pkg?.dependencies ?? {}).some((d) => HEADLESS_DEP_RE.test(d))) homes.push(dir(f));
+  }
+  if (!homes.length) return [];
+  const code = new Set(files.code ?? []);
+  const under = (f, h) => h === '' || f.startsWith(`${h}/`);
+  const printed = new Set();
+  for (const f of files.code ?? []) {
+    if (!/\.[cm]?[jt]sx?$/.test(f) || !homes.some((h) => under(f, h))) continue;
+    const text = read(f) ?? '';
+    if (!HEADLESS_IMPORT_RE.test(text) || !SSR_RENDER_RE.test(text)) continue;
+    if (/\.(tsx|jsx)$/.test(f)) printed.add(f);
+    const home = dir(f);
+    const seen = new Set([f]);
+    const queue = [[f, text]];
+    while (queue.length) {
+      const [from, src] = queue.shift();
+      for (const m of src.matchAll(REL_IMPORT_RE)) {
+        const target = resolveRelative(dir(from), m[1], code);
+        if (!target || seen.has(target) || !under(target, home)) continue;
+        seen.add(target);
+        if (/\.(tsx|jsx)$/.test(target)) printed.add(target);
+        queue.push([target, read(target) ?? '']);
+      }
+    }
+  }
+  return [...printed].sort();
+}
 export const RENDERER_PATH_RE = /(^|\/)(renderers?|scene|canvas)\/|renderElement|DebugCanvas/i;
 
 /** Mostly drawing rather than styling, whatever the file is called. */
@@ -144,6 +211,7 @@ export function exemptReason(file, text = '', { email = null } = {}) {
   if (CRASH_PAGE_RE.test(file)) return 'the crash page replaces the root layout, so the stylesheet never loads there and its styling has to be inline';
   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 (email?.printed?.includes(file)) return 'pages a headless browser prints to a PDF or an image load none of the app\'s stylesheets, so their styling has to be inline';
   if (svgHeavy(text)) return 'the file is mostly drawing rather than styling';
   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

@@ -17,7 +17,7 @@ export { designGaps } from './gaps.mjs';
 import { decideProfile, profileOf, installedDirs } from '../profiles/index.mjs';
 import { KITS } from '../profiles/kit-common.mjs';
 import { kitPaintFindings } from './kitpaint.mjs';
-import { PALETTE_CLASS_RE, blankComments } from '../harvest/paint.mjs';
+import { PALETTE_CLASS_RE, DEMO_PATH_RE, blankComments } from '../harvest/paint.mjs';
 import { harvestTokens, extractStyling, normalizeHex, isGrey } from '../harvest/tokens.mjs';
 import { harvestComponents, definedComponents, tsconfigAliases } from '../harvest/components.mjs';
 import { findDuplicates } from '../harvest/duplicates.mjs';
@@ -63,7 +63,10 @@ export { WIDGET_CSS_RE, WIDGET_CONFIG_RE, LIBRARY_CLASS_RE, isLibraryClass } fro
 // blankComments (8.4.5) is what the report and the live checks run on a file
 // before matching, so a class named in a comment paints nothing; a guard that
 // matches the raw text counts it, and disagrees with the report.
-export { PALETTE_CLASS_RE, blankComments };
+// DEMO_PATH_RE (9.3.2) is the folders the palette count leaves out, stories,
+// examples and demos: a guard that skips them flags palette classes in the
+// same files the report counts.
+export { PALETTE_CLASS_RE, DEMO_PATH_RE, blankComments };
 // A product built on a kit (MUI, Mantine, Chakra UI, Ant Design), 8.4.6: a
 // colour or a pixel size written onto a kit component where the theme has a
 // value. kitPaintFindings(fileText, system.profile.kit, { file }) returns the

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.3.1';
+export const VERSION = '9.3.3';
 // 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

@@ -188,8 +188,11 @@ export function validateContent(content, k) {
   // (editing them is the intended use) and a demo folder is not own code,
   // exactly the files the tile leaves out.
   const inShadcnDoors = (f) => !!f && k.shadcn.doors.some((d) => f === d || f.startsWith(`${d}/`));
-  const paletteRule = k.tailwind ? 'tailwind'
-    : k.shadcn && !(file && (inShadcnDoors(file) || DEMO_PATH_RE.test(file))) ? 'shadcn'
+  // A demo folder is left out on a Tailwind theme too: the report's tile never
+  // counted one, and the live check flagged it (2026-09-30).
+  const demo = !!file && DEMO_PATH_RE.test(file);
+  const paletteRule = k.tailwind ? (demo ? null : 'tailwind')
+    : k.shadcn && !(file && (inShadcnDoors(file) || demo)) ? 'shadcn'
     : null;
   if (paletteRule && !css) {
     const tw = k.tailwind ?? {};

package/skills/roast-my-design-system/scripts/profiles/index.mjs

@@ -197,14 +197,18 @@ export function splitArbitrary(entries, dirs) {
   const installedValues = new Map();
   let installedUses = 0;
   for (const e of entries) {
-    const ownFiles = (e.files ?? []).filter((f) => !underAny(f.file, dirs));
-    const instFiles = (e.files ?? []).filter((f) => underAny(f.file, dirs));
-    const instCount = instFiles.reduce((s, f) => s + f.count, 0);
+    // the whole per-file tally when the harvest kept one (every), else the
+    // capped list: a use in a file that fell off the list of five was counted
+    // as the team's own, so ai-chatbot's installed badge put one of shadcn's
+    // [3px] values in the headline (2026-09-30)
+    const all = e.every ?? e.files ?? [];
+    const ownFiles = all.filter((f) => !underAny(f.file, dirs)).sort((a, b) => b.count - a.count).slice(0, 5);
+    const instCount = all.filter((f) => underAny(f.file, dirs)).reduce((s, f) => s + f.count, 0);
     if (instCount) { installedUses += instCount; installedValues.set(e.value, (installedValues.get(e.value) ?? 0) + instCount); }
-    // the file list under an entry is capped, so own is the remainder of the
-    // entry's total, never a sum of the files that happened to be listed
+    // own is the remainder of the entry's total, never a sum of the files
+    // that happened to be listed
     const ownCount = e.count - instCount;
-    if (ownCount > 0) own.push({ ...e, count: ownCount, files: ownFiles });
+    if (ownCount > 0) { const { every, ...rest } = e; own.push({ ...rest, count: ownCount, files: ownFiles }); }
   }
   own.sort((a, b) => b.count - a.count);
   const values = [...installedValues.entries()].sort((a, b) => b[1] - a[1]).map(([value, count]) => ({ value, count }));