@monoes/monodesign 1.2.22 → 1.2.24

package/README.md

@@ -101,7 +101,7 @@ Source: [`cli/engine/registry/antipatterns.mjs`](packages/@monoes/monodesign/cli
 |---|---|---|
 | `regex` | Source text / CSS-in-JS scan | none |
 | `static-html` | HTMLparser2 static DOM parse | none |
-| `browser` | Puppeteer live-page scan | `puppeteer` (optional) |
+| `browser` | Live-page scan | `@monoes/monobrowse` (optional) with an installed Chrome, Chromium or Edge, else a `puppeteer` you install yourself |
 | `visual` | Visual contrast analysis | `@monoes/monobrowse` (optional) |
 
 ### Auto-Fix
@@ -198,7 +198,7 @@ Search order: `DESIGN.md` → `.agents/context/DESIGN.md` → `docs/DESIGN.md`.
 ```
 
 **Dependencies:** `css-select`, `css-tree`, `domutils`, `fflate`, `htmlparser2`, `marked`  
-**Optional:** `@monoes/monobrowse` (browser detection), `puppeteer` (live URL scanning)
+**Optional:** `@monoes/monobrowse` (browser detection and live URL scanning). `puppeteer` is no longer a dependency; install it yourself only for URL scans on a machine with no Chrome, Chromium or Edge. Through `monomind design detect`, monomind downloads a Chrome on first use instead.
 
 ---
 

package/cli/engine/cli/main.mjs

@@ -18,6 +18,7 @@ import {
   isPortListening,
   walkDir,
 } from '../node/file-system.mjs';
+import { formatGroupedFindings } from '../findings-group.mjs';
 
 // ---------------------------------------------------------------------------
 // Output formatting
@@ -92,6 +93,12 @@ Scan files or URLs for UI anti-patterns and design quality issues.
 Options:
   --json              Output results as JSON
   --quiet             In text mode, only print the final findings count
+  --no-group          In text mode, list every occurrence instead of one line
+                      per unique (rule, snippet) with a count
+  --include-unverified
+                      Also report contrast checks the static analyser cannot
+                      verify (translucent colours, overlays, gradients, SVG
+                      text); hidden by default
   --gpt               Also report GPT-specific provider tells (off by default)
   --gemini            Also report Gemini-specific provider tells (off by default)
   --scope <name>      Only report rules in the given design domain
@@ -138,6 +145,8 @@ async function detectCli() {
   const jsonMode = args.includes('--json');
   const quietMode = args.includes('--quiet');
   const helpMode = args.includes('--help');
+  const groupMode = !args.includes('--no-group');
+  const includeUnverified = args.includes('--include-unverified');
   // --fast (regex-only) is deprecated: since the jsdom removal, the static
   // HTML/CSS analysis is fast and covers every rule, so the regex-only path
   // only loses coverage for no real speed win. Accept the flag for back-compat
@@ -187,7 +196,8 @@ async function detectCli() {
   // apply by default. `--no-config` (raw scan) and the dedicated
   // `--no-inline-ignores` both turn them off.
   const inlineIgnoresEnabled = configEnabled && !args.includes('--no-inline-ignores');
-  const scanOptions = { providers, inlineIgnores: inlineIgnoresEnabled };
+  // Always collect unverified contrast checks so the hidden count can be shown.
+  const scanOptions = { providers, inlineIgnores: inlineIgnoresEnabled, includeUnverified: true };
   if (designSystem) scanOptions.designSystem = designSystem;
   const targets = args.filter(a => !a.startsWith('--'));
 
@@ -307,10 +317,20 @@ async function detectCli() {
 
   allFindings = filterDetectionFindings(allFindings, detectionConfig);
   allFindings = filterByScopes(allFindings, scopes);
+  const unverifiedCount = includeUnverified ? 0 : allFindings.filter(f => f.unverified).length;
+  if (!includeUnverified) allFindings = allFindings.filter(f => !f.unverified);
+  if (unverifiedCount > 0 && !jsonMode && !quietMode) {
+    process.stderr.write(
+      `${unverifiedCount} contrast check${unverifiedCount === 1 ? '' : 's'} could not be verified statically ` +
+      `(translucent colours, overlays, gradients or SVG text) and ${unverifiedCount === 1 ? 'is' : 'are'} hidden. ` +
+      `Pass --include-unverified to list them, or scan the page URL for a browser-rendered check.\n`,
+    );
+  }
 
   if (allFindings.length > 0) {
     if (jsonMode) process.stdout.write(`${formatFindings(allFindings, true)}\n`);
     else if (quietMode) process.stderr.write(`${formatFindingSummary(allFindings.length)}\n`);
+    else if (groupMode) process.stderr.write(`${formatGroupedFindings(allFindings)}\n`);
     else process.stderr.write(`${formatFindings(allFindings, false)}\n`);
     process.exit(2);
   }

package/cli/engine/detect-antipatterns-browser.js

@@ -787,7 +787,7 @@ function isEmojiOnlyText(text) {
 }
 
 function checkColors(opts) {
-  const { tag, textColor, bgColor, effectiveBg, effectiveBgStops, fontSize, fontWeight, hasDirectText, isEmojiOnly, bgClip, bgImage, classList } = opts;
+  const { tag, textColor, bgColor, effectiveBg, effectiveBgStops, fontSize, fontWeight, hasDirectText, isEmojiOnly, bgClip, bgImage, classList, isSvgText } = opts;
   if (SAFE_TAGS.has(tag)) {
     // Exception for <a> and <button> elements styled as buttons. SAFE_TAGS
     // exists to suppress contrast noise on inline links and unstyled controls,
@@ -835,7 +835,14 @@ function checkColors(opts) {
         // like `text-paper/60` on `bg-ink` sections are the FP pattern.
         const isAlphaFallbackFP = !DETECTOR_IS_BROWSER && !effectiveBg && (textColor.a != null && textColor.a < 1);
         if (!isAlphaFallbackFP) {
-          findings.push({ id: 'low-contrast', snippet: `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}` });
+          const snippet = `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}`;
+          // Static analysis can't composite translucent text/surfaces, see
+          // through gradients, or read SVG `fill`, so those ratios are guesses:
+          // report them as unverified rather than definite failures (#424).
+          const unverified = !DETECTOR_IS_BROWSER && (
+            (textColor.a ?? 1) < 1 || !effectiveBg || (effectiveBg.a ?? 1) < 1 || effectiveBg.uncertain || isSvgText
+          );
+          findings.push(unverified ? { id: 'low-contrast', snippet, unverified: true } : { id: 'low-contrast', snippet });
         }
       }
     }
@@ -1395,9 +1402,22 @@ function readOwnBackgroundColor(el, computedStyle) {
   return bg;
 }
 
+// Static mode marks the result `uncertain` when the colour is a guess: a
+// translucent layer was stacked on (or skipped over) the surface we found, a
+// body-level gradient was assumed white, or the walk never reached <body> and
+// fell back to the default white (a fragment's real surface is unknown).
+// Contrast measured against an uncertain surface is reported as unverified.
+function markUncertain(bg, uncertain) {
+  if (!DETECTOR_IS_BROWSER && uncertain) bg.uncertain = true;
+  return bg;
+}
+
 function resolveBackground(el, win, customPropMap) {
   let current = el;
+  let sawTranslucent = false;
+  let sawBody = false;
   while (current && current.nodeType === 1) {
+    if (current.tagName === 'BODY' || current.tagName === 'HTML') sawBody = true;
     const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
     const bgImage = style.backgroundImage || '';
     const hasGradientOrUrl = bgImage && bgImage !== 'none' && (/gradient/i.test(bgImage) || /url\s*\(/i.test(bgImage));
@@ -1429,8 +1449,9 @@ function resolveBackground(el, win, customPropMap) {
     }
 
     if (bg && bg.a > 0.1) {
-      if (DETECTOR_IS_BROWSER || bg.a >= 0.5) return bg;
+      if (DETECTOR_IS_BROWSER || bg.a >= 0.5) return markUncertain(bg, sawTranslucent || bg.a < 1);
     }
+    if (bg && bg.a > 0) sawTranslucent = true;
     // No solid bg-color at this level. If THIS level has a gradient/url
     // with no underlying solid color we can read:
     //   • on body/html: assume white. Body-level gradients are almost
@@ -1445,13 +1466,13 @@ function resolveBackground(el, win, customPropMap) {
     //     bgs worth checking against).
     if (hasGradientOrUrl) {
       if (current.tagName === 'BODY' || current.tagName === 'HTML') {
-        return { r: 255, g: 255, b: 255, a: 1 };
+        return markUncertain({ r: 255, g: 255, b: 255, a: 1 }, true);
       }
       return null;
     }
     current = current.parentElement;
   }
-  return { r: 255, g: 255, b: 255 };
+  return markUncertain({ r: 255, g: 255, b: 255 }, sawTranslucent || !sawBody);
 }
 
 // Walk parents looking for a gradient background and return its color stops.
@@ -2563,6 +2584,8 @@ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInhe
     bgClip: style.webkitBackgroundClip || style.backgroundClip || '',
     bgImage: style.backgroundImage || '',
     classList: el.getAttribute?.('class') || el.className || '',
+    // SVG text paints with `fill`, not `color`, so its CSS colour says nothing.
+    isSvgText: tag === 'text' || tag === 'tspan' || tag === 'textpath',
   });
 }
 

package/cli/engine/detect-antipatterns.mjs

@@ -31,6 +31,7 @@ export {
   collectStaticDesignSystemFindings,
 } from './design-system.mjs';
 export { detectHtml } from './engines/static-html/detect-html.mjs';
+export { groupFindings } from './findings-group.mjs';
 export { detectUrl, createBrowserDetector } from './engines/browser/detect-url.mjs';
 export { detectText, extractStyleBlocks, extractCSSinJS } from './engines/regex/detect-text.mjs';
 export {

package/cli/engine/engines/static-html/detect-html.mjs

@@ -176,7 +176,12 @@ async function detectHtml(filePath, options = {}) {
       const tag = el.tagName.toLowerCase();
       const style = window.getComputedStyle(el);
       for (const f of runElementCheck(rule.id, () => rule.run(el, tag, style, window, customPropMap))) {
-        findings.push(finding(f.id, filePath, f.snippet));
+        // Contrast the static cascade can't resolve (translucent colours,
+        // overlays, gradients) is not a definite failure: callers opt in (#424).
+        if (f.unverified && !options?.includeUnverified) continue;
+        const item = finding(f.id, filePath, f.snippet);
+        if (f.unverified) item.unverified = true;
+        findings.push(item);
       }
     }
   }

package/cli/engine/findings-group.mjs

@@ -0,0 +1,94 @@
+// Collapse repeated findings into one entry per (rule, snippet). A single
+// dark-theme token can fail contrast on hundreds of elements; reporting each
+// occurrence floods agents and humans with the same line (#424).
+
+import path from 'node:path';
+
+const SEVERITY_RANK = { error: 3, warning: 2, advisory: 1, info: 0 };
+
+function severityRank(severity) {
+  return SEVERITY_RANK[severity] ?? SEVERITY_RANK.warning;
+}
+
+function normalizeSnippet(snippet) {
+  return String(snippet ?? '').replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Group findings by (antipattern, normalized snippet).
+ * Returns groups sorted by severity, then occurrence count (both descending),
+ * each carrying the first `maxLocations` locations as examples.
+ */
+function groupFindings(findings, { maxLocations = 3 } = {}) {
+  const groups = new Map();
+  for (const f of findings) {
+    const snippet = normalizeSnippet(f.snippet);
+    const key = `${f.antipattern}\u0000${snippet}`;
+    let g = groups.get(key);
+    if (!g) {
+      g = {
+        antipattern: f.antipattern,
+        name: f.name,
+        severity: f.severity,
+        description: f.description,
+        snippet,
+        count: 0,
+        files: new Set(),
+        seen: new Set(),
+        locations: [],
+      };
+      groups.set(key, g);
+    }
+    g.count += 1;
+    g.files.add(f.file);
+    // Static-HTML findings carry no line, so dedupe locations: one entry per
+    // distinct file:line rather than the same file repeated.
+    const loc = f.line ? { file: f.file, line: f.line } : { file: f.file };
+    if (f.importedBy?.length) loc.importedBy = f.importedBy;
+    const locKey = `${loc.file}:${loc.line ?? ''}`;
+    if (!g.seen.has(locKey) && g.locations.length < maxLocations) {
+      g.seen.add(locKey);
+      g.locations.push(loc);
+    }
+  }
+  // Keep a rule's groups together: order rules by severity then total
+  // occurrences, and groups within a rule by their own count.
+  const ruleTotals = new Map();
+  for (const g of groups.values()) ruleTotals.set(g.antipattern, (ruleTotals.get(g.antipattern) ?? 0) + g.count);
+  return [...groups.values()]
+    .map(({ files, seen, ...g }) => ({ ...g, fileCount: files.size }))
+    .sort((a, b) =>
+      severityRank(b.severity) - severityRank(a.severity)
+      || ruleTotals.get(b.antipattern) - ruleTotals.get(a.antipattern)
+      || a.antipattern.localeCompare(b.antipattern)
+      || b.count - a.count);
+}
+
+function formatLocation(loc, cwd) {
+  const rel = cwd && path.isAbsolute(loc.file) ? path.relative(cwd, loc.file) || loc.file : loc.file;
+  const where = loc.line ? `${rel}:${loc.line}` : rel;
+  return loc.importedBy?.length ? `${where} (imported by ${loc.importedBy.join(', ')})` : where;
+}
+
+/** Human-readable grouped report: one line per unique finding. */
+function formatGroupedFindings(findings, cwd = process.cwd()) {
+  const groups = groupFindings(findings);
+  const out = [];
+  let lastRule = null;
+  for (const g of groups) {
+    if (g.antipattern !== lastRule) {
+      out.push(`\n[${g.antipattern}] ${g.name} (${g.severity})`);
+      out.push(`  → ${g.description}`);
+      lastRule = g.antipattern;
+    }
+    const where = g.locations.map(loc => formatLocation(loc, cwd)).join(', ');
+    const more = g.fileCount > g.locations.length ? `, +${g.fileCount - g.locations.length} more file(s)` : '';
+    out.push(`  ×${g.count}  ${g.snippet}`);
+    out.push(`       at ${where}${more}`);
+  }
+  const unique = groups.length;
+  out.push(`\n${findings.length} anti-pattern${findings.length === 1 ? '' : 's'} found (${unique} unique). Use --no-group to list every occurrence.`);
+  return out.join('\n');
+}
+
+export { groupFindings, formatGroupedFindings, severityRank };

package/cli/engine/fix/index.mjs

@@ -23,6 +23,7 @@ import {
 } from '../../lib/monodesign-config.mjs';
 import { HTML_EXTENSIONS, walkDir } from '../node/file-system.mjs';
 import { UNFIXABLE_REASONS, getFixer, fixableRuleIds, FIXERS } from './fixers.mjs';
+import { unifiedDiff } from './unified-diff.mjs';
 
 // ---------------------------------------------------------------------------
 // Edit application
@@ -57,32 +58,6 @@ function writeFileAtomic(filePath, content) {
   fs.renameSync(tmp, filePath);
 }
 
-// ---------------------------------------------------------------------------
-// Unified diff (minimal single-hunk implementation for --dry-run)
-// ---------------------------------------------------------------------------
-
-function unifiedDiff(oldText, newText, label) {
-  if (oldText === newText) return '';
-  const a = oldText.split('\n');
-  const b = newText.split('\n');
-  let p = 0;
-  while (p < a.length && p < b.length && a[p] === b[p]) p++;
-  let s = 0;
-  while (s < a.length - p && s < b.length - p && a[a.length - 1 - s] === b[b.length - 1 - s]) s++;
-  const aEnd = a.length - s;
-  const bEnd = b.length - s;
-  const ctxStart = Math.max(0, p - 3);
-  const ctxEnd = Math.min(a.length, aEnd + 3);
-  const oldLen = ctxEnd - ctxStart;
-  const newLen = (p - ctxStart) + (bEnd - p) + (ctxEnd - aEnd);
-  const lines = [`--- a/${label}`, `+++ b/${label}`, `@@ -${ctxStart + 1},${oldLen} +${ctxStart + 1},${newLen} @@`];
-  for (let i = ctxStart; i < p; i++) lines.push(` ${a[i]}`);
-  for (let i = p; i < aEnd; i++) lines.push(`-${a[i]}`);
-  for (let i = p; i < bEnd; i++) lines.push(`+${b[i]}`);
-  for (let i = aEnd; i < ctxEnd; i++) lines.push(` ${a[i]}`);
-  return lines.join('\n');
-}
-
 // ---------------------------------------------------------------------------
 // Linked stylesheet resolution (HTML findings whose declaration lives in CSS)
 // ---------------------------------------------------------------------------

package/cli/engine/fix/unified-diff.mjs

@@ -0,0 +1,107 @@
+// Line-level unified diff for `fix --dry-run`. The old single-hunk version
+// spanned the first to the last changed line, so 30 one-line edits spread
+// across a big file printed nearly the whole file (#424). This uses Myers'
+// O((N+M)D) algorithm — D (edited lines) is small for codemods — and emits
+// one hunk per cluster of changes with 3 lines of context.
+
+const CONTEXT = 3;
+// Beyond this many edited lines the trace gets large; fall back to replacing
+// the changed middle wholesale (still trimmed of the shared prefix/suffix).
+const MAX_EDITS = 2000;
+
+// Returns an edit script: [{ op: ' ' | '-' | '+', a, b }] where a/b index the
+// old/new line arrays; null when the diff exceeds MAX_EDITS.
+function myersDiff(a, b) {
+  const n = a.length;
+  const m = b.length;
+  const max = n + m;
+  const offset = max;
+  const v = new Array(2 * max + 2).fill(0);
+  const trace = [];
+  let found = false;
+  for (let d = 0; d <= max && !found; d++) {
+    if (d > MAX_EDITS) return null;
+    // Only diagonals -d..d can be read back for this step: O(D^2) memory.
+    trace.push(v.slice(offset - d, offset + d + 1));
+    for (let k = -d; k <= d; k += 2) {
+      let x = (k === -d || (k !== d && v[offset + k - 1] < v[offset + k + 1]))
+        ? v[offset + k + 1]
+        : v[offset + k - 1] + 1;
+      let y = x - k;
+      while (x < n && y < m && a[x] === b[y]) { x++; y++; }
+      v[offset + k] = x;
+      if (x >= n && y >= m) { found = true; break; }
+    }
+  }
+  // Backtrack through the saved frontiers.
+  const script = [];
+  let x = n;
+  let y = m;
+  for (let d = trace.length - 1; d >= 0; d--) {
+    const vd = trace[d];
+    const at = (kk) => vd[kk + d];
+    const k = x - y;
+    const prevK = (k === -d || (k !== d && at(k - 1) < at(k + 1))) ? k + 1 : k - 1;
+    const prevX = d === 0 ? 0 : at(prevK);
+    const prevY = prevX - prevK;
+    while (x > prevX && y > prevY) { script.push({ op: ' ', a: --x, b: --y }); }
+    if (d > 0) {
+      if (x === prevX) script.push({ op: '+', a: x, b: --y });
+      else script.push({ op: '-', a: --x, b: y });
+    }
+  }
+  return script.reverse();
+}
+
+function unifiedDiff(oldText, newText, label) {
+  if (oldText === newText) return '';
+  const a = oldText.split('\n');
+  const b = newText.split('\n');
+  // A trailing newline yields an empty last element, which is not a line.
+  if (a.length > 1 && b.length > 1 && a[a.length - 1] === '' && b[b.length - 1] === '') { a.pop(); b.pop(); }
+  // Trim the shared prefix/suffix first so Myers only sees the changed middle.
+  let p = 0;
+  while (p < a.length && p < b.length && a[p] === b[p]) p++;
+  let s = 0;
+  while (s < a.length - p && s < b.length - p && a[a.length - 1 - s] === b[b.length - 1 - s]) s++;
+  const oldMid = a.slice(p, a.length - s);
+  const newMid = b.slice(p, b.length - s);
+  const middle = myersDiff(oldMid, newMid) ?? [
+    ...oldMid.map((_, i) => ({ op: '-', a: i, b: 0 })),
+    ...newMid.map((_, i) => ({ op: '+', a: oldMid.length, b: i })),
+  ];
+  const script = [];
+  for (let i = 0; i < p; i++) script.push({ op: ' ', a: i, b: i });
+  for (const e of middle) script.push({ op: e.op, a: e.a + p, b: e.b + p });
+  for (let i = 0; i < s; i++) script.push({ op: ' ', a: a.length - s + i, b: b.length - s + i });
+
+  const lines = [`--- a/${label}`, `+++ b/${label}`];
+  let i = 0;
+  while (i < script.length) {
+    while (i < script.length && script[i].op === ' ') i++;
+    if (i >= script.length) break;
+    const start = Math.max(0, i - CONTEXT);
+    // Extend the hunk until a run of more than 2*CONTEXT unchanged lines.
+    let end = i;
+    let j = i;
+    while (j < script.length) {
+      if (script[j].op !== ' ') { end = j; j++; continue; }
+      let run = 0;
+      while (j + run < script.length && script[j + run].op === ' ') run++;
+      if (j + run >= script.length || run > 2 * CONTEXT) break;
+      j += run;
+    }
+    const stop = Math.min(script.length, end + 1 + CONTEXT);
+    const hunk = script.slice(start, stop);
+    const oldStart = hunk.find(e => e.op !== '+')?.a ?? script[start].a;
+    const newStart = hunk.find(e => e.op !== '-')?.b ?? script[start].b;
+    const oldLen = hunk.filter(e => e.op !== '+').length;
+    const newLen = hunk.filter(e => e.op !== '-').length;
+    lines.push(`@@ -${oldStart + 1},${oldLen} +${newStart + 1},${newLen} @@`);
+    for (const e of hunk) lines.push(`${e.op}${e.op === '+' ? b[e.b] : a[e.a]}`);
+    i = stop;
+  }
+  return lines.join('\n');
+}
+
+export { unifiedDiff };

package/cli/engine/rules/checks-background.mjs

@@ -32,9 +32,22 @@ function readOwnBackgroundColor(el, computedStyle) {
   return bg;
 }
 
+// Static mode marks the result `uncertain` when the colour is a guess: a
+// translucent layer was stacked on (or skipped over) the surface we found, a
+// body-level gradient was assumed white, or the walk never reached <body> and
+// fell back to the default white (a fragment's real surface is unknown).
+// Contrast measured against an uncertain surface is reported as unverified.
+function markUncertain(bg, uncertain) {
+  if (!DETECTOR_IS_BROWSER && uncertain) bg.uncertain = true;
+  return bg;
+}
+
 function resolveBackground(el, win, customPropMap) {
   let current = el;
+  let sawTranslucent = false;
+  let sawBody = false;
   while (current && current.nodeType === 1) {
+    if (current.tagName === 'BODY' || current.tagName === 'HTML') sawBody = true;
     const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
     const bgImage = style.backgroundImage || '';
     const hasGradientOrUrl = bgImage && bgImage !== 'none' && (/gradient/i.test(bgImage) || /url\s*\(/i.test(bgImage));
@@ -66,8 +79,9 @@ function resolveBackground(el, win, customPropMap) {
     }
 
     if (bg && bg.a > 0.1) {
-      if (DETECTOR_IS_BROWSER || bg.a >= 0.5) return bg;
+      if (DETECTOR_IS_BROWSER || bg.a >= 0.5) return markUncertain(bg, sawTranslucent || bg.a < 1);
     }
+    if (bg && bg.a > 0) sawTranslucent = true;
     // No solid bg-color at this level. If THIS level has a gradient/url
     // with no underlying solid color we can read:
     //   • on body/html: assume white. Body-level gradients are almost
@@ -82,13 +96,13 @@ function resolveBackground(el, win, customPropMap) {
     //     bgs worth checking against).
     if (hasGradientOrUrl) {
       if (current.tagName === 'BODY' || current.tagName === 'HTML') {
-        return { r: 255, g: 255, b: 255, a: 1 };
+        return markUncertain({ r: 255, g: 255, b: 255, a: 1 }, true);
       }
       return null;
     }
     current = current.parentElement;
   }
-  return { r: 255, g: 255, b: 255 };
+  return markUncertain({ r: 255, g: 255, b: 255 }, sawTranslucent || !sawBody);
 }
 
 // Walk parents looking for a gradient background and return its color stops.

package/cli/engine/rules/checks-element.mjs

@@ -164,6 +164,8 @@ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInhe
     bgClip: style.webkitBackgroundClip || style.backgroundClip || '',
     bgImage: style.backgroundImage || '',
     classList: el.getAttribute?.('class') || el.className || '',
+    // SVG text paints with `fill`, not `color`, so its CSS colour says nothing.
+    isSvgText: tag === 'text' || tag === 'tspan' || tag === 'textpath',
   });
 }
 

package/cli/engine/rules/checks-pure.mjs

@@ -60,7 +60,7 @@ function isEmojiOnlyText(text) {
 }
 
 function checkColors(opts) {
-  const { tag, textColor, bgColor, effectiveBg, effectiveBgStops, fontSize, fontWeight, hasDirectText, isEmojiOnly, bgClip, bgImage, classList } = opts;
+  const { tag, textColor, bgColor, effectiveBg, effectiveBgStops, fontSize, fontWeight, hasDirectText, isEmojiOnly, bgClip, bgImage, classList, isSvgText } = opts;
   if (SAFE_TAGS.has(tag)) {
     // Exception for <a> and <button> elements styled as buttons. SAFE_TAGS
     // exists to suppress contrast noise on inline links and unstyled controls,
@@ -108,7 +108,14 @@ function checkColors(opts) {
         // like `text-paper/60` on `bg-ink` sections are the FP pattern.
         const isAlphaFallbackFP = !DETECTOR_IS_BROWSER && !effectiveBg && (textColor.a != null && textColor.a < 1);
         if (!isAlphaFallbackFP) {
-          findings.push({ id: 'low-contrast', snippet: `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}` });
+          const snippet = `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}`;
+          // Static analysis can't composite translucent text/surfaces, see
+          // through gradients, or read SVG `fill`, so those ratios are guesses:
+          // report them as unverified rather than definite failures (#424).
+          const unverified = !DETECTOR_IS_BROWSER && (
+            (textColor.a ?? 1) < 1 || !effectiveBg || (effectiveBg.a ?? 1) < 1 || effectiveBg.uncertain || isSvgText
+          );
+          findings.push(unverified ? { id: 'low-contrast', snippet, unverified: true } : { id: 'low-contrast', snippet });
         }
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monodesign",
-  "version": "1.2.22",
+  "version": "1.2.24",
   "description": "Frontend design intelligence for AI agents — design tokens, antipattern detection, and the monodesign skill",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,8 +44,10 @@
     "marked": "^18.0.0"
   },
   "optionalDependencies": {
-    "puppeteer": "^25.1.0",
-    "@monoes/monobrowse": "1.0.27"
+    "@monoes/monobrowse": "1.0.30"
+  },
+  "devDependencies": {
+    "puppeteer": "^25.1.0"
   },
   "scripts": {
     "prebuild": "node ../../../scripts/build-fs.mjs clean dist tsconfig.tsbuildinfo",

package/skill/SKILL.src.md

@@ -1,6 +1,6 @@
 ---
 name: monodesign
-description: "Use when the user wants to design, redesign, shape, critique, audit, polish, clarify, distill, harden, optimize, adapt, animate, colorize, extract, research users, build a component system, generate design images, or otherwise improve a frontend interface. Covers websites, landing pages, dashboards, product UI, app shells, components, forms, settings, onboarding, and empty states. Handles UX review, visual hierarchy, information architecture, cognitive load, accessibility, performance, responsive behavior, theming, anti-patterns, typography, fonts, spacing, layout, alignment, color, motion, micro-interactions, UX copy, error states, edge cases, i18n, reusable design systems, tokens, brand identity, visual storytelling, UX research, usability testing, image generation prompts, and inclusive representation. Also use for bland designs that need to become bolder or more delightful, loud designs that should become quieter, live browser iteration on UI elements, or ambitious visual effects that should feel technically extraordinary. Not for backend-only or non-UI tasks."
+description: "Design, redesign, critique, audit or polish a frontend UI: landing pages, dashboards, components, forms; make it bolder or quieter; type, color, motion, a11y, design systems. Not for non-UI."
 version: 2.0.0
 argument-hint: "[{{command_hint}}] [target]"
 user-invocable: true