roast-my-design-system 3.7.1 → 3.8.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.7.1)
+![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.8.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.7.1)
+![The diagnosis report in light mode](https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/report-light-hero.png?v=3.8.0)
 
 ## What makes the numbers trustworthy
 
@@ -132,4 +132,4 @@ MIT. The code is yours to fork, modify and redistribute; the copyright notice tr
 
 **roast-my-design-system**™ and the GK mark are trademarks of Greg Kozakiewicz. Forking is welcome, republishing under this name is not: see [brand and attribution](https://pencilrebel.github.io/roast-my-design-system/brand.html).
 
-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.7.1"><img src="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark.png?v=3.7.1" 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.8.0"><img src="https://raw.githubusercontent.com/pencilrebel/roast-my-design-system/main/assets/gk-mark.png?v=3.8.0" height="15" alt="GK mark"></picture> Greg Kozakiewicz</a>.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "3.7.1",
+  "version": "3.8.0",
   "description": "Roast your design system with real data. A deterministic, zero-dependency scanner that counts everything that betrays a design system, from colours and their near-identical twins to greys, spacing values, typefaces, duplicated and never-imported components, inline styles, !important and arbitrary Tailwind values, 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

@@ -36,7 +36,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.7.1';
+const VERSION = '3.8.0';
 
 // Report identity. The scan id is a stable digest of this scan's shape, salted
 // with the report namespace, so the same repo scanned twice reads the same and
@@ -321,7 +321,7 @@ function tile(value, label, metric, fallbackTarget, healthValue = value) {
   const av = displayAvg(metric);
   if (av !== null) rows.push(row('Avg Design System', `${n(av)}${avgNote}`, av, value));
   if (rm !== null && (rm > 0 || ZERO_IDEAL.has(metric) || metric === 'arbitrary')) rows.push(row('Reputable systems', n(rm), rm, value));
-  return { num: n(value), label, health, rows };
+  return { num: n(value), label, health, rows, metric, healthValue };
 }
 const bigStats = [
   tile(colors.length, 'distinct colours', 'colors', 'a system needs ~24', tokenLed ? colorStrays : colors.length),
@@ -342,6 +342,42 @@ const healthScore = scoredTiles.length
   ? Math.round(scoredTiles.reduce((sum, s) => sum + SCORE_OF[s.health], 0) / scoredTiles.length)
   : null;
 
+// ---------- what a fix is worth ----------
+// The score is the average of the scored tiles, so moving one tile across a
+// band is worth an exact number of points: red to green 10, red to amber 5,
+// amber to green 5 (on nine tiles). Deltas are only claimed when a move
+// actually crosses a band — a cleanup that lands inside the same band is real
+// work worth zero points, and saying otherwise would be a lie.
+const TILE_COUNT = scoredTiles.length || 1;
+const scoreOfHealth = (hh) => SCORE_OF[hh] ?? 0;
+function bandPoints(metric, from, to) {
+  const a = healthOf(metric, from), b = healthOf(metric, to);
+  if (!(a in SCORE_OF) || !(b in SCORE_OF)) return 0;
+  return Math.round((scoreOfHealth(b) - scoreOfHealth(a)) / TILE_COUNT);
+}
+// The nearest number that moves this metric up a band, and what it pays.
+function nextBand(metric, value) {
+  const iv = ideal(metric);
+  if (iv === null) return null;
+  const cur = healthOf(metric, value);
+  if (cur === 'good') return null;
+  if (cur === 'warn') {
+    const target = ZERO_IDEAL.has(metric) ? 0 : iv;
+    return { target, gain: bandPoints(metric, value, target) };
+  }
+  const warnTarget = ZERO_IDEAL.has(metric) ? WARN_TOLERANCE[metric] : Math.min(median(metric) ?? iv * 1.5, iv * 1.5);
+  return { target: Math.round(warnTarget), gain: bandPoints(metric, value, Math.round(warnTarget)) };
+}
+// The score this repo would have with a set of metrics at new values.
+function projectedScore(applied) {
+  const scored = bigStats.filter((st) => st.health in SCORE_OF);
+  if (!scored.length) return healthScore;
+  return Math.round(scored.reduce((sum, st) => {
+    const v = applied.has(st.metric) ? applied.get(st.metric) : st.healthValue;
+    return sum + scoreOfHealth(healthOf(st.metric, v));
+  }, 0) / scored.length);
+}
+
 // A repo with essentially no colour/spacing signal most likely has no design
 // system in it at all; say that up front instead of quietly scoring zeros.
 const noSystemLikely = colors.length === 0 || (colors.length < 3 && spacingTotal === 0);
@@ -459,6 +495,20 @@ function duplicatesSection() {
     <div class="fams">${iconCard}${dupeCards}${famCards}</div></div>`;
 }
 
+// Scanned values get injected into style attributes below (a radius, a shadow,
+// a font size from someone else's repo). Allow only a conservative CSS charset
+// so a malformed or hostile value cannot break out of the attribute.
+const cssSafe = (v) => (typeof v === 'string' && /^[-#0-9a-z%.,()\s\/]+$/i.test(v) && !/[;{}<>"']/.test(v) ? v.trim() : null);
+// px equivalent of a length, for sorting and for rendering type at real size.
+function toPx(v) {
+  const m = /^(-?\d*\.?\d+)\s*(px|rem|em|pt)?$/i.exec(String(v).trim());
+  if (!m) return null;
+  const num = parseFloat(m[1]);
+  const unit = (m[2] ?? 'px').toLowerCase();
+  if (!Number.isFinite(num) || num <= 0) return null;
+  return unit === 'px' ? num : unit === 'pt' ? num * 1.333 : num * 16;
+}
+
 function typographySection() {
   if (!fontFamilies.length && !fontSizeTotal && !radiiTotal) return '';
   const mini = [
@@ -475,13 +525,59 @@ function typographySection() {
     .sort((a, b) => b.count - a.count).slice(0, 14);
   const receipts = (title, chips) => chips.length < 2 ? '' :
     `<div class="receipts">${eyebrow(title)}<div class="chips-row">${chips.map((c) => `<span class="vchip">${esc(String(c.label))} ×${c.count}</span>`).join('')}</div></div>`;
+
+  // ---------- specimens: the values rendered, not counted ----------
+  // Counting says "47 font sizes". Rendering them says it better: the eye
+  // finds the near-duplicates on its own, the way the grey ramp works.
+  const typeSpecimens = (() => {
+    const rows = (h.tokens.fontSizes ?? [])
+      .map((f) => ({ label: f.value, count: f.count, px: toPx(f.value) }))
+      .filter((f) => f.px && f.px >= 6 && f.px <= 200)
+      .sort((a, b) => b.px - a.px);
+    if (rows.length < 4) return '';
+    const shown = rows.slice(0, 16);
+    const capped = shown.some((r) => r.px > 52);
+    return `<div class="spec">${eyebrow(`the type scale, at its real sizes${capped ? ' · the largest are capped to fit' : ''} · how many of these are the same decision?`)}
+      <div class="spec-rows">${shown.map((r) => `
+        <div class="spec-type">
+          <span class="spec-val">${esc(r.label)} ×${r.count}</span>
+          <span class="spec-sample" style="font-size:${Math.min(r.px, 52)}px">Almost but not quite</span>
+        </div>`).join('')}</div>
+      ${rows.length > 16 ? `<div class="spec-more">and ${rows.length - 16} more</div>` : ''}</div>`;
+  })();
+
+  const radiiSpecimens = (() => {
+    const cells = (h.tokens.radii ?? [])
+      .map((r) => ({ label: r.value, count: r.count, css: cssSafe(r.value) }))
+      .filter((r) => r.css && !/^0$|^0px$/.test(r.css) && !/var\(|calc\(/i.test(r.css))
+      .slice(0, 14);
+    if (cells.length < 3) return '';
+    return `<div class="spec">${eyebrow(`the corners, drawn · ${n(radiiTotal)} radii in one interface`)}
+      <div class="spec-grid">${cells.map((r) => `
+        <div class="spec-cell"><div class="spec-box" style="border-radius:${r.css}"></div>
+        <span class="spec-cap">${esc(r.label)} ×${r.count}</span></div>`).join('')}</div></div>`;
+  })();
+
+  const shadowSpecimens = (() => {
+    const cells = (h.tokens.shadows ?? [])
+      .map((sh) => ({ label: sh.value, count: sh.count, css: cssSafe(sh.value) }))
+      .filter((sh) => sh.css && !/^(none|initial|inherit|unset|revert)$/i.test(sh.css) && !/var\(/i.test(sh.css))
+      .slice(0, 10);
+    if (cells.length < 2) return '';
+    const short = (v) => (v.length > 20 ? `${v.slice(0, 19)}…` : v);
+    return `<div class="spec">${eyebrow(`the elevations, cast${cells.length < shadows.length ? `, ${cells.length} of ${n(shadows.length)}` : ` · ${n(shadows.length)} shadow styles`} · on the light surface they were drawn for`)}
+      <div class="spec-grid spec-shadows">${cells.map((sh) => `
+        <div class="spec-cell"><div class="spec-card" style="box-shadow:${sh.css}"></div>
+        <span class="spec-cap" title="${esc(sh.label)}">${esc(short(sh.label))} ×${sh.count}</span></div>`).join('')}</div></div>`;
+  })();
   const fams = fontFamilies.slice(0, 8).map((f) =>
     `<div class="mini-card"><span class="mc-path">${esc(f.value.slice(0, 70))}</span><span class="pill${f.count > 2 ? ' pill-coral' : ' pill-mint'}">×${f.count}</span></div>`).join('');
   return `<section>
     ${sectionHead('Typography &amp; shape', '')}
     <div class="stats minis">${mini.map((s) => statTile(s)).join('')}</div>
-    ${receipts('the font sizes, by use', sizeChips)}
-    ${receipts('the radii, by use', radiiChips)}
+    ${typeSpecimens || receipts('the font sizes, by use', sizeChips)}
+    ${radiiSpecimens || receipts('the radii, by use', radiiChips)}
+    ${shadowSpecimens}
     ${fontFamilies.length > 1 ? `<div class="glass pad" style="margin-top:16px">${sectionHead(`${typefaces.length} typeface${typefaces.length === 1 ? '' : 's'}, declared ${fontFamilies.length} different ways`, 'every distinct declaration is a chance for the next one to be wrong')}<div class="fam-rows">${fams}</div></div>` : ''}
   </section>`;
 }
@@ -572,7 +668,7 @@ function giftSection() {
 
 function whereToStartSection() {
   const c = [];
-  if (agentFiles.length === 0) c.push({ score: 60, title: 'Write the agent rules file',
+  if (agentFiles.length === 0) c.push({ score: 60, metric: null, title: 'Write the agent rules file',
     sub: `No CLAUDE.md, no AGENTS.md. One page naming the canonical components and the tokens file stops your agent guessing on every UI change. Cheapest fix on this list.` });
   if (hardDupes.length > 0) {
     // Pick the pair with the strongest copy-paste evidence: sibling files in
@@ -588,10 +684,11 @@ function whereToStartSection() {
       return sc;
     };
     const d = [...hardDupes].sort((a, b) => strength(b) - strength(a))[0];
-    c.push({ score: 25 + hardDupes.length * 4, title: `Crown the canonical &lt;${esc(d.name)}&gt;`,
+    c.push({ score: 25 + hardDupes.length * 4, metric: 'exactDuplicates', after: hardDupes.length - 1,
+      title: `Crown the canonical &lt;${esc(d.name)}&gt;`,
       sub: `${hardDupes.length} component name${hardDupes.length > 1 ? 's have' : ' has'} competing implementations. Start with &lt;${esc(d.name)}&gt;: ${esc(d.files[0])} vs ${esc(d.files[1] ?? '')}. Decide which one is canonical, re-export it from one home, and rename or fold in the other.` });
   }
-  if (iconCollisions.length >= 5) c.push({ score: 20 + iconCollisions.length * 3, title: 'Merge the two icon sets',
+  if (iconCollisions.length >= 5) c.push({ score: 20 + iconCollisions.length * 3, metric: null, title: 'Merge the two icon sets',
     sub: `${iconCollisions.length} icon names exist in both sets, so every import is a coin flip. Pick one home and rename or delete the rest. Receipt: ${esc(iconCollisions[0].files[0])} vs ${esc(iconCollisions[0].files[1])}.` });
   const strayOffender = offenders.find((o) => o.strayColors > 0);
   if (colorStrays > 12) {
@@ -601,13 +698,14 @@ function whereToStartSection() {
     const besideTokens = strayOffender && tf && (strayOffender.file === tf
       || strayOffender.file.split('/').slice(0, -1).join('/') === tf.split('/').slice(0, -1).join('/')
       || /variables|tokens|theme/i.test(strayOffender.file));
-    c.push({ score: colorStrays, title: `Tokenise the ${n(colorStrays)} stray colours`,
+    c.push({ score: colorStrays, metric: 'colors', after: 0, title: `Tokenise the ${n(colorStrays)} stray colours`,
       sub: `They are hardcoded where no token names them${strayOffender ? (besideTokens
         ? `, including ${strayOffender.strayColors} in ${esc(strayOffender.file)}, sitting right next to the token definitions. Those are the cheapest wins on this page`
         : `; ${esc(strayOffender.file)} alone carries ${strayOffender.strayColors}`) : ''}. Every one is a value your agent will happily copy.` });
   }
   if (inline.count > 10) { const worst = inline.files[0];
-    c.push({ score: inline.count / 2, title: `Fold ${n(inline.count)} inline style blocks back into the system`,
+    c.push({ score: inline.count / 2, metric: 'inlineStyles', after: 0,
+      title: `Fold ${n(inline.count)} inline style blocks back into the system`,
       sub: `These are static values written as style attributes${worst ? `; start with ${esc(worst.file)} (${worst.count} blocks)` : ''}. Dynamic positioning was already excluded, so all of these could be classes or tokens today.` }); }
   if (arbitraryCount >= 20) {
     // Repeated brackets read as decisions; singletons are worth a pass. Small
@@ -618,7 +716,10 @@ function whereToStartSection() {
     const singles = arbitrary.filter((a) => a.count === 1).length;
     const top = arbitrary[0];
     const tokenFile = h.tokens.tokenFile;
-    c.push({ score: arbitraryCount / 3, title: `Give your repeated bracket values names`,
+    // naming the repeats removes their counts; the one-offs are left alone on purpose
+    const afterNaming = arbitraryCount - repeats.reduce((sum, a) => sum + a.count, 0);
+    c.push({ score: arbitraryCount / 3, metric: 'arbitrary', after: afterNaming,
+      title: `Give your repeated bracket values names`,
       sub: repeats.length
         ? `${esc(top.value)} appears ${top.count} times, which reads as a decision, not drift. If it is one, name it${tokenFile ? ` in ${esc(tokenFile)}` : ' in the scale'} so the next component (and your agent) can reach for it${repeats.length > 1 ? `; ${repeats.length - 1} more repeated value${repeats.length > 2 ? 's' : ''} deserve the same look` : ''}. The ${singles} values used once are worth a pass: keep the deliberate ones (optical nudges${nudges ? ` like the ${nudges} under 4px` : ''}, one-off layout widths) and round the accidents to a neighbouring step.`
         : `${n(arbitraryCount)} bracket values sit outside the scale, almost all used once. Keep the deliberate ones (optical nudges, one-off widths) and round the rest to a neighbouring step.` });
@@ -628,21 +729,66 @@ function whereToStartSection() {
     // the first move is to define it, next to the tokens the repo already has.
     const hasScale = twSpacing.length >= 5;
     const tf = h.tokens.tokenFile;
-    c.push({ score: spacingTotal / 2, title: hasScale
+    c.push({ score: spacingTotal / 2, metric: 'spacing', title: hasScale
       ? `Fold ${n(spacingTotal)} off-scale spacing values back to the scale`
       : `Define a spacing scale, then fold ${n(spacingTotal)} values into it`,
       sub: hasScale
         ? `${n(spacingTotal)} values sit outside the scale you already use. Keep the deliberate exceptions and round the accidents to a neighbouring step.`
         : `${n(spacingTotal)} distinct spacing values and no named scale to hold them. Define ~8 steps${tf ? ` in ${esc(tf)}, next to the tokens you already keep there` : ''}, then migrate values as you touch each file. No mass rounding.` });
   }
-  const top3 = c.sort((a, b) => b.score - a.score).slice(0, 3);
+  if (nearPairs.length >= 3) {
+    const p0 = nearPairs[0];
+    c.push({ score: 30 + nearPairs.length * 2, metric: 'nearPairs', after: 0,
+      title: `Collapse the ${n(nearPairs.length)} near-identical colours`,
+      sub: `${esc(p0.a.value)} and ${esc(p0.b.value)} are the same colour to any eye${p0.a.count + p0.b.count > 3 ? `, and they are used ${n(p0.a.count + p0.b.count)} times between them` : ''}. Nobody chose to have both. Pick the one that is already a token, point the other at it, and the pair stops multiplying.` });
+  }
+  if (important.count >= 10) {
+    const worst = important.files[0];
+    c.push({ score: 20 + important.count, metric: 'important', after: 0,
+      title: `Unwind the ${n(important.count)} !important declarations`,
+      sub: `Each one is a selector losing an argument with another selector${worst ? `; ${esc(basename(worst.file))} alone carries ${worst.count}` : ''}. Fix the specificity at the source and they stop being necessary.` });
+  }
+  if (neverImported.length >= 3) {
+    c.push({ score: 15 + neverImported.length, metric: 'neverImported', after: 0,
+      title: `Decide about the ${n(neverImported.length)} components nobody imports`,
+      sub: `${neverImported.slice(0, 3).map((x) => `&lt;${esc(x.name)}&gt;`).join(', ')}${neverImported.length > 3 ? ' and others' : ''} sit in the system with no callers. Adopt them or delete them: either answer is better than a system with rooms nobody enters.` });
+  }
+
+  // What each move is actually worth, then rank by payoff for real.
+  for (const item of c) {
+    item.delta = 0; item.target = null;
+    if (!item.metric) continue;
+    const now = bigStats.find((st) => st.metric === item.metric)?.healthValue;
+    if (now === undefined) continue;
+    if (item.after !== undefined) {
+      const gain = bandPoints(item.metric, now, item.after);
+      if (gain > 0) { item.delta = gain; continue; }
+    }
+    const nb = nextBand(item.metric, now);
+    if (nb && nb.gain > 0) item.target = nb;
+  }
+  const top3 = c.sort((a, b) => (b.delta - a.delta) || (b.score - a.score)).slice(0, 3);
   if (!top3.length) return '';
+  // The headline is the score with every move applied together, not the sum of
+  // the parts: two moves on the same tile must not be counted twice.
+  const applied = new Map();
+  for (const item of top3) if (item.metric && item.after !== undefined && item.delta > 0) applied.set(item.metric, item.after);
+  const after = projectedScore(applied);
+  const words = ['One tweak', 'Two tweaks', 'Three tweaks'][top3.length - 1];
+  const head = healthScore !== null && after > healthScore
+    ? `${words} · <b class="proj">${healthScore} &rarr; ${after}</b>`
+    : `${words} to increase your score.`;
+  const chip = (item) => item.delta > 0
+    ? `<span class="delta">+${item.delta}</span>`
+    : item.target
+      ? `<span class="delta delta-target">${item.target.target === 0 ? 'clear them all' : `under ${n(item.target.target)}`} · +${item.target.gain}</span>`
+      : '';
   return `<section class="glass pad">
-    ${sectionHead('Where to start', `${['One tweak', 'Two tweaks', 'Three tweaks'][top3.length - 1]} to increase your score.`)}
+    ${sectionHead('Where to start', head)}
     <div class="ledger">${top3.map((item, i) => `
       <div class="ledger-row start-row">
         <span class="ledger-idx">${String(i + 1).padStart(2, '0')}</span>
-        <div class="start-body"><div class="start-title">${item.title}</div><div class="sub">${item.sub}</div></div>
+        <div class="start-body"><div class="start-head"><div class="start-title">${item.title}</div>${chip(item)}</div><div class="sub">${item.sub}</div></div>
       </div>`).join('')}</div></section>`;
 }
 
@@ -885,6 +1031,26 @@ 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); }
+  .spec { margin-top:18px; }
+  .spec-rows { display:grid; gap:2px; margin-top:8px; }
+  .spec-type { display:flex; align-items:baseline; gap:16px; padding:5px 0; border-bottom:1px solid var(--line-soft); }
+  .spec-type:last-child { border-bottom:0; }
+  .spec-val { font:600 11px/1.4 var(--mono); color:var(--dim2); min-width:104px; flex-shrink:0; }
+  .spec-sample { color:var(--text); line-height:1.15; white-space:nowrap; overflow:hidden; text-overflow:ellipsis;
+    font-family:var(--disp); letter-spacing:-.01em; }
+  .spec-more { font:600 10.5px/1 var(--mono); color:var(--dim2); margin-top:10px; }
+  .spec-grid { display:flex; flex-wrap:wrap; gap:16px; margin-top:12px; }
+  .spec-cell { display:grid; gap:7px; justify-items:center; }
+  .spec-box { width:46px; height:46px; background:var(--deep); box-shadow:inset 0 0 0 1px var(--cell-ring); }
+  .spec-shadows { background:#f2f2f5; border-radius:14px; padding:20px 18px 14px; gap:22px; }
+  .spec-card { width:84px; height:50px; border-radius:10px; background:#ffffff; }
+  .spec-shadows .spec-cap { color:#71718a; max-width:104px; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+  .spec-cap { font:500 10.5px/1 var(--mono); color:var(--dim2); }
+  .start-head { display:flex; align-items:baseline; gap:10px; flex-wrap:wrap; }
+  .delta { font:700 11px/1 var(--sans); letter-spacing:.04em; padding:5px 9px; border-radius:99px;
+    background:var(--ok-soft); color:var(--ok); white-space:nowrap; }
+  .delta-target { background:var(--amber-soft); color:var(--amber); font-weight:600; }
+  .proj { color:var(--accent); font-weight:700; }
   .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; }
@@ -975,8 +1141,8 @@ ${componentsSection()}
 
 <footer>
   <div class="foot-left">
-    <div>Generated by <a class="brand" href="https://github.com/pencilrebel/roast-my-design-system">roast-my-design-system</a>, a free skill for Claude Code and Codex</div>
-    <div class="foot-sub"><span class="ver">ver. ${VERSION}</span> · <span class="scan-id" title="scan id">${scanId}</span> · built and designed by <a class="author" href="https://gregkozakiewicz.com"><span class="gk-mark"></span>Greg Kozakiewicz</a></div>
+    <div>Generated by <a class="brand" href="https://github.com/pencilrebel/roast-my-design-system">roast-my-design-system</a> <span class="ver">ver. ${VERSION}</span>, free on npm and as a Claude Code + Codex skill</div>
+    <div class="foot-sub">Designed and built by <a class="author" href="https://gregkozakiewicz.com"><span class="gk-mark"></span>Greg Kozakiewicz</a> · <span class="scan-id" title="scan id">${scanId}</span></div>
   </div>
   <span class="creds"><span>Non-destructive scan</span><span>Read-only</span><span>Paths are real</span></span>
 </footer>