impeccable 3.3.1 → 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.
@@ -109,9 +109,21 @@ function checkColors(opts) {
109
109
  const findings = [];
110
110
 
111
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';
112
122
  // Run background-dependent checks against either a solid bg or, if the
113
123
  // ancestor is a gradient, against every gradient stop (use the worst case).
114
- const bgs = effectiveBg ? [effectiveBg] : (effectiveBgStops && effectiveBgStops.length ? effectiveBgStops : null);
124
+ const bgs = isGradientClippedText
125
+ ? null
126
+ : (effectiveBg ? [effectiveBg] : (effectiveBgStops && effectiveBgStops.length ? effectiveBgStops : null));
115
127
  if (bgs) {
116
128
  // Gray on colored background — flag if every stop is chromatic
117
129
  const textLum = relativeLuminance(textColor);
@@ -444,12 +456,15 @@ function checkHeroEyebrow(opts) {
444
456
  }];
445
457
  }
446
458
 
447
- function checkRepeatedSectionKickers(opts) {
448
- const { candidates, minCount = 3 } = opts;
449
- 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 [];
450
465
  return candidates.map(candidate => ({
451
- id: 'repeated-section-kickers',
452
- 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}"`,
453
468
  }));
454
469
  }
455
470
 
@@ -811,7 +826,13 @@ function isZeroOffset(value) {
811
826
  // never see it — pseudo-elements aren't part of the DOM the cascade walks —
812
827
  // so this scans stylesheet text directly, mirroring the border rule's
813
828
  // gates: >= 3px thick, chromatic fill, full height against a side edge.
814
- 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, ' '));
815
836
  const customProps = collectCssCustomProps(content);
816
837
  const findings = [];
817
838
  const seen = new Set();
@@ -920,9 +941,13 @@ function scanCssTextForPseudoStripe(content) {
920
941
 
921
942
  if (seen.has(selector)) continue;
922
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);
923
947
  findings.push({
924
948
  id: 'side-tab',
925
949
  snippet: `${selector} — absolute ${thicknessPx}px pseudo-element stripe (${edge}: 0)`,
950
+ index: selectorStart,
926
951
  });
927
952
  }
928
953
  return findings;
