roast-my-design-system 3.4.0 → 3.5.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.4.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.5.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.4.0)
+![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)
 
 ## What makes the numbers trustworthy
 
@@ -96,8 +96,9 @@ You get the roast in chat plus `design-system-roast.html` at your repo root: a s
 - a **light/dark theme toggle** in one file
 - the usage-weighted palette bar, the grey ramp, the off-scale spacing receipts, the duplicate-component receipts with clickable file paths, and the worst-offenders ledger
 - a **Where to start** close: up to three moves derived from your repo's own numbers, each with a file-path receipt
+- a **present** 🎁 below it: you sat through the roast, so `design-system-rules.md` is wrapped inside the report itself. Unwrap, then copy or download the agent rules generated from your scan.
 
-After the roast, the skill offers `design-system-rules.md`: the agent-rules file generated from the same scan, ready for your CLAUDE.md, `.cursor/rules` or AGENTS.md.
+After the roast, the skill also offers to write `design-system-rules.md` to disk and merge it into your CLAUDE.md, `.cursor/rules` or AGENTS.md.
 
 ## Live examples
 
@@ -126,4 +127,4 @@ Yes, the median repo is already a mess. That's the point.
 
 MIT
 
-Built and designed by [Greg Kozakiewicz](https://gregkozakiewicz.com).
+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>.

package/bin/roast.mjs

@@ -103,6 +103,9 @@ if (asJson) {
 if (wantRules && !asJson) {
   console.log(`\n  design-system-rules.md is ready: paste it into CLAUDE.md or .cursor/rules
   so your AI agent stops repeating this repo's mistakes.`);
+} else if (!asJson) {
+  console.log(`\n  there is a present wrapped inside the report: your agent rules file,
+  generated from this scan. Or run with --rules to write it straight to disk.`);
 }
 
 say(`\nWant the fixes, not just the roast? The free Claude Code skill runs this same

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "3.4.0",
+  "version": "3.5.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

@@ -11,6 +11,7 @@ import { readFileSync, writeFileSync, existsSync } from 'node:fs';
 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';
 
 // The benchmark (Ideal-2026 norms + scanned-repo stats) ships next to the
 // code so the page works offline; degrade gracefully when absent.
@@ -33,7 +34,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.4.0';
+const VERSION = '3.5.0';
 
 // Two shipped skins, same layout: 'dark' (navy glass, mint accent) and
 // 'light' (lilac wash, white glass, violet accent). --theme picks one.
@@ -483,6 +484,38 @@ function componentsSection() {
 // "Where to start" — at most three moves, every one derived from this repo's
 // own numbers with a receipt. Deliberately shallow: a starting push, not a
 // remediation plan.
+// The present. The report ends the diagnosis arc with a gift: the agent
+// rules file generated from this same scan, wrapped behind one click.
+// Embedded so the report stays a single self-contained shareable file.
+function giftSection() {
+  const { text: rulesText, ruleCount } = rulesMarkdown(h);
+  return `<section class="glass pad gift-sec">
+    ${sectionHead('You sat through the roast', 'so you get a present.')}
+    <div class="gift-stage">
+      <button class="gift" id="gift" aria-label="Unwrap your generated agent rules file">
+        <svg viewBox="0 0 64 64" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+          <rect x="10" y="26" width="44" height="30" rx="4"/>
+          <rect x="6" y="17" width="52" height="9" rx="3"/>
+          <path class="ribbon" d="M32 26 v30"/>
+          <path class="ribbon" d="M32 17 c-9 1 -13 -8 -7 -11 c5 -2 8 4 7 11 c-1 -7 2 -13 7 -11 c6 3 2 12 -7 11z"/>
+        </svg>
+        <span class="gift-hint">unwrap</span>
+      </button>
+      <div class="gift-pop" id="gift-pop" aria-hidden="true"></div>
+      <div class="gift-reveal" id="gift-reveal" hidden>
+        <div class="gift-head"><span class="mono strong">design-system-rules.md</span>
+          <span class="gift-count">${ruleCount} rules generated from this scan, every one with a receipt</span></div>
+        <pre class="gift-md" id="gift-md">${esc(rulesText)}</pre>
+        <div class="gift-actions">
+          <button class="gbtn" id="gift-copy">Copy the rules</button>
+          <button class="gbtn ghost" id="gift-dl">Download the file</button>
+        </div>
+        <div class="gift-sub">Paste into CLAUDE.md, .cursor/rules or AGENTS.md. From then on your AI agent follows your system instead of guessing at it.</div>
+      </div>
+    </div>
+  </section>`;
+}
+
 function whereToStartSection() {
   const c = [];
   if (agentFiles.length === 0) c.push({ score: 60, title: 'Write the agent rules file',
@@ -797,6 +830,36 @@ 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); }
+  .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);
+    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-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; }
+  @keyframes gpop { 0% { opacity:1; transform:translate(0,0) rotate(0); } 100% { opacity:0; transform:translate(var(--dx),var(--dy)) rotate(var(--rot)); } }
+  .gift-reveal { width:100%; }
+  .gift-reveal.in { animation:greveal .5s ease both; }
+  @keyframes greveal { from { opacity:0; transform:translateY(8px) scale(.985); } to { opacity:1; transform:none; } }
+  .gift-head { display:flex; align-items:baseline; gap:12px; flex-wrap:wrap; margin-bottom:10px; }
+  .gift-count { color:var(--dim2); font-size:12.5px; }
+  .gift-md { max-height:340px; overflow:auto; background:var(--chip-bg); border:1px solid var(--line-soft); border-radius:12px;
+    padding:16px 18px; font:12px/1.7 var(--mono); color:var(--dim); white-space:pre-wrap; }
+  .gift-actions { display:flex; gap:10px; margin-top:12px; flex-wrap:wrap; }
+  .gbtn { font:700 12.5px/1 var(--sans); padding:11px 16px; border-radius:10px; border:1px solid var(--accent);
+    background:var(--accent); color:var(--card-solid); cursor:pointer; }
+  .gbtn:hover { filter:brightness(1.08); }
+  .gbtn.ghost { background:transparent; color:var(--accent); }
+  .gift-sub { color:var(--dim2); font-size:12.5px; margin-top:10px; }
+  @media print { .gift, .gift-pop { display:none !important; } .gift-reveal[hidden] { display:block !important; } }
+  @media (prefers-reduced-motion: reduce) { .gift, .gift-reveal.in, .gift-pop i { transition:none !important; animation:none !important; } }
   .author { color:var(--accent); font-weight:700; text-decoration:none; }
   .gk-mark { display:inline-block; width:15px; height:15px; margin-right:5px; vertical-align:-3px;
     background:currentColor; -webkit-mask:url(${GK_MASK}) center/contain no-repeat; mask:url(${GK_MASK}) center/contain no-repeat; }
@@ -829,6 +892,8 @@ const html = `<!doctype html>
 
 ${whereToStartSection()}
 
+${giftSection()}
+
 <div class="stats">${bigStats.map((s) => statTile(s)).join('')}</div>
 
 ${agentSection()}
@@ -851,6 +916,47 @@ ${componentsSection()}
   </div>
   <span class="creds"><span>Non-destructive scan</span><span>Read-only</span><span>Paths are real</span></span>
 </footer>
+<script>
+(function(){
+  var gift=document.getElementById('gift'); if(!gift) return;
+  var reveal=document.getElementById('gift-reveal'), pop=document.getElementById('gift-pop');
+  var reduce=window.matchMedia && matchMedia('(prefers-reduced-motion: reduce)').matches;
+  gift.addEventListener('click', function(){
+    if(!reduce && pop){
+      var colors=['var(--accent)','var(--coral)','var(--amber)','var(--text)'];
+      for(var i=0;i<26;i++){
+        var f=document.createElement('i');
+        var a=Math.random()*Math.PI*2, v=46+Math.random()*84;
+        f.style.setProperty('--dx',(Math.cos(a)*v)+'px');
+        f.style.setProperty('--dy',(Math.sin(a)*v-56)+'px');
+        f.style.setProperty('--rot',(Math.random()*540-270)+'deg');
+        f.style.background=colors[i%4];
+        f.style.animationDelay=(Math.random()*80)+'ms';
+        pop.appendChild(f);
+      }
+      setTimeout(function(){ pop.innerHTML=''; },1000);
+    }
+    gift.classList.add('gone');
+    setTimeout(function(){ gift.hidden=true; gift.parentNode.classList.add('open'); reveal.hidden=false; reveal.classList.add('in'); }, reduce?0:240);
+  },{once:true});
+  var copyBtn=document.getElementById('gift-copy');
+  function rulesText(){ return document.getElementById('gift-md').textContent; }
+  copyBtn.addEventListener('click', function(){
+    var done=function(){ copyBtn.textContent='Copied'; setTimeout(function(){ copyBtn.textContent='Copy the rules'; },1600); };
+    var fallback=function(){ var ta=document.createElement('textarea'); ta.value=rulesText(); document.body.appendChild(ta);
+      ta.select(); try{ document.execCommand('copy'); }catch(e){} ta.remove(); };
+    if(navigator.clipboard && navigator.clipboard.writeText){ navigator.clipboard.writeText(rulesText()).then(done, function(){ fallback(); done(); }); }
+    else { fallback(); done(); }
+  });
+  document.getElementById('gift-dl').addEventListener('click', function(){
+    var a=document.createElement('a');
+    a.href=URL.createObjectURL(new Blob([rulesText()],{type:'text/markdown'}));
+    a.download='design-system-rules.md';
+    document.body.appendChild(a); a.click();
+    setTimeout(function(){ URL.revokeObjectURL(a.href); a.remove(); },400);
+  });
+})();
+</script>
 </div></body></html>`;
 
 writeFileSync(outPath, html);

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

@@ -0,0 +1,118 @@
+/**
+ * Rules builder — shared by the rules CLI and the diagnose page (which embeds
+ * the generated markdown behind the gift reveal). Input: a harvest object.
+ * Output: { text, ruleCount } — paste-ready agent-rules markdown, every rule
+ * with a receipt from the scanned repo.
+ */
+import { distinctTypefaces } from '../lib/typefaces.mjs';
+
+export function rulesMarkdown(h) {
+const repoName = h.profile?.name ?? 'this repo';
+  const t = h.tokens ?? {};
+  const reusable = (h.components ?? []).filter((c) => !c.isPage);
+  const scanDate = (h.harvestedAt ?? '').slice(0, 10);
+  
+  const lines = [];
+  const rule = (s) => lines.push(`- ${s}`);
+  const section = (title) => lines.push('', `### ${title}`, '');
+  
+  lines.push('## Design system rules');
+  lines.push('');
+  lines.push(`<!-- Generated by roast-my-design-system from a scan of ${repoName} on ${scanDate}.`);
+  lines.push('     Paste into CLAUDE.md, .cursor/rules or AGENTS.md. Regenerate after big refactors:');
+  lines.push('     npx roast-my-design-system --rules -->');
+  lines.push('');
+  lines.push('Follow these rules when writing or editing UI in this repo. Every rule below was derived from a scan of this codebase, with real paths and usage counts.');
+  
+  // ---------- tokens ----------
+  const strays = (t.colors ?? []).filter((c) => !c.isToken);
+  const tokenCount = (t.colors ?? []).filter((c) => c.isToken).length;
+  if (t.tokenFile || (t.colors ?? []).length) {
+    section('Colours and tokens');
+    if (t.tokenFile) {
+      rule(`Design tokens live in \`${t.tokenFile}\`. Reach for an existing token before inventing any value.`);
+      if (tokenCount && strays.length) rule(`Never hardcode colour values in components. The palette already has ${tokenCount} tokens; the scan still found ${strays.length} hardcoded colours sitting next to them. Do not add more.`);
+      else rule('Never hardcode colour values in components; add a token first if one is genuinely missing.');
+    } 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 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.`);
+    }
+  }
+  
+  // ---------- canonical components ----------
+  // Skip names that shadow framework components (their usage counts absorb the
+  // framework's) and names defined in more than one file (ambiguous, and the
+  // duplicates section already handles them).
+  const FRAMEWORK_NAMES = new Set(['Link', 'Image', 'Head', 'Script', 'Form']);
+  const nameCounts = new Map();
+  for (const c of reusable) nameCounts.set(c.name, (nameCounts.get(c.name) ?? 0) + 1);
+  const top = reusable
+    .filter((c) => c.usageCount > 0 && !FRAMEWORK_NAMES.has(c.name) && nameCounts.get(c.name) === 1)
+    .sort((a, b) => b.usageCount - a.usageCount).slice(0, 8);
+  if (top.length) {
+    section('Canonical components');
+    rule('Use these existing components instead of writing new ones:');
+    for (const c of top) {
+      const props = c.propsHint?.named?.length ? ` · props: ${c.propsHint.named.slice(0, 4).join(', ')}` : '';
+      lines.push(`  - \`<${c.name}>\` from \`${c.file}\` (used ${c.usageCount}x${props})`);
+    }
+  }
+  
+  // ---------- duplicates to avoid ----------
+  const dupes = h.duplicates?.exactDuplicates ?? [];
+  const icons = h.duplicates?.iconCollisions ?? [];
+  if (dupes.length || icons.length) {
+    section('Known duplicates: do not make it worse');
+    // No per-file usage data here, so rank by how shared the location looks;
+    // when nothing stands out, do not guess a canonical.
+    const sharedScore = (f) => (f.includes('packages/') ? 4 : 0) + (/\/ui\//.test(f) ? 2 : 0) + (f.includes('components/') ? 1 : 0) - (/\bapp\//.test(f) ? 2 : 0) - (f.includes('/icons/') ? 4 : 0);
+    for (const d of dupes.slice(0, 6)) {
+      const files = d.files.map((f) => (typeof f === 'string' ? f : f.file));
+      const ranked = [...files].sort((a, b) => sharedScore(b) - sharedScore(a));
+      const clear = sharedScore(ranked[0]) > sharedScore(ranked[1]);
+      if (d.wrapped) {
+        rule(`\`<${d.name}>\` is defined twice and one wraps the other${clear ? `. Import \`${ranked[0]}\`` : ''}; do not create a third.`);
+      } else if (clear) {
+        rule(`\`<${d.name}>\` exists in ${files.length} places. Treat \`${ranked[0]}\` as canonical; do not import the other ${files.length === 2 ? 'copy' : 'copies'}, and never create another.`);
+      } else {
+        rule(`\`<${d.name}>\` exists in ${files.length} places (${files.slice(0, 2).map((f) => `\`${f}\``).join(', ')}). Match whichever the surrounding code already imports, and never create another.`);
+      }
+    }
+    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 ----------
+  const arbitrary = t.tailwind?.arbitrary ?? [];
+  const arbCount = arbitrary.reduce((s, a) => s + a.count, 0);
+  const offScale = (t.spacing ?? []).length;
+  if (t.tailwind?.spacing?.length || offScale || arbCount) {
+    section('Spacing and sizing');
+    if (t.tailwind?.spacing?.length) rule('Stay on the Tailwind spacing scale. If a gap looks wrong on a scale step, flag it instead of nudging by a pixel.');
+    if (arbCount) rule(`No new arbitrary bracket values (\`p-[13px]\`, \`text-[10px]\`). The scan found ${arbCount} already. If a value repeats, it is a decision: name it as a token instead of writing the bracket again.`);
+    if (offScale) rule(`Avoid new one-off CSS spacing values; ${offScale} off-scale value${offScale === 1 ? ' is' : 's are'} already in play.`);
+  }
+  
+  // ---------- typography ----------
+  const faces = distinctTypefaces(t.fontFamilies ?? []);
+  if (faces.length) {
+    section('Typography');
+    rule(`The repo uses ${faces.length} typeface${faces.length === 1 ? '' : 's'}: ${faces.slice(0, 4).join(', ')}. Do not introduce another, and do not re-declare font stacks by hand; use the existing setup.`);
+  }
+  
+  // ---------- styling discipline ----------
+  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.)`);
+  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('');
+  lines.push('---');
+  lines.push('*Generated by [roast-my-design-system](https://github.com/pencilrebel/roast-my-design-system). Rescan after refactors to keep these rules honest.*');
+  lines.push('');
+  const text = lines.join('\n');
+  const ruleCount = lines.filter((l) => l.startsWith('- ')).length;
+  return { text, ruleCount };
+}

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

@@ -4,12 +4,13 @@
  * agent-rules section (CLAUDE.md, .cursor/rules, AGENTS.md) generated from
  * what the scan actually measured. The report diagnoses the past; this file
  * protects the future — every rule carries a receipt from this repo.
+ * (The report also embeds this same markdown behind the gift reveal.)
  *
  *   node src/rules/index.mjs <harvest.json> [--out design-system-rules.md]
  */
 import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { distinctTypefaces } from '../lib/typefaces.mjs';
+import { rulesMarkdown } from './build.mjs';
 
 function arg(name, fallback) {
   const i = process.argv.indexOf(`--${name}`);
@@ -20,113 +21,7 @@ if (!inPath) { console.error('Usage: node src/rules/index.mjs <harvest.json> [--
 const outPath = resolve(arg('out', 'design-system-rules.md'));
 
 const h = JSON.parse(readFileSync(inPath, 'utf8'));
-const repoName = h.profile?.name ?? 'this repo';
-const t = h.tokens ?? {};
-const reusable = (h.components ?? []).filter((c) => !c.isPage);
-const scanDate = (h.harvestedAt ?? '').slice(0, 10);
-
-const lines = [];
-const rule = (s) => lines.push(`- ${s}`);
-const section = (title) => lines.push('', `### ${title}`, '');
-
-lines.push('## Design system rules');
-lines.push('');
-lines.push(`<!-- Generated by roast-my-design-system from a scan of ${repoName} on ${scanDate}.`);
-lines.push('     Paste into CLAUDE.md, .cursor/rules or AGENTS.md. Regenerate after big refactors:');
-lines.push('     npx roast-my-design-system --rules -->');
-lines.push('');
-lines.push('Follow these rules when writing or editing UI in this repo. Every rule below was derived from a scan of this codebase, with real paths and usage counts.');
-
-// ---------- tokens ----------
-const strays = (t.colors ?? []).filter((c) => !c.isToken);
-const tokenCount = (t.colors ?? []).filter((c) => c.isToken).length;
-if (t.tokenFile || (t.colors ?? []).length) {
-  section('Colours and tokens');
-  if (t.tokenFile) {
-    rule(`Design tokens live in \`${t.tokenFile}\`. Reach for an existing token before inventing any value.`);
-    if (tokenCount && strays.length) rule(`Never hardcode colour values in components. The palette already has ${tokenCount} tokens; the scan still found ${strays.length} hardcoded colours sitting next to them. Do not add more.`);
-    else rule('Never hardcode colour values in components; add a token first if one is genuinely missing.');
-  } 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 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.`);
-  }
-}
-
-// ---------- canonical components ----------
-// Skip names that shadow framework components (their usage counts absorb the
-// framework's) and names defined in more than one file (ambiguous, and the
-// duplicates section already handles them).
-const FRAMEWORK_NAMES = new Set(['Link', 'Image', 'Head', 'Script', 'Form']);
-const nameCounts = new Map();
-for (const c of reusable) nameCounts.set(c.name, (nameCounts.get(c.name) ?? 0) + 1);
-const top = reusable
-  .filter((c) => c.usageCount > 0 && !FRAMEWORK_NAMES.has(c.name) && nameCounts.get(c.name) === 1)
-  .sort((a, b) => b.usageCount - a.usageCount).slice(0, 8);
-if (top.length) {
-  section('Canonical components');
-  rule('Use these existing components instead of writing new ones:');
-  for (const c of top) {
-    const props = c.propsHint?.named?.length ? ` · props: ${c.propsHint.named.slice(0, 4).join(', ')}` : '';
-    lines.push(`  - \`<${c.name}>\` from \`${c.file}\` (used ${c.usageCount}x${props})`);
-  }
-}
-
-// ---------- duplicates to avoid ----------
-const dupes = h.duplicates?.exactDuplicates ?? [];
-const icons = h.duplicates?.iconCollisions ?? [];
-if (dupes.length || icons.length) {
-  section('Known duplicates: do not make it worse');
-  // No per-file usage data here, so rank by how shared the location looks;
-  // when nothing stands out, do not guess a canonical.
-  const sharedScore = (f) => (f.includes('packages/') ? 4 : 0) + (/\/ui\//.test(f) ? 2 : 0) + (f.includes('components/') ? 1 : 0) - (/\bapp\//.test(f) ? 2 : 0) - (f.includes('/icons/') ? 4 : 0);
-  for (const d of dupes.slice(0, 6)) {
-    const files = d.files.map((f) => (typeof f === 'string' ? f : f.file));
-    const ranked = [...files].sort((a, b) => sharedScore(b) - sharedScore(a));
-    const clear = sharedScore(ranked[0]) > sharedScore(ranked[1]);
-    if (d.wrapped) {
-      rule(`\`<${d.name}>\` is defined twice and one wraps the other${clear ? `. Import \`${ranked[0]}\`` : ''}; do not create a third.`);
-    } else if (clear) {
-      rule(`\`<${d.name}>\` exists in ${files.length} places. Treat \`${ranked[0]}\` as canonical; do not import the other ${files.length === 2 ? 'copy' : 'copies'}, and never create another.`);
-    } else {
-      rule(`\`<${d.name}>\` exists in ${files.length} places (${files.slice(0, 2).map((f) => `\`${f}\``).join(', ')}). Match whichever the surrounding code already imports, and never create another.`);
-    }
-  }
-  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 ----------
-const arbitrary = t.tailwind?.arbitrary ?? [];
-const arbCount = arbitrary.reduce((s, a) => s + a.count, 0);
-const offScale = (t.spacing ?? []).length;
-if (t.tailwind?.spacing?.length || offScale || arbCount) {
-  section('Spacing and sizing');
-  if (t.tailwind?.spacing?.length) rule('Stay on the Tailwind spacing scale. If a gap looks wrong on a scale step, flag it instead of nudging by a pixel.');
-  if (arbCount) rule(`No new arbitrary bracket values (\`p-[13px]\`, \`text-[10px]\`). The scan found ${arbCount} already. If a value repeats, it is a decision: name it as a token instead of writing the bracket again.`);
-  if (offScale) rule(`Avoid new one-off CSS spacing values; ${offScale} off-scale value${offScale === 1 ? ' is' : 's are'} already in play.`);
-}
-
-// ---------- typography ----------
-const faces = distinctTypefaces(t.fontFamilies ?? []);
-if (faces.length) {
-  section('Typography');
-  rule(`The repo uses ${faces.length} typeface${faces.length === 1 ? '' : 's'}: ${faces.slice(0, 4).join(', ')}. Do not introduce another, and do not re-declare font stacks by hand; use the existing setup.`);
-}
-
-// ---------- styling discipline ----------
-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.)`);
-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('');
-lines.push('---');
-lines.push('*Generated by [roast-my-design-system](https://github.com/pencilrebel/roast-my-design-system). Rescan after refactors to keep these rules honest.*');
-lines.push('');
-
-writeFileSync(outPath, lines.join('\n'));
-const ruleCount = lines.filter((l) => l.startsWith('- ')).length;
-console.log(`✓ Agent rules for ${repoName}: ${ruleCount} rules, all with receipts`);
+const { text, ruleCount } = rulesMarkdown(h);
+writeFileSync(outPath, text);
+console.log(`✓ Agent rules for ${h.profile?.name ?? 'this repo'}: ${ruleCount} rules, all with receipts`);
 console.log(`  → ${outPath}`);