roast-my-design-system 6.0.0 → 7.0.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=6.0.0" width="72" alt="roast-my-design-system">
+<img src="https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/roaster_logo_300px.png?v=7.0.0" width="72" alt="roast-my-design-system">
 
 # roast-my-design-system
 
@@ -10,6 +10,8 @@
 
 A free CLI tool (and Claude Code skill) that roasts your repo's design system with real data, then generates the rules that keep your AI agent on-system.
 
+> **New in 7.0.** The scoring code is now a separate file that other tools can import, so a CI check gets the same score as the report. Every `summary.json` now records its schema version and which benchmark it was scored against. Five counting bugs are fixed: a bracket spacing class like `p-[13px]` was counted twice, a hex colour inside a CSS comment was counted, and three smaller ones. Most repos lose a few counts. shadcn/ui goes from 325 colours to 323 and keeps its score of 65. Large monorepos scan about ten times faster. If you use the score as a CI threshold, run a fresh scan before comparing. If you read the JSON, a tile's `value` is now a number and the printed text is in `display`.
+
 > **New in 6.0: a dark mode is not sprawl, and the ruler has been rebuilt.** A system with a dark theme states most of its colours twice. One with a density switch states its spacing twice again. Every restatement was counted, so the systems doing the most work scored the worst. Now only a token's first statement counts. A factory-fresh shadcn install goes from 20 colours to 16, and Shoelace from 420 to 219. Two related faults went with it. `border-radius: var(--radius)` was counted as a radius value, so Polaris showed 49 radii of which 36 were references to its own tokens, and Telekom showed 52 font sizes of which 48 were. A new finding names one token holding two different colours in two packages of a monorepo, which fires 8 times across 19 real repos. The benchmark was rebuilt with all of it, so every score is measured against a ruler that counts the same way: cal.com 15 to 20, Cloudscape 35 to 40, MUI 50 to 55. If you have a score from 5.x, take a fresh one before you compare.
 
 Run it on your codebase and get, in about a second:
@@ -43,7 +45,7 @@ Type these in a terminal and you get a result.
 | `... --sarif` | `design-system-roast.sarif` for GitHub code scanning: upload it in CI and findings appear in the Security tab, annotated on files |
 | `... --check` | The working tree's changed files checked against the design system, in the terminal. Exits 1 on findings, so it slots into scripts |
 | <code>...&nbsp;--exclude&nbsp;lab/</code> | Leave a folder out of the scan (repeat the flag or comma-separate). Or list folders in a `.roastignore` file at the repo root. Either way the report says so in the header; see [Scoping the scan](#scoping-the-scan) |
-| `... --json` | The scan summary as JSON on stdout, for scripts and pipelines |
+| `... --json` | The scan summary as JSON on stdout, for scripts and pipelines. Includes `schemaVersion`, the benchmark used, and every metric as a number, so two scans can be compared |
 | <code>...&nbsp;--by&nbsp;"Dwayne&nbsp;Hicks"</code> | Puts a name in the report header, for when you ran it for someone else |
 | <code>...&nbsp;--theme&nbsp;light</code>&nbsp;/ <code>--out&nbsp;&lt;file&gt;</code>&nbsp;/ <code>--no-open</code>&nbsp;/ <code>--open</code> | Light report, custom report path, never open the browser, always open it |
 
@@ -71,11 +73,11 @@ Not to be confused with each other: **"Why this matters"** is generic, ships wit
 
 The full report for vercel/ai-chatbot, top to bottom, including "What the numbers mean", Claude's read of the scan, embedded right under the verdict:
 
-![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, the What the numbers mean analysis written by Claude, priced Where to start moves each with its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, 3-yardstick tiles, the adoption map treemap, palette forensics, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-full-dark.png?v=6.0.0)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, the What the numbers mean analysis written by Claude, priced Where to start moves each with its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, 3-yardstick tiles, the adoption map treemap, palette forensics, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-full-dark.png?v=7.0.0)
 
 The same report in light mode (one file, built-in toggle):
 
-![The diagnosis report in light mode](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-light-hero.png?v=6.0.0)
+![The diagnosis report in light mode](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-light-hero.png?v=7.0.0)
 
 ## What makes the numbers trustworthy
 
@@ -86,7 +88,8 @@ The same report in light mode (one file, built-in toggle):
 - **Honest gaps.** When a repo's components register in a pattern the scan can not read, the component tiles say "not measured" and drop out of the score. A zero the scanner never earned is presented as blindness, not discipline.
 - **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. Your own exclusions (`.roastignore`, `--exclude`) are printed in the report header with file counts, so a scoped scan can never pass itself off as the whole repo.
 - **Intent-aware counting (v3).** Runtime-computed inline styles, compound-component APIs and wrapper components are not crimes and are not counted as ones. Token-led repos are judged on their hardcoded strays, not their token architecture. Repeated arbitrary values are read as decisions without names, not drift.
