roast-my-design-system 7.3.3 → 7.4.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=7.3.2" 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.4.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.4: the score says what it measures, and the report has a new shape.** Under the number: "How safely an AI agent can build on this repo without going off-system." A fixed side panel holds the score, the stack, how the repo was read, an index of every section, and what is not yours and not counted. Installed code splits by one test, does it teach an agent a wrong lesson: shadcn's own bracket values are out of the count and named; palette colours inside an installed registry stay in the score and are never prompted; catalogue stock is not a trap. A factory install scores 100. Leftover theme variables become a fix.
+
 > **New in 7.3: shadcn repos are compared with shadcn repos.** The benchmark carries a shadcn slice, 17 of the 34 fleet repos, and on a shadcn repo every fleet line reads against it: "Avg shadcn repo", "cleaner than 60% of shadcn repos". Ideals and the reputable-systems line stay the same for everyone.
 
 > **New in 7.2: shadcn repos are read as shadcn repos.** The scanner finds the installed catalogue where it actually lives, reads the theme file `components.json` names, and prints how it decided under the report header. 2 new tiles appear on shadcn repos only, both from shadcn's own rules for agents: palette colours in your own code where a theme row exists, and kit components repainted through `className`. Counted per 100 of your own files, never inside the catalogue. The rules file gains a shadcn section. Scores on other repos do not move.
@@ -20,7 +22,7 @@ A free CLI tool (and Claude Code skill) that roasts your repo's design system wi
 
 Run it on your codebase and get, in about a second:
 
-- **A health score you can defend in a meeting.** 0 to 100, deterministic, and benchmarked against 3 yardsticks: Ideal Design System norms, 34 scanned public repos and 10 reputable design systems (Primer, Polaris, Carbon, shadcn/ui…).
+- **A health score you can defend in a meeting.** It measures how safely an AI agent can build new UI on this repo without going off-system. Everything else on the report is receipts for humans. 0 to 100, deterministic, and benchmarked against 3 yardsticks: Ideal Design System norms, 34 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.
 - **Reads React and web components alike.** Stencil, Lit and custom elements are detected by tag registration and counted by kebab tag. Libraries get composition maps, not adoption accusations. Earned token namespaces are named in the header. Anything the scan can not read is declared "not measured" instead of scored.
 - **The receipts behind it.** Every colour and its near-identical twin. Every spacing value, typeface, duplicated or never-imported component, inline style and !important. All with real file paths, in one self-contained HTML report you can open, Slack or email.
@@ -77,11 +79,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 line saying how the repo was read as a shadcn install, 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 including the 2 shadcn tiles, the adoption map treemap, palette forensics, the shadcn theme variable by variable, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-full-dark.png?v=7.3.2)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: a fixed side panel with the health score and what it measures, the stack, how the repo was read as a shadcn install, an index of every section and what is not the team's and not counted; then the summary, 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 including the 2 shadcn tiles, the adoption map treemap, palette forensics, the shadcn theme variable by variable, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-full-dark.png?v=7.4.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=7.3.2)
+![The diagnosis report in light mode](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-light-hero.png?v=7.4.0)
 
 ## What makes the numbers trustworthy
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "7.3.3",
+  "version": "7.4.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/benchmark/benchmark.json

