roast-my-design-system 9.3.3 → 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.3.3",
+  "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,9 +14,10 @@ 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';
 import { PALETTE_CLASS_RE, DEMO_PATH_RE, blankComments } from '../harvest/paint.mjs';
 import { harvestTokens, extractStyling, normalizeHex, isGrey } from '../harvest/tokens.mjs';
 import { harvestComponents, definedComponents, tsconfigAliases } from '../harvest/components.mjs';
@@ -67,6 +68,19 @@ export { WIDGET_CSS_RE, WIDGET_CONFIG_RE, LIBRARY_CLASS_RE, isLibraryClass } fro
 // examples and demos: a guard that skips them flags palette classes in the
 // same files the report counts.
 export { PALETTE_CLASS_RE, DEMO_PATH_RE, blankComments };
+// The palette rule itself (9.4.0): paletteFindings(fileText, system.profile
+// .palette, { file }) returns the worded findings the live checks give for
+// the same file, with the index of each in the text; empty when the rule is
+// off, on a stylesheet, in a demo folder or inside a kit door. Which
+// vocabulary applies was decided once by the profile (lib/palette.mjs), so
+// 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
@@ -135,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
@@ -216,17 +229,27 @@ 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,
-      // a shadcn kit whose theme file holds the variables, in CSS-variable
-      // mode: a palette class in own code is paint from a tin
+      // the vocabulary the palette rule judges against, or null when it is
+      // off: a Tailwind theme's own names, shadcn's names when the sheet's
+      // contract holds in CSS-variable mode, or the repo's own theme under a
+      // shadcn kit with no rows (lib/palette.mjs, 9.4.0). Hand it to
+      // paletteFindings.
+      palette: P.palette,
+      // superseded by `palette` in 9.4.0; kept one release for readers of the
+      // old shape. The old gate read the configured sheet's :root rows alone.
       paletteReady: P.isShadcn && (P.shadcn?.sheet?.shadcnPresent ?? 0) >= 5 && P.designSystem?.cssVariables !== false,
       sheetFile: P.shadcn?.sheet?.found ? P.shadcn.sheet.file : null,
       // packages whose Tailwind config scopes utilities under an id: widgets

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

