impeccable 3.3.0 → 3.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,7 @@
1
1
  import {
2
2
  BORDER_SAFE_TAGS,
3
+ EM_DASH_CHARS_PER_DASH,
4
+ EM_DASH_FLOOR,
3
5
  GENERIC_FONTS,
4
6
  KNOWN_SERIF_FONTS,
5
7
  OVERUSED_FONTS,
@@ -107,9 +109,21 @@ function checkColors(opts) {
107
109
  const findings = [];
108
110
 
109
111
  if (hasDirectText && textColor && !isEmojiOnly) {
112
+ // Gradient-clipped text (`background-clip: text`, typically with a
113
+ // transparent text-fill) paints its glyphs *with* the element's own
114
+ // gradient. The `color` value the cascade still reports is never painted,
115
+ // and the gradient is the fill, not a backdrop — so measuring `color`
116
+ // against that gradient (which resolveGradientStops picks up as the
117
+ // element's own background-image) is a guaranteed false positive
118
+ // (issue #409 Case A). Skip the backdrop-contrast checks; the gradient-text
119
+ // rule below still flags the pattern itself. Skipping a rule beats a false
120
+ // positive here — the true painted contrast can't be measured from `color`.
121
+ const isGradientClippedText = bgClip === 'text';
110
122
  // Run background-dependent checks against either a solid bg or, if the
111
123
  // ancestor is a gradient, against every gradient stop (use the worst case).
112
- const bgs = effectiveBg ? [effectiveBg] : (effectiveBgStops && effectiveBgStops.length ? effectiveBgStops : null);
124
+ const bgs = isGradientClippedText
125
+ ? null
126
+ : (effectiveBg ? [effectiveBg] : (effectiveBgStops && effectiveBgStops.length ? effectiveBgStops : null));
113
127
  if (bgs) {
114
128
  // Gray on colored background — flag if every stop is chromatic
115
129
  const textLum = relativeLuminance(textColor);
@@ -442,12 +456,15 @@ function checkHeroEyebrow(opts) {
442
456
  }];
443
457
  }
444
458
 
445
- function checkRepeatedSectionKickers(opts) {
446
- const { candidates, minCount = 3 } = opts;
447
- if (!Array.isArray(candidates) || candidates.length < minCount) return [];
459
+ // Outright ban: one kicker is one too many, so every collected candidate is
460
+ // a finding. The judgment lives in the candidate gate (isKickerCandidate) and
461
+ // the collector's context skips, not in a repetition count.
462
+ function checkKickerAboveHeading(opts) {
463
+ const { candidates } = opts;
464
+ if (!Array.isArray(candidates)) return [];
448
465
  return candidates.map(candidate => ({
449
- id: 'repeated-section-kickers',
450
- snippet: `repeated section kicker "${candidate.kickerText}" before ${candidate.headingTag} "${candidate.headingText}" (${candidates.length} on page)`,
466
+ id: 'kicker-above-heading',
467
+ snippet: `kicker "${candidate.kickerText}" above ${candidate.headingTag} "${candidate.headingText}"`,
451
468
  }));
452
469
  }
453
470
 
@@ -809,7 +826,13 @@ function isZeroOffset(value) {
809
826
  // never see it — pseudo-elements aren't part of the DOM the cascade walks —
810
827
  // so this scans stylesheet text directly, mirroring the border rule's
811
828
  // gates: >= 3px thick, chromatic fill, full height against a side edge.
812
- function scanCssTextForPseudoStripe(content) {
829
+ function scanCssTextForPseudoStripe(rawContent) {
830
+ // Blank comment bodies byte-for-byte so commented-out rules are not
831
+ // scanned as live CSS and every rule keeps its source offset (each
832
+ // finding carries `index` so line-based callers can attribute it and
833
+ // line-scoped inline ignores can match).
834
+ const content = String(rawContent || '').replace(/\/\*[\s\S]*?\*\//g,
835
+ (block) => block.replace(/[^\n]/g, ' '));
813
836
  const customProps = collectCssCustomProps(content);
814
837
  const findings = [];
815
838
  const seen = new Set();
@@ -918,9 +941,13 @@ function scanCssTextForPseudoStripe(content) {
918
941
 
919
942
  if (seen.has(selector)) continue;
920
943
  seen.add(selector);
944
+ // The selector group absorbs whitespace trailing the previous rule;
945
+ // advance past it so `index` points at the selector itself.
946
+ const selectorStart = m.index + (m[1].length - m[1].trimStart().length);
921
947
  findings.push({
922
948
  id: 'side-tab',
923
949
  snippet: `${selector} — absolute ${thicknessPx}px pseudo-element stripe (${edge}: 0)`,
950
+ index: selectorStart,
924
951
  });
925
952
  }
926
953
  return findings;
@@ -1667,29 +1694,54 @@ function resolveBackground(el, win, customPropMap) {
1667
1694
  // Walk parents looking for a gradient background and return its color stops.
1668
1695
  // Used as a fallback when resolveBackground() returns null because the
1669
1696
  // effective background is a gradient (no single solid color to compare against).
1670
- function resolveGradientStops(el, win) {
1697
+ function resolveGradientStops(el, win, customPropMap) {
1671
1698
  let current = el;
1672
1699
  while (current && current.nodeType === 1) {
1673
1700
  const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
1674
1701
  const bgImage = style.backgroundImage || '';
1702
+ let stops = null;
1675
1703
  if (bgImage && bgImage !== 'none' && /gradient/i.test(bgImage)) {
1676
- const stops = parseGradientColors(bgImage);
1677
- if (stops.length > 0) return stops;
1704
+ const parsed = parseGradientColors(bgImage);
1705
+ if (parsed.length > 0) stops = parsed;
1678
1706
  }
1679
- if (!DETECTOR_IS_BROWSER) {
1707
+ if (!stops && !DETECTOR_IS_BROWSER) {
1680
1708
  // jsdom doesn't decompose `background:` shorthand — peek at the raw inline style
1681
1709
  const rawStyle = current.getAttribute?.('style') || '';
1682
1710
  const bgMatch = rawStyle.match(/background(?:-image)?\s*:\s*([^;]+)/i);
1683
1711
  if (bgMatch && /gradient/i.test(bgMatch[1])) {
1684
- const stops = parseGradientColors(bgMatch[1]);
1685
- if (stops.length > 0) return stops;
1712
+ const parsed = parseGradientColors(bgMatch[1]);
1713
+ if (parsed.length > 0) stops = parsed;
1686
1714
  }
1687
1715
  }
1716
+ if (stops) return compositeGradientStops(stops, current, win, customPropMap);
1688
1717
  current = current.parentElement;
1689
1718
  }
1690
1719
  return null;
1691
1720
  }
1692
1721
 
1722
+ // A translucent gradient stop (e.g. a faint `rgba(52,192,168,0.09)` accent
1723
+ // glow) paints over whatever surface sits beneath the gradient — the browser
1724
+ // composites it, so its effective color is far closer to the base than to the
1725
+ // full-opacity accent. Treating the stop as opaque flags every text child of a
1726
+ // softly-glowing section as low-contrast (issue #409 Case B). Composite each
1727
+ // alpha stop over the resolved surface beneath the gradient element. When that
1728
+ // surface isn't resolvable (another gradient above, no opaque ancestor), drop
1729
+ // the translucent stop rather than guess: a dropped stop can't manufacture a
1730
+ // false finding, and skipping beats a wrong ratio.
1731
+ function compositeGradientStops(stops, gradientEl, win, customPropMap) {
1732
+ const hasAlpha = stops.some(s => (s.a ?? 1) < 0.99);
1733
+ if (!hasAlpha) return stops;
1734
+ const base = resolveBackground(gradientEl.parentElement || gradientEl, win, customPropMap);
1735
+ const out = [];
1736
+ for (const s of stops) {
1737
+ const a = s.a ?? 1;
1738
+ if (a >= 0.99) { out.push(s); continue; }
1739
+ if (base) out.push(compositeColorOver(s, base));
1740
+ // else: unresolvable base — drop the translucent stop (skip, don't guess).
1741
+ }
1742
+ return out.length ? out : null;
1743
+ }
1744
+
1693
1745
  // Parse a single CSS length token to pixels. Accepts "12px", "50%", a
1694
1746
  // shorthand like "12px 4px" (uses the first value), or empty / null.
1695
1747
  // Returns the pixel value, or null when the input is unparseable.
@@ -2339,7 +2391,7 @@ function parseColorResolved(str, customPropMap) {
2339
2391
  return parseAnyColor(resolved);
2340
2392
  }
2341
2393
 
2342
- const REPEATED_KICKER_SKIP_SELECTOR = [
2394
+ const KICKER_SKIP_SELECTOR = [
2343
2395
  'nav',
2344
2396
  'form',
2345
2397
  'table',
@@ -2358,7 +2410,7 @@ const REPEATED_KICKER_SKIP_SELECTOR = [
2358
2410
  '[data-impeccable-allow-kickers]',
2359
2411
  ].join(',');
2360
2412
 
2361
- const REPEATED_KICKER_CARD_CONTEXT_SELECTOR = [
2413
+ const KICKER_CARD_CONTEXT_SELECTOR = [
2362
2414
  'article',
2363
2415
  'button',
2364
2416
  'a',
@@ -2376,23 +2428,32 @@ function cleanInlineText(el) {
2376
2428
  .trim();
2377
2429
  }
2378
2430
 
2379
- function isRepeatedKickerCardContext(heading, kicker) {
2380
- const item = heading.closest?.(REPEATED_KICKER_CARD_CONTEXT_SELECTOR);
2431
+ function isKickerCardContext(heading, kicker) {
2432
+ const item = heading.closest?.(KICKER_CARD_CONTEXT_SELECTOR);
2381
2433
  return Boolean(item && (!item.contains || item.contains(kicker)));
2382
2434
  }
2383
2435
 
2384
- function isRepeatedKickerCandidate(opts) {
2436
+ // Meta lines above headlines join category and date (or path crumbs) with
2437
+ // separator glyphs, or carry a year. A kicker is one short phrase; metadata
2438
+ // keeps its markers.
2439
+ const KICKER_META_TEXT_RE = /[·•|]|\s[\/›»>]\s|\b(19|20)\d{2}\b/;
2440
+ // Legal and document numbering: "Section 4.2", "Article IX", "§ 12.3",
2441
+ // dotted decimal outlines. The label identifies the clause, so it stays.
2442
+ const KICKER_DOC_NUMBERING_RE = /^(§|\d+(\.\d+)+\b|(section|article|clause|appendix|exhibit|schedule|chapter|part|rule|title)\s+([\divxlc]+\b|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve)\b)/i;
2443
+
2444
+ function isKickerCandidate(opts) {
2385
2445
  const {
2386
- headingTag,
2446
+ headingLevel,
2387
2447
  headingText,
2388
2448
  headingFontSize,
2389
2449
  kickerTag,
2390
2450
  kickerText,
2391
2451
  kickerTextTransform,
2452
+ kickerFontVariant,
2392
2453
  kickerFontSize,
2393
2454
  kickerLetterSpacing,
2394
2455
  } = opts;
2395
- if (!['h2', 'h3', 'h4'].includes(headingTag)) return false;
2456
+ if (!headingLevel || headingLevel > 4) return false;
2396
2457
  if (!headingText || headingText.length < 3) return false;
2397
2458
  if (/^\/[\w-]+/i.test(headingText.replace(/^"|"$/g, '').trim())) return false;
2398
2459
  if (!(headingFontSize >= 20)) return false;
@@ -2400,9 +2461,13 @@ function isRepeatedKickerCandidate(opts) {
2400
2461
  if (!['p', 'span', 'div', 'small'].includes(kickerTag)) return false;
2401
2462
  if (!kickerText || kickerText.length < 2 || kickerText.length > 34) return false;
2402
2463
  if (/^step\s*\d+/i.test(kickerText) || /^\d{1,2}$/.test(kickerText)) return false;
2464
+ if (KICKER_META_TEXT_RE.test(kickerText)) return false;
2465
+ if (KICKER_DOC_NUMBERING_RE.test(kickerText)) return false;
2403
2466
 
2467
+ const isSmallCaps = /small-caps/.test(kickerFontVariant || '');
2404
2468
  const isUppercased = kickerTextTransform === 'uppercase'
2405
- || (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText));
2469
+ || (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText))
2470
+ || isSmallCaps;
2406
2471
  if (!isUppercased) return false;
2407
2472
  if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false;
2408
2473
  const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08);
@@ -2410,37 +2475,64 @@ function isRepeatedKickerCandidate(opts) {
2410
2475
  return true;
2411
2476
  }
2412
2477
 
2413
- function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpacing) {
2478
+ // Resolve a heading level for the anchor element: 1-4 for h1-h4, aria-level
2479
+ // (default 2) for role="heading" elements, 0 otherwise.
2480
+ function kickerHeadingLevel(heading) {
2481
+ const tag = heading.tagName.toLowerCase();
2482
+ const byTag = /^h([1-6])$/.exec(tag);
2483
+ if (byTag) return parseInt(byTag[1], 10);
2484
+ const role = heading.getAttribute?.('role') || '';
2485
+ if (role.toLowerCase() !== 'heading') return 0;
2486
+ const ariaLevel = parseInt(heading.getAttribute?.('aria-level') || '', 10);
2487
+ return Number.isFinite(ariaLevel) && ariaLevel >= 1 ? ariaLevel : 2;
2488
+ }
2489
+
2490
+ function collectKickerCandidates(doc, getStyle, resolveLetterSpacing) {
2414
2491
  const candidates = [];
2415
- for (const heading of doc.querySelectorAll('h2, h3, h4')) {
2416
- if (heading.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
2492
+ for (const heading of doc.querySelectorAll('h1, h2, h3, h4, [role="heading"]')) {
2493
+ const headingLevel = kickerHeadingLevel(heading);
2494
+ if (!headingLevel || headingLevel > 4) continue;
2495
+ if (heading.closest?.(KICKER_SKIP_SELECTOR)) continue;
2496
+ // Application contexts (tab panels, dialogs) use compact context labels
2497
+ // above headings to describe state, not to decorate. Same carve-out the
2498
+ // hero-eyebrow rule makes.
2499
+ if (heading.closest?.('[role="tabpanel"], [role="dialog"], [role="application"], dialog')) continue;
2417
2500
  const kicker = heading.previousElementSibling;
2418
- if (!kicker || kicker.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
2419
- if (isRepeatedKickerCardContext(heading, kicker)) continue;
2501
+ if (!kicker || kicker.closest?.(KICKER_SKIP_SELECTOR)) continue;
2502
+ if (isKickerCardContext(heading, kicker)) continue;
2420
2503
 
2421
2504
  const headingStyle = getStyle(heading);
2422
2505
  const kickerStyle = getStyle(kicker);
2506
+ const headingTag = heading.tagName.toLowerCase();
2423
2507
  const headingText = (heading.textContent || '').replace(/\s+/g, ' ').trim();
2424
2508
  const kickerText = cleanInlineText(kicker) || (kicker.textContent || '').replace(/\s+/g, ' ').trim();
2425
2509
  const headingFontSize = resolveLetterSpacing(headingStyle.fontSize || '', 16) || parseFloat(headingStyle.fontSize) || 0;
2426
2510
  const kickerFontSize = resolveLetterSpacing(kickerStyle.fontSize || '', 16) || parseFloat(kickerStyle.fontSize) || 0;
2427
2511
  const kickerLetterSpacing = resolveLetterSpacing(kickerStyle.letterSpacing || '', kickerFontSize);
2428
2512
 
2429
- if (!isRepeatedKickerCandidate({
2430
- headingTag: heading.tagName.toLowerCase(),
2513
+ if (!isKickerCandidate({
2514
+ headingLevel,
2431
2515
  headingText,
2432
2516
  headingFontSize,
2433
2517
  kickerTag: kicker.tagName.toLowerCase(),
2434
2518
  kickerText,
2435
2519
  kickerTextTransform: kickerStyle.textTransform || '',
2520
+ kickerFontVariant: `${kickerStyle.fontVariant || ''} ${kickerStyle.fontVariantCaps || ''}`,
2436
2521
  kickerFontSize,
2437
2522
  kickerLetterSpacing,
2438
2523
  })) {
2439
2524
  continue;
2440
2525
  }
2441
2526
 
2527
+ // A tracked-caps eyebrow above a hero-scale h1 belongs to
2528
+ // hero-eyebrow-chip (which also covers the accent-bold and dash-prefix
2529
+ // stylings there). Stand down so one element gets one finding.
2530
+ if (headingTag === 'h1' && headingFontSize >= 48 && kickerLetterSpacing >= 1.6) {
2531
+ continue;
2532
+ }
2533
+
2442
2534
  candidates.push({
2443
- headingTag: heading.tagName.toLowerCase(),
2535
+ headingTag,
2444
2536
  headingText: headingText.replace(/^"|"$/g, '').slice(0, 60),
2445
2537
  kickerText: kickerText.slice(0, 40),
2446
2538
  });
@@ -2448,17 +2540,17 @@ function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpac
2448
2540
  return candidates;
2449
2541
  }
2450
2542
 
2451
- function checkRepeatedSectionKickersDOM() {
2452
- const candidates = collectRepeatedSectionKickerCandidates(
2543
+ function checkKickerAboveHeadingDOM() {
2544
+ const candidates = collectKickerCandidates(
2453
2545
  document,
2454
2546
  (el) => getComputedStyle(el),
2455
2547
  (value, fontSize) => resolveLengthPx(value, fontSize) || 0,
2456
2548
  );
2457
- return checkRepeatedSectionKickers({ candidates });
2549
+ return checkKickerAboveHeading({ candidates });
2458
2550
  }
2459
2551
 
2460
2552
  // ── Numbered section labels ─────────────────────────────────────────────────
2461
- // Sibling of the repeated-kicker rule: instead of a tracked uppercase word,
2553
+ // Sibling of the kicker-above-heading rule: instead of a tracked uppercase word,
2462
2554
  // the section scaffold is a tiny numeric index riding beside each section
2463
2555
  // heading — bare and zero-padded, or an index joined to a short micro-label
2464
2556
  // by a separator glyph. The kicker rule deliberately excludes bare 1-2 digit
@@ -2512,7 +2604,7 @@ function collectNumberedSectionLabelCandidates(doc, getStyle, resolveLetterSpaci
2512
2604
  const candidates = [];
2513
2605
  const seenLabels = new Set();
2514
2606
  for (const heading of doc.querySelectorAll('h2, h3, h4')) {
2515
- if (heading.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
2607
+ if (heading.closest?.(KICKER_SKIP_SELECTOR)) continue;
2516
2608
  // The index sits either directly before the heading, or before the
2517
2609
  // wrapper the heading leads (label | <div><h2>…</h2>…</div>).
2518
2610
  let label = heading.previousElementSibling;
@@ -2522,9 +2614,9 @@ function collectNumberedSectionLabelCandidates(doc, getStyle, resolveLetterSpaci
2522
2614
  if (firstChild === heading) label = parent.previousElementSibling;
2523
2615
  }
2524
2616
  if (!label || seenLabels.has(label)) continue;
2525
- if (label.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
2617
+ if (label.closest?.(KICKER_SKIP_SELECTOR)) continue;
2526
2618
  if (HEADING_TAGS.has(label.tagName.toLowerCase())) continue;
2527
- if (isRepeatedKickerCardContext(heading, label)) continue;
2619
+ if (isKickerCardContext(heading, label)) continue;
2528
2620
 
2529
2621
  const labelText = cleanInlineText(label) || (label.textContent || '').replace(/\s+/g, ' ').trim();
2530
2622
  const parsed = parseNumberedLabelText(labelText);
@@ -2594,6 +2686,33 @@ function checkNumberedSectionLabelsDOM() {
2594
2686
  return checkNumberedSectionLabels({ candidates });
2595
2687
  }
2596
2688
 
2689
+ // Em-dash overuse (ADVISORY) — pure logic shared by the browser DOM check.
2690
+ // Mirrors the regex/static-HTML analyzer in engines/regex/detect-text.mjs:
2691
+ // two gates (absolute floor + density) so a long article using a few dashes is
2692
+ // left alone while a short, dash-per-clause page is flagged. Operates on
2693
+ // already-rendered text, so no HTML-entity decoding is needed (the browser has
2694
+ // resolved `&mdash;` to the literal glyph). Exported for jsdom unit tests.
2695
+ function checkEmDashOveruse(text) {
2696
+ const body = typeof text === 'string' ? text.replace(/\s+/g, ' ') : '';
2697
+ let count = 0;
2698
+ const re = /[—]|--(?=\S)/g;
2699
+ while (re.exec(body) !== null) count++;
2700
+ if (count < EM_DASH_FLOOR) return [];
2701
+ if (body.length > count * EM_DASH_CHARS_PER_DASH) return [];
2702
+ return [{ id: 'em-dash-overuse', snippet: `${count} em-dashes in body text` }];
2703
+ }
2704
+
2705
+ function checkEmDashOveruseDOM() {
2706
+ const body = document.body;
2707
+ if (!body) return [];
2708
+ // innerText reflects rendered, visible text; fall back to textContent for
2709
+ // engines (jsdom) that don't compute innerText.
2710
+ const text = typeof body.innerText === 'string' && body.innerText
2711
+ ? body.innerText
2712
+ : (body.textContent || '');
2713
+ return checkEmDashOveruse(text);
2714
+ }
2715
+
2597
2716
  function checkElementMotionDOM(el) {
2598
2717
  const tag = el.tagName.toLowerCase();
2599
2718
  if (SAFE_TAGS.has(tag)) return [];
@@ -2700,6 +2819,131 @@ function checkElementAIPaletteDOM(el) {
2700
2819
  return findings;
2701
2820
  }
2702
2821
 
2822
+ // ─── Decorative radial spotlight glow ───────────────────────────────────────
2823
+ // A soft, low-opacity chromatic radial-gradient fading to transparent, painted
2824
+ // as a decorative wash behind a hero or section. The translucent sibling of the
2825
+ // `radial-halo` tell: `radial-halo` requires a saturated, near-opaque center on
2826
+ // a dark page; this catches the low-alpha "spotlight" the halo gate lets slip
2827
+ // (e.g. `radial-gradient(circle at 52% 38%, rgba(80,111,255,0.26),
2828
+ // transparent 44%)`). The two alpha bands are disjoint, so they never
2829
+ // double-report the same declaration.
2830
+ const SPOTLIGHT_COLOR_TOKEN_RE = /(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb|color-mix)\([^)]*(?:\([^)]*\))?[^)]*\)|#[0-9a-f]{3,8}\b|\btransparent\b/i;
2831
+
2832
+ // Parse the FIRST non-repeating radial-gradient in a background value into its
2833
+ // ordered color stops. Each stop is { color: {r,g,b,a} | null, transparent }.
2834
+ // Returns null when there is no plain radial-gradient to read.
2835
+ function parseRadialGradientStops(value) {
2836
+ if (!value || !/radial-gradient/i.test(value)) return null;
2837
+ const gradRe = /(repeating-)?radial-gradient\(/gi;
2838
+ let g;
2839
+ while ((g = gradRe.exec(value)) !== null) {
2840
+ if (g[1]) continue; // repeating-* is a pattern, not a spotlight
2841
+ let depth = 0, end = -1;
2842
+ const open = value.indexOf('(', g.index);
2843
+ for (let i = open; i < value.length; i++) {
2844
+ if (value[i] === '(') depth++;
2845
+ else if (value[i] === ')') { depth--; if (depth === 0) { end = i; break; } }
2846
+ }
2847
+ if (end < 0) return null;
2848
+ const args = splitTopLevelCommas(value.slice(open + 1, end));
2849
+ // The optional prelude (shape / size / `at <pos>`) carries no color token.
2850
+ const stopArgs = args.filter(a => SPOTLIGHT_COLOR_TOKEN_RE.test(a));
2851
+ if (stopArgs.length < 2) return null;
2852
+ return stopArgs.map(a => {
2853
+ const tok = a.match(SPOTLIGHT_COLOR_TOKEN_RE);
2854
+ if (!tok) return { color: null, transparent: false };
2855
+ if (/^transparent$/i.test(tok[0])) return { color: null, transparent: true };
2856
+ const color = parseAnyColor(tok[0]);
2857
+ return { color, transparent: !!color && (color.a ?? 1) <= 0.05 };
2858
+ });
2859
+ }
2860
+ return null;
2861
+ }
2862
+
2863
+ // Pure gate. `label` is a stable identifier the fixture test keys on.
2864
+ function checkRadialSpotlight({ gradientValue, width, height, label }) {
2865
+ const stops = parseRadialGradientStops(gradientValue);
2866
+ if (!stops || stops.length < 2) return [];
2867
+
2868
+ // Must fade OUT: the last stop is transparent / near-zero alpha. A gradient
2869
+ // between two visible surfaces is a real background, not a floating glow.
2870
+ const last = stops[stops.length - 1];
2871
+ const lastAlpha = last.transparent ? 0 : (last.color ? (last.color.a ?? 1) : 1);
2872
+ if (lastAlpha > 0.05) return [];
2873
+
2874
+ // The visible (non-transparent, parseable) color stops.
2875
+ const colored = stops.filter(s => !s.transparent && s.color && (s.color.a ?? 1) > 0.05);
2876
+ if (colored.length === 0) return [];
2877
+ // One soft glow, not a multi-color composition: at most two visible stops.
2878
+ if (colored.length > 2) return [];
2879
+ // Every visible stop must be LOW opacity. Any opaque stop means a real fill
2880
+ // or a saturated halo (`radial-halo`'s job), not this translucent spotlight.
2881
+ if (colored.some(s => (s.color.a ?? 1) >= 0.45)) return [];
2882
+ // At least one visible stop must be chromatic. A neutral (grayscale)
2883
+ // near-black / near-white vignette is a legitimate lighting move, exempt.
2884
+ const chromatic = colored.find(s => hasChroma(s.color, 24));
2885
+ if (!chromatic) return [];
2886
+
2887
+ // Decorative-scale gate. Badges, avatars, and actual small "lights" are
2888
+ // exempt; a spotlight glow only reads as slop when it washes a large surface.
2889
+ if (!(width >= 240 && height >= 160)) return [];
2890
+
2891
+ const alpha = (chromatic.color.a ?? 1).toFixed(2);
2892
+ const name = label || 'section';
2893
+ return [{
2894
+ id: 'radial-spotlight-glow',
2895
+ snippet: `radial-gradient spotlight glow "${name}" (${colorToHex(chromatic.color)} a${alpha} → transparent) on ${Math.round(width)}x${Math.round(height)} surface`,
2896
+ }];
2897
+ }
2898
+
2899
+ // Read the raw radial-gradient source off an element's computed style, with a
2900
+ // fallback to the `background` shorthand and the inline style attribute for
2901
+ // engines that don't decompose the shorthand into backgroundImage.
2902
+ function elementGradientValue(style, el) {
2903
+ const bgImage = style.backgroundImage && style.backgroundImage !== 'none' ? style.backgroundImage : '';
2904
+ if (/radial-gradient/i.test(bgImage)) return bgImage;
2905
+ const bg = style.background || '';
2906
+ if (/radial-gradient/i.test(bg)) return bg;
2907
+ const rawStyle = el?.getAttribute?.('style') || '';
2908
+ const m = rawStyle.match(/background(?:-image)?\s*:\s*([^;]+)/i);
2909
+ if (m && /radial-gradient/i.test(m[1])) return m[1];
2910
+ return '';
2911
+ }
2912
+
2913
+ function spotlightLabel(el) {
2914
+ const dataName = el.getAttribute?.('data-name');
2915
+ if (dataName) return dataName;
2916
+ if (typeof el.id === 'string' && el.id) return el.id;
2917
+ const cls = typeof el.className === 'string' ? el.className.trim().split(/\s+/)[0] : '';
2918
+ if (cls) return cls;
2919
+ return el.tagName ? el.tagName.toLowerCase() : 'section';
2920
+ }
2921
+
2922
+ function checkElementRadialSpotlightDOM(el) {
2923
+ const style = getComputedStyle(el);
2924
+ const gradientValue = elementGradientValue(style, el);
2925
+ if (!gradientValue) return [];
2926
+ const rect = el.getBoundingClientRect();
2927
+ return checkRadialSpotlight({
2928
+ gradientValue,
2929
+ width: rect.width,
2930
+ height: rect.height,
2931
+ label: spotlightLabel(el),
2932
+ });
2933
+ }
2934
+
2935
+ function checkElementRadialSpotlight(el, style, tag, window) {
2936
+ const gradientValue = elementGradientValue(style, el);
2937
+ if (!gradientValue) return [];
2938
+ // Static engine does no layout — read explicit pixel dimensions from CSS.
2939
+ return checkRadialSpotlight({
2940
+ gradientValue,
2941
+ width: parseFloat(style.width) || 0,
2942
+ height: parseFloat(style.height) || 0,
2943
+ label: spotlightLabel(el),
2944
+ });
2945
+ }
2946
+
2703
2947
  const QUALITY_TEXT_TAGS = new Set(['p', 'li', 'td', 'th', 'dd', 'blockquote', 'figcaption']);
2704
2948
 
2705
2949
  // Resolve a CSS font-size value to pixels by walking up the parent chain.
@@ -2821,6 +3065,55 @@ function textDescendantsFlushSides(el, rect) {
2821
3065
  return flush;
2822
3066
  }
2823
3067
 
3068
+ // Screen-reader-only ("visually hidden") text is exempt from the tiny-text
3069
+ // floors: it is never rendered, so its size is irrelevant. Detect the two
3070
+ // standard idioms — a known sr-only class on the element or an ancestor, and
3071
+ // the clip / 1px-box pattern. Works in both jsdom (declared styles) and the
3072
+ // browser (computed styles).
3073
+ const SR_ONLY_SELECTOR = '.sr-only, .visually-hidden, .visuallyhidden, .screen-reader, .screen-reader-only, .screenreader, .a11y-hidden, .hidden-visually, [class*="sr-only" i], [class*="visually-hidden" i], [class*="visuallyhidden" i], [class*="screen-reader" i], [class*="screenreader" i]';
3074
+ function isVisuallyHidden(el, style) {
3075
+ if ((el.matches && el.matches(SR_ONLY_SELECTOR)) || (el.closest && el.closest(SR_ONLY_SELECTOR))) return true;
3076
+ const pos = style.position || '';
3077
+ if (pos === 'absolute' || pos === 'fixed') {
3078
+ const clip = style.clip || '';
3079
+ const clipPath = style.clipPath || style.webkitClipPath || style['clip-path'] || '';
3080
+ if (/rect\(\s*0/.test(clip) || /inset\(\s*(?:50%|99|100%)/.test(clipPath)) return true;
3081
+ const w = parseFloat(style.width);
3082
+ const h = parseFloat(style.height);
3083
+ const overflow = style.overflow || '';
3084
+ if ((w === 1 || h === 1) && (overflow === 'hidden' || overflow === 'clip')) return true;
3085
+ }
3086
+ return false;
3087
+ }
3088
+
3089
+ // Elements whose text is never painted: document metadata and script/style
3090
+ // payloads. Their JS / CSS / JSON-LD text satisfies `hasDirectText`, and on
3091
+ // sites that set `html { font-size: 62.5% }` their inherited computed size is
3092
+ // 10px — so the text-size floors flag them as tiny body copy even though
3093
+ // nothing renders (issue #408: dozens of phantom "10px body text" findings on
3094
+ // every Shopify page). Exclude them, plus anything the cascade resolves to
3095
+ // display:none / visibility:hidden. The jsdom path can't lay out, so the
3096
+ // tag/attribute-based exclusions carry the weight there; the display checks are
3097
+ // computed-style reads that resolve without layout in both adapters.
3098
+ const NON_RENDERED_TAGS = new Set([
3099
+ 'script', 'style', 'title', 'noscript', 'template', 'head',
3100
+ 'meta', 'link', 'base', 'param', 'source', 'track', 'datalist',
3101
+ 'col', 'colgroup', 'map', 'area',
3102
+ ]);
3103
+ function isNonRenderedText(el, tag, style) {
3104
+ const t = (tag || '').toLowerCase();
3105
+ if (NON_RENDERED_TAGS.has(t)) return true;
3106
+ // Descendants of <head> never render even when the tag itself would
3107
+ // (some sites nest <noscript>/<template> content there).
3108
+ if (el && el.closest && el.closest('head')) return true;
3109
+ if (style) {
3110
+ if (style.display === 'none') return true;
3111
+ const vis = style.visibility;
3112
+ if (vis === 'hidden' || vis === 'collapse') return true;
3113
+ }
3114
+ return false;
3115
+ }
3116
+
2824
3117
  // Pure quality checks. Most run on computed CSS and DOM-only inputs (work in
2825
3118
  // jsdom and the browser). Two checks (line-length, cramped-padding) gate on
2826
3119
  // element rect dimensions, which jsdom can't compute — pass `rect: null` from
@@ -2831,8 +3124,13 @@ function textDescendantsFlushSides(el, rect) {
2831
3124
  function checkQuality(opts) {
2832
3125
  const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80, viewportWidth = 0, win = null } = opts;
2833
3126
  const findings = [];
2834
- // Skip browser extension injected elements
2835
- const elId = el.id || '';
3127
+ // Skip browser extension injected elements. Read the id via getAttribute
3128
+ // whenever `el.id` is not a string: on a <form> (and other
3129
+ // [LegacyOverrideBuiltIns] hosts) a named control like <input name="id">
3130
+ // shadows the builtin `id` getter and returns the control element, whose
3131
+ // `.startsWith` is undefined and throws (issue #407 — every Shopify product
3132
+ // form ships an <input name="id">).
3133
+ const elId = typeof el.id === 'string' ? el.id : (el.getAttribute?.('id') || '');
2836
3134
  if (elId.startsWith('claude-') || elId.startsWith('cic-')) return findings;
2837
3135
 
2838
3136
  // --- Line length too long --- (browser-only: needs rect.width)
@@ -3100,11 +3398,67 @@ function checkQuality(opts) {
3100
3398
  const skipTags = ['sub', 'sup', 'code', 'kbd', 'samp', 'var', 'caption', 'figcaption'];
3101
3399
  const inUIContext = el.closest && el.closest('button, a, label, summary, pre, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="option"], nav, footer, [aria-hidden="true"], [class*="badge" i], [class*="caption" i], [class*="chip" i], [class*="code" i], [class*="console" i], [class*="diff" i], [class*="label" i], [class*="meta" i], [class*="mock" i], [class*="pill" i], [class*="preview" i], [class*="tag" i], [class*="terminal" i], [class*="writes" i]');
3102
3400
  const isUppercase = style.textTransform === 'uppercase';
3103
- if (!skipTags.includes(tag) && !inUIContext && !isUppercase) {
3401
+ if (!skipTags.includes(tag) && !inUIContext && !isUppercase && !isNonRenderedText(el, tag, style)) {
3104
3402
  findings.push({ id: 'tiny-text', snippet: `${fontSize}px body text` });
3105
3403
  }
3106
3404
  }
3107
3405
 
3406
+ // --- Undersized functional / UI text ---
3407
+ // Complements `tiny-text` above, which owns long body copy and deliberately
3408
+ // EXEMPTS the UI furniture layer (nav, footer, links, buttons, labels,
3409
+ // uppercase micro-labels). This rule targets exactly that blind spot: the
3410
+ // interactive and short content-bearing text — nav items, buttons, labels,
3411
+ // table cells, meta rows, timecodes — shipped below an 11px floor.
3412
+ //
3413
+ // The live failure it closes: a build shipped its entire furniture layer at
3414
+ // 8px, and the design hook waved it through because 8px had been added to
3415
+ // the DESIGN.md size ramp. Being on the ramp is a token argument, not a
3416
+ // legibility one, so this rule ignores the design system entirely — a value
3417
+ // on the ramp is still flagged.
3418
+ //
3419
+ // Floors: 11px for anything functional. The floor holds inside a footer;
3420
+ // only NON-interactive legal smallprint gets the softer 10px floor. Exempts
3421
+ // sup/sub, visually-hidden (sr-only) text, and code/terminal contexts.
3422
+ // Uppercase letterspaced micro-labels are still functional — not exempt.
3423
+ {
3424
+ const directText = [...el.childNodes]
3425
+ .filter(n => n.nodeType === 3)
3426
+ .map(n => n.textContent || '')
3427
+ .join('')
3428
+ .replace(/\s+/g, ' ')
3429
+ .trim();
3430
+ const dtLen = directText.length;
3431
+ // `option` renders (in native select popups) so it stays a local skip;
3432
+ // script/style/title/noscript/head-descendants and display:none /
3433
+ // visibility:hidden are handled by isNonRenderedText (shared with tiny-text).
3434
+ const UI_SKIP_TAGS = new Set(['sub', 'sup', 'option']);
3435
+ // jsdom resolves the parent chain in resolveFontSizePx, so em/rem/%-sized
3436
+ // text that computes at or above the floor never reaches here. The browser
3437
+ // adapter additionally catches values only resolvable with real layout
3438
+ // (e.g. viewport-relative units, cascade winners set in linked sheets).
3439
+ if (fontSize > 0 && fontSize < 11 && dtLen >= 2 && !UI_SKIP_TAGS.has(tag) && !isNonRenderedText(el, tag, style)) {
3440
+ const EXEMPT_CONTEXT = 'pre, code, kbd, samp, var, svg, [aria-hidden="true"], [class*="terminal" i], [class*="console" i], [class*="code" i], [class*="mock" i], [class*="editor" i], [class*="syntax" i], [class*="diff" i]';
3441
+ const isExemptContext = (el.matches && el.matches(EXEMPT_CONTEXT)) || (el.closest && el.closest(EXEMPT_CONTEXT));
3442
+ if (!isExemptContext && !isVisuallyHidden(el, style)) {
3443
+ const INTERACTIVE = 'a[href], button, summary, label, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="checkbox"], [role="radio"], [role="switch"], [role="treeitem"], [tabindex]';
3444
+ const FURNITURE = 'nav, [role="navigation"], td, th, [role="gridcell"], [role="cell"], caption, figcaption, dt, dd, footer, [class*="meta" i], [class*="label" i], [class*="badge" i], [class*="chip" i], [class*="pill" i], [class*="tag" i], [class*="kicker" i], [class*="eyebrow" i], [class*="breadcrumb" i], [class*="timestamp" i], [class*="category" i], [class*="caption" i], [class*="nav" i]';
3445
+ const SMALLPRINT = 'small, footer, [class*="legal" i], [class*="copyright" i], [class*="fineprint" i], [class*="fine-print" i], [class*="smallprint" i], [class*="small-print" i], [class*="disclaimer" i], [class*="disclosure" i], [class*="footnote" i]';
3446
+ const isInteractive = (el.matches && el.matches(INTERACTIVE)) || (el.closest && el.closest(INTERACTIVE));
3447
+ const isFurniture = (el.matches && el.matches(FURNITURE)) || (el.closest && el.closest(FURNITURE));
3448
+ const isSmallprint = (el.matches && el.matches(SMALLPRINT)) || (el.closest && el.closest(SMALLPRINT));
3449
+ const floor = (!isInteractive && isSmallprint) ? 10 : 11;
3450
+ // Fire on functional text only: interactive, structural furniture, or
3451
+ // any short (<=20-char) run — the label / meta / timecode shape. Long
3452
+ // non-furniture body copy stays with `tiny-text`, so the two rules
3453
+ // never double-flag the same element.
3454
+ if (fontSize < floor && (isInteractive || isFurniture || dtLen <= 20)) {
3455
+ const excerpt = directText.slice(0, 40);
3456
+ findings.push({ id: 'undersized-ui-text', snippet: `${fontSize}px functional text "${excerpt}" (below ${floor}px floor)` });
3457
+ }
3458
+ }
3459
+ }
3460
+ }
3461
+
3108
3462
  // --- All-caps body text ---
3109
3463
  if (hasDirectText && textLen > 30 && style.textTransform === 'uppercase') {
3110
3464
  if (!['h1','h2','h3','h4','h5','h6'].includes(tag)) {
@@ -3295,7 +3649,7 @@ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInhe
3295
3649
  textColor,
3296
3650
  bgColor: ownBg,
3297
3651
  effectiveBg: finalEffectiveBg,
3298
- effectiveBgStops: finalEffectiveBg ? null : resolveGradientStops(el, window),
3652
+ effectiveBgStops: finalEffectiveBg ? null : resolveGradientStops(el, window, customPropMap),
3299
3653
  fontSize: parseFloat(style.fontSize) || 16,
3300
3654
  fontWeight: parseInt(style.fontWeight) || 400,
3301
3655
  hasDirectText,
@@ -3435,13 +3789,13 @@ function checkElementHeroEyebrow(el, style, tag, window, customPropMap) {
3435
3789
  });
3436
3790
  }
3437
3791
 
3438
- function checkRepeatedSectionKickersFromDoc(doc, win) {
3439
- const candidates = collectRepeatedSectionKickerCandidates(
3792
+ function checkKickerAboveHeadingFromDoc(doc, win) {
3793
+ const candidates = collectKickerCandidates(
3440
3794
  doc,
3441
3795
  (el) => win.getComputedStyle(el),
3442
3796
  (value, fontSize) => resolveLengthPx(value, fontSize) || 0,
3443
3797
  );
3444
- return checkRepeatedSectionKickers({ candidates });
3798
+ return checkKickerAboveHeading({ candidates });
3445
3799
  }
3446
3800
 
3447
3801
  function checkElementMotion(tag, style) {
@@ -5068,6 +5422,7 @@ function checkFirstViewportColumnOverflowDOM() {
5068
5422
  }
5069
5423
 
5070
5424
  export {
5425
+ CSS_NAMED_COLORS,
5071
5426
  checkBorders,
5072
5427
  isEmojiOnlyText,
5073
5428
  checkColors,
@@ -5081,7 +5436,7 @@ export {
5081
5436
  checkItalicSerif,
5082
5437
  isAccentColor,
5083
5438
  checkHeroEyebrow,
5084
- checkRepeatedSectionKickers,
5439
+ checkKickerAboveHeading,
5085
5440
  checkMotion,
5086
5441
  checkGlow,
5087
5442
  scanCssTextForGlow,
@@ -5112,15 +5467,17 @@ export {
5112
5467
  parseAnyColor,
5113
5468
  parseColorResolved,
5114
5469
  cleanInlineText,
5115
- isRepeatedKickerCandidate,
5116
- collectRepeatedSectionKickerCandidates,
5117
- checkRepeatedSectionKickersDOM,
5470
+ isKickerCandidate,
5471
+ collectKickerCandidates,
5472
+ checkKickerAboveHeadingDOM,
5118
5473
  parseNumberedLabelText,
5119
5474
  isNumberedSectionLabelCandidate,
5120
5475
  collectNumberedSectionLabelCandidates,
5121
5476
  checkNumberedSectionLabels,
5122
5477
  checkNumberedSectionLabelsFromDoc,
5123
5478
  checkNumberedSectionLabelsDOM,
5479
+ checkEmDashOveruse,
5480
+ checkEmDashOveruseDOM,
5124
5481
  isRepeatedTextContainer,
5125
5482
  collectRepeatedContainerTextFindings,
5126
5483
  checkRepeatedContainerTextFromDoc,
@@ -5129,6 +5486,9 @@ export {
5129
5486
  checkElementMotionDOM,
5130
5487
  checkElementGlowDOM,
5131
5488
  checkElementAIPaletteDOM,
5489
+ checkElementRadialSpotlightDOM,
5490
+ checkElementRadialSpotlight,
5491
+ checkRadialSpotlight,
5132
5492
  resolveFontSizePx,
5133
5493
  resolveLengthPx,
5134
5494
  checkQuality,
@@ -5141,7 +5501,7 @@ export {
5141
5501
  checkElementIconTile,
5142
5502
  checkElementItalicSerif,
5143
5503
  checkElementHeroEyebrow,
5144
- checkRepeatedSectionKickersFromDoc,
5504
+ checkKickerAboveHeadingFromDoc,
5145
5505
  checkElementMotion,
5146
5506
  checkElementGlow,
5147
5507
  checkTypography,