roast-my-design-system 8.4.6 → 8.6.0

package/README.md

@@ -221,7 +221,7 @@ It writes a first draft anyway and runs `roast_validate` before saving:
 Second draft: `color: 'text.secondary'`, `p: 1.5`, the radius read from the theme. `roast_validate` again:
 
 ```
-No measured violations found. Checked: hardcoded colours vs the token set, near-identical colour twins, off-scale spacing, off-scale radii, font sizes and shadows, typefaces outside the system, arbitrary bracket values, static inline style blocks, !important, duplicate component definitions, colours and pixel sizes written onto kit components where the theme has a value.
+No measured violations found. Checked: hardcoded colours vs the token set, near-identical colour twins, off-scale spacing, off-scale radii, font sizes and shadows, typefaces outside the system, arbitrary bracket values, static inline style blocks, !important, duplicate component definitions, new colour tokens that twin an existing token, imports of a duplicate the canonical copy replaces, colours and pixel sizes written onto kit components where the theme has a value.
 ```
 
 Four calls, under 800 tokens in total, and the new component reads the theme instead of adding colour number 44. `roast_review` then checks the whole diff the same way before the agent says it is done.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "8.4.6",
+  "version": "8.6.0",
   "mcpName": "io.github.gregkozakiewicz/roast-my-design-system",
   "description": "Your AI can write the UI. This makes sure it writes your UI. A deterministic scanner scores your design system 0-100 against 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);
   };
 
@@ -624,12 +640,23 @@ export function harvestTokens(root, styleFiles, codeFiles) {
     for (const [f, n] of e.files) head.files.set(f, (head.files.get(f) ?? 0) + n);
   }
   const mergedColors = [...byCanon.values()].sort((a, b) => b.count - a.count);
+  // The token names that state each colour first (dark and density variants
+  // left out, as in the counts). Two differently named tokens holding the same
+  // colour are how drift gets promoted into the palette; the near-pair count
+  // reads these names (lib/nearpairs.mjs, lib/tokentwins.mjs).
+  const namesByCanon = new Map();
+  for (const d of baseDefs) {
+    const list = namesByCanon.get(d.canon) ?? [];
+    if (!list.includes(`--${d.name}`)) list.push(`--${d.name}`);
+    namesByCanon.set(d.canon, list);
+  }
   const colorList = mergedColors.map((e) => ({
     value: e.value,
     count: e.count,
     files: [...e.files.entries()].sort((a, b) => b[1] - a[1]).slice(0, 5).map(([file, count]) => ({ file, count })),
     isToken: e.spellings.some((v) => tokenDefined.has(v)),
     ...(e.spellings.length > 1 ? { spellings: e.spellings } : {}),
+    ...(namesByCanon.has(canonical(e.value)) ? { names: namesByCanon.get(canonical(e.value)).slice(0, 6) } : {}),
   }));
 
   // Worst offenders: files carrying the most stray styling (hardcoded colours
@@ -750,6 +777,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/avoidedimports.mjs