@@ -0,0 +1,195 @@
+/**
+ * Palette classes where the theme names its colours: one rule, read by the
+ * report's live checks (validate, review, --check, the edit hook, the
+ * end-of-turn review) and by the guard through the doorway.
+ *
+ * Until 9.4.0 the rule lived twice. The live checks switched it on for a
+ * Tailwind theme and for any shadcn repo; the guard switched it on only for
+ * a shadcn repo whose configured sheet held five of shadcn's rows under
+ * :root. Probed on the fleet (2026-10-01): the guard was silent on 11 of 48
+ * shadcn repos where the live checks spoke (formbricks writes its theme
+ * straight into @theme, documenso names no sheet path, Nango and Ghost keep
+ * a v4 theme of their own and no shadcn rows), and the live checks flagged
+ * 1,394 palette classes in rybbit's last 300 changes where the report says
+ * the palette is the theme (utility-class mode). A rule kept in two places
+ * drifts; this is the one place.
+ *
+ * decidePalette answers once, from the profile, which vocabulary a palette
+ * class is judged against (profiles/index.mjs stores it as profile.palette):
+ *   1. a Tailwind theme in use: its own names, with the theme's families
+ *      (a palette grey is only drift where the theme has a grey) and its
+ *      retuned names (a palette name given the repo's own colour is the
+ *      theme, not drift)
+ *   2. a shadcn install in CSS-variable mode whose theme contract holds,
+ *      five or more of shadcn's ten rows in any of its stylesheets: shadcn's
+ *      names
+ *   3. a shadcn install with no contract but a v4 theme of its own: that
+ *      theme's names, as in 1
+ *   4. utility-class mode (the palette is the theme, as the report says), or
+ *      nothing to point at: off
+ * paletteFindings words the hits, the same words on every door: the class,
+ * the theme file, the theme colour nearest by value that suits the utility,
+ * and what to add when none fits.
+ */
+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
+const SHADCN_NAMES = ['primary', 'foreground', 'muted-foreground', 'background', 'border'];
+// rows of shadcn's contract that make the sheet the vocabulary
+export const CONTRACT_MIN = 5;
+const CSS_FILE_RE = /\.(css|scss|sass|less|styl)$/i;
+
+const fromTheme = (t, doors) => ({
+  source: 'tailwind', file: t.file, names: t.names, values: t.values ?? {}, retuned: t.retuned ?? [],
+  families: t.families ?? null, adopted: t.adopted !== false, doors,
+});
+
+/**
+ * The vocabulary a palette class is judged against, or null when the rule
+ * is off. `readTheme()` reads the repo's own v4 theme on demand (case 3),
+ * the same reader the Tailwind profile uses.
+ * @returns {{ source, file, names, values, retuned, families, adopted?, doors } | null}
+ */
+export function decidePalette(profile, P, readTheme = null) {
+  if (P.isTailwind && profile.tailwind) return fromTheme(profile.tailwind, []);
+  if (!P.isShadcn || !profile.shadcn) return 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;
+  // 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 {
+      source: 'shadcn', file: sc.sheet?.found ? sc.sheet.file : sc.contract?.file ?? null,
+      names: SHADCN_NAMES, values: {}, retuned: [], families: null, doors,
+    };
+  }
+  const own = typeof readTheme === 'function' ? readTheme() : null;
+  return own ? fromTheme(own, doors) : null;
+}
+
+/**
+ * The palette classes in a piece of text that the vocabulary answers, each
+ * with the fix in the engine's words. Empty when the rule is off, on a
+ * stylesheet, in a demo folder or inside a kit door. `index` is the class's
+ * position in `text`; comments are blanked, not cut, so it holds.
+ * @returns [{ rule: 'palette-class', severity: 'violation', index, value, themeFile, example, message, fix }]
+ */
+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) || 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);
+  const themeFile = palette.file ?? 'the theme sheet';
+  // the example name follows the utility: a text- class wants an ink or
+  // foreground name, a bg- class a surface or background name
+  const names = palette.names ?? [];
+  const pick = (re) => names.find((n) => re.test(n)) ?? names[0] ?? 'brand';
+  const values = palette.values ?? {};
+  // a class named in a comment paints nothing; blanked, not cut, so the
+  // indexes still point at their line
+  const code = blankComments(text);
+  const hits = [...code.matchAll(PALETTE_CLASS_RE)];
+  // the evening override painted by hand (dark:bg-black) is the same sin on a
+  // shadcn sheet, which always has a dark row of its own
+  if (palette.source === 'shadcn') hits.push(...code.matchAll(DARK_WB_RE));
+  const out = [];
+  for (const m of hits.sort((a, b) => a.index - b.index)) {
+    const cls = m[0];
+    const util = cls.replace(/^((?:[\w-]+:)*[a-z]+)-.*$/, '$1');
+    const shade = cls.replace(/^(?:[\w-]+:)*[a-z]+-/, '').replace(/\/\d+$/, '');
+    if (retuned.has(shade)) continue;
+    if (!hasFamily(cls)) continue;
+    const role = utilRole(util);
+    // the theme colour nearest by value among the names that suit the
+    // utility; the pick by name alone only when none is close
+    const example = nearestThemeName(shade, role, values)
+      ?? (role === 'text' ? pick(/ink|text|fg|foreground/) : role === 'surface' ? pick(/surface|bg|background|canvas/) : pick(/border|edge|line|ring/));
+    const word = hueWord(shade, names);
+    out.push({
+      rule: 'palette-class', severity: 'violation', index: m.index, value: cls, themeFile, example: `${util}-${example}`,
+      message: `Palette class ${cls} where the theme names its colours (${themeFile}).`,
+      fix: `Use a theme token as the class (${util}-${example}). ${names.includes(word)
+        ? `If no token fits, add ${/^[aeiou]/.test(word) ? 'an' : 'a'} ${word} shade to the theme once and use it by name.`
+        : `If no token fits, add one to the theme once, for example ${word}, and use ${util}-${word}.`}`,
+    });
+  }
+  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
+// these (brand, warning, positive) is an accent and suits every utility.
+const TEXT_NAME_RE = /ink|text|fg|foreground/;
+const SURFACE_NAME_RE = /surface|(^|-)bg(-|$)|background|canvas|soft|tint|wash/;
+const EDGE_NAME_RE = /border|edge|line|ring|divider|outline/;
+function utilRole(util) {
+  if (/(^|:)(?:text|placeholder|caret|decoration|fill|stroke)$/.test(util)) return 'text';
+  if (/(^|:)bg$/.test(util)) return 'surface';
+  if (/(^|:)(?:border|ring|outline|divide)$/.test(util)) return 'edge';
+  return 'any';
+}
+function suits(name, role) {
+  const text = TEXT_NAME_RE.test(name), surface = SURFACE_NAME_RE.test(name), edge = EDGE_NAME_RE.test(name);
+  if (role === 'any' || (!text && !surface && !edge)) return true;
+  return role === 'text' ? text && !surface && !edge : role === 'surface' ? surface : edge;
+}
+// Distance in OKLab with the two colour axes doubled, so a pale amber lands on
+// the pale warning surface rather than on the near-white canvas beside it.
+const hueDistance = (x, y) => Math.hypot(x.L - y.L, 2 * (x.a - y.a), 2 * (x.b - y.b));
+// Past this, the nearest theme colour is a different colour, not a stand-in
+// (bg-blue-600 against a theme of greys), and the pick by name answers.
+const CLOSE = 0.2;
+/** The suitable theme name nearest to a palette shade's Tailwind value, or null. */
+function nearestThemeName(shade, role, values) {
+  const from = oklab(TAILWIND_DEFAULTS[shade] ?? '');
+  if (!from) return null;
+  let best = null;
+  for (const [name, value] of Object.entries(values)) {
+    if (!suits(name, role)) continue;
+    const to = oklab(value);
+    if (!to) continue;
+    const d = hueDistance(from, to);
+    if (!best || d < best.d) best = { name, d };
+  }
+  return best && best.d <= CLOSE ? best.name : null;
+}
+// The word for a new token follows the hue, in the theme's own vocabulary when
+// it has one (Ledgerly says positive and negative, not success and danger).
+const HUE_WORDS = [
+  [/^(?:red|rose)-/, ['negative', 'danger', 'error', 'destructive']],
+  [/^(?:orange|amber|yellow)-/, ['warning', 'caution']],
+  [/^(?:green|emerald|lime)-/, ['positive', 'success']],
+  [/^(?:blue|sky|cyan)-/, ['info']],
+];
+function hueWord(shade, names) {
+  const words = HUE_WORDS.find(([re]) => re.test(shade))?.[1];
+  if (!words) return GREY_HUE_RE.test(`-${shade}`) ? 'muted' : 'accent';
+  return words.find((w) => names.some((n) => n === w || n.startsWith(`${w}-`)))
+    ?? { negative: 'danger', warning: 'warning', positive: 'success', info: 'info' }[words[0]];
+}

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.3.3';
+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,9 +18,8 @@ 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 { 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 '../lib/color.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';
 import { isChartFile, chartFindings } from '../lib/charts.mjs';
@@ -47,7 +46,7 @@ export const KIT_CHECK = 'colours and pixel sizes written onto kit components wh
 export const PALETTE_CHECK = 'palette classes where the theme names a colour';
 export const BUTTON_CHECK = 'hand-made buttons where the repo has a Button';
 export function checksFor(k) {
-  const list = k?.kit ? [...CHECKS, KIT_CHECK] : (k?.tailwind || k?.shadcn) ? [...CHECKS, PALETTE_CHECK] : [...CHECKS];
+  const list = k?.kit ? [...CHECKS, KIT_CHECK] : k?.palette ? [...CHECKS, PALETTE_CHECK] : [...CHECKS];
   if (k?.buttons?.length) list.push(BUTTON_CHECK);
   return list;
 }
@@ -180,57 +179,12 @@ export function validateContent(content, k) {
   }
 
   // ---------- palette classes where the theme names its colours ----------
-  // A Tailwind theme names its colours (bg-surface, text-ink); a shadcn sheet
-  // names them too (bg-primary, text-muted-foreground). A palette class
-  // (text-gray-500, ring-green-500) where a name of that kind exists is paint
-  // from the tin. Same rule as the report's tile, from harvest/paint.mjs.
-  // On a shadcn repo the catalogue and kit blocks are the kit's own doors
-  // (editing them is the intended use) and a demo folder is not own code,
-  // exactly the files the tile leaves out.
-  const inShadcnDoors = (f) => !!f && k.shadcn.doors.some((d) => f === d || f.startsWith(`${d}/`));
-  // A demo folder is left out on a Tailwind theme too: the report's tile never
-  // counted one, and the live check flagged it (2026-09-30).
-  const demo = !!file && DEMO_PATH_RE.test(file);
-  const paletteRule = k.tailwind ? (demo ? null : 'tailwind')
-    : k.shadcn && !(file && (inShadcnDoors(file) || demo)) ? 'shadcn'
-    : null;
-  if (paletteRule && !css) {
-    const tw = k.tailwind ?? {};
-    const retuned = new Set(tw.retuned ?? []);
-    const fam = tw.families ?? null;
-    const hasFamily = (cls) => !fam || (GREY_HUE_RE.test(cls) ? fam.grey : fam.colour);
-    const themeFile = paletteRule === 'tailwind' ? tw.file : (k.shadcn.sheet ?? 'the theme sheet');
-    // the example name follows the utility: a text- class wants an ink or
-    // foreground name, a bg- class a surface or background name
-    const names = paletteRule === 'tailwind' ? (tw.names ?? []) : ['primary', 'foreground', 'muted-foreground', 'background', 'border'];
-    const pick = (re) => names.find((n) => re.test(n)) ?? names[0] ?? 'brand';
-    const values = paletteRule === 'tailwind' ? tw.values ?? {} : {};
-    // a class named in a comment paints nothing; blanked, not cut, so the
-    // line numbers below still hold
-    const code = blankComments(text);
-    const hits = [...code.matchAll(PALETTE_CLASS_RE)];
-    // the evening override painted by hand (dark:bg-black) is the same sin
-    // on a shadcn sheet, which always has a dark row of its own
-    if (paletteRule === 'shadcn') hits.push(...code.matchAll(DARK_WB_RE));
-    for (const m of hits.sort((a, b) => a.index - b.index)) {
-      const cls = m[0];
-      const util = cls.replace(/^((?:[\w-]+:)*[a-z]+)-.*$/, '$1');
-      const shade = cls.replace(/^(?:[\w-]+:)*[a-z]+-/, '').replace(/\/\d+$/, '');
-      const role = utilRole(util);
-      // the theme colour nearest by value among the names that suit the
-      // utility; the old pick by name alone only when none is close
-      const example = nearestThemeName(shade, role, values)
-        ?? (role === 'text' ? pick(/ink|text|fg|foreground/) : role === 'surface' ? pick(/surface|bg|background|canvas/) : pick(/border|edge|line|ring/));
-      if (retuned.has(shade)) continue;
-      if (!hasFamily(cls)) continue;
-      const word = hueWord(shade, names);
-      add('palette-class', 'violation', m.index,
-        `Palette class ${cls} where the theme names its colours (${themeFile}).`,
-        `Use a theme token as the class (${util}-${example}). ${names.includes(word)
-          ? `If no token fits, add ${/^[aeiou]/.test(word) ? 'an' : 'a'} ${word} shade to the theme once and use it by name.`
-          : `If no token fits, add one to the theme once, for example ${word}, and use ${util}-${word}.`}`);
-    }
-  }
+  // One rule for every door (lib/palette.mjs): which vocabulary applies, a
+  // Tailwind theme, shadcn's sheet or the repo's own theme under a shadcn
+  // kit, was decided once by the profile. The catalogue, kit blocks and demo
+  // folders are left out there, the same files the report's tile leaves out,
+  // and utility-class mode switches the rule off, as the report scores it.
+  for (const f of paletteFindings(text, k.palette, { file, css })) add(f.rule, f.severity, f.index, f.message, f.fix);
 
   // ---------- colours ----------
   const seenHere = new Set();
@@ -293,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) {
@@ -396,59 +352,6 @@ export function validateContent(content, k) {
   return { findings, checked: checksFor(k) };
 }
 
-// ---------- 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
-// these (brand, warning, positive) is an accent and suits every utility.
-const TEXT_NAME_RE = /ink|text|fg|foreground/;
-const SURFACE_NAME_RE = /surface|(^|-)bg(-|$)|background|canvas|soft|tint|wash/;
-const EDGE_NAME_RE = /border|edge|line|ring|divider|outline/;
-function utilRole(util) {
-  if (/(^|:)(?:text|placeholder|caret|decoration|fill|stroke)$/.test(util)) return 'text';
-  if (/(^|:)bg$/.test(util)) return 'surface';
-  if (/(^|:)(?:border|ring|outline|divide)$/.test(util)) return 'edge';
-  return 'any';
-}
-function suits(name, role) {
-  const text = TEXT_NAME_RE.test(name), surface = SURFACE_NAME_RE.test(name), edge = EDGE_NAME_RE.test(name);
-  if (role === 'any' || (!text && !surface && !edge)) return true;
-  return role === 'text' ? text && !surface && !edge : role === 'surface' ? surface : edge;
-}
-// Distance in OKLab with the two colour axes doubled, so a pale amber lands on
-// the pale warning surface rather than on the near-white canvas beside it.
-const hueDistance = (x, y) => Math.hypot(x.L - y.L, 2 * (x.a - y.a), 2 * (x.b - y.b));
-// Past this, the nearest theme colour is a different colour, not a stand-in
-// (bg-blue-600 against a theme of greys), and the old pick by name answers.
-const CLOSE = 0.2;
-/** The suitable theme name nearest to a palette shade's Tailwind value, or null. */
-function nearestThemeName(shade, role, values) {
-  const from = oklab(TAILWIND_DEFAULTS[shade] ?? '');
-  if (!from) return null;
-  let best = null;
-  for (const [name, value] of Object.entries(values)) {
-    if (!suits(name, role)) continue;
-    const to = oklab(value);
-    if (!to) continue;
-    const d = hueDistance(from, to);
-    if (!best || d < best.d) best = { name, d };
-  }
-  return best && best.d <= CLOSE ? best.name : null;
-}
-// The word for a new token follows the hue, in the theme's own vocabulary when
-// it has one (Ledgerly says positive and negative, not success and danger).
-const HUE_WORDS = [
-  [/^(?:red|rose)-/, ['negative', 'danger', 'error', 'destructive']],
-  [/^(?:orange|amber|yellow)-/, ['warning', 'caution']],
-  [/^(?:green|emerald|lime)-/, ['positive', 'success']],
-  [/^(?:blue|sky|cyan)-/, ['info']],
-];
-function hueWord(shade, names) {
-  const words = HUE_WORDS.find(([re]) => re.test(shade))?.[1];
-  if (!words) return GREY_HUE_RE.test(`-${shade}`) ? 'muted' : 'accent';
-  return words.find((w) => names.some((n) => n === w || n.startsWith(`${w}-`)))
-    ?? { negative: 'danger', warning: 'warning', positive: 'success', info: 'info' }[words[0]];
-}
-
 function looksLikeCss(text) {
   // no JSX tags, has a `{ ...: ` declaration shape → treat as stylesheet.
   // Sniffed on the head of the text with bounded patterns: the old version

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,10 +206,16 @@ 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,
     tailwind: P.isTailwind && profile.tailwind ? profile.tailwind : null,
+    // the vocabulary the palette rule judges against, decided once by the
+    // profile (lib/palette.mjs); null switches the rule off
+    palette: P.palette,
     // A shadcn kitchen: the sheet names the colours, so a palette class in
     // own code is paint from a tin (shadcn's own rule: semantic colours,
     // never bg-blue-500). The report's tile counts it over own code plus

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

@@ -52,7 +52,14 @@ export function getContext(k, { path = null } = {}) {
     if (kit.colour?.uses) L.push(`  ${kit.colour.uses} colours are already written onto components (${kit.colour.samples.slice(0, 3).map((x) => x.value).join(', ')}); do not add one.`);
   } else if (t.tokenFile) {
     const strays = t.colors.length - k.tokenColors.length;
-    L.push(`TOKENS: ${k.tokenColors.length} colour tokens in ${t.tokenFile}. Use them${k.shadcn ? ' as classes (bg-primary, text-muted-foreground); never a palette class (text-gray-500, ring-green-500) and' : ';'} never hardcode a colour. Do not add a token that duplicates an existing one; reuse it.${strays ? ` (${strays} hardcoded strays already exist; do not add more.)` : ''}`);
+    // on a shadcn kit the example classes follow the vocabulary the palette
+    // rule judges against (lib/palette.mjs): shadcn's names, or the repo's own
+    // theme when it keeps one and no shadcn rows; in utility-class mode the
+    // palette is the theme and the clause is dropped
+    const pal = k.shadcn ? k.palette : null;
+    const pick = (re, i) => (pal?.names ?? []).find((n) => re.test(n)) ?? pal?.names?.[i] ?? 'brand';
+    const examples = pal?.source === 'tailwind' ? `bg-${pick(/surface|(^|-)bg(-|$)|background|canvas/, 0)}, text-${pick(/ink|text|fg|foreground/, 1)}` : 'bg-primary, text-muted-foreground';
+    L.push(`TOKENS: ${k.tokenColors.length} colour tokens in ${t.tokenFile}. Use them${pal ? ` as classes (${examples}); never a palette class (text-gray-500, ring-green-500) and` : ';'} never hardcode a colour. Do not add a token that duplicates an existing one; reuse it.${strays ? ` (${strays} hardcoded strays already exist; do not add more.)` : ''}`);
   } else if (t.colors.length) {
     L.push(`TOKENS: none defined. ${t.colors.length} distinct colours already in play; reuse one, never invent another.`);
   }

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

@@ -22,7 +22,9 @@ import { join, basename, dirname } from 'node:path';
  * fixture's expected output is byte-identical before and after.
  */
 import shadcn from './shadcn.mjs';
-import tailwind from './tailwind.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';
@@ -82,6 +84,19 @@ export function decideProfile(profile, components, files, root = null) {
   profile.kind = picked.kind;
   profile.kindConfidence = decision.confidence;
   profile.kindEvidence = decision.evidence;
+  // Which vocabulary a palette class is judged against, decided once here
+  // and read by the live checks and the guard (lib/palette.mjs): a Tailwind
+  // theme, shadcn's sheet when its contract holds, the repo's own theme
+  // 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.
@@ -154,6 +169,8 @@ export function profileOf(h) {
     // a Tailwind repo with its own theme and no kit
     isTailwind: kind === 'tailwind',
     tailwind: p.tailwind ?? null,
+    // the vocabulary the palette rule judges against, or null when it is off
+    palette: p.palette ?? null,
     // a product built on a component kit installed from npm (mui)
     isKit: !!p.kit,
     kit: p.kit ?? null,
@@ -185,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;
@@ -202,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
@@ -238,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 = '';
@@ -281,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/profiles/shadcn.mjs

@@ -328,6 +328,12 @@ export default {
     if (registryDirs.length) evidence.push(`${registryDirs.length} installed registr${registryDirs.length === 1 ? 'y' : 'ies'} beside it: ${registryDirs.map((d) => basename(d)).join(', ')}`);
     profile.shadcn = {
       installs: installs.map((i) => ({ config: i.config, uiDir: i.uiDir, catalogueNames: i.catalogueNames })),
+      // the theme contract: how many of shadcn's rows any stylesheet defines,
+      // and the file carrying most of them. The configured sheet can hold
+      // none under :root (formbricks writes its theme straight into @theme,
+      // a sibling package keeps the rows) while the contract still holds;
+      // the palette rule reads this, not the sheet alone (lib/palette.mjs)
+      contract: { rows: contract, file: themeContract.file ?? null },
       kit,
       sheet,
       blockFiles,

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

@@ -118,15 +118,16 @@ function countUses(root, codeFiles, styleFiles, own) {
   return { uses, files };
 }
 
-export default {
-  kind: 'tailwind',
-
-  /**
-   * @param profile the profiler's facts (mutated: designSystem, tailwind)
-   * @param counts reusable/pages/codeFiles
-   * @param ctx { root, files }
-   */
-  recognise(profile, counts, ctx) {
+/**
+ * The repo's own v4 theme, read without deciding anything: the facts the
+ * profile stores as `tailwind` and the evidence for the decision, or null
+ * when there is no theme worth judging. Exported so the palette rule can
+ * read the theme of a repo another kind claimed (a shadcn install with no
+ * shadcn rows but a theme of its own, lib/palette.mjs). Reads `profile`,
+ * never writes it.
+ * @returns {{ facts, decision } | null}
+ */
+export function readTailwindTheme(profile, ctx) {
     if (!ctx?.root || !ctx?.files) return null;
     const { root, files } = ctx;
     const twRaw = profile.stylingDeps?.includes('Tailwind CSS') || /tailwind/i.test((profile.stylingDeps ?? []).join(' '))
@@ -158,8 +159,7 @@ export default {
       twRaw ? `Tailwind ${twRaw}` : 'Tailwind v4 theme block',
     ];
     const values = resolveValues(root, files.styles, theme.own.map((x) => [x, theme.names.get(x)]));
-    profile.designSystem = { kind: 'tailwind', name: 'a Tailwind theme', confidence: 'high', cssVariables: true };
-    profile.tailwind = {
+    const facts = {
       file: theme.file,
       names: theme.own,
       restated: theme.names.size - theme.own.length,
@@ -175,6 +175,22 @@ export default {
       // a theme nobody uses is not the system yet: shown with receipts, not scored
       adopted: usedEnough(uses, theme.own.length),
     };
-    return { confidence: usedEnough(uses, theme.own.length) ? 'high' : 'medium', evidence };
+    return { facts, decision: { confidence: usedEnough(uses, theme.own.length) ? 'high' : 'medium', evidence } };
+}
+
+export default {
+  kind: 'tailwind',
+
+  /**
+   * @param profile the profiler's facts (mutated: designSystem, tailwind)
+   * @param counts reusable/pages/codeFiles
+   * @param ctx { root, files }
+   */
+  recognise(profile, counts, ctx) {
+    const read = readTailwindTheme(profile, ctx);
+    if (!read) return null;
+    profile.designSystem = { kind: 'tailwind', name: 'a Tailwind theme', confidence: 'high', cssVariables: true };
+    profile.tailwind = read.facts;
+    return read.decision;
   },
 };

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}`;
+}