roast-my-design-system 7.4.0 → 7.6.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.4.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.6.0" width="72" alt="roast-my-design-system">
 
 # roast-my-design-system
 
@@ -10,6 +10,10 @@
 
 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.6: a fourth repo profile, `registry`.** A repo that publishes a shadcn registry is read as a registry, not as an app that installed shadcn. Recognition: a `registry.json` with typed items (`registry:ui`, `registry:style`, ...) or a route that builds one from a packages folder. Covers shadcn's own source, magicui, kibo-ui and tweakcn. The header states what the repo publishes (components, blocks, styles, demos) and how many variants of the same components it keeps. Scoring is unchanged in this release: a registry is measured with the shadcn tiles against the shadcn slice, and the registry counting rules follow in the next one. `summary.json` gains `kind: "registry"` and a `registry` block. Also in 7.6: the theme file is checked for the variables tweakcn adds to every export, shown as a `tweakcn theme` pill on a match; typefaces declared in a single file are reported as a picker rather than as N typefaces.
+
+> **New in 7.5: the kit is read as it is built, and every file left out of a count is named.** A fresh `npx shadcn create` install is told apart from a repo built on one: "The score is the kit's, not yours." A rules file a framework wrote for itself is named as such, and so is the shadcn skill when it is installed. The theme file is found where it is, even when `components.json` points at a file that moved; `button/index.tsx` is a Button. The repaint advice checks whether the theme file holds the variables before telling you to swap to them. And the side panel now lists everything a check leaves out, with the reason and one honest line: your agent reads it anyway. New on that list: the Next.js crash page, an embedded widget's `!important`, and `!important` aimed at a library's own class names.
+
 > **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.
@@ -79,11 +83,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: 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 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.6.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.4.0)
+![The diagnosis report in light mode](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-light-hero.png?v=7.6.0)
 
 ## What makes the numbers trustworthy
 
@@ -233,12 +237,13 @@ After the roast, the skill also offers to write `design-system-rules.md` to disk
 
 ## Live examples
 
