roast-my-design-system 9.4.0 → 9.5.0

package/README.md

@@ -142,11 +142,11 @@ Eleven reports, hosted exactly as the tool writes them. Every number determinist
 
 The full report for vercel/ai-chatbot. The verdict answers what the agent will learn here, the gap section comes first, then "What the repo teaches the agent", Claude's read of the scan:
 
-![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 where the agent will have to guess, the fixes you can make right now, each with what it is worth and 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](assets/report-full-dark.png?v=9.3.3)
+![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 where the agent will have to guess, the fixes you can make right now, each with what it is worth and 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](assets/report-full-dark.png?v=9.5.0)
 
 The same report in light mode (one file, built-in toggle):
 
-![The diagnosis report in light mode](assets/report-light-hero.png?v=9.3.3)
+![The diagnosis report in light mode](assets/report-light-hero.png?v=9.5.0)
 
 ## Why the numbers hold
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "9.4.0",
+  "version": "9.5.0",
   "mcpName": "io.github.gregkozakiewicz/roast-my-design-system",
   "description": "Your AI can write the UI. This makes sure it writes your UI. A deterministic scanner scores your design system 0-100 against 112 public repos, reads React and web components (Stencil, Lit), hands you a copy-paste fix prompt for each top finding, writes rules for Claude, Cursor, Copilot and Windsurf with --apply, and runs as a local MCP server with --mcp.",
   "keywords": [

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

@@ -32,7 +32,7 @@ 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 { ownSpacing, profileOf, installedDirs, splitArbitrary } from '../profiles/index.mjs';
+import { ownSpacing, profileOf, installedOf, splitArbitrary } from '../profiles/index.mjs';
 import { KITS } from '../profiles/kit-common.mjs';
 import { rulesOn as lintRulesOn, describeRule as lintDescribe, entryMatcher as lintMatcher, RULE_TILE as LINT_TILE } from '../profiles/shadcn-lint.mjs';
 import { publishesLine } from '../profiles/registry.mjs';
@@ -257,7 +257,7 @@ 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;
+if (P.isShadcn) arbitrary = splitArbitrary(arbitrary, installedOf(P)).own;
 const breakdown = scoreBreakdown(h, bench);
 const neverImported = neverImportedComponents(h.components, P.uiDir);
 

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, ownSpacing } from '../profiles/index.mjs';
+import { profileOf, installedOf, splitArbitrary, ownSpacing } from '../profiles/index.mjs';
 
 export { SCHEMA_VERSION };
 