@@ -91,8 +91,8 @@
       "note": "palette colours in own code where a theme variable exists, per 100 files"
     },
     "doorOverrides": {
-      "value": 15,
-      "note": "shadcn components given a colour or font through className, per 100 files"
+      "value": 2,
+      "note": "shadcn components given a colour through className, per 100 files; the tidiest half of 16 shadcn repos sit under this (2026-09-13 audit)"
     }
   },
   "stats": {
@@ -1852,7 +1852,7 @@
   },
   "slices": {
     "shadcn": {
-      "builtAt": "2026-09-12T19:02:27.297Z",
+      "builtAt": "2026-09-12T20:07:59.374Z",
       "repoCount": 16,
       "note": "every repo in the fleet the scanner reads as shadcn; the \"cleaner than\" line on a shadcn repo reads against these",
       "stats": {
@@ -2074,27 +2074,27 @@
         },
         "arbitrary": {
           "values": [
-            12,
-            38,
-            54,
-            100,
-            101,
-            126,
-            128,
-            163,
-            169,
-            245,
-            257,
-            385,
-            386,
-            614,
-            1625,
-            1673
+            5,
+            25,
+            41,
+            74,
+            88,
+            99,
+            113,
+            113,
+            148,
+            204,
+            217,
+            360,
+            366,
+            569,
+            1186,
+            1602
           ],
-          "p25": 101,
-          "median": 166,
-          "p75": 385,
-          "p90": 1120
+          "p25": 85,
+          "median": 131,
+          "p75": 362,
+          "p90": 878
         },
         "nearPairs": {
           "values": [
@@ -2205,40 +2205,40 @@
             57,
             58,
             62,
-            67,
+            66,
             100,
-            183,
+            179,
             296,
-            491
+            488
           ],
           "p25": 22,
           "median": 50,
           "p75": 75,
-          "p90": 240
+          "p90": 238
         },
         "doorOverrides": {
           "values": [
             0,
+            0,
+            0,
+            1,
+            1,
+            1,
+            1,
+            1,
+            2,
             3,
-            5,
-            13,
+            4,
+            4,
+            6,
             13,
-            15,
-            16,
-            16,
-            17,
-            18,
-            22,
             26,
-            28,
-            31,
-            44,
-            55
+            32
           ],
-          "p25": 13,
-          "median": 17,
-          "p75": 27,
-          "p90": 38
+          "p25": 1,
+          "median": 2,
+          "p75": 5,
+          "p90": 20
         }
       },
       "repos": [
@@ -2260,13 +2260,13 @@
             "shadows": 10,
             "exactDuplicates": 134,
             "inlineStyles": 79,
-            "arbitrary": 257,
+            "arbitrary": 217,
             "nearPairs": 18,
             "important": 157,
             "neverImported": 99,
             "components": 1453,
             "paintTin": 22,
-            "doorOverrides": 5
+            "doorOverrides": 1
           }
         },
         {
@@ -2287,7 +2287,7 @@
             "shadows": 1,
             "exactDuplicates": 0,
             "inlineStyles": 0,
-            "arbitrary": 54,
+            "arbitrary": 41,
             "nearPairs": 0,
             "important": 1,
             "neverImported": 94,
@@ -2314,7 +2314,7 @@
             "shadows": 2,
             "exactDuplicates": 1,
             "inlineStyles": 2,
-            "arbitrary": 12,
+            "arbitrary": 5,
             "nearPairs": 0,
             "important": 2,
             "neverImported": 0,
@@ -2330,7 +2330,7 @@
           "baseColor": "neutral",
           "tailwind": "4",
           "codeFiles": 146,
-          "ownFiles": 60,
+          "ownFiles": 68,
           "metrics": {
             "colors": 41,
             "greys": 0,
@@ -2341,13 +2341,13 @@
             "shadows": 4,
             "exactDuplicates": 1,
             "inlineStyles": 7,
-            "arbitrary": 100,
+            "arbitrary": 74,
             "nearPairs": 0,
             "important": 9,
             "neverImported": 0,
             "components": 316,
-            "paintTin": 67,
-            "doorOverrides": 18
+            "paintTin": 66,
+            "doorOverrides": 1
           }
         },
         {
@@ -2368,13 +2368,13 @@
             "shadows": 0,
             "exactDuplicates": 1,
             "inlineStyles": 11,
-            "arbitrary": 126,
+            "arbitrary": 113,
             "nearPairs": 2,
             "important": 0,
             "neverImported": 100,
             "components": 272,
             "paintTin": 33,
-            "doorOverrides": 17
+            "doorOverrides": 4
           }
         },
         {
@@ -2395,13 +2395,13 @@
             "shadows": 0,
             "exactDuplicates": 16,
             "inlineStyles": 74,
-            "arbitrary": 245,
+            "arbitrary": 204,
             "nearPairs": 18,
             "important": 0,
             "neverImported": 44,
             "components": 811,
             "paintTin": 62,
-            "doorOverrides": 22
+            "doorOverrides": 6
           }
         },
         {
@@ -2422,13 +2422,13 @@
             "shadows": 6,
             "exactDuplicates": 61,
             "inlineStyles": 24,
-            "arbitrary": 169,
+            "arbitrary": 113,
             "nearPairs": 8,
             "important": 55,
             "neverImported": 2,
             "components": 1085,
             "paintTin": 296,
-            "doorOverrides": 31
+            "doorOverrides": 26
           }
         },
         {
@@ -2449,13 +2449,13 @@
             "shadows": 0,
             "exactDuplicates": 102,
             "inlineStyles": 120,
-            "arbitrary": 163,
+            "arbitrary": 148,
             "nearPairs": 11,
             "important": 0,
             "neverImported": 5,
             "components": 1137,
             "paintTin": 5,
-            "doorOverrides": 16
+            "doorOverrides": 1
           }
         },
         {
@@ -2476,13 +2476,13 @@
             "shadows": 0,
             "exactDuplicates": 17,
             "inlineStyles": 22,
-            "arbitrary": 38,
+            "arbitrary": 25,
             "nearPairs": 1,
             "important": 0,
             "neverImported": 19,
             "components": 700,
             "paintTin": 100,
-            "doorOverrides": 3
+            "doorOverrides": 1
           }
         },
         {
@@ -2492,7 +2492,7 @@
           "baseColor": "gray",
           "tailwind": "3",
           "codeFiles": 1379,
-          "ownFiles": 531,
+          "ownFiles": 534,
           "metrics": {
             "colors": 66,
             "greys": 14,
@@ -2503,13 +2503,13 @@
             "shadows": 1,
             "exactDuplicates": 20,
             "inlineStyles": 47,
-            "arbitrary": 386,
+            "arbitrary": 360,
             "nearPairs": 7,
             "important": 42,
             "neverImported": 13,
             "components": 777,
-            "paintTin": 491,
-            "doorOverrides": 55
+            "paintTin": 488,
+            "doorOverrides": 32
           }
         },
         {
@@ -2519,7 +2519,7 @@
           "baseColor": "slate",
           "tailwind": "3",
           "codeFiles": 2120,
-          "ownFiles": 340,
+          "ownFiles": 350,
           "metrics": {
             "colors": 254,
             "greys": 52,
@@ -2530,13 +2530,13 @@
             "shadows": 0,
             "exactDuplicates": 21,
             "inlineStyles": 5,
-            "arbitrary": 128,
+            "arbitrary": 99,
             "nearPairs": 21,
             "important": 9,
             "neverImported": 0,
             "components": 911,
-            "paintTin": 183,
-            "doorOverrides": 15
+            "paintTin": 179,
+            "doorOverrides": 3
           }
         },
         {
@@ -2557,13 +2557,13 @@
             "shadows": 0,
             "exactDuplicates": 25,
             "inlineStyles": 42,
-            "arbitrary": 101,
+            "arbitrary": 88,
             "nearPairs": 0,
             "important": 0,
             "neverImported": 1,
             "components": 246,
             "paintTin": 42,
-            "doorOverrides": 13
+            "doorOverrides": 4
           }
         },
         {
@@ -2584,13 +2584,13 @@
             "shadows": 0,
             "exactDuplicates": 14,
             "inlineStyles": 47,
-            "arbitrary": 385,
+            "arbitrary": 366,
             "nearPairs": 10,
             "important": 12,
             "neverImported": 0,
             "components": 1204,
             "paintTin": 21,
-            "doorOverrides": 26
+            "doorOverrides": 0
           }
         },
         {
@@ -2611,13 +2611,13 @@
             "shadows": 10,
             "exactDuplicates": 65,
             "inlineStyles": 58,
-            "arbitrary": 614,
+            "arbitrary": 569,
             "nearPairs": 16,
             "important": 42,
             "neverImported": 30,
             "components": 1494,
             "paintTin": 58,
-            "doorOverrides": 28
+            "doorOverrides": 2
           }
         },
         {
@@ -2638,13 +2638,13 @@
             "shadows": 2,
             "exactDuplicates": 104,
             "inlineStyles": 117,
-            "arbitrary": 1673,
+            "arbitrary": 1186,
             "nearPairs": 21,
             "important": 0,
             "neverImported": 26,
             "components": 971,
             "paintTin": 32,
-            "doorOverrides": 44
+            "doorOverrides": 1
           }
         },
         {
@@ -2665,13 +2665,13 @@
             "shadows": 14,
             "exactDuplicates": 288,
             "inlineStyles": 263,
-            "arbitrary": 1625,
+            "arbitrary": 1602,
             "nearPairs": 59,
             "important": 93,
             "neverImported": 23,
             "components": 3630,
             "paintTin": 8,
-            "doorOverrides": 16
+            "doorOverrides": 0
           }
         }
       ]

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

@@ -31,8 +31,8 @@ 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';
-import { profileOf } from '../profiles/index.mjs';
+import { loadBenchmark, benchHelpers, makeHealthOf, coreMetrics, tileHealths, scoreOfTiles, scoreBreakdown, scorePackage as scorePackageOf, ZERO_IDEAL, WARN_TOLERANCE, SCORE_OF, SCHEMA_VERSION } from './score.mjs';
+import { profileOf, installedDirs, splitArbitrary } from '../profiles/index.mjs';
 
 // The benchmark and every judgement made against it live in score.mjs; this
 // file only draws. The same numbers reach summary.json through scoreHarvest.
@@ -234,7 +234,7 @@ const typefaces = distinctTypefaces(fontFamilies);
 const { colorTokens, colorStrays, tokenLed, greyStrays } = M;
 
 // Arbitrary bracket values (p-[13px], text-[10px]) — scale erosion, counted.
-const arbitrary = h.tokens.tailwind?.arbitrary ?? [];
+let arbitrary = h.tokens.tailwind?.arbitrary ?? [];
 const arbitraryCount = M.arbitrary;
 
 // !important declarations: the cascade admitting defeat.
@@ -248,6 +248,10 @@ const nearPairs = nearColorPairs(colors);
 const collisions = h.tokens.tokenCollisions ?? [];
 
 const P = profileOf(h);
+// On a shadcn repo the bracket list is the team's own; installed brackets are
+// named in the side panel instead (see coreMetrics for the count).
+if (P.isShadcn) arbitrary = splitArbitrary(arbitrary, installedDirs(P)).own;
+const breakdown = scoreBreakdown(h, bench);
 const neverImported = neverImportedComponents(h.components, P.uiDir);
 
 // Measurability and kind, decided once in profiles/ (telekom/scale, 2026-09-01):
@@ -339,7 +343,7 @@ 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: '1 colour recorded twice',
   important: 'forces a style through', neverImported: 'the system nobody found', arbitrary: 'a handful of deliberate exceptions',
-  paintTin: 'the theme file already has a variable for it', doorOverrides: 'use a variant instead',
+  paintTin: 'the theme file already has a variable for it', doorOverrides: 'use a variant, or add one',
 };
 // Dress one judged tile for the page: formatted number, comparison rows.
 // Accepts a judged tile from score.mjs, or the positional form the
