roast-my-design-system 8.4.6 → 8.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "8.4.6",
+  "version": "8.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/harvest/components.mjs

@@ -4,7 +4,7 @@
  * compile-skill.mjs — brace/string-aware regex parsing,
  * no AST dependency — then extended to scan the whole repo, not one ui/ dir.
  */
-import { join, basename } from 'node:path';
+import { join, basename, posix } from 'node:path';
 import { readSource } from './walk.mjs';
 
 const QUOTES = new Set(['"', "'", '`']);
@@ -161,6 +161,37 @@ function tagCounts(src, re) {
   return counts;
 }
 
+const stripExt = (f) => f.replace(/\.[cm]?[jt]sx?$/, '');
+/**
+ * Which of several same-named definitions a file's `<Name` means, read from
+ * its imports: `import { Button } from '../ui'` or `'./ButtonV2'`, relative
+ * or through an alias (`@/ui/Button`, matched as a path suffix). A barrel
+ * (`../ui` → ui/index.ts) resolves to the copy inside that folder. A file that
+ * defines the name itself means its own. Returns [def] or null when unsure.
+ */
+function importedDef(src, file, name, defs) {
+  const own = defs.find((d) => d.file === file);
+  if (own) return [own];
+  for (const m of src.matchAll(/import\s+(?:type\s+)?([^'";]*?)\s+from\s*['"]([^'"]+)['"]/g)) {
+    const clause = m[1];
+    const named = /\{([^}]*)\}/.exec(clause)?.[1] ?? '';
+    const imports = named.split(',').map((x) => x.trim().replace(/^type\s+/, '')).some((x) => x === name || new RegExp(`\\s+as\\s+${name}$`).test(x))
+      || new RegExp(`^${name}\\b`).test(clause.trim());
+    if (!imports) continue;
+    const spec = m[2];
+    let target = null, suffix = null;
+    if (spec.startsWith('.')) target = posix.normalize(posix.join(posix.dirname(file), spec));
+    else { const a = /^(?:@|~|#)\/(.+)$/.exec(spec); if (a) suffix = a[1]; else return null; }
+    const hit = defs.filter((d) => {
+      const f = stripExt(d.file);
+      if (target !== null) return f === target || f === `${target}/index` || d.file.startsWith(`${target}/`);
+      return f === suffix || f.endsWith(`/${suffix}`) || f.endsWith(`/${suffix}/index`) || d.file.includes(`/${suffix}/`);
+    });
+    return hit.length === 1 ? hit : null;
+  }
+  return null;
+}
+
 /**
  * Harvest all components: definitions (with variants/props) + usages across the
  * repo. `codeFiles` are relative paths; returns { components, totalDefined }.
@@ -208,7 +239,13 @@ export function harvestComponents(root, codeFiles) {
     for (const [name, n] of tagCounts(src, /<([A-Z]\w*)(?=[\s/>]|$)/g)) {
       const defs = byName.get(name);
       if (!defs) continue;
-      for (const def of defs) {
+      // Two components of one name: the use belongs to the one the file
+      // imports. Crediting both made src/ui/Button and a copy in
+      // features/invoices each "used 12x" (8 and 4 in truth), so neither read
+      // as the canon (Ledgerly, 2026-09-24). Unresolved imports keep the old
+      // rule and credit every copy.
+      const owners = defs.length > 1 ? importedDef(src, file, name, defs) ?? defs : defs;
+      for (const def of owners) {
         if (def.file === file) continue; // internal render/recursion, not adoption
         def.usageCount += n;
         if (def.usedIn.length < 8) def.usedIn.push(file);

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

@@ -308,6 +308,7 @@ export function harvestTokens(root, styleFiles, codeFiles) {
         fontSizes = new Tally(), fontFamilies = new Tally(), shadows = new Tally();
   const twColors = new Tally(), twSpacing = new Tally(), twRadii = new Tally(), twTextSizes = new Tally();
   const twArbitrary = new Tally();
+  const themeFonts = new Tally(); // stacks a Tailwind @theme declares
   let inlineStyleCount = 0;
   const inlineStyleFiles = new Map();
   // !important is the cascade admitting defeat; counted per style file.
@@ -456,6 +457,21 @@ export function harvestTokens(root, styleFiles, codeFiles) {
       if (isTokenRef(v)) continue;
       fontFamilies.add(v, file);
     }
+    // Tailwind v4 declares the system's typefaces as --font-* rows in @theme,
+    // with no font-family line anywhere: Ledgerly's Inter lived only there, so
+    // one legacy "Helvetica Neue" read as the system face (2026-09-24). Kept
+    // apart from the declarations the report counts: a theme naming its faces
+    // is the system, not sprawl, and Ghost's theme carries a 21-font picker
+    // its users choose from. --font-weight-* is a weight scale, and the
+    // feature and variation settings are settings on a face.
+    for (const b of text.matchAll(/@theme[^{]*\{([\s\S]*?)\n\}/g)) {
+      for (const d of b[1].matchAll(/--font-([\w-]+)\s*:\s*([^;{}]+)[;}]/g)) {
+        if (d[1].includes('--') || /^(?:weight|feature|variation)(-|$)/.test(d[1])) continue;
+        const v = d[2].trim().replace(/\s+/g, ' ');
+        if (isTokenRef(v) || v === 'initial' || v === 'inherit') continue;
+        themeFonts.add(v, file);
+      }
+    }
     for (const m of text.matchAll(SHADOW_PROPS)) shadows.add(m[1].trim().replace(/\s+/g, ' '), file);
   };
 
@@ -750,6 +766,8 @@ export function harvestTokens(root, styleFiles, codeFiles) {
     radii: radii.toJSON(),
     fontSizes: fontSizes.toJSON(),
     fontFamilies: fontFamilies.toJSON(),
+    // faces a Tailwind v4 @theme declares: the system's own, not counted
+    themeFonts: themeFonts.toJSON(),
     shadows: shadows.toJSON(),
     tailwind: {
       colors: twColors.toJSON(),

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

@@ -197,6 +197,11 @@ const STYLING_DEPS = [
   { pkg: 'class-variance-authority', label: 'CVA' },
 ];
 
+// Plain names a team gives its own shared component folder, checked in order.
+// A bare ui/ at the root is left out: there it is usually the whole front
+// end (Azure-ipam), not a shelf of shared parts.
+const OWN_UI_DIRS = ['src/ui', 'app/ui', 'src/shared/ui', 'shared/ui', 'src/lib/ui', 'src/design-system'];
+
 /** Framework + design-system classification (1.0 logic, widened for monorepos). */
 export function profileRepo(root, files) {
   const pkg = readJSON(join(root, 'package.json')) || {};
@@ -251,21 +256,28 @@ export function profileRepo(root, files) {
   }
 
   const componentsJson = readJSON(join(root, 'components.json'));
-  const uiDir = ['src/components/ui', 'components/ui', 'app/components/ui'].find((d) => existsSync(join(root, d)));
-  const isShadcn = Boolean(componentsJson) || Boolean(uiDir);
+  const shadcnUiDir = ['src/components/ui', 'components/ui', 'app/components/ui'].find((d) => existsSync(join(root, d)));
+  const isShadcn = Boolean(componentsJson) || Boolean(shadcnUiDir);
+  // A team's own shared folder under a plainer name (src/ui, shared/ui) is the
+  // UI folder too, when it holds components: Ledgerly keeps its 13 in src/ui
+  // and read as having none (2026-09-24). It names where the components live;
+  // it never makes the repo a shadcn one or its folder installed stock.
+  const ownUiDir = shadcnUiDir ? null : OWN_UI_DIRS.find((d) => !existsSync(join(root, d, 'package.json'))
+    && files.code.filter((f) => f.startsWith(`${d}/`) && /\.(tsx|jsx)$/.test(f)).length >= 3);
+  const uiDir = shadcnUiDir ?? ownUiDir;
 
   // Catalogue filenames as shipped by `shadcn add --all` (61 as of 2026-09).
   // Only used to recognise a vendored folder, never to judge one.
   const SHADCN_CATALOGUE = CATALOGUE;
   let catalogueNames = 0;
-  if (uiDir) {
+  if (shadcnUiDir) {
     try {
-      for (const f of readdirSync(join(root, uiDir))) {
+      for (const f of readdirSync(join(root, shadcnUiDir))) {
         if (SHADCN_CATALOGUE.has(f.replace(/\.[cm]?[jt]sx?$/, ''))) catalogueNames += 1;
       }
     } catch { /* unreadable */ }
   }
-  const vendoredUi = Boolean(uiDir) && (Boolean(componentsJson) || catalogueNames >= 8);
+  const vendoredUi = Boolean(shadcnUiDir) && (Boolean(componentsJson) || catalogueNames >= 8);
 
   const knownLib = KNOWN_LIBRARIES.find((d) => deps[d.pkg]);
   const homegrown = files.code.filter((f) => /(^|\/)components\//.test(f) && !/\/components\/ui\//.test(f) && /\.(tsx|jsx)$/.test(f));

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

@@ -196,3 +196,24 @@ const HSL_TRIPLET =
   /^\s*(-?\d+(?:\.\d+)?)(?:deg)?\s+(\d+(?:\.\d+)?)%\s+(\d+(?:\.\d+)?)%(?:\s*\/\s*(\d+(?:\.\d+)?%?))?\s*$/;
 // bare RGB channels (dub: --bg-default: 255 255 255), see harvest/tokens.mjs
 const RGB_TRIPLET = /^\s*(\d{1,3})\s+(\d{1,3})\s+(\d{1,3})(?:\s*\/\s*\d+(?:\.\d+)?%?)?\s*$/;
+
+// Gamma-encoded sRGB (0-255) → linear, the inverse of `gamma` above.
+const linear = (c) => { c /= 255; return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4); };
+/**
+ * A colour in OKLab ({ L, a, b }), where a straight-line distance tracks what
+ * the eye sees; null when the value is not a literal colour. Used to find the
+ * theme colour nearest to a palette class, hue included.
+ */
+export function oklab(value) {
+  const c = parseColor(value);
+  if (!c) return null;
+  const r = linear(c.r), g = linear(c.g), b = linear(c.b);
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  return {
+    L: 0.2104542553 * l + 0.7936177850 * m - 0.0040720468 * s,
+    a: 1.9779984951 * l - 2.4285922050 * m + 0.4505937099 * s,
+    b: 0.0259040371 * l + 0.7827717662 * m - 0.8086757660 * s,
+  };
+}

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

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

@@ -18,6 +18,8 @@ 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';
 
 // What this engine measures — shipped with every result, clean or not.
 export const CHECKS = [
@@ -145,6 +147,7 @@ export function validateContent(content, k) {
     // 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);
@@ -155,12 +158,20 @@ export function validateContent(content, k) {
     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 example = /(^|:)(?:text|placeholder|caret|decoration)$/.test(util) ? pick(/ink|text|fg|foreground/) : /(^|:)bg$/.test(util) ? pick(/surface|bg|background|canvas/) : pick(/border|edge|line|ring/) ;
-      if (retuned.has(cls.replace(/^(?:[\w-]+:)*[a-z]+-/, '').replace(/\/\d+$/, ''))) continue;
+      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}). If no token fits, add one to the theme once, for example success, and use ${util}-success.`);
+        `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}.`}`);
     }
   }
 
@@ -306,6 +317,59 @@ 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

@@ -88,7 +88,9 @@ export function loadKnowledge(root) {
   const fontSizesSeen = new Map((tokens.fontSizes ?? []).map((f) => [f.value, f.count]));
   const shadowsSeen = new Map((tokens.shadows ?? []).map((s) => [s.value, s.count]));
   const faceCounts = new Map();
-  for (const f of tokens.fontFamilies ?? []) {
+  // a face the @theme declares is on-system, so a stylesheet using it is not
+  // "a new typeface" (tokens.themeFonts, harvest/tokens.mjs)
+  for (const f of [...(tokens.themeFonts ?? []), ...(tokens.fontFamilies ?? [])]) {
     const face = typefaceOf(f.value);
     if (face) faceCounts.set(face, (faceCounts.get(face) ?? 0) + f.count);
   }

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

@@ -85,7 +85,9 @@ export function getContext(k, { path = null } = {}) {
       ? `SPACING: this repo has no scale, just ${k.spacingSeen.size} values in circulation. Reuse one rather than inventing value number ${k.spacingSeen.size + 1}; do not treat them as a system.`
       : 'SPACING: nothing on record yet. Whatever you pick, the next agent will copy; pick something divisible by 4.');
 
-  const faces = distinctTypefaces(t.fontFamilies ?? []);
+  // the faces the theme declares come first: they are the system, whatever a
+  // stylesheet repeats more often
+  const faces = distinctTypefaces([...(t.themeFonts ?? []), ...(t.fontFamilies ?? [])]);
   if (faces.length) L.push(`TYPE: ${faces.slice(0, 3).join(', ')}. No new typefaces, no hand-declared font stacks.`);
   L.push('DISCIPLINE: no static style={{ }}, no !important, no new arbitrary values. Match the neighbouring component.');
   if (k.agentFiles.length === 0) L.push('NOTE: this repo has no agent rules file; these lines are the only guardrail. Suggest running npx roast-my-design-system@latest --apply.');
@@ -112,24 +114,66 @@ export function getContext(k, { path = null } = {}) {
 // ---------- roast_find_component ----------
 const camelWords = (name) => name.split(/(?=[A-Z])/).map((w) => w.toLowerCase()).filter(Boolean);
 
-export function findComponent(k, { query } = {}) {
-  if (typeof query !== 'string' || !query.trim()) return invalidInput('Give me a component name or intent, like "icon button" or "Modal".');
-  const q = query.trim();
-  const qWords = q.toLowerCase().split(/[\s_-]+/).filter(Boolean);
+// Other names people give the same piece of UI. Asked only when nothing in the
+// repo carries the word itself, and the answer says it went by purpose: an
+// agent asking for a "banner" should hear that <Alert> is this repo's one
+// (Ledgerly, 2026-09-24), never that none exists.
+const SYNONYMS = {
+  banner: ['alert', 'callout', 'notice'], notice: ['alert', 'callout', 'banner'], callout: ['alert', 'notice', 'banner'],
+  alert: ['banner', 'callout', 'notice'], flash: ['alert', 'toast'], notification: ['toast', 'alert'],
+  snackbar: ['toast'], toast: ['snackbar', 'notification'],
+  dropdown: ['select', 'combobox', 'menu'], picker: ['select', 'combobox'], combobox: ['select'], listbox: ['select'],
+  select: ['dropdown', 'combobox', 'picker'],
+  modal: ['dialog'], dialog: ['modal'], popup: ['popover', 'modal', 'dialog'], lightbox: ['modal', 'dialog'],
+  drawer: ['sheet'], sheet: ['drawer'], flyout: ['popover', 'drawer'],
+  tooltip: ['hint'], hint: ['tooltip'],
+  chip: ['badge', 'tag', 'pill'], tag: ['badge', 'chip', 'pill'], pill: ['badge', 'chip', 'tag'], badge: ['tag', 'chip', 'pill'],
+  spinner: ['loader', 'loading'], loader: ['spinner', 'loading'],
+  toggle: ['switch'], switch: ['toggle'],
+  textbox: ['input'], textfield: ['input'], field: ['input'],
+  tile: ['card'], panel: ['card'],
+  datatable: ['table'], grid: ['table'],
+  collapse: ['accordion', 'collapsible'], collapsible: ['accordion'], accordion: ['collapsible'],
+  pager: ['pagination'], btn: ['button'], cta: ['button'],
+};
 
+function scoreComponents(k, qWords, { every = false } = {}) {
   const scored = [];
   for (const c of k.components.filter((x) => !x.isPage)) {
     const words = camelWords(c.name);
     const nameLc = c.name.toLowerCase();
-    let s = 0;
+    let s = 0, missed = 0;
     if (nameLc === qWords.join('')) s += 100;
     for (const w of qWords) {
       // whole camel-word or word-prefix matches only: "board" must not match
       // inside "Onboarding", or every intent finds a wrong component
       if (words.includes(w)) s += 40;
       else if (w.length >= 3 && words.some((x) => x.startsWith(w))) s += 15;
+      else missed += 1;
+    }
+    if (s > 0 && !(every && missed)) scored.push({ c, s });
+  }
+  return scored;
+}
+
+export function findComponent(k, { query } = {}) {
+  if (typeof query !== 'string' || !query.trim()) return invalidInput('Give me a component name or intent, like "icon button" or "Modal".');
+  const q = query.trim();
+  const qWords = q.toLowerCase().split(/[\s_-]+/).filter(Boolean);
+
+  let scored = scoreComponents(k, qWords);
+  let bySynonym = null;
+  if (!scored.length) {
+    // one other name at a time, in the order listed: the first that names a
+    // real component answers, so "dropdown" finds Select before any Menu
+    for (const [i, w] of qWords.entries()) {
+      for (const alt of SYNONYMS[w] ?? []) {
+        // every word must match: a "date picker" is not any Select
+        const hit = scoreComponents(k, qWords.map((x, j) => (j === i ? alt : x)), { every: true });
+        if (hit.length) { scored = hit; bySynonym = alt; break; }
+      }
+      if (bySynonym) break;
     }
-    if (s > 0) scored.push({ c, s });
   }
   if (!scored.length) {
     return `No component matching "${q}" is defined in this repo.`;
@@ -140,6 +184,7 @@ export function findComponent(k, { query } = {}) {
     .sort((a, b) => b.usageCount - a.usageCount);
   const [top, second] = relevant;
   const out = [];
+  if (bySynonym) out.push(`Nothing here is named "${q}". Searched for "${bySynonym}" instead, another name for the same kind of component:`);
 
   // the tie rule: two live candidates close in usage = no clear canon, say so
   const tie = second && second.usageCount > 0 && top.usageCount / Math.max(second.usageCount, 1) < 1.5
@@ -154,12 +199,10 @@ export function findComponent(k, { query } = {}) {
     out.push(`Canonical: ${componentLine(top, k).trim()}`);
     if (top.usageExample) out.push(`Most common real usage, as in ${top.usageExample.file} (${top.usageExample.matches} of ${top.usageExample.total} usages): ${top.usageExample.snippet}`);
     const dupe = k.dupeByName.get(top.name);
-    if (dupe) {
-      const others = dupe.files.map((f) => (typeof f === 'string' ? f : f.file)).filter((f) => f !== top.file);
-      out.push(`Avoid: ${others.join(', ')} (same name, competing copies).`);
-    }
+    const others = dupe ? dupe.files.map((f) => (typeof f === 'string' ? f : f.file)).filter((f) => f !== top.file) : [];
+    if (others.length) out.push(`Avoid: ${others.join(', ')} (same name, competing copies).`);
     for (const c of relevant.slice(1, 3)) {
-      if (c.usageCount === 0) out.push(`Avoid <${c.name}> (${c.file}): defined but never imported.`);
+      if (c.usageCount === 0 && !others.includes(c.file)) out.push(`Avoid <${c.name}> (${c.file}): defined but never imported.`);
     }
   }
   return out.join('\n');

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

@@ -71,7 +71,9 @@ function readTheme(root, styleFiles) {
 // grey is only drift when the theme has a grey of its own to use instead
 // (hey.xyz names four brand pinks and no grey, 2026-09-16).
 const GREY_NAME_RE = /gr[ae]y|neutral|slate|zinc|stone|surface|background|foreground|(^|-)(bg|fg|text|border|line|divider|muted|ink|base|canvas|charcoal|contrast)(-|\d|$)/;
-function themeFamilies(root, styleFiles, names) {
+/** Each theme name's value, followed through var() to a literal (null when it
+ *  leads nowhere readable). Tailwind's own palette answers for --color-x. */
+function resolveValues(root, styleFiles, names) {
   const defs = new Map();
   for (const f of styleFiles ?? []) {
     for (const d of read(join(root, f)).matchAll(/(--[\w-]+)\s*:\s*([^;{}]+);/g)) if (!defs.has(d[1])) defs.set(d[1], d[2].trim());
@@ -84,9 +86,12 @@ function themeFamilies(root, styleFiles, names) {
     const next = defs.get(m[1]) ?? (pal ? TAILWIND_DEFAULTS[pal[1]] : undefined) ?? m[2];
     return next === undefined ? null : resolve(next.trim(), depth + 1);
   };
+  return new Map(names.map(([n, v]) => [n, resolve(v)]));
+}
+function themeFamilies(values) {
   const out = { grey: false, colour: false };
-  for (const [n, v] of names) {
-    const c = parseColor(resolve(v) ?? '');
+  for (const [n, v] of values) {
+    const c = parseColor(v ?? '');
     const grey = c ? Math.max(c.r, c.g, c.b) - Math.min(c.r, c.g, c.b) <= 12 : GREY_NAME_RE.test(n);
     out[grey ? 'grey' : 'colour'] = true;
   }
@@ -152,6 +157,7 @@ export default {
         : `used as classes ${uses} times: defined, but not adopted yet`,
       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 = {
       file: theme.file,
@@ -160,7 +166,10 @@ export default {
       // Tailwind names given the repo's own colours: on-theme, never drift
       retuned: theme.tuned,
       // which palette classes have a theme colour to stand in for them
-      families: themeFamilies(root, files.styles, theme.own.map((x) => [x, theme.names.get(x)])),
+      families: themeFamilies(values),
+      // name → literal colour, so a fix can point at the theme colour nearest
+      // to the palette class it replaces (bg-amber-50 → bg-warning-soft)
+      values: Object.fromEntries([...values].filter(([, v]) => v)),
       uses,
       usedIn,
       // a theme nobody uses is not the system yet: shown with receipts, not scored