From 8ebcfccc647e48b20dd627b80aa96c13084e3bc0 Mon Sep 17 00:00:00 2001
From: Paul Bakaus <paul.bakaus@gmail.com>
Date: Tue, 28 Jul 2026 16:56:08 -0700
Subject: [PATCH] Scope the page-level pattern checks to style carriers, not
 raw source

The static engine's checkHtmlPatterns ran its CSS-property regexes over
the entire source string, so documentation ABOUT css flagged as css:
impeccable.style's changelog line naming background-clip: text inside a
<code> tag tripped gradient-text, the purple hexes in a <pre> sample
read as the AI palette, and a commented-out stripe rule counted as a
live one. The browser path shared the exposure through outerHTML.

The fix is engine-level, not a per-rule patch. The pattern pass now
scans scoped corpora: styleText carries <style> block contents,
style="" attribute values, and the linked stylesheets the static engine
already reads for the cascade; classText carries class attribute values
for the utility-class scans. The static engine builds both from its
parsed document, so escaped code samples never contribute; other
callers fall back to a tag-scoped extraction in
buildHtmlPatternCorpora, and bare CSS input stays its own style text so
direct callers keep working. The pulsing-dot and marquee scanners take
a second markup argument for the parts that really are markup: landmark
ranges, Tailwind class positions, the <marquee> tag itself.

Rendered-text checks (theater phrases) and markup-shaped checks (svg
scenes, img hover classes) keep the full source on purpose. No registry
ids change; this is scoping, not a new rule.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 cli/engine/detect-antipatterns-browser.js     | 115 ++++++++++++-----
 .../engines/static-html/detect-html.mjs       |  20 ++-
 cli/engine/rules/checks.mjs                   | 116 +++++++++++++-----
 tests/detect-antipatterns-fixtures.test.mjs   |  32 +++++
 tests/detect-antipatterns.test.js             |  41 +++++++
 .../css-in-prose-should-flag.html             |  35 ++++++
 .../css-in-prose-should-pass.html             |  77 ++++++++++++
 7 files changed, 373 insertions(+), 63 deletions(-)
 create mode 100644 tests/fixtures/antipatterns/css-in-prose-should-flag.html
 create mode 100644 tests/fixtures/antipatterns/css-in-prose-should-pass.html