-5 real roasts of public repos, hosted as-is (the same self-contained HTML the skill generates), spanning React, Stencil and Lit:
+7 real roasts of public repos, hosted as-is (the same self-contained HTML the skill generates), spanning React, Stencil and Lit:
 
 - **[telekom/scale](https://gregkozakiewicz.github.io/roast-my-design-system/examples/telekom-scale.html)**: Stencil, 95 components read by tag, with Claude's notes embedded
 - **[adobe/spectrum-web-components](https://gregkozakiewicz.github.io/roast-my-design-system/examples/adobe-spectrum.html)**: Lit, the `--spectrum-*` namespace named in the header
-- **[npx shadcn create, fresh](https://gregkozakiewicz.github.io/roast-my-design-system/examples/shadcn-create-fresh.html)**: a factory install with all 61 components, scanned as is
-- **[vercel/ai-chatbot](https://gregkozakiewicz.github.io/roast-my-design-system/examples/vercel-ai-chatbot.html)**: React, with Claude's notes embedded
+- **[npx shadcn create, fresh](https://gregkozakiewicz.github.io/roast-my-design-system/examples/shadcn-create-fresh.html)**: a factory install with all 61 components, scanned as is and read as fresh
+- **[vercel/ai-chatbot](https://gregkozakiewicz.github.io/roast-my-design-system/examples/vercel-ai-chatbot.html)**: React on shadcn, with Claude's notes embedded
+- **[magicuidesign/magicui](https://gregkozakiewicz.github.io/roast-my-design-system/examples/magicui.html)**: read as a shadcn registry, what it publishes named under the score
 - **[excalidraw/excalidraw](https://gregkozakiewicz.github.io/roast-my-design-system/examples/excalidraw-excalidraw.html)**
 - **[dubinc/dub](https://gregkozakiewicz.github.io/roast-my-design-system/examples/dubinc-dub.html)**
 

package/package.json

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

@@ -1852,7 +1852,7 @@
   },
   "slices": {
     "shadcn": {
-      "builtAt": "2026-09-12T20:07:59.374Z",
+      "builtAt": "2026-09-12T23:43:34.615Z",
       "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": {
@@ -2055,7 +2055,7 @@
             5,
             7,
             11,
-            22,
+            21,
             24,
             42,
             47,
@@ -2129,20 +2129,20 @@
             0,
             0,
             1,
+            1,
             2,
+            4,
             9,
-            9,
-            12,
-            42,
-            42,
-            55,
-            93,
-            157
+            11,
+            14,
+            34,
+            65,
+            126
           ],
           "p25": 0,
-          "median": 6,
-          "p75": 42,
-          "p90": 74
+          "median": 2,
+          "p75": 12,
+          "p90": 50
         },
         "neverImported": {
           "values": [
@@ -2151,7 +2151,7 @@
             0,
             0,
             1,
-            2,
+            3,
             5,
             13,
             19,
@@ -2208,7 +2208,7 @@
             66,
             100,
             179,
-            296,
+            297,
             488
           ],
           "p25": 22,
@@ -2249,7 +2249,7 @@
           "baseColor": "zinc",
           "tailwind": null,
           "codeFiles": 4391,
-          "ownFiles": 811,
+          "ownFiles": 810,
           "metrics": {
             "colors": 310,
             "greys": 66,
@@ -2262,7 +2262,7 @@
             "inlineStyles": 79,
             "arbitrary": 217,
             "nearPairs": 18,
-            "important": 157,
+            "important": 126,
             "neverImported": 99,
             "components": 1453,
             "paintTin": 22,
@@ -2316,7 +2316,7 @@
             "inlineStyles": 2,
             "arbitrary": 5,
             "nearPairs": 0,
-            "important": 2,
+            "important": 1,
             "neverImported": 0,
             "components": 60,
             "paintTin": 57,
@@ -2343,7 +2343,7 @@
             "inlineStyles": 7,
             "arbitrary": 74,
             "nearPairs": 0,
-            "important": 9,
+            "important": 2,
             "neverImported": 0,
             "components": 316,
             "paintTin": 66,
@@ -2411,7 +2411,7 @@
           "baseColor": "slate",
           "tailwind": null,
           "codeFiles": 2604,
-          "ownFiles": 788,
+          "ownFiles": 787,
           "metrics": {
             "colors": 132,
             "greys": 16,
@@ -2424,10 +2424,10 @@
             "inlineStyles": 24,
             "arbitrary": 113,
             "nearPairs": 8,
-            "important": 55,
-            "neverImported": 2,
+            "important": 34,
+            "neverImported": 3,
             "components": 1085,
-            "paintTin": 296,
+            "paintTin": 297,
             "doorOverrides": 26
           }
         },
@@ -2438,7 +2438,7 @@
           "baseColor": "neutral",
           "tailwind": null,
           "codeFiles": 2141,
-          "ownFiles": 775,
+          "ownFiles": 772,
           "metrics": {
             "colors": 174,
             "greys": 38,
@@ -2465,7 +2465,7 @@
           "baseColor": "gray",
           "tailwind": null,
           "codeFiles": 875,
-          "ownFiles": 410,
+          "ownFiles": 409,
           "metrics": {
             "colors": 17,
             "greys": 3,
@@ -2475,7 +2475,7 @@
             "radii": 14,
             "shadows": 0,
             "exactDuplicates": 17,
-            "inlineStyles": 22,
+            "inlineStyles": 21,
             "arbitrary": 25,
             "nearPairs": 1,
             "important": 0,
@@ -2505,7 +2505,7 @@
             "inlineStyles": 47,
             "arbitrary": 360,
             "nearPairs": 7,
-            "important": 42,
+            "important": 14,
             "neverImported": 13,
             "components": 777,
             "paintTin": 488,
@@ -2519,7 +2519,7 @@
           "baseColor": "slate",
           "tailwind": "3",
           "codeFiles": 2120,
-          "ownFiles": 350,
+          "ownFiles": 349,
           "metrics": {
             "colors": 254,
             "greys": 52,
@@ -2586,7 +2586,7 @@
             "inlineStyles": 47,
             "arbitrary": 366,
             "nearPairs": 10,
-            "important": 12,
+            "important": 4,
             "neverImported": 0,
             "components": 1204,
             "paintTin": 21,
@@ -2613,7 +2613,7 @@
             "inlineStyles": 58,
             "arbitrary": 569,
             "nearPairs": 16,
-            "important": 42,
+            "important": 11,
             "neverImported": 30,
             "components": 1494,
             "paintTin": 58,
@@ -2627,7 +2627,7 @@
           "baseColor": "neutral",
           "tailwind": "4",
           "codeFiles": 1775,
-          "ownFiles": 605,
+          "ownFiles": 604,
           "metrics": {
             "colors": 187,
             "greys": 51,
@@ -2667,7 +2667,7 @@
             "inlineStyles": 263,
             "arbitrary": 1602,
             "nearPairs": 59,
-            "important": 93,
+            "important": 65,
             "neverImported": 23,
             "components": 3630,
             "paintTin": 8,

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

@@ -32,7 +32,8 @@ 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, scoreBreakdown, scorePackage as scorePackageOf, ZERO_IDEAL, WARN_TOLERANCE, SCORE_OF, SCHEMA_VERSION } from './score.mjs';
-import { profileOf, installedDirs, splitArbitrary } from '../profiles/index.mjs';
+import { ownSpacing, profileOf, installedDirs, splitArbitrary } from '../profiles/index.mjs';
+import { publishesLine } from '../profiles/registry.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.
@@ -207,9 +208,12 @@ const greys = greysSorted(bgLumOf(THEMES.dark.pageBgHex));
 const greysLight = greysSorted(bgLumOf(THEMES.light.pageBgHex));
 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 (formula in score.mjs, shared with the packages pass).
+// On a kit the off-scale values inside installed folders are shadcn's own:
+// kept out of the tile and the bars (formula in score.mjs), named at the top.
+const P_isShadcn = (x) => profileOf(x).isShadcn;
+const spacingOwn = ownSpacing(h);
+const spacing = spacingOwn.css;
+const twSpacing = P_isShadcn(h) ? [...(h.tokens.tailwind?.spacing ?? []).filter((v) => !v.value.startsWith('[')), ...spacingOwn.tw] : (h.tokens.tailwind?.spacing ?? []);
 const spacingTotal = M.spacing;
 const exactDupes = h.duplicates.exactDuplicates ?? [];
 // A wrapped pair (one file imports the name from the other) is composition,
@@ -248,6 +252,7 @@ const nearPairs = nearColorPairs(colors);
 const collisions = h.tokens.tokenCollisions ?? [];
 
 const P = profileOf(h);
+const fresh = P.isShadcn && P.shadcn?.fresh?.fresh === true;
 // 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;
@@ -281,7 +286,12 @@ const offenders = h.tokens.offenders ?? [];
 const candidates = [];
 const effColors = tokenLed ? colorStrays : colors.length;
 const effGreys = tokenLed ? greyStrays : greys.length;
-if (typefaces.length > 3) candidates.push({ ratio: typefaces.length / 3, text: `${typefaces.length} typefaces. Most products use 2 or 3` });
+// Every typeface declared in one file is a picker (a theme editor's font
+// list, shadcn's docs site): one choice offered, one in use at a time.
+const fontFiles = new Set(fontFamilies.flatMap((f) => (f.files ?? []).map((x) => x.file)));
+const fontPicker = typefaces.length > 3 && fontFiles.size === 1 ? [...fontFiles][0] : null;
+if (fontPicker) candidates.push({ ratio: 1.05, text: `${typefaces.length} typefaces offered by a picker in one file (${basename(fontPicker)}), one in use at a time` });
+else if (typefaces.length > 3) candidates.push({ ratio: typefaces.length / 3, text: `${typefaces.length} typefaces. Most products use 2 or 3` });
 else if (typefaces.length && fontFamilies.length > 6) candidates.push({ ratio: fontFamilies.length / 6, text: `${typefaces.length} typeface${typefaces.length > 1 ? 's' : ''} declared ${fontFamilies.length} different ways` });
 if (effColors > 24 * 1.25) candidates.push({ ratio: effColors / 24, text: tokenLed
   ? `${n(colorStrays)} hardcoded colours outside the token set, your agent will happily copy them at random`
@@ -297,15 +307,18 @@ if (componentsMeasured && hardDupes.length > 0) candidates.push({ ratio: 1 + har
 if (inline.count > 20) candidates.push({ ratio: inline.count / 20, text: `${n(inline.count)} inline style blocks skip the design system. An agent that reads them learns to do the same` });
 if (arbitraryCount >= 20) candidates.push({ ratio: arbitraryCount / 30, text: `${n(arbitraryCount)} values like ${arbitrary[0].value} are written outside the Tailwind scale. An agent that reads them learns to do the same` });
 if (agentFiles.length === 0) candidates.push({ ratio: 1.3, text: `No agent rules file, so your AI agent has nothing to follow` });
-if ((h.staleRules ?? []).length >= 2) candidates.push({ ratio: 1.2 + h.staleRules.length / 10, text: `${h.staleRules.length} lines in your agent rules refer to files that no longer exist` });
+const staleOwn = (h.staleRules ?? []).filter((s) => !s.tool);
+if (staleOwn.length >= 2) candidates.push({ ratio: 1.2 + staleOwn.length / 10, text: `${staleOwn.length} lines in your agent rules refer to files that no longer exist` });
 const findings = candidates.sort((a, b) => b.ratio - a.ratio).map((c) => c.text);
 
-let verdict = findings.length === 0
+let verdict = fresh
+  ? 'A fresh shadcn install with nothing built on it yet. Everything below describes the kit you are starting from.'
+  : findings.length === 0
   ? (agentFiles.length > 0
     ? 'This repo is in good shape, and your agent has rules to read. Keep them in step with the code.'
     : 'This repo is in good shape. The gap is documentation: your agent still can\'t see the system.')
   : findings.slice(0, 3).join('. ') + '.';
-if (bench && findings.length) {
+if (bench && findings.length && !fresh) {
   const core = [['colors', tokenLed ? colorStrays : colors.length], ['greys', tokenLed ? greyStrays : greys.length],
     ['spacing', spacingTotal], ['typefaces', typefaces.length], ['exactDuplicates', hardDupes.length], ['inlineStyles', inline.count]];
   const worse = core.filter(([m, v]) => median(m) !== null && v > median(m)).length;
@@ -595,12 +608,12 @@ function sheetSection() {
   const sheet = sc.sheet, paint = sc.paint;
   const parts = [];
   if (sheet?.found) {
-    const bits = [`${n(sheet.lightRows)} variables for light, ${n(sheet.darkRows)} for dark in ${esc(sheet.file)}`];
+    const bits = [`${n(sheet.lightRows)} variables for light, ${n(sheet.darkRows)} for dark in ${esc(sheet.file)}${sheet.scope ? ` under ${esc(sheet.scope)}` : ''}${sheet.configured && sheet.configured !== sheet.file ? ` (components.json names ${esc(sheet.configured)}, ${sheet.configuredFound ? 'which holds no theme rows' : 'which does not exist'})` : ''}`];
     if (sheet.hslEra) bits.push('written in the Tailwind 3 form (hsl triplets)');
     if (sheet.shadcnMissing?.length) bits.push(`${sheet.shadcnMissing.length} of the ${SHADCN_ROW_COUNT} current shadcn variables not defined (${sheet.shadcnMissing.slice(0, 4).map((r) => `--${esc(r)}`).join(', ')}${sheet.shadcnMissing.length > 4 ? '…' : ''})${sheet.hslEra ? ', normal for an install from before the chart and sidebar rows existed' : ''}`);
     if (sheet.missingDark?.length) bits.push(`${sheet.missingDark.length} variable${sheet.missingDark.length === 1 ? '' : 's'} with no dark value (${sheet.missingDark.slice(0, 4).map((r) => `--${esc(r)}`).join(', ')})`);
     if (sheet.custom?.length) bits.push(`${sheet.custom.length} custom variable${sheet.custom.length === 1 ? '' : 's'} of your own (${sheet.custom.slice(0, 5).map((r) => `--${esc(r)}`).join(', ')}${sheet.custom.length > 5 ? '…' : ''})${sheet.customMissingDark?.length ? `, ${sheet.customMissingDark.length} of them light only` : ''}${sheet.customUnregistered?.length ? `, ${sheet.customUnregistered.length} never mapped in @theme inline` : ''}`);
-    if (sheet.tweakcnPresent >= 10) bits.push('tweakcn variables present: shadows and letter-spacing are themed');
+    if (sheet.tweakcnPresent >= 10) bits.push(`a tweakcn theme: ${sheet.tweakcnPresent} of the rows tweakcn adds to every theme it exports are here (shadows, letter-spacing, spacing), so the theme came from a theme editor or copied its shape, and updates will come from there too`);
     if (sheet.spacingChanged) bits.push(`<b>--spacing is ${esc(sheet.spacing)}</b>, not the default 0.25rem: this resizes every gap in the app at once, which shadcn\'s own changelog says never to do`);
     parts.push(`<div class="receipts">${eyebrow('the theme file, variable by variable')}<p class="sub">${bits.join(' · ')}.</p></div>`);
   } else if (sheet) {
@@ -635,7 +648,7 @@ function duplicatesSection() {
     </div>` : '';
   const dupeCards = exactDupes.slice(0, 8).map((d) => `
     <div class="fam">
-      ${eyebrow(`&lt;${esc(d.name)}&gt; · ${d.wrapped ? 'defined twice, one wraps the other' : `${d.files.length} implementations`}`)}
+      ${eyebrow(`&lt;${esc(d.name)}&gt; · ${d.upstream ? 'two shadcn components define it: upstream\'s overlap, not counted' : d.wrapped ? 'defined twice, one wraps the other' : `${d.files.length} implementations`}`)}
       <div class="fam-rows">
       ${d.files.slice(0, 6).map((f) => `<div class="mini-card">${fileLink(f)}</div>`).join('')}
       ${d.files.length > 6 ? `<div class="mini-card dim">…and ${d.files.length - 6} more</div>` : ''}
@@ -742,7 +755,7 @@ function typographySection() {
     ${typeSpecimens || receipts('the font sizes, by use', sizeChips)}
     ${radiiSpecimens || receipts('the radii, by use', radiiChips)}
     ${shadowSpecimens}
-    ${fontFamilies.length > 1 ? `<div class="glass pad" style="margin-top:16px">${sectionHead(`${typefaces.length} typeface${typefaces.length === 1 ? '' : 's'}, declared ${fontFamilies.length} different ways`, 'every distinct declaration is a chance for the next one to be wrong')}<div class="fam-rows">${fams}</div></div>` : ''}
+    ${fontFamilies.length > 1 && fontFamilies.length > typefaces.length ? `<div class="glass pad" style="margin-top:16px">${sectionHead(`${typefaces.length} typeface${typefaces.length === 1 ? '' : 's'}, declared ${fontFamilies.length} different ways`, 'every distinct declaration is a chance for the next one to be wrong')}<div class="fam-rows">${fams}</div></div>` : ''}
   </section>`;
 }
 
@@ -882,7 +895,8 @@ function componentsSection() {
     ${sectionHead(isLibrary ? 'The composition map' : 'The adoption map', `${n(reusable.length)} components defined · tile area is ${isLibrary ? 'internal use: how the system builds from itself, downstream consumers invisible from here' : 'import count'} · the real system, drawn to scale`)}
     ${mapped}
     ${overflow > 0 ? `<p class="sub">${overflow} more adopted component${overflow === 1 ? '' : 's'} below the top 24, not drawn.</p>` : ''}
-    ${onceUsed.length ? `<p class="sub">${n(onceUsed.length)} component${onceUsed.length === 1 ? ' is' : 's are'} imported exactly once: ${onceUsed.slice(0, 6).map((c) => `&lt;${esc(c.name)}&gt;`).join(', ')}${onceUsed.length > 6 ? ` and ${onceUsed.length - 6} more` : ''}. Quiet corners, not yet a system.</p>` : ''}
+    ${fresh ? '<p class="sub">No code of your own uses the kit yet. The counts below are the components using each other.</p>' : ''}
+    ${onceUsed.length && !fresh ? `<p class="sub">${n(onceUsed.length)} component${onceUsed.length === 1 ? ' is' : 's are'} imported exactly once: ${onceUsed.slice(0, 6).map((c) => `&lt;${esc(c.name)}&gt;`).join(', ')}${onceUsed.length > 6 ? ` and ${onceUsed.length - 6} more` : ''}. Quiet corners, not yet a system.</p>` : ''}
     ${top.length ? `<div class="tbl-wrap"><table><thead><tr><th>component</th><th>used</th><th>defined in</th><th>props</th></tr></thead><tbody>${rows}</tbody></table></div>` : ''}
     ${neverImported.length >= 2 ? `
     <div class="receipts">${eyebrow(isLibrary ? `${n(neverImported.length)} components unused internally · showroom stock to review, not dead weight: consumers in other repos are invisible from here` : vendoredUi ? `${n(neverImported.length)} catalogue components not used yet · installed by the shadcn CLI and waiting to be used, not written by this team` : `${n(neverImported.length)} components defined but never imported · they sit in the system as wrong answers waiting to be picked`)}
@@ -1081,9 +1095,18 @@ function whereToStartSection() {
     const pt = P.shadcn.paint;
     if (pt.tin.uses >= 10) {
       const s0 = pt.tin.samples[0], f0 = pt.tin.top[0];
-      c.push({ score: 20 + pt.tin.per100 / 4, metric: 'paintTin', after: 0,
-        title: `Repaint the ${n(pt.tin.uses)} colours from outside the theme`,
-        sub: `${esc(s0.value)} appears ${s0.count} times${f0 ? `, ${esc(basename(f0.file))} alone carries ${f0.count}` : ''}. The theme file already has a variable for each (a grey is <code>text-muted-foreground</code>, a status colour is a Badge variant or a variable you add). Swap the class, not the value.` });
+      // The swap only works when the theme file holds the variables. A
+      // product whose sheet defines none of them (formbricks: brand rows
+      // only, slate as the palette) needs a decision first, not a prompt:
+      // swapping classes there leaves text with no colour.
+      const sheetHasRows = (P.shadcn?.sheet?.shadcnPresent ?? 0) >= 5 || P.shadcn?.kit?.cssVariables === false;
+      c.push(sheetHasRows
+        ? { score: 20 + pt.tin.per100 / 4, metric: 'paintTin', after: 0,
+          title: `Repaint the ${n(pt.tin.uses)} colours from outside the theme`,
+          sub: `${esc(s0.value)} appears ${s0.count} times${f0 ? `, ${esc(basename(f0.file))} alone carries ${f0.count}` : ''}. The theme file already has a variable for each (a grey is <code>text-muted-foreground</code>, a status colour is a Badge variant or a variable you add). Swap the class, not the value.` }
+        : { score: 20 + pt.tin.per100 / 4, metric: 'paintTin', after: 0,
+          title: `Decide what the product paints from`,
+          sub: `${esc(s0.value)} appears ${s0.count} times${f0 ? `, ${esc(basename(f0.file))} alone carries ${f0.count}` : ''}, and there is no theme file to point them at: ${P.shadcn?.sheet?.file ? `${esc(P.shadcn.sheet.file)} defines` : 'the theme file defines'} none of shadcn's colour variables, so the palette is the system today. The first move is a decision, not a swap: adopt the theme variables (define them, map the palette onto them), then repaint file by file. Swapping <code>text-slate-500</code> for <code>text-muted-foreground</code> before that leaves the text with no colour.` });
     }
     if (pt.doors.uses >= 5) {
       const s0 = pt.doors.samples[0];
@@ -1130,6 +1153,7 @@ function whereToStartSection() {
   // reads at click time, so a forwarded report keeps working offline.
   const unesc = (s) => s.replace(/<[^>]+>/g, '').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&rarr;/g, '->').replace(/&amp;/g, '&');
   const promptFor = (item) => fixPrompt({
+    metric: item.metric,
     title: unesc(item.title),
     sub: unesc(item.sub),
     deltaText: item.delta > 0 ? `about +${item.delta} points` : (item.target ? `about +${item.target.gain} points once ${item.target.target === 0 ? 'they are all cleared' : `the count is under ${n(item.target.target)}`}` : ''),
@@ -1205,7 +1229,20 @@ function agentSection() {
   const have = rootAgent.map((c) => `<span class="chip chip-agent">${esc(c.file)} · ${esc(c.tool ?? c.kind)}</span>`).join('')
     + (nestedCount ? `<span class="chip chip-agent">+${nestedCount} nested in subfolders</span>` : '');
   const readsList = (rootAgent.length ? rootAgent : nestedAgent.slice(0, 3)).map((c) => `<span class="mono">${esc(c.file)}</span>`).join(', ');
-  const msg = agentFiles.length
+  // A file a framework wrote for itself (Next.js re-adds its block on every
+  // dev run) is not guidance about the design system, and says so.
+  const managedOnly = agentFiles.length > 0 && agentFiles.every((c) => c.managedOnly === true);
+  const managedBy = managedOnly ? agentFiles[0].managedBy : null;
+  const skill = (h.context ?? []).find((c) => c.kind === 'agent-skill');
+  const skillLine = P.isShadcn ? (skill ? ` The shadcn skill is installed (<span class="mono">${esc(skill.file)}</span>), so the agent can read the kit's configuration.` : ' shadcn offers a skill for that and it is not installed here.') : '';
+  // the files name the kit (or the skill is installed): the gap is the
+  // repo's own habits, which no hand-written file carries
+  const namesKit = P.isShadcn && (skill || agentFiles.some((c) => c.mentionsDesign === true && c.managedOnly !== true));
+  const msg = managedOnly
+    ? `<p class="sub">Your agent reads ${readsList}. ${esc(managedBy)} wrote it, and it is only about ${esc(managedBy)}: nothing in it mentions the theme file or the component folder, so the agent does not know the ${P.isShadcn ? 'kit' : 'design system'} is there.${skillLine} Add the rules file below and the agent knows the theme, the components and the styling rules.</p>`
+    : namesKit
+    ? `<p class="sub">Your agent reads ${readsList}${nestedCount && rootAgent.length ? `, plus ${nestedCount} rules file${nestedCount === 1 ? '' : 's'} nested in subfolders` : ''}${skill ? `, and the shadcn skill is installed (<span class="mono">${esc(skill.file)}</span>)` : ''}. ${skill && !agentFiles.some((c) => c.mentionsDesign) ? 'The skill tells it' : 'They tell it'} the kit is there. What ${skill && !agentFiles.some((c) => c.mentionsDesign) ? 'it does' : 'they do'} not carry is how this repo actually uses it: the numbers below, which the rules file turns into rules with receipts.</p>`
+    : agentFiles.length
     ? `<p class="sub">Your agent reads ${readsList}${nestedCount && rootAgent.length ? `, plus ${nestedCount} rules file${nestedCount === 1 ? '' : 's'} nested in subfolders` : ''}. But none of it points at a single source of truth for components and tokens, because there isn't one yet. The numbers below are what your agent actually works from.</p>`
     : `<p class="sub">No <span class="mono">CLAUDE.md</span>, no <span class="mono">AGENTS.md</span>, no <span class="mono">.cursorrules</span>. Every time your AI builds UI here, it guesses, from everything below. This is why its output looks almost-but-not-quite right.</p>`;
   // Door coverage, stated as fact: which tools can read what exists. Claude
@@ -1222,13 +1259,13 @@ function agentSection() {
   const staleRows = stale.map((s) => `
     <div class="ledger-row">
       <span class="mono strong">${esc(s.ref)}</span>
-      <span class="dim">${s.problem === 'missing' ? 'named in' : 'named canonical in'} ${esc(s.file)}, ${s.problem === 'missing' ? 'but the path no longer exists' : 'but nothing imports it this scan'}</span>
+      <span class="dim">${s.problem === 'missing' ? 'named in' : 'named canonical in'} ${esc(s.file)}${s.tool ? ` (written by ${esc(s.tool)}, not by this team)` : ''}, ${s.problem === 'missing' ? 'but the path no longer exists' : 'but nothing imports it this scan'}</span>
     </div>`).join('');
   const staleBlock = stale.length ? `
     <div class="stale">
       ${eyebrow(`${stale.length} rule reference${stale.length === 1 ? '' : 's'} gone stale · a rule your agent obeys is worse than no rule when the repo has moved on`)}
       <div class="ledger">${staleRows}</div>
-      <p class="sub" style="margin-top:10px">Rules rot quietly: nobody edits them when a component is renamed or a file moves. Regenerate them from a fresh scan, or fix the lines by hand.</p>
+      <p class="sub" style="margin-top:10px">${stale.every((s) => s.tool) ? 'These lines were written by a tool, not by this team: a rule pack that speaks about files this app does not have. Not yours to fix; worth knowing your agent reads them.' : 'Rules rot quietly: nobody edits them when a component is renamed or a file moves. Regenerate them from a fresh scan, or fix the lines by hand.'}</p>
     </div>` : '';
   return `<section class="glass pad agent">
     ${sectionHead('What your AI agent sees today', '')}
@@ -1279,7 +1316,20 @@ 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` : '';
-  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>`;
+  const receipt = `${esc(P.evidence.join(' · '))}${facts.length ? ` · ${esc(facts.join(', '))}` : ''}${esc(fell)}`;
+  if (fresh) {
+    const f = P.shadcn.fresh;
+    const doors = f.catalogueCount;
+    const pages = comps.filter((c) => c.isPage && f.ownFiles.includes(c.file)).length;
+    return `<div class="excl fresh">It is a fresh shadcn install${k?.style ? ` (style ${esc(k.style)}${k.baseColor ? `, base colour ${esc(k.baseColor)}` : ''}${k.tailwind ? `, Tailwind ${esc(k.tailwind)}` : ''})` : ''}. Nothing of your own yet: ${n(doors)} component${doors === 1 ? '' : 's'} installed, the theme file untouched, ${pages === 1 ? 'one demo page' : `${pages} pages`}. <b>The score is the kit's, not yours.</b> Run this again once you have built a few screens.</div><div class="excl">Evidence: ${receipt}</div>`;
+  }
+  if (P.isRegistry && P.registry) {
+    const r = P.registry;
+    const what = r.builtFrom ? `publishes ${r.items} component${r.items === 1 ? '' : 's'}, built from its packages folder` : `publishes ${esc(publishesLine(r))}`;
+    const pages = comps.filter((c) => c.isPage).length;
+    return `<div class="excl fresh">Read as a shadcn registry: ${what}${r.variants.length ? `, the same components kept in ${r.variants.length} variants` : ''}.${pages ? ` Its own site: ${n(pages)} page${pages === 1 ? '' : 's'}.` : ''} Scored as a shadcn install for now; the registry rules come next.</div><div class="excl">Evidence: ${receipt}</div>`;
+  }
+  return `<div class="excl">Read as a shadcn install (${esc(P.confidence ?? 'medium')} confidence): ${receipt}</div>`;
 }
 
 // User exclusions are printed in the header, never hidden: a scoped scan must
@@ -1312,7 +1362,7 @@ function sidePanel() {
     ? `<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 chips = `<div class="chips">${stack.map((c) => `<span class="chip">${esc(c)}</span>`).join('')}${(P.shadcn?.sheet?.tweakcnPresent ?? 0) >= 10 ? '<span class="chip">tweakcn theme</span>' : ''}${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(),
@@ -1339,12 +1389,38 @@ function exceptionsBlock() {
   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.`);
+    const si = spacingOwn.installed;
+    const sv = si.values.length;
+    if (sv) lines.push(`${n(sv)} off-scale spacing value${sv === 1 ? '' : 's'} inside ${esc(P.uiDirs.map((d) => basename(d)).join(', '))} ${sv === 1 ? 'is' : 'are'} shadcn's own (${si.values.slice(0, 3).map((v) => esc(v.value)).join(', ')}) and ${sv === 1 ? 'is' : 'are'} not counted, for the same reason as the bracket values.`);
     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.');
   }
+  const li = h.tokens?.important?.library;
+  if (li?.count) lines.push(`${n(li.count)} !important declaration${li.count === 1 ? '' : 's'} aimed at a library's own class names (${li.classes.slice(0, 3).map((c) => esc(c.value)).join(', ')}) ${li.count === 1 ? 'is' : 'are'} not counted: the library ships its CSS, and this is the only way through it. Your agent reads ${li.count === 1 ? 'it' : 'them'} like everything else.`);
+  // Files no checker judges (email, print, artwork, render-to-image, the
+  // crash page): named here with the reason, because the agent reads them
+  // like everything else and can copy what is in them.
+  const ex = h.tokens?.exemptFiles ?? [];
+  if (ex.length) {
+    const byReason = new Map();
+    for (const e of ex) { if (!byReason.has(e.reason)) byReason.set(e.reason, []); byReason.get(e.reason).push(e.file); }
+    for (const [reason, files] of byReason) {
+      // two files with one name (a spare-part copy) are told apart by their folder
+      const label = (f) => {
+        const parts = f.split('/');
+        for (let k = 1; k <= parts.length; k++) {
+          const tail = parts.slice(-k).join('/');
+          if (files.filter((o) => o === tail || o.endsWith(`/${tail}`)).length === 1) return tail;
+        }
+        return f;
+      };
+      const names = files.slice(0, 3).map((f) => esc(label(f))).join(', ') + (files.length > 3 ? ` and ${files.length - 3} more` : '');
+      lines.push(`${n(files.length)} file${files.length === 1 ? '' : 's'} not judged (${names}): ${esc(reason)}. Not counted, but your agent reads ${files.length === 1 ? 'it' : 'them'} like everything else, so what is in there is still an example it can copy.`);
+    }
+  }
   if (!lines.length) return '';
   return `<div class="excs"><b>Not yours, and not counted</b>${lines.map((l) => `<p>${l}</p>`).join('')}</div>`;
 }
@@ -1409,6 +1485,8 @@ const html = `<!doctype html>
   .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 .excl.fresh { color:var(--text); }
+  .side .facts .excl.fresh b { color:var(--text); }
   .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); }
@@ -1961,7 +2039,8 @@ if (summaryPath) {
     verdict,
     role: P.role,
     kind: P.kind,
-    ...(P.isShadcn && P.shadcn ? { shadcn: { confidence: P.confidence, evidence: P.evidence, style: P.shadcn.kit?.style ?? null, baseColor: P.shadcn.kit?.baseColor ?? null, tailwind: P.shadcn.kit?.tailwind ?? null, catalogues: P.uiDirs, registries: P.shadcn.registryDirs ?? [], ...(P.shadcn.registryPaint ? { registryFiles: P.shadcn.registryPaint.files, registryPaletteColours: P.shadcn.registryPaint.tinUses } : {}), ownFiles: P.shadcn.paint?.ownFiles ?? null } } : {}),
+    ...(P.isRegistry && P.registry ? { registry: { source: P.registry.source, builtFrom: P.registry.builtFrom, items: P.registry.items, publishes: P.registry.publishes, variants: P.registry.variants } } : {}),
+    ...(P.isShadcn && P.shadcn ? { shadcn: { confidence: P.confidence, evidence: P.evidence, style: P.shadcn.kit?.style ?? null, baseColor: P.shadcn.kit?.baseColor ?? null, tailwind: P.shadcn.kit?.tailwind ?? null, catalogues: P.uiDirs, registries: P.shadcn.registryDirs ?? [], ...(P.shadcn.registryPaint ? { registryFiles: P.shadcn.registryPaint.files, registryPaletteColours: P.shadcn.registryPaint.tinUses } : {}), ownFiles: P.shadcn.paint?.ownFiles ?? null, fresh: P.shadcn.fresh?.fresh === true } } : {}),
     componentsMeasured,
     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),

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, installedDirs, splitArbitrary } from '../profiles/index.mjs';
+import { profileOf, installedDirs, splitArbitrary, ownSpacing } from '../profiles/index.mjs';
 
 export { SCHEMA_VERSION };
 
@@ -45,7 +45,8 @@ export function loadBenchmark() {
  * ideals and the reputable-systems line are the same for every kind.
  */
 export function benchHelpers(bench, kind = 'product') {
-  const slice = bench?.slices?.[kind] ?? null;
+  // registries are compared with the shadcn repos, labelled as such (Greg, 2026-09-13)
+  const slice = bench?.slices?.[kind === 'registry' ? 'shadcn' : kind] ?? null;
   if (slice?.stats) bench = { ...bench, stats: { ...(bench?.stats ?? {}), ...slice.stats } };
   const sliceInfo = slice ? { kind, repoCount: slice.repoCount, builtAt: slice.builtAt } : null;
   // where does this value sit among the scanned fleet? ("more colours than 90%")
@@ -105,6 +106,8 @@ export const PROFILE_TILES = {
     ['doorOverrides', 'components recoloured from outside per 100 files'],
   ],
 };
+// a registry measures what a shadcn repo measures (release (a), 2026-09-13)
+PROFILE_TILES.registry = PROFILE_TILES.shadcn;
 export const tilesFor = (kind) => [...TILES, ...(PROFILE_TILES[kind] ?? [])];
 
 /** The tiles, in report order: metric key, the label the report prints. */
@@ -136,8 +139,9 @@ export function coreMetrics(h, opts = {}) {
   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 ?? [];
+  // Off-scale spacing the team wrote: on a kit the values inside installed
+  // folders are shadcn's own, kept out like its bracket values and named.
+  const sp = ownSpacing(h);
   const hardDupes = (h.duplicates?.exactDuplicates ?? []).filter((d) => !d.wrapped);
   return {
     colors: colors.length,
@@ -150,7 +154,7 @@ export function coreMetrics(h, opts = {}) {
     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,
+    spacing: sp.css.length + sp.tw.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,