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.
@@ -260,6 +260,15 @@ const ANTIPATTERNS = [
260
260
  skillSection: 'Color & Contrast',
261
261
  skillGuideline: 'dark mode with glowing accents',
262
262
  },
263
+ {
264
+ id: 'radial-spotlight-glow',
265
+ category: 'slop',
266
+ name: 'Decorative radial spotlight glow',
267
+ description:
268
+ 'A soft, low-opacity accent-colored radial gradient fading to transparent, dropped behind a hero or section as a "spotlight." It is a reflex AI decoration — the translucent cousin of the saturated radial halo. Let the surface stand on its own, or light the composition with a deliberate material accent rather than a floating colored haze.',
269
+ skillSection: 'Color & Contrast',
270
+ skillGuideline: 'dark mode with glowing accents',
271
+ },
263
272
  {
264
273
  id: 'marquee',
265
274
  category: 'slop',
@@ -300,15 +309,14 @@ const ANTIPATTERNS = [
300
309
  skillGuideline: 'tiny uppercase tracked label above the hero headline',
301
310
  },
302
311
  {
303
- id: 'repeated-section-kickers',
312
+ id: 'kicker-above-heading',
304
313
  category: 'slop',
305
314
  scopes: ['type'],
306
- severity: 'advisory',
307
- name: 'Repeated section kicker labels',
315
+ name: 'Kicker / eyebrow label above heading',
308
316
  description:
309
- 'Repeating tiny uppercase tracked labels above section headings turns a brand page into AI editorial scaffolding. Replace them with stronger structure, artifacts, imagery, or a deliberate brand system.',
317
+ 'A tiny tracked uppercase or small-caps label sitting as its own block directly above a heading is banned outright, repeated or not. Generated kickers never earn their place: the heading carries its own weight. Delete the label and let the heading speak; if the words matter, work them into the heading or the body.',
310
318
  skillSection: 'Typography',
311
- skillGuideline: 'repeated eyebrow or kicker labels as section scaffolding',
319
+ skillGuideline: 'kicker or eyebrow labels above headings',
312
320
  },
313
321
  {
314
322
  id: 'numbered-section-labels',
@@ -902,9 +910,21 @@ function checkColors(opts) {
902
910
  const findings = [];
903
911
 
904
912
  if (hasDirectText && textColor && !isEmojiOnly) {
913
+ // Gradient-clipped text (`background-clip: text`, typically with a
914
+ // transparent text-fill) paints its glyphs *with* the element's own
915
+ // gradient. The `color` value the cascade still reports is never painted,
916
+ // and the gradient is the fill, not a backdrop — so measuring `color`
917
+ // against that gradient (which resolveGradientStops picks up as the
918
+ // element's own background-image) is a guaranteed false positive
919
+ // (issue #409 Case A). Skip the backdrop-contrast checks; the gradient-text
920
+ // rule below still flags the pattern itself. Skipping a rule beats a false
921
+ // positive here — the true painted contrast can't be measured from `color`.
922
+ const isGradientClippedText = bgClip === 'text';
905
923
  // Run background-dependent checks against either a solid bg or, if the
906
924
  // ancestor is a gradient, against every gradient stop (use the worst case).
907
- const bgs = effectiveBg ? [effectiveBg] : (effectiveBgStops && effectiveBgStops.length ? effectiveBgStops : null);
925
+ const bgs = isGradientClippedText
926
+ ? null
927
+ : (effectiveBg ? [effectiveBg] : (effectiveBgStops && effectiveBgStops.length ? effectiveBgStops : null));
908
928
  if (bgs) {
909
929
  // Gray on colored background — flag if every stop is chromatic
910
930
  const textLum = relativeLuminance(textColor);
@@ -1237,12 +1257,15 @@ function checkHeroEyebrow(opts) {
1237
1257
  }];
1238
1258
  }
1239
1259
 
1240
- function checkRepeatedSectionKickers(opts) {
1241
- const { candidates, minCount = 3 } = opts;
1242
- if (!Array.isArray(candidates) || candidates.length < minCount) return [];
1260
+ // Outright ban: one kicker is one too many, so every collected candidate is
1261
+ // a finding. The judgment lives in the candidate gate (isKickerCandidate) and
1262
+ // the collector's context skips, not in a repetition count.
1263
+ function checkKickerAboveHeading(opts) {
1264
+ const { candidates } = opts;
1265
+ if (!Array.isArray(candidates)) return [];
1243
1266
  return candidates.map(candidate => ({
1244
- id: 'repeated-section-kickers',
1245
- snippet: `repeated section kicker "${candidate.kickerText}" before ${candidate.headingTag} "${candidate.headingText}" (${candidates.length} on page)`,
1267
+ id: 'kicker-above-heading',
1268
+ snippet: `kicker "${candidate.kickerText}" above ${candidate.headingTag} "${candidate.headingText}"`,
1246
1269
  }));
1247
1270
  }
1248
1271
 
@@ -1604,7 +1627,13 @@ function isZeroOffset(value) {
1604
1627
  // never see it — pseudo-elements aren't part of the DOM the cascade walks —
1605
1628
  // so this scans stylesheet text directly, mirroring the border rule's
1606
1629
  // gates: >= 3px thick, chromatic fill, full height against a side edge.
1607
- function scanCssTextForPseudoStripe(content) {
1630
+ function scanCssTextForPseudoStripe(rawContent) {
1631
+ // Blank comment bodies byte-for-byte so commented-out rules are not
1632
+ // scanned as live CSS and every rule keeps its source offset (each
1633
+ // finding carries `index` so line-based callers can attribute it and
1634
+ // line-scoped inline ignores can match).
1635
+ const content = String(rawContent || '').replace(/\/\*[\s\S]*?\*\//g,
1636
+ (block) => block.replace(/[^\n]/g, ' '));
1608
1637
  const customProps = collectCssCustomProps(content);
1609
1638
  const findings = [];
1610
1639
  const seen = new Set();
@@ -1713,9 +1742,13 @@ function scanCssTextForPseudoStripe(content) {
1713
1742
 
1714
1743
  if (seen.has(selector)) continue;
1715
1744
  seen.add(selector);
1745
+ // The selector group absorbs whitespace trailing the previous rule;
1746
+ // advance past it so `index` points at the selector itself.
1747
+ const selectorStart = m.index + (m[1].length - m[1].trimStart().length);
1716
1748
  findings.push({
1717
1749
  id: 'side-tab',
1718
1750
  snippet: `${selector} — absolute ${thicknessPx}px pseudo-element stripe (${edge}: 0)`,
1751
+ index: selectorStart,
1719
1752
  });
1720
1753
  }
1721
1754
  return findings;
@@ -2462,29 +2495,54 @@ function resolveBackground(el, win, customPropMap) {
2462
2495
  // Walk parents looking for a gradient background and return its color stops.
2463
2496
  // Used as a fallback when resolveBackground() returns null because the
2464
2497
  // effective background is a gradient (no single solid color to compare against).
2465
- function resolveGradientStops(el, win) {
2498
+ function resolveGradientStops(el, win, customPropMap) {
2466
2499
  let current = el;
2467
2500
  while (current && current.nodeType === 1) {
2468
2501
  const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
2469
2502
  const bgImage = style.backgroundImage || '';
2503
+ let stops = null;
2470
2504
  if (bgImage && bgImage !== 'none' && /gradient/i.test(bgImage)) {
2471
- const stops = parseGradientColors(bgImage);
2472
- if (stops.length > 0) return stops;
2505
+ const parsed = parseGradientColors(bgImage);
2506
+ if (parsed.length > 0) stops = parsed;
2473
2507
  }
2474
- if (!DETECTOR_IS_BROWSER) {
2508
+ if (!stops && !DETECTOR_IS_BROWSER) {
2475
2509
  // jsdom doesn't decompose `background:` shorthand — peek at the raw inline style
2476
2510
  const rawStyle = current.getAttribute?.('style') || '';
2477
2511
  const bgMatch = rawStyle.match(/background(?:-image)?\s*:\s*([^;]+)/i);
2478
2512
  if (bgMatch && /gradient/i.test(bgMatch[1])) {
2479
- const stops = parseGradientColors(bgMatch[1]);
2480
- if (stops.length > 0) return stops;
2513
+ const parsed = parseGradientColors(bgMatch[1]);
2514
+ if (parsed.length > 0) stops = parsed;
2481
2515
  }
2482
2516
  }
2517
+ if (stops) return compositeGradientStops(stops, current, win, customPropMap);
2483
2518
  current = current.parentElement;
2484
2519
  }
2485
2520
  return null;
2486
2521
  }
2487
2522
 
2523
+ // A translucent gradient stop (e.g. a faint `rgba(52,192,168,0.09)` accent
2524
+ // glow) paints over whatever surface sits beneath the gradient — the browser
2525
+ // composites it, so its effective color is far closer to the base than to the
2526
+ // full-opacity accent. Treating the stop as opaque flags every text child of a
2527
+ // softly-glowing section as low-contrast (issue #409 Case B). Composite each
2528
+ // alpha stop over the resolved surface beneath the gradient element. When that
2529
+ // surface isn't resolvable (another gradient above, no opaque ancestor), drop
2530
+ // the translucent stop rather than guess: a dropped stop can't manufacture a
2531
+ // false finding, and skipping beats a wrong ratio.
2532
+ function compositeGradientStops(stops, gradientEl, win, customPropMap) {
2533
+ const hasAlpha = stops.some(s => (s.a ?? 1) < 0.99);
2534
+ if (!hasAlpha) return stops;
2535
+ const base = resolveBackground(gradientEl.parentElement || gradientEl, win, customPropMap);
2536
+ const out = [];
2537
+ for (const s of stops) {
2538
+ const a = s.a ?? 1;
2539
+ if (a >= 0.99) { out.push(s); continue; }
2540
+ if (base) out.push(compositeColorOver(s, base));
2541
+ // else: unresolvable base — drop the translucent stop (skip, don't guess).
2542
+ }
2543
+ return out.length ? out : null;
2544
+ }
2545
+
2488
2546
  // Parse a single CSS length token to pixels. Accepts "12px", "50%", a
2489
2547
  // shorthand like "12px 4px" (uses the first value), or empty / null.
2490
2548
  // Returns the pixel value, or null when the input is unparseable.
@@ -3134,7 +3192,7 @@ function parseColorResolved(str, customPropMap) {
3134
3192
  return parseAnyColor(resolved);
3135
3193
  }
3136
3194
 
3137
- const REPEATED_KICKER_SKIP_SELECTOR = [
3195
+ const KICKER_SKIP_SELECTOR = [
3138
3196
  'nav',
3139
3197
  'form',
3140
3198
  'table',
@@ -3153,7 +3211,7 @@ const REPEATED_KICKER_SKIP_SELECTOR = [
3153
3211
  '[data-impeccable-allow-kickers]',
3154
3212
  ].join(',');
3155
3213
 
3156
- const REPEATED_KICKER_CARD_CONTEXT_SELECTOR = [
3214
+ const KICKER_CARD_CONTEXT_SELECTOR = [
3157
3215
  'article',
3158
3216
  'button',
3159
3217
  'a',
@@ -3171,23 +3229,32 @@ function cleanInlineText(el) {
3171
3229
  .trim();
3172
3230
  }
3173
3231
 
3174
- function isRepeatedKickerCardContext(heading, kicker) {
3175
- const item = heading.closest?.(REPEATED_KICKER_CARD_CONTEXT_SELECTOR);
3232
+ function isKickerCardContext(heading, kicker) {
3233
+ const item = heading.closest?.(KICKER_CARD_CONTEXT_SELECTOR);
3176
3234
  return Boolean(item && (!item.contains || item.contains(kicker)));
3177
3235
  }
3178
3236
 
3179
- function isRepeatedKickerCandidate(opts) {
3237
+ // Meta lines above headlines join category and date (or path crumbs) with
3238
+ // separator glyphs, or carry a year. A kicker is one short phrase; metadata
3239
+ // keeps its markers.
3240
+ const KICKER_META_TEXT_RE = /[·•|]|\s[\/›»>]\s|\b(19|20)\d{2}\b/;
3241
+ // Legal and document numbering: "Section 4.2", "Article IX", "§ 12.3",
3242
+ // dotted decimal outlines. The label identifies the clause, so it stays.
3243
+ 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;
3244
+
3245
+ function isKickerCandidate(opts) {
3180
3246
  const {
3181
- headingTag,
3247
+ headingLevel,
3182
3248
  headingText,
3183
3249
  headingFontSize,
3184
3250
  kickerTag,
3185
3251
  kickerText,
3186
3252
  kickerTextTransform,
3253
+ kickerFontVariant,
3187
3254
  kickerFontSize,
3188
3255
  kickerLetterSpacing,
3189
3256
  } = opts;
3190
- if (!['h2', 'h3', 'h4'].includes(headingTag)) return false;
3257
+ if (!headingLevel || headingLevel > 4) return false;
3191
3258
  if (!headingText || headingText.length < 3) return false;
3192
3259
  if (/^\/[\w-]+/i.test(headingText.replace(/^"|"$/g, '').trim())) return false;
3193
3260
  if (!(headingFontSize >= 20)) return false;
@@ -3195,9 +3262,13 @@ function isRepeatedKickerCandidate(opts) {
3195
3262
  if (!['p', 'span', 'div', 'small'].includes(kickerTag)) return false;
3196
3263
  if (!kickerText || kickerText.length < 2 || kickerText.length > 34) return false;
3197
3264
  if (/^step\s*\d+/i.test(kickerText) || /^\d{1,2}$/.test(kickerText)) return false;
3265
+ if (KICKER_META_TEXT_RE.test(kickerText)) return false;
3266
+ if (KICKER_DOC_NUMBERING_RE.test(kickerText)) return false;
3198
3267
 
3268
+ const isSmallCaps = /small-caps/.test(kickerFontVariant || '');
3199
3269
  const isUppercased = kickerTextTransform === 'uppercase'
3200
- || (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText));
3270
+ || (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText))
3271
+ || isSmallCaps;
3201
3272
  if (!isUppercased) return false;
3202
3273
  if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false;
3203
3274
  const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08);
@@ -3205,37 +3276,64 @@ function isRepeatedKickerCandidate(opts) {
3205
3276
  return true;
3206
3277
  }
3207
3278
 
3208
- function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpacing) {
3279
+ // Resolve a heading level for the anchor element: 1-4 for h1-h4, aria-level
3280
+ // (default 2) for role="heading" elements, 0 otherwise.
3281
+ function kickerHeadingLevel(heading) {
3282
+ const tag = heading.tagName.toLowerCase();
3283
+ const byTag = /^h([1-6])$/.exec(tag);
3284
+ if (byTag) return parseInt(byTag[1], 10);
3285
+ const role = heading.getAttribute?.('role') || '';
3286
+ if (role.toLowerCase() !== 'heading') return 0;
3287
+ const ariaLevel = parseInt(heading.getAttribute?.('aria-level') || '', 10);
3288
+ return Number.isFinite(ariaLevel) && ariaLevel >= 1 ? ariaLevel : 2;
3289
+ }
3290
+
3291
+ function collectKickerCandidates(doc, getStyle, resolveLetterSpacing) {
3209
3292
  const candidates = [];
3210
- for (const heading of doc.querySelectorAll('h2, h3, h4')) {
3211
- if (heading.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
3293
+ for (const heading of doc.querySelectorAll('h1, h2, h3, h4, [role="heading"]')) {
3294
+ const headingLevel = kickerHeadingLevel(heading);
3295
+ if (!headingLevel || headingLevel > 4) continue;
3296
+ if (heading.closest?.(KICKER_SKIP_SELECTOR)) continue;
3297
+ // Application contexts (tab panels, dialogs) use compact context labels
3298
+ // above headings to describe state, not to decorate. Same carve-out the
3299
+ // hero-eyebrow rule makes.
3300
+ if (heading.closest?.('[role="tabpanel"], [role="dialog"], [role="application"], dialog')) continue;
3212
3301
  const kicker = heading.previousElementSibling;
3213
- if (!kicker || kicker.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
3214
- if (isRepeatedKickerCardContext(heading, kicker)) continue;
3302
+ if (!kicker || kicker.closest?.(KICKER_SKIP_SELECTOR)) continue;
3303
+ if (isKickerCardContext(heading, kicker)) continue;
3215
3304
 
3216
3305
  const headingStyle = getStyle(heading);
3217
3306
  const kickerStyle = getStyle(kicker);
3307
+ const headingTag = heading.tagName.toLowerCase();
3218
3308
  const headingText = (heading.textContent || '').replace(/\s+/g, ' ').trim();
3219
3309
  const kickerText = cleanInlineText(kicker) || (kicker.textContent || '').replace(/\s+/g, ' ').trim();
3220
3310
  const headingFontSize = resolveLetterSpacing(headingStyle.fontSize || '', 16) || parseFloat(headingStyle.fontSize) || 0;
3221
3311
  const kickerFontSize = resolveLetterSpacing(kickerStyle.fontSize || '', 16) || parseFloat(kickerStyle.fontSize) || 0;
3222
3312
  const kickerLetterSpacing = resolveLetterSpacing(kickerStyle.letterSpacing || '', kickerFontSize);
3223
3313
 
3224
- if (!isRepeatedKickerCandidate({
3225
- headingTag: heading.tagName.toLowerCase(),
3314
+ if (!isKickerCandidate({
3315
+ headingLevel,
3226
3316
  headingText,
3227
3317
  headingFontSize,
3228
3318
  kickerTag: kicker.tagName.toLowerCase(),
3229
3319
  kickerText,
3230
3320
  kickerTextTransform: kickerStyle.textTransform || '',
3321
+ kickerFontVariant: `${kickerStyle.fontVariant || ''} ${kickerStyle.fontVariantCaps || ''}`,
3231
3322
  kickerFontSize,
3232
3323
  kickerLetterSpacing,
3233
3324
  })) {
3234
3325
  continue;
3235
3326
  }
3236
3327
 
3328
+ // A tracked-caps eyebrow above a hero-scale h1 belongs to
3329
+ // hero-eyebrow-chip (which also covers the accent-bold and dash-prefix
3330
+ // stylings there). Stand down so one element gets one finding.
3331
+ if (headingTag === 'h1' && headingFontSize >= 48 && kickerLetterSpacing >= 1.6) {
3332
+ continue;
3333
+ }
3334
+
3237
3335
  candidates.push({
3238
- headingTag: heading.tagName.toLowerCase(),
3336
+ headingTag,
3239
3337
  headingText: headingText.replace(/^"|"$/g, '').slice(0, 60),
3240
3338
  kickerText: kickerText.slice(0, 40),
3241
3339
  });
@@ -3243,17 +3341,17 @@ function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpac
3243
3341
  return candidates;
3244
3342
  }
3245
3343
 
3246
- function checkRepeatedSectionKickersDOM() {
3247
- const candidates = collectRepeatedSectionKickerCandidates(
3344
+ function checkKickerAboveHeadingDOM() {
3345
+ const candidates = collectKickerCandidates(
3248
3346
  document,
3249
3347
  (el) => getComputedStyle(el),
3250
3348
  (value, fontSize) => resolveLengthPx(value, fontSize) || 0,
3251
3349
  );
3252
- return checkRepeatedSectionKickers({ candidates });
3350
+ return checkKickerAboveHeading({ candidates });
3253
3351
  }
3254
3352
 
3255
3353
  // ── Numbered section labels ─────────────────────────────────────────────────
3256
- // Sibling of the repeated-kicker rule: instead of a tracked uppercase word,
3354
+ // Sibling of the kicker-above-heading rule: instead of a tracked uppercase word,
3257
3355
  // the section scaffold is a tiny numeric index riding beside each section
3258
3356
  // heading — bare and zero-padded, or an index joined to a short micro-label
3259
3357
  // by a separator glyph. The kicker rule deliberately excludes bare 1-2 digit
@@ -3307,7 +3405,7 @@ function collectNumberedSectionLabelCandidates(doc, getStyle, resolveLetterSpaci
3307
3405
  const candidates = [];
3308
3406
  const seenLabels = new Set();
3309
3407
  for (const heading of doc.querySelectorAll('h2, h3, h4')) {
3310
- if (heading.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
3408
+ if (heading.closest?.(KICKER_SKIP_SELECTOR)) continue;
3311
3409
  // The index sits either directly before the heading, or before the
3312
3410
  // wrapper the heading leads (label | <div><h2>…</h2>…</div>).
3313
3411
  let label = heading.previousElementSibling;
@@ -3317,9 +3415,9 @@ function collectNumberedSectionLabelCandidates(doc, getStyle, resolveLetterSpaci
3317
3415
  if (firstChild === heading) label = parent.previousElementSibling;
3318
3416
  }
3319
3417
  if (!label || seenLabels.has(label)) continue;
3320
- if (label.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
3418
+ if (label.closest?.(KICKER_SKIP_SELECTOR)) continue;
3321
3419
  if (HEADING_TAGS.has(label.tagName.toLowerCase())) continue;
3322
- if (isRepeatedKickerCardContext(heading, label)) continue;
3420
+ if (isKickerCardContext(heading, label)) continue;
3323
3421
 
3324
3422
  const labelText = cleanInlineText(label) || (label.textContent || '').replace(/\s+/g, ' ').trim();
3325
3423
  const parsed = parseNumberedLabelText(labelText);
@@ -3522,6 +3620,131 @@ function checkElementAIPaletteDOM(el) {
3522
3620
  return findings;
3523
3621
  }
3524
3622
 
3623
+ // ─── Decorative radial spotlight glow ───────────────────────────────────────
3624
+ // A soft, low-opacity chromatic radial-gradient fading to transparent, painted
3625
+ // as a decorative wash behind a hero or section. The translucent sibling of the
3626
+ // `radial-halo` tell: `radial-halo` requires a saturated, near-opaque center on
3627
+ // a dark page; this catches the low-alpha "spotlight" the halo gate lets slip
3628
+ // (e.g. `radial-gradient(circle at 52% 38%, rgba(80,111,255,0.26),
3629
+ // transparent 44%)`). The two alpha bands are disjoint, so they never
3630
+ // double-report the same declaration.
3631
+ const SPOTLIGHT_COLOR_TOKEN_RE = /(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb|color-mix)\([^)]*(?:\([^)]*\))?[^)]*\)|#[0-9a-f]{3,8}\b|\btransparent\b/i;
3632
+
3633
+ // Parse the FIRST non-repeating radial-gradient in a background value into its
3634
+ // ordered color stops. Each stop is { color: {r,g,b,a} | null, transparent }.
3635
+ // Returns null when there is no plain radial-gradient to read.
3636
+ function parseRadialGradientStops(value) {
3637
+ if (!value || !/radial-gradient/i.test(value)) return null;
3638
+ const gradRe = /(repeating-)?radial-gradient\(/gi;
3639
+ let g;
3640
+ while ((g = gradRe.exec(value)) !== null) {
3641
+ if (g[1]) continue; // repeating-* is a pattern, not a spotlight
3642
+ let depth = 0, end = -1;
3643
+ const open = value.indexOf('(', g.index);
3644
+ for (let i = open; i < value.length; i++) {
3645
+ if (value[i] === '(') depth++;
3646
+ else if (value[i] === ')') { depth--; if (depth === 0) { end = i; break; } }
3647
+ }
3648
+ if (end < 0) return null;
3649
+ const args = splitTopLevelCommas(value.slice(open + 1, end));
3650
+ // The optional prelude (shape / size / `at <pos>`) carries no color token.
3651
+ const stopArgs = args.filter(a => SPOTLIGHT_COLOR_TOKEN_RE.test(a));
3652
+ if (stopArgs.length < 2) return null;
3653
+ return stopArgs.map(a => {
3654
+ const tok = a.match(SPOTLIGHT_COLOR_TOKEN_RE);
3655
+ if (!tok) return { color: null, transparent: false };
3656
+ if (/^transparent$/i.test(tok[0])) return { color: null, transparent: true };
3657
+ const color = parseAnyColor(tok[0]);
3658
+ return { color, transparent: !!color && (color.a ?? 1) <= 0.05 };
3659
+ });
3660
+ }
3661
+ return null;
3662
+ }
3663
+
3664
+ // Pure gate. `label` is a stable identifier the fixture test keys on.
3665
+ function checkRadialSpotlight({ gradientValue, width, height, label }) {
3666
+ const stops = parseRadialGradientStops(gradientValue);
3667
+ if (!stops || stops.length < 2) return [];
3668
+
3669
+ // Must fade OUT: the last stop is transparent / near-zero alpha. A gradient
3670
+ // between two visible surfaces is a real background, not a floating glow.
3671
+ const last = stops[stops.length - 1];
3672
+ const lastAlpha = last.transparent ? 0 : (last.color ? (last.color.a ?? 1) : 1);
3673
+ if (lastAlpha > 0.05) return [];
3674
+
3675
+ // The visible (non-transparent, parseable) color stops.
3676
+ const colored = stops.filter(s => !s.transparent && s.color && (s.color.a ?? 1) > 0.05);
3677
+ if (colored.length === 0) return [];
3678
+ // One soft glow, not a multi-color composition: at most two visible stops.
3679
+ if (colored.length > 2) return [];
3680
+ // Every visible stop must be LOW opacity. Any opaque stop means a real fill
3681
+ // or a saturated halo (`radial-halo`'s job), not this translucent spotlight.
3682
+ if (colored.some(s => (s.color.a ?? 1) >= 0.45)) return [];
3683
+ // At least one visible stop must be chromatic. A neutral (grayscale)
3684
+ // near-black / near-white vignette is a legitimate lighting move, exempt.
3685
+ const chromatic = colored.find(s => hasChroma(s.color, 24));
3686
+ if (!chromatic) return [];
3687
+
3688
+ // Decorative-scale gate. Badges, avatars, and actual small "lights" are
3689
+ // exempt; a spotlight glow only reads as slop when it washes a large surface.
3690
+ if (!(width >= 240 && height >= 160)) return [];
3691
+
3692
+ const alpha = (chromatic.color.a ?? 1).toFixed(2);
3693
+ const name = label || 'section';
3694
+ return [{
3695
+ id: 'radial-spotlight-glow',
3696
+ snippet: `radial-gradient spotlight glow "${name}" (${colorToHex(chromatic.color)} a${alpha} → transparent) on ${Math.round(width)}x${Math.round(height)} surface`,
3697
+ }];
3698
+ }
3699
+
3700
+ // Read the raw radial-gradient source off an element's computed style, with a
3701
+ // fallback to the `background` shorthand and the inline style attribute for
3702
+ // engines that don't decompose the shorthand into backgroundImage.
3703
+ function elementGradientValue(style, el) {
3704
+ const bgImage = style.backgroundImage && style.backgroundImage !== 'none' ? style.backgroundImage : '';
3705
+ if (/radial-gradient/i.test(bgImage)) return bgImage;
3706
+ const bg = style.background || '';
3707
+ if (/radial-gradient/i.test(bg)) return bg;
3708
+ const rawStyle = el?.getAttribute?.('style') || '';
3709
+ const m = rawStyle.match(/background(?:-image)?\s*:\s*([^;]+)/i);
3710
+ if (m && /radial-gradient/i.test(m[1])) return m[1];
3711
+ return '';
3712
+ }
3713
+
3714
+ function spotlightLabel(el) {
3715
+ const dataName = el.getAttribute?.('data-name');
3716
+ if (dataName) return dataName;
3717
+ if (typeof el.id === 'string' && el.id) return el.id;
3718
+ const cls = typeof el.className === 'string' ? el.className.trim().split(/\s+/)[0] : '';
3719
+ if (cls) return cls;
3720
+ return el.tagName ? el.tagName.toLowerCase() : 'section';
3721
+ }
3722
+
3723
+ function checkElementRadialSpotlightDOM(el) {
3724
+ const style = getComputedStyle(el);
3725
+ const gradientValue = elementGradientValue(style, el);
3726
+ if (!gradientValue) return [];
3727
+ const rect = el.getBoundingClientRect();
3728
+ return checkRadialSpotlight({
3729
+ gradientValue,
3730
+ width: rect.width,
3731
+ height: rect.height,
3732
+ label: spotlightLabel(el),
3733
+ });
3734
+ }
3735
+
3736
+ function checkElementRadialSpotlight(el, style, tag, window) {
3737
+ const gradientValue = elementGradientValue(style, el);
3738
+ if (!gradientValue) return [];
3739
+ // Static engine does no layout — read explicit pixel dimensions from CSS.
3740
+ return checkRadialSpotlight({
3741
+ gradientValue,
3742
+ width: parseFloat(style.width) || 0,
3743
+ height: parseFloat(style.height) || 0,
3744
+ label: spotlightLabel(el),
3745
+ });
3746
+ }
3747
+
3525
3748
  const QUALITY_TEXT_TAGS = new Set(['p', 'li', 'td', 'th', 'dd', 'blockquote', 'figcaption']);
3526
3749
 
3527
3750
  // Resolve a CSS font-size value to pixels by walking up the parent chain.
@@ -3664,6 +3887,34 @@ function isVisuallyHidden(el, style) {
3664
3887
  return false;
3665
3888
  }
3666
3889
 
3890
+ // Elements whose text is never painted: document metadata and script/style
3891
+ // payloads. Their JS / CSS / JSON-LD text satisfies `hasDirectText`, and on
3892
+ // sites that set `html { font-size: 62.5% }` their inherited computed size is
3893
+ // 10px — so the text-size floors flag them as tiny body copy even though
3894
+ // nothing renders (issue #408: dozens of phantom "10px body text" findings on
3895
+ // every Shopify page). Exclude them, plus anything the cascade resolves to
3896
+ // display:none / visibility:hidden. The jsdom path can't lay out, so the
3897
+ // tag/attribute-based exclusions carry the weight there; the display checks are
3898
+ // computed-style reads that resolve without layout in both adapters.
3899
+ const NON_RENDERED_TAGS = new Set([
3900
+ 'script', 'style', 'title', 'noscript', 'template', 'head',
3901
+ 'meta', 'link', 'base', 'param', 'source', 'track', 'datalist',
3902
+ 'col', 'colgroup', 'map', 'area',
3903
+ ]);
3904
+ function isNonRenderedText(el, tag, style) {
3905
+ const t = (tag || '').toLowerCase();
3906
+ if (NON_RENDERED_TAGS.has(t)) return true;
3907
+ // Descendants of <head> never render even when the tag itself would
3908
+ // (some sites nest <noscript>/<template> content there).
3909
+ if (el && el.closest && el.closest('head')) return true;
3910
+ if (style) {
3911
+ if (style.display === 'none') return true;
3912
+ const vis = style.visibility;
3913
+ if (vis === 'hidden' || vis === 'collapse') return true;
3914
+ }
3915
+ return false;
3916
+ }
3917
+
3667
3918
  // Pure quality checks. Most run on computed CSS and DOM-only inputs (work in
3668
3919
  // jsdom and the browser). Two checks (line-length, cramped-padding) gate on
3669
3920
  // element rect dimensions, which jsdom can't compute — pass `rect: null` from
@@ -3674,8 +3925,13 @@ function isVisuallyHidden(el, style) {
3674
3925
  function checkQuality(opts) {
3675
3926
  const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80, viewportWidth = 0, win = null } = opts;
3676
3927
  const findings = [];
3677
- // Skip browser extension injected elements
3678
- const elId = el.id || '';
3928
+ // Skip browser extension injected elements. Read the id via getAttribute
3929
+ // whenever `el.id` is not a string: on a <form> (and other
3930
+ // [LegacyOverrideBuiltIns] hosts) a named control like <input name="id">
3931
+ // shadows the builtin `id` getter and returns the control element, whose
3932
+ // `.startsWith` is undefined and throws (issue #407 — every Shopify product
3933
+ // form ships an <input name="id">).
3934
+ const elId = typeof el.id === 'string' ? el.id : (el.getAttribute?.('id') || '');
3679
3935
  if (elId.startsWith('claude-') || elId.startsWith('cic-')) return findings;
3680
3936
 
3681
3937
  // --- Line length too long --- (browser-only: needs rect.width)
@@ -3943,7 +4199,7 @@ function checkQuality(opts) {
3943
4199
  const skipTags = ['sub', 'sup', 'code', 'kbd', 'samp', 'var', 'caption', 'figcaption'];
3944
4200
  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]');
3945
4201
  const isUppercase = style.textTransform === 'uppercase';
3946
- if (!skipTags.includes(tag) && !inUIContext && !isUppercase) {
4202
+ if (!skipTags.includes(tag) && !inUIContext && !isUppercase && !isNonRenderedText(el, tag, style)) {
3947
4203
  findings.push({ id: 'tiny-text', snippet: `${fontSize}px body text` });
3948
4204
  }
3949
4205
  }
@@ -3973,13 +4229,15 @@ function checkQuality(opts) {
3973
4229
  .replace(/\s+/g, ' ')
3974
4230
  .trim();
3975
4231
  const dtLen = directText.length;
3976
- const UI_SKIP_TAGS = new Set(['sub', 'sup', 'script', 'style', 'title', 'option']);
3977
- const notRendered = style.display === 'none' || style.visibility === 'hidden' || style.visibility === 'collapse';
4232
+ // `option` renders (in native select popups) so it stays a local skip;
4233
+ // script/style/title/noscript/head-descendants and display:none /
4234
+ // visibility:hidden are handled by isNonRenderedText (shared with tiny-text).
4235
+ const UI_SKIP_TAGS = new Set(['sub', 'sup', 'option']);
3978
4236
  // jsdom resolves the parent chain in resolveFontSizePx, so em/rem/%-sized
3979
4237
  // text that computes at or above the floor never reaches here. The browser
3980
4238
  // adapter additionally catches values only resolvable with real layout
3981
4239
  // (e.g. viewport-relative units, cascade winners set in linked sheets).
3982
- if (fontSize > 0 && fontSize < 11 && dtLen >= 2 && !UI_SKIP_TAGS.has(tag) && !notRendered) {
4240
+ if (fontSize > 0 && fontSize < 11 && dtLen >= 2 && !UI_SKIP_TAGS.has(tag) && !isNonRenderedText(el, tag, style)) {
3983
4241
  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]';
3984
4242
  const isExemptContext = (el.matches && el.matches(EXEMPT_CONTEXT)) || (el.closest && el.closest(EXEMPT_CONTEXT));
3985
4243
  if (!isExemptContext && !isVisuallyHidden(el, style)) {
@@ -4192,7 +4450,7 @@ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInhe
4192
4450
  textColor,
4193
4451
  bgColor: ownBg,
4194
4452
  effectiveBg: finalEffectiveBg,
4195
- effectiveBgStops: finalEffectiveBg ? null : resolveGradientStops(el, window),
4453
+ effectiveBgStops: finalEffectiveBg ? null : resolveGradientStops(el, window, customPropMap),
4196
4454
  fontSize: parseFloat(style.fontSize) || 16,
4197
4455
  fontWeight: parseInt(style.fontWeight) || 400,
4198
4456
  hasDirectText,
@@ -4332,13 +4590,13 @@ function checkElementHeroEyebrow(el, style, tag, window, customPropMap) {
4332
4590
  });
4333
4591
  }
4334
4592
 
4335
- function checkRepeatedSectionKickersFromDoc(doc, win) {
4336
- const candidates = collectRepeatedSectionKickerCandidates(
4593
+ function checkKickerAboveHeadingFromDoc(doc, win) {
4594
+ const candidates = collectKickerCandidates(
4337
4595
  doc,
4338
4596
  (el) => win.getComputedStyle(el),
4339
4597
  (value, fontSize) => resolveLengthPx(value, fontSize) || 0,
4340
4598
  );
4341
- return checkRepeatedSectionKickers({ candidates });
4599
+ return checkKickerAboveHeading({ candidates });
4342
4600
  }
4343
4601
 
4344
4602
  function checkElementMotion(tag, style) {
@@ -6497,7 +6755,11 @@ if (IS_BROWSER) {
6497
6755
  function generateSelector(el) {
6498
6756
  if (el === document.body) return 'body';
6499
6757
  if (el === document.documentElement) return 'html';
6500
- if (el.id) return '#' + CSS.escape(el.id);
6758
+ // Read via getAttribute when `el.id` is not a string — a <form> with a
6759
+ // named control (e.g. <input name="id">) shadows the builtin getter and
6760
+ // returns the element, producing a garbage `#[object …]` selector (#407).
6761
+ const elId = typeof el.id === 'string' ? el.id : (el.getAttribute('id') || '');
6762
+ if (elId) return '#' + CSS.escape(elId);
6501
6763
 
6502
6764
  const parts = [];
6503
6765
  let current = el;
@@ -7434,8 +7696,11 @@ if (IS_BROWSER) {
7434
7696
  for (const el of document.querySelectorAll('*')) {
7435
7697
  // Skip impeccable's own elements and any descendants (overlays, labels, banner, nav buttons)
7436
7698
  if (el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
7437
- // Skip browser extension elements (Claude, etc.)
7438
- const elId = el.id || '';
7699
+ // Skip browser extension elements (Claude, etc.). Use getAttribute when
7700
+ // `el.id` is not a string: a <form> with a named control like
7701
+ // <input name="id"> shadows the builtin `id` getter and returns the
7702
+ // element, whose `.startsWith` throws (issue #407).
7703
+ const elId = typeof el.id === 'string' ? el.id : (el.getAttribute('id') || '');
7439
7704
  if (elId.startsWith('claude-') || elId.startsWith('cic-')) continue;
7440
7705
  // Skip the impeccable live-mode overlay (highlight, tooltip, bar, picker, toast).
7441
7706
  // These are inspector chrome, not part of the user's design.
@@ -7450,6 +7715,7 @@ if (IS_BROWSER) {
7450
7715
  ...checkElementMotionDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
7451
7716
  ...checkElementGlowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
7452
7717
  ...checkElementAIPaletteDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
7718
+ ...checkElementRadialSpotlightDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
7453
7719
  ...checkElementIconTileDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
7454
7720
  ...checkElementItalicSerifDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
7455
7721
  ...checkElementQualityDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
@@ -7488,7 +7754,7 @@ if (IS_BROWSER) {
7488
7754
  addBrowserFindings(groupMap, document.body, typoFindings);
7489
7755
  }
7490
7756
 
7491
- const sectionKickerFindings = checkRepeatedSectionKickersDOM()
7757
+ const sectionKickerFindings = checkKickerAboveHeadingDOM()
7492
7758
  .map(f => ({ type: f.id, detail: f.snippet }))
7493
7759
  .filter(f => _ruleOk(f.type));
7494
7760
  if (sectionKickerFindings.length > 0) {