roast-my-design-system 5.6.2 → 5.7.0

package/README.md

@@ -8,11 +8,9 @@
 
 A free CLI tool (and Claude Code skill) that roasts your repo's design system with real data, then generates the rules that keep your AI agent on-system.
 
-> **New in 5.6: every fix comes with its prompt.** Each move in the report's Where to start now carries a copy button holding a ready-made fix prompt: the finding, the file paths, the expected score payoff, and the calm rules for fixing without steamrolling craft. Paste it into your agent, fix, re-run the scan, press the next button. View it first if you like: the prompt unfolds right in the report.
-
-> **New in 5.5: the adoption map.** The report now draws your real system to scale: a treemap where every adopted component's tile area is its import count, and the never-imported are grouped by the year git last saw them touched. The cupboard audit, with dates on the boxes.
+> **New in 5.7: it reads web components, and it admits what it cannot read.** Stencil, Lit and plain custom elements are detected by their tag registrations (validated on telekom/scale, Shoelace, Ionic, Material Web, Adobe Spectrum, Siemens iX, Baloise and Lion); component libraries get composition maps and library language instead of adoption accusations; an earned token namespace like `--telekom-*` is named in the header. And when a repo's component pattern is beyond the scan, the tiles say "not measured" and the score takes no credit, because zeros the scanner never earned are not discipline.
 
