impeccable 2.1.7 → 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.
- package/README.md +1 -1
- package/README.npm.md +1 -1
- package/README.repo.md +81 -64
- package/{bin → cli/bin}/cli.js +3 -11
- package/{bin → cli/bin}/commands/skills.mjs +5 -5
- package/{src → cli/engine}/detect-antipatterns-browser.js +812 -41
- package/{src → cli/engine}/detect-antipatterns.mjs +923 -170
- package/cli/lib/download-providers.js +25 -0
- package/package.json +32 -16
|
@@ -26,10 +26,11 @@ const IS_BROWSER = typeof window !== 'undefined';
|
|
|
26
26
|
const IS_NODE = !IS_BROWSER;
|
|
27
27
|
|
|
28
28
|
// @browser-strip-start
|
|
29
|
-
let fs, path;
|
|
29
|
+
let fs, path, fileURLToPath;
|
|
30
30
|
if (!IS_BROWSER) {
|
|
31
31
|
fs = (await import('node:fs')).default;
|
|
32
32
|
path = (await import('node:path')).default;
|
|
33
|
+
fileURLToPath = (await import('node:url')).fileURLToPath;
|
|
33
34
|
}
|
|
34
35
|
// @browser-strip-end
|
|
35
36
|
|
|
@@ -56,7 +57,13 @@ const BORDER_SAFE_TAGS = new Set(
|
|
|
56
57
|
);
|
|
57
58
|
|
|
58
59
|
const OVERUSED_FONTS = new Set([
|
|
60
|
+
// Older monoculture (still ubiquitous):
|
|
59
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',
|
|
60
67
|
]);
|
|
61
68
|
|
|
62
69
|
// Brand-associated fonts: don't flag these as "overused" on the brand's own domains.
|
|
@@ -65,10 +72,16 @@ const GOOGLE_DOMAINS = [
|
|
|
65
72
|
'google.com', 'youtube.com', 'android.com', 'chromium.org',
|
|
66
73
|
'chrome.com', 'web.dev', 'gstatic.com', 'firebase.google.com',
|
|
67
74
|
];
|
|
75
|
+
const VERCEL_DOMAINS = ['vercel.com', 'nextjs.org', 'v0.app'];
|
|
76
|
+
const GITHUB_DOMAINS = ['github.com', 'githubnext.com'];
|
|
68
77
|
const BRAND_FONT_DOMAINS = {
|
|
69
78
|
'roboto': GOOGLE_DOMAINS,
|
|
70
79
|
'google sans': GOOGLE_DOMAINS,
|
|
71
80
|
'product sans': GOOGLE_DOMAINS,
|
|
81
|
+
'geist': VERCEL_DOMAINS,
|
|
82
|
+
'geist sans': VERCEL_DOMAINS,
|
|
83
|
+
'geist mono': VERCEL_DOMAINS,
|
|
84
|
+
'mona sans': GITHUB_DOMAINS,
|
|
72
85
|
};
|
|
73
86
|
|
|
74
87
|
function isBrandFontOnOwnDomain(font) {
|
|
@@ -86,6 +99,23 @@ const GENERIC_FONTS = new Set([
|
|
|
86
99
|
'inherit', 'initial', 'unset', 'revert',
|
|
87
100
|
]);
|
|
88
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
|
+
|
|
89
119
|
const ANTIPATTERNS = [
|
|
90
120
|
// ── AI slop: tells that something was AI-generated ──
|
|
91
121
|
{
|
|
@@ -111,7 +141,7 @@ const ANTIPATTERNS = [
|
|
|
111
141
|
category: 'slop',
|
|
112
142
|
name: 'Overused font',
|
|
113
143
|
description:
|
|
114
|
-
'Inter, Roboto,
|
|
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.',
|
|
115
145
|
skillSection: 'Typography',
|
|
116
146
|
skillGuideline: 'overused fonts like Inter',
|
|
117
147
|
},
|
|
@@ -205,6 +235,34 @@ const ANTIPATTERNS = [
|
|
|
205
235
|
skillSection: 'Typography',
|
|
206
236
|
skillGuideline: 'large icons with rounded corners above every heading',
|
|
207
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
|
+
},
|
|
208
266
|
|
|
209
267
|
// ── Quality: general design and accessibility issues ──
|
|
210
268
|
{
|
|
@@ -257,6 +315,13 @@ const ANTIPATTERNS = [
|
|
|
257
315
|
description:
|
|
258
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.',
|
|
259
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
|
+
},
|
|
260
325
|
{
|
|
261
326
|
id: 'tight-leading',
|
|
262
327
|
category: 'quality',
|
|
@@ -460,7 +525,18 @@ function isEmojiOnlyText(text) {
|
|
|
460
525
|
|
|
461
526
|
function checkColors(opts) {
|
|
462
527
|
const { tag, textColor, bgColor, effectiveBg, effectiveBgStops, fontSize, fontWeight, hasDirectText, isEmojiOnly, bgClip, bgImage, classList } = opts;
|
|
463
|
-
if (SAFE_TAGS.has(tag))
|
|
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
|
+
}
|
|
464
540
|
const findings = [];
|
|
465
541
|
|
|
466
542
|
// Pure black background (only solid or near-solid, not semi-transparent overlays)
|
|
@@ -490,7 +566,20 @@ function checkColors(opts) {
|
|
|
490
566
|
const isLargeText = fontSize >= 18 || (fontSize >= 14 && fontWeight >= 700) || isHeading;
|
|
491
567
|
const threshold = isLargeText ? 3.0 : 4.5;
|
|
492
568
|
if (ratio < threshold) {
|
|
493
|
-
|
|
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
|
+
}
|
|
494
583
|
}
|
|
495
584
|
}
|
|
496
585
|
|
|
@@ -599,6 +688,150 @@ function checkIconTile(opts) {
|
|
|
599
688
|
}];
|
|
600
689
|
}
|
|
601
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
|
+
|
|
602
835
|
const LAYOUT_TRANSITION_PROPS = new Set([
|
|
603
836
|
'width', 'height', 'padding', 'margin',
|
|
604
837
|
'max-height', 'max-width', 'min-height', 'min-width',
|
|
@@ -812,43 +1045,88 @@ function checkHtmlPatterns(html) {
|
|
|
812
1045
|
|
|
813
1046
|
// ─── Section 4: resolveBackground (unified) ─────────────────────────────────
|
|
814
1047
|
|
|
815
|
-
|
|
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) {
|
|
816
1077
|
let current = el;
|
|
817
1078
|
while (current && current.nodeType === 1) {
|
|
818
1079
|
const style = IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
|
|
819
|
-
|
|
820
|
-
// If this element has a background-image (gradient or url), it's visually
|
|
821
|
-
// opaque but we can't determine the effective color — bail out so callers
|
|
822
|
-
// don't get a false solid-color answer.
|
|
823
1080
|
const bgImage = style.backgroundImage || '';
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
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.
|
|
828
1090
|
let bg = parseRgb(style.backgroundColor);
|
|
829
1091
|
if (!IS_BROWSER && (!bg || bg.a < 0.1)) {
|
|
830
|
-
// jsdom
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
834
|
-
|
|
835
|
-
if (
|
|
836
|
-
|
|
837
|
-
|
|
838
|
-
const
|
|
839
|
-
|
|
840
|
-
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
} else {
|
|
844
|
-
bg = { r: parseInt(h[0]+h[0], 16), g: parseInt(h[1]+h[1], 16), b: parseInt(h[2]+h[2], 16), a: 1 };
|
|
845
|
-
}
|
|
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);
|
|
846
1105
|
}
|
|
847
1106
|
}
|
|
848
1107
|
}
|
|
1108
|
+
|
|
849
1109
|
if (bg && bg.a > 0.1) {
|
|
850
1110
|
if (IS_BROWSER || bg.a >= 0.5) return bg;
|
|
851
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
|
+
}
|
|
852
1130
|
current = current.parentElement;
|
|
853
1131
|
}
|
|
854
1132
|
return { r: 255, g: 255, b: 255 };
|
|
@@ -880,6 +1158,82 @@ function resolveGradientStops(el, win) {
|
|
|
880
1158
|
return null;
|
|
881
1159
|
}
|
|
882
1160
|
|
|
1161
|
+
// Parse a single CSS length token to pixels. Accepts "12px", "50%", a
|
|
1162
|
+
// shorthand like "12px 4px" (uses the first value), or empty / null.
|
|
1163
|
+
// Returns the pixel value, or null when the input is unparseable.
|
|
1164
|
+
// Percentages convert against `widthPx` when one is supplied. Without a
|
|
1165
|
+
// usable width (jsdom returns "auto" for many real-world elements,
|
|
1166
|
+
// which parseFloat collapses to 0), fall back to the raw percentage
|
|
1167
|
+
// number so callers gating on `> 0` (border-accent-on-rounded,
|
|
1168
|
+
// isCardLike's hasRadius) still see a positive value, matching the
|
|
1169
|
+
// original parseFloat("50%") === 50 behavior.
|
|
1170
|
+
function parseRadiusToPx(value, widthPx) {
|
|
1171
|
+
if (!value || typeof value !== 'string') return null;
|
|
1172
|
+
const trimmed = value.trim();
|
|
1173
|
+
if (!trimmed) return null;
|
|
1174
|
+
const first = trimmed.split(/\s+/)[0];
|
|
1175
|
+
const num = parseFloat(first);
|
|
1176
|
+
if (Number.isNaN(num)) return null;
|
|
1177
|
+
if (/%$/.test(first)) {
|
|
1178
|
+
if (widthPx && widthPx > 0) return (num / 100) * widthPx;
|
|
1179
|
+
return num;
|
|
1180
|
+
}
|
|
1181
|
+
return num;
|
|
1182
|
+
}
|
|
1183
|
+
|
|
1184
|
+
// jsdom from 29.0.2 onward returns "" for the `border-radius` shorthand
|
|
1185
|
+
// in computed style and "0" for longhand reads when the source rule used
|
|
1186
|
+
// the shorthand. The rule engine relied on parseFloat(style.borderRadius)
|
|
1187
|
+
// to identify circular avatars (border-radius >= width/2) and rounded
|
|
1188
|
+
// cards (border-radius > 0); both checks broke silently. This helper
|
|
1189
|
+
// recovers the radius via a chain of fallbacks. Browsers resolve the
|
|
1190
|
+
// shorthand correctly and exit on the first line.
|
|
1191
|
+
function resolveBorderRadiusPx(el, style, widthPx, win) {
|
|
1192
|
+
const fromComputed = parseRadiusToPx(style.borderRadius, widthPx);
|
|
1193
|
+
if (fromComputed !== null) return fromComputed;
|
|
1194
|
+
|
|
1195
|
+
if (IS_BROWSER || !win) return 0;
|
|
1196
|
+
|
|
1197
|
+
const fromLonghand = parseRadiusToPx(style.borderTopLeftRadius, widthPx);
|
|
1198
|
+
if (fromLonghand !== null && fromLonghand > 0) return fromLonghand;
|
|
1199
|
+
|
|
1200
|
+
const fromInlineProp = parseRadiusToPx(el.style?.borderRadius, widthPx);
|
|
1201
|
+
if (fromInlineProp !== null) return fromInlineProp;
|
|
1202
|
+
|
|
1203
|
+
const rawStyle = el.getAttribute?.('style') || '';
|
|
1204
|
+
const inlineMatch = rawStyle.match(/border-radius\s*:\s*([^;]+)/i);
|
|
1205
|
+
if (inlineMatch) {
|
|
1206
|
+
const fromRaw = parseRadiusToPx(inlineMatch[1].trim(), widthPx);
|
|
1207
|
+
if (fromRaw !== null) return fromRaw;
|
|
1208
|
+
}
|
|
1209
|
+
|
|
1210
|
+
// Walk every stylesheet looking for matching rules. Take the maximum
|
|
1211
|
+
// pixel value across all matches so a circle declaration overridden by
|
|
1212
|
+
// a more specific rounded-square selector still registers as a circle
|
|
1213
|
+
// for the exclusion check (better to under-flag than to false-positive
|
|
1214
|
+
// on round avatars).
|
|
1215
|
+
let max = 0;
|
|
1216
|
+
const sheets = win.document?.styleSheets;
|
|
1217
|
+
if (sheets) {
|
|
1218
|
+
for (const sheet of sheets) {
|
|
1219
|
+
let rules;
|
|
1220
|
+
try { rules = sheet.cssRules || []; } catch { continue; }
|
|
1221
|
+
for (const rule of rules) {
|
|
1222
|
+
if (!rule.style || !rule.selectorText) continue;
|
|
1223
|
+
let matches = false;
|
|
1224
|
+
try { matches = el.matches(rule.selectorText); } catch { continue; }
|
|
1225
|
+
if (!matches) continue;
|
|
1226
|
+
const ruleValue = rule.style.borderRadius
|
|
1227
|
+
|| (rule.style.getPropertyValue && rule.style.getPropertyValue('border-radius'))
|
|
1228
|
+
|| rule.style.borderTopLeftRadius;
|
|
1229
|
+
const px = parseRadiusToPx(ruleValue, widthPx);
|
|
1230
|
+
if (px !== null && px > max) max = px;
|
|
1231
|
+
}
|
|
1232
|
+
}
|
|
1233
|
+
}
|
|
1234
|
+
return max;
|
|
1235
|
+
}
|
|
1236
|
+
|
|
883
1237
|
// ─── Section 5: Element Adapters ────────────────────────────────────────────
|
|
884
1238
|
|
|
885
1239
|
// Browser adapters — call getComputedStyle/getBoundingClientRect on live DOM
|
|
@@ -901,7 +1255,9 @@ function checkElementBordersDOM(el) {
|
|
|
901
1255
|
|
|
902
1256
|
function checkElementColorsDOM(el) {
|
|
903
1257
|
const tag = el.tagName.toLowerCase();
|
|
904
|
-
|
|
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.
|
|
905
1261
|
const rect = el.getBoundingClientRect();
|
|
906
1262
|
if (rect.width < 10 || rect.height < 10) return [];
|
|
907
1263
|
const style = getComputedStyle(el);
|
|
@@ -911,7 +1267,7 @@ function checkElementColorsDOM(el) {
|
|
|
911
1267
|
return checkColors({
|
|
912
1268
|
tag,
|
|
913
1269
|
textColor: parseRgb(style.color),
|
|
914
|
-
bgColor:
|
|
1270
|
+
bgColor: readOwnBackgroundColor(el, style),
|
|
915
1271
|
effectiveBg,
|
|
916
1272
|
effectiveBgStops: effectiveBg ? null : resolveGradientStops(el),
|
|
917
1273
|
fontSize: parseFloat(style.fontSize) || 16,
|
|
@@ -959,6 +1315,274 @@ function checkElementIconTileDOM(el) {
|
|
|
959
1315
|
});
|
|
960
1316
|
}
|
|
961
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
|
+
|
|
962
1586
|
function checkElementMotionDOM(el) {
|
|
963
1587
|
const tag = el.tagName.toLowerCase();
|
|
964
1588
|
if (SAFE_TAGS.has(tag)) return [];
|
|
@@ -1109,7 +1733,7 @@ function resolveLengthPx(value, fontSizePx) {
|
|
|
1109
1733
|
// Both adapters resolve font-size, line-height and letter-spacing to pixels
|
|
1110
1734
|
// before calling this so the pure function only deals with numbers.
|
|
1111
1735
|
function checkQuality(opts) {
|
|
1112
|
-
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;
|
|
1113
1737
|
const findings = [];
|
|
1114
1738
|
// Skip browser extension injected elements
|
|
1115
1739
|
const elId = el.id || '';
|
|
@@ -1160,6 +1784,40 @@ function checkQuality(opts) {
|
|
|
1160
1784
|
}
|
|
1161
1785
|
}
|
|
1162
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
|
+
|
|
1163
1821
|
// --- Tight line height ---
|
|
1164
1822
|
if (hasDirectText && textLen > 50 && !['h1','h2','h3','h4','h5','h6'].includes(tag)) {
|
|
1165
1823
|
if (lineHeightPx != null && fontSize > 0) {
|
|
@@ -1221,7 +1879,8 @@ function checkElementQualityDOM(el) {
|
|
|
1221
1879
|
const letterSpacingPx = resolveLengthPx(style.letterSpacing, fontSize);
|
|
1222
1880
|
const rect = el.getBoundingClientRect();
|
|
1223
1881
|
const lineMax = (typeof window !== 'undefined' && window.__IMPECCABLE_CONFIG__?.lineLengthMax) || 80;
|
|
1224
|
-
|
|
1882
|
+
const viewportWidth = (typeof window !== 'undefined' ? window.innerWidth : 0) || 0;
|
|
1883
|
+
return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax, viewportWidth });
|
|
1225
1884
|
}
|
|
1226
1885
|
|
|
1227
1886
|
// Pure page-level skipped-heading walk. Takes a Document so it works in both
|
|
@@ -1266,7 +1925,7 @@ function checkElementQuality(el, style, tag, window) {
|
|
|
1266
1925
|
return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect: null });
|
|
1267
1926
|
}
|
|
1268
1927
|
|
|
1269
|
-
function checkElementBorders(tag, style, overrides) {
|
|
1928
|
+
function checkElementBorders(tag, style, overrides, resolvedRadius) {
|
|
1270
1929
|
const sides = ['Top', 'Right', 'Bottom', 'Left'];
|
|
1271
1930
|
const widths = {}, colors = {};
|
|
1272
1931
|
for (const s of sides) {
|
|
@@ -1286,18 +1945,58 @@ function checkElementBorders(tag, style, overrides) {
|
|
|
1286
1945
|
colors[s] = overrides[s].color;
|
|
1287
1946
|
}
|
|
1288
1947
|
}
|
|
1289
|
-
|
|
1948
|
+
// resolvedRadius lets the caller pre-resolve the radius via
|
|
1949
|
+
// resolveBorderRadiusPx so the value survives jsdom 29.1.0's broken
|
|
1950
|
+
// shorthand serialization. Falls back to the computed value for tests
|
|
1951
|
+
// and browser callers that don't pre-resolve.
|
|
1952
|
+
const radius = resolvedRadius != null
|
|
1953
|
+
? resolvedRadius
|
|
1954
|
+
: (parseFloat(style.borderRadius) || 0);
|
|
1955
|
+
return checkBorders(tag, widths, colors, radius);
|
|
1290
1956
|
}
|
|
1291
1957
|
|
|
1292
|
-
function checkElementColors(el, style, tag, window) {
|
|
1958
|
+
function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInheritRule) {
|
|
1293
1959
|
const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
|
|
1294
1960
|
const hasDirectText = directText.trim().length > 0;
|
|
1295
1961
|
|
|
1296
|
-
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
|
+
|
|
1297
1996
|
return checkColors({
|
|
1298
1997
|
tag,
|
|
1299
|
-
textColor
|
|
1300
|
-
bgColor:
|
|
1998
|
+
textColor,
|
|
1999
|
+
bgColor: readOwnBackgroundColor(el, style),
|
|
1301
2000
|
effectiveBg,
|
|
1302
2001
|
effectiveBgStops: effectiveBg ? null : resolveGradientStops(el, window),
|
|
1303
2002
|
fontSize: parseFloat(style.fontSize) || 16,
|
|
@@ -1341,12 +2040,63 @@ function checkElementIconTile(el, tag, window) {
|
|
|
1341
2040
|
siblingBgColor: parseRgb(sibStyle.backgroundColor),
|
|
1342
2041
|
siblingBgImage: sibStyle.backgroundImage || '',
|
|
1343
2042
|
siblingBorderWidth: parseFloat(sibStyle.borderTopWidth) || 0,
|
|
1344
|
-
siblingBorderRadius:
|
|
2043
|
+
siblingBorderRadius: resolveBorderRadiusPx(sibling, sibStyle, sibWidth, window),
|
|
1345
2044
|
hasIconChild: !!iconChild || hasInlineEmojiIcon,
|
|
1346
2045
|
iconChildWidth: iconWidth,
|
|
1347
2046
|
});
|
|
1348
2047
|
}
|
|
1349
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
|
+
|
|
1350
2100
|
function checkElementMotion(tag, style) {
|
|
1351
2101
|
return checkMotion({
|
|
1352
2102
|
tag,
|
|
@@ -1560,7 +2310,8 @@ function isCardLike(el, win) {
|
|
|
1560
2310
|
const hasShadow = (style.boxShadow && style.boxShadow !== 'none') ||
|
|
1561
2311
|
/\bshadow(?:-sm|-md|-lg|-xl|-2xl)?\b/.test(cls) || /box-shadow/i.test(rawStyle);
|
|
1562
2312
|
const hasBorder = /\bborder\b/.test(cls);
|
|
1563
|
-
const
|
|
2313
|
+
const widthPx = parseFloat(style.width) || 0;
|
|
2314
|
+
const hasRadius = resolveBorderRadiusPx(el, style, widthPx, win) > 0 ||
|
|
1564
2315
|
/\brounded(?:-sm|-md|-lg|-xl|-2xl|-full)?\b/.test(cls) || /border-radius/i.test(rawStyle);
|
|
1565
2316
|
const hasBg = /\bbg-(?:white|gray-\d+|slate-\d+)\b/.test(cls) ||
|
|
1566
2317
|
/background(?:-color)?\s*:\s*(?!transparent)/i.test(rawStyle);
|
|
@@ -2199,6 +2950,7 @@ if (IS_BROWSER) {
|
|
|
2199
2950
|
return {
|
|
2200
2951
|
type: f.type || f.id,
|
|
2201
2952
|
category: ap ? ap.category : 'quality',
|
|
2953
|
+
severity: ap?.severity || 'warning',
|
|
2202
2954
|
detail: f.detail || f.snippet,
|
|
2203
2955
|
name: ap ? ap.name : (f.type || f.id),
|
|
2204
2956
|
description: ap ? ap.description : '',
|
|
@@ -2241,6 +2993,9 @@ if (IS_BROWSER) {
|
|
|
2241
2993
|
// Skip browser extension elements (Claude, etc.)
|
|
2242
2994
|
const elId = el.id || '';
|
|
2243
2995
|
if (elId.startsWith('claude-') || elId.startsWith('cic-')) continue;
|
|
2996
|
+
// Skip the impeccable live-mode overlay (highlight, tooltip, bar, picker, toast).
|
|
2997
|
+
// These are inspector chrome, not part of the user's design.
|
|
2998
|
+
if (el.closest('[id^="impeccable-live-"]')) continue;
|
|
2244
2999
|
// Skip html/body -- page-level findings go in the banner, not a full-page overlay
|
|
2245
3000
|
if (el === document.body || el === document.documentElement) continue;
|
|
2246
3001
|
|
|
@@ -2251,6 +3006,8 @@ if (IS_BROWSER) {
|
|
|
2251
3006
|
...checkElementGlowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
|
2252
3007
|
...checkElementAIPaletteDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
|
2253
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 })),
|
|
2254
3011
|
...checkElementQualityDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
|
2255
3012
|
].filter(f => _ruleOk(f.type));
|
|
2256
3013
|
|
|
@@ -2268,6 +3025,14 @@ if (IS_BROWSER) {
|
|
|
2268
3025
|
allFindings.push({ el: document.body, findings: typoFindings });
|
|
2269
3026
|
}
|
|
2270
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
|
+
|
|
2271
3036
|
const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
|
|
2272
3037
|
for (const f of layoutFindings) {
|
|
2273
3038
|
const el = f.el || document.body;
|
|
@@ -2294,7 +3059,14 @@ if (IS_BROWSER) {
|
|
|
2294
3059
|
}
|
|
2295
3060
|
|
|
2296
3061
|
// Regex-on-HTML checks (shared with Node)
|
|
2297
|
-
|
|
3062
|
+
// Clone the document and strip impeccable-live overlay nodes before the
|
|
3063
|
+
// regex scan, so the inspector's own inline styles (transitions on top/
|
|
3064
|
+
// left/width/height, etc.) don't register as page anti-patterns.
|
|
3065
|
+
const docClone = document.documentElement.cloneNode(true);
|
|
3066
|
+
for (const node of docClone.querySelectorAll('[id^="impeccable-live-"]')) {
|
|
3067
|
+
node.remove();
|
|
3068
|
+
}
|
|
3069
|
+
const htmlPatternFindings = checkHtmlPatterns(docClone.outerHTML);
|
|
2298
3070
|
if (htmlPatternFindings.length > 0) {
|
|
2299
3071
|
const mapped = htmlPatternFindings.map(f => ({ type: f.id, detail: f.snippet })).filter(f => _ruleOk(f.type));
|
|
2300
3072
|
pageLevelFindings.push(...mapped);
|
|
@@ -2399,7 +3171,7 @@ function getAP(id) {
|
|
|
2399
3171
|
|
|
2400
3172
|
function finding(id, filePath, snippet, line = 0) {
|
|
2401
3173
|
const ap = getAP(id);
|
|
2402
|
-
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 };
|
|
2403
3175
|
}
|
|
2404
3176
|
|
|
2405
3177
|
/** Check if content looks like a full page (not a component/partial) */
|
|
@@ -2580,6 +3352,48 @@ function buildBorderOverrideMap(document, window) {
|
|
|
2580
3352
|
return map;
|
|
2581
3353
|
}
|
|
2582
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
|
+
|
|
2583
3397
|
// ---------------------------------------------------------------------------
|
|
2584
3398
|
// jsdom detection (default for HTML files)
|
|
2585
3399
|
// ---------------------------------------------------------------------------
|
|
@@ -2616,6 +3430,16 @@ async function detectHtml(filePath) {
|
|
|
2616
3430
|
}
|
|
2617
3431
|
}
|
|
2618
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
|
+
|
|
2619
3443
|
const dom = new JSDOM(processedHtml, {
|
|
2620
3444
|
url: `file://${resolvedPath}`,
|
|
2621
3445
|
});
|
|
@@ -2629,17 +3453,51 @@ async function detectHtml(filePath) {
|
|
|
2629
3453
|
// by the border check adapter as a fallback.
|
|
2630
3454
|
const borderOverrides = buildBorderOverrideMap(document, window);
|
|
2631
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
|
+
|
|
2632
3489
|
// Element-level checks (borders + colors + motion)
|
|
2633
3490
|
for (const el of document.querySelectorAll('*')) {
|
|
2634
3491
|
const tag = el.tagName.toLowerCase();
|
|
2635
3492
|
const style = window.getComputedStyle(el);
|
|
2636
|
-
|
|
3493
|
+
const resolvedRadius = resolveBorderRadiusPx(el, style, parseFloat(style.width) || 0, window);
|
|
3494
|
+
for (const f of checkElementBorders(tag, style, borderOverrides.get(el), resolvedRadius)) {
|
|
2637
3495
|
findings.push(finding(f.id, filePath, f.snippet));
|
|
2638
3496
|
}
|
|
2639
|
-
for (const f of checkElementColors(el, style, tag, window)) {
|
|
3497
|
+
for (const f of checkElementColors(el, style, tag, window, customPropMap, hasAnchorInheritRule)) {
|
|
2640
3498
|
findings.push(finding(f.id, filePath, f.snippet));
|
|
2641
3499
|
}
|
|
2642
|
-
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))) {
|
|
2643
3501
|
findings.push(finding(f.id, filePath, f.snippet));
|
|
2644
3502
|
}
|
|
2645
3503
|
for (const f of checkElementMotion(tag, style)) {
|
|
@@ -2648,6 +3506,12 @@ async function detectHtml(filePath) {
|
|
|
2648
3506
|
for (const f of checkElementIconTile(el, tag, window)) {
|
|
2649
3507
|
findings.push(finding(f.id, filePath, f.snippet));
|
|
2650
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
|
+
}
|
|
2651
3515
|
for (const f of checkElementQuality(el, style, tag, window)) {
|
|
2652
3516
|
findings.push(finding(f.id, filePath, f.snippet));
|
|
2653
3517
|
}
|
|
@@ -2658,6 +3522,9 @@ async function detectHtml(filePath) {
|
|
|
2658
3522
|
for (const f of checkPageTypography(document, window)) {
|
|
2659
3523
|
findings.push(finding(f.id, filePath, f.snippet));
|
|
2660
3524
|
}
|
|
3525
|
+
for (const f of checkRepeatedSectionKickersFromDoc(document, window)) {
|
|
3526
|
+
findings.push(finding(f.id, filePath, f.snippet));
|
|
3527
|
+
}
|
|
2661
3528
|
for (const f of checkPageLayout(document, window)) {
|
|
2662
3529
|
findings.push(finding(f.id, filePath, f.snippet));
|
|
2663
3530
|
}
|
|
@@ -2687,7 +3554,7 @@ async function detectUrl(url) {
|
|
|
2687
3554
|
|
|
2688
3555
|
// Read the browser detection script — reuse it instead of reimplementing
|
|
2689
3556
|
const browserScriptPath = path.resolve(
|
|
2690
|
-
path.dirname(
|
|
3557
|
+
path.dirname(fileURLToPath(import.meta.url)),
|
|
2691
3558
|
'detect-antipatterns-browser.js'
|
|
2692
3559
|
);
|
|
2693
3560
|
let browserScript;
|
|
@@ -2774,10 +3641,10 @@ const REGEX_MATCHERS = [
|
|
|
2774
3641
|
test: (m, line) => +m[1] >= 3 && hasBorderRadius(line),
|
|
2775
3642
|
fmt: (m) => m[0] },
|
|
2776
3643
|
// --- Overused font ---
|
|
2777
|
-
{ 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,
|
|
2778
3645
|
test: () => true,
|
|
2779
3646
|
fmt: (m) => m[0] },
|
|
2780
|
-
{ 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,
|
|
2781
3648
|
test: () => true,
|
|
2782
3649
|
fmt: (m) => `Google Fonts: ${m[1].replace(/\+/g, ' ')}` },
|
|
2783
3650
|
// --- Pure black background ---
|
|
@@ -3326,7 +4193,11 @@ Examples:
|
|
|
3326
4193
|
}
|
|
3327
4194
|
|
|
3328
4195
|
async function main() {
|
|
3329
|
-
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
|
+
});
|
|
3330
4201
|
const jsonMode = args.includes('--json');
|
|
3331
4202
|
const helpMode = args.includes('--help');
|
|
3332
4203
|
const fastMode = args.includes('--fast');
|
|
@@ -3435,131 +4306,14 @@ async function main() {
|
|
|
3435
4306
|
}
|
|
3436
4307
|
|
|
3437
4308
|
if (allFindings.length > 0) {
|
|
3438
|
-
process.
|
|
4309
|
+
if (jsonMode) process.stdout.write(formatFindings(allFindings, true) + '\n');
|
|
4310
|
+
else process.stderr.write(formatFindings(allFindings, false) + '\n');
|
|
3439
4311
|
process.exit(2);
|
|
3440
4312
|
}
|
|
3441
4313
|
if (jsonMode) process.stdout.write('[]\n');
|
|
3442
4314
|
process.exit(0);
|
|
3443
4315
|
}
|
|
3444
4316
|
|
|
3445
|
-
// ---------------------------------------------------------------------------
|
|
3446
|
-
// Live detection server
|
|
3447
|
-
// ---------------------------------------------------------------------------
|
|
3448
|
-
|
|
3449
|
-
async function findOpenPort(start = 8400) {
|
|
3450
|
-
const net = await import('node:net');
|
|
3451
|
-
return new Promise((resolve) => {
|
|
3452
|
-
const server = net.default.createServer();
|
|
3453
|
-
server.listen(start, '127.0.0.1', () => {
|
|
3454
|
-
const port = server.address().port;
|
|
3455
|
-
server.close(() => resolve(port));
|
|
3456
|
-
});
|
|
3457
|
-
server.on('error', () => resolve(findOpenPort(start + 1)));
|
|
3458
|
-
});
|
|
3459
|
-
}
|
|
3460
|
-
|
|
3461
|
-
const LIVE_PID_FILE = path.join((await import('node:os')).default.tmpdir(), 'impeccable-live.json');
|
|
3462
|
-
|
|
3463
|
-
async function liveCli() {
|
|
3464
|
-
const args = process.argv.slice(2);
|
|
3465
|
-
const helpMode = args.includes('--help');
|
|
3466
|
-
const stopMode = args.includes('stop');
|
|
3467
|
-
const portArg = args.find(a => a.startsWith('--port='));
|
|
3468
|
-
const requestedPort = portArg ? parseInt(portArg.split('=')[1], 10) : null;
|
|
3469
|
-
|
|
3470
|
-
if (helpMode) {
|
|
3471
|
-
console.log(`Usage: impeccable live [options]
|
|
3472
|
-
|
|
3473
|
-
Start a local server that serves the browser detection overlay script.
|
|
3474
|
-
Inject the script into any page to scan for anti-patterns in real time.
|
|
3475
|
-
|
|
3476
|
-
Commands:
|
|
3477
|
-
live Start the server (default)
|
|
3478
|
-
live stop Stop a running live server
|
|
3479
|
-
|
|
3480
|
-
Options:
|
|
3481
|
-
--port=PORT Use a specific port (default: auto-detect unused port)
|
|
3482
|
-
--help Show this help message
|
|
3483
|
-
|
|
3484
|
-
The server provides:
|
|
3485
|
-
/detect.js The detection overlay script (inject via <script> tag)
|
|
3486
|
-
/health Health check endpoint
|
|
3487
|
-
/stop Stop the server remotely`);
|
|
3488
|
-
process.exit(0);
|
|
3489
|
-
}
|
|
3490
|
-
|
|
3491
|
-
// Stop a running server
|
|
3492
|
-
if (stopMode) {
|
|
3493
|
-
try {
|
|
3494
|
-
const info = JSON.parse(fs.readFileSync(LIVE_PID_FILE, 'utf-8'));
|
|
3495
|
-
const res = await fetch(`http://localhost:${info.port}/stop`);
|
|
3496
|
-
if (res.ok) {
|
|
3497
|
-
console.log(`Stopped live server on port ${info.port}.`);
|
|
3498
|
-
}
|
|
3499
|
-
} catch {
|
|
3500
|
-
console.log('No running live server found.');
|
|
3501
|
-
}
|
|
3502
|
-
process.exit(0);
|
|
3503
|
-
}
|
|
3504
|
-
|
|
3505
|
-
const http = await import('node:http');
|
|
3506
|
-
const scriptPath = path.join(path.dirname(new URL(import.meta.url).pathname), 'detect-antipatterns-browser.js');
|
|
3507
|
-
|
|
3508
|
-
let browserScript;
|
|
3509
|
-
try {
|
|
3510
|
-
browserScript = fs.readFileSync(scriptPath, 'utf-8');
|
|
3511
|
-
} catch {
|
|
3512
|
-
process.stderr.write('Error: Browser script not found. Run `npm run build:browser` first.\n');
|
|
3513
|
-
process.exit(1);
|
|
3514
|
-
}
|
|
3515
|
-
|
|
3516
|
-
const port = requestedPort || await findOpenPort();
|
|
3517
|
-
|
|
3518
|
-
const shutdown = () => {
|
|
3519
|
-
try { fs.unlinkSync(LIVE_PID_FILE); } catch { /* ignore */ }
|
|
3520
|
-
server.close();
|
|
3521
|
-
process.exit(0);
|
|
3522
|
-
};
|
|
3523
|
-
|
|
3524
|
-
const server = http.default.createServer((req, res) => {
|
|
3525
|
-
// CORS headers for cross-origin injection
|
|
3526
|
-
res.setHeader('Access-Control-Allow-Origin', '*');
|
|
3527
|
-
res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
|
|
3528
|
-
if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return; }
|
|
3529
|
-
|
|
3530
|
-
if (req.url === '/detect.js' || req.url === '/') {
|
|
3531
|
-
res.writeHead(200, { 'Content-Type': 'application/javascript' });
|
|
3532
|
-
res.end(browserScript);
|
|
3533
|
-
} else if (req.url === '/health') {
|
|
3534
|
-
res.writeHead(200, { 'Content-Type': 'application/json' });
|
|
3535
|
-
res.end(JSON.stringify({ status: 'ok', port }));
|
|
3536
|
-
} else if (req.url === '/stop') {
|
|
3537
|
-
res.writeHead(200, { 'Content-Type': 'text/plain' });
|
|
3538
|
-
res.end('stopping');
|
|
3539
|
-
shutdown();
|
|
3540
|
-
} else {
|
|
3541
|
-
res.writeHead(404);
|
|
3542
|
-
res.end('Not found');
|
|
3543
|
-
}
|
|
3544
|
-
});
|
|
3545
|
-
|
|
3546
|
-
server.listen(port, '127.0.0.1', () => {
|
|
3547
|
-
// Write PID file so `live stop` can find us
|
|
3548
|
-
fs.writeFileSync(LIVE_PID_FILE, JSON.stringify({ pid: process.pid, port }));
|
|
3549
|
-
|
|
3550
|
-
const url = `http://localhost:${port}`;
|
|
3551
|
-
console.log(`Impeccable live detection server running on ${url}\n`);
|
|
3552
|
-
console.log(`Inject into any page:`);
|
|
3553
|
-
console.log(` const s = document.createElement('script');`);
|
|
3554
|
-
console.log(` s.src = '${url}/detect.js';`);
|
|
3555
|
-
console.log(` document.head.appendChild(s);\n`);
|
|
3556
|
-
console.log(`Stop: npx impeccable live stop`);
|
|
3557
|
-
});
|
|
3558
|
-
|
|
3559
|
-
process.on('SIGINT', shutdown);
|
|
3560
|
-
process.on('SIGTERM', shutdown);
|
|
3561
|
-
}
|
|
3562
|
-
|
|
3563
4317
|
// ---------------------------------------------------------------------------
|
|
3564
4318
|
// Entry point
|
|
3565
4319
|
// ---------------------------------------------------------------------------
|
|
@@ -3584,7 +4338,6 @@ export {
|
|
|
3584
4338
|
buildImportGraph, resolveImport,
|
|
3585
4339
|
detectFrameworkConfig, isPortListening, FRAMEWORK_CONFIGS,
|
|
3586
4340
|
main as detectCli,
|
|
3587
|
-
liveCli,
|
|
3588
4341
|
};
|
|
3589
4342
|
|
|
3590
4343
|
// @browser-strip-end
|