@@ -0,0 +1,93 @@
+/**
+ * An import of the copy roast says to avoid. roast_find_component answers
+ * "Canonical: src/ui/Button.tsx … Avoid: src/features/invoices/ButtonV2.tsx",
+ * but on the Ledgerly demo (2026-09-24) an agent asked to match a spec colour
+ * imported the avoided copy anyway, because its hard-coded blue matched, and
+ * nothing in the live checks said a word: the colour lives inside the copy,
+ * not in the file under review. This names the canonical copy instead.
+ *
+ * Only a clear canon is named: the same tie rule roast_find_component uses
+ * (the most used copy must lead the next by half again). Two copies in equal
+ * use have no wrong pick, and saying otherwise would be inventing one.
+ */
+import { posix } from 'node:path';
+
+const CODE_EXT_RE = /\.(?:tsx|ts|jsx|js|mjs|cjs|vue|svelte)$/;
+const stem = (f) => f.replace(CODE_EXT_RE, '').replace(/\/index$/, '');
+
+/** Each name a text imports, with where from: [{ name, spec, index }]. */
+export function importsOf(text) {
+  const out = [];
+  for (const m of String(text ?? '').matchAll(/(?:^|\n)\s*import\s+(?:type\s+)?([^'";]*?)\s+from\s+['"]([^'"]+)['"]/g)) {
+    const [, clause, spec] = m;
+    const index = m.index + m[0].indexOf('import');
+    const named = /\{([^}]*)\}/.exec(clause);
+    for (const part of named ? named[1].split(',') : []) {
+      const name = part.trim().replace(/^type\s+/, '').split(/\s+as\s+/)[0].trim();
+      if (name) out.push({ name, spec, index });
+    }
+    // the default import takes the copy's own name
+    const def = clause.replace(/\{[^}]*\}/, '').replace(/\*\s+as\s+\w+/, '').replace(/,/g, ' ').trim();
+    if (/^[A-Z]\w*$/.test(def)) out.push({ name: def, spec, index, isDefault: true });
+  }
+  return out;
+}
+
+/** The file among `candidates` an import specifier points at, or null. */
+export function resolveSpec(spec, file, candidates) {
+  if (spec.startsWith('.') && file) {
+    const target = posix.normalize(posix.join(posix.dirname(file), spec));
+    return candidates.find((c) => stem(c) === target || stem(c) === stem(target)) ?? null;
+  }
+  // an alias (@/features/invoices/ButtonV2) or no file to resolve against:
+  // the path's tail must name the copy, folder included
+  const tail = stem(spec.replace(/^(?:\.{1,2}\/)+/, '').replace(/^[@~#]\//, ''));
+  if (!tail.includes('/') && !spec.startsWith('.')) return null; // a package, not a file
+  return candidates.find((c) => stem(c) === tail || stem(c).endsWith(`/${tail}`)) ?? null;
+}
+
+/**
+ * The clear canon among the copies of a name, or null on a tie.
+ * copies: [{ file, usageCount }]
+ */
+export function canonicalCopy(copies) {
+  const [top, second] = [...copies].sort((a, b) => b.usageCount - a.usageCount);
+  if (!top || !top.usageCount) return null;
+  if (second && second.usageCount > 0 && top.usageCount / second.usageCount < 1.5) return null;
+  return top;
+}
+
+/**
+ * Findings for imports of a non-canonical duplicate that the change ADDS.
+ * @param dupes  Map<name, { copies: [{ file, usageCount }], strays?: Map<file, [colour]> }>
+ * @param before the file before the change: null for a new file, undefined
+ *               when unknown (every import is then judged)
+ * @returns [{ rule: 'avoided-copy', index, name, from, canonical, message, fix }]
+ */
+export function avoidedImportFindings(text, { file = null, before, dupes } = {}) {
+  if (!dupes?.size) return [];
+  const key = (i) => {
+    const d = dupes.get(i.name);
+    const hit = d ? resolveSpec(i.spec, file, d.copies.map((c) => c.file)) : null;
+    return hit ? `${i.name}|${hit}` : null;
+  };
+  const had = new Set(before == null ? [] : importsOf(before).map(key).filter(Boolean));
+  const out = [], seen = new Set();
+  for (const i of importsOf(text)) {
+    const d = dupes.get(i.name);
+    if (!d) continue;
+    const from = resolveSpec(i.spec, file, d.copies.map((c) => c.file));
+    if (!from || from === file || had.has(`${i.name}|${from}`) || seen.has(`${i.name}|${from}`)) continue;
+    seen.add(`${i.name}|${from}`);
+    const canon = canonicalCopy(d.copies);
+    if (!canon || canon.file === from) continue;
+    const mine = d.copies.find((c) => c.file === from);
+    const strays = d.strays?.get(from) ?? [];
+    out.push({
+      rule: 'avoided-copy', index: i.index, name: i.name, from, canonical: canon.file,
+      message: `Imports <${i.name}> from ${from}, one of ${d.copies.length} competing copies. The canonical one is ${canon.file} (used ${canon.usageCount}x; this copy ${mine?.usageCount ?? 0}x).${strays.length ? ` This copy hard-codes ${strays.slice(0, 3).join(', ')}${strays.length > 3 ? ` and ${strays.length - 3} more` : ''}.` : ''}`,
+      fix: `Import <${i.name}> from ${canon.file}. If the design needs something it lacks, add it there, not to the copy.`,
+    });
+  }
+  return out;
+}

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/guard-api.mjs

@@ -48,6 +48,14 @@ export { PALETTE_CLASS_RE, blankComments };
 // index of each in the text; null when the file is not a kit file, { exempt }
 // when it is not judged. Only meaningful when system.profile.kit is set.
 export { kitPaintFindings };
+// Twin tokens and avoided copies (8.6.0). tokenTwinFindings(text, { before,
+// others, tailwind }) words the colour tokens a stylesheet ADDS that twin one
+// the repo already has (tokenDefsOf reads a stylesheet's tokens, light and
+// dark, for `others`). avoidedImportFindings(text, { file, before, dupes })
+// words a new import of a duplicate where a clear canonical copy exists.
+// Same words as roast_validate, roast_review and --check.
+export { tokenTwinFindings, tokenDefsOf } from './tokentwins.mjs';
+export { avoidedImportFindings, canonicalCopy } from './avoidedimports.mjs';
 
 // Radius, font size, shadow and typeface: the patterns, so both checkers agree
 // on what a declaration is and what counts as a disciplined value.

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

@@ -1,11 +1,26 @@
 /**
  * Near-identical colour pairs (#f5f5f5 next to #f6f6f6): copy-paste, not
  * decisions. Hex-parseable colours only; a pair is "near" when every channel
- * sits within 8 of its twin and alpha matches. Two TOKENS sitting close are a
- * designed ramp (every good grey scale has near neighbours) and are skipped;
- * drift needs at least one hardcoded stray. Shared by diagnose and rules.
+ * sits within 8 of its twin and alpha matches. Two TOKENS sitting close are
+ * usually a designed ramp (every good grey scale has near neighbours) and are
+ * skipped; drift needs at least one hardcoded stray. The exception (8.6.0):
+ * two tokens named for different roles (overdue-soft next to warning-soft) are
+ * one colour under two names. Without it, a stray "fixed" by minting a twin
+ * token left the count and the score went up (Ledgerly, 2026-09-24).
+ * Shared by diagnose and rules.
  */
 import { parseColor } from './color.mjs';
+import { canonical } from './color.mjs';
+import { isRoleName, familyOf, tokenTwinColours } from './tokentwins.mjs';
+
+// Two token colours whose names are roles in different families: a twin.
+// Colours harvested before 8.6.0 carry no names and never pair this way.
+// Same test as the live check (lib/tokentwins.mjs), so both say the same.
+function twinTokens(x, y) {
+  const a = (x.names ?? []).filter(isRoleName), b = (y.names ?? []).filter(isRoleName);
+  return a.some((n) => b.some((m) => familyOf(n) !== familyOf(m)))
+    && tokenTwinColours(canonical(x.value), canonical(y.value));
+}
 
 // Kept under its historical name (the MCP engine imports it): since 5.10.0 it
 // parses every literal colour space, not just hex, so an hsl or oklch
@@ -23,13 +38,14 @@ export function nearColorPairs(colorList) {
     for (let j = i + 1; j < hexes.length; j++) {
       const a = hexes[i].rgb, b = hexes[j].rgb;
       if (a.a !== b.a) continue;
-      if (hexes[i].isToken && hexes[j].isToken) continue;
+      const tokens = hexes[i].isToken && hexes[j].isToken;
+      if (tokens && !twinTokens(hexes[i], hexes[j])) continue;
       // Entries are distinct strings by construction, so d = 0 means the same
       // colour written in two notations (hsl token, rgb stray): the strongest
       // twin there is, not a non-event. Rounded so the report never prints
       // 7.9199999.
       const d = Math.round(Math.max(Math.abs(a.r - b.r), Math.abs(a.g - b.g), Math.abs(a.b - b.b)) * 10) / 10;
-      if (d <= 8) pairs.push({ a: hexes[i], b: hexes[j], d });
+      if (d <= 8) pairs.push({ a: hexes[i], b: hexes[j], d, ...(tokens ? { tokens } : {}) });
     }
   }
   // One twin per stray. A stray sitting inside a dense token ramp is within 8
@@ -38,15 +54,18 @@ export function nearColorPairs(colorList) {
   // finding is "this stray has a token twin", and the fix is one redirect,
   // so each stray keeps only its closest twin (a stray-stray pair survives
   // when it is the closest for either side).
-  const best = new Map();
+  // Twin tokens are thinned the same way among themselves: each token keeps
+  // its closest twin.
+  const best = new Map(), bestTwin = new Map();
   for (const p of pairs) {
     for (const side of ['a', 'b']) {
       const c = p[side];
-      if (c.isToken) continue;
-      const cur = best.get(c.value);
-      if (!cur || p.d < cur.d) best.set(c.value, p);
+      const into = p.tokens ? bestTwin : best;
+      if (c.isToken && !p.tokens) continue;
+      const cur = into.get(c.value);
+      if (!cur || p.d < cur.d) into.set(c.value, p);
     }
   }
-  const kept = [...new Set(best.values())];
+  const kept = [...new Set([...best.values(), ...bestTwin.values()])];
   return kept.sort((x, y) => (y.a.count + y.b.count) - (x.a.count + x.b.count));
 }

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

@@ -0,0 +1,184 @@
+/**
+ * Twin tokens: a new colour token whose value is a near-identical copy of a
+ * token the system already has (--color-overdue-soft: #fff4e5 next to
+ * --color-warning-soft: #fdf5e6). Found on the Ledgerly demo (2026-09-24): an
+ * agent asked to "match the spec exactly" minted six such tokens, the strays
+ * in an old component then equalled a token and stopped counting, and the
+ * score read the drift as progress. The live checks judge a stylesheet with
+ * this file; the report counts the same pairs through lib/nearpairs.mjs.
+ *
+ * Near means every channel within 8, as everywhere else in the engine, and,
+ * because both sides are deliberate tokens, closer than the eye can tell
+ * (TWIN_OKLAB). A shared dark value counts too, because two tokens that agree in
+ * the dark are one colour even when their light values drifted a little further
+ * apart (up to DARK_TWIN_STEPS).
+ *
+ * Only named roles take part. A ramp stop (gray-100, blue-500) sits close to
+ * its neighbours by design, a restated palette (slate-50 beside gray-50) is
+ * Tailwind's, and the rows shadcn's theming docs define share values on
+ * purpose (card and popover are both white). Two names in one family
+ * (brand, brand-strong) are a designed pair, not twins.
+ */
+import { canonical, oklab } from './color.mjs';
+import { KNOWN_ROWS } from '../profiles/shadcn-data.mjs';
+
+export const TWIN_STEPS = 8;
+// Two tokens are deliberate, so a pair of them must also be closer than the
+// eye can tell (OKLab distance 0.01; a just-noticeable difference is about
+// 0.02). The channel rule alone paired Ledgerly's pale red and pale amber
+// surfaces (6 steps, 0.019) and its canvas with its muted surface (4 steps,
+// 0.012), each a designed neighbour; the six tokens the agent minted sat at
+// 0.003 to 0.009.
+export const TWIN_OKLAB = 0.01;
+// A shared dark value makes two tokens one colour when their light values are
+// close enough that roast_find_token would already say "use the token" (24
+// steps). Past that, two roles that meet in the dark are a design decision.
+export const DARK_TWIN_STEPS = 24;
+
+const bare = (name) => name.replace(/^--/, '').replace(/^(?:colou?rs?|clr)-/, '');
+/** A token named for a role (warning-soft), not a ramp stop or a kit row. */
+export function isRoleName(name) {
+  const b = bare(name);
+  return !KNOWN_ROWS.has(b) && !/(^|-)\d+$/.test(b);
+}
+/** The first word of the role: overdue-soft and overdue-title are one family. */
+export const familyOf = (name) => bare(name).split('-')[0];
+
+const rgbOf = (canon) => {
+  if (!canon) return null;
+  const [r, g, b, a] = canon.split(',').map(Number);
+  return { r, g, b, a };
+};
+const okOf = (canon) => {
+  const c = rgbOf(canon);
+  return c ? oklab(`rgb(${c.r} ${c.g} ${c.b})`) : null;
+};
+/** Straight-line OKLab distance between two canonical colours, or null. */
+export function okDistance(x, y) {
+  const a = okOf(x), b = okOf(y);
+  return a && b ? Math.hypot(a.L - b.L, a.a - b.a, a.b - b.b) : null;
+}
+/** Two token colours close enough to be one colour under two names. */
+export function tokenTwinColours(x, y) {
+  const d = channelSteps(x, y);
+  return d !== null && d <= TWIN_STEPS && (okDistance(x, y) ?? 1) <= TWIN_OKLAB;
+}
+
+/** Largest channel difference, or null when the alphas differ. */
+export function channelSteps(x, y) {
+  const a = rgbOf(x), b = rgbOf(y);
+  if (!a || !b || a.a !== b.a) return null;
+  return Math.max(Math.abs(a.r - b.r), Math.abs(a.g - b.g), Math.abs(a.b - b.b));
+}
+
+const DARK_RE = /dark/i;
+
+/**
+ * Every colour custom property a stylesheet defines, by name: the base value
+ * (the first statement outside a dark block) and the dark value (the first
+ * statement inside one: .dark, [data-theme="dark"], a prefers-color-scheme
+ * query). Values are kept as written and as a canonical colour; a name whose
+ * value is not a literal colour (an alias to var(--x)) is left out.
+ * @returns Map<name, { value, canon, index, darkValue?, darkCanon? }>
+ */
+export function tokenDefsOf(raw) {
+  // comments blanked, offsets kept: a retired token in a comment is not a token
+  const text = String(raw ?? '').replace(/\/\*[\s\S]*?\*\//g, (m) => ' '.repeat(m.length));
+  // the blocks, each with the selector that opened it
+  const blocks = [], stack = [];
+  let from = 0;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '{') {
+      stack.push({ start: i, selector: text.slice(from, i).trim().split('\n').pop().trim() });
+      from = i + 1;
+    } else if (ch === '}') {
+      const b = stack.pop();
+      if (b) blocks.push({ ...b, end: i });
+      from = i + 1;
+    } else if (ch === ';') from = i + 1;
+  }
+  const inDark = (i) => blocks.some((b) => b.start < i && i < b.end && DARK_RE.test(b.selector));
+  const defs = new Map();
+  for (const m of text.matchAll(/(--[\w-]+)\s*:\s*([^;{}]+)[;}]/g)) {
+    const [, name, rawValue] = m;
+    const value = rawValue.trim();
+    const canon = canonical(value);
+    if (!canon) continue;
+    const e = defs.get(name) ?? {};
+    if (inDark(m.index)) {
+      if (!e.darkValue) Object.assign(e, { darkValue: value, darkCanon: canon });
+    } else if (!e.value) Object.assign(e, { value, canon, index: m.index });
+    defs.set(name, e);
+  }
+  // a name stated only inside a dark block has no base to compare
+  for (const [name, e] of defs) if (!e.canon) defs.delete(name);
+  return defs;
+}
+
+/**
+ * The existing token a token is a twin of, or null. `pool` is
+ * [{ name, canon, value, darkCanon?, darkValue?, file? }].
+ */
+export function twinOf(name, def, pool) {
+  if (!isRoleName(name)) return null;
+  const fam = familyOf(name);
+  let best = null;
+  for (const e of pool) {
+    if (e.name === name || !isRoleName(e.name) || familyOf(e.name) === fam) continue;
+    const d = channelSteps(def.canon, e.canon);
+    const near = tokenTwinColours(def.canon, e.canon);
+    const darkSame = !!def.darkCanon && def.darkCanon === e.darkCanon;
+    if (!near && !(darkSame && d !== null && d <= DARK_TWIN_STEPS)) continue;
+    // the closest light value wins; a shared dark value breaks a tie
+    const rank = (near ? 0 : 1000) + (d ?? 999) - (darkSame ? 0.5 : 0);
+    if (!best || rank < best.rank) best = { ...e, d, near, darkSame, rank };
+  }
+  return best;
+}
+
+// the utility a role name suits, for the class the fix names
+const utilFor = (name) => (/border|edge|line|ring|divider|outline/.test(name) ? 'border'
+  : /text|title|ink|fg|foreground|label/.test(name) ? 'text' : 'bg');
+
+/**
+ * Worded findings for the tokens a stylesheet ADDS that twin an existing one.
+ * @param text     the stylesheet as it stands now
+ * @param before   the same file before the change (the last commit), null for
+ *                 a new file, undefined when unknown: every token in it is
+ *                 then judged, against the rest of the repo and each other
+ * @param others   tokens other files define: [{ name, canon, value, darkCanon?, darkValue?, file }]
+ * @param tailwind true when --color-* names are Tailwind theme classes
+ * @returns [{ rule: 'twin-token', index, name, twin, message, fix }]
+ */
+export function tokenTwinFindings(text, { before, others = [], tailwind = false } = {}) {
+  const now = tokenDefsOf(text);
+  if (!now.size) return [];
+  const prev = before === undefined ? null : tokenDefsOf(before ?? '');
+  const isNew = (name) => !prev || !prev.has(name);
+  // what already exists: other files, and this file's own tokens that were
+  // there before the change (at today's values)
+  const pool = [...others.filter((o) => !now.has(o.name))];
+  for (const [name, e] of now) if (!isNew(name)) pool.push({ name, ...e });
+  const out = [];
+  for (const [name, def] of [...now].sort((a, b) => a[1].index - b[1].index)) {
+    if (!isNew(name)) continue;
+    const twin = twinOf(name, def, pool);
+    // judged in file order: a later new token may twin an earlier new one
+    pool.push({ name, ...def, added: true });
+    if (!twin) continue;
+    const cls = tailwind && /^--colou?r-/.test(twin.name) ? `${utilFor(bare(name))}-${bare(twin.name)}` : null;
+    const where = twin.file ? ` in ${twin.file}` : '';
+    // "existing" only when it is: without a before, nothing in this file is known to be old
+    const whose = twin.added ? (prev ? 'the new' : 'the token') : prev || twin.file ? 'the existing' : 'the token';
+    const lead = twin.near
+      ? `${name} (${def.value}) is a twin of ${whose} ${twin.name} (${twin.value})${where}: ${twin.d === 0 ? 'the same colour' : `${twin.d} channel step${twin.d === 1 ? '' : 's'} apart`}${twin.darkSame ? `, and the same dark value (${def.darkValue})` : ''}.`
+      : `${name} has the same dark value as ${whose} ${twin.name}${where} (${def.darkValue}), and its light value is only ${twin.d} channel steps away (${def.value} against ${twin.value}).`;
+    out.push({
+      rule: 'twin-token', index: def.index, name, twin: twin.name,
+      message: `${lead} Two names for one colour: the next agent cannot tell which is right.`,
+      fix: `Use ${twin.name}${cls ? ` (as a class: ${cls})` : ''} and remove ${name}. Do not add a token that duplicates an existing one.`,
+    });
+  }
+  return out;
+}

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.6.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,10 @@ 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 { tokenTwinFindings } from '../lib/tokentwins.mjs';
+import { avoidedImportFindings } from '../lib/avoidedimports.mjs';
 
 // What this engine measures — shipped with every result, clean or not.
 export const CHECKS = [
@@ -30,6 +34,8 @@ export const CHECKS = [
   'static inline style blocks',
   '!important',
   'duplicate component definitions',
+  'new colour tokens that twin an existing token',
+  'imports of a duplicate the canonical copy replaces',
 ];
 // What a kit or a Tailwind theme adds to the list, so a clean result on an
 // MUI repo says the kit check ran.
@@ -75,13 +81,16 @@ function nearestToken(value, k) {
 
 /**
  * Validate one piece of content against the repo's knowledge.
- * @param content { text, file? } — file name decides css-vs-code mode and
- *   lets the duplicate check excuse a component's own existing file
+ * @param content { text, file?, before? } — file name decides css-vs-code
+ *   mode and lets the duplicate check excuse a component's own existing file;
+ *   before is the same file at the last commit (null: a new file; left out:
+ *   unknown), so a token or an import the change ADDS can be told from one
+ *   that was already there
  * @returns { findings: [{ rule, severity, line, message, fix? }], checked,
  *   exempt? } — exempt is a sentence saying why the file was not judged
  */
 export function validateContent(content, k) {
-  const { text, file = null } = content;
+  const { text, file = null, before } = content;
   // Some files cannot be on-system by their nature. Judging them is how a
   // checker earns its reputation for crying wolf, and a checker people
   // distrust gets switched off. Say nothing, and say why nothing was said.
@@ -145,6 +154,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 +165,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}.`}`);
     }
   }
 
