roast-my-design-system 9.3.2 → 9.4.0

package/README.md

@@ -133,20 +133,20 @@ Eleven reports, hosted exactly as the tool writes them. Every number determinist
 - **[Metabase](https://gregkozakiewicz.github.io/roast-my-design-system/examples/metabase-mantine.html)** (Mantine): its own wrapper over Mantine counts as the kit, so 2,679 files are read instead of 392; nothing written onto components, 2 spacings per 100 kit files. Score 47.
 - **[SigNoz](https://gregkozakiewicz.github.io/roast-my-design-system/examples/signoz-antd.html)** (Ant Design): 2 colours and 7 spacings per 100 kit files written in style objects where a token exists. Score 51.
 - **[Apache Airflow](https://gregkozakiewicz.github.io/roast-my-design-system/examples/airflow-chakra.html)** (Chakra UI): no colours written onto components, 4 spacings per 100 kit files as pixel strings where a space step exists. Score 43.
-- **[vercel/ai-chatbot](https://gregkozakiewicz.github.io/roast-my-design-system/examples/vercel-ai-chatbot.html)** (shadcn install): 74 values like [13px] written outside the Tailwind scale, and 66 palette colours per 100 files where a theme variable exists; Claude's notes embedded. Score 80.
+- **[vercel/ai-chatbot](https://gregkozakiewicz.github.io/roast-my-design-system/examples/vercel-ai-chatbot.html)** (shadcn install): 71 values like [13px] written outside the Tailwind scale, and 66 palette colours per 100 files where a theme variable exists; Claude's notes embedded. Score 80.
 - **[excalidraw/excalidraw](https://gregkozakiewicz.github.io/roast-my-design-system/examples/excalidraw-excalidraw.html)**: 78 off-scale spacing values and 90 !important declarations. Score 55.
-- **[dubinc/dub](https://gregkozakiewicz.github.io/roast-my-design-system/examples/dubinc-dub.html)**: 624 arbitrary bracket values, 21 duplicated components, and the chart-palette gap named. Score 20.
+- **[dubinc/dub](https://gregkozakiewicz.github.io/roast-my-design-system/examples/dubinc-dub.html)**: 642 arbitrary bracket values, 21 duplicated components, and the chart-palette gap named. Score 20.
 - **[telekom/scale](https://gregkozakiewicz.github.io/roast-my-design-system/examples/telekom-scale.html)** (Stencil): 95 Stencil components read by tag; 66 spacing values outside the scale where about 12 would do; Claude's notes embedded. Score 55.
 - **[magicuidesign/magicui](https://gregkozakiewicz.github.io/roast-my-design-system/examples/magicui.html)** (registry): counted on the components it publishes, 52 off-theme colours per 100 files in the code it ships, its docs site kept out and named. Score 78.
 - **[adobe/spectrum-web-components](https://gregkozakiewicz.github.io/roast-my-design-system/examples/adobe-spectrum.html)** (Lit): hardcoded colours sitting beside 744 colour tokens, and 37 !important declarations. Score 66.
 
 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.2.6)
+![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 same report in light mode (one file, built-in toggle):
 
-![The diagnosis report in light mode](assets/report-light-hero.png?v=9.2.6)
+![The diagnosis report in light mode](assets/report-light-hero.png?v=9.3.3)
 
 ## Why the numbers hold
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "9.3.2",
+  "version": "9.4.0",
   "mcpName": "io.github.gregkozakiewicz/roast-my-design-system",
   "description": "Your AI can write the UI. This makes sure it writes your UI. A deterministic scanner scores your design system 0-100 against 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/harvest/tokens.mjs

@@ -8,7 +8,7 @@
  */
 import { existsSync } from 'node:fs';
 import {
-  isEmail, EMAIL_KIT_RE, ARTWORK_NAME_RE, foreignStylesheet, RENDER_TO_IMAGE_RE, OG_ROUTE_RE, RENDERER_PATH_RE, CRASH_PAGE_RE, svgHeavy, exemptReason, isLibraryClass, WIDGET_CSS_RE, WIDGET_CONFIG_RE,
+  isEmail, foreignStylesheet, CRASH_PAGE_RE, exemptReason, isLibraryClass, WIDGET_CSS_RE, WIDGET_CONFIG_RE,
 } from '../lib/exempt.mjs';
 import { join } from 'node:path';
 import { canonical, parseColor } from '../lib/color.mjs';
@@ -25,7 +25,10 @@ class Tally {
     e.count++;
     e.files.set(file, (e.files.get(file) ?? 0) + 1);
   }
-  toJSON(limitFiles = 5) {
+  // `every` keeps the whole per-file tally beside the capped list shown in
+  // the report, for a caller that has to split the count by folder exactly
+  // (profiles/splitArbitrary: installed code against the team's own).
+  toJSON(limitFiles = 5, { every = false } = {}) {
     return [...this.map.values()]
       .sort((a, b) => b.count - a.count)
       .map((e) => ({
@@ -33,6 +36,7 @@ class Tally {
         count: e.count,
         files: [...e.files.entries()].sort((a, b) => b[1] - a[1]).slice(0, limitFiles)
           .map(([file, count]) => ({ file, count })),
+        ...(every ? { every: [...e.files.entries()].map(([file, count]) => ({ file, count })) } : {}),
       }));
   }
 }
@@ -500,7 +504,6 @@ export function harvestTokens(root, styleFiles, codeFiles, { email = null } = {}
   // reason to discredit the whole report.
   // Email, artwork, mostly-SVG files and pixel renderers: all imported from
   // lib/exempt.mjs, the one list every checker reads.
-  const ARTWORK_RE = ARTWORK_NAME_RE;
   // every file a check skipped, with the reason, so the report can name them
   const exemptFiles = [];
   const skip = (f, src) => { const r = exemptReason(f, src, { email }); if (r) exemptFiles.push({ file: f, reason: r }); return true; };
@@ -566,18 +569,14 @@ export function harvestTokens(root, styleFiles, codeFiles, { email = null } = {}
       paletteFiles.add(f);
       for (const m of src.matchAll(HEX_RE)) tokenDefined.add(normalizeHex(m[0]));
     }
-    if (ARTWORK_RE.test(f) || RENDERER_PATH_RE.test(f) || svgHeavy(src)) { skip(f, src); continue; }
-    // A render-to-image surface (OG card, PDF invoice) is artwork drawn with
-    // code: its colours are the picture's, not the product's palette. Until
-    // 5.10.0 they were the only "strays" a clean shadcn repo had, and they
-    // triggered the "every single one is hardcoded" banner on it.
-    const renderToImage = RENDER_TO_IMAGE_RE.test(src) || OG_ROUTE_RE.test(f);
-    if (renderToImage) { skip(f, src); continue; }
-    // a page a headless browser prints to a PDF (rybbit's reports), found by
-    // the walk from the file that prints it (lib/exempt.mjs printedFilesOf)
-    if (email?.printed?.includes(f)) { skip(f, src); continue; }
-    // an email written with an email kit, wherever it lives (react-email)
-    if (EMAIL_KIT_RE.test(src)) { skip(f, src); continue; }
+    // Artwork, renderers, render-to-image surfaces (OG cards, PDF invoices),
+    // pages a headless browser prints, emails written with a kit: one rule,
+    // lib/exempt.mjs, the same answer the live checks and the guard give.
+    // Until 9.3.3 this counter kept its own list, and the two had drifted: a
+    // file named Badge or IconButton walked free here on its name alone
+    // (2,321 files in 173 repos) while an icon in an icons folder was
+    // counted here and exempt everywhere else (likec4's 12,203 icon colours).
+    if (exemptReason(f, src, { email })) { skip(f, src); continue; }
 
     // Tailwind classes
     for (const cls of classStrings(src)) {
@@ -603,7 +602,7 @@ export function harvestTokens(root, styleFiles, codeFiles, { email = null } = {}
     // length inside them is still a hardcoded value — harvest those from every
     // non-trivial block; count only the all-literal blocks.
     const allBlocks = inlineStyleBlocks(src).filter((b) => !TRIVIAL_INLINE_RE.test(b.trim()));
-    const staticBlocks = renderToImage ? [] : allBlocks.filter(isStaticInline);
+    const staticBlocks = allBlocks.filter(isStaticInline);
     if (staticBlocks.length) {
       inlineStyleCount += staticBlocks.length;
       inlineStyleFiles.set(f, (inlineStyleFiles.get(f) ?? 0) + staticBlocks.length);
@@ -810,7 +809,7 @@ export function harvestTokens(root, styleFiles, codeFiles, { email = null } = {}
       spacing: twSpacing.toJSON(),
       radii: twRadii.toJSON(),
       textSizes: twTextSizes.toJSON(),
-      arbitrary: twArbitrary.toJSON(),
+      arbitrary: twArbitrary.toJSON(5, { every: true }),
     },
     important: {
       // aimed at a library's own class names: kept out, named at the top

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

@@ -17,6 +17,7 @@ export { designGaps } from './gaps.mjs';
 import { decideProfile, profileOf, installedDirs } 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,14 @@ 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 };
 // 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
@@ -225,8 +234,14 @@ export function learnSystem(repoRoot, { exclude = [] } = {}) {
       // 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,178 @@
+/**
+ * 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';
+
+// 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;
+  // 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 ?? [])];
+  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) || (palette.doors ?? []).some((d) => file === d || file.startsWith(`${d}/`)))) 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 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.2';
+export const VERSION = '9.4.0';
 // The shape of harvest.json and summary.json. Bumped only when a field is
 // renamed, removed or changes meaning; a new field is not a new schema. A
 // tool comparing two scans compares like with like by this number, not by VERSION.

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

@@ -18,9 +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 { 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 { 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 +45,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 +178,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();
@@ -396,59 +349,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

@@ -210,6 +210,9 @@ export function loadKnowledge(root) {
     // 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,8 @@ 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 mui from './mui.mjs';
 import mantine from './mantine.mjs';
 import chakra from './chakra.mjs';
@@ -82,6 +83,12 @@ 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);
   // 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 +161,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,
@@ -197,14 +206,18 @@ export function splitArbitrary(entries, dirs) {
   const installedValues = new Map();
   let installedUses = 0;
   for (const e of entries) {
-    const ownFiles = (e.files ?? []).filter((f) => !underAny(f.file, dirs));
-    const instFiles = (e.files ?? []).filter((f) => underAny(f.file, dirs));
-    const instCount = instFiles.reduce((s, f) => s + f.count, 0);
+    // the whole per-file tally when the harvest kept one (every), else the
+    // capped list: a use in a file that fell off the list of five was counted
+    // 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);
     if (instCount) { installedUses += instCount; installedValues.set(e.value, (installedValues.get(e.value) ?? 0) + instCount); }
-    // the file list under an entry is capped, so own is the remainder of the
-    // entry's total, never a sum of the files that happened to be listed
+    // own is the remainder of the entry's total, never a sum of the files
+    // that happened to be listed
     const ownCount = e.count - instCount;
-    if (ownCount > 0) own.push({ ...e, count: ownCount, files: ownFiles });
+    if (ownCount > 0) { const { every, ...rest } = e; own.push({ ...rest, count: ownCount, files: ownFiles }); }
   }
   own.sort((a, b) => b.count - a.count);
   const values = [...installedValues.entries()].sort((a, b) => b[1] - a[1]).map(([value, count]) => ({ value, count }));

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;
   },
 };