roast-my-design-system 3.5.0 → 3.6.0

package/README.md

@@ -24,11 +24,11 @@ Your AI agent (Claude, Cursor, Copilot) builds UI by imitating what's already in
 
 The full report for vercel/ai-chatbot, top to bottom:
 
-![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, three-yardstick tiles, palette forensics, spacing receipts, typography, offenders, duplicates, and the where-to-start close](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-full-dark.png?v=3.5.0)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, three-yardstick tiles, palette forensics, spacing receipts, typography, offenders, duplicates, and the where-to-start close](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-full-dark.png?v=3.6.0)
 
 The same report in light mode (one file, built-in toggle):
 
-![The diagnosis report in light mode](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-light-hero.png?v=3.5.0)
+![The diagnosis report in light mode](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-light-hero.png?v=3.6.0)
 
 ## What makes the numbers trustworthy
 
@@ -127,4 +127,4 @@ Yes, the median repo is already a mess. That's the point.
 
 MIT
 
-Built and designed by <a href="https://gregkozakiewicz.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark-dark.png?v=3.5.0"><img src="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark.png?v=3.5.0" height="15" alt="GK mark"></picture> Greg Kozakiewicz</a>.
+Built and designed by <a href="https://gregkozakiewicz.com"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark-dark.png?v=3.6.0"><img src="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark.png?v=3.6.0" height="15" alt="GK mark"></picture> Greg Kozakiewicz</a>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "Roast your design system with real data. A deterministic, zero-dependency scanner that counts every colour, grey, spacing value, typeface, duplicated component, inline style and arbitrary Tailwind value in your repo, scores it 0-100 against Ideal Design System norms and a 30-repo benchmark, generates a shareable HTML diagnosis, and with --rules writes the agent rules file (CLAUDE.md, .cursor/rules) that stops the mess coming back.",
   "keywords": [
     "design-system",

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

@@ -12,6 +12,7 @@ import { resolve, basename, join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { distinctTypefaces } from '../lib/typefaces.mjs';
 import { rulesMarkdown } from '../rules/build.mjs';
+import { nearColorPairs } from '../lib/nearpairs.mjs';
 
 // The benchmark (Ideal-2026 norms + scanned-repo stats) ships next to the
 // code so the page works offline; degrade gracefully when absent.
@@ -34,7 +35,7 @@ const GK_MASK = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqa
 const GK_MARK = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAIAAAD8GO2jAAAACXBIWXMAAAAAAAAAAQCEeRdzAAACPklEQVR4nOVWTYh5URR/PlJYEKV8LKwkZalsmI2dZmMnK8pKmaZ87JSanexEkayUhSxsZyfJNBQ7UYqVhSShfM+v/6mXmtU81+p/Frfze+/d3++ce88993Hcf2cikehZ1GazWafTPUVDLBZjLBQKnU6HMTVvcrl8Op3ebrdsNgsokUiYUVP4Pp/v9s96vd79cwZGK95sNkkgGAwC2u12lhrY3u12C/b1ei2TyV5eXjabjV6vZ6BBa51MJin8arUKWKlU4H99fSkUCo5JUQ2HQxJwuVzIYLVawcdIVSs8CQoNpMQ+Go0Aw+EwwXw+D+h2u4Vr0LRSqUSMqVQKsN1uE3Q4HEql8ng8BgIBTnDhqlSqxWIBuvP5bDAYLBbL5XIBHAwGeBuJRODvdjun0/nnPOjraDRK8TYaDcBMJkMwFosBfn9/E0wkEn9OgjYgnU6fTidQwAGcTCbw9/u9VqvFUYB/vV5RskajkRNcTiaTKR6PI9j5fE7xlstlPM/lcgTr9ToneJ/5oOB4PB70O8Tb7/f9fv9sNqPkXl9fhQsQ9f1ktVqNvUVCxA6ZRxsf5pMAxnsuVBSOwvv7+6Phk0PsBNn0OOLC9haLReqdvBL/wUNKNPnt7Q0LjeVutVqhUEij0TwU9W8BVA4JUEUul8tarcZGhpbIarWiSeA0HQ4Hkvn4+GB56VMvov6DA+z1eplR89btdsE+Ho9tNhv3jOv+8/MTFz06M3ypVMqMnTfcwPhn4djG/tue+Mf4RGom9gMt6lAx16huIwAAAABJRU5ErkJggg==';
 
 // Shown in the report footer; keep in step with plugin.json when releasing.
-const VERSION = '3.5.0';
+const VERSION = '3.6.0';
 
 // Two shipped skins, same layout: 'dark' (navy glass, mint accent) and
 // 'light' (lilac wash, white glass, violet accent). --theme picks one.
@@ -151,6 +152,22 @@ const greyStrays = greys.filter((c) => !c.isToken).length;
 const arbitrary = h.tokens.tailwind?.arbitrary ?? [];
 const arbitraryCount = arbitrary.reduce((sum, a) => sum + a.count, 0);
 
+// !important declarations: the cascade admitting defeat.
+const important = h.tokens.important ?? { count: 0, files: [] };
+
+const nearPairs = nearColorPairs(colors);
+
+// Components defined but never imported — scoped to the design-system
+// directory, where "nobody imports this" is meaningful. File-local
+// subcomponents elsewhere legitimately never get imported by name.
+const dsDirRe = h.profile?.uiDir
+  ? new RegExp(`^${h.profile.uiDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/`)
+  : /(^|\/)(packages\/ui|design-system|ui-kit)\//;
+const usedFiles = new Set(reusable.filter((c) => c.usageCount > 0).map((c) => c.file));
+const neverImported = reusable.filter((c) => !c.usageCount && dsDirRe.test(c.file)
+  && !/(^|\/)icons?\//.test(c.file)          // glyph sets are deliberately complete
+  && !usedFiles.has(c.file));                 // compound API: an adopted file's sub-exports are surface, not dead
+
 // Benchmark helpers: for a metric value, where does this repo sit among the
 // scanned fleet? ("more colours than 90% of scanned repos")
 function percentile(metric, value) {
@@ -204,6 +221,8 @@ if (effGreys > 13 * 1.25) candidates.push({ ratio: effGreys / 13, text: tokenLed
   ? `${greyStrays} hardcoded greys outside the token set`
   : `${greys.length} shades of grey doing the job of 13` });
 if (spacingTotal > 15) candidates.push({ ratio: spacingTotal / 12, text: `${spacingTotal} off-scale spacing values where a dozen would do` });
+if (nearPairs.length >= 3) candidates.push({ ratio: 1 + nearPairs.length / 6, text: `${nearPairs.length} colour pairs are nearly identical (${nearPairs[0].a.value} next to ${nearPairs[0].b.value}), copy-paste, not decisions` });
+if (important.count >= 10) candidates.push({ ratio: 1 + important.count / 30, text: `${n(important.count)} !important declarations, the cascade admitting defeat` });
 if (iconCollisions.length >= 5) candidates.push({ ratio: 1 + iconCollisions.length / 8, text: `two icon sets collide on ${iconCollisions.length} names` });
 if (hardDupes.length > 0) candidates.push({ ratio: 1 + hardDupes.length / 5, text: `${hardDupes.length} component${hardDupes.length > 1 ? 's' : ''} implemented more than once` });
 if (inline.count > 20) candidates.push({ ratio: inline.count / 20, text: `${n(inline.count)} inline style blocks bypassing every system` });
@@ -361,6 +380,9 @@ function paletteSection() {
     </div>
     <div class="usage-bar">${cells}${restCell}</div>
     ${ramp}
+    ${nearPairs.length ? `
+    <div class="receipts">${eyebrow(`${nearPairs.length} nearly identical pair${nearPairs.length === 1 ? '' : 's'} · copy-paste, not decisions`)}
+    <div class="chips-row">${nearPairs.slice(0, 8).map((pr) => `<span class="vchip" title="every channel within ${pr.d} of its twin"><i class="ndot" style="background:${esc(pr.a.value)}"></i>${esc(pr.a.value)} ×${pr.a.count} <b class="nsim">≈</b> <i class="ndot" style="background:${esc(pr.b.value)}"></i>${esc(pr.b.value)} ×${pr.b.count}</span>`).join('')}${nearPairs.length > 8 ? `<span class="vchip dim">+${nearPairs.length - 8} more</span>` : ''}</div></div>` : ''}
   </div>
 </section>`;
 }
@@ -457,20 +479,24 @@ function offendersSection() {
 }
 
 function inlineSection() {
-  if (inline.count < 5) return '';
+  if (inline.count < 5 && important.count < 5) return '';
   const max = Math.max(...inline.files.slice(0, 6).map((f) => f.count), 1);
-  return `<div class="glass pad half">
-    ${sectionHead(`${n(inline.count)} inline style blocks`, 'styling no system can see')}
-    <div class="fam-rows">${inline.files.slice(0, 6).map((f) => `
+  const importantRow = important.count ? `
+    <div class="receipts">${eyebrow(`${n(important.count)} !important declaration${important.count === 1 ? '' : 's'} · the cascade admitting defeat`)}
+    <div class="chips-row">${important.files.map((f) => `<span class="vchip bad" title="${esc(f.file)}">${esc(basename(f.file))} ×${f.count}</span>`).join('')}</div></div>` : '';
+  const blocks = inline.count >= 5 ? `<div class="fam-rows">${inline.files.slice(0, 6).map((f) => `
       <div class="mini-card col">
         <div class="mc-row">${fileLink(f.file)}<span class="mc-count">×${f.count}</span></div>
         <div class="mc-track"><div class="mc-bar" style="width:${Math.round((f.count / max) * 100)}%"></div></div>
-      </div>`).join('')}</div></div>`;
+      </div>`).join('')}</div>` : '';
+  return `<div class="glass pad half">
+    ${sectionHead(inline.count >= 5 ? `${n(inline.count)} inline style blocks` : `${n(important.count)} !important declarations`, 'styling no system can see')}
+    ${blocks}${importantRow}</div>`;
 }
 
 function componentsSection() {
   const top = reusable.filter((c) => c.usageCount > 0).slice(0, 10);
-  if (!top.length) return '';
+  if (!top.length && neverImported.length < 2) return '';
   const rows = top.map((c) => `
     <tr><td class="mono strong">&lt;${esc(c.name)}&gt;</td>
     <td><span class="pill pill-mint">${c.usageCount}×</span></td>
@@ -478,7 +504,11 @@ function componentsSection() {
     <td>${c.propsHint?.named?.length ? c.propsHint.named.slice(0, 5).map((p) => `<span class="chip chip-xs">${esc(p)}</span>`).join(' ') : '<span class="dim">none</span>'}</td></tr>`).join('');
   return `<section class="glass pad">
     ${sectionHead('What you actually use', `${n(reusable.length)} components defined · top by adoption · the real system, buried in here`)}
-    <div class="tbl-wrap"><table><thead><tr><th>component</th><th>used</th><th>defined in</th><th>props</th></tr></thead><tbody>${rows}</tbody></table></div></section>`;
+    ${top.length ? `<div class="tbl-wrap"><table><thead><tr><th>component</th><th>used</th><th>defined in</th><th>props</th></tr></thead><tbody>${rows}</tbody></table></div>` : ''}
+    ${neverImported.length >= 2 ? `
+    <div class="receipts">${eyebrow(`${n(neverImported.length)} components defined but never imported · candidates for deletion, or the system nobody found`)}
+    <div class="chips-row">${neverImported.slice(0, 8).map((c) => `<span class="vchip" title="${esc(c.file)}">&lt;${esc(c.name)}&gt;</span>`).join('')}${neverImported.length > 8 ? `<span class="vchip dim">+${neverImported.length - 8} more</span>` : ''}</div>
+    <p class="sub" style="margin-top:8px">Routers, dynamic imports and barrel files can hide real usage, so treat this as a shortlist to check, not a demolition order.</p>` : ''}</section>`;
 }
 
 // "Where to start" — at most three moves, every one derived from this repo's
@@ -830,17 +860,24 @@ const html = `<!doctype html>
   footer .brand { color:var(--accent); font-weight:700; text-decoration:none; }
   footer .brand:hover { text-decoration:underline; }
   footer .creds { display:flex; gap:16px; font:700 9.5px/1.6 var(--sans); letter-spacing:.16em; text-transform:uppercase; color:var(--dim2); }
+  .ndot { display:inline-block; width:9px; height:9px; border-radius:3px; margin-right:4px; vertical-align:-1px; box-shadow:inset 0 0 0 1px var(--cell-ring); }
+  .nsim { color:var(--dim2); font-weight:400; padding:0 2px; }
   .gift-sec { margin-top:16px; }
   .gift-stage { position:relative; display:grid; place-items:center; min-height:120px; }
   .gift-stage.open { min-height:0; }
   .gift[hidden] { display:none; }
-  .gift { background:none; border:0; cursor:pointer; display:grid; place-items:center; gap:9px; padding:14px; color:var(--dim);
+  .gift { position:relative; background:none; border:0; cursor:pointer; display:grid; place-items:center; gap:9px; padding:14px; color:var(--dim);
     transition:transform .25s ease, opacity .25s ease, filter .25s ease; }
   .gift svg { width:72px; height:72px; }
   .gift .ribbon { stroke:var(--accent); }
   .gift:hover { transform:translateY(-3px) scale(1.04); color:var(--text); }
   .gift.gone { transform:scale(.5); opacity:0; filter:blur(5px); }
   .gift-hint { font:700 10px/1 var(--sans); letter-spacing:.18em; text-transform:uppercase; }
+  .gift::after { content:'your agent rules file, generated from this scan'; position:absolute; top:100%; left:50%;
+    transform:translateX(-50%); white-space:nowrap; font:400 11.5px/1 var(--sans); letter-spacing:0; text-transform:none;
+    color:var(--dim2); opacity:0; transition:opacity .3s ease .6s; pointer-events:none; }
+  .gift:hover::after { opacity:1; }
+  .gift.gone::after { opacity:0; transition:none; }
   .gift-pop { position:absolute; inset:0; pointer-events:none; }
   .gift-pop i { position:absolute; left:50%; top:42%; width:7px; height:10px; border-radius:2px; opacity:0;
     animation:gpop .85s cubic-bezier(.16,.8,.32,1) forwards; }

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

@@ -129,6 +129,8 @@ export function harvestTokens(root, styleFiles, codeFiles) {
   const twArbitrary = new Tally();
   let inlineStyleCount = 0;
   const inlineStyleFiles = new Map();
+  // !important is the cascade admitting defeat; counted per style file.
+  const importantFiles = new Map();
 
   // Colours that appear in a CSS custom-property DEFINITION (--grey-100: #f5f5f5)
   // are deliberate tokens; everything else is a hardcoded stray. The diagnosis
@@ -137,6 +139,8 @@ export function harvestTokens(root, styleFiles, codeFiles) {
   const tokenDefsPerFile = new Map();
 
   const scanCssText = (text, file) => {
+    const imp = (text.match(/!\s*important/gi) ?? []).length;
+    if (imp) importantFiles.set(file, (importantFiles.get(file) ?? 0) + imp);
     for (const m of text.matchAll(/--[\w-]+\s*:\s*([^;{}]+)[;}]/g)) {
       tokenDefsPerFile.set(file, (tokenDefsPerFile.get(file) ?? 0) + 1);
       for (const c of m[1].matchAll(HEX_RE)) tokenDefined.add(normalizeHex(c[0]));
@@ -303,6 +307,11 @@ export function harvestTokens(root, styleFiles, codeFiles) {
       textSizes: twTextSizes.toJSON(),
       arbitrary: twArbitrary.toJSON(),
     },
+    important: {
+      count: [...importantFiles.values()].reduce((a, b) => a + b, 0),
+      files: [...importantFiles.entries()].sort((a, b) => b[1] - a[1]).slice(0, 6)
+        .map(([file, count]) => ({ file, count })),
+    },
     inlineStyles: {
       count: inlineStyleCount,
       files: [...inlineStyleFiles.entries()].sort((a, b) => b[1] - a[1]).slice(0, 10)

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

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+export function hexRgb(v) {
+  const m = /^#([0-9a-f]{3,8})$/i.exec(v);
+  if (!m) return null;
+  let x = m[1];
+  if (x.length === 3 || x.length === 4) x = [...x].map((c) => c + c).join('');
+  if (x.length !== 6 && x.length !== 8) return null;
+  return { r: parseInt(x.slice(0, 2), 16), g: parseInt(x.slice(2, 4), 16), b: parseInt(x.slice(4, 6), 16),
+    a: x.length === 8 ? x.slice(6, 8) : 'ff' };
+}
+
+export function nearColorPairs(colorList) {
+  const hexes = colorList.map((c) => ({ ...c, rgb: hexRgb(c.value) })).filter((c) => c.rgb);
+  const pairs = [];
+  for (let i = 0; i < hexes.length; i++) {
+    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 d = Math.max(Math.abs(a.r - b.r), Math.abs(a.g - b.g), Math.abs(a.b - b.b));
+      if (d > 0 && d <= 8) pairs.push({ a: hexes[i], b: hexes[j], d });
+    }
+  }
+  return pairs.sort((x, y) => (y.a.count + y.b.count) - (x.a.count + x.b.count));
+}

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

@@ -5,6 +5,7 @@
  * with a receipt from the scanned repo.
  */
 import { distinctTypefaces } from '../lib/typefaces.mjs';
+import { nearColorPairs } from './../lib/nearpairs.mjs';
 
 export function rulesMarkdown(h) {
 const repoName = h.profile?.name ?? 'this repo';
@@ -36,6 +37,8 @@ const repoName = h.profile?.name ?? 'this repo';
     } else if ((t.colors ?? []).length) {
       rule(`There is no token file yet. Until one exists, reuse the colours already in the codebase instead of introducing new ones (${t.colors.length} distinct colours are already in play).`);
     }
+    const near = nearColorPairs(t.colors ?? []);
+    if (near.length) rule(`Never eyeball a colour from memory: the scan found ${near.length} nearly identical pair${near.length === 1 ? '' : 's'} (like ${near[0].a.value} next to ${near[0].b.value}). Look the exact value up, or better, use its token.`);
     const ds = h.profile?.designSystem;
     if (ds?.kind && !['none', 'custom'].includes(ds.kind) && ds.confidence !== 'low') {
       rule(`This repo uses ${ds.name ?? ds.kind}${h.profile.uiDir ? `; its components live in \`${h.profile.uiDir}\`` : ''}. Prefer extending it over building parallel pieces.`);
@@ -84,7 +87,20 @@ const repoName = h.profile?.name ?? 'this repo';
     if (icons.length) rule(`Two icon sets collide on ${icons.length} name${icons.length === 1 ? '' : 's'}. Before adding any icon, check which set the surrounding file already imports and stay with it.`);
   }
   
-  // ---------- spacing ----------
+  // ---------- never-imported components ----------
+const dsDirRe = h.profile?.uiDir
+  ? new RegExp(`^${h.profile.uiDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/`)
+  : /(^|\/)(packages\/ui|design-system|ui-kit)\//;
+const usedFiles = new Set(reusable.filter((c) => c.usageCount > 0).map((c) => c.file));
+const neverImported = reusable.filter((c) => !c.usageCount && dsDirRe.test(c.file)
+  && !/(^|\/)icons?\//.test(c.file)          // glyph sets are deliberately complete
+  && !usedFiles.has(c.file));                 // compound API: an adopted file's sub-exports are surface, not dead
+if (neverImported.length >= 3) {
+  section('Components nobody imports');
+  rule(`${neverImported.length} components are defined but never imported (${neverImported.slice(0, 3).map((c) => `\`<${c.name}>\``).join(', ')}…). Before writing any new component, check this list first; adopt one or flag it for deletion instead of adding another.`);
+}
+
+// ---------- spacing ----------
   const arbitrary = t.tailwind?.arbitrary ?? [];
   const arbCount = arbitrary.reduce((s, a) => s + a.count, 0);
   const offScale = (t.spacing ?? []).length;
@@ -106,6 +122,7 @@ const repoName = h.profile?.name ?? 'this repo';
   section('Styling discipline');
   rule(`Never write ${reusable.length ? '`style={{ ... }}`' : 'inline `style="..."` attributes'} for static values; styling belongs to classes and tokens where the system can see it.`);
   if ((t.inlineStyles?.count ?? 0) > 0) lines.push(`  (${t.inlineStyles.count} static inline block${t.inlineStyles.count === 1 ? '' : 's'} already exist; do not add to them.)`);
+  if ((t.important?.count ?? 0) >= 3) rule(`Never write !important; the scan found ${t.important.count} declaration${t.important.count === 1 ? '' : 's'} already. When a style does not apply, fix the selector or the source of the conflict instead of shouting over it.`);
   rule('Before styling anything new, look at a neighbouring component and match how it does it. Consistency with the repo beats personal preference.');
   
   lines.push('');