@@ -549,7 +553,9 @@ function collisionsTrap() {
   return trapBox(`--${esc(top.name)} is ${where(a)}, and ${where(b)}. One name, two colours, and nothing in the code says which is the real one. An agent reads whichever package it opened, so the brand depends on where it started.${rest}`);
 }
 function orphansTrap() {
-  if (!componentsMeasured || isLibrary) return '';
+  // Catalogue stock is protective, not a trap: an agent reaches for it
+  // instead of building its own version (Sahaj Jain, 2026-09-09).
+  if (!componentsMeasured || isLibrary || vendoredUi) return '';
   if (neverImported.length < 10) return '';
   return trapBox(`${neverImported.length} components are never imported anywhere. An agent searching for a Button finds the unused ones next to the real one with nothing to tell them apart, so an old dead end becomes today's example.`);
 }
@@ -607,7 +613,8 @@ function sheetSection() {
     parts.push(`<div class="receipts">${eyebrow(`${n(paint.tin.uses)} colours from outside the theme in ${n(paint.tin.files)} of ${n(paint.ownFiles)} own files · ${n(paint.tin.per100)} per 100 files`)}${paint.tin.uses ? `<div class="chips-row">${tinChips}</div><div class="chips-row">${tinFiles}</div>` : '<p class="sub">Your own code takes every colour from the theme file. This is what shadcn is designed for.</p>'}${rp?.tinUses ? `<p class="sub">Not counted above: ${n(rp.tinUses)} palette colour${rp.tinUses === 1 ? '' : 's'} inside ${esc(rp.dirs.map((d) => basename(d)).join(', '))}, installed by a registry rather than written here. An agent reading those files will still copy them.</p>` : ''}</div>`);
     parts.push(whyToggle('paintTin'));
     const doorChips = (paint.doors.samples ?? []).slice(0, 6).map((s) => `<span class="vchip bad">${esc(s.value)} ×${s.count}</span>`).join('');
-    parts.push(`<div class="receipts">${eyebrow(`${n(paint.doors.uses)} shadcn components restyled through className · ${n(paint.doors.per100)} per 100 files`)}${paint.doors.uses ? `<div class="chips-row">${doorChips}</div>` : '<p class="sub">No shadcn component is given a colour or a font through className. Variants are doing their job.</p>'}</div>`);
+    const typoChips = (paint.typo?.samples ?? []).slice(0, 6).map((s) => `<span class="vchip">${esc(s.value)} ×${s.count}</span>`).join('');
+    parts.push(`<div class="receipts">${eyebrow(`${n(paint.doors.uses)} shadcn components recoloured through className · ${n(paint.doors.per100)} per 100 files`)}${paint.doors.uses ? `<div class="chips-row">${doorChips}</div>` : '<p class="sub">No shadcn component is given a colour through className. Variants are doing their job.</p>'}${paint.typo?.uses ? `<p class="sub" style="margin-top:10px">Shown, not scored: ${n(paint.typo.uses)} shadcn components given a text size or weight through className, ${n(paint.typo.per100)} per 100 files. shadcn asks for a variant here too, but every shadcn repo does this at the same rate, so it says nothing about yours.</p><div class="chips-row">${typoChips}</div>` : ''}</div>`);
     parts.push(whyToggle('doorOverrides'));
   }
   if (!parts.length) return '';
