impeccable 2.1.8 → 2.1.9

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.
@@ -57,7 +57,13 @@ const BORDER_SAFE_TAGS = new Set(
57
57
  );
58
58
 
59
59
  const OVERUSED_FONTS = new Set([
60
+ // Older monoculture (still ubiquitous):
60
61
  'inter', 'roboto', 'open sans', 'lato', 'montserrat', 'arial', 'helvetica',
62
+ // Newer monoculture (the Anthropic-skill / Vercel / GitHub default wave):
63
+ 'fraunces', 'instrument sans',
64
+ 'geist', 'geist sans', 'geist mono',
65
+ 'mona sans',
66
+ 'plus jakarta sans', 'space grotesk', 'recoleta',
61
67
  ]);
62
68
 
63
69
  // Brand-associated fonts: don't flag these as "overused" on the brand's own domains.
@@ -66,10 +72,16 @@ const GOOGLE_DOMAINS = [
66
72
  'google.com', 'youtube.com', 'android.com', 'chromium.org',
67
73
  'chrome.com', 'web.dev', 'gstatic.com', 'firebase.google.com',
68
74
  ];
75
+ const VERCEL_DOMAINS = ['vercel.com', 'nextjs.org', 'v0.app'];
76
+ const GITHUB_DOMAINS = ['github.com', 'githubnext.com'];
69
77
  const BRAND_FONT_DOMAINS = {
70
78
  'roboto': GOOGLE_DOMAINS,
71
79
  'google sans': GOOGLE_DOMAINS,
72
80
  'product sans': GOOGLE_DOMAINS,
81
+ 'geist': VERCEL_DOMAINS,
82
+ 'geist sans': VERCEL_DOMAINS,
83
+ 'geist mono': VERCEL_DOMAINS,
84
+ 'mona sans': GITHUB_DOMAINS,
73
85
  };
74
86
 
