roast-my-design-system 3.7.1 → 3.9.0

package/README.md

@@ -7,6 +7,7 @@
 Run this skill on your codebase and get, in about a second:
 
 - **A health score you can defend in a meeting.** 0-100, deterministic, benchmarked against Ideal Design System norms, 30 scanned public repos and 10 reputable design systems (Primer, Polaris, Carbon, shadcn/ui…).
+- **Per-package scores for monorepos.** One blended number hides which package is the problem: `packages/ui` scores 80 while `apps/web` scores 40, and now you can see it.
 - **The receipts behind it.** Every colour and its near-identical twin, every spacing value, typeface, duplicated or never-imported component, inline style and !important, with real file paths, in one self-contained HTML report you can open, Slack or email.
 - **The first fixes ranked by payoff.** A "Where to start" list derived from your own numbers: keep the report as the audit, or hand it to Claude as the punch list for the fix.
 - **Rules that stop the mess coming back.** A generated `design-system-rules.md` for your CLAUDE.md or .cursor/rules: canonical components, your token file, known duplicates to avoid, so your AI agent follows your system instead of guessing at it.
@@ -24,15 +25,15 @@ Your AI agent (Claude, Cursor, Copilot) builds UI by imitating what's already in
 
 The full report for vercel/ai-chatbot, top to bottom:
 
-![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, three-yardstick tiles, palette forensics, spacing receipts, typography, offenders, duplicates, and the where-to-start close](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-full-dark.png?v=3.7.1)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, three-yardstick tiles, palette forensics, spacing receipts, typography, offenders, duplicates, and the where-to-start close](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-full-dark.png?v=3.9.0)
 
 The same report in light mode (one file, built-in toggle):
 
-![The diagnosis report in light mode](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-light-hero.png?v=3.7.1)
+![The diagnosis report in light mode](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-light-hero.png?v=3.9.0)
 
 ## What makes the numbers trustworthy
 
-- **Deterministic scanner, not AI sampling.** A zero-dependency Node script reads *every* file (a 5,000-file monorepo takes ~1.5s) and returns the same numbers every run. Claude narrates; it never counts.
+- **Deterministic scanner, not AI sampling.** A zero-dependency Node script reads *every* file (about a second on a normal repo, a few on a large monorepo) and returns the same numbers every run. Claude narrates; it never counts.
 - **Read-only.** Nothing in your repo is modified. The only outputs are a temp JSON and the HTML report.
 - **No network, no telemetry.** Everything runs locally. Nothing about your code leaves your machine.
 - **Honest exclusions.** Test files, Storybook stories, docs sites, example apps, SVG artwork, and email templates (which *must* inline styles) are excluded, so you can't discredit the numbers on a technicality.
@@ -132,4 +133,4 @@ MIT. The code is yours to fork, modify and redistribute; the copyright notice tr
 
 **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://pencilrebel.github.io/roast-my-design-system/brand.html).
 