@@ -975,9 +982,15 @@ function extraSectionsHtml() {
 // buttons hold, published in --summary so the MCP server's roast-fix prompt
 // hands out byte-identical text. One composer, two doors.
 let startMoves = [];
+let startProjection = null;
 
 function whereToStartSection() {
   const c = [];
+  if (P.isShadcn && (P.shadcn?.sheet?.customUnused ?? []).length) {
+    const dead = P.shadcn.sheet.customUnused;
+    c.push({ score: 40, metric: null, title: `Delete the ${dead.length} theme variable${dead.length === 1 ? '' : 's'} nothing uses`,
+      sub: `${dead.slice(0, 3).map((r) => `--${esc(r)}`).join(', ')}${dead.length > 3 ? ' and more' : ''} sit in ${esc(P.shadcn.sheet.file)} next to the real theme, and nothing in the repo reads them. An agent opening that file sees 2 colour systems and can not tell which one is dead. ${dead.length * 2} lines to delete; the cheapest fix on this page.` });
+  }
   if (agentFiles.length === 0) c.push({ score: 60, metric: null, title: 'Write the agent rules file',
     sub: `No CLAUDE.md, no AGENTS.md. One page naming the canonical components and the tokens file stops your agent guessing on every UI change. Cheapest fix on this list.` });
   if (componentsMeasured && hardDupes.length > 0) {
@@ -1075,8 +1088,8 @@ function whereToStartSection() {
     if (pt.doors.uses >= 5) {
       const s0 = pt.doors.samples[0];
       c.push({ score: 15 + pt.doors.per100 / 4, metric: 'doorOverrides', after: 0,
-        title: `Stop restyling shadcn components through className`,
-        sub: `${n(pt.doors.uses)} shadcn components receive a colour or a font through className, like ${esc(s0.value)}. Use the variant that does it, or add one to the component you own. className on a shadcn component is for layout only.` });
+        title: `Stop recolouring shadcn components through className`,
+        sub: `${n(pt.doors.uses)} shadcn components receive a colour through className, like ${esc(s0.value)}. Use the variant that does it, or add one to the component you own. className on a shadcn component is for layout only.` });
     }
   }
 
@@ -1100,6 +1113,7 @@ function whereToStartSection() {
   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);
+  startProjection = { count: top3.length, after };
   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>`
@@ -1265,9 +1279,7 @@ function shadcnReceipt() {
   ].filter(Boolean);
   const unmatched = (k?.fellBack ?? []).filter((f) => f === 'theme' || f === 'chartColor');
   const fell = unmatched.length ? ` · ${unmatched.length === 2 ? 'accent and chart colour' : unmatched[0] === 'theme' ? 'accent' : 'chart colour'} not matched to a named shadcn theme` : '';
-  const rp = P.shadcn?.registryPaint ?? null;
-  const regLine = rp ? `<div class="excl">Installed registries kept out of the own-code counts: ${esc(rp.dirs.map((d) => basename(d)).join(', '))} (${n(rp.files)} file${rp.files === 1 ? '' : 's'}${rp.tinUses ? `, ${n(rp.tinUses)} palette colour${rp.tinUses === 1 ? '' : 's'} of their own` : ''}). Installed code, not written here, but your agent reads it like everything else and copies what it finds there.</div>` : '';
-  return `<div class="excl">Read as a shadcn install (${esc(P.confidence ?? 'medium')} confidence): ${esc(P.evidence.join(' · '))}${facts.length ? ` · ${esc(facts.join(', '))}` : ''}${esc(fell)}</div>${regLine}`;
+  return `<div class="excl">Read as a shadcn install (${esc(P.confidence ?? 'medium')} confidence): ${esc(P.evidence.join(' · '))}${facts.length ? ` · ${esc(facts.join(', '))}` : ''}${esc(fell)}</div>`;
 }
 
 // User exclusions are printed in the header, never hidden: a scoped scan must
@@ -1286,6 +1298,85 @@ function exclusionsLine() {
   return `<div class="excl">${parts.join(' · ')} · ${n(total)} files kept out of this scan</div>`;
 }
 
+
+// ---------- the side panel (fixed left column, 2026-09 template) ----------
+// Score, the definition it measures, the stack, how the repo was read, the
+// index of what rendered, and what is not the team's and not counted.
+function sidePanel() {
+  const date = esc((h.harvestedAt ?? '').slice(0, 10));
+  const def = 'How safely an AI agent can build on this repo without going off-system.';
+  const lift = startProjection && healthScore !== null && startProjection.after > healthScore
+    ? ` <b>${['One fix lifts', 'Two fixes lift', 'Three fixes lift'][startProjection.count - 1] ?? 'The fixes lift'} it to ${startProjection.after}.</b>` : '';
+  const rp = P.shadcn?.registryPaint ?? null;
+  const bd = breakdown.ownScore !== null && breakdown.installedPoints > 0 && rp
+    ? `<div class="bd">Of which <b>${breakdown.installedPoints} point${breakdown.installedPoints === 1 ? '' : 's'}</b> come from installed code you did not write: ${esc(rp.dirs.map((d) => basename(d)).join(', '))} (${n(rp.files)} file${rp.files === 1 ? '' : 's'}, ${n(rp.tinUses)} palette colour${rp.tinUses === 1 ? '' : 's'}). Your own code alone would score <b>${breakdown.ownScore}</b>. Kept in the score because your agent reads those files like everything else; left out of the fixes because they are not yours to edit.</div>` : '';
+  const scoreBlock = healthScore !== null
+    ? `<div class="score${noSystemLikely ? ' muted' : ''}">${eyebrow('Health score')}<div class="val">${healthScore}<span class="slash">/</span><span class="of">100</span></div>${noSystemLikely ? '<div class="note">little here to score · see the note</div>' : ''}<div class="def">${def}${lift}</div>${bd}</div>` : '';
+  const chips = `<div class="chips">${stack.map((c) => `<span class="chip">${esc(c)}</span>`).join('')}${dsUnrecognised ? '<span class="chip chip-dim">design system: unrecognised</span>' : ''}${legacyChip ? `<span class="chip chip-dim">${esc(legacyChip)}</span>` : ''}${agentFiles.map((c) => `<span class="chip chip-agent">${esc(c.file)}</span>`).join('')}</div>`;
+  const facts = [
+    shadcnReceipt(),
+    exclusionsLine(),
+    commissionedBy ? `<div class="excl">Commissioned by <b>${esc(commissionedBy)}</b></div>` : '',
+  ].join('');
+  return `<aside class="side">
+  <div class="eyebrow">Design-system diagnosis</div>
+  <div class="repo"><span class="mono">${esc(repoName)}</span></div>
+  <div class="scanned">Scanned ${date} · ${n(h.files.code)} code files · ${h.tookMs}ms</div>
+  ${scoreBlock}
+  ${chips}
+  <div class="facts">${facts}</div>
+  <div class="eyebrow idx-head">Index</div>
+  <nav class="idx" id="idx"></nav>
+  ${exceptionsBlock()}
+  <div class="side-foot">roast-my-design-system ${VERSION}</div>
+</aside>`;
+}
+
+// What is not the team's, and how it is treated. Every exclusion is named
+// here with what it carries and the honest caveat: the agent reads it anyway.
+function exceptionsBlock() {
+  const lines = [];
+  if (P.isShadcn) {
+    const ai = P.shadcn?.arbitraryInstalled;
+    if (ai?.uses) lines.push(`${n(ai.uses)} bracket value${ai.uses === 1 ? '' : 's'} inside ${esc(P.uiDirs.map((d) => basename(d)).join(', '))} are shadcn's own (${ai.values.slice(0, 3).map((v) => esc(v.value)).join(', ')}) and are not counted. shadcn's docs allow brackets for one-off values, so your agent will treat them as normal; the rules file tells it otherwise for your own code.`);
+    if (vendoredUi && neverImported.length) lines.push(`${n(neverImported.length)} catalogue component${neverImported.length === 1 ? '' : 's'} not used yet: stock on the shelf, not scored.`);
+    const rp = P.shadcn?.registryPaint;
+    if (rp) lines.push(`Installed registr${rp.dirs.length === 1 ? 'y' : 'ies'} ${esc(rp.dirs.map((d) => basename(d)).join(', '))}: ${n(rp.files)} file${rp.files === 1 ? '' : 's'}${rp.tinUses ? `, ${n(rp.tinUses)} palette colour${rp.tinUses === 1 ? '' : 's'}` : ''}. Kept in the score, left out of the fixes. Your agent reads them like everything else.`);
+  } else if (isLibrary) {
+    lines.push('A library: unused components are internal-only, and downstream consumers are invisible from here.');
+  }
+  if (!lines.length) return '';
+  return `<div class="excs"><b>Not yours, and not counted</b>${lines.map((l) => `<p>${l}</p>`).join('')}</div>`;
+}
+
+// The index is built from what rendered: every section with a heading gets
+// a stable id, in page order, and the side panel lists them. Nothing here is
+// hand-maintained, so a section that did not render is never listed.
+function addIndex(page) {
+  // heading text is already HTML-escaped; strip tags and leading counts only
+  const short = (t) => t.replace(/<[^>]+>/g, '').replace(/\s+/g, ' ').trim().replace(/^[\d,]+ /, '')
+    .replace(/^What your AI agent sees today$/, 'What your agent sees').replace(/^You sat through the roast$/, 'Your present')
+    .replace(/^The shadcn theme and the 2 shadcn checks$/, 'shadcn theme and checks').replace(/, declared .*$/, '')
+    .replace(/^off-scale spacing values$/, 'Off-scale spacing').replace(/^inline style blocks?$/, 'Inline styles').replace(/^typefaces?$/, 'Typefaces');
+  const entries = [];
+  let i = 0;
+  const body = page.replace(/<section\b([^>]*)>([\s\S]*?)(?=<section\b|<footer>|<\/main>)/g, (m, attrs, inner) => {
+    const h2 = inner.match(/<h2>([\s\S]*?)<\/h2>/);
+    if (!h2) return m;
+    i += 1;
+    let id = (attrs.match(/\bid="([^"]+)"/) ?? [])[1];
+    let open = attrs;
+    if (!id) { id = `s-${i}`; open = ` id="${id}"${attrs}`; }
+    entries.push({ id, text: short(h2[1]) });
+    return `<section${open}>${inner}`;
+  });
+  const nav = entries.map((e, k) => `<a href="#${e.id}"><i>${String(k + 1).padStart(2, '0')}</i>${e.text}</a>`).join('');
+  return body.replace('<nav class="idx" id="idx"></nav>', `<nav class="idx" id="idx">${nav}</nav>`);
+}
+
+// Rendered first: the side panel quotes its projection.
+const whereToStartHtml = whereToStartSection();
+
 const html = `<!doctype html>
 <html lang="en" data-theme="${themeName}"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
@@ -1302,7 +1393,34 @@ const html = `<!doctype html>
   /* fixed gradient wash on its own layer: background-attachment:fixed +
      backdrop-filter makes Chromium skip repaints on scroll */
   body::before { content:''; position:fixed; inset:0; z-index:-1; background:var(--page-grad), var(--bg); }
-  .wrap { max-width:1120px; margin:0 auto; padding:48px 28px 72px; }
+  .wrap { zoom:0.9; }
+  /* two columns: a fixed side panel and the scrolling main column */
+  .side { position:fixed; left:0; top:0; bottom:0; width:300px; padding:22px 24px; overflow:auto; z-index:5;
+    border-right:1px solid var(--line); background:var(--card-solid, var(--bg)); }
+  .main { margin-left:300px; padding:22px 40px 60px; max-width:1080px; }
+  .side .repo { font:600 20px/1.25 var(--disp); letter-spacing:-.01em; margin:4px 0 4px; word-break:break-all; }
+  .side .repo .mono { font-size:17px; }
+  .side .scanned { font:500 11.5px/1.5 var(--sans); color:var(--dim); margin:0 0 16px; }
+  .side .score { text-align:left; margin:0 0 16px; }
+  .side .score .def { font:500 11.5px/1.5 var(--sans); color:var(--dim); margin-top:8px; }
+  .side .score .def b { color:var(--text); font-weight:700; }
+  .side .score .bd { font:500 11.5px/1.5 var(--sans); color:var(--dim); margin-top:8px; padding-top:8px; border-top:1px solid var(--line); }
+  .side .score .bd b { color:var(--text); }
+  .side .chips { margin:0 0 14px; gap:5px; }
+  .side .facts { font:500 11.5px/1.55 var(--sans); color:var(--dim); margin-bottom:16px; }
+  .side .facts .excl { margin-top:6px; font-size:11.5px; }
+  .side .facts b { color:var(--text); font-weight:600; }
+  .side .idx-head { margin-bottom:4px; }
+  .side .idx a { display:block; font:500 13px/1.3 var(--sans); color:var(--dim); text-decoration:none; padding:6px 0 6px 12px; border-left:2px solid var(--line); }
+  .side .idx a:hover, .side .idx a.on { color:var(--accent); border-left-color:var(--accent); }
+  .side .idx a i { font-style:normal; font-size:10.5px; margin-right:8px; opacity:.6; }
+  .side .excs { margin-top:16px; padding-top:12px; border-top:1px solid var(--line); font:500 11.5px/1.55 var(--sans); color:var(--dim); }
+  .side .excs b { color:var(--text); display:block; margin-bottom:4px; }
+  .side .excs p { margin:0 0 6px; }
+  .side .side-foot { margin-top:18px; font:500 11px/1.5 var(--sans); color:var(--dim2, var(--dim)); }
+  .main > .verdict-card { margin-top:0; }
+  @media (max-width: 900px) { .side { position:static; width:auto; border-right:0; border-bottom:1px solid var(--line); } .main { margin-left:0; padding:20px; } }
+  @media print { .side { position:static; width:auto; border-right:0; } .main { margin-left:0; } .wrap { zoom:1; } }
 
   .glass { background:var(--card); backdrop-filter:blur(24px) saturate(140%); -webkit-backdrop-filter:blur(24px) saturate(140%);
     border:1px solid var(--line); border-radius:16px;
@@ -1344,8 +1462,8 @@ const html = `<!doctype html>
 
   .chips { display:flex; flex-wrap:wrap; gap:8px; margin-top:18px; }
   .chip { border:1px solid var(--line); background:var(--card); border-radius:99px;
-    padding:4px 12px; font:500 11.5px/1.5 var(--sans); color:var(--text); }
-  .chip-agent { background:var(--text); color:var(--bg); border-color:var(--text); font-weight:600; }
+    padding:3px 8px; font:500 10.5px/1.5 var(--sans); color:var(--text); }
+  .chip-agent { font-weight:600; }
   .coverage { margin-top:12px; }
   .cov-yes { color:var(--ok); font-weight:700; }
   .cov-no { color:var(--coral); font-weight:700; }