@@ -146,7 +146,7 @@ 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 ?? []);
+  const arbitraryEntries = P.isShadcn ? splitArbitrary(h.tokens?.tailwind?.arbitrary ?? [], installedOf(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 = P.isTailwind ? P.tailwind?.paint

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

@@ -29,9 +29,9 @@ 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, decideFresh, profileOf, installedDirs, splitArbitrary, scopeFiles } from '../profiles/index.mjs';
+import { decideProfile, decideFresh, profileOf, installedOf, doorFile, installedFile, splitArbitrary, scopeFiles } from '../profiles/index.mjs';
 import { publishesLine } from '../profiles/registry.mjs';
-import { countPaint } from './paint.mjs';
+import { countPaint, doorShades } from './paint.mjs';
 
 function arg(name, fallback) {
   const i = process.argv.indexOf(`--${name}`);
@@ -120,17 +120,18 @@ if (profileOf(profile).isRegistry) {
   const P = profileOf(profile);
   if (P.isShadcn) {
     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}/`))));
+    // installed code, file by file (profiles/installed.mjs): a component of
+    // the team's own kept in the catalogue folder is own code (9.5.0)
+    const installed = installedOf(P);
+    const doorFiles = new Set(files.code.filter(installed));
     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, email });
+    // wrong lesson as one in own code. shadcn's own components and kit blocks
+    // stay out: editing them is the intended use.
+    profile.shadcn.paint = countPaint(target, files.code, { isDoor: (f) => doorFile(P, f), kitNames, email });
     // Own code alone, for the breakdown line under the score.
-    profile.shadcn.paintOwn = regDirs.length ? countPaint(target, files.code, { uiDirs: allInstalled, kitNames, email }) : profile.shadcn.paint;
+    profile.shadcn.paintOwn = regDirs.length ? countPaint(target, files.code, { isDoor: installed, kitNames, email }) : 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, email });
@@ -138,7 +139,18 @@ if (profileOf(profile).isRegistry) {
     }
     // 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);
+    // Utility-class mode (9.5.0), for the rules file only: the shades shadcn's
+    // own components paint with, and, where the repo keeps a theme of its
+    // own, the palette classes in own code that theme does not own.
+    if (P.designSystem?.cssVariables === false) {
+      profile.shadcn.doorShades = doorShades(target, files.code.filter((f) => /\.(tsx|jsx)$/.test(f) && doorFile(P, f)));
+      const own = profile.shadcn.ownTheme;
+      if (own) {
+        const p = countPaint(target, files.code, { isDoor: installed, retuned: own.retuned, families: own.families, email });
+        profile.shadcn.ownThemePaint = { uses: p.tin.uses, samples: p.tin.samples.slice(0, 6) };
+      }
+    }
+    const split = splitArbitrary(tokens.tailwind?.arbitrary ?? [], installed);
     profile.shadcn.arbitraryInstalled = split.installed;
     // A fresh kit (the install command's output, nothing built yet) is
     // decided here, once, from the facts above.
@@ -162,8 +174,8 @@ const context = harvestContext(target);
 // The chart palette the repo keeps, or the charts painting by hand without
 // one, and the gaps an agent will fill by inventing (lib/charts, lib/gaps).
 const charts = (() => {
-  const installed = installedDirs(profileOf(profile));
-  const own = (f) => !installed.some((d) => f === d || f.startsWith(`${d}/`));
+  const P = profileOf(profile);
+  const own = (f) => !installedFile(P, f);
   return chartSystemOf(files, (f) => readSource(resolve(target, f)), { own });
 })();
 const gaps = designGaps({ charts, tokenFile: tokens.tokenFile ?? null });

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

@@ -60,11 +60,13 @@ export const DEMO_PATH_RE = /(^|\/)(stories|storybook|__stories__|examples?|demo
 /**
  * @param root repo root
  * @param codeFiles relative code paths from the walk
- * @param opts { uiDirs: string[], kitNames: Set<string> } — catalogue folders
+ * @param opts { uiDirs: string[], kitNames: Set<string> } — catalogue folders;
+ *   `isDoor(file)` in place of uiDirs decides file by file (9.5.0: a team
+ *   component kept in the catalogue folder is own code, profiles/installed.mjs)
  *   and the component names defined in them
  */
-export function countPaint(root, codeFiles, { uiDirs = [], kitNames = new Set(), retuned = [], families = null, email = null } = {}) {
-  const inCatalogue = (f) => uiDirs.some((d) => f === d || f.startsWith(`${d}/`));
+export function countPaint(root, codeFiles, { uiDirs = [], isDoor = null, kitNames = new Set(), retuned = [], families = null, email = null } = {}) {
+  const inCatalogue = isDoor ?? ((f) => uiDirs.some((d) => f === d || f.startsWith(`${d}/`)));
   const names = [...kitNames].filter((n) => /^[A-Z][A-Za-z0-9]*$/.test(n));
   const doorOpen = names.length
     ? new RegExp(`<(${names.join('|')})\\b[^>]*?className=(?:"([^"]*)"|\\{cn\\(\\s*["'\`]([^"'\`]*)["'\`])`, 'g')
@@ -141,3 +143,22 @@ export function countPaint(root, codeFiles, { uiDirs = [], kitNames = new Set(),
   });
   return { ownFiles, tin: finish(tin), doors: finish(doors), typo: finish(typo) };
 }
+
+/**
+ * The palette shades shadcn's own components paint with, most used first,
+ * with variant prefixes and opacity dropped (hover:bg-zinc-900/90 is
+ * bg-zinc-900). On a utility-class install these are the system: the rules
+ * file tells the agent to stay with them (9.5.0).
+ */
+export function doorShades(root, doorFiles) {
+  const tally = new Map();
+  for (const f of doorFiles) {
+    const raw = readSource(join(root, f));
+    if (raw === null) continue;
+    for (const m of blankComments(raw).matchAll(PALETTE_CLASS_RE)) {
+      const cls = m[0].replace(/^(?:[\w-]+:)*/, '').replace(/\/\d+$/, '');
+      tally.set(cls, (tally.get(cls) ?? 0) + 1);
+    }
+  }
+  return [...tally.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).slice(0, 8).map(([value, count]) => ({ value, count }));
+}

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

@@ -14,7 +14,7 @@ import { walkRepo, readSource, profileRepo } from '../harvest/walk.mjs';
 import { chartSystemOf } from './charts.mjs';
 import { designGaps } from './gaps.mjs';
 export { designGaps } from './gaps.mjs';
-import { decideProfile, profileOf, installedDirs } from '../profiles/index.mjs';
+import { decideProfile, profileOf, installedDirs, installedFile, installedFrom } from '../profiles/index.mjs';
 import { KITS } from '../profiles/kit-common.mjs';
 import { kitPaintFindings } from './kitpaint.mjs';
 import { paletteFindings } from './palette.mjs';
@@ -76,6 +76,11 @@ export { PALETTE_CLASS_RE, DEMO_PATH_RE, blankComments };
 // a guard that calls this agrees with the report's live checks by
 // construction, on a Tailwind theme and on a shadcn kit alike.
 export { paletteFindings };