@@ -272,6 +290,19 @@ export function validateContent(content, k) {
     }
   }
 
+  // ---------- a new token that twins an existing one ----------
+  // Minting a second name for a colour the system already has is drift
+  // promoted into the token set: the strays that matched it stop counting and
+  // the palette reads as tidier than it is (Ledgerly, 2026-09-24).
+  if (css) {
+    const twins = tokenTwinFindings(text, {
+      before,
+      others: (k.tokenDefs ?? []).filter((d) => d.file !== file),
+      tailwind: !!k.tailwind || /@theme\b/.test(text),
+    });
+    for (const f of twins) add(f.rule, 'violation', f.index, f.message, f.fix);
+  }
+
   // ---------- discipline ----------
   for (const b of got.inlineBlocks) {
     add('inline-style', 'violation', b.index,
@@ -303,9 +334,69 @@ export function validateContent(content, k) {
     }
   }
 
+  // ---------- an import of the copy the canon replaces ----------
+  if (!css) {
+    for (const f of avoidedImportFindings(text, { file, before, dupes: k.dupeCopies })) {
+      add(f.rule, 'violation', f.index, f.message, f.fix);
+    }
+  }
+
   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

@@ -12,9 +12,9 @@
  */
 import { statSync } from 'node:fs';
 import { join } from 'node:path';
-import { walkRepo, profileRepo } from '../harvest/walk.mjs';
+import { walkRepo, profileRepo, readSource } from '../harvest/walk.mjs';
 import { harvestComponents } from '../harvest/components.mjs';
-import { harvestTokens } from '../harvest/tokens.mjs';
+import { harvestTokens, extractStyling } from '../harvest/tokens.mjs';
 import { findDuplicates } from '../harvest/duplicates.mjs';
 import { harvestContext } from '../harvest/context.mjs';
 import { loadExclusions } from '../lib/exclusions.mjs';
@@ -24,6 +24,8 @@ import { typefaceOf } from '../lib/typefaces.mjs';
 import { hexRgb } from '../lib/nearpairs.mjs';
 import { decideProfile, profileOf } from '../profiles/index.mjs';
 import { KITS } from '../profiles/kit-common.mjs';
+import { tokenDefsOf } from '../lib/tokentwins.mjs';
+import { canonicalCopy } from '../lib/avoidedimports.mjs';
 
 const MAX_DEPTH = 14; // same ruler as the harvest CLI
 
@@ -88,7 +90,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);
   }