@@ -1681,32 +1799,20 @@ const html = `<!doctype html>
 </button>
 <script>try{var t=localStorage.getItem('roast-theme');if(t==='light'||t==='dark')document.documentElement.setAttribute('data-theme',t)}catch(e){}</script>
 <div class="wrap">
-
-<header>
-  <div class="hero">
-    <div>
-      <div class="kicker"><span class="dot"></span>Scan complete · ${h.tookMs}ms · ${n(h.files.code)} code files</div>
-      <h1>Design System Diagnosis</h1>
-      <div class="meta"><span class="mono">${esc(repoName)}</span> · scanned ${esc((h.harvestedAt ?? '').slice(0, 10))}${commissionedBy ? ` · commissioned by ${esc(commissionedBy)}` : ''}</div>
-    </div>
-    ${healthScore !== null ? `<div class="score${noSystemLikely ? ' muted' : ''}">${eyebrow('Health score')}<div class="val">${healthScore}<span class="slash">/</span><span class="of">100</span></div>${noSystemLikely ? '<div class="note">little here to score · see the note below</div>' : ''}</div>` : ''}
-  </div>
-  <div class="chips">${stack.map((s) => `<span class="chip">${esc(s)}</span>`).join('')}${dsUnrecognised ? '<span class="chip chip-dim">design system: unrecognised</span>' : ''}${legacyChip ? `<span class="chip chip-dim">${esc(legacyChip)}</span>` : ''}${agentFiles.map((c) => `<span class="chip chip-agent">${esc(c.file)}</span>`).join('')}</div>
-  ${shadcnReceipt()}
-  ${exclusionsLine()}
+${sidePanel()}
+<main class="main">
   ${noSystemLikely ? `<div class="nods">${ICONS.warn}<span>There is most likely <b>no design system in this repo</b>: almost no colour or spacing values were found. Styling may live outside this codebase (CDN stylesheets, a parent repo, or generated output).</span></div>` : ''}
   <div class="glass verdict-card">
     <div class="blob b1"></div><div class="blob b2"></div>
     ${eyebrow('Summary')}
     <div class="verdict">${esc(verdict)}</div>
   </div>
-</header>
 
 ${notesSection()}
 
 ${extraSectionsHtml()}
 
-${whereToStartSection()}
+${whereToStartHtml}
 
 ${agentSection()}
 
@@ -1737,6 +1843,7 @@ ${componentsSection()}
   </div>
   <span class="creds"><span>Non-destructive scan</span><span>Read-only</span><span>Paths are real</span></span>
 </footer>
+</main>
 <script>
 (function(){
   var gift=document.getElementById('gift'); if(!gift) return;
@@ -1831,7 +1938,7 @@ ${componentsSection()}
 </script>
 </div></body></html>`;
 
-writeFileSync(outPath, html);
+writeFileSync(outPath, addIndex(html));
 
 // Machine-readable summary for wrappers (the npx CLI reads this instead of
 // parsing the HTML): --summary <path> writes score, verdict and per-tile health.