+// Installed code, file by file (9.5.0, profiles/installed.mjs): a guard
+// leaves installedFile(system.profile.installedFrom, file, under) alone and
+// judges everything else, including the team's own components kept in the
+// shadcn catalogue folder. isShadcnFile(file) is the name test on its own.
+export { installedFile, doorFile, isShadcnFile } from '../profiles/installed.mjs';
 // A product built on a kit (MUI, Mantine, Chakra UI, Ant Design), 8.4.6: a
 // colour or a pixel size written onto a kit component where the theme has a
 // value. kitPaintFindings(fileText, system.profile.kit, { file }) returns the
@@ -144,8 +149,7 @@ export function learnSystem(repoRoot, { exclude = [] } = {}) {
   const read = (f) => readSource(join(repoRoot, f));
   const hardDupes = (findDuplicates(ledger, profile.uiDir, repoRoot, profile.uiDirs ?? null).exactDuplicates ?? []).filter((d) => !d.wrapped);
   const P = profileOf(profile);
-  const installedNow = installedDirs(P);
-  const charts = chartSystemOf(files, read, { own: (f) => !installedNow.some((d) => f === d || f.startsWith(`${d}/`)) });
+  const charts = chartSystemOf(files, read, { own: (f) => !installedFile(P, f) });
   // the kit the product is built on, with its definition attached, the way
   // the MCP knowledge reads it (mcp/knowledge.mjs): the theme's colours are
   // the token set on a kit repo, whatever stylesheet holds the most literals
@@ -225,12 +229,16 @@ export function learnSystem(repoRoot, { exclude = [] } = {}) {
     profile: {
       kind: P.kind,
       role: P.role,
-      // folders the team did not write (a shadcn catalogue, installed
-      // registries, kit blocks): their brackets and copies are not the PR's
-      // sin. Empty on a registry: what it publishes is its own work.
-      // only a shadcn kit has installed code; a hand-written components/ui on a
-      // plain product is the team's own (the report splits nothing there either)
+      // folders that hold installed code (a shadcn catalogue, installed
+      // registries, kit blocks). Empty on a registry: what it publishes is
+      // its own work. Only a shadcn kit has installed code; a hand-written
+      // components/ui on a plain product is the team's own.
       installedDirs: P.isShadcn && !P.isRegistry ? installedDirs(P) : [],
+      // Which files in those folders are installed, file by file (9.5.0): a
+      // component of the team's own kept in the catalogue folder is the
+      // team's, and judged. installedFile(profile.installedFrom, file, under)
+      // answers; `under` is how the caller matches a file to a folder.
+      installedFrom: installedFrom(P),
       // a product built on a kit: name, theme files and values, spacing step,
       // the team's own layers over it, and the definition kitPaintFindings reads
       kit,

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

@@ -34,6 +34,7 @@
 import { PALETTE_CLASS_RE, GREY_HUE_RE, DARK_WB_RE, DEMO_PATH_RE, blankComments } from '../harvest/paint.mjs';
 import { TAILWIND_DEFAULTS } from '../profiles/tailwind-defaults.mjs';
 import { oklab } from './color.mjs';
+import { doorFile } from '../profiles/installed.mjs';
 
 // shadcn's names, one per role the utilities want; the sheet always has
 // greys and colours, so no family check
@@ -59,9 +60,10 @@ export function decidePalette(profile, P, readTheme = null) {
   const sc = profile.shadcn;
   // utility-class mode: the palette is the theme, and the report scores it so
   if (P.designSystem?.cssVariables === false) return null;
-  // the catalogue and kit blocks are the kit's own doors: editing them is the
-  // intended use, and the report's tile leaves them out
-  const doors = [...(P.uiDirs ?? []), ...(sc.blockFiles ?? [])];
+  // shadcn's own components and kit blocks are the kit's doors: editing them
+  // is the intended use, and the report's tile leaves them out. A component
+  // of the team's own kept in the catalogue folder is not a door (9.5.0).
+  const doors = { uiDirs: [...(P.uiDirs ?? [])], shadcn: { blockFiles: [...(sc.blockFiles ?? [])] } };
   const rows = Math.max(sc.sheet?.shadcnPresent ?? 0, sc.contract?.rows ?? 0);
   if (rows >= CONTRACT_MIN) {
     return {
@@ -83,7 +85,7 @@ export function decidePalette(profile, P, readTheme = null) {
 export function paletteFindings(text, palette, { file = null, css = null } = {}) {
   if (!palette || !text) return [];
   if (css ?? (file ? CSS_FILE_RE.test(file) : false)) return [];
-  if (file && (DEMO_PATH_RE.test(file) || (palette.doors ?? []).some((d) => file === d || file.startsWith(`${d}/`)))) return [];
+  if (file && (DEMO_PATH_RE.test(file) || doorFile(palette.doors, file))) return [];
   const retuned = new Set(palette.retuned ?? []);
   const fam = palette.families ?? null;
   const hasFamily = (cls) => !fam || (GREY_HUE_RE.test(cls) ? fam.grey : fam.colour);
@@ -124,6 +126,21 @@ export function paletteFindings(text, palette, { file = null, css = null } = {})
   return out;
 }
 
+/**
+ * The theme class that stands in for a palette class, or null: the theme's
+ * own word for the hue when it has one (text-red-500 on a theme naming
+ * destructive is text-destructive), else the suitable theme colour nearest
+ * by value. For the rules file's example (9.5.0).
+ */
+export function themeClassFor(cls, names = [], values = {}) {
+  const util = cls.replace(/^((?:[\w-]+:)*[a-z]+)-.*$/, '$1').replace(/^(?:[\w-]+:)*/, '');
+  const shade = cls.replace(/^(?:[\w-]+:)*[a-z]+-/, '').replace(/\/\d+$/, '');
+  const word = hueWord(shade, names);
+  if (names.includes(word)) return `${util}-${word}`;
+  const near = nearestThemeName(shade, utilRole(util), values);
+  return near ? `${util}-${near}` : null;
+}
+
 // ---------- the theme colour a palette class stands in for ----------
 // Which theme names suit a utility, read from the name: a text class wants an
 // ink, a bg class a surface, a border class an edge. A name that says none of

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 = '9.4.0';
+export const VERSION = '9.5.0';
 // The shape of harvest.json and summary.json. Bumped only when a field is
 // renamed, removed or changes meaning; a new field is not a new schema. A
 // tool comparing two scans compares like with like by this number, not by VERSION.

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

@@ -18,6 +18,7 @@ import { exemptReason, isDrawing, SVG_MARKUP_RE } from '../lib/exempt.mjs';
 import { extraDeclarations, fontDeclarations } from '../lib/declarations.mjs';
 import { typefaceOf, GENERIC_FONTS } from '../lib/typefaces.mjs';
 import { kitPaintFindings } from '../lib/kitpaint.mjs';
+import { installedFile } from '../profiles/installed.mjs';
 import { paletteFindings } from '../lib/palette.mjs';
 import { tokenTwinFindings } from '../lib/tokentwins.mjs';
 import { avoidedImportFindings } from '../lib/avoidedimports.mjs';
@@ -246,10 +247,12 @@ export function validateContent(content, k) {
     // a raw value the repo already uses, in a non-Tailwind repo, is consistency,
     // not a new offence — silence
   }
-  // Bracket values inside installed code (the shadcn catalogue, kit blocks,
-  // registries) are the kit's own choices. The report names them and keeps
-  // them out of the count; a file under review is judged by the same line.
-  const installed = !!file && (k.installedDirs ?? []).some((d) => file === d || file.startsWith(`${d}/`));
+  // Bracket values inside installed code (shadcn's own components, kit
+  // blocks, registries) are the kit's own choices. The report names them and
+  // keeps them out of the count; a file under review is judged by the same
+  // line, file by file: a component of the team's own kept in the catalogue
+  // folder is the team's (profiles/installed.mjs, 9.5.0).
+  const installed = !!file && installedFile(k.installedFrom, file);
   const localArb = new Map();
   for (const a of got.arbitrary) localArb.set(a.value, (localArb.get(a.value) ?? 0) + 1);
   for (const a of installed ? [] : got.arbitrary) {

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

@@ -24,7 +24,7 @@ import { tsconfigAliases } from '../harvest/components.mjs';
 import { neverImportedComponents } from '../lib/neverimported.mjs';
 import { typefaceOf } from '../lib/typefaces.mjs';
 import { hexRgb } from '../lib/nearpairs.mjs';
-import { decideProfile, profileOf, installedDirs } from '../profiles/index.mjs';
+import { decideProfile, profileOf, installedDirs, installedFile, installedFrom } from '../profiles/index.mjs';
 import { KITS } from '../profiles/kit-common.mjs';
 import { repoTokenDefs } from '../lib/tokentwins.mjs';
 import { dupeCopiesOf } from '../lib/avoidedimports.mjs';
@@ -159,7 +159,7 @@ export function loadKnowledge(root) {
   // without one (lib/charts.mjs)
   // installed kit code is the kit's own door, never a precedent (profiles/index)
   const installed = installedDirs(P);
-  const ownCode = (f) => !installed.some((d) => f === d || f.startsWith(`${d}/`));
+  const ownCode = (f) => !installedFile(P, f);
   const charts = chartSystemOf(files, read, { own: ownCode });
   const gaps = designGaps({ charts, tokenFile: tokens.tokenFile ?? null });
 
@@ -206,6 +206,9 @@ export function loadKnowledge(root) {
     // draws (lib/guard-api.mjs): only a shadcn kit has installed code, and a
     // registry's published folders are its own work
     installedDirs: P.isShadcn && !P.isRegistry ? installed : [],
+    // the facts installedFile reads (profiles/installed.mjs): a component of
+    // the team's own kept in the catalogue folder is judged like own code
+    installedFrom: installedFrom(P),
     // the kit the product is built on, and the Tailwind theme it names its
     // colours in: null when the repo is neither (see profiles/)
     kit,

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

@@ -24,6 +24,7 @@ import { join, basename, dirname } from 'node:path';
 import shadcn from './shadcn.mjs';
 import tailwind, { readTailwindTheme } from './tailwind.mjs';
 import { decidePalette } from '../lib/palette.mjs';
+import { installedFile } from './installed.mjs';
 import mui from './mui.mjs';
 import mantine from './mantine.mjs';
 import chakra from './chakra.mjs';
@@ -89,6 +90,13 @@ export function decideProfile(profile, components, files, root = null) {
   // under a shadcn kit with no rows, or nothing. The report's tile keeps
   // its own gates (harvest/index.mjs) and no score reads this.
   profile.palette = decidePalette(profile, profileOf(profile), () => readTailwindTheme({ ...profile }, ctx)?.facts ?? null);
+  // shadcn in utility-class mode (components.json: cssVariables false) paints
+  // with Tailwind classes by design. A theme of the repo's own beside it
+  // (rybbit retunes the whole neutral scale) is what the rules file points
+  // the agent at. Kept as facts: no score and no check reads it (9.5.0).
+  if (profile.shadcn && profile.designSystem?.cssVariables === false) {
+    profile.shadcn.ownTheme = readTailwindTheme({ ...profile }, ctx)?.facts ?? null;
+  }
   // A shadcn repo that PUBLISHES a registry is a registry: the fourth kind.
   // Every count still reads the shadcn facts (release (a): zero score change);
   // the kind, the receipt and the header line say what it is.
@@ -194,14 +202,31 @@ export function installedDirs(P) {
   return [...(P?.uiDirs ?? []), ...(sc.registryDirs ?? []), ...(sc.blockFiles ?? [])];
 }
 const underAny = (file, dirs) => dirs.some((d) => file === d || file.startsWith(`${d}/`));
+// Which files in those folders are installed, file by file (9.5.0): a
+// component of the team's own kept in the catalogue folder is the team's.
+// The rule lives in profiles/installed.mjs.
+export { isShadcnFile, doorFile, installedFile, installedFrom } from './installed.mjs';
+
+/**
+ * The installed-code test for one reading, as a function of a file path.
+ * `none` is set when the repo has no installed folders at all, so a caller
+ * can skip the split.
+ */
+export function installedOf(P) {
+  const fn = (file) => installedFile(P, file);
+  fn.none = installedDirs(P).length === 0;
+  return fn;
+}
 
 /**
  * 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.
+ * `installed` is installedOf(P), or (older callers) a list of folders.
  */
-export function splitArbitrary(entries, dirs) {
-  if (!dirs.length) return { own: entries, installed: { uses: 0, values: [] } };
+export function splitArbitrary(entries, installed) {
+  const isInstalled = typeof installed === 'function' ? installed : (file) => underAny(file, installed);
+  if (typeof installed === 'function' ? installed.none : !installed.length) return { own: entries, installed: { uses: 0, values: [] } };
   const own = [];
   const installedValues = new Map();
   let installedUses = 0;
@@ -211,8 +236,8 @@ export function splitArbitrary(entries, dirs) {
     // as the team's own, so ai-chatbot's installed badge put one of shadcn's
     // [3px] values in the headline (2026-09-30)
     const all = e.every ?? e.files ?? [];
-    const ownFiles = all.filter((f) => !underAny(f.file, dirs)).sort((a, b) => b.count - a.count).slice(0, 5);
-    const instCount = all.filter((f) => underAny(f.file, dirs)).reduce((s, f) => s + f.count, 0);
+    const ownFiles = all.filter((f) => !isInstalled(f.file)).sort((a, b) => b.count - a.count).slice(0, 5);
+    const instCount = all.filter((f) => isInstalled(f.file)).reduce((s, f) => s + f.count, 0);
     if (instCount) { installedUses += instCount; installedValues.set(e.value, (installedValues.get(e.value) ?? 0) + instCount); }
     // own is the remainder of the entry's total, never a sum of the files
     // that happened to be listed
@@ -247,16 +272,16 @@ export function decideFresh(profile, components, files, tokens, root = null) {
   const P = profileOf(profile);
   if (!P.isShadcn || !profile.shadcn) return;
   const sc = profile.shadcn;
-  const dirs = installedDirs(P);
-  const own = (files.code ?? []).filter((f) => /\.[jt]sx?$/.test(f) && !underAny(f, dirs));
+  const installed = installedOf(P);
+  const own = (files.code ?? []).filter((f) => /\.[jt]sx?$/.test(f) && !installed(f));
   // build config at the root (next.config, vite.config, tailwind.config) is scaffold too
   const stem = (f) => f.split('/').pop().replace(/\.[jt]sx?$/, '').replace(/^[\w-]+\.config$/, 'app');
-  const ownComponents = (components ?? []).filter((c) => !c.isPage && !underAny(c.file, dirs));
-  const ownArbitrary = splitArbitrary(tokens?.tailwind?.arbitrary ?? [], dirs).own.reduce((s, a) => s + a.count, 0);
-  const ownInline = (tokens?.inlineStyles?.files ?? []).filter((f) => !underAny(f.file ?? f, dirs)).length;
+  const ownComponents = (components ?? []).filter((c) => !c.isPage && !installed(c.file));
+  const ownArbitrary = splitArbitrary(tokens?.tailwind?.arbitrary ?? [], installed).own.reduce((s, a) => s + a.count, 0);
+  const ownInline = (tokens?.inlineStyles?.files ?? []).filter((f) => !installed(f.file ?? f)).length;
   // the demo page the install command writes shows one Button; a page that
   // composes several doors is a screen someone built
-  const ownPages = (components ?? []).filter((c) => c.isPage && !underAny(c.file, dirs)).map((c) => c.file);
+  const ownPages = (components ?? []).filter((c) => c.isPage && !installed(c.file)).map((c) => c.file);
   const doorImports = (f) => {
     if (!root) return 0;
     let src = '';
@@ -290,7 +315,7 @@ export function ownSpacing(h) {
   const css = h.tokens?.spacing ?? [];
   const tw = (h.tokens?.tailwind?.spacing ?? []).filter((v) => v.value.startsWith('['));
   if (!P.isShadcn) return { css, tw, installed: { uses: 0, values: [] } };
-  const dirs = installedDirs(P);
-  const a = splitArbitrary(css, dirs), b = splitArbitrary(tw, dirs);
+  const installed = installedOf(P);
+  const a = splitArbitrary(css, installed), b = splitArbitrary(tw, installed);
   return { css: a.own, tw: b.own, installed: { uses: a.installed.uses + b.installed.uses, values: [...a.installed.values, ...b.installed.values].sort((x, y) => y.count - x.count) } };
 }

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

@@ -0,0 +1,74 @@
+/**
+ * Installed code on a shadcn repo: which files the team did not write.
+ *
+ * Until 9.5.0 every file in the catalogue folder (components/ui, or wherever
+ * components.json points) counted as installed: its bracket values were
+ * called shadcn's, its palette classes were not counted, and the guard left
+ * it alone. Probed on the fleet (2026-10-01): 33 of 44 shadcn product repos
+ * keep components of their own in that folder, 1,014 of 2,709 files, with
+ * 1,285 palette classes nothing counted. formbricks keeps 191 of its own
+ * there, and the report called their values shadcn's.
+ *
+ * The rule, in one place for the report, the live checks and the guard:
+ *   - a third-party registry folder (ai-elements, magicui) is installed
+ *   - a kit block (app-sidebar, login-form) is installed
+ *   - a file in the catalogue folder is installed only when it is one of
+ *     shadcn's components by name, however the team spells it (Nango keeps
+ *     Avatar.tsx and Checkbox.tsx); anything else there is the team's
+ *
+ * The name list is shadcn's own (CATALOGUE, BLOCK_COMPONENTS in
+ * shadcn-data.mjs), checked on 2026-10-01 against every component name
+ * shadcn has shipped, current and historical. A third-party component
+ * installed straight into the catalogue folder, rather than a folder of its
+ * own, reads as the team's: nothing on disk tells the two apart.
+ */
+import { basename, dirname } from 'node:path';
+import { CATALOGUE, BLOCK_COMPONENTS } from './shadcn-data.mjs';
+
+const kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').replace(/_/g, '-').toLowerCase();
+
+/** The component a file holds, by shadcn's naming: index files take their folder's name. */
+function componentName(file) {
+  const stem = basename(file).replace(/\.[cm]?[jt]sx?$/, '');
+  return kebab(stem === 'index' ? basename(dirname(file)) : stem);
+}
+
+/** Is this one of shadcn's own files: a catalogue component or a kit block, by name? */
+export function isShadcnFile(file) {
+  const n = componentName(file);
+  return CATALOGUE.has(n) || BLOCK_COMPONENTS.has(n);
+}
+
+const prefixUnder = (file, dirs) => (dirs ?? []).some((d) => file === d || file.startsWith(`${d}/`));
+
+/**
+ * Is `file` a kit door: one of shadcn's own components in the catalogue
+ * folder, or a kit block? Editing a door is the intended use, so the paint
+ * checks leave doors alone.
+ * @param from { uiDirs, shadcn: { blockFiles } } (a profileOf() reading, or the
+ *   plain `installedFrom` object the knowledge and the doorway carry)
+ * @param under how a file is matched to a folder; the guard passes its own,
+ *   which also matches when it runs in a subdirectory
+ */
+export function doorFile(from, file, under = prefixUnder) {
+  if (!from || !file) return false;
+  if (under(file, from.shadcn?.blockFiles)) return true;
+  return under(file, from.uiDirs) && isShadcnFile(file);
+}
+
+/** Is `file` installed code: a door (above), or a file in a third-party registry folder? */
+export function installedFile(from, file, under = prefixUnder) {
+  if (!from || !file) return false;
+  return under(file, from.shadcn?.registryDirs) || doorFile(from, file, under);
+}
+
+/**
+ * The plain facts installedFile and doorFile read, for a profileOf() reading:
+ * what the knowledge and the guard doorway carry. Null when nothing is
+ * installed (no shadcn kit, or a registry, whose published folders are its
+ * own work).
+ */
+export function installedFrom(P) {
+  if (!P?.isShadcn || P.isRegistry) return null;
+  return { uiDirs: [...(P.uiDirs ?? [])], shadcn: { blockFiles: [...(P.shadcn?.blockFiles ?? [])], registryDirs: [...(P.shadcn?.registryDirs ?? [])] } };
+}

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

@@ -9,7 +9,8 @@ import { distinctTypefaces } from '../lib/typefaces.mjs';
 import { nearColorPairs } from './../lib/nearpairs.mjs';
 import { neverImportedComponents } from '../lib/neverimported.mjs';
 import { VERSION } from '../lib/version.mjs';
-import { profileOf, installedDirs, splitArbitrary, ownSpacing } from '../profiles/index.mjs';
+import { profileOf, installedOf, splitArbitrary, ownSpacing } from '../profiles/index.mjs';
+import { themeClassFor } from '../lib/palette.mjs';
 import { rulesOn as lintRulesOn, describeRule as lintDescribe } from '../profiles/shadcn-lint.mjs';
 
 export function rulesMarkdown(h, opts = {}) {
@@ -157,7 +158,7 @@ if (neverImported.length >= 3) {
   // On a kit the values inside installed folders are shadcn's own: the
   // counts here are the team's, the shadcn section explains the rest.
   const P0 = profileOf(h);
-  const arbitrary = P0.isShadcn ? splitArbitrary(t.tailwind?.arbitrary ?? [], installedDirs(P0)).own : (t.tailwind?.arbitrary ?? []);
+  const arbitrary = P0.isShadcn ? splitArbitrary(t.tailwind?.arbitrary ?? [], installedOf(P0)).own : (t.tailwind?.arbitrary ?? []);
   const arbCount = arbitrary.reduce((s, a) => s + a.count, 0);
   const offScale = ownSpacing(h).css.length;
   if (t.tailwind?.spacing?.length || offScale || arbCount) {
@@ -205,10 +206,21 @@ if (neverImported.length >= 3) {
     const paint = sc.paint ?? null;
     section('shadcn: the components and the theme');
     if (P.isRegistry) rule(`This repo publishes a shadcn registry${P.registry?.publishes ? ` (${[['components', P.registry.publishes.components], ['blocks', P.registry.publishes.blocks], ['styles', P.registry.publishes.styles]].filter(([, v]) => v).map(([k, v]) => `${v} ${k}`).join(', ')})` : ''}. A palette colour, a bracket value or a hand-written dark: colour written here ships into every repo that installs it. Hold published code to the theme variables and the scale harder than app code, and keep demos and examples out of published files.`);
-    rule(`This is a shadcn install${sc.kit?.style ? ` (style \`${sc.kit.style}\`${sc.kit.baseColor ? `, base colour ${sc.kit.baseColor}` : ''})` : ''}. The theme is a set of CSS variables${sheetFile ? ` in \`${sheetFile}\`` : ''}: background, foreground, primary, muted, border and the rest, each with a light and a dark value. Change a colour there, never in a component.`);
-    if ((sc.sheet?.shadcnPresent ?? 0) >= 5 || sc.kit?.cssVariables === false) 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.');
-    else rule(`${sheetFile ? `\`${sheetFile}\` defines` : 'The theme file defines'} none of shadcn's colour variables, so \`bg-background\` and \`text-muted-foreground\` have nothing behind them here. Until the theme variables are adopted, stay with the palette classes the surrounding file already uses; do not introduce semantic classes with no variable behind them, and do not add a second palette.`);
-    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.)`);
+    const styleNote = sc.kit?.style ? ` (style \`${sc.kit.style}\`${sc.kit.baseColor ? `, base colour ${sc.kit.baseColor}` : ''})` : '';
+    if (sc.kit?.cssVariables === false) {
+      // Utility-class mode (9.5.0, words approved by Greg 2026-10-01): the
+      // components paint with Tailwind classes by design, so "use the theme
+      // variables, never a palette colour" was wrong advice here.
+      rule(`This is a shadcn install${styleNote}.`);
+      rule(utilityModeRule(sc));
+      const op = sc.ownTheme ? sc.ownThemePaint : null;
+      if (op?.uses) lines.push(`  (${op.uses} palette colour${op.uses === 1 ? '' : 's'} the theme does not own already sit in own code, ${op.samples.slice(0, 3).map((s) => `\`${s.value}\` ×${s.count}`).join(', ')}; do not add to them.)`);
+    } else {
+      rule(`This is a shadcn install${styleNote}. The theme is a set of CSS variables${sheetFile ? ` in \`${sheetFile}\`` : ''}: background, foreground, primary, muted, border and the rest, each with a light and a dark value. Change a colour there, never in a component.`);
+      if ((sc.sheet?.shadcnPresent ?? 0) >= 5) 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.');
+      else rule(`${sheetFile ? `\`${sheetFile}\` defines` : 'The theme file defines'} none of shadcn's colour variables, so \`bg-background\` and \`text-muted-foreground\` have nothing behind them here. Until the theme variables are adopted, stay with the palette classes the surrounding file already uses; do not introduce semantic classes with no variable behind them, and do not add a second palette.`);
+      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?.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.)`);
@@ -257,3 +269,56 @@ if (neverImported.length >= 3) {
   const ruleCount = text.split('\n').filter((l) => l.startsWith('- ')).length;
   return { text, ruleCount };
 }
+
+// ---------- shadcn in utility-class mode (words approved by Greg, 2026-10-01) ----------
+const andList = (xs) => (xs.length <= 1 ? xs.join('') : `${xs.slice(0, -1).join(', ')} and ${xs.at(-1)}`);
+// Tailwind names the theme gives new values, as ranges: neutral-50 to neutral-950
+function retunedRanges(retuned) {
+  const fam = new Map();
+  for (const n of retuned) {
+    const m = /^(.*)-(\d+)$/.exec(n);
+    if (!m) { fam.set(n, null); continue; }
+    if (!fam.has(m[1])) fam.set(m[1], []);
+    fam.get(m[1]).push(Number(m[2]));
+  }
+  return [...fam].map(([f, steps]) => {
+    if (!steps) return f;
+    steps.sort((a, b) => a - b);
+    return steps.length === 1 ? `${f}-${steps[0]}` : `${f}-${steps[0]} to ${f}-${steps.at(-1)}`;
+  });
+}
+// the theme's own names worth naming: the ones a palette colour gets swapped
+// for (destructive, accent), and the chart colours as a group
+const NAMED_RE = /^(destructive|danger|error|negative|success|positive|warning|caution|info|accent|brand|highlight)$/;
+function themeWords(names, retuned) {
+  const tuned = new Set(retuned);
+  const base = [...new Set(names.filter((n) => !tuned.has(n)).map((n) => n.replace(/-\d+$/, '')))];
+  const words = base.filter((n) => NAMED_RE.test(n));
+  const chart = base.some((n) => /^chart(-|$)/.test(n));
+  const picked = words.length ? words : base.filter((n) => !/(^|-)foreground$|^chart(-|$)/.test(n)).slice(0, 3);
+  return chart ? [...picked, 'the chart colours'] : picked;
+}
+function utilityModeRule(sc) {
+  const head = 'shadcn is installed without CSS variables here (components.json: cssVariables false), so the components paint with';
+  const own = sc.ownTheme;
+  if (!own) {
+    const shades = sc.doorShades ?? [];
+    // the install's base colour first (zinc on a zinc install), so the example is the everyday shade, not the destructive red
+    const base = sc.kit?.baseColor ? `-${sc.kit.baseColor}-` : null;
+    const first = (util) => (base && shades.find((s) => s.value.startsWith(util) && s.value.includes(base))) ?? shades.find((s) => s.value.startsWith(util));
+    const pick = [first('bg-'), first('text-')].filter(Boolean);
+    return `${head} Tailwind's palette classes by design. Stay with the shades they already use${pick.length ? ` (${pick.map((s) => `\`${s.value}\``).join(', ')})` : ''}. Never a hex, an rgb() or a bracket colour.`;
+  }
+  const ranges = retunedRanges(own.retuned ?? []);
+  const words = themeWords(own.names ?? [], own.retuned ?? []);
+  const gives = ranges.length ? `gives ${andList(ranges)} this repo's own values` : '';
+  const namesPart = words.length ? `names ${andList(words)}` : '';
+  const theme = gives || namesPart ? ` The theme file, \`${own.file}\`, ${[gives, namesPart].filter(Boolean).join(', and ')}. Use those classes.` : '';
+  const samples = sc.ownThemePaint?.samples ?? [];
+  const example = (samples.find((s) => !s.value.includes(':')) ?? samples[0])?.value ?? null;
+  const swap = example ? themeClassFor(example, own.names ?? [], own.values ?? {}) : null;
+  const never = example
+    ? ` Never a palette colour the theme does not own, such as \`${example}\`; ${swap ? `use \`${swap}\`, or add` : 'add'} the colour to the theme once.`
+    : ' Never a palette colour the theme does not own; add the colour to the theme once.';
+  return `${head} Tailwind classes.${theme}${never}`;
+}