@@ -117,6 +121,31 @@ export function loadKnowledge(root) {
 
   const neverImported = neverImportedComponents(components, profile.uiDir);
 
+  // The copies of each duplicated name with their usage, and the colours each
+  // copy hard-codes: what the avoided-import check names (lib/avoidedimports).
+  const dupeCopies = new Map();
+  for (const d of hardDupes) {
+    const paths = d.files.map((f) => (typeof f === 'string' ? f : f.file));
+    const copies = paths.map((file) => ({ file, usageCount: (byName.get(d.name) ?? []).find((c) => c.file === file)?.usageCount ?? 0 }));
+    const canon = canonicalCopy(copies);
+    const strays = new Map();
+    for (const file of paths) {
+      if (file === canon?.file) continue;
+      const text = readSource(join(root, file));
+      if (text) strays.set(file, [...new Set(extractStyling(text).colors.map((c) => c.value))]);
+    }
+    dupeCopies.set(d.name, { copies, strays });
+  }
+
+  // Every colour token each stylesheet defines, light and dark, so a new one
+  // can be compared with the ones already there (lib/tokentwins).
+  const tokenDefs = [];
+  for (const file of files.styles) {
+    const text = readSource(join(root, file));
+    if (!text || !text.includes('--')) continue;
+    for (const [name, e] of tokenDefsOf(text)) tokenDefs.push({ name, file, ...e });
+  }
+
   return {
     root,
     scannedAt: new Date().toISOString(),
@@ -142,6 +171,8 @@ export function loadKnowledge(root) {
     byName,
     canonical,
     dupeByName,
+    dupeCopies,
+    tokenDefs,
     neverImported,
     // stock, not debt: see profiles/index.mjs
     vendoredUi: P.vendoredUi,

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

@@ -78,7 +78,7 @@ const PROMPTS = [
   {
     name: 'roast-build-ui',
     description: 'Build UI in this repo the way the repo already does it',
-    text: 'Before implementing any UI in this repository: call roast_get_context (pass the folder you will work in), check roast_find_component for anything you are about to create, and roast_find_token for any raw colour or size value. Build. Then call roast_validate on what you wrote and fix every finding, and finish with roast_review. Do not invent components, colours or spacing values this repository does not already have.',
+    text: 'Before implementing any UI in this repository: call roast_get_context (pass the folder you will work in), check roast_find_component for anything you are about to create, and roast_find_token for any raw colour or size value. Build. Then call roast_validate on what you wrote and fix every finding, and finish with roast_review. Do not invent components, colours or spacing values this repository does not already have, and do not add a token that duplicates an existing one; reuse it.',
   },
   {
     name: 'roast-review-ui',

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

@@ -50,7 +50,7 @@ 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.${strays ? ` (${strays} hardcoded strays already exist; do not add more.)` : ''}`);
+    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.)` : ''}`);
   } else if (t.colors.length) {
     L.push(`TOKENS: none defined. ${t.colors.length} distinct colours already in play; reuse one, never invent another.`);
   }
@@ -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');
@@ -230,12 +273,35 @@ function toPxLocal(len) {
   return m[2] === 'px' ? parseFloat(m[1]) : parseFloat(m[1]) * 16;
 }
 
+// ---------- the file before the change ----------
+// The last commit's copy of a file, so a check can tell a token or an import
+// the change ADDS from one that was already there: null when the file is new
+// (git has a HEAD and no copy of it), undefined when there is nothing to ask
+// (not a repository, no commits yet). gitPath is relative to the git root.
+function headVersion(gitRoot, gitPath) {
+  try {
+    return execFileSync('git', ['show', `HEAD:${gitPath}`], { cwd: gitRoot, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 16 * 1024 * 1024 });
+  } catch {
+    try {
+      execFileSync('git', ['rev-parse', '--verify', 'HEAD'], { cwd: gitRoot, stdio: 'ignore' });
+      return null;
+    } catch { return undefined; }
+  }
+}
+function beforeOf(k, file) {
+  if (!file) return undefined;
+  try {
+    const gitRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: k.root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    return headVersion(gitRoot, relative(realpathSync.native(gitRoot), join(realpathSync.native(k.root), file)).split('\\').join('/'));
+  } catch { return undefined; }
+}
+
 // ---------- roast_validate ----------
 export function validate(k, { code, file = null } = {}) {
   if (typeof code !== 'string' || !code.trim()) return invalidInput('Send the code you are about to save (and ideally its file path).');
   if (file != null && typeof file !== 'string') return invalidInput('file is optional, but when sent it must be a repo-relative path as a string.');
   if (code.length > MAX_VALIDATE_CHARS) return invalidInput(`That is ${Math.round(code.length / 1000)}k characters; send the part you changed (up to ${MAX_VALIDATE_CHARS / 1000}k).`);
-  const { findings, exempt } = validateContent({ text: code, file }, k);
+  const { findings, exempt } = validateContent({ text: code, file, before: beforeOf(k, file) }, k);
   if (exempt) return `Not judged: ${file} is exempt because ${exempt}. Nothing here was checked.`;
   if (!findings.length) return cleanResultText(k);
   const L = [`${findings.length} finding${findings.length === 1 ? '' : 's'}:`];
@@ -280,7 +346,7 @@ export function reviewData(k) {
     let text;
     try { text = readFileSync(join(gitRoot, f), 'utf8'); } catch { continue; }
     // knowledge paths are scanned-root-relative; git paths are toplevel-relative
-    const { findings, exempt } = validateContent({ text, file: relative(realRoot, join(gitRoot, f)) }, k);
+    const { findings, exempt } = validateContent({ text, file: relative(realRoot, join(gitRoot, f)), before: headVersion(gitRoot, f) }, k);
     if (exempt) { exemptCount++; continue; }
     if (findings.length) { perFile.push({ f, findings }); total += findings.length; }
   }

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