@monoes/monodesign 1.2.22 → 1.2.23

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.23",
   "description": "Frontend design intelligence for AI agents — design tokens, antipattern detection, and the monodesign skill",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,7 +45,7 @@
   },
   "optionalDependencies": {
     "puppeteer": "^25.1.0",
-    "@monoes/monobrowse": "1.0.27"
+    "@monoes/monobrowse": "1.0.28"
   },
   "scripts": {
     "prebuild": "node ../../../scripts/build-fs.mjs clean dist tsconfig.tsbuildinfo",