75
87
  function isBrandFontOnOwnDomain(font) {
@@ -87,6 +99,23 @@ const GENERIC_FONTS = new Set([
87
99
  'inherit', 'initial', 'unset', 'revert',
88
100
  ]);
89
101
 
102
+ // Serif faces that show up in italic-display heroes. The rule also fires when
103
+ // the primary face is unknown but the stack ends in the generic `serif` token,
104
+ // which catches custom/private faces with a serif fallback.
105
+ const KNOWN_SERIF_FONTS = new Set([
106
+ 'fraunces', 'recoleta', 'newsreader', 'playfair display', 'playfair',
107
+ 'cormorant', 'cormorant garamond', 'garamond', 'eb garamond',
108
+ 'tiempos', 'tiempos headline', 'tiempos text',
109
+ 'lora', 'vollkorn', 'spectral',
110
+ 'source serif pro', 'source serif 4', 'source serif',
111
+ 'ibm plex serif', 'merriweather',
112
+ 'libre caslon', 'libre baskerville', 'baskerville',
113
+ 'georgia', 'times new roman', 'times',
114
+ 'dm serif display', 'dm serif text',
115
+ 'instrument serif', 'gt sectra', 'ogg', 'canela',
116
+ 'freight display', 'freight text',
117
+ ]);
118
+
90
119
  const ANTIPATTERNS = [
91
120
  // ── AI slop: tells that something was AI-generated ──
92
121
  {
@@ -112,7 +141,7 @@ const ANTIPATTERNS = [
112
141
  category: 'slop',
113
142
  name: 'Overused font',
114
143
  description:
115
- 'Inter, Roboto, Open Sans, Lato, Montserrat, and Arial are used on millions of sites. Choose a distinctive font that gives your interface personality.',
144
+ 'Inter, Roboto, Fraunces, Geist, Plus Jakarta Sans, and Space Grotesk are used on so many sites they no longer feel distinctive. Each new wave of AI-generated UIs converges on the same handful of faces. Choose a face that gives your interface personality.',
116
145
  skillSection: 'Typography',
117
146
  skillGuideline: 'overused fonts like Inter',
118
147
  },
@@ -206,6 +235,34 @@ const ANTIPATTERNS = [
206
235
  skillSection: 'Typography',
207
236
  skillGuideline: 'large icons with rounded corners above every heading',
208
237
  },
238
+ {
239
+ id: 'italic-serif-display',
240
+ category: 'slop',
241
+ name: 'Italic serif display headline',
242
+ description:
243
+ 'Oversized italic serif (Fraunces, Recoleta, Playfair, Newsreader-italic) as the primary hero headline reads as taste in isolation but has become the universal AI-startup landing page hero. Set roman, or move to a non-serif display face. Editorial / magazine register may legitimately want this — judge by context.',
244
+ skillSection: 'Typography',
245
+ skillGuideline: 'oversized italic serif as the hero headline',
246
+ },
247
+ {
248
+ id: 'hero-eyebrow-chip',
249
+ category: 'slop',
250
+ name: 'Hero eyebrow / pill chip',
251
+ description:
252
+ 'A tiny uppercase letter-spaced label sitting immediately above an oversized hero headline — or the same shape rendered as a pill chip — is now the default AI SaaS hero. Drop the eyebrow, integrate the kicker into the headline, or run it as a navigation breadcrumb instead.',
253
+ skillSection: 'Typography',
254
+ skillGuideline: 'tiny uppercase tracked label above the hero headline',
255
+ },
256
+ {
257
+ id: 'repeated-section-kickers',
258
+ category: 'slop',
259
+ severity: 'advisory',
260
+ name: 'Repeated section kicker labels',
261
+ description:
262
+ '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.',
263
+ skillSection: 'Typography',
264
+ skillGuideline: 'repeated eyebrow or kicker labels as section scaffolding',
265
+ },
209
266
 
210
267
  // ── Quality: general design and accessibility issues ──
211
268
  {
@@ -258,6 +315,13 @@ const ANTIPATTERNS = [
258
315
  description:
259
316
  'Text is too close to the edge of its container. Add at least 8px (ideally 12-16px) of padding inside bordered or colored containers.',
260
317
  },
318
+ {
319
+ id: 'body-text-viewport-edge',
320
+ category: 'quality',
321
+ name: 'Body text touching viewport edge',
322
+ description:
323
+ 'Body paragraphs render flush against the left or right viewport edge with no container providing horizontal padding. Wrap content in a container with at least 16px (ideally 24-32px) of horizontal padding, or apply max-width with mx-auto.',
324
+ },
261
325
  {
262
326
  id: 'tight-leading',
263
327
  category: 'quality',
@@ -461,7 +525,18 @@ function isEmojiOnlyText(text) {
461
525
 
462
526
  function checkColors(opts) {
463
527
  const { tag, textColor, bgColor, effectiveBg, effectiveBgStops, fontSize, fontWeight, hasDirectText, isEmojiOnly, bgClip, bgImage, classList } = opts;
464
- if (SAFE_TAGS.has(tag)) return [];
528
+ if (SAFE_TAGS.has(tag)) {
529
+ // Exception for <a> and <button> elements styled as buttons. SAFE_TAGS
530
+ // exists to suppress contrast noise on inline links and unstyled controls,
531
+ // where the element has no own background and the contrast against the
532
+ // ancestor surface is already the intended visual. When the element has
533
+ // its own opaque background and direct text, it is a styled button — and
534
+ // contrast on its own surface is a real, frequent bug worth flagging.
535
+ const isStyledButton = (tag === 'a' || tag === 'button')
536
+ && hasDirectText
537
+ && bgColor && bgColor.a > 0.5;
538
+ if (!isStyledButton) return [];
539
+ }
465
540
  const findings = [];
466
541
 
467
542
  // Pure black background (only solid or near-solid, not semi-transparent overlays)
@@ -491,7 +566,20 @@ function checkColors(opts) {
491
566
  const isLargeText = fontSize >= 18 || (fontSize >= 14 && fontWeight >= 700) || isHeading;
492
567
  const threshold = isLargeText ? 3.0 : 4.5;
493
568
  if (ratio < threshold) {
494
- findings.push({ id: 'low-contrast', snippet: `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}` });
569
+ // Skip the false-positive class where text has alpha < 1 AND we
570
+ // couldn't find an opaque ancestor (effectiveBg is null, we're
571
+ // comparing against gradient-stop fallback). In jsdom mode the
572
+ // detector can't resolve `var(--X)` color tokens, so a dark
573
+ // section sitting between the text and the body's decorative
574
+ // gradient is invisible to us — we end up measuring contrast
575
+ // against the body's paper-grain noise instead of the real
576
+ // local bg. Real low-contrast bugs use alpha=1 and have a
577
+ // resolvable opaque ancestor; semi-transparent Tailwind tokens
578
+ // like `text-paper/60` on `bg-ink` sections are the FP pattern.
579
+ const isAlphaFallbackFP = !IS_BROWSER && !effectiveBg && (textColor.a != null && textColor.a < 1);
580
+ if (!isAlphaFallbackFP) {
581
+ findings.push({ id: 'low-contrast', snippet: `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}` });
582
+ }
495
583
  }
496
584
  }
497
585
 
@@ -600,6 +688,150 @@ function checkIconTile(opts) {
600
688
  }];
601
689
  }
602
690
 
691
+ // Resolve the primary (non-generic) face from a font-family string and return
692
+ // whether the resolved primary is serif. Two paths:
693
+ // 1. Primary face is in KNOWN_SERIF_FONTS → serif.
694
+ // 2. Primary face is unknown but the stack ends in the generic `serif`
695
+ // token → treat as serif. Authors who declare `font-family: 'X', serif`
696
+ // almost always have a serif primary; a sans declared with a serif
697
+ // fallback is a code smell, not the common case.
698
+ // Returns { primary, isSerif } so the snippet can name the face.
699
+ function resolveSerif(fontFamily) {
700
+ if (!fontFamily) return { primary: null, isSerif: false };
701
+ const tokens = fontFamily.split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase());
702
+ const primary = tokens.find(f => f && !GENERIC_FONTS.has(f)) || null;
703
+ if (!primary) return { primary: null, isSerif: false };
704
+ if (KNOWN_SERIF_FONTS.has(primary)) return { primary, isSerif: true };
705
+ if (tokens.includes('serif')) return { primary, isSerif: true };
706
+ return { primary, isSerif: false };
707
+ }
708
+
709
+ function checkItalicSerif(opts) {
710
+ const { tag, fontStyle, fontFamily, fontSize, headingText } = opts;
711
+ if (fontStyle !== 'italic') return [];
712
+ // Anchor the rule on hero-scale text. h1 is the canonical hero element;
713
+ // h2 ≥ 48px catches the cases where the design demotes the visual hero
714
+ // to an h2 but keeps the size.
715
+ if (tag !== 'h1' && !(tag === 'h2' && fontSize >= 48)) return [];
716
+ if (fontSize < 48) return [];
717
+ const { primary, isSerif } = resolveSerif(fontFamily);
718
+ if (!isSerif) return [];
719
+
720
+ const text = (headingText || '').trim().slice(0, 60);
721
+ return [{
722
+ id: 'italic-serif-display',
723
+ snippet: `italic serif ${tag} (${primary || 'serif'}) at ${Math.round(fontSize)}px "${text}"`,
724
+ }];
725
+ }
726
+
727
+ // Color saturation check. Returns true when the color has visible
728
+ // chroma — i.e., it's an "accent color" rather than near-neutral.
729
+ // Handles rgb()/rgba(), #hex, oklch(), and hsl(). var() refs are
730
+ // expected to be pre-resolved by the caller.
731
+ function isAccentColor(cssColor) {
732
+ if (!cssColor) return false;
733
+ const s = String(cssColor).trim();
734
+ // rgb / rgba — direct channel-distance check.
735
+ const rgbM = /rgba?\(\s*(\d+)\s*,?\s+|\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/.exec(s.replace(/rgba?\(\s*/, 'rgb(').replace(/,/g, ', '));
736
+ const rgbStrict = /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/.exec(s);
737
+ if (rgbStrict) {
738
+ const r = +rgbStrict[1], g = +rgbStrict[2], b = +rgbStrict[3];
739
+ return (Math.max(r, g, b) - Math.min(r, g, b)) >= 40;
740
+ }
741
+ // #hex — 3, 4, 6, or 8 digit.
742
+ const hexM = /^#([0-9a-f]{3,8})\b/i.exec(s);
743
+ if (hexM) {
744
+ let h = hexM[1];
745
+ if (h.length === 3 || h.length === 4) h = h.split('').map((c) => c + c).join('').slice(0, 6);
746
+ else h = h.slice(0, 6);
747
+ if (h.length === 6) {
748
+ const r = parseInt(h.slice(0, 2), 16);
749
+ const g = parseInt(h.slice(2, 4), 16);
750
+ const b = parseInt(h.slice(4, 6), 16);
751
+ return (Math.max(r, g, b) - Math.min(r, g, b)) >= 40;
752
+ }
753
+ }
754
+ // oklch(L C H) — chroma C is what matters. Typical neutral grays
755
+ // have C < 0.02; visible accents are 0.05+. CSS minification can
756
+ // collapse spaces between L% and C ("oklch(43%.15 34)"), so we
757
+ // extract all numbers and take the second rather than matching a
758
+ // strict L-then-whitespace-then-C pattern.
759
+ if (/^oklch\(/i.test(s)) {
760
+ const nums = s.match(/\d*\.\d+|\d+/g);
761
+ if (nums && nums.length >= 2) {
762
+ const c = parseFloat(nums[1]);
763
+ return !Number.isNaN(c) && c >= 0.05;
764
+ }
765
+ }
766
+ // hsl(H, S%, L%) — saturation > 20% reads as accent.
767
+ const hslM = /hsla?\(\s*[\d.]+\s*,\s*([\d.]+)%/i.exec(s);
768
+ if (hslM) {
769
+ const sat = parseFloat(hslM[1]);
770
+ return !Number.isNaN(sat) && sat >= 20;
771
+ }
772
+ return false;
773
+ }
774
+
775
+ // Sibling-relationship rule. Anchor on a hero-scale h1, look at the
776
+ // previousElementSibling, and gate on EITHER the classic tracked-
777
+ // uppercase eyebrow OR the modern accent-colored bold eyebrow.
778
+ function checkHeroEyebrow(opts) {
779
+ const {
780
+ headingTag, headingText, headingFontSize,
781
+ siblingTag, siblingText, siblingTextTransform,
782
+ siblingFontSize, siblingLetterSpacing,
783
+ siblingFontWeight, siblingColor,
784
+ } = opts;
785
+ if (headingTag !== 'h1') return [];
786
+ // We previously gated on headingFontSize >= 48 to anchor "hero scale".
787
+ // But modern hero h1s use clamp() / vw / var(--text-*), none of which
788
+ // jsdom can resolve — the computed value comes back as "2em" or
789
+ // "var(--text-9xl)" and parseFloat returns 2 or NaN. The gate fails
790
+ // on virtually every Tailwind v4 / framework build. The other gates
791
+ // (sibling text 2-60 chars, font-size ≤ 14px, accent-bold OR
792
+ // tracked-caps) are tight enough to avoid false positives on non-
793
+ // hero h1s — a tiny tan label directly above any h1 is the
794
+ // antipattern regardless of how big the h1 ends up.
795
+ if (!siblingTag) return [];
796
+ // An h2 above an h1 is a different anti-pattern (heading hierarchy / dual
797
+ // headings) — never an eyebrow.
798
+ if (HEADING_TAGS.has(siblingTag)) return [];
799
+
800
+ const text = (siblingText || '').trim();
801
+ if (text.length < 2 || text.length > 60) return [];
802
+ if (!(siblingFontSize > 0 && siblingFontSize <= 14)) return [];
803
+
804
+ // Branch A: classic tracked-uppercase eyebrow.
805
+ const isUppercased = siblingTextTransform === 'uppercase'
806
+ || (/[A-Z]/.test(text) && !/[a-z]/.test(text));
807
+ const isClassicTracked = isUppercased && siblingLetterSpacing >= 1.6;
808
+
809
+ // Branch B: modern accent-bold eyebrow — sentence case, low
810
+ // tracking, but bold + accent-colored. The style choices changed;
811
+ // the pattern is the same kicker-above-headline anti-pattern.
812
+ const weight = Number(siblingFontWeight) || 400;
813
+ const isAccentBold = weight >= 700 && isAccentColor(siblingColor || '');
814
+
815
+ if (!isClassicTracked && !isAccentBold) return [];
816
+
817
+ const headingTextSnippet = (headingText || '').trim().slice(0, 60);
818
+ const eyebrowSnippet = text.slice(0, 40);
819
+ const style = isClassicTracked ? 'tracked-caps' : 'accent-bold';
820
+ return [{
821
+ id: 'hero-eyebrow-chip',
822
+ snippet: `eyebrow chip (${style}) "${eyebrowSnippet}" above ${headingTag} "${headingTextSnippet}"`,
823
+ }];
824
+ }
825
+
826
+ function checkRepeatedSectionKickers(opts) {
827
+ const { candidates, minCount = 3 } = opts;
828
+ if (!Array.isArray(candidates) || candidates.length < minCount) return [];
829
+ return candidates.map(candidate => ({
830
+ id: 'repeated-section-kickers',
831
+ snippet: `repeated section kicker "${candidate.kickerText}" before ${candidate.headingTag} "${candidate.headingText}" (${candidates.length} on page)`,
832
+ }));
833
+ }
834
+
603
835
  const LAYOUT_TRANSITION_PROPS = new Set([
604
836
  'width', 'height', 'padding', 'margin',
605
837
  'max-height', 'max-width', 'min-height', 'min-width',
@@ -813,43 +1045,88 @@ function checkHtmlPatterns(html) {
813
1045
 
814
1046
  // ─── Section 4: resolveBackground (unified) ─────────────────────────────────
815
1047
 
816
- function resolveBackground(el, win) {
1048
+ // Read the element's own background color, computed-style first, with a
1049
+ // jsdom-friendly fallback that parses the inline `background:` shorthand
1050
+ // from the raw style attribute. jsdom (~v29) does not decompose the
1051
+ // shorthand into `backgroundColor`, so without this fallback the CLI silently
1052
+ // returns null for any element styled via `background: rgb(...)` or
1053
+ // `background: #abc`. Real browsers always decompose, so the fallback is
1054
+ // a no-op there.
1055
+ function readOwnBackgroundColor(el, computedStyle) {
1056
+ const bg = parseRgb(computedStyle.backgroundColor);
1057
+ if (IS_BROWSER || (bg && bg.a >= 0.1)) return bg;
1058
+ const rawStyle = el.getAttribute?.('style') || '';
1059
+ const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
1060
+ const inlineBg = bgMatch ? bgMatch[1].trim() : '';
1061
+ if (!inlineBg) return bg;
1062
+ if (/gradient/i.test(inlineBg) || /url\s*\(/i.test(inlineBg)) return bg;
1063
+ const fromRgb = parseRgb(inlineBg);
1064
+ if (fromRgb) return fromRgb;
1065
+ const hexMatch = inlineBg.match(/#([0-9a-f]{6}|[0-9a-f]{3})\b/i);
1066
+ if (hexMatch) {
1067
+ const h = hexMatch[1];
1068
+ if (h.length === 6) {
1069
+ return { r: parseInt(h.slice(0, 2), 16), g: parseInt(h.slice(2, 4), 16), b: parseInt(h.slice(4, 6), 16), a: 1 };
1070
+ }
1071
+ return { r: parseInt(h[0] + h[0], 16), g: parseInt(h[1] + h[1], 16), b: parseInt(h[2] + h[2], 16), a: 1 };
1072
+ }
1073
+ return bg;
1074
+ }
1075
+
1076
+ function resolveBackground(el, win, customPropMap) {
817
1077
  let current = el;
818
1078
  while (current && current.nodeType === 1) {
819
1079
  const style = IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
820
-
821
- // If this element has a background-image (gradient or url), it's visually
822
- // opaque but we can't determine the effective color — bail out so callers
823
- // don't get a false solid-color answer.
824
1080
  const bgImage = style.backgroundImage || '';
825
- if (bgImage && bgImage !== 'none' && (/gradient/i.test(bgImage) || /url\s*\(/i.test(bgImage))) {
826
- return null;
827
- }
828
-
1081
+ const hasGradientOrUrl = bgImage && bgImage !== 'none' && (/gradient/i.test(bgImage) || /url\s*\(/i.test(bgImage));
1082
+
1083
+ // Try the solid bg-color FIRST. If the element has both a solid color
1084
+ // and a gradient/url overlay (a common pattern: `background: var(--paper)
1085
+ // radial-gradient(...)` for paper-grain texture), the solid color is the
1086
+ // dominant visible surface for contrast purposes; the overlay is
1087
+ // decorative. The old behavior bailed on any gradient ancestor, which
1088
+ // caused massive false-positive contrast findings on grain-textured
1089
+ // body backgrounds.
829
1090
  let bg = parseRgb(style.backgroundColor);
830
1091
  if (!IS_BROWSER && (!bg || bg.a < 0.1)) {
831
- // jsdom doesn't decompose background shorthand — parse raw style attr
832
- const rawStyle = current.getAttribute?.('style') || '';
833
- const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
834
- const inlineBg = bgMatch ? bgMatch[1].trim() : '';
835
- // Check for gradient or url() image in inline style too
836
- if (/gradient/i.test(inlineBg) || /url\s*\(/i.test(inlineBg)) return null;
837
- bg = parseRgb(inlineBg);
838
- if (!bg && inlineBg) {
839
- const hexMatch = inlineBg.match(/#([0-9a-f]{6}|[0-9a-f]{3})\b/i);
840
- if (hexMatch) {
841
- const h = hexMatch[1];
842
- if (h.length === 6) {
843
- bg = { r: parseInt(h.slice(0,2), 16), g: parseInt(h.slice(2,4), 16), b: parseInt(h.slice(4,6), 16), a: 1 };
844
- } else {
845
- bg = { r: parseInt(h[0]+h[0], 16), g: parseInt(h[1]+h[1], 16), b: parseInt(h[2]+h[2], 16), a: 1 };
846
- }
1092
+ // jsdom returns literal "var(--X)" / "oklch(...)" strings. Resolve
1093
+ // through customPropMap so Tailwind v4 color tokens become RGB.
1094
+ if (customPropMap) {
1095
+ bg = parseColorResolved(style.backgroundColor, customPropMap);
1096
+ }
1097
+ if (!bg || bg.a < 0.1) {
1098
+ // Inline-style fallback. jsdom doesn't decompose background
1099
+ // shorthand, so colors set via inline style are otherwise invisible.
1100
+ const rawStyle = current.getAttribute?.('style') || '';
1101
+ const bgMatch = rawStyle.match(/background(?:-color)?\s*:\s*([^;]+)/i);
1102
+ const inlineBg = bgMatch ? bgMatch[1].trim() : '';
1103
+ if (inlineBg && !/gradient/i.test(inlineBg) && !/url\s*\(/i.test(inlineBg)) {
1104
+ bg = parseColorResolved(inlineBg, customPropMap) || parseAnyColor(inlineBg);
847
1105
  }
848
1106
  }
849
1107
  }
1108
+
850
1109
  if (bg && bg.a > 0.1) {
851
1110
  if (IS_BROWSER || bg.a >= 0.5) return bg;
852
1111
  }
1112
+ // No solid bg-color at this level. If THIS level has a gradient/url
1113
+ // with no underlying solid color we can read:
1114
+ // • on body/html: assume white. Body-level gradients are almost
1115
+ // always decorative texture (paper grain, noise) on top of a
1116
+ // solid bg-color the page set via `background: var(--paper)`
1117
+ // shorthand — which jsdom can't decompose into bg-color. The
1118
+ // downstream gradient-stops fallback path produces catastrophic
1119
+ // false positives in this case (gradient noise stops have
1120
+ // accidental browns/blacks that look like card backgrounds).
1121
+ // • on other elements: bail to null and let the caller fall back
1122
+ // to gradient stops (gradient buttons / hero sections are real
1123
+ // bgs worth checking against).
1124
+ if (hasGradientOrUrl) {
1125
+ if (current.tagName === 'BODY' || current.tagName === 'HTML') {
1126
+ return { r: 255, g: 255, b: 255, a: 1 };
1127
+ }
1128
+ return null;
1129
+ }
853
1130
  current = current.parentElement;
854
1131
  }
855
1132
  return { r: 255, g: 255, b: 255 };
@@ -978,7 +1255,9 @@ function checkElementBordersDOM(el) {
978
1255
 
979
1256
  function checkElementColorsDOM(el) {
980
1257
  const tag = el.tagName.toLowerCase();
981
- if (SAFE_TAGS.has(tag)) return [];
1258
+ // No early SAFE_TAGS bail here — checkColors() does its own gating that
1259
+ // includes the styled-button exception for <a> / <button> with their own
1260
+ // opaque background. Bailing here would prevent that exception from firing.
982
1261
  const rect = el.getBoundingClientRect();
983
1262
  if (rect.width < 10 || rect.height < 10) return [];
984
1263
  const style = getComputedStyle(el);
@@ -988,7 +1267,7 @@ function checkElementColorsDOM(el) {
988
1267
  return checkColors({
989
1268
  tag,
990
1269
  textColor: parseRgb(style.color),
991
- bgColor: parseRgb(style.backgroundColor),
1270
+ bgColor: readOwnBackgroundColor(el, style),
992
1271
  effectiveBg,
993
1272
  effectiveBgStops: effectiveBg ? null : resolveGradientStops(el),
994
1273
  fontSize: parseFloat(style.fontSize) || 16,
@@ -1036,6 +1315,274 @@ function checkElementIconTileDOM(el) {
1036
1315
  });
1037
1316
  }
1038
1317
 
1318
+ function checkElementItalicSerifDOM(el) {
1319
+ const tag = el.tagName.toLowerCase();
1320
+ if (tag !== 'h1' && tag !== 'h2') return [];
1321
+ const style = getComputedStyle(el);
1322
+ return checkItalicSerif({
1323
+ tag,
1324
+ fontStyle: style.fontStyle || '',
1325
+ fontFamily: style.fontFamily || '',
1326
+ fontSize: parseFloat(style.fontSize) || 0,
1327
+ headingText: el.textContent || '',
1328
+ });
1329
+ }
1330
+
1331
+ function checkElementHeroEyebrowDOM(el) {
1332
+ const tag = el.tagName.toLowerCase();
1333
+ if (tag !== 'h1') return [];
1334
+ const sibling = el.previousElementSibling;
1335
+ if (!sibling) return [];
1336
+ const headStyle = getComputedStyle(el);
1337
+ const sibStyle = getComputedStyle(sibling);
1338
+ return checkHeroEyebrow({
1339
+ headingTag: tag,
1340
+ headingText: el.textContent || '',
1341
+ headingFontSize: parseFloat(headStyle.fontSize) || 0,
1342
+ siblingTag: sibling.tagName.toLowerCase(),
1343
+ siblingText: sibling.textContent || '',
1344
+ siblingTextTransform: sibStyle.textTransform || '',
1345
+ siblingFontSize: parseFloat(sibStyle.fontSize) || 0,
1346
+ siblingLetterSpacing: parseFloat(sibStyle.letterSpacing) || 0,
1347
+ siblingFontWeight: sibStyle.fontWeight || '',
1348
+ siblingColor: sibStyle.color || '',
1349
+ });
1350
+ }
1351
+
1352
+ // Build a map of CSS custom properties declared on :root / :host / html.
1353
+ // Used to resolve var(--X) refs that jsdom returns verbatim in
1354
+ // getComputedStyle. Tailwind v4 routes every utility class through
1355
+ // CSS vars (font-weight: var(--font-weight-bold), font-size:
1356
+ // var(--text-xs), letter-spacing: var(--tracking-widest)), so without
1357
+ // resolution every style-based check silently fails on Tailwind v4
1358
+ // builds — the values come back as literal "var(--font-weight-bold)"
1359
+ // strings and parseFloat returns NaN.
1360
+ function buildCustomPropMap(document) {
1361
+ const map = new Map();
1362
+ let sheets;
1363
+ try { sheets = Array.from(document.styleSheets || []); }
1364
+ catch { return map; }
1365
+ for (const sheet of sheets) {
1366
+ let rules;
1367
+ try { rules = Array.from(sheet.cssRules || []); }
1368
+ catch { continue; }
1369
+ for (const rule of rules) {
1370
+ // Style rules only (type 1). Walk @media / @supports if present.
1371
+ if (rule.type === 4 /* MEDIA_RULE */ || rule.type === 12 /* SUPPORTS_RULE */) {
1372
+ try { rules.push(...Array.from(rule.cssRules || [])); } catch { /* ignore */ }
1373
+ continue;
1374
+ }
1375
+ if (rule.type !== 1 /* STYLE_RULE */) continue;
1376
+ const sel = rule.selectorText || '';
1377
+ if (!/(^|,\s*)(:root|html|:host)\b/i.test(sel)) continue;
1378
+ const style = rule.style;
1379
+ if (!style) continue;
1380
+ for (let i = 0; i < style.length; i++) {
1381
+ const prop = style[i];
1382
+ if (!prop || !prop.startsWith('--')) continue;
1383
+ const val = style.getPropertyValue(prop).trim();
1384
+ if (val) map.set(prop, val);
1385
+ }
1386
+ }
1387
+ }
1388
+ return map;
1389
+ }
1390
+
1391
+ // Resolve var(--X[, fallback]) refs in a computed-style value string.
1392
+ // Recurses up to 8 levels for chained refs (--a: var(--b)). Returns
1393
+ // the original string when no refs are present or the chain doesn't
1394
+ // resolve. Safe to call on already-resolved values.
1395
+ function resolveVarRefs(raw, customPropMap, depth = 0) {
1396
+ if (typeof raw !== 'string' || !raw.includes('var(')) return raw;
1397
+ if (depth > 8) return raw;
1398
+ return raw.replace(/var\(\s*(--[a-zA-Z0-9_-]+)\s*(?:,\s*([^)]+))?\)/g, (_m, name, fallback) => {
1399
+ const v = customPropMap.get(name);
1400
+ if (v != null) return resolveVarRefs(v, customPropMap, depth + 1);
1401
+ return fallback ? resolveVarRefs(fallback.trim(), customPropMap, depth + 1) : _m;
1402
+ });
1403
+ }
1404
+
1405
+ // OKLCH → sRGB conversion (Björn Ottosson's matrices). L in 0..1 (or %),
1406
+ // C in 0..~0.4 typical, H in degrees. Returns clamped {r,g,b,a:1} in 0..255.
1407
+ // Needed because jsdom doesn't compute oklch() values — getComputedStyle
1408
+ // returns the literal "oklch(...)" string. Without this, the entire
1409
+ // Tailwind v4 color palette (which is OKLCH-based) is invisible to the
1410
+ // detector's contrast / color checks.
1411
+ function oklchToRgb(L, C, H) {
1412
+ const hRad = (H * Math.PI) / 180;
1413
+ const a = C * Math.cos(hRad);
1414
+ const b = C * Math.sin(hRad);
1415
+ const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
1416
+ const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
1417
+ const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
1418
+ const lc = l_ * l_ * l_, mc = m_ * m_ * m_, sc = s_ * s_ * s_;
1419
+ const rLin = 4.0767416621 * lc - 3.3077115913 * mc + 0.2309699292 * sc;
1420
+ const gLin = -1.2684380046 * lc + 2.6097574011 * mc - 0.3413193965 * sc;
1421
+ const bLin = -0.0041960863 * lc - 0.7034186147 * mc + 1.7076147010 * sc;
1422
+ const enc = (x) => {
1423
+ const c = Math.max(0, Math.min(1, x));
1424
+ return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
1425
+ };
1426
+ return {
1427
+ r: Math.round(enc(rLin) * 255),
1428
+ g: Math.round(enc(gLin) * 255),
1429
+ b: Math.round(enc(bLin) * 255),
1430
+ a: 1,
1431
+ };
1432
+ }
1433
+
1434
+ // Extended color parser: rgb/rgba/hex/oklch. Returns null on no match.
1435
+ // Use this when the input might be any CSS color form; use plain parseRgb
1436
+ // when you only expect computed rgb() values from real browsers.
1437
+ function parseAnyColor(s) {
1438
+ if (!s || typeof s !== 'string') return null;
1439
+ const str = s.trim();
1440
+ if (str === 'transparent' || str === 'currentcolor' || str === 'inherit') return null;
1441
+ let m;
1442
+ m = str.match(/rgba?\(\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)\s*,?\s*(\d+(?:\.\d+)?)(?:\s*[,/]\s*([\d.]+))?\s*\)/);
1443
+ if (m) return { r: Math.round(+m[1]), g: Math.round(+m[2]), b: Math.round(+m[3]), a: m[4] !== undefined ? +m[4] : 1 };
1444
+ m = str.match(/^#([0-9a-f]{3,8})$/i);
1445
+ if (m) {
1446
+ const h = m[1];
1447
+ if (h.length === 3 || h.length === 4) {
1448
+ return {
1449
+ r: parseInt(h[0] + h[0], 16),
1450
+ g: parseInt(h[1] + h[1], 16),
1451
+ b: parseInt(h[2] + h[2], 16),
1452
+ a: h.length === 4 ? parseInt(h[3] + h[3], 16) / 255 : 1,
1453
+ };
1454
+ }
1455
+ if (h.length === 6 || h.length === 8) {
1456
+ return {
1457
+ r: parseInt(h.slice(0, 2), 16),
1458
+ g: parseInt(h.slice(2, 4), 16),
1459
+ b: parseInt(h.slice(4, 6), 16),
1460
+ a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1,
1461
+ };
1462
+ }
1463
+ }
1464
+ // OKLCH parser. Tailwind v4's CSS minifier squishes the space after
1465
+ // `%` ("21.5%.02 50"), so the separator between L and C may be absent.
1466
+ // Match L (with optional %), then C and H separated permissively.
1467
+ m = str.match(/oklch\(\s*([\d.]+)(%?)\s*[\s,]*\s*([\d.]+)\s*[\s,]+\s*([-\d.]+)(?:deg)?\s*\)/i);
1468
+ if (m) {
1469
+ const Lnum = parseFloat(m[1]);
1470
+ const L = m[2] === '%' ? Lnum / 100 : Lnum;
1471
+ return oklchToRgb(L, parseFloat(m[3]), parseFloat(m[4]));
1472
+ }
1473
+ return null;
1474
+ }
1475
+
1476
+ // Resolve var() refs in a color string (via customPropMap), then parse.
1477
+ // Returns null on any failure. Used in jsdom-mode paths where
1478
+ // getComputedStyle returns literal "var(--X)" or "oklch(...)" strings.
1479
+ function parseColorResolved(str, customPropMap) {
1480
+ if (!str) return null;
1481
+ const resolved = customPropMap ? resolveVarRefs(str, customPropMap) : str;
1482
+ return parseAnyColor(resolved);
1483
+ }
1484
+
1485
+ const REPEATED_KICKER_SKIP_SELECTOR = [
1486
+ 'nav',
1487
+ 'form',
1488
+ 'table',
1489
+ 'thead',
1490
+ 'tbody',
1491
+ 'tfoot',
1492
+ 'figure',
1493
+ 'figcaption',
1494
+ 'ol',
1495
+ 'ul',
1496
+ 'li',
1497
+ '[role="navigation"]',
1498
+ '[aria-label*="breadcrumb" i]',
1499
+ '[class*="breadcrumb" i]',
1500
+ '[data-impeccable-allow-kickers]',
1501
+ ].join(',');
1502
+
1503
+ function cleanInlineText(el) {
1504
+ return [...el.childNodes]
1505
+ .filter(n => n.nodeType === 3)
1506
+ .map(n => n.textContent)
1507
+ .join(' ')
1508
+ .replace(/\s+/g, ' ')
1509
+ .trim();
1510
+ }
1511
+
1512
+ function isRepeatedKickerCandidate(opts) {
1513
+ const {
1514
+ headingTag,
1515
+ headingText,
1516
+ headingFontSize,
1517
+ kickerTag,
1518
+ kickerText,
1519
+ kickerTextTransform,
1520
+ kickerFontSize,
1521
+ kickerLetterSpacing,
1522
+ } = opts;
1523
+ if (!['h2', 'h3', 'h4'].includes(headingTag)) return false;
1524
+ if (!headingText || headingText.length < 3) return false;
1525
+ if (!(headingFontSize >= 20)) return false;
1526
+ if (!kickerTag || HEADING_TAGS.has(kickerTag)) return false;
1527
+ if (!['p', 'span', 'div', 'small'].includes(kickerTag)) return false;
1528
+ if (!kickerText || kickerText.length < 2 || kickerText.length > 34) return false;
1529
+ if (/^step\s*\d+/i.test(kickerText) || /^\d{1,2}$/.test(kickerText)) return false;
1530
+
1531
+ const isUppercased = kickerTextTransform === 'uppercase'
1532
+ || (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText));
1533
+ if (!isUppercased) return false;
1534
+ if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false;
1535
+ const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08);
1536
+ if (!(kickerLetterSpacing >= minTrackedSpacing)) return false;
1537
+ return true;
1538
+ }
1539
+
1540
+ function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpacing) {
1541
+ const candidates = [];
1542
+ for (const heading of doc.querySelectorAll('h2, h3, h4')) {
1543
+ if (heading.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
1544
+ const kicker = heading.previousElementSibling;
1545
+ if (!kicker || kicker.closest?.(REPEATED_KICKER_SKIP_SELECTOR)) continue;
1546
+
1547
+ const headingStyle = getStyle(heading);
1548
+ const kickerStyle = getStyle(kicker);
1549
+ const headingText = (heading.textContent || '').replace(/\s+/g, ' ').trim();
1550
+ const kickerText = cleanInlineText(kicker) || (kicker.textContent || '').replace(/\s+/g, ' ').trim();
1551
+ const headingFontSize = resolveLetterSpacing(headingStyle.fontSize || '', 16) || parseFloat(headingStyle.fontSize) || 0;
1552
+ const kickerFontSize = resolveLetterSpacing(kickerStyle.fontSize || '', 16) || parseFloat(kickerStyle.fontSize) || 0;
1553
+ const kickerLetterSpacing = resolveLetterSpacing(kickerStyle.letterSpacing || '', kickerFontSize);
1554
+
1555
+ if (!isRepeatedKickerCandidate({
1556
+ headingTag: heading.tagName.toLowerCase(),
1557
+ headingText,
1558
+ headingFontSize,
1559
+ kickerTag: kicker.tagName.toLowerCase(),
1560
+ kickerText,
1561
+ kickerTextTransform: kickerStyle.textTransform || '',
1562
+ kickerFontSize,
1563
+ kickerLetterSpacing,
1564
+ })) {
1565
+ continue;
1566
+ }
1567
+
1568
+ candidates.push({
1569
+ headingTag: heading.tagName.toLowerCase(),
1570
+ headingText: headingText.replace(/^"|"$/g, '').slice(0, 60),
1571
+ kickerText: kickerText.slice(0, 40),
1572
+ });
1573
+ }
1574
+ return candidates;
1575
+ }
1576
+
1577
+ function checkRepeatedSectionKickersDOM() {
1578
+ const candidates = collectRepeatedSectionKickerCandidates(
1579
+ document,
1580
+ (el) => getComputedStyle(el),
1581
+ (value, fontSize) => resolveLengthPx(value, fontSize) || 0,
1582
+ );
1583
+ return checkRepeatedSectionKickers({ candidates });
1584
+ }
1585
+
1039
1586
  function checkElementMotionDOM(el) {
1040
1587
  const tag = el.tagName.toLowerCase();
1041
1588
  if (SAFE_TAGS.has(tag)) return [];
@@ -1186,7 +1733,7 @@ function resolveLengthPx(value, fontSizePx) {
1186
1733
  // Both adapters resolve font-size, line-height and letter-spacing to pixels
1187
1734
  // before calling this so the pure function only deals with numbers.
1188
1735
  function checkQuality(opts) {
1189
- const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80 } = opts;
1736
+ const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80, viewportWidth = 0 } = opts;
1190
1737
  const findings = [];
1191
1738
  // Skip browser extension injected elements
1192
1739
  const elId = el.id || '';
@@ -1237,6 +1784,40 @@ function checkQuality(opts) {
1237
1784
  }
1238
1785
  }
1239
1786
 
1787
+ // --- Body text touching viewport edge --- (browser-only: needs rect)
1788
+ // Catches the failure mode where the agent ships body paragraphs
1789
+ // with NO container providing horizontal padding — text bleeds
1790
+ // directly to the viewport edge. Different from cramped-padding,
1791
+ // which requires a colored/bordered container. Here the failure
1792
+ // is the absence of the container entirely.
1793
+ //
1794
+ // Gate aggressively to avoid false positives:
1795
+ // - <p> or <li> only (body content; not headings, not nav, not
1796
+ // wrappers)
1797
+ // - text > 40 chars (paragraph-like, not a label)
1798
+ // - rect.width > 50% of viewport (real body, not a pull-quote)
1799
+ // - rect.left < 16 OR rect.right > viewport - 16 (actually
1800
+ // touching the edge)
1801
+ // - not inside <nav> or <header> (those legitimately bleed)
1802
+ // - element itself has no background-color (intentional full-bleed
1803
+ // sections set a bg-color and provide their own internal padding)
1804
+ if (rect && hasDirectText && textLen > 40 && ['P', 'LI'].includes(tag.toUpperCase()) && viewportWidth > 0) {
1805
+ const inNavHeader = el.closest && (el.closest('nav') || el.closest('header'));
1806
+ const hasOwnBg = style.backgroundColor && style.backgroundColor !== 'rgba(0, 0, 0, 0)' && style.backgroundColor !== 'transparent';
1807
+ const isPositioned = ['fixed', 'absolute'].includes(style.position || '');
1808
+ const widthRatio = rect.width / viewportWidth;
1809
+ const leftClose = rect.left < 16;
1810
+ const rightClose = rect.right > viewportWidth - 16;
1811
+ if (!inNavHeader && !hasOwnBg && !isPositioned && widthRatio > 0.5 && (leftClose || rightClose)) {
1812
+ const which = leftClose && rightClose
1813
+ ? `left ${Math.round(rect.left)}px / right ${Math.round(viewportWidth - rect.right)}px`
1814
+ : leftClose
1815
+ ? `left ${Math.round(rect.left)}px`
1816
+ : `right ${Math.round(viewportWidth - rect.right)}px`;
1817
+ findings.push({ id: 'body-text-viewport-edge', snippet: `<${tag.toLowerCase()}> with ${textLen}-char body bleeds to viewport edge (${which})` });
1818
+ }
1819
+ }
1820
+
1240
1821
  // --- Tight line height ---
1241
1822
  if (hasDirectText && textLen > 50 && !['h1','h2','h3','h4','h5','h6'].includes(tag)) {
1242
1823
  if (lineHeightPx != null && fontSize > 0) {
@@ -1298,7 +1879,8 @@ function checkElementQualityDOM(el) {
1298
1879
  const letterSpacingPx = resolveLengthPx(style.letterSpacing, fontSize);
1299
1880
  const rect = el.getBoundingClientRect();
1300
1881
  const lineMax = (typeof window !== 'undefined' && window.__IMPECCABLE_CONFIG__?.lineLengthMax) || 80;
1301
- return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax });
1882
+ const viewportWidth = (typeof window !== 'undefined' ? window.innerWidth : 0) || 0;
1883
+ return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax, viewportWidth });
1302
1884
  }
1303
1885
 
1304
1886
  // Pure page-level skipped-heading walk. Takes a Document so it works in both
@@ -1373,15 +1955,48 @@ function checkElementBorders(tag, style, overrides, resolvedRadius) {
1373
1955
  return checkBorders(tag, widths, colors, radius);
1374
1956
  }
1375
1957
 
1376
- function checkElementColors(el, style, tag, window) {
1958
+ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInheritRule) {
1377
1959
  const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
1378
1960
  const hasDirectText = directText.trim().length > 0;
1379
1961
 
1380
- const effectiveBg = resolveBackground(el, window);
1962
+ const effectiveBg = resolveBackground(el, window, customPropMap);
1963
+ // jsdom returns literal "var(--X)" / "oklch(...)" for color, so plain
1964
+ // parseRgb misses Tailwind-tokenized text colors. Resolve through the
1965
+ // customPropMap first; fall back to parseRgb for vanilla rgb() pages.
1966
+ let textColor = customPropMap ? parseColorResolved(style.color, customPropMap) : null;
1967
+ if (!textColor) textColor = parseRgb(style.color);
1968
+
1969
+ // Anchor-inherit FP workaround: jsdom's UA stylesheet has `:link { color:
1970
+ // blue }` at high specificity. The page's `a { color: inherit }` rule
1971
+ // (Tailwind v4 preflight) loses to jsdom even though it WINS in real
1972
+ // browsers (Chrome's UA wraps :link in :where() — zero specificity).
1973
+ // When the page declares the inherit rule AND we see jsdom's default
1974
+ // link blue on an anchor, walk to the nearest non-anchor ancestor and
1975
+ // use its color instead.
1976
+ if (
1977
+ hasAnchorInheritRule &&
1978
+ textColor &&
1979
+ textColor.r === 0 && textColor.g === 0 && textColor.b === 238 &&
1980
+ (tag === 'a' || el.closest?.('a'))
1981
+ ) {
1982
+ let cur = el.parentElement;
1983
+ while (cur && cur.tagName !== 'HTML') {
1984
+ if (cur.tagName !== 'A') {
1985
+ const ps = window.getComputedStyle(cur);
1986
+ const inh = (customPropMap ? parseColorResolved(ps.color, customPropMap) : null) || parseRgb(ps.color);
1987
+ if (inh && !(inh.r === 0 && inh.g === 0 && inh.b === 238)) {
1988
+ textColor = inh;
1989
+ break;
1990
+ }
1991
+ }
1992
+ cur = cur.parentElement;
1993
+ }
1994
+ }
1995
+
1381
1996
  return checkColors({
1382
1997
  tag,
1383
- textColor: parseRgb(style.color),
1384
- bgColor: parseRgb(style.backgroundColor),
1998
+ textColor,
1999
+ bgColor: readOwnBackgroundColor(el, style),
1385
2000
  effectiveBg,
1386
2001
  effectiveBgStops: effectiveBg ? null : resolveGradientStops(el, window),
1387
2002
  fontSize: parseFloat(style.fontSize) || 16,
@@ -1431,6 +2046,57 @@ function checkElementIconTile(el, tag, window) {
1431
2046
  });
1432
2047
  }
1433
2048
 
2049
+ function checkElementItalicSerif(el, style, tag) {
2050
+ if (tag !== 'h1' && tag !== 'h2') return [];
2051
+ return checkItalicSerif({
2052
+ tag,
2053
+ fontStyle: style.fontStyle || '',
2054
+ fontFamily: style.fontFamily || '',
2055
+ fontSize: parseFloat(style.fontSize) || 0,
2056
+ headingText: el.textContent || '',
2057
+ });
2058
+ }
2059
+
2060
+ function checkElementHeroEyebrow(el, style, tag, window, customPropMap) {
2061
+ if (tag !== 'h1') return [];
2062
+ const sibling = el.previousElementSibling;
2063
+ if (!sibling) return [];
2064
+ const sibStyle = window.getComputedStyle(sibling);
2065
+ // Resolve Tailwind v4 CSS-variable wrappers (font-weight:var(--font-weight-bold)
2066
+ // etc.) before parsing. jsdom returns these verbatim from getComputedStyle;
2067
+ // without resolution every style-based gate fails silently on Tailwind v4 builds.
2068
+ const fontSizeRaw = customPropMap ? resolveVarRefs(sibStyle.fontSize, customPropMap) : sibStyle.fontSize;
2069
+ const fontWeightRaw = customPropMap ? resolveVarRefs(sibStyle.fontWeight, customPropMap) : sibStyle.fontWeight;
2070
+ const letterSpacingRaw = customPropMap ? resolveVarRefs(sibStyle.letterSpacing, customPropMap) : sibStyle.letterSpacing;
2071
+ const colorRaw = customPropMap ? resolveVarRefs(sibStyle.color, customPropMap) : sibStyle.color;
2072
+ const headingFontSizeRaw = customPropMap ? resolveVarRefs(style.fontSize, customPropMap) : style.fontSize;
2073
+ const siblingFontSize = parseFloat(fontSizeRaw) || 0;
2074
+ // resolveLengthPx returns null for 'normal' / 'auto'; coerce to 0 so the
2075
+ // gate falls through cleanly. jsdom returns letter-spacing verbatim
2076
+ // (e.g. '0.15em'), unlike real browsers, so this conversion is required.
2077
+ return checkHeroEyebrow({
2078
+ headingTag: tag,
2079
+ headingText: el.textContent || '',
2080
+ headingFontSize: parseFloat(headingFontSizeRaw) || 0,
2081
+ siblingTag: sibling.tagName.toLowerCase(),
2082
+ siblingText: sibling.textContent || '',
2083
+ siblingTextTransform: sibStyle.textTransform || '',
2084
+ siblingFontSize,
2085
+ siblingLetterSpacing: resolveLengthPx(letterSpacingRaw, siblingFontSize) || 0,
2086
+ siblingFontWeight: fontWeightRaw || '',
2087
+ siblingColor: colorRaw || '',
2088
+ });
2089
+ }
2090
+
2091
+ function checkRepeatedSectionKickersFromDoc(doc, win) {
2092
+ const candidates = collectRepeatedSectionKickerCandidates(
2093
+ doc,
2094
+ (el) => win.getComputedStyle(el),
2095
+ (value, fontSize) => resolveLengthPx(value, fontSize) || 0,
2096
+ );
2097
+ return checkRepeatedSectionKickers({ candidates });
2098
+ }
2099
+
1434
2100
  function checkElementMotion(tag, style) {
1435
2101
  return checkMotion({
1436
2102
  tag,
@@ -2284,6 +2950,7 @@ if (IS_BROWSER) {
2284
2950
  return {
2285
2951
  type: f.type || f.id,
2286
2952
  category: ap ? ap.category : 'quality',
2953
+ severity: ap?.severity || 'warning',
2287
2954
  detail: f.detail || f.snippet,
2288
2955
  name: ap ? ap.name : (f.type || f.id),
2289
2956
  description: ap ? ap.description : '',
@@ -2339,6 +3006,8 @@ if (IS_BROWSER) {
2339
3006
  ...checkElementGlowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
2340
3007
  ...checkElementAIPaletteDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
2341
3008
  ...checkElementIconTileDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
3009
+ ...checkElementItalicSerifDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
3010
+ ...checkElementHeroEyebrowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
2342
3011
  ...checkElementQualityDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
2343
3012
  ].filter(f => _ruleOk(f.type));
2344
3013
 
@@ -2356,6 +3025,14 @@ if (IS_BROWSER) {
2356
3025
  allFindings.push({ el: document.body, findings: typoFindings });
2357
3026
  }
2358
3027
 
3028
+ const sectionKickerFindings = checkRepeatedSectionKickersDOM()
3029
+ .map(f => ({ type: f.id, detail: f.snippet }))
3030
+ .filter(f => _ruleOk(f.type));
3031
+ if (sectionKickerFindings.length > 0) {
3032
+ pageLevelFindings.push(...sectionKickerFindings);
3033
+ allFindings.push({ el: document.body, findings: sectionKickerFindings });
3034
+ }
3035
+
2359
3036
  const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
2360
3037
  for (const f of layoutFindings) {
2361
3038
  const el = f.el || document.body;
@@ -2494,7 +3171,7 @@ function getAP(id) {
2494
3171
 
2495
3172
  function finding(id, filePath, snippet, line = 0) {
2496
3173
  const ap = getAP(id);
2497
- return { antipattern: id, name: ap.name, description: ap.description, file: filePath, line, snippet };
3174
+ return { antipattern: id, name: ap.name, description: ap.description, severity: ap.severity || 'warning', file: filePath, line, snippet };
2498
3175
  }
2499
3176
 
2500
3177
  /** Check if content looks like a full page (not a component/partial) */
@@ -2675,6 +3352,48 @@ function buildBorderOverrideMap(document, window) {
2675
3352
  return map;
2676
3353
  }
2677
3354
 
3355
+ // Strip `@layer NAME { … }` wrappers from a CSS / HTML source, leaving
3356
+ // the inner rules as flat CSS. jsdom doesn't implement CSS @layer, so
3357
+ // any rule inside a layer block becomes invisible to getComputedStyle.
3358
+ // Tailwind v4 makes this ubiquitous: every utility class lives in
3359
+ // `@layer utilities`, and Preflight lives in `@layer base`. Without
3360
+ // unwrapping, every Tailwind-styled element returns empty computed
3361
+ // styles. We walk the source character-by-character, balancing braces
3362
+ // so we correctly handle nested style rules inside the layer block.
3363
+ function unwrapCssAtLayer(source) {
3364
+ if (!source || !source.includes('@layer')) return source;
3365
+ // Find `@layer <name>? {` openers. The match starts at the @, and
3366
+ // we then balance braces from the opening { onward.
3367
+ const re = /@layer\b[^{;]*\{/g;
3368
+ let out = '';
3369
+ let lastIdx = 0;
3370
+ let m;
3371
+ while ((m = re.exec(source)) !== null) {
3372
+ const openStart = m.index;
3373
+ const openEnd = m.index + m[0].length; // position right after `{`
3374
+ let depth = 1;
3375
+ let i = openEnd;
3376
+ while (i < source.length && depth > 0) {
3377
+ const c = source.charCodeAt(i);
3378
+ if (c === 0x7b /* { */) depth++;
3379
+ else if (c === 0x7d /* } */) depth--;
3380
+ i++;
3381
+ }
3382
+ if (depth !== 0) {
3383
+ // Unbalanced — bail and return source unchanged.
3384
+ return source;
3385
+ }
3386
+ // Emit everything before the @layer, then the inner contents
3387
+ // (between the opening { and the matched closing }), then advance.
3388
+ out += source.slice(lastIdx, openStart);
3389
+ out += source.slice(openEnd, i - 1); // i-1 = position of the closing }
3390
+ lastIdx = i;
3391
+ re.lastIndex = i;
3392
+ }
3393
+ out += source.slice(lastIdx);
3394
+ return out;
3395
+ }
3396
+
2678
3397
  // ---------------------------------------------------------------------------
2679
3398
  // jsdom detection (default for HTML files)
2680
3399
  // ---------------------------------------------------------------------------
@@ -2711,6 +3430,16 @@ async function detectHtml(filePath) {
2711
3430
  }
2712
3431
  }
2713
3432
 
3433
+ // jsdom does not implement CSS `@layer` rules — every utility class
3434
+ // inside `@layer utilities { ... }` is silently ignored, so computed
3435
+ // styles come back empty. Tailwind v4 wraps every utility class in
3436
+ // an @layer, which means jsdom returns empty strings for fontSize /
3437
+ // fontWeight / textTransform / letterSpacing on every Tailwind-styled
3438
+ // element. Strip the @layer wrapper, keep the inner rules as flat
3439
+ // CSS that jsdom can process. The cascade ordering @layer provides
3440
+ // doesn't matter for our checks — we only read computed values.
3441
+ processedHtml = unwrapCssAtLayer(processedHtml);
3442
+
2714
3443
  const dom = new JSDOM(processedHtml, {
2715
3444
  url: `file://${resolvedPath}`,
2716
3445
  });
@@ -2724,6 +3453,39 @@ async function detectHtml(filePath) {
2724
3453
  // by the border check adapter as a fallback.
2725
3454
  const borderOverrides = buildBorderOverrideMap(document, window);
2726
3455
 
3456
+ // Pre-pass: collect :root / :host / html CSS custom properties so the
3457
+ // checks can resolve var(--X) refs that jsdom returns verbatim from
3458
+ // getComputedStyle. Tailwind v4 wraps every utility-class value in a
3459
+ // CSS var; without this, font-weight / font-size / letter-spacing /
3460
+ // color all come back as literal "var(--X)" strings.
3461
+ const customPropMap = buildCustomPropMap(document);
3462
+
3463
+ // Pre-pass: detect whether the page's CSS declares `a { color: inherit }`
3464
+ // (Tailwind v4 preflight signature). When present, real browsers render
3465
+ // anchors using the cascaded ancestor color, but jsdom's UA stylesheet
3466
+ // applies `:link { color: blue }` at higher specificity, so anchors come
3467
+ // back as `rgb(0, 0, 238)` regardless. checkElementColors uses this
3468
+ // flag to walk for the cascaded color when it sees jsdom's blue default
3469
+ // on an anchor — preventing a whole class of contrast false positives
3470
+ // on Tailwind v4 pages.
3471
+ let hasAnchorInheritRule = false;
3472
+ const scanForAnchorInherit = (rules) => {
3473
+ for (const rule of rules) {
3474
+ if (rule.selectorText === 'a' && rule.style && rule.style.color === 'inherit') return true;
3475
+ // Recurse into @layer / @media / @supports / etc.
3476
+ if (rule.cssRules && scanForAnchorInherit(rule.cssRules)) return true;
3477
+ }
3478
+ return false;
3479
+ };
3480
+ for (const sheet of document.styleSheets) {
3481
+ try {
3482
+ if (scanForAnchorInherit(sheet.cssRules || [])) {
3483
+ hasAnchorInheritRule = true;
3484
+ break;
3485
+ }
3486
+ } catch (e) { /* cross-origin sheet, skip */ }
3487
+ }
3488
+
2727
3489
  // Element-level checks (borders + colors + motion)
2728
3490
  for (const el of document.querySelectorAll('*')) {
2729
3491
  const tag = el.tagName.toLowerCase();
@@ -2732,10 +3494,10 @@ async function detectHtml(filePath) {
2732
3494
  for (const f of checkElementBorders(tag, style, borderOverrides.get(el), resolvedRadius)) {
2733
3495
  findings.push(finding(f.id, filePath, f.snippet));
2734
3496
  }
2735
- for (const f of checkElementColors(el, style, tag, window)) {
3497
+ for (const f of checkElementColors(el, style, tag, window, customPropMap, hasAnchorInheritRule)) {
2736
3498
  findings.push(finding(f.id, filePath, f.snippet));
2737
3499
  }
2738
- for (const f of checkElementGlow(tag, style, resolveBackground(el.parentElement || el, window))) {
3500
+ for (const f of checkElementGlow(tag, style, resolveBackground(el.parentElement || el, window, customPropMap))) {
2739
3501
  findings.push(finding(f.id, filePath, f.snippet));
2740
3502
  }
2741
3503
  for (const f of checkElementMotion(tag, style)) {
@@ -2744,6 +3506,12 @@ async function detectHtml(filePath) {
2744
3506
  for (const f of checkElementIconTile(el, tag, window)) {
2745
3507
  findings.push(finding(f.id, filePath, f.snippet));
2746
3508
  }
3509
+ for (const f of checkElementItalicSerif(el, style, tag)) {
3510
+ findings.push(finding(f.id, filePath, f.snippet));
3511
+ }
3512
+ for (const f of checkElementHeroEyebrow(el, style, tag, window, customPropMap)) {
3513
+ findings.push(finding(f.id, filePath, f.snippet));
3514
+ }
2747
3515
  for (const f of checkElementQuality(el, style, tag, window)) {
2748
3516
  findings.push(finding(f.id, filePath, f.snippet));
2749
3517
  }
@@ -2754,6 +3522,9 @@ async function detectHtml(filePath) {
2754
3522
  for (const f of checkPageTypography(document, window)) {
2755
3523
  findings.push(finding(f.id, filePath, f.snippet));
2756
3524
  }
3525
+ for (const f of checkRepeatedSectionKickersFromDoc(document, window)) {
3526
+ findings.push(finding(f.id, filePath, f.snippet));
3527
+ }
2757
3528
  for (const f of checkPageLayout(document, window)) {
2758
3529
  findings.push(finding(f.id, filePath, f.snippet));
2759
3530
  }
@@ -2870,10 +3641,10 @@ const REGEX_MATCHERS = [
2870
3641
  test: (m, line) => +m[1] >= 3 && hasBorderRadius(line),
2871
3642
  fmt: (m) => m[0] },
2872
3643
  // --- Overused font ---
2873
- { id: 'overused-font', regex: /font-family\s*:\s*['"]?(Inter|Roboto|Open Sans|Lato|Montserrat|Arial|Helvetica)\b/gi,
3644
+ { id: 'overused-font', regex: /font-family\s*:\s*['"]?(Inter|Roboto|Open Sans|Lato|Montserrat|Arial|Helvetica|Fraunces|Geist Sans|Geist Mono|Geist|Mona Sans|Plus Jakarta Sans|Space Grotesk|Recoleta|Instrument Sans)\b/gi,
2874
3645
  test: () => true,
2875
3646
  fmt: (m) => m[0] },
2876
- { id: 'overused-font', regex: /fonts\.googleapis\.com\/css2?\?family=(Inter|Roboto|Open\+Sans|Lato|Montserrat)\b/gi,
3647
+ { id: 'overused-font', regex: /fonts\.googleapis\.com\/css2?\?family=(Inter|Roboto|Open\+Sans|Lato|Montserrat|Fraunces|Plus\+Jakarta\+Sans|Space\+Grotesk|Instrument\+Sans|Mona\+Sans|Geist)\b/gi,
2877
3648
  test: () => true,
2878
3649
  fmt: (m) => `Google Fonts: ${m[1].replace(/\+/g, ' ')}` },
2879
3650
  // --- Pure black background ---
@@ -3422,7 +4193,11 @@ Examples:
3422
4193
  }
3423
4194
 
3424
4195
  async function main() {
3425
- const args = process.argv.slice(2);
4196
+ const args = process.argv.slice(2).map(arg => {
4197
+ if (arg === '-json') return '--json';
4198
+ if (arg === '-fast') return '--fast';
4199
+ return arg;
4200
+ });
3426
4201
  const jsonMode = args.includes('--json');
3427
4202
  const helpMode = args.includes('--help');
3428
4203
  const fastMode = args.includes('--fast');
@@ -3531,7 +4306,8 @@ async function main() {
3531
4306
  }
3532
4307
 
3533
4308
  if (allFindings.length > 0) {
3534
- process.stderr.write(formatFindings(allFindings, jsonMode) + '\n');
4309
+ if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');
4310
+ else process.stderr.write(formatFindings(allFindings, false) + '\n');
3535
4311
  process.exit(2);
3536
4312
  }
3537
4313
  if (jsonMode) process.stdout.write('[]\n');