-- **A real benchmark.** The "Avg Design System" yardstick comes from scanning 34 public React repos (cal.com, excalidraw, supabase, grafana, twenty, dub, langfuse…). Median: 130 colours, 17 greys, 20 duplicated components, 49 inline style blocks, 70 arbitrary Tailwind values.
+- **The scoring code can be imported.** `scoreHarvest(harvest)` in `diagnose/score.mjs` returns the score, the nine tile results and the metrics as plain data. The report uses the same function. A CI check gets the same numbers as the page, and every `summary.json` records its schema version and the benchmark used.
+- **A real benchmark.** The "Avg Design System" yardstick comes from scanning 34 public React repos (cal.com, excalidraw, supabase, grafana, twenty, dub, langfuse…). Median: 130 colours, 17 greys, 20 duplicated components, 49 inline style blocks, 70 arbitrary Tailwind values. The builder and the repo list are in `tools/benchmark/`, so the ruler can be checked, not just quoted.
 - **A second yardstick: reputable systems.** Curated, scoped scans of 10 well-known design systems (shadcn/ui, Primer, Polaris, Carbon, Material UI, Chakra, Ant Design, GOV.UK, Spectrum, Cloudscape) show what disciplined looks like at scale.
 
 ## Scoping the scan

package/bin/roast.mjs

