roast-my-design-system 9.6.0 → 9.7.0

package/README.md

@@ -142,11 +142,11 @@ Eleven reports, hosted exactly as the tool writes them. Every number determinist
 
 The full report for vercel/ai-chatbot. The verdict answers what the agent will learn here, the gap section comes first, then "What the repo teaches the agent", Claude's read of the scan:
 
-![The full diagnosis report for vercel/ai-chatbot in dark mode: a fixed side panel with the health score and what it measures, the stack, how the repo was read as a shadcn install, an index of every section and what is not the team's and not counted; then where the agent will have to guess, the fixes you can make right now, each with what it is worth and its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, 3-yardstick tiles including the 2 shadcn tiles, the adoption map treemap, palette forensics, the shadcn theme variable by variable, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](assets/report-full-dark.png?v=9.6.0)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: a fixed side panel with the health score and what it measures, the stack, how the repo was read as a shadcn install, an index of every section and what is not the team's and not counted; then where the agent will have to guess, the fixes you can make right now, each with what it is worth and its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, 3-yardstick tiles including the 2 shadcn tiles, the adoption map treemap, palette forensics, the shadcn theme variable by variable, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](assets/report-full-dark.png?v=9.7.0)
 
 The same report in light mode (one file, built-in toggle):
 
-![The diagnosis report in light mode](assets/report-light-hero.png?v=9.6.0)
+![The diagnosis report in light mode](assets/report-light-hero.png?v=9.7.0)
 
 ## Why the numbers hold
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roast-my-design-system",
-  "version": "9.6.0",
+  "version": "9.7.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/diagnose/index.mjs

@@ -36,6 +36,8 @@ import { ownSpacing, profileOf, installedOf, splitArbitrary, installedByOwner }
 import { KITS } from '../profiles/kit-common.mjs';
 import { rulesOn as lintRulesOn, describeRule as lintDescribe, entryMatcher as lintMatcher, RULE_TILE as LINT_TILE } from '../profiles/shadcn-lint.mjs';
 import { publishesLine } from '../profiles/registry.mjs';
+import { CONTRACT_MIN } from '../lib/palette.mjs';
+import { GREY_HUE_RE } from '../harvest/paint.mjs';
 
 // The benchmark and every judgement made against it live in score.mjs; this
 // file only draws. The same numbers reach summary.json through scoreHarvest.
@@ -55,6 +57,13 @@ const h = JSON.parse(readFileSync(inPath, 'utf8'));
 // the shadcn repos in the fleet).
 const B = benchHelpers(bench, profileOf(h).kind);
 const { percentile, cleanerPct, ideal, median, displayAvg, refMedian } = B;
+// The group the medians come from, by name: a registry is compared with the
+// shadcn repos, an MUI product with the MUI ones. The verdict said "the
+// median of 34 scanned repos" when the medians came from a kit's own group,
+// on 51 of 204 fleet scans, and the tiles said "Avg registry repo" for a
+// group that does not exist (2026-10-01).
+const GROUP_NAMES = { shadcn: 'shadcn', registry: 'shadcn', tailwind: 'Tailwind', mui: 'MUI', mantine: 'Mantine', chakra: 'Chakra', antd: 'Ant Design' };
+const benchGroup = B.sliceInfo ? { name: GROUP_NAMES[B.sliceInfo.kind] ?? B.sliceInfo.kind, repoCount: B.sliceInfo.repoCount } : null;
 const healthOf = makeHealthOf(B);
 const M = coreMetrics(h);
 
@@ -260,6 +269,14 @@ const fresh = P.isShadcn && P.shadcn?.fresh?.fresh === true;
 if (P.isShadcn) arbitrary = splitArbitrary(arbitrary, installedOf(P)).own;
 const breakdown = scoreBreakdown(h, bench);
 const neverImported = neverImportedComponents(h.components, P.uiDir);
+// In a shadcn catalogue folder the unused list holds two things: shadcn's
+// stock, installed and waiting to be used, and components the team wrote
+// itself that nothing imports. Both were called stock until 9.7.0: 178 of
+// 2,182 such components in 16 shadcn repos are the team's own (cal.com 38,
+// 2026-10-01). Neither is scored; the words now tell them apart.
+const isInstalled = installedOf(P);
+const neverStock = P.vendoredUi ? neverImported.filter((c) => isInstalled(c.file)) : [];
+const neverOwn = P.vendoredUi ? neverImported.filter((c) => !isInstalled(c.file)) : neverImported;
 
 // Measurability and kind, decided once in profiles/ (telekom/scale, 2026-09-01):
 // when the component detector could not read this repo's stack, the component
@@ -372,7 +389,8 @@ if (bench && findings.length && !fresh) {
   const core = [['colors', tokenLed ? colorStrays : colors.length], ['greys', tokenLed ? greyStrays : greys.length],
     ['spacing', spacingTotal], ['typefaces', typefaces.length], ['exactDuplicates', hardDupes.length], ['inlineStyles', inline.count]];
   const worse = core.filter(([m, v]) => median(m) !== null && v > median(m)).length;
-  if (worse >= 3) verdict += ` Messier than the median of ${bench.repoCount} scanned repos on ${worse} of ${core.length} core metrics. And the median repo is already a mess.`;
+  const pool = benchGroup ? `${benchGroup.repoCount} scanned ${benchGroup.name} repos` : `${bench.repoCount} scanned repos`;
+  if (worse >= 3) verdict += ` Messier than the median of ${pool} on ${worse} of ${core.length} core metrics. And the median repo is already a mess.`;
 }
 
 // ---------- health scoring ----------