-Built and designed by <a href="https://gregkozakiewicz.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark-dark.png?v=3.7.1"><img src="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark.png?v=3.7.1" height="15" alt="GK mark"></picture> Greg Kozakiewicz</a>.
+Built and designed by <a href="https://gregkozakiewicz.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark-dark.png?v=3.9.0"><img src="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark.png?v=3.9.0" height="15" alt="GK mark"></picture> Greg Kozakiewicz</a>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "3.7.1",
+  "version": "3.9.0",
   "description": "Roast your design system with real data. A deterministic, zero-dependency scanner that counts everything that betrays a design system, from colours and their near-identical twins to greys, spacing values, typefaces, duplicated and never-imported components, inline styles, !important and arbitrary Tailwind values, scores it 0-100 against Ideal Design System norms and a 30-repo benchmark, generates a shareable HTML diagnosis, and with --rules writes the agent rules file (CLAUDE.md, .cursor/rules) that stops the mess coming back.",
   "keywords": [
     "design-system",

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

@@ -36,7 +36,7 @@ const GK_MASK = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqa
 const GK_MARK = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAACXBIWXMAAAAAAAAAAQCEeRdzAAACPklEQVR4nOVWTYh5URR/PlJYEKV8LKwkZalsmI2dZmMnK8pKmaZ87JSanexEkayUhSxsZyfJNBQ7UYqVhSShfM+v/6mXmtU81+p/Frfze+/d3++ce88993Hcf2cikehZ1GazWafTPUVDLBZjLBQKnU6HMTVvcrl8Op3ebrdsNgsokUiYUVP4Pp/v9s96vd79cwZGK95sNkkgGAwC2u12lhrY3u12C/b1ei2TyV5eXjabjV6vZ6BBa51MJin8arUKWKlU4H99fSkUCo5JUQ2HQxJwuVzIYLVawcdIVSs8CQoNpMQ+Go0Aw+EwwXw+D+h2u4Vr0LRSqUSMqVQKsN1uE3Q4HEql8ng8BgIBTnDhqlSqxWIBuvP5bDAYLBbL5XIBHAwGeBuJRODvdjun0/nnPOjraDRK8TYaDcBMJkMwFosBfn9/E0wkEn9OgjYgnU6fTidQwAGcTCbw9/u9VqvFUYB/vV5RskajkRNcTiaTKR6PI9j5fE7xlstlPM/lcgTr9ToneJ/5oOB4PB70O8Tb7/f9fv9sNqPkXl9fhQsQ9f1ktVqNvUVCxA6ZRxsf5pMAxnsuVBSOwvv7+6Phk0PsBNn0OOLC9haLReqdvBL/wUNKNPnt7Q0LjeVutVqhUEij0TwU9W8BVA4JUEUul8tarcZGhpbIarWiSeA0HQ4Hkvn4+GB56VMvov6DA+z1eplR89btdsE+Ho9tNhv3jOv+8/MTFz06M3ypVMqMnTfcwPhn4djG/tue+Mf4RGom9gMt6lAx16huIwAAAABJRU5ErkJggg==';
 
 // Shown in the report footer; keep in step with plugin.json when releasing.
-const VERSION = '3.7.1';
+const VERSION = '3.9.0';
 
 // Report identity. The scan id is a stable digest of this scan's shape, salted
 // with the report namespace, so the same repo scanned twice reads the same and
@@ -280,14 +280,16 @@ const WARN_TOLERANCE = { exactDuplicates: 2, inlineStyles: 10, nearPairs: 2, imp
 // Absence rule also skipped for arbitrary values: zero brackets is discipline
 // (nine of ten reputable systems sit at 0, including Tailwind-native shadcn/ui).
 const NO_ABSENCE_RULE = new Set(['colors', 'greys', 'arbitrary']);
-function healthOf(metric, value) {
+function healthOf(metric, value, opts = {}) {
   const iv = ideal(metric);
   if (iv === null) return 'info';
   if (ZERO_IDEAL.has(metric)) {
     if (value === 0) return 'good';
     return value <= WARN_TOLERANCE[metric] ? 'warn' : 'bad';
   }
-  if (!NO_ABSENCE_RULE.has(metric) && value < Math.max(1, iv * 0.05)) return 'bad';
+  // "almost nothing found" reads as a missing design system for a whole repo,
+  // but a single package with no spacing values is just a small package.
+  if (!opts.noAbsence && !NO_ABSENCE_RULE.has(metric) && value < Math.max(1, iv * 0.05)) return 'bad';
   if (value <= iv) return 'good';
   const mv = median(metric);
   const warnCap = mv && mv > iv ? mv : iv * 1.5;
@@ -321,7 +323,7 @@ function tile(value, label, metric, fallbackTarget, healthValue = value) {
   const av = displayAvg(metric);
   if (av !== null) rows.push(row('Avg Design System', `${n(av)}${avgNote}`, av, value));
   if (rm !== null && (rm > 0 || ZERO_IDEAL.has(metric) || metric === 'arbitrary')) rows.push(row('Reputable systems', n(rm), rm, value));
-  return { num: n(value), label, health, rows };
+  return { num: n(value), label, health, rows, metric, healthValue };
 }
 const bigStats = [
   tile(colors.length, 'distinct colours', 'colors', 'a system needs ~24', tokenLed ? colorStrays : colors.length),
@@ -342,6 +344,42 @@ const healthScore = scoredTiles.length
   ? Math.round(scoredTiles.reduce((sum, s) => sum + SCORE_OF[s.health], 0) / scoredTiles.length)
   : null;
 
+// ---------- what a fix is worth ----------
+// The score is the average of the scored tiles, so moving one tile across a
+// band is worth an exact number of points: red to green 10, red to amber 5,
+// amber to green 5 (on nine tiles). Deltas are only claimed when a move
+// actually crosses a band — a cleanup that lands inside the same band is real
+// work worth zero points, and saying otherwise would be a lie.
+const TILE_COUNT = scoredTiles.length || 1;
+const scoreOfHealth = (hh) => SCORE_OF[hh] ?? 0;
+function bandPoints(metric, from, to) {
+  const a = healthOf(metric, from), b = healthOf(metric, to);
+  if (!(a in SCORE_OF) || !(b in SCORE_OF)) return 0;
+  return Math.round((scoreOfHealth(b) - scoreOfHealth(a)) / TILE_COUNT);
+}
+// The nearest number that moves this metric up a band, and what it pays.
+function nextBand(metric, value) {
+  const iv = ideal(metric);
+  if (iv === null) return null;
+  const cur = healthOf(metric, value);
+  if (cur === 'good') return null;
+  if (cur === 'warn') {
+    const target = ZERO_IDEAL.has(metric) ? 0 : iv;
+    return { target, gain: bandPoints(metric, value, target) };
+  }
+  const warnTarget = ZERO_IDEAL.has(metric) ? WARN_TOLERANCE[metric] : Math.min(median(metric) ?? iv * 1.5, iv * 1.5);
+  return { target: Math.round(warnTarget), gain: bandPoints(metric, value, Math.round(warnTarget)) };
+}
+// The score this repo would have with a set of metrics at new values.
+function projectedScore(applied) {
+  const scored = bigStats.filter((st) => st.health in SCORE_OF);
+  if (!scored.length) return healthScore;
+  return Math.round(scored.reduce((sum, st) => {
+    const v = applied.has(st.metric) ? applied.get(st.metric) : st.healthValue;
+    return sum + scoreOfHealth(healthOf(st.metric, v));
+  }, 0) / scored.length);
+}
+
 // A repo with essentially no colour/spacing signal most likely has no design
 // system in it at all; say that up front instead of quietly scoring zeros.
 const noSystemLikely = colors.length === 0 || (colors.length < 3 && spacingTotal === 0);
@@ -459,6 +497,20 @@ function duplicatesSection() {
     <div class="fams">${iconCard}${dupeCards}${famCards}</div></div>`;
 }
 
+// Scanned values get injected into style attributes below (a radius, a shadow,
+// a font size from someone else's repo). Allow only a conservative CSS charset
+// so a malformed or hostile value cannot break out of the attribute.
+const cssSafe = (v) => (typeof v === 'string' && /^[-#0-9a-z%.,()\s\/]+$/i.test(v) && !/[;{}<>"']/.test(v) ? v.trim() : null);
+// px equivalent of a length, for sorting and for rendering type at real size.
+function toPx(v) {
+  const m = /^(-?\d*\.?\d+)\s*(px|rem|em|pt)?$/i.exec(String(v).trim());
+  if (!m) return null;
+  const num = parseFloat(m[1]);
+  const unit = (m[2] ?? 'px').toLowerCase();
+  if (!Number.isFinite(num) || num <= 0) return null;
+  return unit === 'px' ? num : unit === 'pt' ? num * 1.333 : num * 16;
+}
+
 function typographySection() {
   if (!fontFamilies.length && !fontSizeTotal && !radiiTotal) return '';
   const mini = [
@@ -475,13 +527,59 @@ function typographySection() {
     .sort((a, b) => b.count - a.count).slice(0, 14);
   const receipts = (title, chips) => chips.length < 2 ? '' :
     `<div class="receipts">${eyebrow(title)}<div class="chips-row">${chips.map((c) => `<span class="vchip">${esc(String(c.label))} ×${c.count}</span>`).join('')}</div></div>`;
+
+  // ---------- specimens: the values rendered, not counted ----------
+  // Counting says "47 font sizes". Rendering them says it better: the eye
+  // finds the near-duplicates on its own, the way the grey ramp works.
+  const typeSpecimens = (() => {
+    const rows = (h.tokens.fontSizes ?? [])
+      .map((f) => ({ label: f.value, count: f.count, px: toPx(f.value) }))
+      .filter((f) => f.px && f.px >= 6 && f.px <= 200)
+      .sort((a, b) => b.px - a.px);
+    if (rows.length < 4) return '';
+    const shown = rows.slice(0, 16);
+    const capped = shown.some((r) => r.px > 52);
+    return `<div class="spec">${eyebrow(`the type scale, at its real sizes${capped ? ' · the largest are capped to fit' : ''} · how many of these are the same decision?`)}
+      <div class="spec-rows">${shown.map((r) => `
+        <div class="spec-type">
+          <span class="spec-val">${esc(r.label)} ×${r.count}</span>
+          <span class="spec-sample" style="font-size:${Math.min(r.px, 52)}px">Almost but not quite</span>
+        </div>`).join('')}</div>
+      ${rows.length > 16 ? `<div class="spec-more">and ${rows.length - 16} more</div>` : ''}</div>`;
+  })();
+
+  const radiiSpecimens = (() => {
+    const cells = (h.tokens.radii ?? [])
+      .map((r) => ({ label: r.value, count: r.count, css: cssSafe(r.value) }))
+      .filter((r) => r.css && !/^0$|^0px$/.test(r.css) && !/var\(|calc\(/i.test(r.css))
+      .slice(0, 14);
+    if (cells.length < 3) return '';
+    return `<div class="spec">${eyebrow(`the corners, drawn · ${n(radiiTotal)} radii in one interface`)}
+      <div class="spec-grid">${cells.map((r) => `
+        <div class="spec-cell"><div class="spec-box" style="border-radius:${r.css}"></div>
+        <span class="spec-cap">${esc(r.label)} ×${r.count}</span></div>`).join('')}</div></div>`;
+  })();
+
+  const shadowSpecimens = (() => {
+    const cells = (h.tokens.shadows ?? [])
+      .map((sh) => ({ label: sh.value, count: sh.count, css: cssSafe(sh.value) }))
+      .filter((sh) => sh.css && !/^(none|initial|inherit|unset|revert)$/i.test(sh.css) && !/var\(/i.test(sh.css))
+      .slice(0, 10);
+    if (cells.length < 2) return '';
+    const short = (v) => (v.length > 20 ? `${v.slice(0, 19)}…` : v);
+    return `<div class="spec">${eyebrow(`the elevations, cast${cells.length < shadows.length ? `, ${cells.length} of ${n(shadows.length)}` : ` · ${n(shadows.length)} shadow styles`} · on the light surface they were drawn for`)}
+      <div class="spec-grid spec-shadows">${cells.map((sh) => `
+        <div class="spec-cell"><div class="spec-card" style="box-shadow:${sh.css}"></div>
+        <span class="spec-cap" title="${esc(sh.label)}">${esc(short(sh.label))} ×${sh.count}</span></div>`).join('')}</div></div>`;
+  })();
   const fams = fontFamilies.slice(0, 8).map((f) =>
     `<div class="mini-card"><span class="mc-path">${esc(f.value.slice(0, 70))}</span><span class="pill${f.count > 2 ? ' pill-coral' : ' pill-mint'}">×${f.count}</span></div>`).join('');
   return `<section>
     ${sectionHead('Typography &amp; shape', '')}
     <div class="stats minis">${mini.map((s) => statTile(s)).join('')}</div>
-    ${receipts('the font sizes, by use', sizeChips)}
-    ${receipts('the radii, by use', radiiChips)}
+    ${typeSpecimens || receipts('the font sizes, by use', sizeChips)}
+    ${radiiSpecimens || receipts('the radii, by use', radiiChips)}
+    ${shadowSpecimens}
     ${fontFamilies.length > 1 ? `<div class="glass pad" style="margin-top:16px">${sectionHead(`${typefaces.length} typeface${typefaces.length === 1 ? '' : 's'}, declared ${fontFamilies.length} different ways`, 'every distinct declaration is a chance for the next one to be wrong')}<div class="fam-rows">${fams}</div></div>` : ''}
   </section>`;
 }
@@ -572,7 +670,7 @@ function giftSection() {
 
 function whereToStartSection() {
   const c = [];
-  if (agentFiles.length === 0) c.push({ score: 60, title: 'Write the agent rules file',
+  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.` });
   if (hardDupes.length > 0) {
     // Pick the pair with the strongest copy-paste evidence: sibling files in
@@ -588,10 +686,11 @@ function whereToStartSection() {
       return sc;
     };
     const d = [...hardDupes].sort((a, b) => strength(b) - strength(a))[0];
-    c.push({ score: 25 + hardDupes.length * 4, title: `Crown the canonical &lt;${esc(d.name)}&gt;`,
+    c.push({ score: 25 + hardDupes.length * 4, metric: 'exactDuplicates', after: hardDupes.length - 1,
+      title: `Crown the canonical &lt;${esc(d.name)}&gt;`,
       sub: `${hardDupes.length} component name${hardDupes.length > 1 ? 's have' : ' has'} competing implementations. Start with &lt;${esc(d.name)}&gt;: ${esc(d.files[0])} vs ${esc(d.files[1] ?? '')}. Decide which one is canonical, re-export it from one home, and rename or fold in the other.` });
   }
-  if (iconCollisions.length >= 5) c.push({ score: 20 + iconCollisions.length * 3, title: 'Merge the two icon sets',
+  if (iconCollisions.length >= 5) c.push({ score: 20 + iconCollisions.length * 3, metric: null, title: 'Merge the two icon sets',
     sub: `${iconCollisions.length} icon names exist in both sets, so every import is a coin flip. Pick one home and rename or delete the rest. Receipt: ${esc(iconCollisions[0].files[0])} vs ${esc(iconCollisions[0].files[1])}.` });
   const strayOffender = offenders.find((o) => o.strayColors > 0);
   if (colorStrays > 12) {
@@ -601,13 +700,14 @@ function whereToStartSection() {
     const besideTokens = strayOffender && tf && (strayOffender.file === tf
       || strayOffender.file.split('/').slice(0, -1).join('/') === tf.split('/').slice(0, -1).join('/')
       || /variables|tokens|theme/i.test(strayOffender.file));
-    c.push({ score: colorStrays, title: `Tokenise the ${n(colorStrays)} stray colours`,
+    c.push({ score: colorStrays, metric: 'colors', after: 0, title: `Tokenise the ${n(colorStrays)} stray colours`,
       sub: `They are hardcoded where no token names them${strayOffender ? (besideTokens
         ? `, including ${strayOffender.strayColors} in ${esc(strayOffender.file)}, sitting right next to the token definitions. Those are the cheapest wins on this page`
         : `; ${esc(strayOffender.file)} alone carries ${strayOffender.strayColors}`) : ''}. Every one is a value your agent will happily copy.` });
   }
   if (inline.count > 10) { const worst = inline.files[0];
-    c.push({ score: inline.count / 2, title: `Fold ${n(inline.count)} inline style blocks back into the system`,
+    c.push({ score: inline.count / 2, metric: 'inlineStyles', after: 0,
+      title: `Fold ${n(inline.count)} inline style blocks back into the system`,
       sub: `These are static values written as style attributes${worst ? `; start with ${esc(worst.file)} (${worst.count} blocks)` : ''}. Dynamic positioning was already excluded, so all of these could be classes or tokens today.` }); }
   if (arbitraryCount >= 20) {
     // Repeated brackets read as decisions; singletons are worth a pass. Small
@@ -618,7 +718,10 @@ function whereToStartSection() {
     const singles = arbitrary.filter((a) => a.count === 1).length;
     const top = arbitrary[0];
     const tokenFile = h.tokens.tokenFile;
-    c.push({ score: arbitraryCount / 3, title: `Give your repeated bracket values names`,
+    // naming the repeats removes their counts; the one-offs are left alone on purpose
+    const afterNaming = arbitraryCount - repeats.reduce((sum, a) => sum + a.count, 0);
+    c.push({ score: arbitraryCount / 3, metric: 'arbitrary', after: afterNaming,
+      title: `Give your repeated bracket values names`,
       sub: repeats.length
         ? `${esc(top.value)} appears ${top.count} times, which reads as a decision, not drift. If it is one, name it${tokenFile ? ` in ${esc(tokenFile)}` : ' in the scale'} so the next component (and your agent) can reach for it${repeats.length > 1 ? `; ${repeats.length - 1} more repeated value${repeats.length > 2 ? 's' : ''} deserve the same look` : ''}. The ${singles} values used once are worth a pass: keep the deliberate ones (optical nudges${nudges ? ` like the ${nudges} under 4px` : ''}, one-off layout widths) and round the accidents to a neighbouring step.`
         : `${n(arbitraryCount)} bracket values sit outside the scale, almost all used once. Keep the deliberate ones (optical nudges, one-off widths) and round the rest to a neighbouring step.` });
@@ -628,24 +731,124 @@ function whereToStartSection() {
     // the first move is to define it, next to the tokens the repo already has.
     const hasScale = twSpacing.length >= 5;
     const tf = h.tokens.tokenFile;
-    c.push({ score: spacingTotal / 2, title: hasScale
+    c.push({ score: spacingTotal / 2, metric: 'spacing', title: hasScale
       ? `Fold ${n(spacingTotal)} off-scale spacing values back to the scale`
       : `Define a spacing scale, then fold ${n(spacingTotal)} values into it`,
       sub: hasScale
         ? `${n(spacingTotal)} values sit outside the scale you already use. Keep the deliberate exceptions and round the accidents to a neighbouring step.`
         : `${n(spacingTotal)} distinct spacing values and no named scale to hold them. Define ~8 steps${tf ? ` in ${esc(tf)}, next to the tokens you already keep there` : ''}, then migrate values as you touch each file. No mass rounding.` });
   }
-  const top3 = c.sort((a, b) => b.score - a.score).slice(0, 3);
+  if (nearPairs.length >= 3) {
+    const p0 = nearPairs[0];
+    c.push({ score: 30 + nearPairs.length * 2, metric: 'nearPairs', after: 0,
+      title: `Collapse the ${n(nearPairs.length)} near-identical colours`,
+      sub: `${esc(p0.a.value)} and ${esc(p0.b.value)} are the same colour to any eye${p0.a.count + p0.b.count > 3 ? `, and they are used ${n(p0.a.count + p0.b.count)} times between them` : ''}. Nobody chose to have both. Pick the one that is already a token, point the other at it, and the pair stops multiplying.` });
+  }
+  if (important.count >= 10) {
+    const worst = important.files[0];
+    c.push({ score: 20 + important.count, metric: 'important', after: 0,
+      title: `Unwind the ${n(important.count)} !important declarations`,
+      sub: `Each one is a selector losing an argument with another selector${worst ? `; ${esc(basename(worst.file))} alone carries ${worst.count}` : ''}. Fix the specificity at the source and they stop being necessary.` });
+  }
+  if (neverImported.length >= 3) {
+    c.push({ score: 15 + neverImported.length, metric: 'neverImported', after: 0,
+      title: `Decide about the ${n(neverImported.length)} components nobody imports`,
+      sub: `${neverImported.slice(0, 3).map((x) => `&lt;${esc(x.name)}&gt;`).join(', ')}${neverImported.length > 3 ? ' and others' : ''} sit in the system with no callers. Adopt them or delete them: either answer is better than a system with rooms nobody enters.` });
+  }
+
+  // What each move is actually worth, then rank by payoff for real.
+  for (const item of c) {
+    item.delta = 0; item.target = null;
+    if (!item.metric) continue;
+    const now = bigStats.find((st) => st.metric === item.metric)?.healthValue;
+    if (now === undefined) continue;
+    if (item.after !== undefined) {
+      const gain = bandPoints(item.metric, now, item.after);
+      if (gain > 0) { item.delta = gain; continue; }
+    }
+    const nb = nextBand(item.metric, now);
+    if (nb && nb.gain > 0) item.target = nb;
+  }
+  const top3 = c.sort((a, b) => (b.delta - a.delta) || (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.
+  const applied = new Map();
+  for (const item of top3) if (item.metric && item.after !== undefined && item.delta > 0) applied.set(item.metric, item.after);
+  const after = projectedScore(applied);
+  const words = ['One tweak', 'Two tweaks', 'Three tweaks'][top3.length - 1];
+  const head = healthScore !== null && after > healthScore
+    ? `${words} · <b class="proj">${healthScore} &rarr; ${after}</b>`
+    : `${words} to increase your score.`;
+  const chip = (item) => item.delta > 0
+    ? `<span class="delta">+${item.delta}</span>`
+    : item.target
+      ? `<span class="delta delta-target">${item.target.target === 0 ? 'clear them all' : `under ${n(item.target.target)}`} · +${item.target.gain}</span>`
+      : '';
   return `<section class="glass pad">
-    ${sectionHead('Where to start', `${['One tweak', 'Two tweaks', 'Three tweaks'][top3.length - 1]} to increase your score.`)}
+    ${sectionHead('Where to start', head)}
     <div class="ledger">${top3.map((item, i) => `
       <div class="ledger-row start-row">
         <span class="ledger-idx">${String(i + 1).padStart(2, '0')}</span>
-        <div class="start-body"><div class="start-title">${item.title}</div><div class="sub">${item.sub}</div></div>
+        <div class="start-body"><div class="start-head"><div class="start-title">${item.title}</div>${chip(item)}</div><div class="sub">${item.sub}</div></div>
       </div>`).join('')}</div></section>`;
 }
 
+// ---------- package by package ----------
+// One number for a monorepo hides which package is the problem. Each package
+// is judged on the same nine tiles, with usage counted repo-wide, so a shared
+// component another package imports is adopted rather than dead.
+const PKG_LABELS = {
+  colors: 'stray colours', greys: 'greys', spacing: 'off-scale spacing values',
+  exactDuplicates: 'duplicated components', inlineStyles: 'inline style blocks',
+  nearPairs: 'near-identical colour pairs', important: '!important declarations',
+  neverImported: 'components nobody imports', arbitrary: 'arbitrary bracket values',
+};
+function scorePackage(m) {
+  const tokenLed = m.colorTokens >= m.colorStrays && m.colorTokens > 0;
+  const vals = {
+    colors: tokenLed ? m.colorStrays : m.colors,
+    greys: tokenLed ? m.greyStrays : m.greys,
+    spacing: m.spacing,
+    exactDuplicates: m.exactDuplicates,
+    inlineStyles: m.inlineStyles,
+    nearPairs: m.nearPairs,
+    important: m.important,
+    neverImported: m.neverImported,
+    arbitrary: m.arbitrary,
+  };
+  const rows = Object.entries(vals).map(([metric, v]) => ({ metric, value: v, health: healthOf(metric, v, { noAbsence: true }) }));
+  const scored = rows.filter((r) => r.health in SCORE_OF);
+  if (!scored.length) return null;
+  const score = Math.round(scored.reduce((sum, r) => sum + SCORE_OF[r.health], 0) / scored.length);
+  // the worst finding: furthest past its ideal among the failing tiles
+  const over = (r) => { const iv = ideal(r.metric); return iv ? r.value / Math.max(iv, 1) : r.value; };
+  const worst = scored.filter((r) => r.health === 'bad').sort((a, b) => over(b) - over(a))[0]
+    ?? scored.filter((r) => r.health === 'warn').sort((a, b) => over(b) - over(a))[0];
+  return { score, worst };
+}
+function packagesSection() {
+  const pkgs = (h.packages ?? []).filter((p) => p.scored && p.metrics);
+  if (pkgs.length < 2) return '';
+  const rated = pkgs.map((p) => ({ ...p, ...scorePackage(p.metrics) })).filter((p) => p.score !== undefined && p.score !== null);
+  if (rated.length < 2) return '';
+  rated.sort((a, b) => a.score - b.score);
+  const shown = rated.slice(0, 10);
+  const band = (sc) => (sc >= 85 ? 'good' : sc >= 55 ? 'warn' : 'bad');
+  const skipped = (h.packages ?? []).length - rated.length;
+  const rows = shown.map((p) => `
+    <tr><td class="mono strong">${esc(p.dir)}</td>
+    <td><span class="pkg-score pkg-${band(p.score)}">${p.score}</span></td>
+    <td>${p.worst ? `${n(p.worst.value)} ${esc(PKG_LABELS[p.worst.metric] ?? p.worst.metric)}` : '<span class="dim">nothing over the line</span>'}</td>
+    <td class="dim">${n(p.codeFiles)} files</td></tr>`).join('');
+  return `<section class="glass pad">
+    ${sectionHead('Package by package', `${rated.length} package${rated.length === 1 ? '' : 's'} with enough UI to judge · the repo score above is the whole thing blended${skipped > 0 ? `, and ${skipped} package${skipped === 1 ? ' was' : 's were'} too small or too backend to score` : ''}`)}
+    <div class="tbl-wrap"><table><thead><tr><th>package</th><th>score</th><th>worst finding</th><th>size</th></tr></thead><tbody>${rows}</tbody></table></div>
+    ${rated.length > 10 ? `<div class="spec-more">and ${rated.length - 10} more</div>` : ''}
+    ${healthScore !== null && rated.length && Math.min(...rated.map((p) => p.score)) > healthScore
+      ? `<p class="sub" style="margin-top:12px">A repo scores below its own packages by arithmetic, not by accident: distinct values add up across packages, so the whole always carries more than any part. Read the package scores for where each team stands, and the repo score for what your agent sees when it looks at everything at once.</p>` : ''}</section>`;
+}
+
 function agentSection() {
   const have = agentFiles.map((c) => `<span class="chip chip-agent">${esc(c.file)} · ${esc(c.tool ?? c.kind)}</span>`).join('');
   const msg = agentFiles.length
@@ -885,6 +1088,31 @@ const html = `<!doctype html>
   footer .brand { color:var(--accent); font-weight:700; text-decoration:none; }
   footer .brand:hover { text-decoration:underline; }
   footer .creds { display:flex; gap:16px; font:700 9.5px/1.6 var(--sans); letter-spacing:.16em; text-transform:uppercase; color:var(--dim2); }
+  .pkg-score { display:inline-block; min-width:38px; text-align:center; font:700 12.5px/1 var(--sans);
+    padding:6px 8px; border-radius:8px; }
+  .pkg-good { background:var(--ok-soft); color:var(--ok); }
+  .pkg-warn { background:var(--amber-soft); color:var(--amber); }
+  .pkg-bad { background:var(--coral-soft); color:var(--coral); }
+  .spec { margin-top:18px; }
+  .spec-rows { display:grid; gap:2px; margin-top:8px; }
+  .spec-type { display:flex; align-items:baseline; gap:16px; padding:5px 0; border-bottom:1px solid var(--line-soft); }
+  .spec-type:last-child { border-bottom:0; }
+  .spec-val { font:600 11px/1.4 var(--mono); color:var(--dim2); min-width:104px; flex-shrink:0; }
+  .spec-sample { color:var(--text); line-height:1.15; white-space:nowrap; overflow:hidden; text-overflow:ellipsis;
+    font-family:var(--disp); letter-spacing:-.01em; }
+  .spec-more { font:600 10.5px/1 var(--mono); color:var(--dim2); margin-top:10px; }
+  .spec-grid { display:flex; flex-wrap:wrap; gap:16px; margin-top:12px; }
+  .spec-cell { display:grid; gap:7px; justify-items:center; }
+  .spec-box { width:46px; height:46px; background:var(--deep); box-shadow:inset 0 0 0 1px var(--cell-ring); }
+  .spec-shadows { background:#f2f2f5; border-radius:14px; padding:20px 18px 14px; gap:22px; }
+  .spec-card { width:84px; height:50px; border-radius:10px; background:#ffffff; }
+  .spec-shadows .spec-cap { color:#71718a; max-width:104px; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+  .spec-cap { font:500 10.5px/1 var(--mono); color:var(--dim2); }
+  .start-head { display:flex; align-items:baseline; gap:10px; flex-wrap:wrap; }
+  .delta { font:700 11px/1 var(--sans); letter-spacing:.04em; padding:5px 9px; border-radius:99px;
+    background:var(--ok-soft); color:var(--ok); white-space:nowrap; }
+  .delta-target { background:var(--amber-soft); color:var(--amber); font-weight:600; }
+  .proj { color:var(--accent); font-weight:700; }
   .ndot { display:inline-block; width:9px; height:9px; border-radius:3px; margin-right:4px; vertical-align:-1px; box-shadow:inset 0 0 0 1px var(--cell-ring); }
   .nsim { color:var(--dim2); font-weight:400; padding:0 2px; }
   .gift-sec { margin-top:16px; }
@@ -960,6 +1188,8 @@ ${giftSection()}
 
 <div class="stats">${bigStats.map((s) => statTile(s)).join('')}</div>
 
+${packagesSection()}
+
 ${agentSection()}
 
 <section style="margin-top:16px">${paletteSection()}</section>
@@ -975,8 +1205,8 @@ ${componentsSection()}
 
 <footer>
   <div class="foot-left">
-    <div>Generated by <a class="brand" href="https://github.com/pencilrebel/roast-my-design-system">roast-my-design-system</a>, a free skill for Claude Code and Codex</div>
-    <div class="foot-sub"><span class="ver">ver. ${VERSION}</span> · <span class="scan-id" title="scan id">${scanId}</span> · built and designed by <a class="author" href="https://gregkozakiewicz.com"><span class="gk-mark"></span>Greg Kozakiewicz</a></div>
+    <div>Generated by <a class="brand" href="https://github.com/pencilrebel/roast-my-design-system">roast-my-design-system</a> <span class="ver">ver. ${VERSION}</span>, free on npm and as a Claude Code + Codex skill</div>
+    <div class="foot-sub">Designed and built by <a class="author" href="https://gregkozakiewicz.com"><span class="gk-mark"></span>Greg Kozakiewicz</a> · <span class="scan-id" title="scan id">${scanId}</span></div>
   </div>
   <span class="creds"><span>Non-destructive scan</span><span>Read-only</span><span>Paths are real</span></span>
 </footer>
@@ -1036,6 +1266,10 @@ if (summaryPath) {
     noSystemLikely,
     verdict,
     tiles: bigStats.map((s) => ({ label: s.label, value: s.num, health: s.health })),
+    packages: (h.packages ?? []).filter((p) => p.scored && p.metrics)
+      .map((p) => ({ dir: p.dir, name: p.name, ...(scorePackage(p.metrics) ?? {}) }))
+      .filter((p) => p.score !== undefined)
+      .sort((a, b) => a.score - b.score),
     report: outPath,
   }, null, 2));
 }

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

@@ -14,6 +14,9 @@ import { harvestComponents } from './components.mjs';
 import { harvestTokens } from './tokens.mjs';
 import { findDuplicates } from './duplicates.mjs';
 import { harvestContext } from './context.mjs';
+import { resolveWorkspaces } from '../lib/workspaces.mjs';
+import { nearColorPairs } from '../lib/nearpairs.mjs';
+import { neverImportedComponents } from '../lib/neverimported.mjs';
 
 function arg(name, fallback) {
   const i = process.argv.indexOf(`--${name}`);
@@ -35,6 +38,70 @@ const tokens = harvestTokens(target, files.styles, files.code);
 const duplicates = findDuplicates(components, profile.uiDir, target);
 const context = harvestContext(target);
 
+// ---------- per-package pass (monorepos) ----------
+// Styling is measured inside each package, but usage is counted repo-wide: a
+// component another package imports is adopted, not dead. Files are already
+// walked, so this re-reads each package's own files once, not the whole repo
+// per package. Packages with too little UI to judge are listed, never scored.
+const workspaces = resolveWorkspaces(target);
+const packages = [];
+if (workspaces.length > 1) {
+  const inDir = (f, dir) => f === dir || f.startsWith(`${dir}/`);
+  // deepest-first so apps/web/sub is attributed to itself, not to apps/web
+  const byDepth = [...workspaces].sort((a, b) => b.dir.split('/').length - a.dir.split('/').length);
+  const claimed = new Map();
+  const claim = (f) => byDepth.find((w) => inDir(f, w.dir))?.dir ?? null;
+  for (const f of files.code) { const d = claim(f); if (d) (claimed.get(d) ?? claimed.set(d, { code: [], styles: [] }).get(d)).code.push(f); }
+  for (const f of files.styles) { const d = claim(f); if (d) (claimed.get(d) ?? claimed.set(d, { code: [], styles: [] }).get(d)).styles.push(f); }
+
+  // Only packages that actually contain UI are worth reading twice: a backend
+  // or config package has no styling to judge, and scanning it would cost time
+  // to produce a meaningless perfect score. Biggest UI packages first, capped,
+  // so a 100-package monorepo cannot blow the scan budget.
+  const UI_RE = /\.(tsx|jsx|vue|svelte)$/;
+  const uiCount = (w) => {
+    const own = claimed.get(w.dir);
+    return own ? own.code.filter((f) => UI_RE.test(f)).length + own.styles.length : 0;
+  };
+  const candidates = workspaces
+    .map((w) => ({ w, ui: uiCount(w) }))
+    .sort((a, b) => b.ui - a.ui);
+  const scanning = new Set(candidates.filter((c) => c.ui >= 8).slice(0, 30).map((c) => c.w.dir));
+
+  for (const w of workspaces) {
+    const own = claimed.get(w.dir);
+    if (!own) continue;
+    const codeCount = own.code.length, styleCount = own.styles.length;
+    const entry = { name: w.name, dir: w.dir, codeFiles: codeCount, styleFiles: styleCount, scored: false };
+    if (!scanning.has(w.dir)) { packages.push(entry); continue; }
+    const t = harvestTokens(target, own.styles, own.code);
+    const comps = components.filter((c) => inDir(c.file, w.dir));
+    const dupes = duplicates.exactDuplicates.filter((d) => !d.wrapped
+      && d.files.every((f) => inDir(typeof f === 'string' ? f : f.file, w.dir)));
+    const colorTokens = t.colors.filter((c) => c.isToken).length;
+    const signal = t.colors.length + t.spacing.length + t.inlineStyles.count
+      + (t.tailwind.colors.length + t.tailwind.spacing.length);
+    if (signal < 5) { packages.push(entry); continue; }   // nothing to judge, so no verdict
+    entry.scored = true;
+    entry.metrics = {
+      colors: t.colors.length,
+      colorTokens,
+      colorStrays: t.colors.length - colorTokens,
+      greys: t.greyCount,
+      greyStrays: t.colors.filter((c) => !c.isToken && c.value.startsWith('#')).length,
+      spacing: t.spacing.length + t.tailwind.spacing.filter((v) => v.value.startsWith('[')).length,
+      exactDuplicates: dupes.length,
+      inlineStyles: t.inlineStyles.count,
+      nearPairs: nearColorPairs(t.colors).length,
+      important: t.important?.count ?? 0,
+      neverImported: neverImportedComponents(comps, null).length,
+      arbitrary: (t.tailwind.arbitrary ?? []).reduce((sum, a) => sum + a.count, 0),
+      components: comps.filter((c) => !c.isPage).length,
+    };
+    packages.push(entry);
+  }
+}
+
 const harvest = {
   repo: target,
   harvestedAt: new Date().toISOString(),
@@ -49,6 +116,7 @@ const harvest = {
   tokens,
   duplicates,
   context,
+  packages,
 };
 harvest.tookMs = Date.now() - t0;
 

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

@@ -0,0 +1,92 @@
+/**
+ * Workspace resolution. A monorepo declares its packages in one of a few
+ * places and always as globs, never as a fixed folder shape — guessing from
+ * folder depth misses most of them (cal.com keeps 23 packages that a naive
+ * two-level scan reports as zero). Read the declaration instead.
+ *
+ * Supports: package.json `workspaces` (array or { packages: [] }),
+ * pnpm-workspace.yaml, and negation patterns.
+ */
+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+const readJSON = (p) => { try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; } };
+
+/** Expand one glob ('packages/*', 'apps/**', 'tools/x') to existing directories. */
+function expand(root, pattern) {
+  if (pattern === '.' || pattern === './') return [];
+  const parts = pattern.replace(/\/+$/, '').split('/').filter(Boolean);
+  let dirs = [''];
+  for (const part of parts) {
+    const next = [];
+    for (const d of dirs) {
+      const abs = join(root, d);
+      if (part === '*' || part === '**') {
+        let entries;
+        try { entries = readdirSync(abs, { withFileTypes: true }); } catch { continue; }
+        for (const e of entries) {
+          if (!e.isDirectory() || e.name.startsWith('.') || e.name === 'node_modules') continue;
+          const rel = d ? `${d}/${e.name}` : e.name;
+          next.push(rel);
+          // '**' also matches deeper levels
+          if (part === '**') dirs.push(rel);
+        }
+      } else {
+        const rel = d ? `${d}/${part}` : part;
+        if (existsSync(join(root, rel))) next.push(rel);
+      }
+    }
+    dirs = next;
+  }
+  return dirs.filter((d) => { try { return statSync(join(root, d)).isDirectory(); } catch { return false; } });
+}
+
+/**
+ * Resolve a repo's workspace packages.
+ * Returns [{ name, dir }] with dir relative to the repo root, or [] when the
+ * repo is not a workspace monorepo.
+ */
+export function resolveWorkspaces(root) {
+  const patterns = [];
+  const pkg = readJSON(join(root, 'package.json'));
+  const ws = pkg?.workspaces;
+  if (Array.isArray(ws)) patterns.push(...ws);
+  else if (Array.isArray(ws?.packages)) patterns.push(...ws.packages);
+
+  // pnpm-workspace.yaml: the "packages:" block, read line by line. Comments and
+  // blank lines are legal inside it (langfuse opens with one), and sibling
+  // top-level keys such as "catalog:" end it.
+  try {
+    const lines = readFileSync(join(root, 'pnpm-workspace.yaml'), 'utf8').split('\n');
+    let inBlock = false;
+    for (const line of lines) {
+      if (/^packages:\s*$/.test(line)) { inBlock = true; continue; }
+      if (!inBlock) continue;
+      if (/^\s*(#.*)?$/.test(line)) continue;              // comment or blank
+      if (/^\S/.test(line)) break;                          // next top-level key
+      const m = /^\s*-\s*["']?([^"'#]+?)["']?\s*$/.exec(line);
+      if (m) patterns.push(m[1].trim());
+    }
+  } catch { /* not a pnpm workspace */ }
+
+  if (!patterns.length) return [];
+
+  const negations = patterns.filter((p) => p.startsWith('!')).map((p) => p.slice(1).replace(/\/+$/, ''));
+  const isNegated = (dir) => negations.some((neg) => {
+    if (neg.includes('*')) return expand(root, neg).includes(dir);
+    return dir === neg || dir.startsWith(`${neg}/`);
+  });
+
+  const seen = new Map();
+  for (const pattern of patterns) {
+    if (pattern.startsWith('!')) continue;
+    for (const dir of expand(root, pattern)) {
+      if (!dir || dir === '.' || isNegated(dir) || seen.has(dir)) continue;
+      // a workspace package is one that declares itself
+      const own = readJSON(join(root, dir, 'package.json'));
+      if (!own) continue;
+      seen.set(dir, { name: own.name || dir, dir });
+    }
+  }
+  return [...seen.values()].sort((a, b) => a.dir.localeCompare(b.dir));
+}