-> **New in 5.4: the MCP server is verified in Cursor and Windsurf (now Devin Desktop), alongside Claude Code.** Each tested end to end in the editor itself: server connected, five tools listed, real answers in the chat. Setup for each lives in [Live answers over MCP](#live-answers-over-mcp).
+> **New in 5.6: every fix comes with its prompt.** Each move in the report's Where to start now carries a copy button holding a ready-made fix prompt: the finding, the file paths, the expected score payoff, and the calm rules for fixing without steamrolling craft. Paste it into your agent, fix, re-run the scan, press the next button. View it first if you like: the prompt unfolds right in the report.
 
 > **New in 5.0: it runs as a local MCP server.** One command, and your agent asks the design system before writing UI, then gets the work checked after: which Button is canonical, which token holds that colour, review my changes. Local, deterministic, nothing leaves your machine. See [Live answers over MCP](#live-answers-over-mcp).
 
@@ -20,6 +18,7 @@ Run it on your codebase and get, in about a second:
 
 - **A health score you can defend in a meeting.** 0-100, deterministic, benchmarked against Ideal Design System norms, 34 scanned public repos and 10 reputable design systems (Primer, Polaris, Carbon, shadcn/ui…).
 - **Per-package scores for monorepos.** One blended number hides which package is the problem: `packages/ui` scores 80 while `apps/web` scores 40, and now you can see it.
+- **Reads React and web components alike.** Stencil, Lit and custom elements detected by tag registration, counted by kebab tag; libraries get composition maps, not adoption accusations; earned token namespaces named in the header; and anything the scan cannot read is declared "not measured" instead of scored.
 - **The receipts behind it.** Every colour and its near-identical twin, every spacing value, typeface, duplicated or never-imported component, inline style and !important, with real file paths, in one self-contained HTML report you can open, Slack or email.
 - **The first fixes ranked by payoff, each with its prompt.** A "Where to start" list derived from your own numbers, and every move carries a copy button with a ready-made fix prompt for your agent: the finding, the files, the expected payoff, and rules that respect deliberate craft. Fix, re-run the scan, press the next button.
 - **Rules that stop the mess coming back.** A generated `design-system-rules.md` with canonical components, your token file, and known duplicates to avoid, so your AI agent follows your system instead of guessing at it. `--apply` injects them into every agent file you have: Claude, Cursor, GitHub Copilot, and Windsurf. Every scan also checks the rules you already have for stale references: paths that no longer exist, components named canonical that nothing imports anymore.
@@ -61,7 +60,7 @@ One scan powers all of it; the flags decide what lands on disk. Combine freely.
 
 The full report for vercel/ai-chatbot, top to bottom — including "What the numbers mean", Claude's read of the scan, embedded right under the verdict:
 
-![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, the What the numbers mean analysis written by Claude, priced Where to start moves each with its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, three-yardstick tiles, the adoption map treemap, palette forensics, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-full-dark.png?v=5.6.1)
+![The full diagnosis report for vercel/ai-chatbot in dark mode: health score, the What the numbers mean analysis written by Claude, priced Where to start moves each with its copy-the-fix-prompt button, the wrapped present with the agent rules, an agent trap callout, three-yardstick tiles, the adoption map treemap, palette forensics, spacing receipts, typography specimens, offenders, duplicates, and the component usage ledger](https://raw.githubusercontent.com/gregkozakiewicz/roast-my-design-system/main/assets/report-full-dark.png?v=5.7.0)
 
 The same report in light mode (one file, built-in toggle):
 
@@ -73,6 +72,7 @@ The same report in light mode (one file, built-in toggle):
 - **Read-only.** Nothing in your repo is modified. The only outputs are a temp JSON and the HTML report.
 - **No network, no telemetry.** Everything runs locally. Nothing about your code leaves your machine.
 - **Zero dependencies, enforced by the test suite.** The package installs nothing but itself, and that is a tested promise rather than a habit: the suite fails if package.json ever declares a dependency, and the exact file list npm ships is a photographed contract, so nothing can stow away in a release.
+- **Honest gaps.** When a repo's components register in a pattern the scan cannot read, the component tiles say "not measured" and drop out of the score. A zero the scanner never earned is presented as blindness, not discipline.
 - **Honest exclusions.** Test files, Storybook stories, docs sites, example apps, SVG artwork, and email templates (which *must* inline styles) are excluded, so you can't discredit the numbers on a technicality. Your own exclusions (`.roastignore`, `--exclude`) are printed in the report header with file counts, so a scoped scan can never pass itself off as the whole repo.
 - **Intent-aware counting (v3).** Runtime-computed inline styles, compound-component APIs and wrapper components are not crimes and are not counted as ones. Token-led repos are judged on their hardcoded strays, not their token architecture. Repeated arbitrary values are read as decisions without names, not drift.
 - **A real benchmark.** The "Avg Design System" yardstick comes from scanning 34 public React repos (cal.com, excalidraw, supabase, grafana, twenty, dub, langfuse…). Median: 130 colours, 17 greys, 20 duplicated components, 49 inline style blocks, 70 arbitrary Tailwind values.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "roast-my-design-system",
-  "version": "5.6.2",
+  "version": "5.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 34 public repos, 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.",
+  "description": "Your AI can write the UI. This makes sure it writes your UI. A deterministic scanner scores your design system 0-100 against 34 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": [
     "design-system",
     "mcp",
@@ -19,7 +19,11 @@
     "linter",
     "code-quality",
     "cursor",
-    "windsurf"
+    "windsurf",
+    "web-components",
+    "stencil",
+    "lit",
+    "devin"
   ],
   "homepage": "https://gregkozakiewicz.github.io/roast-my-design-system/",
   "bugs": "https://github.com/gregkozakiewicz/roast-my-design-system/issues",

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

@@ -228,6 +228,15 @@ const nearPairs = nearColorPairs(colors);
 
 const neverImported = neverImportedComponents(h.components, h.profile?.uiDir);
 
+// Measurability and role, decided by the harvest (telekom/scale, 2026-09-01):
+// when the component detector could not read this repo's stack, the component
+// metrics say so and take no score credit; when the repo is a published
+// library, usage means composition (how the system uses itself), never
+// adoption, and every accusation about orphans is softened to match.
+const componentsMeasured = h.profile?.componentDetection?.measured !== false;
+const notMeasuredReason = h.profile?.componentDetection?.reason ?? 'an unrecognised component pattern';
+const isLibrary = h.profile?.role === 'library';
+
 // Benchmark helpers: for a metric value, where does this repo sit among the
 // scanned fleet? ("more colours than 90% of scanned repos")
 function percentile(metric, value) {
@@ -283,8 +292,8 @@ if (effGreys > 13 * 1.25) candidates.push({ ratio: effGreys / 13, text: tokenLed
 if (spacingTotal > 15) candidates.push({ ratio: spacingTotal / 12, text: `${spacingTotal} off-scale spacing values where a dozen would do` });
 if (nearPairs.length >= 3) candidates.push({ ratio: 1 + nearPairs.length / 6, text: `${nearPairs.length} colour pairs are nearly identical (${nearPairs[0].a.value} next to ${nearPairs[0].b.value}), copy-paste, not decisions` });
 if (important.count >= 10) candidates.push({ ratio: 1 + important.count / 30, text: `${n(important.count)} !important declarations, the cascade admitting defeat` });
-if (iconCollisions.length >= 5) candidates.push({ ratio: 1 + iconCollisions.length / 8, text: `two icon sets collide on ${iconCollisions.length} names` });
-if (hardDupes.length > 0) candidates.push({ ratio: 1 + hardDupes.length / 5, text: `${hardDupes.length} component${hardDupes.length > 1 ? 's' : ''} implemented more than once, so an agent asked for a Button has several random options` });
+if (componentsMeasured && iconCollisions.length >= 5) candidates.push({ ratio: 1 + iconCollisions.length / 8, text: `two icon sets collide on ${iconCollisions.length} names` });
+if (componentsMeasured && hardDupes.length > 0) candidates.push({ ratio: 1 + hardDupes.length / 5, text: `${hardDupes.length} component${hardDupes.length > 1 ? 's' : ''} implemented more than once, so an agent asked for a Button has several random options` });
 if (inline.count > 20) candidates.push({ ratio: inline.count / 20, text: `${n(inline.count)} inline style blocks bypassing every system, and teaching your agent to do the same` });
 if (arbitraryCount >= 20) candidates.push({ ratio: arbitraryCount / 30, text: `${n(arbitraryCount)} arbitrary values like ${arbitrary[0].value} punched through the Tailwind scale, each one a precedent your agent will follow` });
 if (agentFiles.length === 0) candidates.push({ ratio: 1.3, text: `no agent rules, so your AI is guessing` });
@@ -339,6 +348,7 @@ const ICONS = {
   warn: '<svg class="ic ic-warn" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10"/><line x1="12" y1="8" x2="12" y2="12"/><line x1="12" y1="16" x2="12" y2="16.01"/></svg>',
   bad: '<svg class="ic ic-bad" viewBox="0 0 24 24"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>',
   info: '',
+  na: '<svg class="ic ic-na" viewBox="0 0 24 24"><line x1="7" y1="12" x2="17" y2="12"/></svg>',
 };
 
 // Feather "activity", the pulse line, points reversed so it traces left to
@@ -380,6 +390,21 @@ const bigStats = [
   tile(arbitraryCount, 'arbitrary bracket values', 'arbitrary', 'a handful of deliberate exceptions'),
 ];
 
+// Component metrics the detector could not measure render as such and drop
+// out of the score ('na' is not a scored health); a library's never-imported
+// count stays visible but unscored, with the reason on the tile.
+if (!componentsMeasured) {
+  for (const m of ['exactDuplicates', 'neverImported']) {
+    const i = bigStats.findIndex((st) => st.metric === m);
+    bigStats[i] = { num: '—', label: bigStats[i].label, health: 'na', metric: m, healthValue: null,
+      rows: [{ label: `not measured: ${notMeasuredReason}`, val: '', dir: '' }] };
+  }
+} else if (isLibrary) {
+  const t = bigStats.find((st) => st.metric === 'neverImported');
+  t.health = 'info';
+  t.rows.push({ label: 'library: internal use only, downstream consumers invisible', val: '', dir: '' });
+}
+
 // Health score for the hero: the scored tiles averaged (good 100 / warn 55 / bad 10).
 const SCORE_OF = { good: 100, warn: 55, bad: 10 };
 const scoredTiles = bigStats.filter((s) => s.health in SCORE_OF);
@@ -500,6 +525,7 @@ function trapBox(text) {
   return `<div class="trap">${ICONS.warn}<span><b>Agent trap.</b> ${text}</span></div>`;
 }
 function dupesTrap() {
+  if (!componentsMeasured) return '';
   const hard = exactDupes.filter((d) => !d.wrapped);
   if (hard.length < 2) return '';
   const top = hard[0];
@@ -530,6 +556,7 @@ function importantTrap() {
   return trapBox(`${n(important.count)} !important declarations, and each one is a shouting match a previous developer decided to win by force. An agent whose style will not apply does what the repo taught it and shouts louder. The volume in this codebase only goes up.`);
 }
 function orphansTrap() {
+  if (!componentsMeasured || isLibrary) return '';
   if (neverImported.length < 10) return '';
   return trapBox(`${neverImported.length} components are never imported anywhere. An agent searching for a Button finds the abandoned ones alongside the canonical one with nothing to tell them apart, so yesterday's dead end becomes today's example.`);
 }
@@ -780,6 +807,14 @@ function orphanRows() {
 }
 
 function componentsSection() {
+  // The wing the inspector could not enter gets named, never skipped: a
+  // missing section claims "nothing worth mapping", which is a different
+  // claim from "I could not see them".
+  if (!componentsMeasured) {
+    return `<section class="glass pad">
+    ${sectionHead('The component ledger', 'not measured in this repo')}
+    <p class="sub">Components here are built as ${esc(notMeasuredReason)}, a pattern this scan cannot read yet. Nothing on this page makes claims about component count, duplication, usage or adoption, and the score takes no credit for those tiles. Everything measured from stylesheets stands unaffected: colours, spacing, typography, !important.</p></section>`;
+  }
   const adopted = reusable.filter((c) => c.usageCount > 0);
   const top = adopted.slice(0, 10);
   if (!top.length && neverImported.length < 2) return '';
@@ -793,13 +828,13 @@ function componentsSection() {
     <td class="path">${esc(c.file)}</td>
     <td>${c.propsHint?.named?.length ? c.propsHint.named.slice(0, 5).map((p) => `<span class="chip chip-xs">${esc(p)}</span>`).join(' ') : '<span class="dim">none</span>'}</td></tr>`).join('');
   return `<section class="glass pad">
-    ${sectionHead('The adoption map', `${n(reusable.length)} components defined · tile area is import count · the real system, drawn to scale`)}
+    ${sectionHead(isLibrary ? 'The composition map' : 'The adoption map', `${n(reusable.length)} components defined · tile area is ${isLibrary ? 'internal use: how the system builds from itself, downstream consumers invisible from here' : 'import count'} · the real system, drawn to scale`)}
     ${mapped}
     ${overflow > 0 ? `<p class="sub">${overflow} more adopted component${overflow === 1 ? '' : 's'} below the top 24, not drawn.</p>` : ''}
     ${onceUsed.length ? `<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(`${n(neverImported.length)} components defined but never imported · they sit in the system as wrong answers waiting to be picked`)}
+    <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 · they sit in the system as wrong answers waiting to be picked`)}
     ${orphanRows()}
     <p class="sub" style="margin-top:8px">Routers, dynamic imports and barrel files can hide real usage, so treat this as a shortlist to check, not a demolition order.</p>` : ''}</section>`;
 }
@@ -900,7 +935,7 @@ function whereToStartSection() {
   const c = [];
   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) {
+  if (componentsMeasured && hardDupes.length > 0) {
     // Pick the pair with the strongest copy-paste evidence: sibling files in
     // app code (same basename, neither in a shared package) are true
     // duplicates; a library-vs-app pair may be an intentional override, and
@@ -918,7 +953,7 @@ function whereToStartSection() {
       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, metric: null, title: 'Merge the two icon sets',
+  if (componentsMeasured && 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) {
@@ -978,7 +1013,7 @@ function whereToStartSection() {
       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) {
+  if (componentsMeasured && !isLibrary && 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.` });
@@ -1129,13 +1164,33 @@ function agentSection() {
 }
 
 // ---------- page ----------
+// One chip owns the design-system slot, and bigger titles are earned, not
+// assumed (Greg's rule, 2026-09-01): a recognised library by name; a token
+// NAMESPACE upgrades to "custom design system (--brand-*)" because
+// components-plus-tokens is the system definition this tool preaches; a
+// library with tokens but no namespace gets the plain title; a tokenless
+// library stays "component library"; a product repo we cannot read gets the
+// quiet unrecognised chip, because not knowing IS a finding here.
+const ns = h.tokens.namespaces ?? null;
+const dsChip =
+  ds.kind === 'shadcn' ? 'shadcn/ui'
+  : ds.kind === 'library' ? ds.name
+  : ns ? `custom design system (--${ns.primary}-*${ns.partner ? ` + --${ns.partner}-*` : ''})`
+  // A tokenFile alone is a technicality (Lion's is one drawer style file);
+  // the plain title needs a token LAYER: ten defined colour tokens.
+  : isLibrary && h.tokens.tokenFile && (h.tokens.colors ?? []).filter((c) => c.isToken).length >= 10 ? 'custom design system'
+  : isLibrary ? 'component library'
+  : ds.name === 'CSS tokens' ? 'CSS tokens'
+  : null;
 const stack = [
   h.profile.framework !== 'unknown' ? h.profile.framework : null,
   h.profile.typescript ? 'TypeScript' : null,
   ...(h.profile.stylingDeps ?? []),
-  ds.kind === 'shadcn' ? 'shadcn/ui' : ds.kind === 'library' ? ds.name : null,
+  dsChip,
   h.profile.monorepo ? 'monorepo' : null,
 ].filter(Boolean);
+const dsUnrecognised = !dsChip && !noSystemLikely;
+const legacyChip = ns?.others?.length ? `also present: ${ns.others.map((l) => `--${l}-*`).join(', ')}` : null;
 
 // User exclusions are printed in the header, never hidden: a scoped scan must
 // say it is scoped, or the score could be quietly gamed. Grouped by source
@@ -1364,6 +1419,9 @@ const html = `<!doctype html>
     border-radius:99px; padding:2px 10px; }
   .vchip.bad { color:var(--coral); border-color:var(--coral-soft); background:var(--coral-soft); }
   .vchip.dim { color:var(--dim2); }
+  .chip-dim { opacity:.6; font-style:italic; }
+  .st-na .num { color:var(--dim2); }
+  .ic-na { stroke:var(--dim2); }
   .amap { width:100%; height:auto; display:block; margin:10px 0 4px; }
   .atile { fill:var(--ok-soft); stroke:var(--bg, #0f172a); stroke-width:2; }
   .orow { display:flex; align-items:baseline; gap:12px; margin-top:8px; }
@@ -1511,7 +1569,7 @@ const html = `<!doctype html>
     </div>
     ${healthScore !== null ? `<div class="score${noSystemLikely ? ' muted' : ''}">${eyebrow('Health score')}<div class="val">${healthScore}<span class="slash">/</span><span class="of">100</span></div>${noSystemLikely ? '<div class="note">little here to score · see the note below</div>' : ''}</div>` : ''}
   </div>
-  <div class="chips">${stack.map((s) => `<span class="chip">${esc(s)}</span>`).join('')}${agentFiles.map((c) => `<span class="chip chip-agent">${esc(c.file)}</span>`).join('')}</div>
+  <div class="chips">${stack.map((s) => `<span class="chip">${esc(s)}</span>`).join('')}${dsUnrecognised ? '<span class="chip chip-dim">design system: unrecognised</span>' : ''}${legacyChip ? `<span class="chip chip-dim">${esc(legacyChip)}</span>` : ''}${agentFiles.map((c) => `<span class="chip chip-agent">${esc(c.file)}</span>`).join('')}</div>
   ${exclusionsLine()}
   ${noSystemLikely ? `<div class="nods">${ICONS.warn}<span>There is most likely <b>no design system in this repo</b>: almost no colour or spacing values were found. Styling may live outside this codebase (CDN stylesheets, a parent repo, or generated output).</span></div>` : ''}
   <div class="glass verdict-card">
@@ -1645,6 +1703,8 @@ if (summaryPath) {
     score: healthScore,
     noSystemLikely,
     verdict,
+    role: h.profile?.role ?? 'product',
+    componentsMeasured,
     tiles: bigStats.map((s) => ({ label: s.label, value: s.num, health: s.health })),
     ...(startMoves.length ? { moves: startMoves } : {}),
     packages: (h.packages ?? []).filter((p) => p.scored && p.metrics)

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

@@ -122,6 +122,31 @@ export function definedComponents(src) {
 
 const looksLikeJSXFile = (src) => /<[A-Za-z][\w.]*[\s/>]/.test(src);
 
+// ---------- web components: the tag-registered world ----------
+// Stencil, Lit and raw customElements.define register components by TAG, and
+// pages consume them as <kebab-tags> — invisible to the JSX pass, which is
+// how 93 Telekom components once scanned as one (telekom/scale, 2026-09-01).
+// Generated framework wrappers (Stencil's react/vue/angular output targets)
+// are skipped for definitions AND usage, or every component would gain
+// phantom adoption from its own machine-made bindings.
+const GENERATED_RE = /(@stencil\/(?:react|vue|angular)-output-target|output-target|auto-?generated|generated file|do not edit)/i;
+const TAG_RE = String.raw`([a-z][\w]*(?:-[\w]+)+)`;
+export function webComponentDefs(src) {
+  const defs = [];
+  const classAfter = (idx) => src.slice(idx).match(/(?:export\s+)?class\s+([A-Za-z]\w*)/)?.[1];
+  for (const m of src.matchAll(new RegExp(String.raw`@Component\(\s*\{[^{}]*?tag\s*:\s*['"]${TAG_RE}['"]`, 'g')))
+    defs.push({ name: classAfter(m.index) ?? m[1], tag: m[1] });
+  for (const m of src.matchAll(new RegExp(String.raw`@customElement\(\s*['"]${TAG_RE}['"]\s*\)\s*(?:export\s+)?class\s+([A-Za-z]\w*)`, 'g')))
+    defs.push({ name: m[2], tag: m[1] });
+  for (const m of src.matchAll(new RegExp(String.raw`customElements\.define\(\s*['"]${TAG_RE}['"]\s*,\s*([A-Za-z]\w*)`, 'g')))
+    defs.push({ name: m[2], tag: m[1] });
+  // Shoelace-style static registration: SlButton.define('sl-button')
+  for (const m of src.matchAll(new RegExp(String.raw`\b([A-Z]\w*)\.define\(\s*['"]${TAG_RE}['"]`, 'g')))
+    defs.push({ name: m[1], tag: m[2] });
+  const seen = new Set();
+  return defs.filter((d) => !seen.has(d.tag) && seen.add(d.tag));
+}
+
 /** Count real `<Name` tag usages of `name` in `src` (tag boundary checked). */
 function countUsages(src, name) {
   let count = 0, from = 0, open;
@@ -186,6 +211,34 @@ export function harvestComponents(root, codeFiles) {
     }
   }
 
+  // Web-component pass: definitions by tag registration (any code file, JSX
+  // or not — Lit lives in plain .ts), usage counted as the kebab tag across
+  // every non-generated source.
+  const wcSources = new Map();
+  for (const f of codeFiles.filter((x) => /\.(tsx|jsx|ts|js|mjs)$/.test(x))) {
+    let src = sources.get(f);
+    if (src === undefined) { try { src = readFileSync(join(root, f), 'utf8'); } catch { continue; } }
+    if (GENERATED_RE.test(src.slice(0, 2000))) continue;
+    wcSources.set(f, src);
+  }
+  const wcComponents = [];
+  for (const [file, src] of wcSources) {
+    for (const def of webComponentDefs(src)) {
+      wcComponents.push({ name: def.name, tag: def.tag, file, isPage: false,
+        variants: extractVariants(src), propsHint: null, usageCount: 0, usedIn: [] });
+    }
+  }
+  for (const [file, src] of wcSources) {
+    for (const def of wcComponents) {
+      if (def.file === file) continue;
+      const u = countUsages(src, def.tag);
+      if (!u) continue;
+      def.usageCount += u;
+      if (def.usedIn.length < 8) def.usedIn.push(file);
+    }
+  }
+  components.push(...wcComponents);
+
   components.sort((a, b) => b.usageCount - a.usageCount || a.name.localeCompare(b.name));
 
   // Pass 3: golden examples — for the most-used components, quote the repo's

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

@@ -62,6 +62,38 @@ const staleRules = ruleStaleness(target, components,
   new Set(neverImportedComponents(components, profile.uiDir).map((c) => c.name)),
   [...files.code, ...files.styles, ...files.other]);
 
+// Repo role and measurability, decided from what the scan actually found.
+// A published components package with no app pages is a LIBRARY: its real
+// consumers live in other repos, so usage counts mean composition, not
+// adoption, and the report's language follows. And when a component stack
+// the detector cannot read is present while it found almost nothing, the
+// component metrics are declared NOT MEASURED instead of scoring zeros as
+// discipline (the telekom/scale lesson, 2026-09-01).
+{
+  const reusableCount = components.filter((c) => !c.isPage).length;
+  // A web-components repo with many tag-registered components and no pages
+  // is a library by construction, whatever its packages are named (Ionic's
+  // @ionic/core and Material Web both dodge the name rule).
+  // A handful of pages next to hundreds of components is a demo or test app
+  // riding in the library's monorepo (Siemens iX ships two), not a product.
+  const pageCount = components.length - reusableCount;
+  const fewPages = pageCount <= reusableCount * 0.05;
+  profile.role = (profile.libraryPkg && fewPages && reusableCount >= 5)
+    || (String(profile.framework).startsWith('web components') && fewPages && reusableCount >= 10)
+    ? 'library' : 'product';
+  // The gate fires on the situation, never a list of known frameworks: a
+  // repo with real code volume where the detector found almost nothing is a
+  // repo we could not read, whatever it is written in (the Shoelace lesson:
+  // its .define() idiom was invisible and the named-framework gate stayed
+  // silent, which would have shipped blind zeros as discipline again).
+  // Either trigger suffices: a named unreadable stack (Vue/Angular/Svelte
+  // markers, however small the repo), or sheer volume the detector saw
+  // nothing in (the Shoelace near-miss: unknown idiom, no marker).
+  profile.componentDetection = reusableCount < 3 && (profile.unreadableComponentStack || files.code.length >= 40)
+    ? { measured: false, reason: profile.unreadableComponentStack ?? 'a component pattern this scan cannot read' }
+    : { measured: true };
+}
+
 // Orphans carry a receipt: the last time git saw anyone touch the file.
 // Only never-imported components are dated (the adoption map's evidence);
 // outside a git repo the field is simply absent and no claim is made.

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

@@ -32,7 +32,12 @@ class Tally {
 
 // ---------- colour parsing ----------
 const HEX_RE = /#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})\b/g;
-const FUNC_COLOR_RE = /\b(?:rgba?|hsla?|oklch|oklab|lab|lch|color)\(\s*[^)]{1,80}\)/g;
+const FUNC_COLOR_RE = /\b(?:rgba?|hsla?|oklch|oklab|lab|lch)\(\s*[^)]{1,80}\)|\bcolor\(\s*(?:from|srgb|srgb-linear|display-p3|a98-rgb|prophoto-rgb|rec2020|xyz(?:-d(?:50|65))?)\b[^)]{0,80}\)/g;
+
+/** Fully transparent values are the CSS word for "nothing here" — counting
+ * rgba(0,0,0,0) as a palette colour 581 times (Siemens iX) inflates every
+ * colour metric with non-decisions. */
+export const isTransparent = (v) => /^(?:rgba|hsla)\(\s*[\d.,%\s]+,\s*0(?:\.0+)?\s*\)$/.test(v) || /\/\s*0(?:\.0+)?\s*\)$/.test(v);
 
 /** normalize: lowercase; expand #abc → #aabbcc so duplicates merge. */
 export function normalizeHex(hex) {
@@ -197,17 +202,28 @@ export function harvestTokens(root, styleFiles, codeFiles) {
   // hinges on this split.
   const tokenDefined = new Set();
   const tokenDefsPerFile = new Map();
+  const nsDefs = new Map();  // --telekom-x: value  → 'telekom' (definitions)
+  const nsRefs = new Map();  // var(--telekom-x)    → 'telekom' (references)
 
   const scanCssText = (text, file) => {
     const imp = (text.match(/!\s*important/gi) ?? []).length;
     if (imp) importantFiles.set(file, (importantFiles.get(file) ?? 0) + imp);
-    for (const m of text.matchAll(/--[\w-]+\s*:\s*([^;{}]+)[;}]/g)) {
+    for (const m of text.matchAll(/--([\w-]+)\s*:\s*([^;{}]+)[;}]/g)) {
       tokenDefsPerFile.set(file, (tokenDefsPerFile.get(file) ?? 0) + 1);
-      for (const c of m[1].matchAll(HEX_RE)) tokenDefined.add(normalizeHex(c[0]));
-      for (const c of m[1].matchAll(FUNC_COLOR_RE)) tokenDefined.add(c[0].replace(/\s+/g, ' ').toLowerCase());
+      const stem = m[1].split('-')[0].toLowerCase();
+      if (stem) nsDefs.set(stem, (nsDefs.get(stem) ?? 0) + 1);
+      for (const c of m[2].matchAll(HEX_RE)) tokenDefined.add(normalizeHex(c[0]));
+      for (const c of m[2].matchAll(FUNC_COLOR_RE)) tokenDefined.add(c[0].replace(/\s+/g, ' ').toLowerCase());
+    }
+    // References count too: a system whose tokens are defined in a package
+    // dependency still answers to its namespace in every var(--telekom-...)
+    // (telekom/scale defines few tokens in-repo but references hundreds).
+    for (const m of text.matchAll(/var\(\s*--([\w-]+)/g)) {
+      const stem = m[1].split('-')[0].toLowerCase();
+      if (stem) nsRefs.set(stem, (nsRefs.get(stem) ?? 0) + 1);
     }
     for (const m of text.matchAll(HEX_RE)) colors.add(normalizeHex(m[0]), file);
-    for (const m of text.matchAll(FUNC_COLOR_RE)) colors.add(m[0].replace(/\s+/g, ' ').toLowerCase(), file);
+    for (const m of text.matchAll(FUNC_COLOR_RE)) { const v = m[0].replace(/\s+/g, ' ').toLowerCase(); if (!isTransparent(v)) colors.add(v, file); }
     for (const m of text.matchAll(SPACING_PROPS)) {
       for (const len of (m[2].match(LENGTH_RE) ?? [])) spacing.add(len, file);
     }
@@ -215,8 +231,12 @@ export function harvestTokens(root, styleFiles, codeFiles) {
     for (const m of text.matchAll(FONTSIZE_PROPS)) fontSizes.add(m[1].trim(), file);
     for (const m of text.matchAll(FONTFAMILY_PROPS)) {
       const v = m[1].trim().replace(/\s+/g, ' ');
-      // var(--x) and inherit are disciplined token usage, not declarations
+      // var(--x) and inherit are disciplined token usage, not declarations —
+      // and so are Sass token references ($label-text-font, map.get($tokens,
+      // ...)), Material Web's whole idiom: 59 fake "typefaces" once counted
+      // where one Roboto lived behind tokens (caught 2026-09-02).
       if (/^(var\(--[\w-]+\)|inherit)$/i.test(v)) continue;
+      if (v.startsWith('$') || /\bmap[.-]get\b/.test(v)) continue;
       fontFamilies.add(v, file);
     }
     for (const m of text.matchAll(SHADOW_PROPS)) shadows.add(m[1].trim().replace(/\s+/g, ' '), file);
@@ -248,6 +268,24 @@ export function harvestTokens(root, styleFiles, codeFiles) {
     if (EXEMPT_RE.test(f)) continue;
     let src; try { src = readFileSync(join(root, f), 'utf8'); } catch { continue; }
 
+    // CSS-in-tagged-templates (Lit css``, styled-components css``) IS the
+    // stylesheet in those worlds: Shoelace keeps its entire component styling
+    // in .styles.ts files, and skipping them scored a mostly-unread repo 94
+    // (caught by Greg, 2026-09-02). Each block runs through the same CSS
+    // scanner as a stylesheet; interpolations are blanked first (dynamic
+    // values are not static styling); the block text is then removed from
+    // the raw-hex pass below so nothing is counted twice.
+    {
+      let cssBlocks = 0;
+      for (const m of src.matchAll(/(?:^|[\s=(,:])css\s*`([^`]*)`/gs)) {
+        const text = m[1].replace(/\$\{[^}]*\}/g, ' ');
+        if (text.length < 20) continue;
+        scanCssText(text, f);
+        cssBlocks++;
+      }
+      if (cssBlocks) src = src.replace(/(?:^|[\s=(,:])css\s*`([^`]*)`/gs, ' ');
+    }
+
     // A Tailwind config's colours ARE the token layer (the tailwind-native
     // equivalent of --var definitions). Its fontFamily block is the typeface
     // declaration for the whole app.
@@ -350,8 +388,53 @@ export function harvestTokens(root, styleFiles, codeFiles) {
 
   const tokenFile = [...tokenDefsPerFile.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
 
+  // Token namespace: the brand stem the repo's custom properties answer to
+  // (--telekom-*), named only when earned — enough definitions, a dominant
+  // share, not a generic category word. A second qualifying stem is the
+  // fossil of a migration, named as legacy. Below the bar: no claim.
+  const NS_GENERIC = new Set(['color', 'colors', 'colour', 'font', 'fonts', 'text', 'spacing', 'space',
+    'size', 'sizes', 'bg', 'background', 'border', 'shadow', 'shadows', 'radius', 'radii', 'grey', 'gray',
+    'theme', 'base', 'global', 'primary', 'secondary', 'brand', 'var', 'css', 'root', 'light', 'dark',
+    'transition', 'duration', 'animation', 'ease', 'focus', 'hover', 'active', 'disabled', 'gap', 'grid', 'index',
+    'container', 'content', 'item', 'label', 'icon', 'surface', 'outline', 'track', 'thumb', 'state', 'input',
+    'width', 'height', 'margin', 'padding', 'opacity', 'line', 'letter']);
+  let namespaces = null;
+  {
+    // The contest is namespace vs namespace, never namespace vs category
+    // words: --telekom-* competes with --scl-*, not with --color-*. Primary
+    // must carry a real share of all custom-property traffic AND clearly beat
+    // its nearest rival; every other qualifying rival is a legacy namespace,
+    // the fossil of a migration, named as such.
+    const nsAll = new Map();
+    for (const [st, c] of nsDefs) nsAll.set(st, c);
+    for (const [st, c] of nsRefs) nsAll.set(st, (nsAll.get(st) ?? 0) + c);
+    const total = [...nsAll.values()].reduce((a, b) => a + b, 0);
+    const candidates = [...nsAll.entries()]
+      .filter(([st, c]) => st.length >= 2 && !NS_GENERIC.has(st) && c >= 10 && c / total >= 0.05)
+      .sort((a, b) => b[1] - a[1]);
+    const [top, second] = candidates;
+    if (top && top[1] / total >= 0.25) {
+      // The machine names namespaces; it never judges them. "Legacy" failed
+      // the admission test across seven real systems (2026-09-02): scale's
+      // dead --scl-* and Baloise's live --mod-* tier share the exact same
+      // defs/refs shape, so no ratio can tell abandonment from architecture.
+      // Facts only: a co-equal partner joins the title; every other
+      // qualifying namespace is reported as present, verdict-free. The roast
+      // notes, which can read deprecation notices and docs, make the legacy
+      // call per repo — judgment stays where context lives.
+      if (!second || top[1] >= second[1] * 2) {
+        const others = candidates.slice(1).map(([st]) => st);
+        namespaces = { primary: top[0], count: top[1], totalRefs: total, ...(others.length ? { others } : {}) };
+      } else if (second[1] / total >= 0.15) {
+        const others = candidates.slice(2).map(([st]) => st);
+        namespaces = { primary: top[0], partner: second[0], count: top[1], totalRefs: total, ...(others.length ? { others } : {}) };
+      }
+    }
+  }
+
   return {
     tokenFile,
+    namespaces,
     colors: colorList,
     offenders: offenderList,
     greyCount: colorList.filter((c) => c.value.startsWith('#') && isGrey(c.value)).length,

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

@@ -145,14 +145,42 @@ export function profileRepo(root, files) {
   // Hand-built sites are a real category, not a detection failure: "unknown"
   // next to a good score reads like a shrug, so name what is actually there.
   const htmlFiles = files.other.filter((f) => /\.html?$/.test(f)).length;
+  // Web-component builders come FIRST: a Stencil monorepo ships generated
+  // React/Vue/Angular wrappers whose deps would otherwise win, and calling
+  // Telekom's Stencil system "react" is how a report loses its reader in one
+  // glance (learned on telekom/scale, 2026-09-01).
   const framework =
-    deps.next ? 'next'
+    deps['@stencil/core'] ? 'web components (Stencil)'
+    : deps.lit || deps['lit-element'] ? 'web components (Lit)'
+    : deps.next ? 'next'
     : deps['@remix-run/react'] || deps['@react-router/dev'] ? 'remix'
     : deps.vite && deps.react ? 'vite-react'
     : deps.react ? 'react'
+    : deps.vue ? 'vue'
+    : deps['@angular/core'] ? 'angular'
+    : deps.svelte ? 'svelte'
     : htmlFiles > 0 ? 'static HTML/CSS'
     : 'unknown';
 
+  // A published components package marks a LIBRARY: a repo whose consumers
+  // live in other repos entirely. The distinction changes what usage counts
+  // mean (composition, not adoption) and how orphans may be judged.
+  // Two honest signals: the ROOT package being publishable (private !== true
+  // with a main/module/exports) marks the whole repo as the product being
+  // shipped, whatever it is named (Shoelace); a publishable SUB-package needs
+  // a components-ish name, or every monorepo publishing anything would flip.
+  let libraryPkg = null;
+  if (pkg.private !== true && (pkg.main || pkg.module || pkg.exports)) libraryPkg = pkg.name ?? 'root package';
+  if (!libraryPkg) {
+    for (const f of pkgFiles) {
+      if (f === 'package.json') continue;
+      const p = readJSON(join(root, f));
+      if (!p || p.private === true) continue;
+      if (!(p.main || p.module || p.exports)) continue;
+      if (/components|design.?system|design.?tokens|ui-kit|\bui\b/i.test(p.name ?? '')) { libraryPkg = p.name; break; }
+    }
+  }
+
   const componentsJson = readJSON(join(root, 'components.json'));
   const uiDir = ['src/components/ui', 'components/ui', 'app/components/ui'].find((d) => existsSync(join(root, d)));
   const isShadcn = Boolean(componentsJson) || Boolean(uiDir);
@@ -208,5 +236,13 @@ export function profileRepo(root, files) {
     stylingDeps: styling,
     importAlias: componentsJson?.aliases?.components?.split('/')[0] || alias || null,
     uiDir: uiDir || null,
+    libraryPkg,
+    // markers the component detector cannot read (yet): used by the harvest
+    // to declare component metrics "not measured" instead of scoring zeros
+    unreadableComponentStack:
+      deps.vue || files.other.some((f) => f.endsWith('.vue')) ? 'Vue single-file components'
+      : deps['@angular/core'] ? 'Angular components'
+      : deps.svelte || files.other.some((f) => f.endsWith('.svelte')) ? 'Svelte components'
+      : null,
   };
 }

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

@@ -1,4 +1,4 @@
 // Single version constant for the engine — imported by diagnose (report
 // footer) and rules (generated-by line). This is the bump spot that used to
 // live as a const inside diagnose/index.mjs.
-export const VERSION = '5.6.2';
+export const VERSION = '5.7.0';

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

@@ -51,6 +51,11 @@ const repoName = h.profile?.name ?? 'this repo';
   const tokenCount = (t.colors ?? []).filter((c) => c.isToken).length;
   if (t.tokenFile || (t.colors ?? []).length) {
     section('Colours and tokens');
+    if (t.namespaces?.primary) {
+      const nsLabel = t.namespaces.partner ? `\`--${t.namespaces.primary}-*\` and \`--${t.namespaces.partner}-*\` namespaces` : `\`--${t.namespaces.primary}-*\` namespace`;
+      rule(`This system's tokens answer to the ${nsLabel}. Reach for an existing \`var(--...)\` from them before inventing any value.`);
+      if (t.namespaces.others?.length) rule(`${t.namespaces.others.map((l) => `\`--${l}-*\``).join(', ')} ${t.namespaces.others.length === 1 ? 'is also' : 'are also'} present in the code. Before writing new references to ${t.namespaces.others.length === 1 ? 'it' : 'them'}, check whether this repo treats ${t.namespaces.others.length === 1 ? 'it' : 'them'} as current or as a migration source; when unsure, prefer \`--${t.namespaces.primary}-*\`.`);
+    }
     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.`);