diff --git a/cli/engine/detect-antipatterns-browser.js b/cli/engine/detect-antipatterns-browser.js
index 3d948ad39..5266535c3 100644
--- a/cli/engine/detect-antipatterns-browser.js
+++ b/cli/engine/detect-antipatterns-browser.js
@@ -1863,9 +1863,11 @@ function collectMarqueeKeyframes(content) {
 // bound to a keyframe loop that travels a large horizontal distance.
 // Rotation/opacity animations never qualify (no X travel); JS-driven
 // carousels with user controls have no infinite CSS X-loop to match.
-function scanCssTextForMarquee(content) {
+// `content` is CSS-bearing text; `markup` (defaulting to the same string
+// for single-corpus callers) is where the <marquee> tag itself lives.
+function scanCssTextForMarquee(content, markup = content) {
   const findings = [];
-  if (/<marquee\b/i.test(content)) {
+  if (/<marquee\b/i.test(markup)) {
     findings.push({ id: 'marquee', snippet: '<marquee> element' });
   }
   const marqueeKeyframes = collectMarqueeKeyframes(content);
@@ -2044,10 +2046,14 @@ function selectorHitsLandmark(content, selector, ranges) {
 // element sits inside a header/nav landmark is the hero liveness cliché
 // and is promoted to error severity; occurrences elsewhere keep the
 // registry default severity.
-function scanCssTextForPulsingDot(content) {
+//
+// `content` is CSS-bearing text (rules and keyframes); `markup` — defaulting
+// to the same string for single-corpus callers like the regex source
+// engine — is where landmark ranges and Tailwind class attributes live.
+function scanCssTextForPulsingDot(content, markup = content) {
   const customProps = collectCssCustomProps(content);
   const keyframes = collectPulseKeyframes(content);
-  const heroRanges = landmarkSourceRanges(content);
+  const heroRanges = landmarkSourceRanges(markup);
   const findings = [];
   const seen = new Set();
 
@@ -2096,7 +2102,7 @@ function scanCssTextForPulsingDot(content) {
 
     if (seen.has(selector)) continue;
     seen.add(selector);
-    const inLandmark = selectorHitsLandmark(content, selector, heroRanges);
+    const inLandmark = selectorHitsLandmark(markup, selector, heroRanges);
     findings.push({
       id: 'pulsing-dot',
       snippet: `${selector} — ${w}x${h}px dot with infinite "${pulseName}" animation${inLandmark ? ' in header/nav' : ''}`,
@@ -2106,10 +2112,11 @@ function scanCssTextForPulsingDot(content) {
   }
 
   // Tailwind utilities: animate-ping / animate-pulse on a tiny rounded-full
-  // element declared entirely in the class attribute.
+  // element declared entirely in the class attribute. Scanned in the markup
+  // corpus so the match index lines up with the landmark ranges.
   const classRe = /class\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
   let cm;
-  while ((cm = classRe.exec(content)) !== null) {
+  while ((cm = classRe.exec(markup)) !== null) {
     const cls = cm[1] || cm[2] || '';
     const anim = cls.match(/\banimate-(ping|pulse)\b/);
     if (!anim) continue;
@@ -2190,20 +2197,64 @@ function scanHtmlForShapeAssembledIllustration(html) {
   return findings;
 }
 
+// Scoped scan corpora for the page-level pattern checks. CSS-property
+// regexes run over the whole source string fire on documentation ABOUT
+// css — `<code>background-clip: text</code>` prose, <pre> samples, HTML
+// comments — so the checks scan only the strings that actually style the
+// page:
+//   styleText — <style> block contents plus style="…" attribute values.
+//     Attribute values keep their `style="…"` form so block-scoped
+//     scanners (grid background) keep treating each attribute as one
+//     declaration block, exactly as they did against raw source. Engines
+//     that already read more CSS (linked stylesheets) prepend it.
+//   classText — class attribute values, for utility-class scans.
+// Markup-shaped checks (inline <svg> scenes, <img> tags, <marquee>,
+// landmark ranges) and rendered-text checks (theater phrases) keep the
+// full source. This extraction serves callers without a parsed document
+// (the browser bundle scanning outerHTML); attribute reads are tag-scoped
+// so escaped code samples (&lt;div style="…"&gt;) never contribute. The
+// static engine passes richer corpora built from its parsed document.
+// Bare CSS input (no markup at all) is its own style text, which keeps
+// direct checkHtmlPatterns(css) callers behaving as before.
+function buildHtmlPatternCorpora(html) {
+  const source = String(html || '');
+  if (!/<[a-zA-Z!/]/.test(source)) {
+    return { styleText: source, classText: source };
+  }
+  const styleParts = [];
+  const classParts = [];
+  const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
+  let m;
+  while ((m = styleBlockRe.exec(source)) !== null) styleParts.push(m[1]);
+  const tagRe = /<[a-zA-Z][^>]*>/g;
+  while ((m = tagRe.exec(source)) !== null) {
+    const tag = m[0];
+    const sm = tag.match(/\bstyle\s*=\s*("[^"]*"|'[^']*')/i);
+    if (sm) styleParts.push(`style=${sm[1]}`);
+    const cm = tag.match(/\bclass\s*=\s*(?:"([^"]*)"|'([^']*)')/i);
+    if (cm) classParts.push(cm[1] ?? cm[2] ?? '');
+  }
+  return { styleText: styleParts.join('\n'), classText: classParts.join('\n') };
+}
+
 /**
  * Regex-on-HTML checks shared between browser and Node page-level detection.
- * These don't need DOM access, just the raw HTML string.
+ * These don't need DOM access, just the raw HTML string. CSS-property and
+ * utility-class patterns scan the scoped corpora (styleText / classText —
+ * see buildHtmlPatternCorpora) so prose about css never flags; only the
+ * markup-shaped and rendered-text checks read the full source.
  */
-function checkHtmlPatterns(html) {
+function checkHtmlPatterns(html, corpora) {
+  const { styleText, classText } = corpora || buildHtmlPatternCorpora(html);
   const findings = [];
 
   // --- Color ---
 
   // AI color palette: purple/violet
   const purpleHexRe = /#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9|6366f1|764ba2|667eea)\b/gi;
-  if (purpleHexRe.test(html)) {
+  if (purpleHexRe.test(styleText)) {
     const purpleTextRe = /(?:(?:^|;)\s*color\s*:\s*(?:.*?)(?:#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9))|gradient.*?#(?:7c3aed|8b5cf6|a855f7|764ba2|667eea))/gi;
-    if (purpleTextRe.test(html)) {
+    if (purpleTextRe.test(styleText)) {
       findings.push({ id: 'ai-color-palette', snippet: 'Purple/violet accent colors detected' });
     }
   }
@@ -2211,15 +2262,15 @@ function checkHtmlPatterns(html) {
   // Gradient text (background-clip: text + gradient)
   const gradientRe = /(?:-webkit-)?background-clip\s*:\s*text/gi;
   let gm;
-  while ((gm = gradientRe.exec(html)) !== null) {
+  while ((gm = gradientRe.exec(styleText)) !== null) {
     const start = Math.max(0, gm.index - 200);
-    const context = html.substring(start, gm.index + gm[0].length + 200);
+    const context = styleText.substring(start, gm.index + gm[0].length + 200);
     if (/gradient/i.test(context)) {
       findings.push({ id: 'gradient-text', snippet: 'background-clip: text + gradient' });
       break;
     }
   }
-  if (/\bbg-clip-text\b/.test(html) && /\bbg-gradient-to-/.test(html)) {
+  if (/\bbg-clip-text\b/.test(classText) && /\bbg-gradient-to-/.test(classText)) {
     findings.push({ id: 'gradient-text', snippet: 'bg-clip-text + bg-gradient (Tailwind)' });
   }
 
@@ -2228,10 +2279,10 @@ function checkHtmlPatterns(html) {
   // Side-tab accent stripe drawn as an absolutely-positioned pseudo-element
   // (no border property involved, so the element-level border checks and
   // the border-left regexes never see it).
-  findings.push(...scanCssTextForPseudoStripe(html));
+  findings.push(...scanCssTextForPseudoStripe(styleText));
 
   // Side-tab accent stripe drawn as a single-edge inset box-shadow.
-  findings.push(...scanCssTextForInsetStripe(html));
+  findings.push(...scanCssTextForInsetStripe(styleText));
 
   // --- Layout ---
 
@@ -2239,20 +2290,20 @@ function checkHtmlPatterns(html) {
   const spacingValues = [];
   const spacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*(\d+)px/gi;
   let sm;
-  while ((sm = spacingRe.exec(html)) !== null) {
+  while ((sm = spacingRe.exec(styleText)) !== null) {
     const v = parseInt(sm[1], 10);
     if (v > 0 && v < 200) spacingValues.push(v);
   }
   const gapRe = /gap\s*:\s*(\d+)px/gi;
-  while ((sm = gapRe.exec(html)) !== null) {
+  while ((sm = gapRe.exec(styleText)) !== null) {
     spacingValues.push(parseInt(sm[1], 10));
   }
   const twSpaceRe = /\b(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap)-(\d+)\b/g;
-  while ((sm = twSpaceRe.exec(html)) !== null) {
+  while ((sm = twSpaceRe.exec(classText)) !== null) {
     spacingValues.push(parseInt(sm[1], 10) * 4);
   }
   const remSpacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*([\d.]+)rem/gi;
-  while ((sm = remSpacingRe.exec(html)) !== null) {
+  while ((sm = remSpacingRe.exec(styleText)) !== null) {
     const v = Math.round(parseFloat(sm[1]) * 16);
     if (v > 0 && v < 200) spacingValues.push(v);
   }
@@ -2276,7 +2327,7 @@ function checkHtmlPatterns(html) {
 
   // Bounce/elastic animation names
   const bounceRe = /animation(?:-name)?\s*:\s*([^;{}]*(?:bounce|elastic|wobble|jiggle|spring)[^;{}]*)/gi;
-  const bounceMatch = bounceRe.exec(html);
+  const bounceMatch = bounceRe.exec(styleText);
   if (bounceMatch) {
     const animationToken = bounceMatch[1]
       .split(/[,\s]+/)
@@ -2287,7 +2338,7 @@ function checkHtmlPatterns(html) {
   // Overshoot cubic-bezier
   const bezierRe = /cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)/g;
   let bm;
-  while ((bm = bezierRe.exec(html)) !== null) {
+  while ((bm = bezierRe.exec(styleText)) !== null) {
     const y1 = parseFloat(bm[2]), y2 = parseFloat(bm[4]);
     if (y1 < -0.1 || y1 > 1.1 || y2 < -0.1 || y2 > 1.1) {
       findings.push({ id: 'bounce-easing', snippet: `cubic-bezier(${bm[1]}, ${bm[2]}, ${bm[3]}, ${bm[4]})` });
@@ -2298,7 +2349,7 @@ function checkHtmlPatterns(html) {
   // Layout property transitions
   const transRe = /transition(?:-property)?\s*:\s*([^;{}]+)/gi;
   let tm;
-  while ((tm = transRe.exec(html)) !== null) {
+  while ((tm = transRe.exec(styleText)) !== null) {
     const val = tm[1].toLowerCase();
     if (/\ball\b/.test(val)) continue;
     const found = val.match(/\b(?:(?:max|min)-)?(?:width|height)\b|\bpadding(?:-(?:top|right|bottom|left))?\b|\bmargin(?:-(?:top|right|bottom|left))?\b/gi);
@@ -2308,30 +2359,32 @@ function checkHtmlPatterns(html) {
     }
   }
 
-  // Pulsing status dots (tiny circular elements on infinite pulse animations)
-  findings.push(...scanCssTextForPulsingDot(html));
+  // Pulsing status dots (tiny circular elements on infinite pulse animations).
+  // The CSS rules come from styleText; the markup carries the landmark
+  // ranges and Tailwind class attributes.
+  findings.push(...scanCssTextForPulsingDot(styleText, html));
 
   // Shape-assembled illustrations (large pictorial SVGs built from primitives)
   findings.push(...scanHtmlForShapeAssembledIllustration(html));
 
   // Auto-scrolling marquees (<marquee> or infinite horizontal loop animations)
-  findings.push(...scanCssTextForMarquee(html));
+  findings.push(...scanCssTextForMarquee(styleText, html));
 
   // --- Dark glow / chromatic halo shadows ---
 
-  const glowHits = scanCssTextForGlow(html);
+  const glowHits = scanCssTextForGlow(styleText);
   if (glowHits.length > 0) {
     findings.push({ id: 'dark-glow', snippet: glowHits[0].snippet });
   }
 
   // Radial-gradient background halo (gradient-drawn sibling of dark-glow)
-  const haloHits = scanCssTextForRadialHalo(html);
+  const haloHits = scanCssTextForRadialHalo(styleText);
   if (haloHits.length > 0) {
     findings.push({ id: 'radial-halo', snippet: haloHits[0].snippet });
   }
 
   // --- Generated-UI tells: repeating-gradient stripes ---
-  if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(html)) {
+  if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(styleText)) {
     findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes' });
   }
 
@@ -2348,7 +2401,7 @@ function checkHtmlPatterns(html) {
   // in for the second axis. Colors like `oklch(96% 0.012 82 / 0.055)` carry
   // nested parens, so match the hairline stop directly rather than parsing
   // whole gradient layers.
-  const gridHits = scanCssTextForGridBackground(html);
+  const gridHits = scanCssTextForGridBackground(styleText);
   if (gridHits.length > 0) {
     findings.push({ id: 'codex-grid-background', snippet: gridHits[0].snippet });
   }
@@ -2370,7 +2423,7 @@ function checkHtmlPatterns(html) {
   // hover:rotate / hover:translate utility on an <img>. Each distinct
   // mechanism is its own finding.
   const imgHoverCss = /\bimg\b[^,{}]*:hover\b[^{}]*\{[^}]*\btransform\s*:\s*(?:scale|rotate|translate|matrix|skew)/i;
-  if (imgHoverCss.test(html)) {
+  if (imgHoverCss.test(styleText)) {
     findings.push({ id: 'image-hover-transform', snippet: 'img:hover { transform } rule' });
   }
   const imgTagRe = /<img\b[^>]*\bclass\s*=\s*"([^"]*)"/gi;
diff --git a/cli/engine/engines/static-html/detect-html.mjs b/cli/engine/engines/static-html/detect-html.mjs
index 4e2074042..53aadd058 100644
--- a/cli/engine/engines/static-html/detect-html.mjs
+++ b/cli/engine/engines/static-html/detect-html.mjs
@@ -220,7 +220,25 @@ async function detectHtml(filePath, options = {}) {
     for (const f of runPageCheck('skipped-heading', () => checkPageQualityFromDoc(document))) {
       findings.push(finding(f.id, filePath, f.snippet));
     }
-    for (const f of runPageCheck('html-patterns', () => checkHtmlPatterns(html).filter(item =>
+    // Scoped corpora for the pattern checks (see buildHtmlPatternCorpora in
+    // rules/checks.mjs): CSS-property regexes must not fire on prose ABOUT
+    // css — `<code>background-clip: text</code>` in a changelog is
+    // documentation, not styling. cssText already carries the <style>
+    // blocks and any linked local stylesheets; style/class attributes come
+    // from the parsed document, so escaped code samples never contribute.
+    const styleAttrParts = [];
+    const classAttrParts = [];
+    for (const el of document.querySelectorAll('*')) {
+      const styleAttr = el.getAttribute('style');
+      if (styleAttr) styleAttrParts.push(`style="${styleAttr}"`);
+      const classAttr = el.getAttribute('class');
+      if (classAttr) classAttrParts.push(classAttr);
+    }
+    const patternCorpora = {
+      styleText: [cssText, ...styleAttrParts].join('\n'),
+      classText: classAttrParts.join('\n'),
+    };
+    for (const f of runPageCheck('html-patterns', () => checkHtmlPatterns(html, patternCorpora).filter(item =>
       item.id !== 'bounce-easing' && item.id !== 'layout-transition'
     ))) {
       const item = finding(f.id, filePath, f.snippet);
diff --git a/cli/engine/rules/checks.mjs b/cli/engine/rules/checks.mjs
index 3bf26b9b5..3abf2758e 100644
--- a/cli/engine/rules/checks.mjs
+++ b/cli/engine/rules/checks.mjs
@@ -1062,9 +1062,11 @@ function collectMarqueeKeyframes(content) {
 // bound to a keyframe loop that travels a large horizontal distance.
 // Rotation/opacity animations never qualify (no X travel); JS-driven
 // carousels with user controls have no infinite CSS X-loop to match.
-function scanCssTextForMarquee(content) {
+// `content` is CSS-bearing text; `markup` (defaulting to the same string
+// for single-corpus callers) is where the <marquee> tag itself lives.
+function scanCssTextForMarquee(content, markup = content) {
   const findings = [];
-  if (/<marquee\b/i.test(content)) {
+  if (/<marquee\b/i.test(markup)) {
     findings.push({ id: 'marquee', snippet: '<marquee> element' });
   }
   const marqueeKeyframes = collectMarqueeKeyframes(content);
@@ -1243,10 +1245,14 @@ function selectorHitsLandmark(content, selector, ranges) {
 // element sits inside a header/nav landmark is the hero liveness cliché
 // and is promoted to error severity; occurrences elsewhere keep the
 // registry default severity.
-function scanCssTextForPulsingDot(content) {
+//
+// `content` is CSS-bearing text (rules and keyframes); `markup` — defaulting
+// to the same string for single-corpus callers like the regex source
+// engine — is where landmark ranges and Tailwind class attributes live.
+function scanCssTextForPulsingDot(content, markup = content) {
   const customProps = collectCssCustomProps(content);
   const keyframes = collectPulseKeyframes(content);
-  const heroRanges = landmarkSourceRanges(content);
+  const heroRanges = landmarkSourceRanges(markup);
   const findings = [];
   const seen = new Set();
 
@@ -1295,7 +1301,7 @@ function scanCssTextForPulsingDot(content) {
 
     if (seen.has(selector)) continue;
     seen.add(selector);
-    const inLandmark = selectorHitsLandmark(content, selector, heroRanges);
+    const inLandmark = selectorHitsLandmark(markup, selector, heroRanges);
     findings.push({
       id: 'pulsing-dot',
       snippet: `${selector} — ${w}x${h}px dot with infinite "${pulseName}" animation${inLandmark ? ' in header/nav' : ''}`,
@@ -1305,10 +1311,11 @@ function scanCssTextForPulsingDot(content) {
   }
 
   // Tailwind utilities: animate-ping / animate-pulse on a tiny rounded-full
-  // element declared entirely in the class attribute.
+  // element declared entirely in the class attribute. Scanned in the markup
+  // corpus so the match index lines up with the landmark ranges.
   const classRe = /class\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
   let cm;
-  while ((cm = classRe.exec(content)) !== null) {
+  while ((cm = classRe.exec(markup)) !== null) {
     const cls = cm[1] || cm[2] || '';
     const anim = cls.match(/\banimate-(ping|pulse)\b/);
     if (!anim) continue;
@@ -1389,20 +1396,64 @@ function scanHtmlForShapeAssembledIllustration(html) {
   return findings;
 }
 
+// Scoped scan corpora for the page-level pattern checks. CSS-property
+// regexes run over the whole source string fire on documentation ABOUT
+// css — `<code>background-clip: text</code>` prose, <pre> samples, HTML
+// comments — so the checks scan only the strings that actually style the
+// page:
+//   styleText — <style> block contents plus style="…" attribute values.
+//     Attribute values keep their `style="…"` form so block-scoped
+//     scanners (grid background) keep treating each attribute as one
+//     declaration block, exactly as they did against raw source. Engines
+//     that already read more CSS (linked stylesheets) prepend it.
+//   classText — class attribute values, for utility-class scans.
+// Markup-shaped checks (inline <svg> scenes, <img> tags, <marquee>,
+// landmark ranges) and rendered-text checks (theater phrases) keep the
+// full source. This extraction serves callers without a parsed document
+// (the browser bundle scanning outerHTML); attribute reads are tag-scoped
+// so escaped code samples (&lt;div style="…"&gt;) never contribute. The
+// static engine passes richer corpora built from its parsed document.
+// Bare CSS input (no markup at all) is its own style text, which keeps
+// direct checkHtmlPatterns(css) callers behaving as before.
+function buildHtmlPatternCorpora(html) {
+  const source = String(html || '');
+  if (!/<[a-zA-Z!/]/.test(source)) {
+    return { styleText: source, classText: source };
+  }
+  const styleParts = [];
+  const classParts = [];
+  const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
+  let m;
+  while ((m = styleBlockRe.exec(source)) !== null) styleParts.push(m[1]);
+  const tagRe = /<[a-zA-Z][^>]*>/g;
+  while ((m = tagRe.exec(source)) !== null) {
+    const tag = m[0];
+    const sm = tag.match(/\bstyle\s*=\s*("[^"]*"|'[^']*')/i);
+    if (sm) styleParts.push(`style=${sm[1]}`);
+    const cm = tag.match(/\bclass\s*=\s*(?:"([^"]*)"|'([^']*)')/i);
+    if (cm) classParts.push(cm[1] ?? cm[2] ?? '');
+  }
+  return { styleText: styleParts.join('\n'), classText: classParts.join('\n') };
+}
+
 /**
  * Regex-on-HTML checks shared between browser and Node page-level detection.
- * These don't need DOM access, just the raw HTML string.
+ * These don't need DOM access, just the raw HTML string. CSS-property and
+ * utility-class patterns scan the scoped corpora (styleText / classText —
+ * see buildHtmlPatternCorpora) so prose about css never flags; only the
+ * markup-shaped and rendered-text checks read the full source.
  */
-function checkHtmlPatterns(html) {
+function checkHtmlPatterns(html, corpora) {
+  const { styleText, classText } = corpora || buildHtmlPatternCorpora(html);
   const findings = [];
 
   // --- Color ---
 
   // AI color palette: purple/violet
   const purpleHexRe = /#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9|6366f1|764ba2|667eea)\b/gi;
-  if (purpleHexRe.test(html)) {
+  if (purpleHexRe.test(styleText)) {
     const purpleTextRe = /(?:(?:^|;)\s*color\s*:\s*(?:.*?)(?:#(?:7c3aed|8b5cf6|a855f7|9333ea|7e22ce|6d28d9))|gradient.*?#(?:7c3aed|8b5cf6|a855f7|764ba2|667eea))/gi;
-    if (purpleTextRe.test(html)) {
+    if (purpleTextRe.test(styleText)) {
       findings.push({ id: 'ai-color-palette', snippet: 'Purple/violet accent colors detected' });
     }
   }
@@ -1410,15 +1461,15 @@ function checkHtmlPatterns(html) {
   // Gradient text (background-clip: text + gradient)
   const gradientRe = /(?:-webkit-)?background-clip\s*:\s*text/gi;
   let gm;
-  while ((gm = gradientRe.exec(html)) !== null) {
+  while ((gm = gradientRe.exec(styleText)) !== null) {
     const start = Math.max(0, gm.index - 200);
-    const context = html.substring(start, gm.index + gm[0].length + 200);
+    const context = styleText.substring(start, gm.index + gm[0].length + 200);
     if (/gradient/i.test(context)) {
       findings.push({ id: 'gradient-text', snippet: 'background-clip: text + gradient' });
       break;
     }
   }
-  if (/\bbg-clip-text\b/.test(html) && /\bbg-gradient-to-/.test(html)) {
+  if (/\bbg-clip-text\b/.test(classText) && /\bbg-gradient-to-/.test(classText)) {
     findings.push({ id: 'gradient-text', snippet: 'bg-clip-text + bg-gradient (Tailwind)' });
   }
 
@@ -1427,10 +1478,10 @@ function checkHtmlPatterns(html) {
   // Side-tab accent stripe drawn as an absolutely-positioned pseudo-element
   // (no border property involved, so the element-level border checks and
   // the border-left regexes never see it).
-  findings.push(...scanCssTextForPseudoStripe(html));
+  findings.push(...scanCssTextForPseudoStripe(styleText));
 
   // Side-tab accent stripe drawn as a single-edge inset box-shadow.
-  findings.push(...scanCssTextForInsetStripe(html));
+  findings.push(...scanCssTextForInsetStripe(styleText));
 
   // --- Layout ---
 
@@ -1438,20 +1489,20 @@ function checkHtmlPatterns(html) {
   const spacingValues = [];
   const spacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*(\d+)px/gi;
   let sm;
-  while ((sm = spacingRe.exec(html)) !== null) {
+  while ((sm = spacingRe.exec(styleText)) !== null) {
     const v = parseInt(sm[1], 10);
     if (v > 0 && v < 200) spacingValues.push(v);
   }
   const gapRe = /gap\s*:\s*(\d+)px/gi;
-  while ((sm = gapRe.exec(html)) !== null) {
+  while ((sm = gapRe.exec(styleText)) !== null) {
     spacingValues.push(parseInt(sm[1], 10));
   }
   const twSpaceRe = /\b(?:p|px|py|pt|pb|pl|pr|m|mx|my|mt|mb|ml|mr|gap)-(\d+)\b/g;
-  while ((sm = twSpaceRe.exec(html)) !== null) {
+  while ((sm = twSpaceRe.exec(classText)) !== null) {
     spacingValues.push(parseInt(sm[1], 10) * 4);
   }
   const remSpacingRe = /(?:padding|margin)(?:-(?:top|right|bottom|left))?\s*:\s*([\d.]+)rem/gi;
-  while ((sm = remSpacingRe.exec(html)) !== null) {
+  while ((sm = remSpacingRe.exec(styleText)) !== null) {
     const v = Math.round(parseFloat(sm[1]) * 16);
     if (v > 0 && v < 200) spacingValues.push(v);
   }
@@ -1475,7 +1526,7 @@ function checkHtmlPatterns(html) {
 
   // Bounce/elastic animation names
   const bounceRe = /animation(?:-name)?\s*:\s*([^;{}]*(?:bounce|elastic|wobble|jiggle|spring)[^;{}]*)/gi;
-  const bounceMatch = bounceRe.exec(html);
+  const bounceMatch = bounceRe.exec(styleText);
   if (bounceMatch) {
     const animationToken = bounceMatch[1]
       .split(/[,\s]+/)
@@ -1486,7 +1537,7 @@ function checkHtmlPatterns(html) {
   // Overshoot cubic-bezier
   const bezierRe = /cubic-bezier\(\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*,\s*([\d.-]+)\s*\)/g;
   let bm;
-  while ((bm = bezierRe.exec(html)) !== null) {
+  while ((bm = bezierRe.exec(styleText)) !== null) {
     const y1 = parseFloat(bm[2]), y2 = parseFloat(bm[4]);
     if (y1 < -0.1 || y1 > 1.1 || y2 < -0.1 || y2 > 1.1) {
       findings.push({ id: 'bounce-easing', snippet: `cubic-bezier(${bm[1]}, ${bm[2]}, ${bm[3]}, ${bm[4]})` });
@@ -1497,7 +1548,7 @@ function checkHtmlPatterns(html) {
   // Layout property transitions
   const transRe = /transition(?:-property)?\s*:\s*([^;{}]+)/gi;
   let tm;
-  while ((tm = transRe.exec(html)) !== null) {
+  while ((tm = transRe.exec(styleText)) !== null) {
     const val = tm[1].toLowerCase();
     if (/\ball\b/.test(val)) continue;
     const found = val.match(/\b(?:(?:max|min)-)?(?:width|height)\b|\bpadding(?:-(?:top|right|bottom|left))?\b|\bmargin(?:-(?:top|right|bottom|left))?\b/gi);
@@ -1507,30 +1558,32 @@ function checkHtmlPatterns(html) {
     }
   }
 
-  // Pulsing status dots (tiny circular elements on infinite pulse animations)
-  findings.push(...scanCssTextForPulsingDot(html));
+  // Pulsing status dots (tiny circular elements on infinite pulse animations).
+  // The CSS rules come from styleText; the markup carries the landmark
+  // ranges and Tailwind class attributes.
+  findings.push(...scanCssTextForPulsingDot(styleText, html));
 
   // Shape-assembled illustrations (large pictorial SVGs built from primitives)
   findings.push(...scanHtmlForShapeAssembledIllustration(html));
 
   // Auto-scrolling marquees (<marquee> or infinite horizontal loop animations)
-  findings.push(...scanCssTextForMarquee(html));
+  findings.push(...scanCssTextForMarquee(styleText, html));
 
   // --- Dark glow / chromatic halo shadows ---
 
-  const glowHits = scanCssTextForGlow(html);
+  const glowHits = scanCssTextForGlow(styleText);
   if (glowHits.length > 0) {
     findings.push({ id: 'dark-glow', snippet: glowHits[0].snippet });
   }
 
   // Radial-gradient background halo (gradient-drawn sibling of dark-glow)
-  const haloHits = scanCssTextForRadialHalo(html);
+  const haloHits = scanCssTextForRadialHalo(styleText);
   if (haloHits.length > 0) {
     findings.push({ id: 'radial-halo', snippet: haloHits[0].snippet });
   }
 
   // --- Generated-UI tells: repeating-gradient stripes ---
-  if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(html)) {
+  if (/repeating-(?:linear|radial|conic)-gradient\s*\(/i.test(styleText)) {
     findings.push({ id: 'repeating-stripes-gradient', snippet: 'repeating-gradient decorative stripes' });
   }
 
@@ -1547,7 +1600,7 @@ function checkHtmlPatterns(html) {
   // in for the second axis. Colors like `oklch(96% 0.012 82 / 0.055)` carry
   // nested parens, so match the hairline stop directly rather than parsing
   // whole gradient layers.
-  const gridHits = scanCssTextForGridBackground(html);
+  const gridHits = scanCssTextForGridBackground(styleText);
   if (gridHits.length > 0) {
     findings.push({ id: 'codex-grid-background', snippet: gridHits[0].snippet });
   }
@@ -1569,7 +1622,7 @@ function checkHtmlPatterns(html) {
   // hover:rotate / hover:translate utility on an <img>. Each distinct
   // mechanism is its own finding.
   const imgHoverCss = /\bimg\b[^,{}]*:hover\b[^{}]*\{[^}]*\btransform\s*:\s*(?:scale|rotate|translate|matrix|skew)/i;
-  if (imgHoverCss.test(html)) {
+  if (imgHoverCss.test(styleText)) {
     findings.push({ id: 'image-hover-transform', snippet: 'img:hover { transform } rule' });
   }
   const imgTagRe = /<img\b[^>]*\bclass\s*=\s*"([^"]*)"/gi;
@@ -5450,6 +5503,7 @@ export {
   cssLengthToPx,
   scanCssTextForPulsingDot,
   scanHtmlForShapeAssembledIllustration,
+  buildHtmlPatternCorpora,
   checkHtmlPatterns,
   readOwnBackgroundColor,
   resolveBackground,
diff --git a/tests/detect-antipatterns-fixtures.test.mjs b/tests/detect-antipatterns-fixtures.test.mjs
index 722a29c04..bdda86a94 100644
--- a/tests/detect-antipatterns-fixtures.test.mjs
+++ b/tests/detect-antipatterns-fixtures.test.mjs
@@ -1331,3 +1331,35 @@ describe('em-dash overuse — browser adapter parity (checkEmDashOveruse)', () =
     assert.equal(id(findings), 'em-dash-overuse');
   });
 });
+
+describe('detectHtml — CSS patterns in prose (css-in-prose fixtures)', () => {
+  // CSS-property regexes must scan only real style carriers (<style> blocks,
+  // style="" attributes, linked stylesheets, class="" attributes). Prose,
+  // <code>/<pre> samples, and comments documenting a pattern are not styling.
+  // Live FP: impeccable.style's changelog line
+  // `<code>background-clip: text</code> gradients stop tripping contrast`.
+  const SCOPED_RULE_IDS = ['gradient-text', 'ai-color-palette', 'side-tab', 'pulsing-dot'];
+
+  it('documentation about the patterns adds no findings', async () => {
+    const f = await detectHtml(path.join(FIXTURES, 'css-in-prose-should-pass.html'));
+    const hits = f.filter(r => SCOPED_RULE_IDS.includes(r.antipattern));
+    assert.equal(
+      hits.length, 0,
+      `prose/code/comment mentions must not flag, got: ${hits.map(r => `${r.antipattern}:${r.snippet}`).join('; ')}`
+    );
+  });
+
+  it('the same patterns applied as real styling still flag', async () => {
+    const f = await detectHtml(path.join(FIXTURES, 'css-in-prose-should-flag.html'));
+    const gradient = f.filter(r => r.antipattern === 'gradient-text');
+    assert.ok(
+      gradient.some(r => /background-clip: text \+ gradient/.test(r.snippet || '')),
+      'expected the CSS-mechanism gradient-text finding'
+    );
+    assert.ok(
+      gradient.some(r => /bg-clip-text \+ bg-gradient \(Tailwind\)/.test(r.snippet || '')),
+      'expected the Tailwind gradient-text finding'
+    );
+    assert.ok(f.some(r => r.antipattern === 'ai-color-palette'), 'expected ai-color-palette');
+  });
+});
diff --git a/tests/detect-antipatterns.test.js b/tests/detect-antipatterns.test.js
index 8f068faf5..8fd08f464 100644
--- a/tests/detect-antipatterns.test.js
+++ b/tests/detect-antipatterns.test.js
@@ -896,6 +896,47 @@ describe('detectHtml — static HTML/CSS engine', () => {
     expect(findingIds(f)).toContain('side-tab');
   });
 
+  test('gradient-text: a style="" attribute alone carries the page-level flag', async () => {
+    await withStaticFixture({
+      'index.html': `<!DOCTYPE html><html><head><title>t</title></head><body>
+        <h2 style="background: linear-gradient(90deg, #667eea, #764ba2); -webkit-background-clip: text; background-clip: text; -webkit-text-fill-color: transparent;">Inline gradient heading</h2>
+        <p>Body copy long enough to make this a real page for the scanners.</p>
+      </body></html>`,
+    }, async ({ file }) => {
+      const f = await detectHtml(file);
+      expect(f.some(r => r.antipattern === 'gradient-text' && /background-clip/.test(r.snippet))).toBe(true);
+    });
+  });
+
+  test('gradient-text: a <style> rule alone carries the page-level flag', async () => {
+    await withStaticFixture({
+      'index.html': `<!DOCTYPE html><html><head><style>
+        .t { background: linear-gradient(90deg, #667eea, #764ba2); -webkit-background-clip: text; background-clip: text; -webkit-text-fill-color: transparent; }
+      </style></head><body>
+        <h2 class="t">Styled gradient heading</h2>
+        <p>Body copy long enough to make this a real page for the scanners.</p>
+      </body></html>`,
+    }, async ({ file }) => {
+      const f = await detectHtml(file);
+      expect(f.some(r => r.antipattern === 'gradient-text' && /background-clip/.test(r.snippet))).toBe(true);
+    });
+  });
+
+  test('gradient-text: prose and code samples about the pattern do not flag', async () => {
+    await withStaticFixture({
+      'index.html': `<!DOCTYPE html><html><head><title>changelog</title></head><body>
+        <h1>Changelog</h1>
+        <p><code>background-clip: text</code> gradients stop tripping the contrast rules.</p>
+        <pre><code>.hero { background: linear-gradient(135deg, #667eea, #764ba2); background-clip: text; }</code></pre>
+        <p>Pair bg-clip-text with bg-gradient-to-r and both utilities together are the tell.</p>
+      </body></html>`,
+    }, async ({ file }) => {
+      const f = await detectHtml(file);
+      expect(f.filter(r => r.antipattern === 'gradient-text')).toHaveLength(0);
+      expect(f.filter(r => r.antipattern === 'ai-color-palette')).toHaveLength(0);
+    });
+  });
+
   test('flattens @layer, resolves CSS variables and fallbacks, and skips unsupported selectors', async () => {
     await withStaticFixture({
       'index.html': `<!DOCTYPE html>
diff --git a/tests/fixtures/antipatterns/css-in-prose-should-flag.html b/tests/fixtures/antipatterns/css-in-prose-should-flag.html
new file mode 100644
index 000000000..af69dc8e3
--- /dev/null
+++ b/tests/fixtures/antipatterns/css-in-prose-should-flag.html
@@ -0,0 +1,35 @@
+<!DOCTYPE html>
+<!--
+  Companion to css-in-prose-should-pass.html: the same patterns applied as
+  real styling. The scoped-corpus scan must still catch every carrier a page
+  can style itself with — a <style> rule, an inline style="" attribute, and
+  Tailwind utility classes.
+-->
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Real gradient-text styling</title>
+<style>
+  body { font-family: Georgia, serif; margin: 0; padding: 40px 24px; background: #fdfcf9; color: #1f2933; }
+  /* SHOULD FLAG (gradient-text + ai-color-palette): a real style rule. */
+  .gradient-heading {
+    background: linear-gradient(135deg, #7c3aed, #a855f7);
+    -webkit-background-clip: text;
+    background-clip: text;
+    -webkit-text-fill-color: transparent;
+    font-size: 44px;
+  }
+</style>
+</head>
+<body>
+<h1 class="gradient-heading">Ship Faster With Us</h1>
+
+<!-- SHOULD FLAG (gradient-text): the same construction inline. -->
+<h2 style="background: linear-gradient(90deg, #667eea, #764ba2); -webkit-background-clip: text; background-clip: text; -webkit-text-fill-color: transparent; font-size: 28px;">Inline gradient heading</h2>
+
+<!-- SHOULD FLAG (gradient-text, Tailwind): bg-clip-text + bg-gradient-to- classes. -->
+<h2 class="bg-clip-text bg-gradient-to-r from-purple-500 to-pink-500 text-transparent">Tailwind gradient heading</h2>
+
+<p>Body copy long enough to make this a real page for the scanners to read.</p>
+</body>
+</html>
diff --git a/tests/fixtures/antipatterns/css-in-prose-should-pass.html b/tests/fixtures/antipatterns/css-in-prose-should-pass.html
new file mode 100644
index 000000000..96f5282a1
--- /dev/null
+++ b/tests/fixtures/antipatterns/css-in-prose-should-pass.html
@@ -0,0 +1,77 @@
+<!DOCTYPE html>
+<!--
+  Regression fixture: CSS-property patterns appearing in prose, code samples,
+  and comments are documentation ABOUT css, not styling. The page-level
+  pattern checks must scan only real style carriers (<style> blocks, style=""
+  attribute values, linked stylesheets, class="" attribute values), never
+  rendered text. Live false positive that motivated this fixture: the
+  impeccable.style changelog line
+    "<code>background-clip: text</code> gradients stop tripping contrast"
+  tripped gradient-text on the raw-source scan, and the purple hex codes in
+  its rule documentation shared the same exposure via ai-color-palette.
+
+  Every case in this file SHOULD PASS: nothing here styles the page with the
+  documented patterns.
+-->
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>Docs about CSS anti-patterns</title>
+<style>
+  body { font-family: Georgia, 'Iowan Old Style', serif; margin: 0; padding: 32px 24px 40px; color: #1f2933; background: #fdfcf9; }
+  h1 { font-size: 34px; margin: 0 0 12px; }
+  h2 { font-size: 20px; margin: 28px 0 8px; }
+  p { font-size: 16px; max-width: 640px; }
+  pre { background: #f1efe9; padding: 16px; overflow-x: auto; font-size: 13px; }
+  code { font-family: 'SF Mono', ui-monospace, monospace; }
+</style>
+</head>
+<body>
+<h1>Changelog</h1>
+
+<!-- SHOULD PASS (gradient-text): the exact changelog shape — inline <code>
+     naming the property with "gradient" prose within the context window. -->
+<h2>Detector</h2>
+<p><code>background-clip: text</code> gradients stop tripping the contrast rules when the glyph fill is transparent.</p>
+
+<!-- SHOULD PASS (gradient-text + ai-color-palette): a <pre> CSS sample
+     documenting the pattern, purple hexes and all. -->
+<h2>What the rule catches</h2>
+<pre><code>.hero-title {
+  background: linear-gradient(135deg, #667eea, #764ba2);
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: #7c3aed;
+}</code></pre>
+
+<!-- SHOULD PASS (gradient-text, Tailwind form): prose naming the utility
+     classes without applying them. -->
+<p>The Tailwind form pairs bg-clip-text with bg-gradient-to-r on one element; the two utilities together are the tell.</p>
+
+<!-- SHOULD PASS (gradient-text): an HTML comment carrying the pattern.
+     background-clip: text; with a linear-gradient(90deg, #7c3aed, #a855f7)
+     fill is the construction the rule looks for. -->
+
+<!-- SHOULD PASS (pulsing-dot): a <pre> sample of the decorative live dot. -->
+<h2>Pulsing dots</h2>
+<pre><code>.status-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  animation: pulse 2s ease-in-out infinite;
+}</code></pre>
+
+<!-- SHOULD PASS (side-tab): a <pre> sample of the pseudo-element stripe. -->
+<h2>Side stripes</h2>
+<pre><code>.card::before {
+  content: "";
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  width: 4px;
+  background: #3b82f6;
+}</code></pre>
+
+</body>
+</html>