roast-my-design-system 8.1.0 → 8.2.0

package/README.md

@@ -1,4 +1,4 @@
-<img src="https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/roaster_logo_300px.png?v=8.0.0" width="72" alt="roast-my-design-system">
+<img src="https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/roster_logo_v1.png?v=8.2.0" width="100" alt="roast-my-design-system">
 
 # roast-my-design-system
 
@@ -149,6 +149,51 @@ The loop: context before building, find while building, validate before saving,
 
 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 (`12px` is `p: 3` on a 4px MUI theme), and `roast_validate` and `roast_review` flag a colour or a pixel size written onto a kit component where the theme has a value. On a Tailwind theme they flag a palette class such as `text-gray-500` where the theme names a colour of that kind.
 
+### What a session looks like
+
+A real exchange against [Unleash](https://github.com/Unleash/unleash), an MUI product that scores 64/100. The agent was asked to add a small usage hint to a feature page. Every answer is the server's own text, unedited.
+
+Before writing anything, the agent calls `roast_get_context`:
+
+```
+KIT: MUI (1109 files import it, the theme is read 6162x). A colour, a spacing step or a radius is decided in frontend/src/themes/dark-theme.ts. On a component, read it: sx paths (color: 'text.secondary', p: 2) or theme.palette / theme.spacing() in styled().
+  43 colours are already written onto components (#6c65e5, #f1f0fc, #302e42); do not add one.
+USE THESE, DO NOT REBUILD THEM:
+  <Dialogue> from frontend/src/component/common/Dialogue/Dialogue.tsx (97x)
+  <TextCell> from frontend/src/component/common/Table/cells/TextCell/TextCell.tsx (96x)
+  <PageContent> from frontend/src/component/common/PageContent/PageContent.tsx (84x)
+DUPLICATES, DO NOT MAKE IT WORSE:
+  <StyledSuccessIcon> exists in 6 places; match what the surrounding code imports, never create another.
+SPACING: Use spacing steps (p: 2), not pixels. 17 pixel sizes are already written onto components; do not add one.
+TYPE: Sen. No new typefaces, no hand-declared font stacks.
+Before finishing: call roast_validate on what you wrote, then roast_review.
+```
+
+It has a grey in hand and a padding in mind, so `roast_find_token` twice:
+
+```
+#6b7280 → Nearest token: #607d8b, 11 channel steps from #6b7280. Unless the difference is a deliberate decision, use the token.
+12px    → 12px is between steps 1 (8px) and 2 (16px) on the default theme. If the design needs 12px exactly, keep it with a comment; otherwise use the nearest step in sx.
+```
+
+It writes a first draft anyway and runs `roast_validate` before saving:
+
+```
+2 findings:
+✕ L5 Colour #6b7280 written onto an MUI component, and the theme has no such colour.
+   Fix: Add it to the theme once (frontend/src/themes/dark-theme.ts), then read it there. On an MUI component, point at it: color: 'text.secondary' in sx, or theme.palette.primary.main in a styled() call.
+✕ L5 Pixel size p: 12px on an MUI component.
+   Fix: 12px is between steps 1 (8px) and 2 (16px) on the default theme. If the design needs 12px exactly, keep it with a comment; otherwise use the nearest step in sx.
+```
+
+Second draft: `color: 'text.secondary'`, `p: 1.5`, the radius read from the theme. `roast_validate` again:
+
+```
+No measured violations found. Checked: hardcoded colours vs the token set, near-identical colour twins, off-scale spacing, off-scale radii, font sizes and shadows, typefaces outside the system, arbitrary bracket values, static inline style blocks, !important, duplicate component definitions, colours and pixel sizes written onto kit components where the theme has a value.
+```
+
+Four calls, under 800 tokens in total, and the new component reads the theme instead of adding colour number 44. `roast_review` then checks the whole diff the same way before the agent says it is done.
+
 When the goal is fixing the system rather than building on it, the `roast-fix` prompt serves the top Where-to-start move from a fresh scan. It is a ready-made fix prompt, byte-identical to the report's copy buttons. Fix it, ask again, and the next move has risen to the top: the scan is the progress bar. Pass `move: 2` to jump the queue.
 
 To use it in Claude Code, type `/mcp__roast__roast-fix` in the chat. MCP prompts appear as slash commands, named after whatever you registered the server as, and the `/` autocomplete menu lists them too. Add the move number to jump the queue: `/mcp__roast__roast-fix 2`. Other clients list server prompts in their own prompt picker; wherever `roast-build-ui` and `roast-review-ui` show up, `roast-fix` sits beside them.
@@ -250,6 +295,36 @@ You get the roast in chat plus `design-system-roast.html` at your repo root: a s
 
 After the roast, the skill also offers to write `design-system-rules.md` to disk and merge it into your CLAUDE.md, `.cursor/rules` or AGENTS.md.
 
+### Three prompts to try
+
+Type any of these in Claude Code, inside the repo:
+
+```
+Roast my design system.
+```
+
+```
+How bad is my CSS? Scan this repo and show me the receipts.
+```
+
+With the MCP server connected (see [Live answers over MCP](#live-answers-over-mcp)):
+
+```
+Is there already a Button component in this repo, and which one should I use?
+```
+
+## Troubleshooting
+
+- **"Command not found" or the plugin will not install.** Update Claude Code; the plugin marketplace needs a recent version. The manual install above works on any version.
+- **"Nothing to roast" or a near-empty report.** The scan found almost no colours or spacing. The styling probably lives in another repo, a CDN or an installed package. Run it from the repo that holds the styles.
+- **A score that looks wrong.** Check the header of the report: it names how the repo was read (product, library, shadcn, a kit, a Tailwind theme) and every folder that was left out. Scope the scan with a `.roastignore` file or `--exclude` if a playground or an old app is blurring the numbers.
+- **The report did not open.** It is written to `design-system-roast.html` at the repo root. Open it in any browser; it needs no server and makes no requests.
+- **The MCP server does not appear.** Restart the client after adding it. In Claude Code, `claude mcp list` shows whether it connected. Everything it needs is Node 18 or newer.
+
+## Support
+
+Bugs and questions go to [GitHub Issues](https://github.com/gregkozakiewicz/roast-my-design-system/issues). Everything else reaches Greg through [gregkozakiewicz.com](https://gregkozakiewicz.com).
+
 ## Live examples
 
 7 real roasts of public repos, hosted as-is (the same self-contained HTML the skill generates), spanning React, Stencil and Lit:
@@ -288,7 +363,7 @@ Yes, the median repo is already a mess. That's the point.
 
 MIT. The code is yours to fork, modify and redistribute; the copyright notice travels with it.
 
-Building your own report, summary or audit from this tool's scores, counts or benchmark comparisons? Keep one line in it: *Built with [roast-my-design-system](https://github.com/gregkozakiewicz/roast-my-design-system) by Greg Kozakiewicz*. The scan data asks the same of AI agents that consume it.
+Building your own report, summary or audit from this tool's scores, counts or benchmark comparisons? Keep one line in it: *Built with [roast-my-design-system](https://github.com/gregkozakiewicz/roast-my-design-system) by Greg Kozakiewicz*. The skill asks the same of an AI agent that writes such a document from the scan.
 
 **roast-my-design-system**™ and the GK mark are trademarks of Greg Kozakiewicz. Forking is welcome, republishing under this name is not: see [brand and attribution](https://gregkozakiewicz.github.io/roast-my-design-system/brand.html).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "8.1.0",
+  "version": "8.2.0",
   "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

@@ -51,9 +51,18 @@ const FUNC_COLOR_RE = /\b(?:rgba?|hsla?|oklch|oklab|lab|lch)\(\s*[^)]{1,80}\)|\b
 // scanned as 0 tokens until 5.10.0. Recognised here and normalised to hsl()
 // so it flows through greys, twins and the rest like any other colour.
 const HSL_TRIPLET_RE = /^\s*(-?\d+(?:\.\d+)?)(?:deg)?\s+(\d+(?:\.\d+)?)%\s+(\d+(?:\.\d+)?)%(?:\s*\/\s*(\d+(?:\.\d+)?%?))?\s*$/;
+// The same convention with RGB channels: --bg-default: 255 255 255, wrapped
+// later as rgb(var(--bg-default) / <alpha-value>). dub keeps its whole theme
+// this way, and until 8.2.0 it scanned as a repo without a token file, so an
+// avatar colour list took the title (2026-09-18). Three integers 0-255, and
+// nothing else, so a bare "16px" or "1 2" never reads as a colour.
+const RGB_TRIPLET_RE = /^\s*(\d{1,3})\s+(\d{1,3})\s+(\d{1,3})(?:\s*\/\s*(\d+(?:\.\d+)?%?))?\s*$/;
 export const tripletToHsl = (v) => {
   const m = HSL_TRIPLET_RE.exec(v);
-  return m ? `hsl(${m[1]} ${m[2]}% ${m[3]}%${m[4] ? ` / ${m[4]}` : ''})` : null;
+  if (m) return `hsl(${m[1]} ${m[2]}% ${m[3]}%${m[4] ? ` / ${m[4]}` : ''})`;
+  const r = RGB_TRIPLET_RE.exec(v);
+  if (r && [r[1], r[2], r[3]].every((n) => Number(n) <= 255)) return `rgb(${r[1]} ${r[2]} ${r[3]}${r[4] ? ` / ${r[4]}` : ''})`;
+  return null;
 };
 // Loose hex in CODE (not in a style block, a class string or a stylesheet) is
 // ambiguous: #RGBA shorthand is legal CSS but vanishingly rare in code, while
@@ -284,6 +293,16 @@ export function extractStyling(src, { css = false } = {}) {
  * Returns { colors, greys, spacing, radii, fontSizes, fontFamilies, shadows,
  *           tailwind: {...same buckets from tw classes...}, inlineStyleCount }
  */
+/** Share of a code file's quoted colours that sit inside an array holding 8 or more of them. */
+export function colourListShare(src) {
+  const QUOTED = /(['"`])(?:#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})|(?:rgba?|hsla?)\([^)'"`]*\))\1/g;
+  const all = (src.match(QUOTED) ?? []).length;
+  if (!all) return 0;
+  let inLists = 0;
+  for (const a of src.match(/\[[^[\]]*\]/g) ?? []) { const n = (a.match(QUOTED) ?? []).length; if (n >= 8) inLists += n; }
+  return inLists / all;
+}
+
 export function harvestTokens(root, styleFiles, codeFiles) {
   const colors = new Tally(), spacing = new Tally(), radii = new Tally(),
         fontSizes = new Tally(), fontFamilies = new Tally(), shadows = new Tally();
@@ -349,6 +368,7 @@ export function harvestTokens(root, styleFiles, codeFiles) {
     return owner;
   };
   const paletteFiles = 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)
 
@@ -468,6 +488,7 @@ export function harvestTokens(root, styleFiles, codeFiles) {
     let src = readSource(join(root, f));
     if (src === null) continue;
     for (const m of src.matchAll(/[A-Za-z_][\w-]+/g)) ownClasses.add(m[0]);
+    listShare.set(f, colourListShare(src));
 
     // CSS-in-tagged-templates (Lit css``, styled-components css``) IS the
     // stylesheet in those worlds: Shoelace keeps its entire component styling
@@ -639,11 +660,19 @@ export function harvestTokens(root, styleFiles, codeFiles) {
       else straysIn.set(f, (straysIn.get(f) ?? 0) + 1);
     }
   }
+  // A code palette whose colours sit mostly inside arrays is a list handed to
+  // something (dub's avatar pairs, plane's chart series), not the vocabulary
+  // an agent should add a colour to. It keeps its palette status for the
+  // counts, but it does not take the token-file title while any other
+  // candidate qualifies. Probe, 72 repos with a code token file (2026-09-18):
+  // 10 switch, 4 have nothing else and keep it. A Tailwind config or a
+  // 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]);
   const tokenFile = [...candidates]
-    .map((f) => ({ f, tokens: tokenColoursIn.get(f) ?? 0, strays: straysIn.get(f) ?? 0 }))
+    .map((f) => ({ f, tokens: tokenColoursIn.get(f) ?? 0, strays: straysIn.get(f) ?? 0, list: isList(f) ? 1 : 0 }))
     .filter((c) => c.tokens >= 3)
-    .sort((a, b) => b.tokens - a.tokens || a.strays - b.strays)[0]?.f
+    .sort((a, b) => a.list - b.list || b.tokens - a.tokens || a.strays - b.strays)[0]?.f
     ?? [...tokenDefsPerFile.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
 
   // Token namespace: the brand stem the repo's custom properties answer to

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

@@ -184,10 +184,15 @@ export function canonical(raw) {
   const v = String(raw).trim();
   if (!v || /var\(|\$\{|calc\(/.test(v)) return null;
   const t = HSL_TRIPLET.exec(v);
-  const c = parseColor(t ? `hsl(${t[1]} ${t[2]}% ${t[3]}%)` : v.replace(/\s+/g, ' ').toLowerCase());
+  const r = t ? null : RGB_TRIPLET.exec(v);
+  const c = parseColor(t ? `hsl(${t[1]} ${t[2]}% ${t[3]}%)`
+    : r && [r[1], r[2], r[3]].every((n) => Number(n) <= 255) ? `rgb(${r[1]} ${r[2]} ${r[3]})`
+      : v.replace(/\s+/g, ' ').toLowerCase());
   if (!c) return null;
   return [c.r, c.g, c.b].map((x) => Math.round(x)).join(',') + ',' + Math.round(c.a * 100);
 }
 
 const HSL_TRIPLET =
   /^\s*(-?\d+(?:\.\d+)?)(?:deg)?\s+(\d+(?:\.\d+)?)%\s+(\d+(?:\.\d+)?)%(?:\s*\/\s*(\d+(?:\.\d+)?%?))?\s*$/;
+// bare RGB channels (dub: --bg-default: 255 255 255), see harvest/tokens.mjs
+const RGB_TRIPLET = /^\s*(\d{1,3})\s+(\d{1,3})\s+(\d{1,3})(?:\s*\/\s*\d+(?:\.\d+)?%?)?\s*$/;

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

@@ -206,8 +206,13 @@ export function countKitPaint(root, codeFiles, { importRe: kitImportRe, themeRe,
     top: b.top.sort((a, c) => c.count - a.count).slice(0, 10),
     samples: [...b.samples.entries()].sort((a, c) => c[1] - a[1]).slice(0, 12).map(([value, count]) => ({ value, count })),
   });
-  // the theme a reader should open first: a theme-named path, then the most colours
-  const ranked = themeFiles.sort((a, b) => (THEME_NAME_RE.test(b.f) - THEME_NAME_RE.test(a.f)) || b.n - a.n).map((t) => t.f);
+  // the theme a reader should open first: not a component's own theme or a
+  // provider (Open-Assistant's Theme/components/Badge.ts and Metabase's
+  // ThemeProvider.tsx both outranked the root theme, 2026-09-18), then a
+  // theme-named path, then the most colours
+  const componentLevel = (f) => /(^|\/)(components?|providers?)\//i.test(f);
+  const ranked = themeFiles.sort((a, b) => (componentLevel(a.f) - componentLevel(b.f))
+    || (THEME_NAME_RE.test(b.f) - THEME_NAME_RE.test(a.f)) || b.n - a.n).map((t) => t.f);
   const colourOut = finish(colour);
   // a written colour the theme already holds: the move can say where it lives
   for (const s of colourOut.samples) if (themeValues.has(s.value)) s.inTheme = true;

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 = '8.1.0';
+export const VERSION = '8.2.0';
 // 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/knowledge.mjs

@@ -60,10 +60,13 @@ export function loadKnowledge(root) {
     const themeSet = new Set(kit.themeValues ?? []);
     tokens = {
       ...tokens,
-      tokenFile: tokens.tokenFile ?? kit.themeFiles[0] ?? null,
+      // the theme first: on a kit repo it is where a colour is decided, whatever
+      // stylesheet or palette file holds the most literals
+      tokenFile: kit.themeFiles[0] ?? tokens.tokenFile ?? null,
       colors: tokens.colors.map((c) => (themeSet.has(c.value) ? { ...c, isToken: true } : c)),
     };
-    for (const v of themeSet) if (!tokens.colors.some((c) => c.value === v)) tokens.colors.push({ value: v, count: 1, isToken: true });
+    // 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);
   const context = harvestContext(root);

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

@@ -28,29 +28,41 @@ const PROTOCOL = '2025-06-18';
 // ---------- tool + resource + prompt catalogue ----------
 // Descriptions are budgeted: every client loads them into every session, so
 // each one carries only what changes an agent's tool choice (5.0.1 trim).
+// Every tool is read-only and local: the annotations say so, so a client can
+// run them without a per-call prompt (directory policy, 2026-09-18).
 const TOOLS = [
   {
     name: 'roast_get_context',
+    title: 'Design system context',
+    annotations: { title: 'Design system context', readOnlyHint: true, destructiveHint: false, openWorldHint: false },
     description: 'Design-system context before writing UI in this repo: tokens or the kit theme (MUI, Mantine, Chakra, Ant Design, shadcn, a Tailwind theme), canonical components, duplicates, spacing and type rules, from a real scan. Optional path ("packages/ui") narrows the slice.',
     inputSchema: { type: 'object', properties: { path: { type: 'string', description: 'Repo-relative folder (optional)' } } },
   },
   {
     name: 'roast_find_component',
+    title: 'Find the canonical component',
+    annotations: { title: 'Find the canonical component', readOnlyHint: true, destructiveHint: false, openWorldHint: false },
     description: 'Find the canonical component for a name or intent ("icon button"). Returns import path, usage count and a real usage example, or an honest zero. Ties are reported, never guessed.',
     inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Component name or intent' } }, required: ['query'] },
   },
   {
     name: 'roast_find_token',
+    title: 'Snap a value to a token',
+    annotations: { title: 'Snap a value to a token', readOnlyHint: true, destructiveHint: false, openWorldHint: false },
     description: 'Snap a raw value (#111111, 13px) to this repo\'s nearest token, theme colour or spacing step, in the kit\'s own terms on a kit repo. Says so when no scale exists.',
     inputSchema: { type: 'object', properties: { value: { type: 'string', description: 'Colour or length value' } }, required: ['value'] },
   },
   {
     name: 'roast_validate',
+    title: 'Validate code before saving',
+    annotations: { title: 'Validate code before saving', readOnlyHint: true, destructiveHint: false, openWorldHint: false },
     description: 'Check code before saving: hardcoded colours, near-token twins, off-scale spacing, arbitrary brackets, inline styles, !important, duplicate components; on a kit repo, colours and pixel sizes written onto kit components where the theme has a value; on a Tailwind theme, palette classes. Findings name the fix.',
     inputSchema: { type: 'object', properties: { code: { type: 'string', description: 'The code to check' }, file: { type: 'string', description: 'Intended file path (optional)' } }, required: ['code'] },
   },
   {
     name: 'roast_review',
+    title: 'Review changed files',
+    annotations: { title: 'Review changed files', readOnlyHint: true, destructiveHint: false, openWorldHint: false },
     description: 'Review the working tree\'s changed files (git diff + untracked) against the design system. Reads the diff itself; send no code. Call before finishing UI work.',
     inputSchema: { type: 'object', properties: {} },
   },

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

@@ -96,8 +96,8 @@ export function getContext(k, { path = null } = {}) {
     text = assemble(nCanon, nDupes) + shortened();
   }
   if (text.length > CONTEXT_BUDGET) text = `${text.slice(0, text.lastIndexOf('\n', CONTEXT_BUDGET))}\n(trimmed to budget; ask roast_find_component / roast_find_token for specifics)`;
-  // Appended after the trim so it survives on every repo size.
-  text += '\nCREDIT: if you produce a report or document from this scan, include: Built with roast-my-design-system (https://github.com/gregkozakiewicz/roast-my-design-system) by Greg Kozakiewicz.';
+  // No credit line here (8.1.1): a tool answers the question and nothing
+  // else. Attribution lives on the report and in the skill's citation rule.
   return text;
 }