@@ -1849,6 +1956,7 @@ if (summaryPath) {
     ...(extraSections.length ? { sectionsEmbedded: extraSections.map((s) => s.title) } : {}),
     ...(h.exclusions ? { exclusions: h.exclusions } : {}),
     score: healthScore,
+    ...(breakdown.ownScore !== null ? { ownCodeScore: breakdown.ownScore, installedPoints: breakdown.installedPoints } : {}),
     noSystemLikely,
     verdict,
     role: P.role,

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

@@ -26,7 +26,7 @@ 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';
-import { profileOf } from '../profiles/index.mjs';
+import { profileOf, installedDirs, splitArbitrary } from '../profiles/index.mjs';
 
 export { SCHEMA_VERSION };
 
@@ -102,7 +102,7 @@ export function makeHealthOf(b) {
 export const PROFILE_TILES = {
   shadcn: [
     ['paintTin', 'off-theme colours per 100 files'],
-    ['doorOverrides', 'components restyled from outside per 100 files'],
+    ['doorOverrides', 'components recoloured from outside per 100 files'],
   ],
 };
 export const tilesFor = (kind) => [...TILES, ...(PROFILE_TILES[kind] ?? [])];
@@ -124,7 +124,14 @@ export const TILES = [
  * 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) {
+export function coreMetrics(h, opts = {}) {
+  const P = profileOf(h);
+  // On a shadcn repo the bracket count is the team's own: brackets inside the
+  // catalogue, kit blocks and registries are installed choices, not drift.
+  const arbitraryEntries = P.isShadcn ? splitArbitrary(h.tokens?.tailwind?.arbitrary ?? [], installedDirs(P)).own : (h.tokens?.tailwind?.arbitrary ?? []);
+  // ownCode: the breakdown under the score. Same metrics, paint counted on
+  // own code only, so the difference is what installed registries cost.
+  const paint = opts.ownCode ? (P.shadcn?.paintOwn ?? P.shadcn?.paint) : P.shadcn?.paint;
   const colors = h.tokens?.colors ?? [];
   const greys = colors.filter((c) => isGrey(c.value));
   const colorTokens = colors.filter((c) => c.isToken).length;
@@ -151,7 +158,7 @@ export function coreMetrics(h) {
     nearPairs: nearColorPairs(colors).length,
     important: h.tokens?.important?.count ?? 0,
     neverImported: neverImportedComponents(h.components, profileOf(h).uiDir).length,
-    arbitrary: (h.tokens?.tailwind?.arbitrary ?? []).reduce((sum, a) => sum + a.count, 0),
+    arbitrary: arbitraryEntries.reduce((sum, a) => sum + a.count, 0),
     // Measurability and kind, decided once in profiles/: 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.
@@ -163,11 +170,26 @@ export function coreMetrics(h) {
     // utility-class mode (components.json cssVariables: false): the palette IS
     // the theme by design, so a palette class is not paint from a tin
     utilityPalette: profileOf(h).designSystem?.cssVariables === false,
-    paintTin: profileOf(h).shadcn?.paint?.tin?.per100 ?? 0,
-    doorOverrides: profileOf(h).shadcn?.paint?.doors?.per100 ?? 0,
+    paintTin: paint?.tin?.per100 ?? 0,
+    doorOverrides: paint?.doors?.per100 ?? 0,
   };
 }
 
+/**
+ * The score as the agent meets the repo, and the score own code alone would
+ * earn. The difference is what installed code the team did not write costs.
+ * ownScore is null when nothing installed carries any weight (no registries).
+ */
+export function scoreBreakdown(h, bench = loadBenchmark()) {
+  const b = benchHelpers(bench, profileOf(h).kind);
+  const healthOf = makeHealthOf(b);
+  const all = scoreOfTiles(tileHealths(coreMetrics(h), healthOf));
+  const P = profileOf(h);
+  if (!P.isShadcn || !(P.shadcn?.registryDirs ?? []).length) return { score: all, ownScore: null, installedPoints: 0 };
+  const own = scoreOfTiles(tileHealths(coreMetrics(h, { ownCode: true }), healthOf));
+  return { score: all, ownScore: own, installedPoints: own === null || all === null ? 0 : own - all };
+}
+
 /**
  * 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.

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

@@ -16,9 +16,9 @@ export const WHY = {
     'The ideal is 25 per 100 files. That is where the tidiest third of 15 shadcn repos in the benchmark sit; the median is 62. shadcn\'s own rules for agents say it in 1 line: use semantic colours, never bg-blue-500.',
   ],
   doorOverrides: [
-    'A shadcn component ships with variants: outline, ghost, destructive, small, large. The variant decides how the component looks, once, in the component file you own. Passing bg-blue-100 or font-bold through className decides it again at the call site, where the component can not see it.',
+    'A shadcn component ships with variants: outline, ghost, destructive, small, large. The variant decides how the component looks, once, in the component file you own. Passing bg-blue-100 through className decides it again at the call site, where the component can not see it.',
     'Do this in 5 places and 1 button has 6 designs. The next person can not tell which one is intended, and an agent copies whichever it finds first. shadcn\'s guidance gives 3 routes: use a variant that exists, add a variant to the component, or add a variable to the theme file. className is for layout: width, margin, position.',
-    'The ideal is 15 per 100 files, the tidiest third of the same 15 repos; the median is 22.',
+    'The ideal is 2 per 100 files, the tidiest half of the 16 shadcn repos in the benchmark; the median is 1. Typography through className, a text-sm on an Input, is shown here and not scored: 12 of the 16 repos do it at the same rate, so it separates nothing, and nowhere else in this report does a text size cost points.',
   ],
   colors: [
     'Look, nobody consciously chooses 100 colours to start with. They were added with each change, and the change after that. No one was checking for the drift, because no one expected it. Then come the multipliers: a rebrand, a dark-mode pass, ad hoc files, each one multiplying the values again.',

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

@@ -27,7 +27,7 @@ import { ruleStaleness } from '../lib/staleness.mjs';
 import { neverImportedComponents } from '../lib/neverimported.mjs';
 import { lastTouchedDates } from '../lib/lasttouched.mjs';
 import { SCHEMA_VERSION } from '../lib/version.mjs';
-import { decideProfile, profileOf } from '../profiles/index.mjs';
+import { decideProfile, profileOf, installedDirs, splitArbitrary } from '../profiles/index.mjs';
 import { countPaint } from './paint.mjs';
 
 function arg(name, fallback) {
@@ -58,6 +58,7 @@ const exclusions = loadExclusions(target, argAll('exclude'));
 const files = walkRepo(target, 14, exclusions);
 const profile = profileRepo(target, files);
 const { components } = harvestComponents(target, files.code);
+const tokens = harvestTokens(target, files.styles, files.code);
 // Repo kind and measurability, decided once in profiles/ and read everywhere
 // (a published components package with no app pages is a LIBRARY; a stack the
 // detector cannot read is NOT MEASURED, never scored as zeros). The decision
@@ -68,22 +69,30 @@ decideProfile(profile, components, files, target);
 {
   const P = profileOf(profile);
   if (P.isShadcn) {
-    const installed = [...P.uiDirs, ...(profile.shadcn?.registryDirs ?? [])];
-    const doorFiles = new Set([...installed.flatMap((d) => files.code.filter((f) => f.startsWith(`${d}/`))), ...(profile.shadcn?.blockFiles ?? [])]);
-    const kitNames = new Set(components.filter((c) => doorFiles.has(c.file)).map((c) => c.name));
-    profile.shadcn.paint = countPaint(target, files.code, { uiDirs: [...installed, ...(profile.shadcn.blockFiles ?? [])], kitNames });
-    // what the installed registries carry themselves: kept out of the own-code
-    // counts, shown in the header, because an agent reads them all the same
     const regDirs = profile.shadcn.registryDirs ?? [];
+    const blocks = profile.shadcn.blockFiles ?? [];
+    const allInstalled = installedDirs(P);
+    const doorFiles = new Set(allInstalled.flatMap((d) => files.code.filter((f) => f === d || f.startsWith(`${d}/`))));
+    const kitNames = new Set(components.filter((c) => doorFiles.has(c.file)).map((c) => c.name));
+    // The score reads the repo as the agent meets it: own code plus installed
+    // registries, because a palette colour in ai-elements teaches the same
+    // wrong lesson as one in own code. The catalogue and kit blocks stay out:
+    // editing them is the intended use.
+    profile.shadcn.paint = countPaint(target, files.code, { uiDirs: [...P.uiDirs, ...blocks], kitNames });
+    // Own code alone, for the breakdown line under the score.
+    profile.shadcn.paintOwn = regDirs.length ? countPaint(target, files.code, { uiDirs: allInstalled, kitNames }) : profile.shadcn.paint;
     if (regDirs.length) {
       const regFiles = files.code.filter((f) => regDirs.some((d) => f.startsWith(`${d}/`)));
       const rp = countPaint(target, regFiles, { uiDirs: [], kitNames });
-      profile.shadcn.registryPaint = { files: rp.ownFiles, tinUses: rp.tin.uses, dirs: regDirs };
+      profile.shadcn.registryPaint = { files: rp.ownFiles, tinUses: rp.tin.uses, doorUses: rp.doors.uses, dirs: regDirs };
     }
+    // Bracket values inside installed code are shadcn's (or a registry's)
+    // choices: a true lesson, badly framed. Kept out of the count, named.
+    const split = splitArbitrary(tokens.tailwind?.arbitrary ?? [], allInstalled);
+    profile.shadcn.arbitraryInstalled = split.installed;
   }
 }
 
-const tokens = harvestTokens(target, files.styles, files.code);
 const duplicates = findDuplicates(components, profile.uiDir, target);
 const context = harvestContext(target);
 const staleRules = ruleStaleness(target, components,

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

@@ -6,10 +6,14 @@
  *     row exists: `text-gray-500`, `bg-blue-100`, `text-emerald-600` on a
  *     status, and the manual evening override `dark:bg-gray-950`. 1 sin, 3
  *     spellings. The rule: "Semantic colors. Never `bg-blue-500`."
- *  2. Doors repainted from outside. A colour or typography class passed into
- *     a kit component through className (`<Card className="bg-blue-100
- *     font-bold">`) where a variant or a sheet row was the intended route.
- *     The rule: "className for layout only."
+ *  2. Doors recoloured from outside. A colour class passed into a kit
+ *     component through className (`<Card className="bg-blue-100">`) where
+ *     a variant or a sheet row was the intended route. The rule: "className
+ *     for layout only." Typography through className (`<Input
+ *     className="text-sm">`) is counted separately as a receipt, never
+ *     scored: the 2026-09-13 fleet audit found it on 12 of 16 shadcn repos at
+ *     a flat rate, so it separates nothing, and nowhere else in the report
+ *     does a text size cost points.
  *
  * Both are counted over OWN code only: never inside the catalogue (those are
  * kit doors, edited on purpose), never in exempt files (email, print,
@@ -30,9 +34,10 @@ const TIN_RE = new RegExp(`(?<![\\w-])(?:[\\w-]+:)*(?:bg|text|border|ring|outlin
 // Evening overrides painted by hand with white or black (the palette shades
 // are already caught above with their dark: prefix).
 const DARK_WB_RE = /(?<![\w-])dark:(?:bg|text|border)-(?:white|black)(?:\/\d+)?(?![\w-])/g;
-// Colour or typography passed into a kit door: palette colour, black/white,
-// weight, size.
-const DOOR_CLASS_RE = new RegExp(`(?<![\\w-])(?:[\\w-]+:)*(?:(?:bg|text|border)-(?:${PALETTE}|white|black)(?:-(?:50|[1-9]00|950))?(?:/\\d+)?|font-(?:thin|extralight|light|normal|medium|semibold|bold|extrabold|black)|text-(?:xs|sm|base|lg|xl|[2-9]xl))(?![\\w-])`, 'g');
+// Colour passed into a kit door: palette colour, black, white, any variant prefix.
+const DOOR_COLOR_RE = new RegExp(`(?<![\\w-])(?:[\\w-]+:)*(?:bg|text|border)-(?:${PALETTE}|white|black)(?:-(?:50|[1-9]00|950))?(?:/\\d+)?(?![\\w-])`, 'g');
+// Typography passed into a kit door: weight or size. A receipt, not a score.
+const DOOR_TYPO_RE = /(?<![\w-])(?:[\w-]+:)*(?:font-(?:thin|extralight|light|normal|medium|semibold|bold|extrabold|black)|text-(?:xs|sm|base|lg|xl|[2-9]xl))(?![\w-])/g;
 
 const DEMO_PATH_RE = /(^|\/)(stories|storybook|__stories__|examples?|demos?|templates?|playground|fixtures?|__tests__|__mocks__|e2e|cypress)\//i;
 
@@ -52,6 +57,7 @@ export function countPaint(root, codeFiles, { uiDirs = [], kitNames = new Set()
   let ownFiles = 0;
   const tin = { uses: 0, files: 0, top: [], samples: new Map() };
   const doors = { uses: 0, files: 0, top: [], samples: new Map() };
+  const typo = { uses: 0, files: 0, top: [], samples: new Map() };
   const bump = (bucket, file, count, sample) => {
     bucket.uses += count; bucket.files += 1;
     bucket.top.push({ file, count });
@@ -77,20 +83,28 @@ export function countPaint(root, codeFiles, { uiDirs = [], kitNames = new Set()
     }
 
     if (doorOpen) {
-      let hits = 0; const seen = new Map();
+      let hits = 0, thits = 0; const seen = new Map(), tseen = new Map();
       for (const m of src.matchAll(doorOpen)) {
         const cls = m[2] ?? m[3] ?? '';
-        const bad = cls.match(DOOR_CLASS_RE);
-        if (!bad) continue;
-        hits += 1;
-        const key = `<${m[1]} className="${bad.slice(0, 3).join(' ')}">`;
-        seen.set(key, (seen.get(key) ?? 0) + 1);
+        const colour = cls.match(DOOR_COLOR_RE);
+        if (colour) {
+          hits += 1;
+          const key = `<${m[1]} className="${colour.slice(0, 3).join(' ')}">`;
+          seen.set(key, (seen.get(key) ?? 0) + 1);
+        } else {
+          const t = cls.match(DOOR_TYPO_RE);
+          if (t) { thits += 1; const key = `<${m[1]} className="${t.slice(0, 2).join(' ')}">`; tseen.set(key, (tseen.get(key) ?? 0) + 1); }
+        }
       }
       if (hits) {
         bump(doors, f, hits, null);
         for (const [k, v] of seen) doors.samples.set(k, (doors.samples.get(k) ?? 0) + v);
         doors.top.at(-1).sample = [...seen.entries()].sort((a, b) => b[1] - a[1])[0][0];
       }
+      if (thits) {
+        bump(typo, f, thits, null);
+        for (const [k, v] of tseen) typo.samples.set(k, (typo.samples.get(k) ?? 0) + v);
+      }
     }
   }
 
@@ -101,5 +115,5 @@ export function countPaint(root, codeFiles, { uiDirs = [], kitNames = new Set()
     top: b.top.sort((a, b2) => b2.count - a.count).slice(0, 8),
     samples: [...b.samples.entries()].sort((a, b2) => b2[1] - a[1]).slice(0, 10).map(([value, count]) => ({ value, count })),
   });
-  return { ownFiles, tin: finish(tin), doors: finish(doors) };
+  return { ownFiles, tin: finish(tin), doors: finish(doors), typo: finish(typo) };
 }

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 = '7.3.3';
+export const VERSION = '7.4.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/profiles/index.mjs

@@ -100,3 +100,41 @@ export function profileOf(h) {
   };
 }
 
+/**
+ * Installed code: folders the team did not write. The catalogue, kit blocks
+ * installed into own code, and third-party registries. Under the agent-safety
+ * definition (2026-09-13) installed code splits in two: what teaches a wrong
+ * lesson stays in the score, attributed (registry palette colours); what
+ * teaches a true lesson or none is kept out of the count and named at the top
+ * (shadcn's own bracket values, unused stock).
+ */
+export function installedDirs(P) {
+  const sc = P?.shadcn ?? {};
+  return [...(P?.uiDirs ?? []), ...(sc.registryDirs ?? []), ...(sc.blockFiles ?? [])];
+}
+const underAny = (file, dirs) => dirs.some((d) => file === d || file.startsWith(`${d}/`));
+
+/**
+ * Split bracket-value entries ({value, count, files:[{file,count}]}) into the
+ * team's own uses and installed uses. Own entries keep only own files with
+ * counts re-summed; installed is a flat count with its top values.
+ */
+export function splitArbitrary(entries, dirs) {
+  if (!dirs.length) return { own: entries, installed: { uses: 0, values: [] } };
+  const own = [];
+  const installedValues = new Map();
+  let installedUses = 0;
+  for (const e of entries) {
+    const ownFiles = (e.files ?? []).filter((f) => !underAny(f.file, dirs));
+    const instFiles = (e.files ?? []).filter((f) => underAny(f.file, dirs));
+    const instCount = instFiles.reduce((s, f) => s + f.count, 0);
+    if (instCount) { installedUses += instCount; installedValues.set(e.value, (installedValues.get(e.value) ?? 0) + instCount); }
+    // the file list under an entry is capped, so own is the remainder of the
+    // entry's total, never a sum of the files that happened to be listed
+    const ownCount = e.count - instCount;
+    if (ownCount > 0) own.push({ ...e, count: ownCount, files: ownFiles });
+  }
+  own.sort((a, b) => b.count - a.count);
+  const values = [...installedValues.entries()].sort((a, b) => b[1] - a[1]).map(([value, count]) => ({ value, count }));
+  return { own, installed: { uses: installedUses, values } };
+}

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

@@ -125,7 +125,7 @@ function rowsUnder(css, selector) {
 const norm = (v) => (v ?? '').replace(/\s+/g, ' ').trim();
 
 /** Read the sheet: the CSS file the config names. */
-function readSheet(root, wsRoot, cssPath) {
+function readSheet(root, wsRoot, cssPath, files = null) {
   if (!cssPath) return null;
   const file = [join(wsRoot, cssPath), join(wsRoot, 'src', cssPath)].find((p) => existsSync(p));
   if (!file) return { file: cssPath, found: false };
@@ -146,8 +146,23 @@ function readSheet(root, wsRoot, cssPath) {
   const customUnregistered = themeVars.size
     ? custom.filter((r) => !/^(font|shadow|tracking|spacing|radius|ease|breakpoint|typeset)/.test(r) && !themeVars.has(`color-${r}`))
     : [];
+  // A custom row nothing references anywhere (no var(--x), no class built on
+  // it) is a leftover: the Next.js starter's --foreground-rgb next to the real
+  // --foreground. An agent can not tell which colour system is dead.
+  let customUnused = [];
+  if (files && custom.length) {
+    const rel = file.slice(root.length + 1);
+    const others = [...(files.code ?? []), ...(files.styles ?? [])].filter((f) => f !== rel).slice(0, 4000);
+    const pending = new Set(custom.filter((r) => !/^(font|shadow|tracking|spacing|radius|ease|breakpoint|typeset)/.test(r)));
+    for (const f of others) {
+      if (!pending.size) break;
+      const src = read(join(root, f));
+      for (const r of [...pending]) if (src.includes(`--${r}`) || new RegExp(`[-:]${r}(?![\\w-])`).test(src)) pending.delete(r);
+    }
+    customUnused = [...pending];
+  }
   return {
-    file: file.slice(root.length + 1), found: true, hslEra,
+    file: file.slice(root.length + 1), found: true, hslEra, customUnused,
     lightRows: rows.length, darkRows: dark.size, shadcnPresent, shadcnMissing: SHADCN_ROWS.filter((r) => !light.has(r)),
     known: known.length, custom, missingDark, customMissingDark, customUnregistered, tweakcnPresent,
     spacing, spacingChanged: spacing !== null && norm(spacing) !== FACTORY_SPACING,
@@ -219,7 +234,7 @@ export default {
       }
       const pkg = readJSON(join(wsRoot, 'package.json')) ?? readJSON(join(root, 'package.json')) ?? {};
       const deps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
-      const sheet = readSheet(root, wsRoot, cfg.tailwind?.css);
+      const sheet = readSheet(root, wsRoot, cfg.tailwind?.css, files);
       installs.push({ config: file, uiDir: uiAbs, catalogueNames, kit: readKit(cfg, sheet, deps), sheet });
     }
     const swept = catalogueSweep(root, files);

package/skills/roast-my-design-system/scripts/rules/build.mjs

@@ -176,11 +176,16 @@ if (neverImported.length >= 3) {
     rule('Use the semantic classes the theme gives you (`bg-background`, `text-muted-foreground`, `border-border`), never a palette colour like `bg-blue-500` or `text-gray-600`, and never a hand-written `dark:` colour. The variables already carry both modes.');
     if (paint?.tin?.uses) lines.push(`  (${paint.tin.uses} palette colour${paint.tin.uses === 1 ? '' : 's'} already sit in own code, ${paint.tin.samples.slice(0, 3).map((s) => `\`${s.value}\` ×${s.count}`).join(', ')}; do not add to them.)`);
     rule('Before adding classes to a shadcn component, use one of its variants (`variant="outline"`, `size="sm"`). `className` on a shadcn component is for layout only: width, margin, position. Never colour, never typography.');
-    if (paint?.doors?.uses) lines.push(`  (${paint.doors.uses} shadcn component${paint.doors.uses === 1 ? '' : 's'} already restyled through className, like ${paint.doors.samples.slice(0, 2).map((s) => `\`${s.value}\``).join(' and ')}; do not add to them.)`);
+    if (paint?.typo?.uses) lines.push(`  (${paint.typo.uses} shadcn component${paint.typo.uses === 1 ? '' : 's'} get a text size or weight through className, like ${paint.typo.samples.slice(0, 2).map((s) => `\`${s.value}\``).join(' and ')}; add a size variant instead.)`);
+    if (paint?.doors?.uses) lines.push(`  (${paint.doors.uses} shadcn component${paint.doors.uses === 1 ? '' : 's'} already recoloured through className, like ${paint.doors.samples.slice(0, 2).map((s) => `\`${s.value}\``).join(' and ')}; do not add to them.)`);
     if (sc.registryDirs?.length) rule(`${sc.registryDirs.map((d) => `\`${d}\``).join(', ')} ${sc.registryDirs.length === 1 ? 'is an installed registry' : 'are installed registries'} (added through the shadcn CLI, not written here). Treat ${sc.registryDirs.length === 1 ? 'it' : 'them'} like \`${P.uiDir ?? 'components/ui'}\`: reach for what is there before building your own${sc.registryPaint?.tinUses ? `, and do not copy the ${sc.registryPaint.tinUses} palette colour${sc.registryPaint.tinUses === 1 ? '' : 's'} inside into own code` : ''}.`);
     rule(`Edit the component you own in \`${P.uiDir ?? 'components/ui'}\`. Never build a second one beside it under another name. A wrapper that composes shadcn components is fine; a second implementation is not.`);
     rule('Merge classes with `cn()`. Never concatenate strings and never write a ternary inside a className string.');
     rule('Add a component with `npx shadcn@latest add <name>`, then edit it. To see what changed upstream, run `npx shadcn@latest add <name> --diff`.');
+    const ai = sc.arbitraryInstalled ?? null;
+    if (ai?.uses) rule(`Bracket values in \`${P.uiDir ?? 'components/ui'}\` are shadcn's, not a pattern to copy. The installed components use a few values Tailwind's scale does not have (${ai.values.slice(0, 3).map((v) => `\`${v.value}\``).join(', ')}), written by shadcn's authors for those components only. In your own code, do not write a bracket value: use a step from the scale, or a variable from the theme file. If a value you need is missing, add it to the theme file once and use it by name.`);
+    else rule('In your own code, do not write a bracket value: use a step from the scale, or a variable from the theme file. If a value you need is missing, add it to the theme file once and use it by name.');
+    if (sc.sheet?.customUnused?.length) rule(`${sc.sheet.customUnused.slice(0, 3).map((r) => `\`--${r}\``).join(', ')} in \`${sc.sheet.file}\` ${sc.sheet.customUnused.length === 1 ? 'is' : 'are'} defined and used nowhere. Do not use ${sc.sheet.customUnused.length === 1 ? 'it' : 'them'}; ${sc.sheet.customUnused.length === 1 ? 'it is' : 'they are'} a leftover next to the real theme.`);
     rule('Radius comes from the `--radius` variable and the scale derived from it; never a bracket value. Never change `--spacing`: it resizes every gap in the app.');
     if (sc.sheet?.customUnregistered?.length) rule(`Custom variables must be registered where Tailwind can see them: ${sc.sheet.customUnregistered.slice(0, 3).map((r) => `\`--${r}\``).join(', ')} ${sc.sheet.customUnregistered.length === 1 ? 'is' : 'are'} defined but never mapped in \`@theme inline\`, so \`bg-${sc.sheet.customUnregistered[0]}\` does nothing.`);
     rule('Small habits shadcn expects: `gap-*` not `space-x/y-*`; `size-4` not `w-4 h-4`; `truncate` for one-line clipping; no `z-index` on Dialog, Sheet, Popover or Tooltip, they stack themselves; icons from the project\'s own icon library only.');