impeccable 2.0.6 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3,7 +3,7 @@
3
3
  /**
4
4
  * Anti-Pattern Detector for Impeccable
5
5
  * Copyright (c) 2026 Paul Bakaus
6
- * SPDX-License-Identifier: BSL-1.1
6
+ * SPDX-License-Identifier: Apache-2.0
7
7
  *
8
8
  * Universal file — auto-detects environment (browser vs Node) and adapts.
9
9
  *
@@ -43,10 +43,42 @@ const SAFE_TAGS = new Set([
43
43
  'rect', 'line', 'polyline', 'polygon', 'g', 'defs', 'use',
44
44
  ]);
45
45
 
46
+ // Per-check safe-tags override for the border (side-tab / border-accent)
47
+ // rule. We intentionally re-allow <label> here because card-shaped clickable
48
+ // labels (e.g. .checklist-item wrapping a checkbox + content) are one of the
49
+ // canonical side-tab anti-pattern shapes and must be detected. The rule's
50
+ // other preconditions (non-neutral color, width >= 2px on a single side,
51
+ // radius > 0 or width >= 3, element size >= 20x20 in the browser path)
52
+ // already filter out plain inline form labels so this does not introduce
53
+ // false positives. See modern-color-borders.html for the test matrix.
54
+ const BORDER_SAFE_TAGS = new Set(
55
+ [...SAFE_TAGS].filter(t => t !== 'label')
56
+ );
57
+
46
58
  const OVERUSED_FONTS = new Set([
47
59
  'inter', 'roboto', 'open sans', 'lato', 'montserrat', 'arial', 'helvetica',
48
60
  ]);
49
61
 
62
+ // Brand-associated fonts: don't flag these as "overused" on the brand's own domains.
63
+ // Keys are font names, values are arrays of hostname suffixes where the font is allowed.
64
+ const GOOGLE_DOMAINS = [
65
+ 'google.com', 'youtube.com', 'android.com', 'chromium.org',
66
+ 'chrome.com', 'web.dev', 'gstatic.com', 'firebase.google.com',
67
+ ];
68
+ const BRAND_FONT_DOMAINS = {
69
+ 'roboto': GOOGLE_DOMAINS,
70
+ 'google sans': GOOGLE_DOMAINS,
71
+ 'product sans': GOOGLE_DOMAINS,
72
+ };
73
+
74
+ function isBrandFontOnOwnDomain(font) {
75
+ if (typeof location === 'undefined') return false;
76
+ const allowed = BRAND_FONT_DOMAINS[font];
77
+ if (!allowed) return false;
78
+ const host = location.hostname.toLowerCase();
79
+ return allowed.some(suffix => host === suffix || host.endsWith('.' + suffix));
80
+ }
81
+
50
82
  const GENERIC_FONTS = new Set([
51
83
  'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy',
52
84
  'system-ui', 'ui-serif', 'ui-sans-serif', 'ui-monospace', 'ui-rounded',
@@ -55,146 +87,216 @@ const GENERIC_FONTS = new Set([
55
87
  ]);
56
88
 
57
89
  const ANTIPATTERNS = [
90
+ // ── AI slop: tells that something was AI-generated ──
58
91
  {
59
92
  id: 'side-tab',
93
+ category: 'slop',
60
94
  name: 'Side-tab accent border',
61
95
  description:
62
96
  'Thick colored border on one side of a card — the most recognizable tell of AI-generated UIs. Use a subtler accent or remove it entirely.',
97
+ skillSection: 'Visual Details',
98
+ skillGuideline: 'colored accent stripe',
63
99
  },
64
100
  {
65
101
  id: 'border-accent-on-rounded',
102
+ category: 'slop',
66
103
  name: 'Border accent on rounded element',
67
104
  description:
68
105
  'Thick accent border on a rounded card — the border clashes with the rounded corners. Remove the border or the border-radius.',
106
+ skillSection: 'Visual Details',
107
+ skillGuideline: 'colored accent stripe',
69
108
  },
70
109
  {
71
110
  id: 'overused-font',
111
+ category: 'slop',
72
112
  name: 'Overused font',
73
113
  description:
74
114
  'Inter, Roboto, Open Sans, Lato, Montserrat, and Arial are used on millions of sites. Choose a distinctive font that gives your interface personality.',
115
+ skillSection: 'Typography',
116
+ skillGuideline: 'overused fonts like Inter',
75
117
  },
76
118
  {
77
119
  id: 'single-font',
120
+ category: 'slop',
78
121
  name: 'Single font for everything',
79
122
  description:
80
123
  'Only one font family is used for the entire page. Pair a distinctive display font with a refined body font to create typographic hierarchy.',
124
+ skillSection: 'Typography',
125
+ skillGuideline: 'only one font family for the entire page',
81
126
  },
82
127
  {
83
128
  id: 'flat-type-hierarchy',
129
+ category: 'slop',
84
130
  name: 'Flat type hierarchy',
85
131
  description:
86
132
  'Font sizes are too close together — no clear visual hierarchy. Use fewer sizes with more contrast (aim for at least a 1.25 ratio between steps).',
87
- },
88
- {
89
- id: 'pure-black-white',
90
- name: 'Pure black background',
91
- description:
92
- 'Pure #000000 as a background color looks harsh and unnatural. Tint it slightly toward your brand hue (e.g., oklch(12% 0.01 250)) for a more refined feel.',
93
- },
94
- {
95
- id: 'gray-on-color',
96
- name: 'Gray text on colored background',
97
- description:
98
- 'Gray text looks washed out on colored backgrounds. Use a darker shade of the background color instead, or white/near-white for contrast.',
99
- },
100
- {
101
- id: 'low-contrast',
102
- name: 'Low contrast text',
103
- description:
104
- 'Text does not meet WCAG AA contrast requirements (4.5:1 for body, 3:1 for large text). Increase the contrast between text and background.',
133
+ skillSection: 'Typography',
134
+ skillGuideline: 'flat type hierarchy',
105
135
  },
106
136
  {
107
137
  id: 'gradient-text',
138
+ category: 'slop',
108
139
  name: 'Gradient text',
109
140
  description:
110
141
  'Gradient text is decorative rather than meaningful — a common AI tell, especially on headings and metrics. Use solid colors for text.',
142
+ skillSection: 'Color & Contrast',
143
+ skillGuideline: 'gradient text for',
111
144
  },
112
145
  {
113
146
  id: 'ai-color-palette',
147
+ category: 'slop',
114
148
  name: 'AI color palette',
115
149
  description:
116
150
  'Purple/violet gradients and cyan-on-dark are the most recognizable tells of AI-generated UIs. Choose a distinctive, intentional palette.',
151
+ skillSection: 'Color & Contrast',
152
+ skillGuideline: 'AI color palette',
117
153
  },
118
154
  {
119
155
  id: 'nested-cards',
156
+ category: 'slop',
120
157
  name: 'Nested cards',
121
158
  description:
122
159
  'Cards inside cards create visual noise and excessive depth. Flatten the hierarchy — use spacing, typography, and dividers instead of nesting containers.',
160
+ skillSection: 'Layout & Space',
161
+ skillGuideline: 'Nest cards inside cards',
123
162
  },
124
163
  {
125
164
  id: 'monotonous-spacing',
165
+ category: 'slop',
126
166
  name: 'Monotonous spacing',
127
167
  description:
128
168
  'The same spacing value used everywhere — no rhythm, no variation. Use tight groupings for related items and generous separations between sections.',
169
+ skillSection: 'Layout & Space',
170
+ skillGuideline: 'same spacing everywhere',
129
171
  },
130
172
  {
131
173
  id: 'everything-centered',
174
+ category: 'slop',
132
175
  name: 'Everything centered',
133
176
  description:
134
177
  'Every text element is center-aligned. Left-aligned text with asymmetric layouts feels more designed. Center only hero sections and CTAs.',
178
+ skillSection: 'Layout & Space',
179
+ skillGuideline: 'Center everything',
135
180
  },
136
181
  {
137
182
  id: 'bounce-easing',
183
+ category: 'slop',
138
184
  name: 'Bounce or elastic easing',
139
185
  description:
140
186
  'Bounce and elastic easing feel dated and tacky. Real objects decelerate smoothly — use exponential easing (ease-out-quart/quint/expo) instead.',
141
- },
142
- {
143
- id: 'layout-transition',
144
- name: 'Layout property animation',
145
- description:
146
- 'Animating width, height, padding, or margin causes layout thrash and janky performance. Use transform and opacity instead, or grid-template-rows for height animations.',
187
+ skillSection: 'Motion',
188
+ skillGuideline: 'bounce or elastic easing',
147
189
  },
148
190
  {
149
191
  id: 'dark-glow',
192
+ category: 'slop',
150
193
  name: 'Dark mode with glowing accents',
151
194
  description:
152
195
  'Dark backgrounds with colored box-shadow glows are the default "cool" look of AI-generated UIs. Use subtle, purposeful lighting instead — or skip the dark theme entirely.',
196
+ skillSection: 'Color & Contrast',
197
+ skillGuideline: 'dark mode with glowing accents',
198
+ },
199
+ {
200
+ id: 'icon-tile-stack',
201
+ category: 'slop',
202
+ name: 'Icon tile stacked above heading',
203
+ description:
204
+ 'A small rounded-square icon container above a heading is the universal AI feature-card template — every generator outputs this exact shape. Try a side-by-side icon and heading, or let the icon sit in flow without its own container.',
205
+ skillSection: 'Typography',
206
+ skillGuideline: 'large icons with rounded corners above every heading',
207
+ },
208
+
209
+ // ── Quality: general design and accessibility issues ──
210
+ {
211
+ id: 'pure-black-white',
212
+ category: 'quality',
213
+ name: 'Pure black background',
214
+ description:
215
+ 'Pure #000000 as a background color looks harsh and unnatural. Tint it slightly toward your brand hue (e.g., oklch(12% 0.01 250)) for a more refined feel.',
216
+ skillSection: 'Color & Contrast',
217
+ skillGuideline: 'pure black (#000)',
218
+ },
219
+ {
220
+ id: 'gray-on-color',
221
+ category: 'quality',
222
+ name: 'Gray text on colored background',
223
+ description:
224
+ 'Gray text looks washed out on colored backgrounds. Use a darker shade of the background color instead, or white/near-white for contrast.',
225
+ skillSection: 'Color & Contrast',
226
+ skillGuideline: 'gray text on colored backgrounds',
227
+ },
228
+ {
229
+ id: 'low-contrast',
230
+ category: 'quality',
231
+ name: 'Low contrast text',
232
+ description:
233
+ 'Text does not meet WCAG AA contrast requirements (4.5:1 for body, 3:1 for large text). Increase the contrast between text and background.',
234
+ },
235
+ {
236
+ id: 'layout-transition',
237
+ category: 'quality',
238
+ name: 'Layout property animation',
239
+ description:
240
+ 'Animating width, height, padding, or margin causes layout thrash and janky performance. Use transform and opacity instead, or grid-template-rows for height animations.',
241
+ skillSection: 'Motion',
242
+ skillGuideline: 'Animate layout properties',
153
243
  },
154
244
  {
155
245
  id: 'line-length',
246
+ category: 'quality',
156
247
  name: 'Line length too long',
157
248
  description:
158
249
  'Text lines wider than ~80 characters are hard to read. The eye loses its place tracking back to the start of the next line. Add a max-width (65ch to 75ch) to text containers.',
250
+ skillSection: 'Layout & Space',
251
+ skillGuideline: 'wrap beyond ~80 characters',
159
252
  },
160
253
  {
161
254
  id: 'cramped-padding',
255
+ category: 'quality',
162
256
  name: 'Cramped padding',
163
257
  description:
164
258
  'Text is too close to the edge of its container. Add at least 8px (ideally 12-16px) of padding inside bordered or colored containers.',
165
259
  },
166
260
  {
167
261
  id: 'tight-leading',
262
+ category: 'quality',
168
263
  name: 'Tight line height',
169
264
  description:
170
265
  'Line height below 1.3x the font size makes multi-line text hard to read. Use 1.5 to 1.7 for body text so lines have room to breathe.',
171
266
  },
172
267
  {
173
268
  id: 'skipped-heading',
269
+ category: 'quality',
174
270
  name: 'Skipped heading level',
175
271
  description:
176
272
  'Heading levels should not skip (e.g. h1 then h3 with no h2). Screen readers use heading hierarchy for navigation. Skipping levels breaks the document outline.',
177
273
  },
178
274
  {
179
275
  id: 'justified-text',
276
+ category: 'quality',
180
277
  name: 'Justified text',
181
278
  description:
182
279
  'Justified text without hyphenation creates uneven word spacing ("rivers of white"). Use text-align: left for body text, or enable hyphens: auto if you must justify.',
183
280
  },
184
281
  {
185
282
  id: 'tiny-text',
283
+ category: 'quality',
186
284
  name: 'Tiny body text',
187
285
  description:
188
286
  'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
189
287
  },
190
288
  {
191
289
  id: 'all-caps-body',
290
+ category: 'quality',
192
291
  name: 'All-caps body text',
193
292
  description:
194
293
  'Long passages in uppercase are hard to read. We recognize words by shape (ascenders and descenders), which all-caps removes. Reserve uppercase for short labels and headings.',
294
+ skillSection: 'Typography',
295
+ skillGuideline: 'long body passages in uppercase',
195
296
  },
196
297
  {
197
298
  id: 'wide-tracking',
299
+ category: 'quality',
198
300
  name: 'Wide letter spacing on body text',
199
301
  description:
200
302
  'Letter spacing above 0.05em on body text disrupts natural character groupings and slows reading. Reserve wide tracking for short uppercase labels only.',
@@ -205,9 +307,53 @@ const ANTIPATTERNS = [
205
307
 
206
308
  function isNeutralColor(color) {
207
309
  if (!color || color === 'transparent') return true;
208
- const m = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
209
- if (!m) return true;
210
- return (Math.max(+m[1], +m[2], +m[3]) - Math.min(+m[1], +m[2], +m[3])) < 30;
310
+
311
+ // rgb/rgba — use channel spread. Threshold 30 ≈ 11.7% of the 0–255 range.
312
+ const rgb = color.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
313
+ if (rgb) {
314
+ return (Math.max(+rgb[1], +rgb[2], +rgb[3]) - Math.min(+rgb[1], +rgb[2], +rgb[3])) < 30;
315
+ }
316
+
317
+ // oklch()/lch() — chroma is the second numeric component.
318
+ // oklch chroma is ~0–0.4 in sRGB gamut; >= 0.02 reads as tinted, not gray.
319
+ // lch chroma is ~0–150; >= 3 reads as tinted. jsdom emits both formats
320
+ // literally (it does NOT convert them to rgb).
321
+ const oklch = color.match(/oklch\(\s*[\d.%-]+\s+([\d.-]+)/i);
322
+ if (oklch) return parseFloat(oklch[1]) < 0.02;
323
+ const lch = color.match(/lch\(\s*[\d.%-]+\s+([\d.-]+)/i);
324
+ if (lch) return parseFloat(lch[1]) < 3;
325
+
326
+ // oklab()/lab() — a and b are signed axes; chroma = sqrt(a² + b²).
327
+ // oklab a/b are ~-0.4..0.4, threshold 0.02. lab a/b are ~-128..127, threshold 3.
328
+ const oklab = color.match(/oklab\(\s*[\d.%-]+\s+([\d.-]+)\s+([\d.-]+)/i);
329
+ if (oklab) {
330
+ const a = parseFloat(oklab[1]), b = parseFloat(oklab[2]);
331
+ return Math.hypot(a, b) < 0.02;
332
+ }
333
+ const lab = color.match(/lab\(\s*[\d.%-]+\s+([\d.-]+)\s+([\d.-]+)/i);
334
+ if (lab) {
335
+ const a = parseFloat(lab[1]), b = parseFloat(lab[2]);
336
+ return Math.hypot(a, b) < 3;
337
+ }
338
+
339
+ // hsl/hsla — saturation is the second numeric component (percent).
340
+ // Modern jsdom usually converts hsl() to rgb, but handle it directly for
341
+ // safety across versions and for any engine that preserves the format.
342
+ const hsl = color.match(/hsla?\(\s*[\d.-]+\s*,?\s*([\d.]+)%/i);
343
+ if (hsl) return parseFloat(hsl[1]) < 10;
344
+
345
+ // hwb(hue whiteness% blackness%) — a pixel is fully gray when
346
+ // whiteness + blackness >= 100; chroma-like saturation = 1 - (w+b)/100.
347
+ const hwb = color.match(/hwb\(\s*[\d.-]+\s+([\d.]+)%\s+([\d.]+)%/i);
348
+ if (hwb) {
349
+ const w = parseFloat(hwb[1]), b = parseFloat(hwb[2]);
350
+ return (1 - Math.min(100, w + b) / 100) < 0.1;
351
+ }
352
+
353
+ // Unknown / unrecognized format — err on the side of DETECTING rather
354
+ // than silently skipping. This is the opposite of the previous default,
355
+ // which was the root cause of the oklch bug.
356
+ return false;
211
357
  }
212
358
 
213
359
  function parseRgb(color) {
@@ -232,9 +378,20 @@ function contrastRatio(c1, c2) {
232
378
 
233
379
  function parseGradientColors(bgImage) {
234
380
  if (!bgImage || !bgImage.includes('gradient')) return [];
235
- return [...bgImage.matchAll(/rgba?\([^)]+\)/g)]
236
- .map(m => parseRgb(m[0]))
237
- .filter(Boolean);
381
+ const colors = [];
382
+ for (const m of bgImage.matchAll(/rgba?\([^)]+\)/g)) {
383
+ const c = parseRgb(m[0]);
384
+ if (c) colors.push(c);
385
+ }
386
+ for (const m of bgImage.matchAll(/#([0-9a-f]{6}|[0-9a-f]{3})\b/gi)) {
387
+ const h = m[1];
388
+ if (h.length === 6) {
389
+ colors.push({ r: parseInt(h.slice(0,2),16), g: parseInt(h.slice(2,4),16), b: parseInt(h.slice(4,6),16), a: 1 });
390
+ } else {
391
+ colors.push({ r: parseInt(h[0]+h[0],16), g: parseInt(h[1]+h[1],16), b: parseInt(h[2]+h[2],16), a: 1 });
392
+ }
393
+ }
394
+ return colors;
238
395
  }
239
396
 
240
397
  function hasChroma(c, threshold = 30) {
@@ -263,7 +420,7 @@ function colorToHex(c) {
263
420
  // ─── Section 3: Pure Detection ──────────────────────────────────────────────
264
421
 
265
422
  function checkBorders(tag, widths, colors, radius) {
266
- if (SAFE_TAGS.has(tag)) return [];
423
+ if (BORDER_SAFE_TAGS.has(tag)) return [];
267
424
  const findings = [];
268
425
  const sides = ['Top', 'Right', 'Bottom', 'Left'];
269
426
 
@@ -289,8 +446,20 @@ function checkBorders(tag, widths, colors, radius) {
289
446
  return findings;
290
447
  }
291
448
 
449
+ // Returns true if the given text is composed entirely of emoji characters
450
+ // (plus whitespace / variation selectors). Emojis render as multicolor glyphs
451
+ // regardless of CSS `color`, so contrast checks against the element's text
452
+ // color are meaningless for these nodes.
453
+ const EMOJI_CHAR_RE = /[\u{1F1E6}-\u{1F1FF}\u{1F300}-\u{1F9FF}\u{1FA00}-\u{1FAFF}\u{2600}-\u{27BF}\u{2300}-\u{23FF}\u{FE0F}\u{200D}\u{1F3FB}-\u{1F3FF}]/u;
454
+ const EMOJI_CHARS_GLOBAL = /[\u{1F1E6}-\u{1F1FF}\u{1F300}-\u{1F9FF}\u{1FA00}-\u{1FAFF}\u{2600}-\u{27BF}\u{2300}-\u{23FF}\u{FE0F}\u{200D}\u{1F3FB}-\u{1F3FF}]/gu;
455
+ function isEmojiOnlyText(text) {
456
+ if (!text) return false;
457
+ if (!EMOJI_CHAR_RE.test(text)) return false;
458
+ return text.replace(EMOJI_CHARS_GLOBAL, '').trim() === '';
459
+ }
460
+
292
461
  function checkColors(opts) {
293
- const { tag, textColor, bgColor, effectiveBg, fontSize, fontWeight, hasDirectText, bgClip, bgImage, classList } = opts;
462
+ const { tag, textColor, bgColor, effectiveBg, effectiveBgStops, fontSize, fontWeight, hasDirectText, isEmojiOnly, bgClip, bgImage, classList } = opts;
294
463
  if (SAFE_TAGS.has(tag)) return [];
295
464
  const findings = [];
296
465
 
@@ -299,23 +468,29 @@ function checkColors(opts) {
299
468
  findings.push({ id: 'pure-black-white', snippet: '#000000 background' });
300
469
  }
301
470
 
302
- if (hasDirectText && textColor) {
303
- // Skip background-dependent checks if we can't determine the background (e.g. gradient)
304
- if (effectiveBg) {
305
- // Gray on colored background
471
+ if (hasDirectText && textColor && !isEmojiOnly) {
472
+ // Run background-dependent checks against either a solid bg or, if the
473
+ // ancestor is a gradient, against every gradient stop (use the worst case).
474
+ const bgs = effectiveBg ? [effectiveBg] : (effectiveBgStops && effectiveBgStops.length ? effectiveBgStops : null);
475
+ if (bgs) {
476
+ // Gray on colored background — flag if every stop is chromatic
306
477
  const textLum = relativeLuminance(textColor);
307
478
  const isGray = !hasChroma(textColor, 20) && textLum > 0.05 && textLum < 0.85;
308
- if (isGray && hasChroma(effectiveBg, 40)) {
309
- findings.push({ id: 'gray-on-color', snippet: `text ${colorToHex(textColor)} on bg ${colorToHex(effectiveBg)}` });
479
+ if (isGray && bgs.every(b => hasChroma(b, 40))) {
480
+ const bgLabel = effectiveBg ? colorToHex(effectiveBg) : `gradient(${bgs.map(colorToHex).join(', ')})`;
481
+ findings.push({ id: 'gray-on-color', snippet: `text ${colorToHex(textColor)} on bg ${bgLabel}` });
310
482
  }
311
483
 
312
- // Low contrast (WCAG AA)
313
- const ratio = contrastRatio(textColor, effectiveBg);
484
+ // Low contrast (WCAG AA) — worst case across all bg stops
485
+ const ratios = bgs.map(b => contrastRatio(textColor, b));
486
+ let worstIdx = 0;
487
+ for (let i = 1; i < ratios.length; i++) if (ratios[i] < ratios[worstIdx]) worstIdx = i;
488
+ const ratio = ratios[worstIdx];
314
489
  const isHeading = ['h1', 'h2', 'h3'].includes(tag);
315
490
  const isLargeText = fontSize >= 18 || (fontSize >= 14 && fontWeight >= 700) || isHeading;
316
491
  const threshold = isLargeText ? 3.0 : 4.5;
317
492
  if (ratio < threshold) {
318
- findings.push({ id: 'low-contrast', snippet: `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(effectiveBg)}` });
493
+ findings.push({ id: 'low-contrast', snippet: `${ratio.toFixed(1)}:1 (need ${threshold}:1) — text ${colorToHex(textColor)} on ${colorToHex(bgs[worstIdx])}` });
319
494
  }
320
495
  }
321
496
 
@@ -368,6 +543,62 @@ function isCardLikeFromProps(hasShadow, hasBorder, hasRadius, hasBg) {
368
543
  return hasRadius || hasBg;
369
544
  }
370
545
 
546
+ const HEADING_TAGS = new Set(['h1', 'h2', 'h3', 'h4', 'h5', 'h6']);
547
+
548
+ // Pure check: given a heading and metrics about its previousElementSibling,
549
+ // decide if the sibling is the canonical "icon-tile-stacked-above-heading" shape.
550
+ //
551
+ // Triggers when ALL of the following hold for the sibling:
552
+ // • size 32–128px on both axes (not too small, not a hero image)
553
+ // • aspect ratio 0.7–1.4 (squarish — excludes wide thumbnails / pill badges)
554
+ // • has a non-transparent background-color, background-image, OR a visible border
555
+ // (covers solid colors, white-with-border, gradients — anything that visually
556
+ // defines a tile)
557
+ // • border-radius < width/2 (excludes round avatars; rounded squares pass)
558
+ // • contains an <svg> or icon-class <i> element that's smaller than the tile
559
+ // • the tile sits above the heading (its bottom is above the heading's top)
560
+ function checkIconTile(opts) {
561
+ const { headingTag, headingText, headingTop,
562
+ siblingTag, siblingWidth, siblingHeight, siblingBottom,
563
+ siblingBgColor, siblingBgImage, siblingBorderWidth, siblingBorderRadius,
564
+ hasIconChild, iconChildWidth } = opts;
565
+ if (!HEADING_TAGS.has(headingTag)) return [];
566
+ if (!siblingTag) return [];
567
+ // Don't recurse into nested headings (e.g. h2 above h3 in a section header)
568
+ if (HEADING_TAGS.has(siblingTag)) return [];
569
+
570
+ // Size window: 32–128px on each axis
571
+ if (!(siblingWidth >= 32 && siblingWidth <= 128)) return [];
572
+ if (!(siblingHeight >= 32 && siblingHeight <= 128)) return [];
573
+
574
+ // Squarish aspect ratio
575
+ const ratio = siblingWidth / siblingHeight;
576
+ if (ratio < 0.7 || ratio > 1.4) return [];
577
+
578
+ // Must have something that visually defines the tile
579
+ const bgVisible = (siblingBgColor && siblingBgColor.a > 0.1)
580
+ || (siblingBgImage && siblingBgImage !== 'none' && siblingBgImage !== '');
581
+ const borderVisible = siblingBorderWidth > 0;
582
+ if (!bgVisible && !borderVisible) return [];
583
+
584
+ // Exclude circles (avatars). Rounded squares pass.
585
+ if (siblingBorderRadius >= siblingWidth / 2) return [];
586
+
587
+ // Must contain an icon element smaller than the tile
588
+ if (!hasIconChild) return [];
589
+ if (iconChildWidth && iconChildWidth >= siblingWidth * 0.95) return [];
590
+
591
+ // Vertical stacking: tile must end above where the heading starts.
592
+ // (Allow the check to skip when both top/bottom are 0 — jsdom layout case.)
593
+ if (headingTop && siblingBottom && siblingBottom > headingTop + 4) return [];
594
+
595
+ const text = (headingText || '').trim().slice(0, 60);
596
+ return [{
597
+ id: 'icon-tile-stack',
598
+ snippet: `${Math.round(siblingWidth)}x${Math.round(siblingHeight)}px icon tile above ${headingTag} "${text}"`,
599
+ }];
600
+ }
601
+
371
602
  const LAYOUT_TRANSITION_PROPS = new Set([
372
603
  'width', 'height', 'padding', 'margin',
373
604
  'max-height', 'max-width', 'min-height', 'min-width',
@@ -621,13 +852,39 @@ function resolveBackground(el, win) {
621
852
  return { r: 255, g: 255, b: 255 };
622
853
  }
623
854
 
855
+ // Walk parents looking for a gradient background and return its color stops.
856
+ // Used as a fallback when resolveBackground() returns null because the
857
+ // effective background is a gradient (no single solid color to compare against).
858
+ function resolveGradientStops(el, win) {
859
+ let current = el;
860
+ while (current && current.nodeType === 1) {
861
+ const style = IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
862
+ const bgImage = style.backgroundImage || '';
863
+ if (bgImage && bgImage !== 'none' && /gradient/i.test(bgImage)) {
864
+ const stops = parseGradientColors(bgImage);
865
+ if (stops.length > 0) return stops;
866
+ }
867
+ if (!IS_BROWSER) {
868
+ // jsdom doesn't decompose `background:` shorthand — peek at the raw inline style
869
+ const rawStyle = current.getAttribute?.('style') || '';
870
+ const bgMatch = rawStyle.match(/background(?:-image)?\s*:\s*([^;]+)/i);
871
+ if (bgMatch && /gradient/i.test(bgMatch[1])) {
872
+ const stops = parseGradientColors(bgMatch[1]);
873
+ if (stops.length > 0) return stops;
874
+ }
875
+ }
876
+ current = current.parentElement;
877
+ }
878
+ return null;
879
+ }
880
+
624
881
  // ─── Section 5: Element Adapters ────────────────────────────────────────────
625
882
 
626
883
  // Browser adapters — call getComputedStyle/getBoundingClientRect on live DOM
627
884
 
628
885
  function checkElementBordersDOM(el) {
629
886
  const tag = el.tagName.toLowerCase();
630
- if (SAFE_TAGS.has(tag)) return [];
887
+ if (BORDER_SAFE_TAGS.has(tag)) return [];
631
888
  const rect = el.getBoundingClientRect();
632
889
  if (rect.width < 20 || rect.height < 20) return [];
633
890
  const style = getComputedStyle(el);
@@ -646,21 +903,60 @@ function checkElementColorsDOM(el) {
646
903
  const rect = el.getBoundingClientRect();
647
904
  if (rect.width < 10 || rect.height < 10) return [];
648
905
  const style = getComputedStyle(el);
649
- const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim());
906
+ const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
907
+ const hasDirectText = directText.trim().length > 0;
908
+ const effectiveBg = resolveBackground(el);
650
909
  return checkColors({
651
910
  tag,
652
911
  textColor: parseRgb(style.color),
653
912
  bgColor: parseRgb(style.backgroundColor),
654
- effectiveBg: resolveBackground(el),
913
+ effectiveBg,
914
+ effectiveBgStops: effectiveBg ? null : resolveGradientStops(el),
655
915
  fontSize: parseFloat(style.fontSize) || 16,
656
916
  fontWeight: parseInt(style.fontWeight) || 400,
657
917
  hasDirectText,
918
+ isEmojiOnly: isEmojiOnlyText(directText),
658
919
  bgClip: style.webkitBackgroundClip || style.backgroundClip || '',
659
920
  bgImage: style.backgroundImage || '',
660
921
  classList: el.getAttribute('class') || '',
661
922
  });
662
923
  }
663
924
 
925
+ function checkElementIconTileDOM(el) {
926
+ const tag = el.tagName.toLowerCase();
927
+ if (!HEADING_TAGS.has(tag)) return [];
928
+ const sibling = el.previousElementSibling;
929
+ if (!sibling) return [];
930
+
931
+ const sibRect = sibling.getBoundingClientRect();
932
+ const headRect = el.getBoundingClientRect();
933
+ const sibStyle = getComputedStyle(sibling);
934
+
935
+ // The tile may either contain an <svg>/<i> icon child, OR the tile itself
936
+ // may contain an emoji/symbol character directly as its only text content
937
+ // (the "card-icon" pattern from many AI-generated demos).
938
+ const iconChild = sibling.querySelector('svg, i[data-lucide], i[class*="fa-"], i[class*="icon"]');
939
+ const iconRect = iconChild?.getBoundingClientRect();
940
+ const sibDirectText = [...sibling.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
941
+ const hasInlineEmojiIcon = sibling.children.length === 0 && isEmojiOnlyText(sibDirectText);
942
+
943
+ return checkIconTile({
944
+ headingTag: tag,
945
+ headingText: el.textContent || '',
946
+ headingTop: headRect.top,
947
+ siblingTag: sibling.tagName.toLowerCase(),
948
+ siblingWidth: sibRect.width,
949
+ siblingHeight: sibRect.height,
950
+ siblingBottom: sibRect.bottom,
951
+ siblingBgColor: parseRgb(sibStyle.backgroundColor),
952
+ siblingBgImage: sibStyle.backgroundImage || '',
953
+ siblingBorderWidth: parseFloat(sibStyle.borderTopWidth) || 0,
954
+ siblingBorderRadius: parseFloat(sibStyle.borderRadius) || 0,
955
+ hasIconChild: !!iconChild || hasInlineEmojiIcon,
956
+ iconChildWidth: iconRect?.width || 0,
957
+ });
958
+ }
959
+
664
960
  function checkElementMotionDOM(el) {
665
961
  const tag = el.tagName.toLowerCase();
666
962
  if (SAFE_TAGS.has(tag)) return [];
@@ -762,67 +1058,116 @@ function checkElementAIPaletteDOM(el) {
762
1058
 
763
1059
  const QUALITY_TEXT_TAGS = new Set(['p', 'li', 'td', 'th', 'dd', 'blockquote', 'figcaption']);
764
1060
 
765
- function checkElementQualityDOM(el) {
766
- const tag = el.tagName.toLowerCase();
1061
+ // Resolve a CSS font-size value to pixels by walking up the parent chain.
1062
+ // Browsers resolve em/rem/% to px in getComputedStyle, but jsdom returns the
1063
+ // specified value verbatim — so for the Node path we walk parents ourselves.
1064
+ function resolveFontSizePx(el, win) {
1065
+ const chain = []; // raw font-size strings, leaf → root
1066
+ let cur = el;
1067
+ while (cur && cur.nodeType === 1) {
1068
+ const fs = (win ? win.getComputedStyle(cur) : getComputedStyle(cur)).fontSize;
1069
+ chain.push(fs || '');
1070
+ cur = cur.parentElement;
1071
+ }
1072
+ // Walk root → leaf, resolving each value relative to its parent context.
1073
+ let px = 16; // root default
1074
+ for (let i = chain.length - 1; i >= 0; i--) {
1075
+ const v = chain[i];
1076
+ if (!v || v === 'inherit') continue;
1077
+ const num = parseFloat(v);
1078
+ if (isNaN(num)) continue;
1079
+ if (v.endsWith('px')) px = num;
1080
+ else if (v.endsWith('rem')) px = num * 16;
1081
+ else if (v.endsWith('em')) px = num * px;
1082
+ else if (v.endsWith('%')) px = (num / 100) * px;
1083
+ else px = num; // unitless — already resolved
1084
+ }
1085
+ return px;
1086
+ }
1087
+
1088
+ // Resolve a CSS length value (line-height, letter-spacing, etc.) given a
1089
+ // known font-size context. Returns null for "normal" / unparseable values.
1090
+ function resolveLengthPx(value, fontSizePx) {
1091
+ if (!value || value === 'normal' || value === 'auto' || value === 'inherit') return null;
1092
+ const num = parseFloat(value);
1093
+ if (isNaN(num)) return null;
1094
+ if (value.endsWith('px')) return num;
1095
+ if (value.endsWith('rem')) return num * 16;
1096
+ if (value.endsWith('em')) return num * fontSizePx;
1097
+ if (value.endsWith('%')) return (num / 100) * fontSizePx;
1098
+ // Unitless line-height = multiplier, return px equivalent
1099
+ return num * fontSizePx;
1100
+ }
1101
+
1102
+ // Pure quality checks. Most run on computed CSS and DOM-only inputs (work in
1103
+ // jsdom and the browser). Two checks (line-length, cramped-padding) gate on
1104
+ // element rect dimensions, which jsdom can't compute — pass `rect: null` from
1105
+ // the Node adapter to skip those.
1106
+ //
1107
+ // Both adapters resolve font-size, line-height and letter-spacing to pixels
1108
+ // before calling this so the pure function only deals with numbers.
1109
+ function checkQuality(opts) {
1110
+ const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80 } = opts;
1111
+ const findings = [];
767
1112
  // Skip browser extension injected elements
768
1113
  const elId = el.id || '';
769
- if (elId.startsWith('claude-') || elId.startsWith('cic-')) return [];
770
- const style = getComputedStyle(el);
771
- const findings = [];
772
-
773
- const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 10);
774
- const textLen = el.textContent?.trim().length || 0;
775
- const fontSize = parseFloat(style.fontSize) || 16;
776
- const rect = el.getBoundingClientRect();
1114
+ if (elId.startsWith('claude-') || elId.startsWith('cic-')) return findings;
777
1115
 
778
- // --- Line length too long ---
779
- // Only flag if text is long enough to actually fill the line (>80 chars)
780
- if (hasDirectText && QUALITY_TEXT_TAGS.has(tag) && rect.width > 0 && textLen > 80) {
1116
+ // --- Line length too long --- (browser-only: needs rect.width)
1117
+ if (rect && hasDirectText && QUALITY_TEXT_TAGS.has(tag) && rect.width > 0 && textLen > lineMax) {
781
1118
  const charsPerLine = rect.width / (fontSize * 0.5);
782
- if (charsPerLine > 85) {
783
- findings.push({ id: 'line-length', snippet: `~${Math.round(charsPerLine)} chars/line (aim for <80)` });
1119
+ if (charsPerLine > lineMax + 5) {
1120
+ findings.push({ id: 'line-length', snippet: `~${Math.round(charsPerLine)} chars/line (aim for <${lineMax})` });
784
1121
  }
785
1122
  }
786
1123
 
787
- // --- Cramped padding (skip small elements like labels/badges) ---
788
- if (hasDirectText && textLen > 20 && rect.width > 100 && rect.height > 30) {
1124
+ // --- Cramped padding --- (browser-only: needs rect to skip small badges/labels)
1125
+ // Vertical and horizontal thresholds are independent because line-height
1126
+ // already provides built-in vertical breathing room (the line box is taller
1127
+ // than the cap height), but horizontal has no equivalent. Both scale with
1128
+ // font-size — bigger text demands proportionally more padding.
1129
+ // vertical: max(4px, fontSize × 0.3)
1130
+ // horizontal: max(8px, fontSize × 0.5)
1131
+ if (rect && hasDirectText && textLen > 20 && rect.width > 100 && rect.height > 30) {
789
1132
  const borders = {
790
1133
  top: parseFloat(style.borderTopWidth) || 0,
791
1134
  right: parseFloat(style.borderRightWidth) || 0,
792
1135
  bottom: parseFloat(style.borderBottomWidth) || 0,
793
1136
  left: parseFloat(style.borderLeftWidth) || 0,
794
1137
  };
795
- // Need at least 2 borders (a container), or a non-transparent background
796
1138
  const borderCount = Object.values(borders).filter(w => w > 0).length;
797
1139
  const hasBg = style.backgroundColor && style.backgroundColor !== 'rgba(0, 0, 0, 0)';
798
1140
  if (borderCount >= 2 || hasBg) {
799
- // Only check padding on sides that have borders or where bg creates containment
800
- const paddings = [];
801
- if (hasBg || borders.top > 0) paddings.push(parseFloat(style.paddingTop) || 0);
802
- if (hasBg || borders.right > 0) paddings.push(parseFloat(style.paddingRight) || 0);
803
- if (hasBg || borders.bottom > 0) paddings.push(parseFloat(style.paddingBottom) || 0);
804
- if (hasBg || borders.left > 0) paddings.push(parseFloat(style.paddingLeft) || 0);
805
- if (paddings.length > 0) {
806
- const minPad = Math.min(...paddings);
807
- if (minPad < 8) {
808
- findings.push({ id: 'cramped-padding', snippet: `${minPad}px padding (need >=8px)` });
809
- }
1141
+ const vPads = [], hPads = [];
1142
+ if (hasBg || borders.top > 0) vPads.push(parseFloat(style.paddingTop) || 0);
1143
+ if (hasBg || borders.bottom > 0) vPads.push(parseFloat(style.paddingBottom) || 0);
1144
+ if (hasBg || borders.left > 0) hPads.push(parseFloat(style.paddingLeft) || 0);
1145
+ if (hasBg || borders.right > 0) hPads.push(parseFloat(style.paddingRight) || 0);
1146
+
1147
+ const vMin = vPads.length ? Math.min(...vPads) : Infinity;
1148
+ const hMin = hPads.length ? Math.min(...hPads) : Infinity;
1149
+ const vThresh = Math.max(4, fontSize * 0.3);
1150
+ const hThresh = Math.max(8, fontSize * 0.5);
1151
+
1152
+ // Emit at most one finding per element — pick whichever axis is worse.
1153
+ if (vMin < vThresh) {
1154
+ findings.push({ id: 'cramped-padding', snippet: `${vMin}px vertical padding (need ≥${vThresh.toFixed(1)}px for ${fontSize}px text)` });
1155
+ } else if (hMin < hThresh) {
1156
+ findings.push({ id: 'cramped-padding', snippet: `${hMin}px horizontal padding (need ≥${hThresh.toFixed(1)}px for ${fontSize}px text)` });
810
1157
  }
811
1158
  }
812
1159
  }
813
1160
 
814
1161
  // --- Tight line height ---
815
1162
  if (hasDirectText && textLen > 50 && !['h1','h2','h3','h4','h5','h6'].includes(tag)) {
816
- const lineHeight = parseFloat(style.lineHeight);
817
- if (lineHeight && lineHeight !== NaN) {
818
- const ratio = lineHeight / fontSize;
819
- if (ratio < 1.3 && ratio > 0) {
1163
+ if (lineHeightPx != null && fontSize > 0) {
1164
+ const ratio = lineHeightPx / fontSize;
1165
+ if (ratio > 0 && ratio < 1.3) {
820
1166
  findings.push({ id: 'tight-leading', snippet: `line-height ${ratio.toFixed(2)}x (need >=1.3)` });
821
1167
  }
822
1168
  }
823
1169
  }
824
1170
 
825
-
826
1171
  // --- Justified text (without hyphens) ---
827
1172
  if (hasDirectText && style.textAlign === 'justify') {
828
1173
  const hyphens = style.hyphens || style.webkitHyphens || '';
@@ -832,8 +1177,12 @@ function checkElementQualityDOM(el) {
832
1177
  }
833
1178
 
834
1179
  // --- Tiny body text ---
1180
+ // Only flag actual body content, not UI labels (buttons, tabs, badges, captions, footer text, etc.)
835
1181
  if (hasDirectText && textLen > 20 && fontSize < 12) {
836
- if (!['sub', 'sup', 'code', 'kbd', 'samp', 'var'].includes(tag)) {
1182
+ const skipTags = ['sub', 'sup', 'code', 'kbd', 'samp', 'var', 'caption', 'figcaption'];
1183
+ const inUIContext = el.closest && el.closest('button, a, label, summary, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="option"], nav, footer, [class*="badge" i], [class*="chip" i], [class*="pill" i], [class*="tag" i], [class*="label" i], [class*="caption" i]');
1184
+ const isUppercase = style.textTransform === 'uppercase';
1185
+ if (!skipTags.includes(tag) && !inUIContext && !isUppercase) {
837
1186
  findings.push({ id: 'tiny-text', snippet: `${fontSize}px body text` });
838
1187
  }
839
1188
  }
@@ -846,10 +1195,9 @@ function checkElementQualityDOM(el) {
846
1195
  }
847
1196
 
848
1197
  // --- Wide letter spacing on body text ---
849
- if (hasDirectText && textLen > 20) {
850
- const tracking = parseFloat(style.letterSpacing);
851
- if (tracking > 0 && style.textTransform !== 'uppercase') {
852
- const trackingEm = tracking / fontSize;
1198
+ if (hasDirectText && textLen > 20 && style.textTransform !== 'uppercase') {
1199
+ if (letterSpacingPx != null && letterSpacingPx > 0 && fontSize > 0) {
1200
+ const trackingEm = letterSpacingPx / fontSize;
853
1201
  if (trackingEm > 0.05) {
854
1202
  findings.push({ id: 'wide-tracking', snippet: `letter-spacing: ${trackingEm.toFixed(2)}em on body text` });
855
1203
  }
@@ -859,53 +1207,144 @@ function checkElementQualityDOM(el) {
859
1207
  return findings;
860
1208
  }
861
1209
 
862
- function checkPageQualityDOM() {
863
- const findings = [];
1210
+ function checkElementQualityDOM(el) {
1211
+ const tag = el.tagName.toLowerCase();
1212
+ const style = getComputedStyle(el);
1213
+ const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 10);
1214
+ const textLen = el.textContent?.trim().length || 0;
1215
+ // Browser getComputedStyle resolves everything to px — direct parseFloat
1216
+ // works.
1217
+ const fontSize = parseFloat(style.fontSize) || 16;
1218
+ const lineHeightPx = resolveLengthPx(style.lineHeight, fontSize);
1219
+ const letterSpacingPx = resolveLengthPx(style.letterSpacing, fontSize);
1220
+ const rect = el.getBoundingClientRect();
1221
+ const lineMax = (typeof window !== 'undefined' && window.__IMPECCABLE_CONFIG__?.lineLengthMax) || 80;
1222
+ return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax });
1223
+ }
864
1224
 
865
- // --- Skipped heading levels ---
866
- const headings = document.querySelectorAll('h1, h2, h3, h4, h5, h6');
1225
+ // Pure page-level skipped-heading walk. Takes a Document so it works in both
1226
+ // the browser and jsdom.
1227
+ function checkPageQualityFromDoc(doc) {
1228
+ const findings = [];
1229
+ const headings = doc.querySelectorAll('h1, h2, h3, h4, h5, h6');
867
1230
  let prevLevel = 0;
1231
+ let prevText = '';
868
1232
  for (const h of headings) {
869
1233
  const level = parseInt(h.tagName[1]);
1234
+ const text = (h.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 60);
870
1235
  if (prevLevel > 0 && level > prevLevel + 1) {
871
- findings.push({ type: 'skipped-heading', detail: `h${prevLevel} followed by h${level} (missing h${prevLevel + 1})` });
1236
+ findings.push({
1237
+ id: 'skipped-heading',
1238
+ snippet: `<h${prevLevel}> "${prevText}" followed by <h${level}> "${text}" (missing h${prevLevel + 1})`,
1239
+ });
872
1240
  }
873
1241
  prevLevel = level;
1242
+ prevText = text;
874
1243
  }
875
-
876
1244
  return findings;
877
1245
  }
878
1246
 
1247
+ // Browser adapter (returns the legacy { type, detail } shape used by the overlay loop)
1248
+ function checkPageQualityDOM() {
1249
+ return checkPageQualityFromDoc(document).map(f => ({ type: f.id, detail: f.snippet }));
1250
+ }
1251
+
879
1252
  // Node adapters — take pre-extracted jsdom computed style
880
1253
 
881
- function checkElementBorders(tag, style) {
1254
+ // jsdom doesn't lay out OR resolve em/rem/% to px — so we pre-resolve every
1255
+ // CSS length the rule needs ourselves (walking the parent chain for
1256
+ // font-size inheritance), and pass `rect: null` to skip the two rules that
1257
+ // genuinely need element rects (line-length, cramped-padding).
1258
+ function checkElementQuality(el, style, tag, window) {
1259
+ const hasDirectText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 10);
1260
+ const textLen = el.textContent?.trim().length || 0;
1261
+ const fontSize = resolveFontSizePx(el, window);
1262
+ const lineHeightPx = resolveLengthPx(style.lineHeight, fontSize);
1263
+ const letterSpacingPx = resolveLengthPx(style.letterSpacing, fontSize);
1264
+ return checkQuality({ el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect: null });
1265
+ }
1266
+
1267
+ function checkElementBorders(tag, style, overrides) {
882
1268
  const sides = ['Top', 'Right', 'Bottom', 'Left'];
883
1269
  const widths = {}, colors = {};
884
1270
  for (const s of sides) {
885
1271
  widths[s] = parseFloat(style[`border${s}Width`]) || 0;
886
1272
  colors[s] = style[`border${s}Color`] || '';
1273
+ // jsdom silently drops any border shorthand containing var(), leaving
1274
+ // both width and color empty on the computed style. When the detectHtml
1275
+ // pre-pass pulled a resolved value off the rule, use it to fill in the
1276
+ // missing side so the side-tab check can run. Real browsers resolve
1277
+ // var() natively, so this fallback is a no-op in the browser path.
1278
+ if (widths[s] === 0 && overrides && overrides[s]) {
1279
+ widths[s] = overrides[s].width;
1280
+ colors[s] = overrides[s].color;
1281
+ } else if (colors[s] && colors[s].startsWith('var(') && overrides && overrides[s]) {
1282
+ // Longhand case: jsdom kept the width but left the color as the
1283
+ // literal `var(...)` string. Substitute the resolved color.
1284
+ colors[s] = overrides[s].color;
1285
+ }
887
1286
  }
888
1287
  return checkBorders(tag, widths, colors, parseFloat(style.borderRadius) || 0);
889
1288
  }
890
1289
 
891
1290
  function checkElementColors(el, style, tag, window) {
892
- const hasText = el.textContent?.trim().length > 0;
893
- const hasDirectText = hasText && [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim());
1291
+ const directText = [...el.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
1292
+ const hasDirectText = directText.trim().length > 0;
894
1293
 
1294
+ const effectiveBg = resolveBackground(el, window);
895
1295
  return checkColors({
896
1296
  tag,
897
1297
  textColor: parseRgb(style.color),
898
1298
  bgColor: parseRgb(style.backgroundColor),
899
- effectiveBg: resolveBackground(el, window),
1299
+ effectiveBg,
1300
+ effectiveBgStops: effectiveBg ? null : resolveGradientStops(el, window),
900
1301
  fontSize: parseFloat(style.fontSize) || 16,
901
1302
  fontWeight: parseInt(style.fontWeight) || 400,
902
1303
  hasDirectText,
1304
+ isEmojiOnly: isEmojiOnlyText(directText),
903
1305
  bgClip: style.webkitBackgroundClip || style.backgroundClip || '',
904
1306
  bgImage: style.backgroundImage || '',
905
1307
  classList: el.getAttribute?.('class') || el.className || '',
906
1308
  });
907
1309
  }
908
1310
 
1311
+ function checkElementIconTile(el, tag, window) {
1312
+ if (!HEADING_TAGS.has(tag)) return [];
1313
+ const sibling = el.previousElementSibling;
1314
+ if (!sibling) return [];
1315
+
1316
+ const sibStyle = window.getComputedStyle(sibling);
1317
+ // jsdom doesn't lay out — read explicit pixel dimensions from CSS instead.
1318
+ const sibWidth = parseFloat(sibStyle.width) || 0;
1319
+ const sibHeight = parseFloat(sibStyle.height) || 0;
1320
+
1321
+ const iconChild = sibling.querySelector('svg, i[data-lucide], i[class*="fa-"], i[class*="icon"]');
1322
+ let iconWidth = 0;
1323
+ if (iconChild) {
1324
+ const iconStyle = window.getComputedStyle(iconChild);
1325
+ iconWidth = parseFloat(iconStyle.width) || parseFloat(iconChild.getAttribute('width')) || 0;
1326
+ }
1327
+ // Or: tile contains an emoji/symbol character directly as its only content
1328
+ const sibDirectText = [...sibling.childNodes].filter(n => n.nodeType === 3).map(n => n.textContent).join('');
1329
+ const hasInlineEmojiIcon = sibling.children.length === 0 && isEmojiOnlyText(sibDirectText);
1330
+
1331
+ return checkIconTile({
1332
+ headingTag: tag,
1333
+ headingText: el.textContent || '',
1334
+ headingTop: 0, // jsdom: no layout, skip vertical-stacking gate
1335
+ siblingTag: sibling.tagName.toLowerCase(),
1336
+ siblingWidth: sibWidth,
1337
+ siblingHeight: sibHeight,
1338
+ siblingBottom: 0,
1339
+ siblingBgColor: parseRgb(sibStyle.backgroundColor),
1340
+ siblingBgImage: sibStyle.backgroundImage || '',
1341
+ siblingBorderWidth: parseFloat(sibStyle.borderTopWidth) || 0,
1342
+ siblingBorderRadius: parseFloat(sibStyle.borderRadius) || 0,
1343
+ hasIconChild: !!iconChild || hasInlineEmojiIcon,
1344
+ iconChildWidth: iconWidth,
1345
+ });
1346
+ }
1347
+
909
1348
  function checkElementMotion(tag, style) {
910
1349
  return checkMotion({
911
1350
  tag,
@@ -927,41 +1366,45 @@ function checkElementGlow(tag, style, effectiveBg) {
927
1366
 
928
1367
  function checkTypography() {
929
1368
  const findings = [];
930
- const fonts = new Set();
931
- const overusedFound = new Set();
932
1369
 
933
- for (const sheet of document.styleSheets) {
934
- let rules;
935
- try { rules = sheet.cssRules || sheet.rules; } catch { continue; }
936
- if (!rules) continue;
937
- for (const rule of rules) {
938
- if (rule.type !== 1) continue;
939
- const ff = rule.style?.fontFamily;
940
- if (!ff) continue;
941
- const stack = ff.split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase());
942
- const primary = stack.find(f => f && !GENERIC_FONTS.has(f));
943
- if (primary) {
944
- fonts.add(primary);
945
- if (OVERUSED_FONTS.has(primary)) overusedFound.add(primary);
946
- }
947
- }
1370
+ // Walk actual text-bearing elements and tally font usage by *computed style*.
1371
+ // This is much more accurate than scanning CSS rules — it ignores rules that
1372
+ // exist in the stylesheet but apply to nothing (e.g. demo classes showing
1373
+ // anti-patterns), and counts what the user actually sees.
1374
+ const fontUsage = new Map(); // primary font name → count of elements
1375
+ let totalTextElements = 0;
1376
+ for (const el of document.querySelectorAll('p, h1, h2, h3, h4, h5, h6, li, td, th, dd, blockquote, figcaption, a, button, label, span')) {
1377
+ // Skip impeccable's own elements
1378
+ if (el.closest && el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
1379
+ // Only count elements that actually have visible direct text
1380
+ const hasText = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 0);
1381
+ if (!hasText) continue;
1382
+ const style = getComputedStyle(el);
1383
+ const ff = style.fontFamily;
1384
+ if (!ff) continue;
1385
+ const stack = ff.split(',').map(f => f.trim().replace(/^['"]|['"]$/g, '').toLowerCase());
1386
+ const primary = stack.find(f => f && !GENERIC_FONTS.has(f));
1387
+ if (!primary) continue;
1388
+ fontUsage.set(primary, (fontUsage.get(primary) || 0) + 1);
1389
+ totalTextElements++;
948
1390
  }
949
1391
 
950
- const html = document.documentElement.outerHTML;
951
- const gfRe = /fonts\.googleapis\.com\/css2?\?family=([^&"'\s]+)/gi;
952
- let m;
953
- while ((m = gfRe.exec(html)) !== null) {
954
- for (const f of m[1].split('|').map(f => f.split(':')[0].replace(/\+/g, ' ').toLowerCase())) {
955
- fonts.add(f);
956
- if (OVERUSED_FONTS.has(f)) overusedFound.add(f);
1392
+ if (totalTextElements >= 20) {
1393
+ // A font is "primary" if it's used by at least 15% of text elements
1394
+ const PRIMARY_THRESHOLD = 0.15;
1395
+ for (const [font, count] of fontUsage) {
1396
+ const share = count / totalTextElements;
1397
+ if (share < PRIMARY_THRESHOLD) continue;
1398
+ if (!OVERUSED_FONTS.has(font)) continue;
1399
+ if (isBrandFontOnOwnDomain(font)) continue;
1400
+ findings.push({ type: 'overused-font', detail: `Primary font: ${font} (${Math.round(share * 100)}% of text)` });
957
1401
  }
958
- }
959
1402
 
960
- for (const font of overusedFound) {
961
- findings.push({ type: 'overused-font', detail: `Primary font: ${font}` });
962
- }
963
- if (fonts.size === 1 && document.querySelectorAll('*').length >= 20) {
964
- findings.push({ type: 'single-font', detail: `only font used is ${[...fonts][0]}` });
1403
+ // Single-font check: only one distinct primary font across all text
1404
+ if (fontUsage.size === 1) {
1405
+ const only = [...fontUsage.keys()][0];
1406
+ findings.push({ type: 'single-font', detail: `only font used is ${only}` });
1407
+ }
965
1408
  }
966
1409
 
967
1410
  const sizes = new Set();
@@ -1204,52 +1647,143 @@ function checkPageLayout(doc, win) {
1204
1647
  // ─── Section 7: Browser UI (IS_BROWSER only) ────────────────────────────────
1205
1648
 
1206
1649
  if (IS_BROWSER) {
1207
- const LABEL_BG = 'oklch(55% 0.25 350)';
1208
- const OUTLINE_COLOR = 'oklch(60% 0.25 350)';
1650
+ // Detect extension mode via the script tag's data attribute or the document element fallback.
1651
+ // currentScript is reliable for synchronously-executing scripts (which our IIFE is).
1652
+ const _myScript = document.currentScript;
1653
+ const EXTENSION_MODE = (_myScript && _myScript.dataset.impeccableExtension === 'true')
1654
+ || document.documentElement.dataset.impeccableExtension === 'true';
1655
+
1656
+ const BRAND_COLOR = 'oklch(55% 0.25 350)';
1657
+ const BRAND_COLOR_HOVER = 'oklch(45% 0.25 350)';
1658
+ const LABEL_BG = BRAND_COLOR;
1659
+ const OUTLINE_COLOR = BRAND_COLOR;
1209
1660
 
1210
1661
  // Inject hover styles via CSS (more reliable than JS event listeners)
1211
1662
  const styleEl = document.createElement('style');
1212
1663
  styleEl.textContent = `
1213
1664
  @keyframes impeccable-reveal {
1214
- from { opacity: 0; outline-color: transparent; }
1215
- to { opacity: 1; outline-color: ${OUTLINE_COLOR}; }
1665
+ from { opacity: 0; }
1666
+ to { opacity: 1; }
1216
1667
  }
1217
1668
  .impeccable-overlay:not(.impeccable-banner) {
1218
1669
  pointer-events: none;
1219
1670
  outline: 2px solid ${OUTLINE_COLOR};
1220
1671
  border-radius: 4px;
1221
- transition: outline-color 0.3s ease;
1672
+ transition: outline-color 0.15s ease;
1222
1673
  animation: impeccable-reveal 0.4s cubic-bezier(0.16, 1, 0.3, 1) both;
1223
1674
  animation-play-state: paused;
1675
+ border-top-left-radius: 0;
1224
1676
  }
1225
1677
  .impeccable-overlay.impeccable-visible {
1226
1678
  animation-play-state: running;
1227
1679
  }
1228
1680
  .impeccable-overlay.impeccable-hover {
1229
- outline-color: rgba(0,0,0,0.85);
1681
+ outline-color: ${BRAND_COLOR_HOVER};
1230
1682
  z-index: 100001 !important;
1231
1683
  }
1232
- .impeccable-label-name,
1233
- .impeccable-label-detail {
1234
- transition: transform 0.3s cubic-bezier(0.16, 1, 0.3, 1);
1684
+ .impeccable-overlay.impeccable-hover .impeccable-label {
1685
+ background: ${BRAND_COLOR_HOVER};
1235
1686
  }
1236
- .impeccable-label-detail {
1237
- position: absolute; top: 100%; left: 0;
1687
+ .impeccable-overlay.impeccable-spotlight {
1688
+ z-index: 100002 !important;
1238
1689
  }
1239
- .impeccable-overlay.impeccable-hover .impeccable-label-name,
1240
- .impeccable-overlay.impeccable-hover .impeccable-label-detail {
1241
- transform: translateY(-100%);
1690
+ .impeccable-overlay.impeccable-spotlight-dimmed {
1691
+ opacity: 0.15 !important;
1692
+ animation: none !important;
1693
+ filter: blur(3px);
1242
1694
  }
1243
- .impeccable-hidden .impeccable-overlay:not(.impeccable-banner) {
1695
+ .impeccable-spotlight-backdrop {
1696
+ position: fixed;
1697
+ top: 0; left: 0; right: 0; bottom: 0;
1698
+ backdrop-filter: blur(3px) brightness(0.6);
1699
+ -webkit-backdrop-filter: blur(3px) brightness(0.6);
1700
+ pointer-events: none;
1701
+ z-index: 99998;
1702
+ opacity: 0;
1703
+ outline: none !important;
1704
+ animation: none !important;
1705
+ }
1706
+ .impeccable-spotlight-backdrop.impeccable-visible {
1707
+ opacity: 1;
1708
+ }
1709
+ .impeccable-hidden .impeccable-overlay${EXTENSION_MODE ? '' : ':not(.impeccable-banner)'} {
1710
+ display: none !important;
1711
+ }
1712
+ .impeccable-hidden .impeccable-overlay${EXTENSION_MODE ? '' : ':not(.impeccable-banner)'} {
1244
1713
  display: none !important;
1245
1714
  }
1246
1715
  `;
1247
1716
  (document.head || document.documentElement).appendChild(styleEl);
1248
1717
 
1718
+ // Spotlight backdrop element (created lazily on first use)
1719
+ let spotlightBackdrop = null;
1720
+ let spotlightTarget = null;
1721
+ let spotlightTimer = null;
1722
+
1723
+ function getSpotlightBackdrop() {
1724
+ if (!spotlightBackdrop) {
1725
+ spotlightBackdrop = document.createElement('div');
1726
+ spotlightBackdrop.className = 'impeccable-spotlight-backdrop';
1727
+ document.body.appendChild(spotlightBackdrop);
1728
+ }
1729
+ return spotlightBackdrop;
1730
+ }
1731
+
1732
+ function updateSpotlightClipPath() {
1733
+ if (!spotlightBackdrop || !spotlightTarget) return;
1734
+ const r = spotlightTarget.getBoundingClientRect();
1735
+ // Match the overlay's outer edge: element rect + 4px (2px overlay offset + 2px outline width)
1736
+ const inset = 4;
1737
+ const radius = 6; // outline border-radius (4) + outline width (2)
1738
+ const x1 = r.left - inset;
1739
+ const y1 = r.top - inset;
1740
+ const x2 = r.right + inset;
1741
+ const y2 = r.bottom + inset;
1742
+ const vw = window.innerWidth;
1743
+ const vh = window.innerHeight;
1744
+ // Outer rect + rounded inner rect (evenodd creates a hole)
1745
+ const path = `M0 0H${vw}V${vh}H0Z M${x1 + radius} ${y1}H${x2 - radius}A${radius} ${radius} 0 0 1 ${x2} ${y1 + radius}V${y2 - radius}A${radius} ${radius} 0 0 1 ${x2 - radius} ${y2}H${x1 + radius}A${radius} ${radius} 0 0 1 ${x1} ${y2 - radius}V${y1 + radius}A${radius} ${radius} 0 0 1 ${x1 + radius} ${y1}Z`;
1746
+ spotlightBackdrop.style.clipPath = `path(evenodd, "${path}")`;
1747
+ }
1748
+
1749
+ function showSpotlight(target) {
1750
+ if (!target || !target.getBoundingClientRect) return;
1751
+ // Respect the spotlightBlur setting: if disabled, don't show the backdrop
1752
+ if (window.__IMPECCABLE_CONFIG__?.spotlightBlur === false) {
1753
+ spotlightTarget = target;
1754
+ return;
1755
+ }
1756
+ spotlightTarget = target;
1757
+ const bd = getSpotlightBackdrop();
1758
+ updateSpotlightClipPath();
1759
+ bd.classList.add('impeccable-visible');
1760
+ }
1761
+
1762
+ function hideSpotlight() {
1763
+ spotlightTarget = null;
1764
+ if (spotlightTimer) { clearTimeout(spotlightTimer); spotlightTimer = null; }
1765
+ if (spotlightBackdrop) spotlightBackdrop.classList.remove('impeccable-visible');
1766
+ }
1767
+
1768
+ function isInViewport(el) {
1769
+ const r = el.getBoundingClientRect();
1770
+ return r.top >= 0 && r.left >= 0 && r.bottom <= window.innerHeight && r.right <= window.innerWidth;
1771
+ }
1772
+
1773
+ // Reposition spotlight on scroll/resize
1774
+ window.addEventListener('scroll', () => {
1775
+ if (spotlightTarget) updateSpotlightClipPath();
1776
+ }, { passive: true });
1777
+ window.addEventListener('resize', () => {
1778
+ if (spotlightTarget) updateSpotlightClipPath();
1779
+ });
1780
+
1249
1781
  const overlays = [];
1250
1782
  const TYPE_LABELS = {};
1783
+ const RULE_CATEGORY = {};
1251
1784
  for (const ap of ANTIPATTERNS) {
1252
- TYPE_LABELS[ap.id] = ap.name.toLowerCase().substring(0, 26);
1785
+ TYPE_LABELS[ap.id] = ap.name.toLowerCase();
1786
+ RULE_CATEGORY[ap.id] = ap.category || 'quality';
1253
1787
  }
1254
1788
 
1255
1789
  function isInFixedContext(el) {
@@ -1281,6 +1815,8 @@ if (IS_BROWSER) {
1281
1815
  function repositionOverlays() {
1282
1816
  for (const o of overlays) {
1283
1817
  if (!o._targetEl || o.classList.contains('impeccable-banner')) continue;
1818
+ // Skip overlays whose target is currently hidden (display: none on the overlay)
1819
+ if (o.style.display === 'none') continue;
1284
1820
  positionOverlay(o);
1285
1821
  }
1286
1822
  }
@@ -1291,6 +1827,13 @@ if (IS_BROWSER) {
1291
1827
  resizeRAF = requestAnimationFrame(repositionOverlays);
1292
1828
  };
1293
1829
  window.addEventListener('resize', onResize);
1830
+ // Reposition on scroll too -- catches sticky/parallax shifts
1831
+ window.addEventListener('scroll', onResize, { passive: true });
1832
+ // Reposition when body resizes (lazy-loaded images, dynamic content, fonts loading)
1833
+ if (typeof ResizeObserver !== 'undefined') {
1834
+ const bodyResizeObserver = new ResizeObserver(onResize);
1835
+ bodyResizeObserver.observe(document.body);
1836
+ }
1294
1837
 
1295
1838
  // Track target element visibility via IntersectionObserver.
1296
1839
  // Uses a huge rootMargin so all *rendered* elements count as intersecting,
@@ -1306,8 +1849,17 @@ if (IS_BROWSER) {
1306
1849
  positionOverlay(overlay);
1307
1850
  if (!overlay._revealed) {
1308
1851
  overlay._revealed = true;
1309
- overlay.style.animationDelay = `${(overlay._staggerIndex || 0) * 80}ms`;
1310
- requestAnimationFrame(() => overlay.classList.add('impeccable-visible'));
1852
+ if (firstScanDone) {
1853
+ // Subsequent reveals (re-scans, scroll-into-view): instant, no animation
1854
+ overlay.style.animation = 'none';
1855
+ } else {
1856
+ // Initial scan: staggered cascade reveal
1857
+ overlay.style.animationDelay = `${Math.min((overlay._staggerIndex || 0) * 60, 600)}ms`;
1858
+ }
1859
+ requestAnimationFrame(() => {
1860
+ overlay.classList.add('impeccable-visible');
1861
+ if (overlay._checkLabel) overlay._checkLabel();
1862
+ });
1311
1863
  }
1312
1864
  } else {
1313
1865
  overlay.style.display = 'none';
@@ -1329,6 +1881,8 @@ if (IS_BROWSER) {
1329
1881
  });
1330
1882
 
1331
1883
  const highlight = function(el, findings) {
1884
+ const hasSlop = findings.some(f => RULE_CATEGORY[f.type || f.id] === 'slop');
1885
+
1332
1886
  const fixed = isInFixedContext(el);
1333
1887
  const rect = el.getBoundingClientRect();
1334
1888
  const outline = document.createElement('div');
@@ -1343,33 +1897,85 @@ if (IS_BROWSER) {
1343
1897
  zIndex: '99999', boxSizing: 'border-box',
1344
1898
  });
1345
1899
 
1346
- const typeText = findings.map(f => TYPE_LABELS[f.type || f.id] || f.type || f.id).join(', ');
1347
- const detailText = findings.map(f => f.detail || f.snippet).join(' | ');
1900
+ // Build per-finding label entries: ✦ prefix for slop
1901
+ const entries = findings.map(f => {
1902
+ const name = TYPE_LABELS[f.type || f.id] || f.type || f.id;
1903
+ const prefix = RULE_CATEGORY[f.type || f.id] === 'slop' ? '\u2726 ' : '';
1904
+ return { name: prefix + name, detail: f.detail || f.snippet };
1905
+ });
1906
+ const allText = entries.map(e => e.name).join(', ');
1348
1907
 
1349
1908
  const label = document.createElement('div');
1350
1909
  label.className = 'impeccable-label';
1351
1910
  Object.assign(label.style, {
1352
- position: 'absolute', top: '-22px', left: '0',
1353
- clipPath: 'inset(0 -999px)',
1911
+ position: 'absolute', bottom: '100%', left: '-2px',
1912
+ display: 'flex', alignItems: 'center',
1913
+ whiteSpace: 'nowrap',
1914
+ fontSize: '11px', fontWeight: '600', letterSpacing: '0.02em',
1915
+ color: 'white', lineHeight: '14px',
1916
+ background: LABEL_BG,
1917
+ fontFamily: 'system-ui, sans-serif',
1918
+ borderRadius: '4px 4px 0 0',
1354
1919
  });
1355
1920
 
1356
- const rowBase = {
1357
- padding: '2px 8px', borderRadius: '3px', whiteSpace: 'nowrap',
1358
- fontSize: '11px', fontWeight: '600', letterSpacing: '0.02em',
1359
- color: 'white', lineHeight: '16px',
1360
- };
1921
+ const textSpan = document.createElement('span');
1922
+ textSpan.style.padding = '3px 8px';
1923
+ textSpan.textContent = allText;
1924
+ label.appendChild(textSpan);
1361
1925
 
1362
- const nameRow = document.createElement('div');
1363
- nameRow.className = 'impeccable-label-name';
1364
- nameRow.textContent = typeText;
1365
- Object.assign(nameRow.style, { ...rowBase, background: LABEL_BG, fontFamily: 'system-ui, sans-serif' });
1366
- label.appendChild(nameRow);
1926
+ // State for cycling mode
1927
+ let cycleMode = false;
1928
+ let cycleIndex = 0;
1929
+ let isHovered = false;
1930
+ let prevBtn, nextBtn;
1367
1931
 
1368
- const detailRow = document.createElement('div');
1369
- detailRow.className = 'impeccable-label-detail';
1370
- detailRow.textContent = detailText;
1371
- Object.assign(detailRow.style, { ...rowBase, background: 'rgba(0,0,0,0.85)', fontFamily: 'ui-monospace, monospace', fontWeight: '400' });
1372
- label.appendChild(detailRow);
1932
+ function updateCycleText() {
1933
+ const e = entries[cycleIndex];
1934
+ textSpan.textContent = isHovered ? e.detail : e.name;
1935
+ }
1936
+
1937
+ function enableCycleMode() {
1938
+ if (cycleMode || entries.length < 2) return;
1939
+ cycleMode = true;
1940
+
1941
+ const btnStyle = {
1942
+ background: 'none', border: 'none', color: 'rgba(255,255,255,0.7)',
1943
+ fontSize: '11px', cursor: 'pointer', padding: '3px 4px',
1944
+ fontFamily: 'system-ui, sans-serif', lineHeight: '14px',
1945
+ pointerEvents: 'auto',
1946
+ };
1947
+
1948
+ const navGroup = document.createElement('span');
1949
+ Object.assign(navGroup.style, {
1950
+ display: 'inline-flex', alignItems: 'center', flexShrink: '0',
1951
+ });
1952
+
1953
+ prevBtn = document.createElement('button');
1954
+ prevBtn.textContent = '\u2039';
1955
+ Object.assign(prevBtn.style, btnStyle);
1956
+ prevBtn.style.paddingLeft = '6px';
1957
+ prevBtn.addEventListener('click', (e) => {
1958
+ e.stopPropagation();
1959
+ cycleIndex = (cycleIndex - 1 + entries.length) % entries.length;
1960
+ updateCycleText();
1961
+ });
1962
+
1963
+ nextBtn = document.createElement('button');
1964
+ nextBtn.textContent = '\u203A';
1965
+ Object.assign(nextBtn.style, btnStyle);
1966
+ nextBtn.style.paddingRight = '2px';
1967
+ nextBtn.addEventListener('click', (e) => {
1968
+ e.stopPropagation();
1969
+ cycleIndex = (cycleIndex + 1) % entries.length;
1970
+ updateCycleText();
1971
+ });
1972
+
1973
+ navGroup.appendChild(prevBtn);
1974
+ navGroup.appendChild(nextBtn);
1975
+ label.insertBefore(navGroup, textSpan);
1976
+ textSpan.style.padding = '3px 8px 3px 4px';
1977
+ updateCycleText();
1978
+ }
1373
1979
 
1374
1980
  outline.appendChild(label);
1375
1981
 
@@ -1379,9 +1985,36 @@ if (IS_BROWSER) {
1379
1985
  el._impeccableOverlay = outline;
1380
1986
  visibilityObserver.observe(el);
1381
1987
 
1382
- // Drive hover state from the target element so pointer events pass through
1383
- el.addEventListener('mouseenter', () => outline.classList.add('impeccable-hover'));
1384
- el.addEventListener('mouseleave', () => outline.classList.remove('impeccable-hover'));
1988
+ // After first paint, check label width vs outline
1989
+ outline._checkLabel = () => {
1990
+ if (entries.length > 1 && label.offsetWidth > outline.offsetWidth) {
1991
+ enableCycleMode();
1992
+ }
1993
+ };
1994
+
1995
+ // Hover: show detail text, darken
1996
+ el.addEventListener('mouseenter', () => {
1997
+ isHovered = true;
1998
+ outline.classList.add('impeccable-hover');
1999
+ outline.style.outlineColor = BRAND_COLOR_HOVER;
2000
+ label.style.background = BRAND_COLOR_HOVER;
2001
+ if (cycleMode) {
2002
+ updateCycleText();
2003
+ } else {
2004
+ textSpan.textContent = entries.map(e => e.detail).join(' | ');
2005
+ }
2006
+ });
2007
+ el.addEventListener('mouseleave', () => {
2008
+ isHovered = false;
2009
+ outline.classList.remove('impeccable-hover');
2010
+ outline.style.outlineColor = '';
2011
+ label.style.background = LABEL_BG;
2012
+ if (cycleMode) {
2013
+ updateCycleText();
2014
+ } else {
2015
+ textSpan.textContent = allText;
2016
+ }
2017
+ });
1385
2018
 
1386
2019
  document.body.appendChild(outline);
1387
2020
  overlays.push(outline);
@@ -1413,8 +2046,9 @@ if (IS_BROWSER) {
1413
2046
  scrollbarWidth: 'none',
1414
2047
  });
1415
2048
  for (const f of findings) {
2049
+ const prefix = RULE_CATEGORY[f.type] === 'slop' ? '\u2726 ' : '';
1416
2050
  const tag = document.createElement('span');
1417
- tag.textContent = `${TYPE_LABELS[f.type] || f.type}: ${f.detail}`;
2051
+ tag.textContent = `${prefix}${TYPE_LABELS[f.type] || f.type}: ${f.detail}`;
1418
2052
  Object.assign(tag.style, {
1419
2053
  background: 'rgba(255,255,255,0.15)', padding: '2px 8px',
1420
2054
  borderRadius: '3px', fontSize: '12px', fontFamily: 'ui-monospace, monospace',
@@ -1424,47 +2058,153 @@ if (IS_BROWSER) {
1424
2058
  }
1425
2059
  banner.appendChild(scrollArea);
1426
2060
 
1427
- // Controls area (always visible on the right)
1428
- const controls = document.createElement('div');
1429
- Object.assign(controls.style, {
1430
- display: 'flex', alignItems: 'center', gap: '2px',
1431
- padding: '0 8px', flexShrink: '0',
1432
- });
2061
+ // Controls area (only in standalone mode, not extension)
2062
+ if (!EXTENSION_MODE) {
2063
+ const controls = document.createElement('div');
2064
+ Object.assign(controls.style, {
2065
+ display: 'flex', alignItems: 'center', gap: '2px',
2066
+ padding: '0 8px', flexShrink: '0',
2067
+ });
1433
2068
 
1434
- // Toggle visibility button
1435
- const toggle = document.createElement('button');
1436
- toggle.textContent = '\u25C9'; // circle with dot (visible state)
1437
- toggle.title = 'Toggle overlay visibility';
1438
- Object.assign(toggle.style, {
1439
- background: 'none', border: 'none',
1440
- color: 'white', fontSize: '16px', cursor: 'pointer', padding: '0 4px',
1441
- opacity: '0.85', transition: 'opacity 0.15s',
1442
- });
1443
- let overlaysVisible = true;
1444
- toggle.addEventListener('click', () => {
1445
- overlaysVisible = !overlaysVisible;
1446
- document.body.classList.toggle('impeccable-hidden', !overlaysVisible);
1447
- toggle.textContent = overlaysVisible ? '\u25C9' : '\u25CB'; // filled vs empty circle
1448
- toggle.style.opacity = overlaysVisible ? '0.85' : '0.5';
1449
- });
1450
- controls.appendChild(toggle);
1451
-
1452
- // Close button
1453
- const close = document.createElement('button');
1454
- close.textContent = '\u00d7';
1455
- close.title = 'Dismiss banner';
1456
- Object.assign(close.style, {
1457
- background: 'none', border: 'none',
1458
- color: 'white', fontSize: '18px', cursor: 'pointer', padding: '0 4px',
1459
- });
1460
- close.addEventListener('click', () => banner.remove());
1461
- controls.appendChild(close);
2069
+ // Toggle visibility button
2070
+ const toggle = document.createElement('button');
2071
+ toggle.textContent = '\u25C9'; // circle with dot (visible state)
2072
+ toggle.title = 'Toggle overlay visibility';
2073
+ Object.assign(toggle.style, {
2074
+ background: 'none', border: 'none',
2075
+ color: 'white', fontSize: '16px', cursor: 'pointer', padding: '0 4px',
2076
+ opacity: '0.85', transition: 'opacity 0.15s',
2077
+ });
2078
+ let overlaysVisible = true;
2079
+ toggle.addEventListener('click', () => {
2080
+ overlaysVisible = !overlaysVisible;
2081
+ document.body.classList.toggle('impeccable-hidden', !overlaysVisible);
2082
+ toggle.textContent = overlaysVisible ? '\u25C9' : '\u25CB'; // filled vs empty circle
2083
+ toggle.style.opacity = overlaysVisible ? '0.85' : '0.5';
2084
+ });
2085
+ controls.appendChild(toggle);
2086
+
2087
+ // Close button
2088
+ const close = document.createElement('button');
2089
+ close.textContent = '\u00d7';
2090
+ close.title = 'Dismiss banner';
2091
+ Object.assign(close.style, {
2092
+ background: 'none', border: 'none',
2093
+ color: 'white', fontSize: '18px', cursor: 'pointer', padding: '0 4px',
2094
+ });
2095
+ close.addEventListener('click', () => banner.remove());
2096
+ controls.appendChild(close);
1462
2097
 
1463
- banner.appendChild(controls);
2098
+ banner.appendChild(controls);
2099
+ }
1464
2100
  document.body.appendChild(banner);
1465
2101
  overlays.push(banner);
1466
2102
  };
1467
2103
 
2104
+ // Heuristic for skipping CSS-in-JS hashed class names like "css-1a2b3c" or "_2x4hG_".
2105
+ // These change between builds and produce brittle, ugly selectors.
2106
+ function isLikelyHashedClass(c) {
2107
+ if (!c) return true;
2108
+ if (/^(css|sc|emotion|jsx|module)-[\w-]{4,}$/i.test(c)) return true;
2109
+ if (/^_[\w-]{5,}$/.test(c)) return true;
2110
+ if (/^[a-z0-9]{6,}$/i.test(c) && /\d/.test(c)) return true;
2111
+ return false;
2112
+ }
2113
+
2114
+ function buildSelectorSegment(el) {
2115
+ const tag = el.tagName.toLowerCase();
2116
+ let sel = tag;
2117
+
2118
+ if (el.classList && el.classList.length > 0) {
2119
+ const classes = [...el.classList]
2120
+ .filter(c => !c.startsWith('impeccable-') && !isLikelyHashedClass(c))
2121
+ .slice(0, 2);
2122
+ if (classes.length > 0) {
2123
+ sel += '.' + classes.map(c => CSS.escape(c)).join('.');
2124
+ }
2125
+ }
2126
+
2127
+ // Disambiguate among siblings only if the parent has multiple matches
2128
+ const parent = el.parentElement;
2129
+ if (parent) {
2130
+ try {
2131
+ const matching = parent.querySelectorAll(':scope > ' + sel);
2132
+ if (matching.length > 1) {
2133
+ const sameType = [...parent.children].filter(c => c.tagName === el.tagName);
2134
+ const idx = sameType.indexOf(el) + 1;
2135
+ sel += `:nth-of-type(${idx})`;
2136
+ }
2137
+ } catch {
2138
+ const idx = [...parent.children].indexOf(el) + 1;
2139
+ sel = `${tag}:nth-child(${idx})`;
2140
+ }
2141
+ }
2142
+ return sel;
2143
+ }
2144
+
2145
+ function generateSelector(el) {
2146
+ if (el === document.body) return 'body';
2147
+ if (el === document.documentElement) return 'html';
2148
+ if (el.id) return '#' + CSS.escape(el.id);
2149
+
2150
+ const parts = [];
2151
+ let current = el;
2152
+ let depth = 0;
2153
+ const MAX_DEPTH = 10;
2154
+
2155
+ while (current && current !== document.body && current !== document.documentElement && depth < MAX_DEPTH) {
2156
+ parts.unshift(buildSelectorSegment(current));
2157
+
2158
+ // Anchor on an ancestor's ID and stop walking up
2159
+ if (current.id) {
2160
+ parts[0] = '#' + CSS.escape(current.id);
2161
+ break;
2162
+ }
2163
+
2164
+ // Stop as soon as the partial selector uniquely identifies the target
2165
+ const trySelector = parts.join(' > ');
2166
+ try {
2167
+ const matches = document.querySelectorAll(trySelector);
2168
+ if (matches.length === 1 && matches[0] === el) {
2169
+ return trySelector;
2170
+ }
2171
+ } catch { /* invalid selector — keep walking */ }
2172
+
2173
+ current = current.parentElement;
2174
+ depth++;
2175
+ }
2176
+
2177
+ return parts.join(' > ');
2178
+ }
2179
+
2180
+ function isElementHidden(el) {
2181
+ if (!el || el === document.body || el === document.documentElement) return false;
2182
+ if (typeof el.checkVisibility === 'function') return !el.checkVisibility({ checkOpacity: false, checkVisibilityCSS: true });
2183
+ // Fallback: zero size or no offsetParent (covers display:none and detached subtrees)
2184
+ return el.offsetWidth === 0 && el.offsetHeight === 0;
2185
+ }
2186
+
2187
+ function serializeFindings(allFindings) {
2188
+ return allFindings.map(({ el, findings }) => ({
2189
+ selector: generateSelector(el),
2190
+ tagName: el.tagName?.toLowerCase() || 'unknown',
2191
+ rect: (el !== document.body && el !== document.documentElement && el.getBoundingClientRect)
2192
+ ? el.getBoundingClientRect().toJSON() : null,
2193
+ isPageLevel: el === document.body || el === document.documentElement,
2194
+ isHidden: isElementHidden(el),
2195
+ findings: findings.map(f => {
2196
+ const ap = ANTIPATTERNS.find(a => a.id === (f.type || f.id));
2197
+ return {
2198
+ type: f.type || f.id,
2199
+ category: ap ? ap.category : 'quality',
2200
+ detail: f.detail || f.snippet,
2201
+ name: ap ? ap.name : (f.type || f.id),
2202
+ description: ap ? ap.description : '',
2203
+ };
2204
+ }),
2205
+ }));
2206
+ }
2207
+
1468
2208
  const printSummary = function(allFindings) {
1469
2209
  if (allFindings.length === 0) {
1470
2210
  console.log('%c[impeccable] No anti-patterns found.', 'color: #22c55e; font-weight: bold');
@@ -1483,16 +2223,19 @@ if (IS_BROWSER) {
1483
2223
  console.groupEnd();
1484
2224
  };
1485
2225
 
2226
+ let firstScanDone = false;
1486
2227
  const scan = function() {
1487
2228
  for (const o of overlays) o.remove();
1488
2229
  overlays.length = 0;
1489
2230
  visibilityObserver.disconnect();
2231
+ overlayIndex = 0;
1490
2232
  const allFindings = [];
2233
+ const _disabled = EXTENSION_MODE ? (window.__IMPECCABLE_CONFIG__?.disabledRules || []) : [];
2234
+ const _ruleOk = (id) => !_disabled.length || !_disabled.includes(id);
1491
2235
 
1492
2236
  for (const el of document.querySelectorAll('*')) {
1493
- if (el.classList.contains('impeccable-overlay') ||
1494
- el.classList.contains('impeccable-label') ||
1495
- el.classList.contains('impeccable-tooltip')) continue;
2237
+ // Skip impeccable's own elements and any descendants (overlays, labels, banner, nav buttons)
2238
+ if (el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
1496
2239
  // Skip browser extension elements (Claude, etc.)
1497
2240
  const elId = el.id || '';
1498
2241
  if (elId.startsWith('claude-') || elId.startsWith('cic-')) continue;
@@ -1505,8 +2248,9 @@ if (IS_BROWSER) {
1505
2248
  ...checkElementMotionDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1506
2249
  ...checkElementGlowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1507
2250
  ...checkElementAIPaletteDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
2251
+ ...checkElementIconTileDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1508
2252
  ...checkElementQualityDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
1509
- ];
2253
+ ].filter(f => _ruleOk(f.type));
1510
2254
 
1511
2255
  if (findings.length > 0) {
1512
2256
  highlight(el, findings);
@@ -1516,13 +2260,13 @@ if (IS_BROWSER) {
1516
2260
 
1517
2261
  const pageLevelFindings = [];
1518
2262
 
1519
- const typoFindings = checkTypography();
2263
+ const typoFindings = checkTypography().filter(f => _ruleOk(f.type));
1520
2264
  if (typoFindings.length > 0) {
1521
2265
  pageLevelFindings.push(...typoFindings);
1522
2266
  allFindings.push({ el: document.body, findings: typoFindings });
1523
2267
  }
1524
2268
 
1525
- const layoutFindings = checkLayout();
2269
+ const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
1526
2270
  for (const f of layoutFindings) {
1527
2271
  const el = f.el || document.body;
1528
2272
  delete f.el;
@@ -1541,7 +2285,7 @@ if (IS_BROWSER) {
1541
2285
  }
1542
2286
 
1543
2287
  // Page-level quality checks (headings, etc.)
1544
- const qualityFindings = checkPageQualityDOM();
2288
+ const qualityFindings = checkPageQualityDOM().filter(f => _ruleOk(f.type));
1545
2289
  if (qualityFindings.length > 0) {
1546
2290
  pageLevelFindings.push(...qualityFindings);
1547
2291
  allFindings.push({ el: document.body, findings: qualityFindings });
@@ -1550,7 +2294,7 @@ if (IS_BROWSER) {
1550
2294
  // Regex-on-HTML checks (shared with Node)
1551
2295
  const htmlPatternFindings = checkHtmlPatterns(document.documentElement.outerHTML);
1552
2296
  if (htmlPatternFindings.length > 0) {
1553
- const mapped = htmlPatternFindings.map(f => ({ type: f.id, detail: f.snippet }));
2297
+ const mapped = htmlPatternFindings.map(f => ({ type: f.id, detail: f.snippet })).filter(f => _ruleOk(f.type));
1554
2298
  pageLevelFindings.push(...mapped);
1555
2299
  allFindings.push({ el: document.body, findings: mapped });
1556
2300
  }
@@ -1559,14 +2303,86 @@ if (IS_BROWSER) {
1559
2303
  showPageBanner(pageLevelFindings);
1560
2304
  }
1561
2305
 
1562
- printSummary(allFindings);
2306
+ if (!EXTENSION_MODE) printSummary(allFindings);
2307
+
2308
+ // In extension mode, post serialized results for the DevTools panel
2309
+ if (EXTENSION_MODE) {
2310
+ window.postMessage({
2311
+ source: 'impeccable-results',
2312
+ findings: serializeFindings(allFindings),
2313
+ count: allFindings.length,
2314
+ }, '*');
2315
+ }
2316
+
2317
+ // After this scan completes, all subsequent reveals are instant (no stagger, no animation)
2318
+ setTimeout(() => { firstScanDone = true; }, 1000);
2319
+
1563
2320
  return allFindings;
1564
2321
  };
1565
2322
 
1566
- if (document.readyState === 'loading') {
1567
- document.addEventListener('DOMContentLoaded', () => setTimeout(scan, 100));
2323
+ if (EXTENSION_MODE) {
2324
+ // Extension mode: listen for commands, don't auto-scan
2325
+ window.addEventListener('message', (e) => {
2326
+ if (e.source !== window || !e.data || e.data.source !== 'impeccable-command') return;
2327
+ if (e.data.action === 'scan') {
2328
+ if (e.data.config) window.__IMPECCABLE_CONFIG__ = e.data.config;
2329
+ scan();
2330
+ }
2331
+ if (e.data.action === 'toggle-overlays') {
2332
+ const visible = !document.body.classList.contains('impeccable-hidden');
2333
+ document.body.classList.toggle('impeccable-hidden', visible);
2334
+ window.postMessage({ source: 'impeccable-overlays-toggled', visible: !visible }, '*');
2335
+ }
2336
+ if (e.data.action === 'remove') {
2337
+ for (const o of overlays) o.remove();
2338
+ overlays.length = 0;
2339
+ visibilityObserver.disconnect();
2340
+ styleEl.remove();
2341
+ if (spotlightBackdrop) { spotlightBackdrop.remove(); spotlightBackdrop = null; }
2342
+ document.body.classList.remove('impeccable-hidden');
2343
+ }
2344
+ if (e.data.action === 'highlight') {
2345
+ if (spotlightTimer) { clearTimeout(spotlightTimer); spotlightTimer = null; }
2346
+ try {
2347
+ const target = e.data.selector ? document.querySelector(e.data.selector) : null;
2348
+ if (target) {
2349
+ // Scroll first so positionOverlay reads the post-scroll rect
2350
+ if (!isInViewport(target) && target.scrollIntoView) {
2351
+ target.scrollIntoView({ behavior: 'instant', block: 'center' });
2352
+ }
2353
+ for (const o of overlays) {
2354
+ if (o.classList.contains('impeccable-banner')) continue;
2355
+ const isMatch = o._targetEl === target;
2356
+ o.classList.toggle('impeccable-spotlight', isMatch);
2357
+ o.classList.toggle('impeccable-spotlight-dimmed', !isMatch);
2358
+ if (isMatch) {
2359
+ // Force the matching overlay visible immediately, don't wait for IntersectionObserver
2360
+ o.style.display = '';
2361
+ o.style.animation = 'none';
2362
+ o.classList.add('impeccable-visible');
2363
+ o._revealed = true;
2364
+ positionOverlay(o);
2365
+ }
2366
+ }
2367
+ showSpotlight(target);
2368
+ }
2369
+ } catch { /* invalid selector */ }
2370
+ }
2371
+ if (e.data.action === 'unhighlight') {
2372
+ hideSpotlight();
2373
+ for (const o of overlays) {
2374
+ o.classList.remove('impeccable-spotlight');
2375
+ o.classList.remove('impeccable-spotlight-dimmed');
2376
+ }
2377
+ }
2378
+ });
2379
+ window.postMessage({ source: 'impeccable-ready' }, '*');
1568
2380
  } else {
1569
- setTimeout(scan, 100);
2381
+ if (document.readyState === 'loading') {
2382
+ document.addEventListener('DOMContentLoaded', () => setTimeout(scan, 100));
2383
+ } else {
2384
+ setTimeout(scan, 100);
2385
+ }
1570
2386
  }
1571
2387
 
1572
2388
  window.impeccableScan = scan;
@@ -1590,6 +2406,178 @@ function isFullPage(content) {
1590
2406
  return /<!doctype\s|<html[\s>]|<head[\s>]/i.test(stripped);
1591
2407
  }
1592
2408
 
2409
+ // ---------------------------------------------------------------------------
2410
+ // jsdom CSS-variable border override map
2411
+ // ---------------------------------------------------------------------------
2412
+ //
2413
+ // jsdom's CSSOM silently drops any border shorthand that contains a var()
2414
+ // reference — the computed style for the element then shows empty width,
2415
+ // empty style, and a default black color. That's enough to hide the most
2416
+ // common real-world side-tab pattern in AI-generated pages:
2417
+ //
2418
+ // :root { --brand: #87a8ff; }
2419
+ // .card { border-left: 5px solid var(--brand); border-radius: 4px; }
2420
+ //
2421
+ // Real browsers (and therefore the browser detector path) resolve var()
2422
+ // natively, so this only affects the Node jsdom path.
2423
+ //
2424
+ // This pre-pass walks the stylesheets, finds any rule whose per-side or
2425
+ // all-sides border property contains var(), resolves the var() against
2426
+ // :root-level custom properties (read from the documentElement's computed
2427
+ // style, which jsdom DOES handle correctly), and attaches the resolved
2428
+ // width+color to every element that matches the rule's selector. The
2429
+ // Node-side `checkElementBorders` adapter consumes that map as a fallback
2430
+ // whenever jsdom's computed style came back empty.
2431
+ //
2432
+ // Limitations (intentional, to keep the pass simple):
2433
+ // * Only :root-level custom properties are resolved. Scoped overrides on
2434
+ // descendants are not tracked — uncommon in practice and would require
2435
+ // a per-element cascade walk.
2436
+ // * @media / @supports wrapped rules are ignored (jsdom often mishandles
2437
+ // these anyway).
2438
+ // * The fallback only fills sides that jsdom left empty, so any rule
2439
+ // whose border parses normally still wins via the computed style.
2440
+
2441
+ const BORDER_SHORTHAND_RE = /^(\d+(?:\.\d+)?)px\s+(solid|dashed|dotted|double|groove|ridge|inset|outset)\s+(.+)$/i;
2442
+
2443
+ // isNeutralColor only understands rgba()/oklch()/lch()/lab()/hsl()/hwb().
2444
+ // CSS variables typically hold hex or named colors, so normalize those to
2445
+ // rgb() before handing the value off to the shared check. Anything we don't
2446
+ // recognise is passed through unchanged — isNeutralColor then treats it as
2447
+ // non-neutral, which is the safer default (matches the oklch-era bugfix).
2448
+ const NAMED_COLORS = {
2449
+ white: [255, 255, 255], black: [0, 0, 0], gray: [128, 128, 128],
2450
+ grey: [128, 128, 128], silver: [192, 192, 192], red: [255, 0, 0],
2451
+ green: [0, 128, 0], blue: [0, 0, 255], yellow: [255, 255, 0],
2452
+ };
2453
+
2454
+ function normalizeColorForCheck(value) {
2455
+ if (!value) return value;
2456
+ const v = value.trim();
2457
+ const hex6 = v.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
2458
+ if (hex6) {
2459
+ const [r, g, b] = [parseInt(hex6[1], 16), parseInt(hex6[2], 16), parseInt(hex6[3], 16)];
2460
+ return `rgb(${r}, ${g}, ${b})`;
2461
+ }
2462
+ const hex3 = v.match(/^#([0-9a-f])([0-9a-f])([0-9a-f])$/i);
2463
+ if (hex3) {
2464
+ const [r, g, b] = [
2465
+ parseInt(hex3[1] + hex3[1], 16),
2466
+ parseInt(hex3[2] + hex3[2], 16),
2467
+ parseInt(hex3[3] + hex3[3], 16),
2468
+ ];
2469
+ return `rgb(${r}, ${g}, ${b})`;
2470
+ }
2471
+ const named = NAMED_COLORS[v.toLowerCase()];
2472
+ if (named) return `rgb(${named[0]}, ${named[1]}, ${named[2]})`;
2473
+ return v;
2474
+ }
2475
+
2476
+ function buildBorderOverrideMap(document, window) {
2477
+ const map = new Map();
2478
+ const rootStyle = window.getComputedStyle(document.documentElement);
2479
+
2480
+ function resolveVar(value, depth = 0) {
2481
+ if (!value || depth > 10 || !value.includes('var(')) return value;
2482
+ return value.replace(
2483
+ /var\(\s*(--[\w-]+)\s*(?:,\s*([^)]+))?\s*\)/g,
2484
+ (_, name, fallback) => {
2485
+ const v = rootStyle.getPropertyValue(name).trim();
2486
+ if (v) return resolveVar(v, depth + 1);
2487
+ if (fallback) return resolveVar(fallback.trim(), depth + 1);
2488
+ return '';
2489
+ }
2490
+ );
2491
+ }
2492
+
2493
+ function parseShorthand(text) {
2494
+ const m = text.trim().match(BORDER_SHORTHAND_RE);
2495
+ if (!m) return null;
2496
+ return { width: parseFloat(m[1]), color: normalizeColorForCheck(m[3]) };
2497
+ }
2498
+
2499
+ // Read from the per-property accessors on rule.style. jsdom preserves
2500
+ // each border-* shorthand it parsed, even when the overall cssText has
2501
+ // been truncated (e.g. a `border: 1px solid var(...)` followed by a
2502
+ // `border-left: ...` loses the first declaration but keeps the second).
2503
+ const SIDE_PROPS = [
2504
+ ['borderLeft', 'Left'],
2505
+ ['borderRight', 'Right'],
2506
+ ['borderTop', 'Top'],
2507
+ ['borderBottom', 'Bottom'],
2508
+ ['borderInlineStart', 'Left'],
2509
+ ['borderInlineEnd', 'Right'],
2510
+ ];
2511
+
2512
+ for (const sheet of document.styleSheets) {
2513
+ let rules;
2514
+ try { rules = sheet.cssRules || []; } catch { continue; }
2515
+ for (const rule of rules) {
2516
+ // CSSStyleRule only; skip @media / @keyframes / @supports wrappers.
2517
+ if (rule.type !== 1 || !rule.style || !rule.selectorText) continue;
2518
+
2519
+ const perSide = {};
2520
+
2521
+ for (const [prop, side] of SIDE_PROPS) {
2522
+ const val = rule.style[prop];
2523
+ if (!val || !val.includes('var(')) continue;
2524
+ const parsed = parseShorthand(resolveVar(val));
2525
+ if (parsed && parsed.color) perSide[side] = parsed;
2526
+ }
2527
+
2528
+ // Uniform `border: <w> <style> var(...)` applies to every side the
2529
+ // per-side map didn't already claim.
2530
+ const borderAll = rule.style.border;
2531
+ if (borderAll && borderAll.includes('var(')) {
2532
+ const parsed = parseShorthand(resolveVar(borderAll));
2533
+ if (parsed && parsed.color) {
2534
+ for (const s of ['Top', 'Right', 'Bottom', 'Left']) {
2535
+ if (!perSide[s]) perSide[s] = parsed;
2536
+ }
2537
+ }
2538
+ }
2539
+
2540
+ // Longhand `border-*-color: var(...)` with width/style in separate
2541
+ // declarations. Rare in AI-generated pages, but cheap to cover.
2542
+ for (const [prop, side] of [
2543
+ ['borderLeftColor', 'Left'],
2544
+ ['borderRightColor', 'Right'],
2545
+ ['borderTopColor', 'Top'],
2546
+ ['borderBottomColor', 'Bottom'],
2547
+ ]) {
2548
+ const val = rule.style[prop];
2549
+ if (!val || !val.includes('var(')) continue;
2550
+ const resolved = resolveVar(val).trim();
2551
+ if (!resolved) continue;
2552
+ // Width may or may not come from this rule — that's fine; the
2553
+ // adapter only substitutes the color when jsdom left it as a
2554
+ // literal var() string.
2555
+ if (!perSide[side]) perSide[side] = { width: 0, color: normalizeColorForCheck(resolved) };
2556
+ }
2557
+
2558
+ if (Object.keys(perSide).length === 0) continue;
2559
+
2560
+ let matched;
2561
+ try { matched = document.querySelectorAll(rule.selectorText); }
2562
+ catch { continue; }
2563
+
2564
+ for (const el of matched) {
2565
+ const existing = map.get(el);
2566
+ if (existing) {
2567
+ // Later rules overwrite earlier ones — approximates source-order
2568
+ // cascade for equal-specificity rules and is good enough for the
2569
+ // uncontested var()-dropped sides we're trying to recover.
2570
+ Object.assign(existing, perSide);
2571
+ } else {
2572
+ map.set(el, { ...perSide });
2573
+ }
2574
+ }
2575
+ }
2576
+ }
2577
+
2578
+ return map;
2579
+ }
2580
+
1593
2581
  // ---------------------------------------------------------------------------
1594
2582
  // jsdom detection (default for HTML files)
1595
2583
  // ---------------------------------------------------------------------------
@@ -1634,11 +2622,16 @@ async function detectHtml(filePath) {
1634
2622
 
1635
2623
  const findings = [];
1636
2624
 
2625
+ // Pre-pass: recover border declarations that jsdom dropped because they
2626
+ // contained a var() reference. The map is keyed by element and consulted
2627
+ // by the border check adapter as a fallback.
2628
+ const borderOverrides = buildBorderOverrideMap(document, window);
2629
+
1637
2630
  // Element-level checks (borders + colors + motion)
1638
2631
  for (const el of document.querySelectorAll('*')) {
1639
2632
  const tag = el.tagName.toLowerCase();
1640
2633
  const style = window.getComputedStyle(el);
1641
- for (const f of checkElementBorders(tag, style)) {
2634
+ for (const f of checkElementBorders(tag, style, borderOverrides.get(el))) {
1642
2635
  findings.push(finding(f.id, filePath, f.snippet));
1643
2636
  }
1644
2637
  for (const f of checkElementColors(el, style, tag, window)) {
@@ -1650,6 +2643,12 @@ async function detectHtml(filePath) {
1650
2643
  for (const f of checkElementMotion(tag, style)) {
1651
2644
  findings.push(finding(f.id, filePath, f.snippet));
1652
2645
  }
2646
+ for (const f of checkElementIconTile(el, tag, window)) {
2647
+ findings.push(finding(f.id, filePath, f.snippet));
2648
+ }
2649
+ for (const f of checkElementQuality(el, style, tag, window)) {
2650
+ findings.push(finding(f.id, filePath, f.snippet));
2651
+ }
1653
2652
  }
1654
2653
 
1655
2654
  // Page-level checks (only for full pages, not partials)
@@ -1660,6 +2659,9 @@ async function detectHtml(filePath) {
1660
2659
  for (const f of checkPageLayout(document, window)) {
1661
2660
  findings.push(finding(f.id, filePath, f.snippet));
1662
2661
  }
2662
+ for (const f of checkPageQualityFromDoc(document)) {
2663
+ findings.push(finding(f.id, filePath, f.snippet));
2664
+ }
1663
2665
  for (const f of checkHtmlPatterns(html)) {
1664
2666
  findings.push(finding(f.id, filePath, f.snippet));
1665
2667
  }
@@ -1693,7 +2695,11 @@ async function detectUrl(url) {
1693
2695
  throw new Error(`Browser script not found at ${browserScriptPath}`);
1694
2696
  }
1695
2697
 
1696
- const browser = await puppeteer.default.launch({ headless: true });
2698
+ // CI runners (GitHub Actions Ubuntu) block unprivileged user namespaces, so
2699
+ // Chrome can't initialize its sandbox there. Disable the sandbox only when
2700
+ // running in CI; local users keep the default hardened launch.
2701
+ const launchArgs = process.env.CI ? ['--no-sandbox', '--disable-setuid-sandbox'] : [];
2702
+ const browser = await puppeteer.default.launch({ headless: true, args: launchArgs });
1697
2703
  const page = await browser.newPage();
1698
2704
  await page.setViewport({ width: 1280, height: 800 });
1699
2705
  await page.goto(url, { waitUntil: 'networkidle0', timeout: 30000 });
@@ -2460,7 +3466,7 @@ async function liveCli() {
2460
3466
  const requestedPort = portArg ? parseInt(portArg.split('=')[1], 10) : null;
2461
3467
 
2462
3468
  if (helpMode) {
2463
- console.log(`Usage: impeccable-detect live [options]
3469
+ console.log(`Usage: impeccable live [options]
2464
3470
 
2465
3471
  Start a local server that serves the browser detection overlay script.
2466
3472
  Inject the script into any page to scan for anti-patterns in real time.