@@ -171,12 +171,16 @@ for (const [flagName, file] of [
   process.exit(1);
 }
 
+// Every value-taking flag is consumed before the path is looked for, so
+// `--out report.html .` no longer reads report.html as the repo (it did,
+// until 6.0.1: flags in the "wrong" order died with "Not a directory").
+const outOpt = opt('out', null);
 const target = resolve(argv.find((a) => !a.startsWith('--')) || process.cwd());
 if (!existsSync(target) || !statSync(target).isDirectory()) {
   console.error(`Not a directory: ${target}`);
   process.exit(1);
 }
-const outPath = resolve(opt('out', join(target, 'design-system-roast.html')));
+const outPath = resolve(outOpt ?? join(target, 'design-system-roast.html'));
 
 const tmp = mkdtempSync(join(tmpdir(), 'roast-'));
 const harvestPath = join(tmp, 'harvest.json');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "6.0.0",
+  "version": "7.0.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 34 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

@@ -31,11 +31,14 @@ import { feedbackUrl, FEEDBACK_ASK, FEEDBACK_CTA } from '../lib/feedback.mjs';
 import { fixPrompt } from '../lib/fixprompt.mjs';
 import { WHY } from './why.mjs';
 import { parseColor, luminance, isGrey } from '../lib/color.mjs';
+import { loadBenchmark, benchHelpers, makeHealthOf, coreMetrics, tileHealths, scoreOfTiles, scorePackage as scorePackageOf, ZERO_IDEAL, WARN_TOLERANCE, SCORE_OF, SCHEMA_VERSION } from './score.mjs';
 
-// The benchmark (Ideal-2026 norms + scanned-repo stats) ships next to the
-// code so the page works offline; degrade gracefully when absent.
-const BENCH_PATH = join(dirname(fileURLToPath(import.meta.url)), '../benchmark/benchmark.json');
-const bench = existsSync(BENCH_PATH) ? JSON.parse(readFileSync(BENCH_PATH, 'utf8')) : null;
+// The benchmark and every judgement made against it live in score.mjs; this
+// file only draws. The same numbers reach summary.json through scoreHarvest.
+const bench = loadBenchmark();
+const B = benchHelpers(bench);
+const { percentile, cleanerPct, ideal, median, displayAvg, refMedian } = B;
+const healthOf = makeHealthOf(B);
 
 function arg(name, fallback) {
   const i = process.argv.indexOf(`--${name}`);
@@ -46,6 +49,7 @@ if (!inPath) { console.error('Usage: node src/diagnose/index.mjs <harvest.json>
 const outPath = resolve(arg('out', 'diagnosis.html'));
 
 const h = JSON.parse(readFileSync(inPath, 'utf8'));
+const M = coreMetrics(h);
 
 // The GK mark (32px favicon, also gregkozakiewicz.com). Reused in the footer
 // as a CSS mask filled with currentColor so it works in both themes.
@@ -201,9 +205,8 @@ const nonGreys = colors.filter((c) => !isGrey(c.value));
 const twColorUtils = (h.tokens.tailwind?.colors ?? []).length;
 const spacing = h.tokens.spacing ?? [];
 const twSpacing = h.tokens.tailwind?.spacing ?? [];
-// Off-scale spacing only: CSS-declared values plus arbitrary brackets. Using
-// many steps of the sanctioned Tailwind scale is health, not sprawl.
-const spacingTotal = spacing.length + twSpacing.filter((v) => v.value.startsWith('[')).length;
+// Off-scale spacing only (formula in score.mjs, shared with the packages pass).
+const spacingTotal = M.spacing;
 const exactDupes = h.duplicates.exactDuplicates ?? [];
 // A wrapped pair (one file imports the name from the other) is composition,
 // not competition — listed with a badge, but not counted as a duplicate.
@@ -224,14 +227,11 @@ const typefaces = distinctTypefaces(fontFamilies);
 // Token-led repos (shadcn/Tailwind semantic setups) hold most of their colours
 // as deliberate CSS-variable tokens; judging them on the total punishes the
 // exact architecture the ideal recommends. Health rides on the strays instead.
-const colorTokens = colors.filter((c) => c.isToken).length;
-const colorStrays = colors.length - colorTokens;
-const tokenLed = colorTokens >= colorStrays && colorTokens > 0;
-const greyStrays = greys.filter((c) => !c.isToken).length;
+const { colorTokens, colorStrays, tokenLed, greyStrays } = M;
 
 // Arbitrary bracket values (p-[13px], text-[10px]) — scale erosion, counted.
 const arbitrary = h.tokens.tailwind?.arbitrary ?? [];
-const arbitraryCount = arbitrary.reduce((sum, a) => sum + a.count, 0);
+const arbitraryCount = M.arbitrary;
 
 // !important declarations: the cascade admitting defeat.
 const important = h.tokens.important ?? { count: 0, files: [] };
@@ -250,45 +250,13 @@ const neverImported = neverImportedComponents(h.components, h.profile?.uiDir);
 // metrics say so and take no score credit; when the repo is a published
 // library, usage means composition (how the system uses itself), never
 // adoption, and every accusation about orphans is softened to match.
-const componentsMeasured = h.profile?.componentDetection?.measured !== false;
+const { componentsMeasured, isLibrary, vendoredUi } = M;
 const notMeasuredReason = h.profile?.componentDetection?.reason ?? 'an unrecognised component pattern';
-const isLibrary = h.profile?.role === 'library';
 // A shadcn ui folder is a vendored catalogue: `shadcn add` copies the source
 // in, people take the whole set at once, and an unused component there is
 // stock on a shelf rather than something a team built and abandoned. It is
 // also protective — the agent reaches for it instead of writing its own worse
 // version. So it is counted and shown, never scored and never a fix to make.
-const vendoredUi = h.profile?.vendoredUi === true;
-
-// Benchmark helpers: for a metric value, where does this repo sit among the
-// scanned fleet? ("more colours than 90% of scanned repos")
-function percentile(metric, value) {
-  const vals = bench?.stats?.[metric]?.values;
-  if (!vals?.length) return null;
-  const below = vals.filter((v) => v < value).length;
-  return Math.round((below / vals.length) * 100);
-}
-// The flattering twin: what share of the scanned fleet is messier than you.
-function cleanerPct(metric, value) {
-  const vals = bench?.stats?.[metric]?.values;
-  if (!vals?.length) return null;
-  const above = vals.filter((v) => v > value).length;
-  return Math.round((above / vals.length) * 100);
-}
-const ideal = (metric) => bench?.ideal2026?.[metric]?.value ?? null;
-const median = (metric) => bench?.stats?.[metric]?.median ?? null;
-// A zero median reads as broken data ("Avg: 0 typefaces"), when it really
-// means "the median repo declares none". Fall back to the fleet mean there;
-// it stays an honest "Avg" and only zeroes out if literally every repo does.
-function displayAvg(metric) {
-  const mv = median(metric);
-  if (mv === null) return null;
-  if (mv !== 0) return mv;
-  const vals = bench?.stats?.[metric]?.values ?? [];
-  const mean = vals.length ? vals.reduce((a, b) => a + b, 0) / vals.length : 0;
-  return mean >= 0.5 ? Math.round(mean) : null;
-}
-const refMedian = (metric) => bench?.referenceSystems?.stats?.[metric]?.median ?? null;
 
 // Clickable file paths — vscode:// opens the file straight in the editor.
 const fileLink = (f) => `<a class="path" href="vscode://file/${encodeURI(`${h.repo}/${f}`)}">${esc(f)}</a>`;
@@ -336,36 +304,8 @@ if (bench && findings.length) {
 }
 
 // ---------- health scoring ----------
-// Each tile is a mini scorecard: your number vs the Ideal Design System
-// target, the scanned-fleet average (the low bar) and the reputable-systems
-// median. Health drives the animated icon and colours:
-//   good  = at or under the ideal          → green checkmark (draws in)
-//   warn  = over the ideal but better than the 27-repo median: "over the
-//           target, better than the average repo" → amber circle (pulses)
-//   bad   = worse than the median (and the median is already a mess)
-//           → coral cross (shakes)
-// Where the median is missing or sits at/below ideal, warn caps at 1.5x ideal.
-// Zero-ideal metrics (duplicates, inline styles): 0 is good; a small tolerance
-// is warn; beyond that bad.
-// There used to be an absence rule here (basically nothing found = bad, on
-// the theory that an empty count means no design system). The noSystemLikely
-// guard now owns that judgement at report level, and for a repo with a real
-// system a zero is discipline, not absence — all spacing on tokens scored red.
-const ZERO_IDEAL = new Set(['exactDuplicates', 'inlineStyles', 'nearPairs', 'important', 'neverImported']);
-const WARN_TOLERANCE = { exactDuplicates: 2, inlineStyles: 10, nearPairs: 2, important: 5, neverImported: 2 };
-function healthOf(metric, value) {
-  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 (value <= iv) return 'good';
-  const mv = median(metric);
-  const warnCap = mv && mv > iv ? mv : iv * 1.5;
-  if (value <= warnCap) return 'warn';
-  return 'bad';
-}
+// The bands, the tolerances and healthOf itself live in score.mjs (imported
+// above), so a guard or a CI check judges with the same ruler as this page.
 // Our own marks, drawn by hand for this report: a tick that starts at the
 // left foot, a full-bleed cross, a round exclamation, a quiet dash. Generic
 // glyphs on purpose, and our own coordinates on purpose: nothing here is
@@ -390,59 +330,49 @@ function row(label, valText, refVal, value) {
   if (value === refVal) return { label, val: valText, dir: 'eq' };
   return { label, val: valText, dir: value < refVal ? 'down' : 'up' };
 }
-function tile(value, label, metric, fallbackTarget, healthValue = value) {
-  const health = healthOf(metric, healthValue);
-  const iv = ideal(metric), mv = median(metric), rm = refMedian(metric);
+const FALLBACK_TARGET = {
+  colors: 'a system needs ~24', greys: 'a scale has up to 13', spacing: 'a dozen deliberate exceptions',
+  exactDuplicates: 'should be 0', inlineStyles: 'invisible to any system', nearPairs: 'copy-paste, not decisions',
+  important: 'the cascade admitting defeat', neverImported: 'the system nobody found', arbitrary: 'a handful of deliberate exceptions',
+};
+// Dress one judged tile for the page: formatted number, comparison rows.
+// Accepts a judged tile from score.mjs, or the positional form the
+// typography section uses for its unscored tiles: (value, label, metric, fallback).
+function tile(t, pLabel, pMetric, pFallback) {
+  if (typeof t === 'number') {
+    return tile({ metric: pMetric, label: pLabel, value: t, healthValue: t, health: healthOf(pMetric, t), fallbackTarget: pFallback });
+  }
+  const { metric, label, value, healthValue, health } = t;
+  if (health === 'na') {
+    return { num: '—', label, health, metric, healthValue: null,
+      rows: [{ label: `not measured: ${notMeasuredReason}`, val: '', dir: '' }] };
+  }
+  const iv = ideal(metric), rm = refMedian(metric);
   const pct = percentile(metric, value);
   const rows = [];
   if (iv !== null) rows.push(row('Ideal Design System', ZERO_IDEAL.has(metric) ? String(iv) : `~${n(iv)}`, iv, value));
-  else rows.push({ label: fallbackTarget, val: '', dir: '' });
+  else rows.push({ label: t.fallbackTarget ?? FALLBACK_TARGET[metric], val: '', dir: '' });
   const clean = cleanerPct(metric, value);
   const avgNote = pct !== null && pct >= 60 && health !== 'good' ? ` · messier than ${pct}%`
     : clean !== null && clean >= 60 ? ` · cleaner than ${clean}%` : '';
   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, metric, healthValue };
-}
-const bigStats = [
-  tile(colors.length, 'distinct colours', 'colors', 'a system needs ~24', tokenLed ? colorStrays : colors.length),
-  tile(greys.length, 'shades of grey', 'greys', 'a scale has up to 13', tokenLed ? greyStrays : greys.length),
-  tile(spacingTotal, 'off-scale spacing values', 'spacing', 'a dozen deliberate exceptions'),
-  tile(hardDupes.length, 'duplicated components', 'exactDuplicates', 'should be 0'),
-  tile(inline.count, 'inline style blocks', 'inlineStyles', 'invisible to any system'),
-  tile(nearPairs.length, 'near-identical colour pairs', 'nearPairs', 'copy-paste, not decisions'),
-  tile(important.count, '!important declarations', 'important', 'the cascade admitting defeat'),
-  tile(neverImported.length, 'components never imported', 'neverImported', 'the system nobody found'),
-  tile(arbitraryCount, 'arbitrary bracket values', 'arbitrary', 'a handful of deliberate exceptions'),
-];
-
-// Component metrics the detector could not measure render as such and drop
-// out of the score ('na' is not a scored health); a library's never-imported
-// count stays visible but unscored, with the reason on the tile.
-if (!componentsMeasured) {
-  for (const m of ['exactDuplicates', 'neverImported']) {
-    const i = bigStats.findIndex((st) => st.metric === m);
-    bigStats[i] = { num: '—', label: bigStats[i].label, health: 'na', metric: m, healthValue: null,
-      rows: [{ label: `not measured: ${notMeasuredReason}`, val: '', dir: '' }] };
+  // A vendored catalogue is never judged for what it left on the shelf, and a
+  // library's internal use says nothing about adoption: shown, not scored.
+  if (health === 'info' && metric === 'neverImported') {
+    rows.push({ label: isLibrary
+      ? 'library: internal use only, downstream consumers invisible'
+      : 'catalogue stock: installed by the shadcn CLI, not used yet', val: '', dir: '' });
   }
-// A vendored catalogue is never judged for what it has left on the shelf —
-// but a repo that used everything it installed keeps the credit it earned, so
-// the tile only drops out of the score when it would otherwise accuse.
-} else if (isLibrary || (vendoredUi && neverImported.length > 0)) {
-  const t = bigStats.find((st) => st.metric === 'neverImported');
-  t.health = 'info';
-  t.rows.push({ label: isLibrary
-    ? 'library: internal use only, downstream consumers invisible'
-    : 'catalogue stock: installed by the shadcn CLI, not used yet', val: '', dir: '' });
+  return { num: n(value), label, health, rows, metric, healthValue };
 }
+const judgedTiles = tileHealths(M, healthOf);
+const bigStats = judgedTiles.map(tile);
 
 // Health score for the hero: the scored tiles averaged (good 100 / warn 55 / bad 10).
-const SCORE_OF = { good: 100, warn: 55, bad: 10 };
 const scoredTiles = bigStats.filter((s) => s.health in SCORE_OF);
-const healthScore = scoredTiles.length
-  ? Math.round(scoredTiles.reduce((sum, s) => sum + SCORE_OF[s.health], 0) / scoredTiles.length)
-  : null;
+const healthScore = scoreOfTiles(judgedTiles);
 
 // ---------- what a fix is worth ----------
 // The score is the average of the scored tiles, so moving one tile across a
@@ -522,12 +452,12 @@ function paletteSection() {
   const rest = sorted.slice(60);
   const cells = shown.map((c) => {
     const src = c.files?.[0] ? ` in ${c.files[0].file}` : '';
-    return `<div class="uc${c.isToken ? '' : ' stray'}" style="background:${esc(c.value)};flex-grow:${Math.max(c.count, 1)}" title="${esc(c.value)} ×${c.count}${esc(src)}">${c.isToken ? '' : '<i></i>'}</div>`;
+    return `<div class="uc${c.isToken ? '' : ' stray'}" style="background:${swatch(c.value)};flex-grow:${Math.max(c.count, 1)}" title="${esc(c.value)} ×${c.count}${esc(src)}">${c.isToken ? '' : '<i></i>'}</div>`;
   }).join('');
   const restCell = rest.length ? `<div class="uc uc-rest" style="flex-grow:${Math.max(rest.reduce((s, c) => s + c.count, 0), 1)}" title="${rest.length} more colours">+${rest.length}</div>` : '';
 
   const rampFor = (list) => `
-    <div class="grey-strip">${list.map((c) => `<div class="grey-cell" style="background:${esc(c.value)}" title="${esc(c.value)} ×${c.count}"></div>`).join('')}</div>
+    <div class="grey-strip">${list.map((c) => `<div class="grey-cell" style="background:${swatch(c.value)}" title="${esc(c.value)} ×${c.count}"></div>`).join('')}</div>
     ${list.length <= 8 ? `<div class="ramp-labels">${list.map((c) => `<span>${esc(c.value)}</span>`).join('')}</div>` : ''}`;
   const ramp = greys.length >= 4 ? `
     <div class="ramp-head">${eyebrow('Grey ramp · sorted dark → light · how many can you tell apart?')}</div>
@@ -557,7 +487,7 @@ function paletteSection() {
     ${ramp}
     ${nearPairs.length ? `
     <div class="receipts">${eyebrow(`${nearPairs.length} nearly identical pair${nearPairs.length === 1 ? '' : 's'} · copy-paste, not decisions`)}
-    <div class="chips-row">${nearPairs.slice(0, 8).map((pr) => `<span class="vchip" title="every channel within ${pr.d} of its twin"><i class="ndot" style="background:${esc(pr.a.value)}"></i>${esc(pr.a.value)} ×${pr.a.count} <b class="nsim">≈</b> <i class="ndot" style="background:${esc(pr.b.value)}"></i>${esc(pr.b.value)} ×${pr.b.count}</span>`).join('')}${nearPairs.length > 8 ? `<span class="vchip dim">+${nearPairs.length - 8} more</span>` : ''}</div>
+    <div class="chips-row">${nearPairs.slice(0, 8).map((pr) => `<span class="vchip" title="every channel within ${pr.d} of its twin"><i class="ndot" style="background:${swatch(pr.a.value)}"></i>${esc(pr.a.value)} ×${pr.a.count} <b class="nsim">≈</b> <i class="ndot" style="background:${swatch(pr.b.value)}"></i>${esc(pr.b.value)} ×${pr.b.count}</span>`).join('')}${nearPairs.length > 8 ? `<span class="vchip dim">+${nearPairs.length - 8} more</span>` : ''}</div>
     ${whyToggle('nearPairs')}</div>` : ''}
   </div>
 </section>`;
@@ -676,6 +606,9 @@ function duplicatesSection() {
 // 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);
+// A colour swatch is painted with the value itself, so the value must look
+// like a colour and nothing else; anything odd paints grey rather than the page.
+const swatch = (v) => cssSafe(v) ?? '#888';
 // 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());
@@ -1151,29 +1084,7 @@ const PKG_LABELS = {
   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) }));
-  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 };
-}
+const scorePackage = (m) => scorePackageOf(m, healthOf, B);
 function packagesSection() {
   const pkgs = (h.packages ?? []).filter((p) => p.scored && p.metrics);
   const rated = pkgs.map((p) => ({ ...p, ...scorePackage(p.metrics) })).filter((p) => p.score !== undefined && p.score !== null);
@@ -1737,7 +1648,7 @@ ${componentsSection()}
 
 <footer>
   <div class="foot-left">
-    <div>Generated by <a class="brand" href="https://github.com/gregkozakiewicz/roast-my-design-system">roast-my-design-system</a> <span class="ver">ver. ${VERSION}</span> · free to run: <a class="brand" href="https://www.npmjs.com/package/roast-my-design-system"><span class="mono" id="npx-cmd">npx roast-my-design-system</span></a> <button type="button" class="copy-pill" id="npx-copy">copy</button> · also a Claude Code + Codex skill and a local MCP server</div>
+    <div>Generated by <a class="brand" href="https://github.com/gregkozakiewicz/roast-my-design-system">roast-my-design-system</a> <span class="ver">ver. ${VERSION}</span> · free to run: <span class="mono" id="npx-cmd">npx roast-my-design-system@latest</span> <button type="button" class="copy-pill" id="npx-copy">copy</button> · also a Claude Code + Codex skill and a local MCP server</div>
     <div class="foot-sub">Designed and built by <a class="author" href="https://gregkozakiewicz.com/?utm_source=roast-report"><span class="gk-mark"></span>Greg Kozakiewicz</a> · <span class="scan-id" title="scan id">${scanId}</span> · ${FEEDBACK_ASK} <a class="feedback" href="${feedbackUrl(VERSION).replace(/&/g, '&amp;')}">${PULSE_ICON}${FEEDBACK_CTA}</a></div>
   </div>
   <span class="creds"><span>Non-destructive scan</span><span>Read-only</span><span>Paths are real</span></span>
@@ -1845,6 +1756,10 @@ if (summaryPath) {
   writeFileSync(resolve(summaryPath), JSON.stringify({
     repo: repoName,
     version: VERSION,
+    // The contract two scans are compared by: schemaVersion for the
+    // shape, benchmark for the ruler each scan was measured against.
+    schemaVersion: SCHEMA_VERSION,
+    benchmark: bench ? { builtAt: bench.builtAt, repoCount: bench.repoCount, referenceSystems: bench.referenceSystems?.count ?? 0 } : null,
     ...(commissionedBy ? { commissionedBy } : {}),
     ...(notesText ? { notesEmbedded: true } : {}),
     ...(extraSections.length ? { sectionsEmbedded: extraSections.map((s) => s.title) } : {}),
@@ -1854,7 +1769,11 @@ if (summaryPath) {
     verdict,
     role: h.profile?.role ?? 'product',
     componentsMeasured,
-    tiles: bigStats.map((s) => ({ label: s.label, value: s.num, health: s.health })),
+    metrics: (({ colors, colorTokens, colorStrays, greys, greyStrays, spacing, exactDuplicates, inlineStyles, nearPairs, important, neverImported, arbitrary, tokenLed }) =>
+      ({ colors, colorTokens, colorStrays, greys, greyStrays, spacing, exactDuplicates, inlineStyles, nearPairs, important, neverImported, arbitrary, tokenLed }))(M),
+    // value is the number as counted (null when not measured); display is
+    // what the page prints. Until 7.0.0 value was the formatted string.
+    tiles: judgedTiles.map((t, i) => ({ metric: t.metric, label: t.label, value: t.value, display: bigStats[i].num, health: t.health })),
     ...(startMoves.length ? { moves: startMoves } : {}),
     packages: (h.packages ?? []).filter((p) => p.scored && p.metrics)
       .map((p) => ({ dir: p.dir, name: p.name, ...(scorePackage(p.metrics) ?? {}) }))

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

@@ -0,0 +1,214 @@
+/**
+ * Score — the arithmetic behind the number in the hero, on its own so it can
+ * be imported (a guard, a CI step, any tool comparing two scans) without
+ * rendering a page. The report imports this; nothing here knows about HTML.
+ *
+ * One harvest.json in, one plain object out:
+ *   { schemaVersion, benchmark, metrics, tiles, score }
+ *
+ * The rules of the game, in one place:
+ *   - Each metric is judged against the Ideal Design System target and the
+ *     scanned-fleet median. good = at or under the ideal; warn = over the
+ *     ideal but no worse than the median (or 1.5x the ideal when the median
+ *     is missing or sits under the ideal); bad = worse than that.
+ *   - Zero-ideal metrics (duplicates, inline styles, twins, !important,
+ *     orphans): 0 is good, a small tolerance is warn, beyond it bad.
+ *   - The score is the scored tiles averaged: good 100, warn 55, bad 10.
+ *   - Token-led repos are judged on their strays, not their totals, because
+ *     a palette held as tokens is the architecture the ideal asks for.
+ *   - A metric the detector could not measure ('na') and a metric that is
+ *     shown but deliberately unscored ('info') take no part in the average.
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isGrey } from '../lib/color.mjs';
+import { nearColorPairs } from '../lib/nearpairs.mjs';
+import { neverImportedComponents } from '../lib/neverimported.mjs';
+import { SCHEMA_VERSION } from '../lib/version.mjs';
+
+export { SCHEMA_VERSION };
+
+// The benchmark (Ideal Design System norms + scanned-repo stats) ships next
+// to the code so everything works offline; degrade gracefully when absent.
+const BENCH_PATH = join(dirname(fileURLToPath(import.meta.url)), '../benchmark/benchmark.json');
+export function loadBenchmark() {
+  return existsSync(BENCH_PATH) ? JSON.parse(readFileSync(BENCH_PATH, 'utf8')) : null;
+}
+
+/** The yardstick readers for one benchmark object (null-safe). */
+export function benchHelpers(bench) {
+  // where does this value sit among the scanned fleet? ("more colours than 90%")
+  const percentile = (metric, value) => {
+    const vals = bench?.stats?.[metric]?.values;
+    if (!vals?.length) return null;
+    return Math.round((vals.filter((v) => v < value).length / vals.length) * 100);
+  };
+  // the flattering twin: what share of the fleet is messier than you
+  const cleanerPct = (metric, value) => {
+    const vals = bench?.stats?.[metric]?.values;
+    if (!vals?.length) return null;
+    return Math.round((vals.filter((v) => v > value).length / vals.length) * 100);
+  };
+  const ideal = (metric) => bench?.ideal2026?.[metric]?.value ?? null;
+  const median = (metric) => bench?.stats?.[metric]?.median ?? null;
+  // A zero median reads as broken data ("Avg: 0 typefaces") when it means
+  // "the median repo declares none". Fall back to the fleet mean there; it
+  // stays an honest "Avg" and only zeroes out if literally every repo does.
+  const displayAvg = (metric) => {
+    const mv = median(metric);
+    if (mv === null) return null;
+    if (mv !== 0) return mv;
+    const vals = bench?.stats?.[metric]?.values ?? [];
+    const mean = vals.length ? vals.reduce((a, b) => a + b, 0) / vals.length : 0;
+    return mean >= 0.5 ? Math.round(mean) : null;
+  };
+  const refMedian = (metric) => bench?.referenceSystems?.stats?.[metric]?.median ?? null;
+  return { percentile, cleanerPct, ideal, median, displayAvg, refMedian };
+}
+
+export const ZERO_IDEAL = new Set(['exactDuplicates', 'inlineStyles', 'nearPairs', 'important', 'neverImported']);
+export const WARN_TOLERANCE = { exactDuplicates: 2, inlineStyles: 10, nearPairs: 2, important: 5, neverImported: 2 };
+export const SCORE_OF = { good: 100, warn: 55, bad: 10 };
+
+/** healthOf(metric, value) for one benchmark: 'good' | 'warn' | 'bad' | 'info'. */
+export function makeHealthOf(b) {
+  return (metric, value) => {
+    const iv = b.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 (value <= iv) return 'good';
+    const mv = b.median(metric);
+    const warnCap = mv && mv > iv ? mv : iv * 1.5;
+    if (value <= warnCap) return 'warn';
+    return 'bad';
+  };
+}
+
+/** The tiles, in report order: metric key, the label the report prints. */
+export const TILES = [
+  ['colors', 'distinct colours'],
+  ['greys', 'shades of grey'],
+  ['spacing', 'off-scale spacing values'],
+  ['exactDuplicates', 'duplicated components'],
+  ['inlineStyles', 'inline style blocks'],
+  ['nearPairs', 'near-identical colour pairs'],
+  ['important', '!important declarations'],
+  ['neverImported', 'components never imported'],
+  ['arbitrary', 'arbitrary bracket values'],
+];
+
+/**
+ * The numbers every judgement rests on, read once from a harvest. Plain
+ * integers and flags; the same formulas the per-package pass uses.
+ */
+export function coreMetrics(h) {
+  const colors = h.tokens?.colors ?? [];
+  const greys = colors.filter((c) => isGrey(c.value));
+  const colorTokens = colors.filter((c) => c.isToken).length;
+  const colorStrays = colors.length - colorTokens;
+  const spacing = h.tokens?.spacing ?? [];
+  const twSpacing = h.tokens?.tailwind?.spacing ?? [];
+  const hardDupes = (h.duplicates?.exactDuplicates ?? []).filter((d) => !d.wrapped);
+  return {
+    colors: colors.length,
+    colorTokens,
+    colorStrays,
+    // Token-led repos hold most colours as deliberate CSS-variable tokens;
+    // judging them on the total punishes the architecture the ideal asks for.
+    tokenLed: colorTokens >= colorStrays && colorTokens > 0,
+    greys: greys.length,
+    greyStrays: greys.filter((c) => !c.isToken).length,
+    // Off-scale spacing only: CSS-declared values plus bracket utilities.
+    // Many steps of the sanctioned Tailwind scale is health, not sprawl.
+    spacing: spacing.length + twSpacing.filter((v) => v.value.startsWith('[')).length,
+    // A wrapped pair (one file imports the name from the other) is
+    // composition, not competition: listed with a badge, never counted.
+    exactDuplicates: hardDupes.length,
+    inlineStyles: h.tokens?.inlineStyles?.count ?? 0,
+    nearPairs: nearColorPairs(colors).length,
+    important: h.tokens?.important?.count ?? 0,
+    neverImported: neverImportedComponents(h.components, h.profile?.uiDir).length,
+    arbitrary: (h.tokens?.tailwind?.arbitrary ?? []).reduce((sum, a) => sum + a.count, 0),
+    // Measurability and role, decided by the harvest: an unreadable stack
+    // takes no score credit; a library's orphans are shown, not judged; a
+    // vendored shadcn catalogue is stock on a shelf, not abandonment.
+    componentsMeasured: h.profile?.componentDetection?.measured !== false,
+    isLibrary: h.profile?.role === 'library',
+    vendoredUi: h.profile?.vendoredUi === true,
+  };
+}
+
+/**
+ * Judge the nine tiles from a metric set. Each tile carries the value shown,
+ * the value judged (strays for token-led colour tiles), and its health.
+ */
+export function tileHealths(m, healthOf) {
+  const shown = {
+    colors: m.colors, greys: m.greys, spacing: m.spacing, exactDuplicates: m.exactDuplicates,
+    inlineStyles: m.inlineStyles, nearPairs: m.nearPairs, important: m.important,
+    neverImported: m.neverImported, arbitrary: m.arbitrary,
+  };
+  const judged = { ...shown, colors: m.tokenLed ? m.colorStrays : m.colors, greys: m.tokenLed ? m.greyStrays : m.greys };
+  return TILES.map(([metric, label]) => {
+    let health = healthOf(metric, judged[metric]);
+    let value = shown[metric], healthValue = judged[metric];
+    if (!m.componentsMeasured && (metric === 'exactDuplicates' || metric === 'neverImported')) {
+      health = 'na'; value = null; healthValue = null;
+    } else if (metric === 'neverImported' && (m.isLibrary || (m.vendoredUi && m.neverImported > 0))) {
+      health = 'info';
+    }
+    return { metric, label, value, healthValue, health };
+  });
+}
+
+/** The scored tiles averaged (good 100 / warn 55 / bad 10); null when none. */
+export function scoreOfTiles(tiles) {
+  const scored = tiles.filter((t) => t.health in SCORE_OF);
+  return scored.length ? Math.round(scored.reduce((sum, t) => sum + SCORE_OF[t.health], 0) / scored.length) : null;
+}
+
+/** A package's score and its worst finding from its harvested metrics. */
+export function scorePackage(m, healthOf, b) {
+  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) }));
+  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 = b.ideal(r.metric); return iv ? r.value / Math.max(iv, 1) : r.value; };
+  const worst = scored.filter((r) => r.health === 'bad').sort((a, b2) => over(b2) - over(a))[0]
+    ?? scored.filter((r) => r.health === 'warn').sort((a, b2) => over(b2) - over(a))[0];
+  return { score, worst };
+}
+
+/** The whole judgement of one harvest, as data. */
+export function scoreHarvest(h, bench = loadBenchmark()) {
+  const b = benchHelpers(bench);
+  const healthOf = makeHealthOf(b);
+  const metrics = coreMetrics(h);
+  const tiles = tileHealths(metrics, healthOf);
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    // A rebuilt ruler moves every score with no change in the repo, so a
+    // history must know which ruler each scan was measured with.
+    benchmark: bench ? { builtAt: bench.builtAt, repoCount: bench.repoCount, referenceSystems: bench.referenceSystems?.count ?? 0 } : null,
+    metrics,
+    tiles,
+    score: scoreOfTiles(tiles),
+  };
+}