@@ -429,13 +447,15 @@ function tile(t, pLabel, pMetric, pFallback) {
   const avgNote = pct !== null && pct >= 60 && health !== 'good' ? ` · messier than ${pct}%`
     : clean !== null && clean >= 60 ? ` · cleaner than ${clean}%` : '';
   const av = displayAvg(metric);
-  if (av !== null) rows.push(row(B.sliceInfo ? `Avg ${B.sliceInfo.kind} repo` : 'Avg Design System', `${n(av)}${avgNote}`, av, value));
+  if (av !== null) rows.push(row(benchGroup ? `Avg ${benchGroup.name} repo` : '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));
   // A vendored catalogue is never judged for what it left on the shelf, and a
   // library's internal use says nothing about adoption: shown, not scored.
   if (health === 'info' && metric === 'neverImported') {
     rows.push({ label: isLibrary
       ? 'library: internal use only, downstream consumers invisible'
+      : neverOwn.length
+      ? `${neverStock.length ? `${n(neverStock.length)} installed by the shadcn CLI and ` : ''}${n(neverOwn.length)} of the team's own, not used yet; not scored`
       : 'catalogue stock: installed by the shadcn CLI, not used yet', val: '', dir: '' });
   }
   if (health === 'info' && metric === 'paintTin') {
@@ -520,16 +540,7 @@ function paletteSection() {
   const strays = colors.length - tokens;
   const tokenPct = Math.round((tokens / colors.length) * 100);
 
-  // Usage-weighted colour bar: every colour, width proportional to use.
-  // Beyond 60 segments the bar turns to noise; fold the tail into one cell.
-  const sorted = [...colors].sort((a, b) => b.count - a.count);
-  const shown = sorted.slice(0, 60);
-  const rest = sorted.slice(60);
-  const cells = shown.map((c) => {
-    const src = c.files?.[0] ? ` in ${c.files[0].file}` : '';
-    return `<div class="uc${c.isToken ? '' : ' stray'}" style="background:${swatch(c.value)};flex-grow:${Math.max(c.count, 1)}" title="${esc(c.value)} ×${c.count}${esc(src)}">${c.isToken ? '' : '<i></i>'}</div>`;
-  }).join('');
-  const restCell = rest.length ? `<div class="uc uc-rest" style="flex-grow:${Math.max(rest.reduce((s, c) => s + c.count, 0), 1)}" title="${rest.length} more colours">+${rest.length}</div>` : '';
+  const usage = colourUsage();
 
   const rampFor = (list) => `
     <div class="grey-strip">${list.map((c) => `<div class="grey-cell" style="background:${swatch(c.value)}" title="${esc(c.value)} ×${c.count}"></div>`).join('')}</div>
@@ -555,10 +566,11 @@ function paletteSection() {
   </div>
   <div class="glass pal-usage">
     <div class="pal-usage-head">
-      <div>${eyebrow('Colour usage')}<div class="h3d">Sized by how often each is used</div></div>
-      <div class="legend"><span><i class="lg lg-tok"></i> token</span><span><i class="lg lg-stray"></i> stray</span></div>
+      <div>${eyebrow('Colour usage')}<div class="h3d">${usage.subtitle}</div></div>
+      <div class="legend">${usage.legend}</div>
     </div>
-    <div class="usage-bar">${cells}${restCell}</div>
+    <div class="usage-bar">${usage.cells}</div>
+    ${usage.line}
     ${ramp}
     ${nearPairs.length ? `
     <div class="receipts">${eyebrow(`${nearPairs.length} nearly identical pair${nearPairs.length === 1 ? '' : 's'} · each pair is 1 colour recorded twice`)}
@@ -568,6 +580,138 @@ function paletteSection() {
 </section>`;
 }
 
+// The Colour usage bar. Since 9.7.0 it is sized by USE (harvest/coloruse.mjs):
+// a theme class, a var() read or a read of the kit's theme joins its colour's
+// segment, a Tailwind palette class is a palette cell or a stray as the one
+// palette rule says, and a definition is not a use. Until then it was sized by
+// literal writes, the theme's own definitions included, so bg-primary on every
+// button drew primary as one of the thinnest segments. Where the repo reads
+// its theme mostly through code the pass cannot follow, and for a harvest
+// written before 9.7.0, the bar stays sized by written values and says so.
+// Beyond 60 segments the bar turns to noise; the tail folds into one cell
+// per state, so the visible proportions stay true.
+function colourUsage() {
+  const use = h.colourUse ?? null;
+  const written = () => {
+    const sorted = [...colors].sort((a, b) => b.count - a.count);
+    const shown = sorted.slice(0, 60);
+    const rest = sorted.slice(60);
+    const cells = shown.map((c) => {
+      const src = c.files?.[0] ? ` in ${c.files[0].file}` : '';
+      return `<div class="uc${c.isToken ? '' : ' stray'}" style="background:${swatch(c.value)};flex-grow:${Math.max(c.count, 1)}" title="${esc(c.value)} ×${c.count}${esc(src)}">${c.isToken ? '' : '<i></i>'}</div>`;
+    }).join('');
+    const restCell = rest.length ? `<div class="uc uc-rest" style="flex-grow:${Math.max(rest.reduce((s, c) => s + c.count, 0), 1)}" title="${rest.length} more colours">+${rest.length}</div>` : '';
+    return { cells: cells + restCell, subtitle: 'Sized by how often each value is written',
+      legend: '<span><i class="lg lg-tok"></i> token</span><span><i class="lg lg-stray"></i> stray</span>' };
+  };
+  if (!use || !use.totals?.total) return { ...written(), line: '' };
+  if (use.fallback) {
+    const pct = Math.round(use.fallback.share * 100);
+    const words = { sass: 'Sass variables', less: 'Less variables', 'js-theme': 'JavaScript theme objects' };
+    const what = listWords(use.fallback.why.map((w) => words[w]).filter(Boolean));
+    return { ...written(), line: `<p class="sub use-line">${pct} in every 100 colour uses here go through ${what}. This bar cannot follow those yet, so it counts written values instead.</p>` };
+  }
+
+  const kitName = P.kit?.name ?? 'kit';
+  // a dark: override on a theme whose configured sheet sets dark values
+  const darkRows = (P.shadcn?.sheet?.darkRows ?? 0) > 0;
+  const how = (c) => listWords([c.classes ? `${n(c.classes)} as classes` : '', c.vars ? `${n(c.vars)} through var()` : '', c.kit ? `${n(c.kit)} through the ${kitName} theme` : ''].filter(Boolean));
+  const label = (c) => {
+    if (c.named === 'kit') return `${c.names[0]} ×${n(c.weight)}, read by name from the ${kitName} theme`;
+    if (c.named === 'outside') return `${c.names[0]} ×${n(c.weight)}, read by name; its value is not a colour this scan can read`;
+    if (c.state === 'token') return `${c.value}${c.names.length ? ` (${c.names.join(', ')})` : ''} ×${n(c.weight)}: ${how(c)}`;
+    if (c.state === 'palette') return `${c.names[0]} ×${n(c.weight)} as Tailwind palette classes`;
+    if (c.written) return `${c.value} ×${n(c.weight)} written by hand${c.names.length ? `; the theme names it ${c.names[0]}` : c.token ? '; a token already holds this value' : ''}`;
+    if (c.dark) return `${c.names[0]} ×${n(c.weight)} as dark: overrides written by hand${darkRows ? ', where the theme already sets its own dark-mode colours' : ''}`;
+    return `${c.names[0]} ×${n(c.weight)} as palette classes where the theme names its own colours`;
+  };
+  const MARK = { token: '', palette: ' pal', stray: ' stray' };
+  const cells = use.segments.map((c) => {
+    const src = c.file ? ` · most in ${c.file}` : '';
+    const bg = c.named ? '' : `background:${swatch(c.value)};`;
+    return `<div class="uc${MARK[c.state]}${c.named ? ' named' : ''}" style="${bg}flex-grow:${Math.max(c.weight, 1)}" title="${esc(label(c))}${esc(src)}">${c.state === 'token' ? '' : '<i></i>'}</div>`;
+  }).join('');
+  const REST = { token: 'reached by name', palette: 'as Tailwind palette classes', stray: 'as strays' };
+  const rest = ['token', 'palette', 'stray'].filter((k) => use.rest[k].count)
+    .map((k) => `<div class="uc uc-rest${MARK[k]}" style="flex-grow:${Math.max(use.rest[k].weight, 1)}" title="${n(use.rest[k].count)} more colours ${REST[k]}, ${n(use.rest[k].weight)} uses">+${n(use.rest[k].count)}${k === 'token' ? '' : '<i></i>'}</div>`).join('');
+
+  // A legend entry for each kind of cell the bar holds. "token" is a colour
+  // drawn with its swatch, here or folded into the "+N" tail; a bar whose
+  // token cells and tail are all names with no colour shown has none
+  // (Unleash: every cell an MUI read). The dotted "named" entry stands for
+  // the dotted cells drawn.
+  const has = (state) => use.segments.some((c) => c.state === state) || use.rest[state].count > 0;
+  const restSwatched = use.rest.token.count - (use.rest.token.named?.count ?? 0);
+  const swatched = use.segments.some((c) => c.state === 'token' && !c.named) || restSwatched > 0;
+  const named = use.segments.some((c) => c.state === 'token' && c.named);
+  const legend = [
+    swatched ? '<span><i class="lg lg-tok"></i> token</span>' : '',
+    named ? '<span><i class="lg lg-named"></i> named, colour not shown</span>' : '',
+    has('palette') ? '<span><i class="lg lg-pal"></i> Tailwind palette</span>' : '',
+    has('stray') ? '<span><i class="lg lg-stray"></i> stray</span>' : '',
+  ].join('');
+
+  // Of every 100 uses: three shares that add up to 100 (largest remainder)
+  const raw = [use.share.token, use.share.palette, use.share.stray].map((x) => x * 100);
+  const [t, p, st] = (() => {
+    const out = raw.map(Math.floor);
+    const order = raw.map((x, i) => [x - Math.floor(x), i]).sort((a, b) => b[0] - a[0] || a[1] - b[1]);
+    const short = 100 - out.reduce((a, b) => a + b, 0);
+    for (let k = 0; k < short; k++) out[order[k][1]] += 1;
+    return out;
+  })();
+  const T = use.totals;
+  // what a stray is here, said once after the shares
+  const strayWhat = T.written && T.paletteStray ? 'a value written by hand, or a palette class where the theme has its own colour'
+    : T.written ? 'a value written by hand' : 'a palette class where the theme has its own colour';
+  const parts = [
+    t ? `${t} use${t === 1 ? 's' : ''} a theme colour by name` : '',
+    p ? `${p} use${p === 1 ? 's' : ''} Tailwind's palette` : '',
+    st ? `${st} ${st === 1 ? 'is a stray' : 'are strays'}` : '',
+  ].filter(Boolean);
+  const sentences = [`Of every 100 colour uses, ${listWords(parts)}.${st ? ` A stray is ${strayWhat}.` : ''}`];
+  // why the palette cells are not strays, in the one rule's terms
+  if (p) {
+    const w = use.paletteWhy ?? {};
+    if (!P.palette && (w.off ?? 0) > 0) {
+      sentences.push(ds.kind === 'shadcn' && ds.cssVariables === false
+        ? "shadcn is set up without CSS variables here, so Tailwind's palette is the theme."
+        // a shadcn repo with no theme the rule can read still has its
+        // palette classes counted by the off-theme colours tile (workout-cool)
+        : P.isShadcn && (P.shadcn?.paint?.tin?.uses ?? 0) > 0
+          ? "No theme was found to check these palette classes against, so the bar shows them as Tailwind's palette. The off-theme colours tile still counts palette classes."
+          : 'The report does not check palette classes against a theme here, so none of them count as strays.');
+    }
+    const fam = P.palette?.families ?? null;
+    // white and black apart, and which dark: overrides are strays on the bar
+    const wb = [(w.white ?? 0) > 0 ? 'white' : '', (w.black ?? 0) > 0 ? 'black' : ''].filter(Boolean);
+    const left = [
+      // the rule flags dark: backgrounds, text and borders; every other
+      // dark: white or black (dark:via-white, dark:ring-white) stays plain
+      wb.length ? `plain ${listWords(wb)}${T.paletteStrayDark ? ', except dark: backgrounds, text and borders' : ''}` : '',
+      w.family && fam ? (!fam.grey ? 'greys (the theme names no grey)' : 'colours other than grey (the theme names only greys)') : '',
+      w.apply ? '@apply lines in stylesheets' : '',
+      w.sides ? `side borders and ring offsets${w.sidesTop ? `, such as ${w.sidesTop}` : ''}` : '',
+      w.installed ? "shadcn's own components" : '',
+    ].filter(Boolean);
+    // semicolons: "plain white and black" carries its own "and"
+    if (P.palette && left.length) sentences.push(`Palette classes not counted as strays: ${left.join('; ')}.`);
+  }
+  if (use.scope === 'installed') sentences.push("Your own code uses colour fewer than 20 times so far, so shadcn's installed components are counted too.");
+  else if (P.isShadcn && use.doorFiles) sentences.push("shadcn's own components are left out, as they are in the score.");
+  return {
+    cells: cells + rest, legend,
+    subtitle: 'Sized by how often the code uses each colour',
+    // the shares in one line; how they were counted folded under it, the
+    // same fold as "why this matters" (Greg, 1 October)
+    line: `<p class="sub use-line">${esc(sentences[0])}</p>${sentences.length > 1 ? `<div class="whywrap"><button type="button" class="whybtn" data-why="colouruse">${WHY_ICON}<span class="why-lab">how this is counted</span></button><div class="whytext" hidden id="why-colouruse">${sentences.slice(1).map((x) => `<p>${esc(x)}</p>`).join('')}</div></div>` : ''}`,
+  };
+}
+// "a", "a and b", "a, b and c"
+function listWords(xs) {
+  return xs.length <= 1 ? (xs[0] ?? '') : `${xs.slice(0, -1).join(', ')} and ${xs.at(-1)}`;
+}
+
 // Agent traps: findings that do not just sit there but multiply, because an
 // agent reads the repo as instruction. Copy only, no new measurement, and a
 // trap renders only when its mechanism is real for this repo, so the marker
@@ -914,12 +1058,12 @@ function adoptionMap(tiled) {
 // the obituary column. "Untouched since 2023" needs no decoding, and a heavy
 // year reads as what it is, the fossil of one abandoned effort. Orphans
 // without a date (no git) fall back to one plain row, exactly as before.
-function orphanRows() {
-  const shown = neverImported.slice(0, 16);
+function orphanRows(list = neverImported) {
+  const shown = list.slice(0, 16);
   const chip = (c) => `<span class="vchip" title="${esc(c.file)}${c.lastTouched ? ` · untouched since ${esc(c.lastTouched)}` : ''}">&lt;${esc(c.name)}&gt;</span>`;
-  const more = neverImported.length > 16 ? `<span class="vchip dim">+${neverImported.length - 16} more</span>` : '';
+  const more = list.length > 16 ? `<span class="vchip dim">+${list.length - 16} more</span>` : '';
   const dated = shown.filter((c) => c.lastTouched);
-  if (dated.length < 2) return `<div class="chips-row">${shown.slice(0, 8).map(chip).join('')}${neverImported.length > 8 ? `<span class="vchip dim">+${neverImported.length - 8} more</span>` : ''}</div>`;
+  if (dated.length < 2) return `<div class="chips-row">${shown.slice(0, 8).map(chip).join('')}${list.length > 8 ? `<span class="vchip dim">+${list.length - 8} more</span>` : ''}</div>`;
   const byYear = new Map();
   for (const c of shown) {
     const k = c.lastTouched ? c.lastTouched.slice(0, 4) : 'no git date';
@@ -959,11 +1103,18 @@ function componentsSection() {
     ${fresh ? '<p class="sub">No code of your own uses the kit yet. The counts below are the components using each other.</p>' : ''}
     ${onceUsed.length && !fresh ? `<p class="sub">${n(onceUsed.length)} component${onceUsed.length === 1 ? ' is' : 's are'} imported exactly once: ${onceUsed.slice(0, 6).map((c) => `&lt;${esc(c.name)}&gt;`).join(', ')}${onceUsed.length > 6 ? ` and ${onceUsed.length - 6} more` : ''}. Quiet corners, not yet a system.</p>` : ''}
     ${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(isLibrary ? `${n(neverImported.length)} components unused internally · showroom stock to review, not dead weight: consumers in other repos are invisible from here` : vendoredUi ? `${n(neverImported.length)} catalogue components not used yet · installed by the shadcn CLI and waiting to be used, not written by this team` : `${n(neverImported.length)} components defined but never imported · they sit in the system as wrong answers waiting to be picked`)}
+    ${neverImported.length >= 2 && vendoredUi ? `${neverStock.length ? `
+    <div class="receipts">${eyebrow(`${n(neverStock.length)} shadcn component${neverStock.length === 1 ? '' : 's'} installed but not used yet · added by the shadcn CLI, not written by this team`)}
+    ${orphanRows(neverStock)}
+    <p class="sub" style="margin-top:8px">Use one before you build anything new. This list is counted and shown, and takes nothing off the score.</p></div>` : ''}${neverOwn.length ? `
+    <div class="receipts">${eyebrow(`${n(neverOwn.length)} component${neverOwn.length === 1 ? '' : 's'} the team wrote in ${esc(P.uiDir)} ${neverOwn.length === 1 ? 'is' : 'are'} never imported · an agent may use ${neverOwn.length === 1 ? 'it' : 'one of these'} by mistake`)}
+    ${orphanRows(neverOwn)}
+    <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. Counted and shown, not scored.</p>
+    ${whyToggle('neverImported')}</div>` : ''}` : neverImported.length >= 2 ? `
+    <div class="receipts">${eyebrow(isLibrary ? `${n(neverImported.length)} components unused internally · showroom stock to review, not dead weight: consumers in other repos are invisible from here` : `${n(neverImported.length)} components defined but never imported · an agent may use one of these by mistake`)}
     ${orphanRows()}
-    <p class="sub" style="margin-top:8px">${vendoredUi ? 'Reach for one before building anything new. This list is counted and shown, and takes nothing off the score.' : 'Routers, dynamic imports and barrel files can hide real usage, so treat this as a shortlist to check, not a demolition order.'}</p>
-    ${isLibrary || vendoredUi ? '' : whyToggle('neverImported')}` : ''}</section>`;
+    <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>
+    ${isLibrary ? '' : whyToggle('neverImported')}` : ''}</section>`;
 }
 
 // "Where to start" — at most three moves, every one derived from this repo's
@@ -1164,12 +1315,41 @@ function whereToStartSection() {
     const pt = P.shadcn.paint;
     if (pt.tin.uses >= 10) {
       const s0 = pt.tin.samples[0], f0 = productFirst(pt.tin.top)[0];
-      // The swap only works when the theme file holds the variables. A
-      // product whose sheet defines none of them (formbricks: brand rows
-      // only, slate as the palette) needs a decision first, not a prompt:
-      // swapping classes there leaves text with no colour.
-      const sheetHasRows = (P.shadcn?.sheet?.shadcnPresent ?? 0) >= 5 || P.shadcn?.kit?.cssVariables === false;
-      c.push(sheetHasRows
+      // The swap only works when the theme holds the variables. Which first
+      // move fits depends on where the theme lives (9.7.0). Until then the
+      // gate read the configured sheet alone, and sent documenso and
+      // taxonomy (shadcn's rows in a stylesheet no config names) and
+      // formbricks (a v4 theme of its own, written straight into @theme) to
+      // "Decide what the product paints from", telling the first two their
+      // theme defined none of shadcn's colour variables.
+      //   - a configured sheet holding shadcn's rows, or utility-class mode: repaint
+      //   - a configured sheet that is a theme of the repo's own (3 names or
+      //     more) lacking shadcn's greys: map the palette onto it first
+      //   - no configured sheet, but shadcn's rows in a stylesheet: repaint
+      //   - otherwise the palette is the system today: decide first
+      const sc = P.shadcn ?? {};
+      const tr = sc.themeRead ?? null;
+      const missing = tr ? ['muted-foreground', 'border', 'background', 'foreground'].filter((r) => !tr.names.includes(r)) : [];
+      const gate = sc.kit?.cssVariables === false ? 'repaint'
+        : sc.sheet?.found
+          ? ((sc.sheet.shadcnPresent ?? 0) >= CONTRACT_MIN ? 'repaint'
+            : tr && tr.file === sc.sheet.file && tr.count >= 3 ? (missing.length ? 'map' : 'repaint') : 'decide')
+          : (sc.contract?.rows ?? 0) >= CONTRACT_MIN ? 'repaint' : 'decide';
+      // a palette grey among the samples (white and black are not greys here)
+      const isGreyClass = (v) => GREY_HUE_RE.test(v) && !/-(?:white|black)(?:\/|$)/.test(v);
+      const grey = (pt.tin.samples ?? []).map((x) => x.value).find(isGreyClass) ?? null;
+      const textGrey = (pt.tin.samples ?? []).map((x) => x.value.replace(/^(?:[\w-]+:)*/, '').replace(/\/\d+$/, '')).find((v) => /^text-/.test(v) && isGreyClass(v)) ?? 'text-slate-500';
+      // a theme's names, one per family (brand, not brand-light and brand-dark),
+      // in the theme's own order
+      const families = tr ? [...tr.names.reduce((m, nm) => { const k = nm.split('-')[0]; if (!m.has(k) || nm.length < m.get(k).length) m.set(k, nm); return m; }, new Map()).values()] : [];
+      const themeNames = !tr ? ''
+        : tr.count <= 4 ? `${n(tr.count)} colours of its own (${listWords(tr.names)})`
+          : families.length >= 4 ? `${n(tr.count)} colours of its own, from ${listWords(families.slice(0, 3))} to ${families.at(-1)}`
+            : `${n(tr.count)} colours of its own, among them ${listWords(families)}`;
+      if (gate === 'map') c.push({ score: 20 + pt.tin.per100 / 4, metric: 'paintTin', after: 0,
+        title: `Map the palette onto the theme you already have`,
+        sub: `${esc(s0.value)} appears ${s0.count} times.${f0 ? ` ${esc(basename(f0.file))} alone has ${f0.count} palette classes.` : ''} ${esc(tr.file)} already names ${esc(themeNames)}. ${grey ? 'It does not name the greys these classes replace' : "It does not name shadcn's colours for text, borders and surfaces"}: ${listWords(missing.slice(0, 3))}. Add ${grey ? 'those greys' : 'them'} to the theme first, then change the classes one file at a time.${missing.includes('muted-foreground') ? ` If you change <code>${esc(textGrey)}</code> to <code>text-muted-foreground</code> before that, the text will have no colour.` : ''}` });
+      else c.push(gate === 'repaint'
         ? { score: 20 + pt.tin.per100 / 4, metric: 'paintTin', after: 0,
           title: `Repaint the ${n(pt.tin.uses)} colours from outside the theme`,
           sub: `${esc(s0.value)} appears ${s0.count} times${f0 ? `, ${esc(basename(f0.file))} alone carries ${f0.count}` : ''}. The theme file already has a variable for each (a grey is <code>text-muted-foreground</code>, a status colour is a Badge variant or a variable you add). Swap the class, not the value.` }
@@ -1191,13 +1371,13 @@ function whereToStartSection() {
       const s0 = k.colour.samples[0], f0 = productFirst(k.colour.top)[0];
       c.push({ score: 20 + k.colour.per100 / 4, metric: 'kitColour', after: 0,
         title: `Move the ${n(k.colour.uses)} colours written on components into the ${esc(k.name)} theme`,
-        sub: `The most written is ${esc(s0.value)} (${s0.count} times)${f0 ? `; ${esc(basename(f0.file))} carries the most, ${f0.count}, mostly ${esc(f0.sample)}` : ''}.${s0.inTheme ? ` ${esc(s0.value)} is already in your theme: read it from there, from the entry that holds it in every mode.` : ''} ${k.themeFiles.length ? `The theme in ${esc(k.themeFiles[0])} is where a colour is decided` : `There is no theme yet: start one with ${KITS[k.name]?.advice.themeCall ?? "the kit's theme call"} and put the palette there`}. ${KITS[k.name]?.advice.colourHow ?? ''}` });
+        sub: `The most written is ${esc(s0.value)} (${s0.count} times)${f0 ? `; ${esc(basename(f0.file))} carries the most, ${f0.count}, mostly ${esc(f0.sample)}` : ''}.${s0.inTheme ? ` ${esc(s0.value)} is already in your theme: read it from there, from the entry that holds it in every mode.` : ''} ${k.themeFiles.length ? `The theme in ${esc(k.themeFiles[0])} is where a colour is decided` : `There is no theme yet: start one with ${KITS[k.name]?.advice.themeCall ?? "the kit's theme call"} and put the palette there`}. ${KITS[k.name]?.advice.colourHow ?? ''}${secondKitMoveNote(k, 'colours')}` });
     }
     if (k.px.uses >= 10) {
       const s0 = k.px.samples[0], f0 = productFirst(k.px.top)[0];
       c.push({ score: 15 + k.px.per100 / 4, metric: 'kitPx', after: 0,
         title: `Put the ${n(k.px.uses)} pixel spacings on the theme's spacing steps`,
-        sub: `The most written is ${esc(s0.value)} (${s0.count} times)${f0 ? `; ${esc(basename(f0.file))} carries the most, ${f0.count}, mostly ${esc(f0.sample)}` : ''}. ${KITS[k.name]?.advice.spacingHow(k) ?? ''}` });
+        sub: `The most written is ${esc(s0.value)} (${s0.count} times)${f0 ? `; ${esc(basename(f0.file))} carries the most, ${f0.count}, mostly ${esc(f0.sample)}` : ''}. ${KITS[k.name]?.advice.spacingHow(k) ?? ''}${secondKitMoveNote(k, 'px')}` });
     }
   }
 
@@ -1271,6 +1451,7 @@ function whereToStartSection() {
   const promptFor = (item) => fixPrompt({
     metric: item.metric,
     kit: P.isKit ? P.kit?.name : null,
+    second: P.isKit && P.kit?.second ? { name: P.kit.second.name, pkg: P.kit.second.pkg } : null,
     title: unesc(item.title),
     sub: unesc(item.sub),
     // the points arrive when the whole finding is done; one file moves the count
@@ -1469,9 +1650,24 @@ function shadcnReceipt() {
     const counted = (r.counted?.code ?? 0) === 0 && r.themes?.total
       ? `<b>It publishes no code, so the themes check is the score</b>: the ${n(kept)} files of the app that makes them are not counted.`
       : `<b>Only what it publishes is counted</b>: ${n(r.counted?.code ?? 0)} code file${(r.counted?.code ?? 0) === 1 ? '' : 's'}${kept ? `, with ${n(kept)} more kept out as its site, demos and examples` : ''}.`;
-    return `<div class="excl fresh">Read as a shadcn registry: ${what}${r.variants.length ? `, the same components kept in ${r.variants.length} variants` : ''}. ${counted}${th}</div><div class="excl">Evidence: ${receipt}</div>`;
+    return `<div class="excl fresh">Read as a shadcn registry: ${what}${r.variants.length ? `, the same components kept in ${r.variants.length} variants` : ''}. ${counted}${th}</div><div class="excl">Evidence: ${receipt}</div>${themeUsesLine()}`;
   }
-  return `<div class="excl">Read as a shadcn install (${esc(P.confidence ?? 'medium')} confidence): ${receipt}</div>`;
+  return `<div class="excl">Read as a shadcn install (${esc(P.confidence ?? 'medium')} confidence): ${receipt}</div>${themeUsesLine()}`;
+}
+// The theme's names, and how often class names matching them appear across
+// the repo, by the Tailwind receipt's counter with comments blanked (shadcn's
+// own components included, as there) (9.7.0). A count under half the bar's
+// own class uses means the receipt read the wrong names: onlook's @theme
+// holds only its 8 sidebar names (49 uses, the bar counts 1,926), and
+// supabase's reader took a comment saying "@theme inline block" for the
+// theme (551 against 5,869). Said nothing rather than something the bar
+// beside it contradicts.
+function themeUsesLine() {
+  const u = P.shadcn?.themeUses ?? null;
+  if (!u?.uses) return '';
+  if (h.colourUse?.totals && u.uses * 2 < h.colourUse.totals.classes) return '';
+  const N = u.names.length;
+  return `<div class="excl">Its theme names ${n(N)} colour${N === 1 ? '' : 's'} in ${esc(u.file)}; class names matching them appear ${n(u.uses)} time${u.uses === 1 ? '' : 's'} across ${n(u.usedIn)} file${u.usedIn === 1 ? '' : 's'}.</div>`;
 }
 
 // A Tailwind repo with its own theme: what the vocabulary is, how much of
@@ -1488,7 +1684,39 @@ function publishesRegistryLine() {
 function kitReceipt() {
   if (!P.isKit || !P.kit) return '';
   const k = P.kit;
-  return `<div class="excl fresh">Read as a product built on ${esc(k.name)}: imported in ${n(k.kitFiles)} files, ${k.themeFiles.length ? `theme defined in ${esc(k.themeFiles[0])}` : `no theme of its own, so the ${esc(k.name)} defaults are the theme`}. The kit's own code is installed from npm and not counted; what is counted is what the repo writes onto its components.</div><div class="excl">Evidence: ${esc(P.evidence.join(' · '))}</div>`;
+  const sk = k.second;
+  // a second kit: named, and why its own files are not in the counts
+  // the files without the first kit stay out of the kit counts; they still
+  // count in the repo-wide tiles like any other file
+  const without = !sk?.withoutFirst ? '' : sk.withoutFirst === sk.files ? `, none of them with ${esc(k.name)}` : `, ${n(sk.withoutFirst)} of them without ${esc(k.name)}`;
+  const second = !sk ? '' : ` ${esc(sk.name)} is imported in ${n(sk.files)} files too${sk.withoutFirst
+    ? `${without}. ${sk.withoutFirst === 1 ? 'That file is' : `Those ${n(sk.withoutFirst)} files are`} not in the kit counts: ${esc(sk.name)} components do not read the ${esc(k.name)} theme.`
+    : `, each of them beside ${esc(k.name)}.`}`;
+  return `<div class="excl fresh">Read as a product built on ${esc(k.name)}: imported in ${n(k.kitFiles)} files, ${k.themeFiles.length ? `theme defined in ${esc(k.themeFiles[0])}` : `no theme of its own, so the ${esc(k.name)} defaults are the theme`}. The kit's own code is installed from npm and not counted; what is counted is what the repo writes onto its components.${second}</div><div class="excl">Evidence: ${esc(P.evidence.join(' · '))}</div>`;
+}
+
+// A second kit, on the two kit moves: change only the first kit's
+// components, said only where some of that card's values sit in files that
+// use both kits
+function secondKitMoveNote(k, part) {
+  const sk = k.second;
+  return sk?.mixed && sk.mixedPaint?.[part] ? ` In the ${n(sk.mixed)} file${sk.mixed === 1 ? '' : 's'} that also use${sk.mixed === 1 ? 's' : ''} ${esc(sk.name)}, change only what sits on ${esc(k.name)} components.` : '';
+}
+
+const aKitName = (name) => `${/^(?:[AEIOU]|MUI)/.test(name) ? 'an' : 'a'} ${esc(name)}`;
+// A second kit, in the kit section: which files are counted and which are not
+function secondKitBlock(k) {
+  const sk = k.second;
+  if (!sk) return '';
+  const mp = sk.mixedPaint ?? { colours: 0, px: 0 };
+  const inThem = [mp.colours ? `${n(mp.colours)} of the colours` : '', mp.px ? `${n(mp.px)} of the pixel sizes` : ''].filter(Boolean).join(' and ');
+  const one = mp.colours + mp.px === 1;
+  const parts = [
+    sk.withoutFirst ? `${n(sk.withoutFirst)} file${sk.withoutFirst === 1 ? ' uses' : 's use'} ${esc(sk.name)} without ${esc(k.name)}. ${sk.withoutFirst === 1 ? 'It is' : 'They are'} not in the counts above.` : '',
+    sk.mixed ? `${n(sk.mixed)} file${sk.mixed === 1 ? ' uses' : 's use'} both kits and ${sk.mixed === 1 ? 'is' : 'are'} counted.${inThem ? ` ${inThem[0].toUpperCase()}${inThem.slice(1)} above ${one ? 'is' : 'are'} in ${sk.mixed === 1 ? 'that file' : 'those files'}, so ${one ? `it may be on ${aKitName(sk.name)} component` : `some may be on ${esc(sk.name)} components`}.` : ''}` : '',
+    "Follow the kit the file already uses. Never put one kit's styling on the other's components.",
+  ].filter(Boolean);
+  return `<div class="receipts">${eyebrow(`Two kits · ${esc(sk.name)} in ${n(sk.files)} files`)}<p class="sub">${parts.join(' ')}</p></div>`;
 }
 
 // A kit product: the theme, how often components read it, and where a colour
@@ -1501,6 +1729,7 @@ function kitSection() {
   const parts = [`<div class="receipts">${eyebrow(k.themeFiles.length ? `Theme in ${esc(k.themeFiles[0])}${k.themeFiles.length > 1 ? ` and ${n(k.themeFiles.length - 1)} more` : ''} · read ${n(k.refs)} times from components` : `No theme of its own · the ${esc(k.name)} defaults`)}<p class="sub">${k.themeFiles.length ? `Components reach the theme ${n(k.refsPer100)} times per 100 kit files, through ${KITS[k.name]?.advice.refExamples ?? 'theme references'}. That is the system working.` : `Without a theme of its own, every colour a component needs is either ${esc(k.name)}'s default or written by hand.`}</p></div>`];
   parts.push(`<div class="receipts">${eyebrow(`${n(k.colour.uses)} colours written on components · ${n(k.colour.per100)} per 100 kit files`)}${k.colour.uses ? `<div class="chips-row">${chips(k.colour.samples, 'bad')}</div><div class="chips-row">${files(k.colour.top)}</div>` : '<p class="sub">Every colour on a component comes from the theme.</p>'}${whyToggle('kitColour')}</div>`);
   parts.push(`<div class="receipts">${eyebrow(`${n(k.px.uses)} pixel sizes written on components · ${n(k.px.per100)} per 100 kit files`)}${k.px.uses ? `<div class="chips-row">${chips(k.px.samples, 'warn')}</div><div class="chips-row">${files(k.px.top)}</div>` : '<p class="sub">Spacing, type size and radius on components come from the theme.</p>'}${whyToggle('kitPx')}</div>`);
+  if (k.second) parts.push(secondKitBlock(k));
   if (k.exempt?.length) parts.push(`<p class="sub">Not counted: ${n(k.exempt.length)} file${k.exempt.length === 1 ? '' : 's'} of colour data or artwork (${esc(k.exempt.slice(0, 3).map((e) => basename(e.file)).join(', '))}).</p>`);
   return `<section class="glass pad">${sectionHead(`Your ${esc(k.name)} theme, and what is written around it`, 'the theme, and the places a colour or a pixel size was written onto a component instead')}${parts.join('')}</section>`;
 }
@@ -1659,7 +1888,8 @@ function exceptionsBlock() {
       const vd = r.variantsDropped ?? [];
       if (vd.length) lines.push(`${vd.length} variant${vd.length === 1 ? '' : 's'} of the same components (${vd.map((e) => esc(basename(dirname(e.dir)) === 'bases' ? basename(dirname(e.dir)) + '/' + basename(e.dir) : e.dir)).join(', ')}, ${n(vd.reduce((a, e) => a + e.files, 0))} files) counted once, through the variant the registry file names.`);
     }
-    if (vendoredUi && neverImported.length) lines.push(`${n(neverImported.length)} catalogue component${neverImported.length === 1 ? '' : 's'} not used yet: stock on the shelf, not scored.`);
+    if (vendoredUi && neverStock.length) lines.push(`${n(neverStock.length)} shadcn component${neverStock.length === 1 ? ' is' : 's are'} installed but not used yet. ${neverStock.length === 1 ? 'It is' : 'They are'} not scored.`);
+    if (vendoredUi && neverOwn.length) lines.push(`${n(neverOwn.length)} component${neverOwn.length === 1 ? '' : 's'} the team wrote in the same folder ${neverOwn.length === 1 ? 'is' : 'are'} not imported either. ${neverOwn.length === 1 ? 'It is' : 'They are'} listed under the adoption map and ${neverOwn.length === 1 ? 'is' : 'are'} not scored.`);
     const rp = P.shadcn?.registryPaint;
     if (rp) lines.push(`Installed registr${rp.dirs.length === 1 ? 'y' : 'ies'} ${esc(rp.dirs.map((d) => basename(d)).join(', '))}: ${n(rp.files)} file${rp.files === 1 ? '' : 's'}${rp.tinUses ? `, ${n(rp.tinUses)} palette colour${rp.tinUses === 1 ? '' : 's'}` : ''}. Kept in the score, left out of the fixes. Your agent reads them like everything else.`);
   } else if (isLibrary) {
@@ -1905,6 +2135,7 @@ ${ogTags()}
 
   /* palette */
   .palette-grid { display:grid; grid-template-columns:1fr 1.6fr; gap:16px; }
+  .palette-grid > * { min-width:0; }
   @media (max-width:860px) { .palette-grid { grid-template-columns:1fr; } }
   .pal-hero { position:relative; overflow:hidden; padding:26px 28px; }
   .pal-hero .b1 { right:-40px; top:-40px; width:160px; height:160px; background:var(--blob); filter:blur(32px); }
@@ -1924,8 +2155,13 @@ ${ogTags()}
   .lg-tok { background:var(--text); } .lg-stray { background:var(--coral); }
   .usage-bar { display:flex; height:96px; gap:2px; margin-top:18px; border-radius:16px; overflow:hidden; }
   .uc { position:relative; min-width:3px; box-shadow:0 0 0 1px var(--cell-ring) inset; }
+  .usage-bar .uc { min-width:2px; }
   .uc:first-child { border-radius:16px 0 0 16px; } .uc:last-child { border-radius:0 16px 16px 0; }
-  .uc.stray i { position:absolute; top:4px; right:4px; width:6px; height:6px; border-radius:99px; background:var(--coral); box-shadow:0 0 0 2px var(--card-solid); }
+  .uc.stray i, .uc.pal i { position:absolute; top:4px; right:4px; width:6px; height:6px; border-radius:99px; background:var(--coral); box-shadow:0 0 0 2px var(--card-solid); }
+  .uc.pal i { background:var(--dim); }
+  .uc.named { background:radial-gradient(var(--dim2) 1.2px, transparent 1.8px) 0 0/7px 7px, var(--deep); }
+  .lg-pal { background:var(--dim); } .lg-named { background:radial-gradient(var(--dim) 1px, transparent 1.4px) 0 0/4px 4px, var(--deep); }
+  .use-line { margin-top:12px; }
   .uc-rest { background:repeating-linear-gradient(45deg,var(--deep),var(--deep) 4px,var(--card-solid) 4px,var(--card-solid) 8px);
     display:flex; align-items:center; justify-content:center; font:600 10px var(--mono); color:var(--dim); }
   .ramp-head { margin-top:26px; }
@@ -2320,7 +2556,9 @@ if (summaryPath) {
     role: P.role,
     kind: P.kind,
     ...(P.publishesRegistry ? { publishesRegistry: { source: P.publishesRegistry.source, publishes: P.publishesRegistry.publishes } } : {}),
-    ...(P.isKit && P.kit ? { kit: { name: P.kit.name, kitFiles: P.kit.kitFiles, themeFiles: P.kit.themeFiles, spacingUnit: P.kit.spacingUnit ?? null, refs: P.kit.refs, colours: P.kit.colour.uses, pixelSizes: P.kit.px.uses, evidence: P.evidence } } : {}),
+    ...(P.isKit && P.kit ? { kit: { name: P.kit.name, kitFiles: P.kit.kitFiles, themeFiles: P.kit.themeFiles, spacingUnit: P.kit.spacingUnit ?? null, refs: P.kit.refs, colours: P.kit.colour.uses, pixelSizes: P.kit.px.uses, evidence: P.evidence,
+      // a second kit, named and not scored (9.7.0); absent when there is none
+      ...(P.kit.second ? { second: { name: P.kit.second.name, pkg: P.kit.second.pkg, files: P.kit.second.files, withoutFirst: P.kit.second.withoutFirst, mixed: P.kit.second.mixed } } : {}) } } : {}),
     ...(P.isTailwind && P.tailwind ? { tailwind: { file: P.tailwind.file, names: P.tailwind.names.length, restated: P.tailwind.restated, retuned: P.tailwind.retuned?.length ?? 0, uses: P.tailwind.uses, usedIn: P.tailwind.usedIn, adopted: P.tailwind.adopted, evidence: P.evidence } } : {}),
     ...(P.isRegistry && P.registry ? { registry: { source: P.registry.source, builtFrom: P.registry.builtFrom, items: P.registry.items, publishes: P.registry.publishes, variants: P.registry.variants, counted: P.registry.counted ?? null, showcase: P.registry.showcase ?? [], variantsDropped: P.registry.variantsDropped ?? [], themes: P.registry.themes ? { total: P.registry.themes.total, incomplete: P.registry.themes.incomplete } : null } } : {}),
     ...(P.isShadcn && P.shadcn ? { shadcn: { confidence: P.confidence, evidence: P.evidence, style: P.shadcn.kit?.style ?? null, baseColor: P.shadcn.kit?.baseColor ?? null, tailwind: P.shadcn.kit?.tailwind ?? null, catalogues: P.uiDirs, registries: P.shadcn.registryDirs ?? [], ...(P.shadcn.registryPaint ? { registryFiles: P.shadcn.registryPaint.files, registryPaletteColours: P.shadcn.registryPaint.tinUses } : {}), ownFiles: P.shadcn.paint?.ownFiles ?? null, fresh: P.shadcn.fresh?.fresh === true, ...(P.shadcn.lint ? { lint: { file: P.shadcn.lint.file, kind: P.shadcn.lint.kind, rulesOn: lintRulesOn(P.shadcn.lint), readFully: P.shadcn.lint.readFully } } : {}) } } : {}),