@@ -1669,29 +1694,54 @@ function resolveBackground(el, win, customPropMap) {
1669
1694
  // Walk parents looking for a gradient background and return its color stops.
1670
1695
  // Used as a fallback when resolveBackground() returns null because the
1671
1696
  // effective background is a gradient (no single solid color to compare against).
1672
- function resolveGradientStops(el, win) {
1697
+ function resolveGradientStops(el, win, customPropMap) {
1673
1698
  let current = el;
1674
1699
  while (current && current.nodeType === 1) {
1675
1700
  const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
1676
1701
  const bgImage = style.backgroundImage || '';
1702
+ let stops = null;
1677
1703
  if (bgImage && bgImage !== 'none' && /gradient/i.test(bgImage)) {
1678
- const stops = parseGradientColors(bgImage);
1679
- if (stops.length > 0) return stops;
1704
+ const parsed = parseGradientColors(bgImage);
1705
+ if (parsed.length > 0) stops = parsed;
1680
1706
  }
1681
- if (!DETECTOR_IS_BROWSER) {
1707
+ if (!stops && !DETECTOR_IS_BROWSER) {
1682
1708
  // jsdom doesn't decompose `background:` shorthand — peek at the raw inline style
1683
1709
  const rawStyle = current.getAttribute?.('style') || '';
1684
1710
  const bgMatch = rawStyle.match(/background(?:-image)?\s*:\s*([^;]+)/i);
1685
1711
  if (bgMatch && /gradient/i.test(bgMatch[1])) {
1686
- const stops = parseGradientColors(bgMatch[1]);
1687
- if (stops.length > 0) return stops;
1712
+ const parsed = parseGradientColors(bgMatch[1]);
1713
+ if (parsed.length > 0) stops = parsed;
1688
1714
  }
1689
1715
  }
1716
+ if (stops) return compositeGradientStops(stops, current, win, customPropMap);
1690
1717
  current = current.parentElement;
1691
1718
  }
1692
1719
  return null;
1693
1720
  }
1694
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
+
1695
1745
  // Parse a single CSS length token to pixels. Accepts "12px", "50%", a
1696
1746
  // shorthand like "12px 4px" (uses the first value), or empty / null.
1697
1747
  // Returns the pixel value, or null when the input is unparseable.
@@ -2341,7 +2391,7 @@ function parseColorResolved(str, customPropMap) {
2341
2391
  return parseAnyColor(resolved);
2342
2392
  }
2343
2393
 
2344
- const REPEATED_KICKER_SKIP_SELECTOR = [
2394
+ const KICKER_SKIP_SELECTOR = [
2345
2395
  'nav',
2346
2396
  'form',
2347
2397
  'table',
@@ -2360,7 +2410,7 @@ const REPEATED_KICKER_SKIP_SELECTOR = [
2360
2410
  '[data-impeccable-allow-kickers]',
2361
2411
  ].join(',');
2362
2412
 
2363
- const REPEATED_KICKER_CARD_CONTEXT_SELECTOR = [
2413
+ const KICKER_CARD_CONTEXT_SELECTOR = [
2364
2414
  'article',
2365
2415
  'button',
2366
2416
  'a',
@@ -2378,23 +2428,32 @@ function cleanInlineText(el) {
2378
2428
  .trim();
2379
2429
  }
2380
2430
 
2381
- function isRepeatedKickerCardContext(heading, kicker) {
2382
- const item = heading.closest?.(REPEATED_KICKER_CARD_CONTEXT_SELECTOR);
2431
+ function isKickerCardContext(heading, kicker) {
2432
+ const item = heading.closest?.(KICKER_CARD_CONTEXT_SELECTOR);
2383
2433
  return Boolean(item && (!item.contains || item.contains(kicker)));
2384
2434
  }
2385
2435
 
2386
- 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) {
2387
2445
  const {
2388
- headingTag,
2446
+ headingLevel,
2389
2447
  headingText,
2390
2448
  headingFontSize,
2391
2449
  kickerTag,
2392
2450
  kickerText,
2393
2451
  kickerTextTransform,
2452
+ kickerFontVariant,
2394
2453
  kickerFontSize,
2395
2454
  kickerLetterSpacing,
2396
2455
  } = opts;
2397
- if (!['h2', 'h3', 'h4'].includes(headingTag)) return false;
2456
+ if (!headingLevel || headingLevel > 4) return false;
2398
2457
  if (!headingText || headingText.length < 3) return false;
2399
2458
  if (/^\/[\w-]+/i.test(headingText.replace(/^"|"$/g, '').trim())) return false;
2400
2459
  if (!(headingFontSize >= 20)) return false;
@@ -2402,9 +2461,13 @@ function isRepeatedKickerCandidate(opts) {
2402
2461
  if (!['p', 'span', 'div', 'small'].includes(kickerTag)) return false;
2403
2462
  if (!kickerText || kickerText.length < 2 || kickerText.length > 34) return false;
2404
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;
2405
2466
 
2467
+ const isSmallCaps = /small-caps/.test(kickerFontVariant || '');
2406
2468
  const isUppercased = kickerTextTransform === 'uppercase'
2407
- || (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText));
2469
+ || (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText))
2470
+ || isSmallCaps;
2408
2471
  if (!isUppercased) return false;
2409
2472
  if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false;
2410
2473
  const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08);
@@ -2412,37 +2475,64 @@ function isRepeatedKickerCandidate(opts) {
2412
2475
  return true;
2413
2476
  }
2414
2477
 
2415
- 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) {
2416
2491
  const candidates = [];
2417
- for (const heading of doc.querySelectorAll('h2, h3, h4')) {
2418
- 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;
2419
2500
  const kicker = heading.previousElementSibling;
2420
- if (!kicker || kicker.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
2421
- if (isRepeatedKickerCardContext(heading, kicker)) continue;
2501
+ if (!kicker || kicker.closest?.(KICKER_SKIP_SELECTOR)) continue;
2502
+ if (isKickerCardContext(heading, kicker)) continue;
2422
2503
 
2423
2504
  const headingStyle = getStyle(heading);
2424
2505
  const kickerStyle = getStyle(kicker);
2506
+ const headingTag = heading.tagName.toLowerCase();
2425
2507
  const headingText = (heading.textContent || '').replace(/\s+/g, ' ').trim();
2426
2508
  const kickerText = cleanInlineText(kicker) || (kicker.textContent || '').replace(/\s+/g, ' ').trim();
2427
2509
  const headingFontSize = resolveLetterSpacing(headingStyle.fontSize || '', 16) || parseFloat(headingStyle.fontSize) || 0;
2428
2510
  const kickerFontSize = resolveLetterSpacing(kickerStyle.fontSize || '', 16) || parseFloat(kickerStyle.fontSize) || 0;
2429
2511
  const kickerLetterSpacing = resolveLetterSpacing(kickerStyle.letterSpacing || '', kickerFontSize);
2430
2512
 
2431
- if (!isRepeatedKickerCandidate({
2432
- headingTag: heading.tagName.toLowerCase(),
2513
+ if (!isKickerCandidate({
2514
+ headingLevel,
2433
2515
  headingText,
2434
2516
  headingFontSize,
2435
2517
  kickerTag: kicker.tagName.toLowerCase(),
2436
2518
  kickerText,
2437
2519
  kickerTextTransform: kickerStyle.textTransform || '',
2520
+ kickerFontVariant: `${kickerStyle.fontVariant || ''} ${kickerStyle.fontVariantCaps || ''}`,
2438
2521
  kickerFontSize,
2439
2522
  kickerLetterSpacing,
2440
2523
  })) {
2441
2524
  continue;
2442
2525
  }
2443
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
+
2444
2534
  candidates.push({
2445
- headingTag: heading.tagName.toLowerCase(),
2535
+ headingTag,
2446
2536
  headingText: headingText.replace(/^"|"$/g, '').slice(0, 60),
2447
2537
  kickerText: kickerText.slice(0, 40),
2448
2538
  });
@@ -2450,17 +2540,17 @@ function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpac
2450
2540
  return candidates;
2451
2541
  }
2452
2542
 
2453
- function checkRepeatedSectionKickersDOM() {
2454
- const candidates = collectRepeatedSectionKickerCandidates(
2543
+ function checkKickerAboveHeadingDOM() {
2544
+ const candidates = collectKickerCandidates(
2455
2545
  document,
2456
2546
  (el) => getComputedStyle(el),
2457
2547
  (value, fontSize) => resolveLengthPx(value, fontSize) || 0,
2458
2548
  );
2459
- return checkRepeatedSectionKickers({ candidates });
2549
+ return checkKickerAboveHeading({ candidates });
2460
2550
  }
2461
2551
 
2462
2552
  // ── Numbered section labels ─────────────────────────────────────────────────
2463
- // 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,
2464
2554
  // the section scaffold is a tiny numeric index riding beside each section
2465
2555
  // heading — bare and zero-padded, or an index joined to a short micro-label
2466
2556
  // by a separator glyph. The kicker rule deliberately excludes bare 1-2 digit
@@ -2514,7 +2604,7 @@ function collectNumberedSectionLabelCandidates(doc, getStyle, resolveLetterSpaci
2514
2604
  const candidates = [];
2515
2605
  const seenLabels = new Set();
2516
2606
  for (const heading of doc.querySelectorAll('h2, h3, h4')) {
2517
- if (heading.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
2607
+ if (heading.closest?.(KICKER_SKIP_SELECTOR)) continue;
2518
2608
  // The index sits either directly before the heading, or before the
2519
2609
  // wrapper the heading leads (label | <div><h2>…</h2>…</div>).
2520
2610
  let label = heading.previousElementSibling;
@@ -2524,9 +2614,9 @@ function collectNumberedSectionLabelCandidates(doc, getStyle, resolveLetterSpaci
2524
2614
  if (firstChild === heading) label = parent.previousElementSibling;
2525
2615
  }
2526
2616
  if (!label || seenLabels.has(label)) continue;
2527
- if (label.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
2617
+ if (label.closest?.(KICKER_SKIP_SELECTOR)) continue;
2528
2618
  if (HEADING_TAGS.has(label.tagName.toLowerCase())) continue;
2529
- if (isRepeatedKickerCardContext(heading, label)) continue;
2619
+ if (isKickerCardContext(heading, label)) continue;
2530
2620
 
2531
2621
  const labelText = cleanInlineText(label) || (label.textContent || '').replace(/\s+/g, ' ').trim();
2532
2622
  const parsed = parseNumberedLabelText(labelText);
@@ -2729,6 +2819,131 @@ function checkElementAIPaletteDOM(el) {
2729
2819
  return findings;
2730
2820
  }
2731
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
+
2732
2947
  const QUALITY_TEXT_TAGS = new Set(['p', 'li', 'td', 'th', 'dd', 'blockquote', 'figcaption']);
2733
2948
 
2734
2949
  // Resolve a CSS font-size value to pixels by walking up the parent chain.
@@ -2871,6 +3086,34 @@ function isVisuallyHidden(el, style) {
2871
3086
  return false;
2872
3087
  }
2873
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
+
2874
3117
  // Pure quality checks. Most run on computed CSS and DOM-only inputs (work in
2875
3118
  // jsdom and the browser). Two checks (line-length, cramped-padding) gate on
2876
3119
  // element rect dimensions, which jsdom can't compute — pass `rect: null` from
@@ -2881,8 +3124,13 @@ function isVisuallyHidden(el, style) {
2881
3124
  function checkQuality(opts) {
2882
3125
  const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80, viewportWidth = 0, win = null } = opts;
2883
3126
  const findings = [];
2884
- // Skip browser extension injected elements
2885
- 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') || '');
2886
3134
  if (elId.startsWith('claude-') || elId.startsWith('cic-')) return findings;
2887
3135
 
2888
3136
  // --- Line length too long --- (browser-only: needs rect.width)
@@ -3150,7 +3398,7 @@ function checkQuality(opts) {
3150
3398
  const skipTags = ['sub', 'sup', 'code', 'kbd', 'samp', 'var', 'caption', 'figcaption'];
3151
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]');
3152
3400
  const isUppercase = style.textTransform === 'uppercase';
3153
- if (!skipTags.includes(tag) && !inUIContext && !isUppercase) {
3401
+ if (!skipTags.includes(tag) && !inUIContext && !isUppercase && !isNonRenderedText(el, tag, style)) {
3154
3402
  findings.push({ id: 'tiny-text', snippet: `${fontSize}px body text` });
3155
3403
  }
3156
3404
  }
@@ -3180,13 +3428,15 @@ function checkQuality(opts) {
3180
3428
  .replace(/\s+/g, ' ')
3181
3429
  .trim();
3182
3430
  const dtLen = directText.length;
3183
- const UI_SKIP_TAGS = new Set(['sub', 'sup', 'script', 'style', 'title', 'option']);
3184
- const notRendered = style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse';
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']);
3185
3435
  // jsdom resolves the parent chain in resolveFontSizePx, so em/rem/%-sized
3186
3436
  // text that computes at or above the floor never reaches here. The browser
3187
3437
  // adapter additionally catches values only resolvable with real layout
3188
3438
  // (e.g. viewport-relative units, cascade winners set in linked sheets).
3189
- if (fontSize > 0 && fontSize < 11 && dtLen >= 2 && !UI_SKIP_TAGS.has(tag) && !notRendered) {
3439
+ if (fontSize > 0 && fontSize < 11 && dtLen >= 2 && !UI_SKIP_TAGS.has(tag) && !isNonRenderedText(el, tag, style)) {
3190
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]';
3191
3441
  const isExemptContext = (el.matches && el.matches(EXEMPT_CONTEXT)) || (el.closest && el.closest(EXEMPT_CONTEXT));
3192
3442
  if (!isExemptContext && !isVisuallyHidden(el, style)) {
@@ -3399,7 +3649,7 @@ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInhe
3399
3649
  textColor,
3400
3650
  bgColor: ownBg,
3401
3651
  effectiveBg: finalEffectiveBg,
3402
- effectiveBgStops: finalEffectiveBg ? null : resolveGradientStops(el, window),
3652
+ effectiveBgStops: finalEffectiveBg ? null : resolveGradientStops(el, window, customPropMap),
3403
3653
  fontSize: parseFloat(style.fontSize) || 16,
3404
3654
  fontWeight: parseInt(style.fontWeight) || 400,
3405
3655
  hasDirectText,
@@ -3539,13 +3789,13 @@ function checkElementHeroEyebrow(el, style, tag, window, customPropMap) {
3539
3789
  });
3540
3790
  }
3541
3791
 
3542
- function checkRepeatedSectionKickersFromDoc(doc, win) {
3543
- const candidates = collectRepeatedSectionKickerCandidates(
3792
+ function checkKickerAboveHeadingFromDoc(doc, win) {
3793
+ const candidates = collectKickerCandidates(
3544
3794
  doc,
3545
3795
  (el) => win.getComputedStyle(el),
3546
3796
  (value, fontSize) => resolveLengthPx(value, fontSize) || 0,
3547
3797
  );
3548
- return checkRepeatedSectionKickers({ candidates });
3798
+ return checkKickerAboveHeading({ candidates });
3549
3799
  }
3550
3800
 
3551
3801
  function checkElementMotion(tag, style) {
@@ -5172,6 +5422,7 @@ function checkFirstViewportColumnOverflowDOM() {
5172
5422
  }
5173
5423
 
5174
5424
  export {
5425
+ CSS_NAMED_COLORS,
5175
5426
  checkBorders,
5176
5427
  isEmojiOnlyText,
5177
5428
  checkColors,
@@ -5185,7 +5436,7 @@ export {
5185
5436
  checkItalicSerif,
5186
5437
  isAccentColor,
5187
5438
  checkHeroEyebrow,
5188
- checkRepeatedSectionKickers,
5439
+ checkKickerAboveHeading,
5189
5440
  checkMotion,
5190
5441
  checkGlow,
5191
5442
  scanCssTextForGlow,
@@ -5216,9 +5467,9 @@ export {
5216
5467
  parseAnyColor,
5217
5468
  parseColorResolved,
5218
5469
  cleanInlineText,
5219
- isRepeatedKickerCandidate,
5220
- collectRepeatedSectionKickerCandidates,
5221
- checkRepeatedSectionKickersDOM,
5470
+ isKickerCandidate,
5471
+ collectKickerCandidates,
5472
+ checkKickerAboveHeadingDOM,
5222
5473
  parseNumberedLabelText,
5223
5474
  isNumberedSectionLabelCandidate,
5224
5475
  collectNumberedSectionLabelCandidates,
@@ -5235,6 +5486,9 @@ export {
5235
5486
  checkElementMotionDOM,
5236
5487
  checkElementGlowDOM,
5237
5488
  checkElementAIPaletteDOM,
5489
+ checkElementRadialSpotlightDOM,
5490
+ checkElementRadialSpotlight,
5491
+ checkRadialSpotlight,
5238
5492
  resolveFontSizePx,
5239
5493
  resolveLengthPx,
5240
5494
  checkQuality,
@@ -5247,7 +5501,7 @@ export {
5247
5501
  checkElementIconTile,
5248
5502
  checkElementItalicSerif,
5249
5503
  checkElementHeroEyebrow,
5250
- checkRepeatedSectionKickersFromDoc,
5504
+ checkKickerAboveHeadingFromDoc,
5251
5505
  checkElementMotion,
5252
5506
  checkElementGlow,
5253
5507
  checkTypography,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "impeccable",
3
- "version": "3.3.1",
3
+ "version": "3.4.0",
4
4
  "author": "Paul Bakaus",
5
5
  "description": "Design skills, commands, and anti-pattern detection for AI coding agents",
6
6
  "keywords": [
@@ -88,7 +88,7 @@
88
88
  "@ai-sdk/google": "^4.0.8",
89
89
  "@ai-sdk/openai": "^4.0.7",
90
90
  "@anthropic-ai/claude-agent-sdk": "^0.3.165",
91
- "@anthropic-ai/sdk": "^0.112.3",
91
+ "@anthropic-ai/sdk": "^0.115.0",
92
92
  "@babel/parser": "^7.29.3",
93
93
  "ai": "^7.0.14",
94
94
  "archiver": "^8.0.0",