impeccable 3.3.0 → 3.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +2 -2
- package/README.npm.md +2 -2
- package/README.repo.md +3 -3
- package/cli/bin/commands/skills.mjs +221 -28
- package/cli/engine/browser/injected/index.mjs +27 -4
- package/cli/engine/cli/main.mjs +113 -19
- package/cli/engine/design-system.mjs +62 -0
- package/cli/engine/detect-antipatterns-browser.js +458 -53
- package/cli/engine/engines/regex/detect-text.mjs +44 -8
- package/cli/engine/engines/static-html/css-cascade.mjs +23 -11
- package/cli/engine/engines/static-html/detect-html.mjs +4 -2
- package/cli/engine/findings.mjs +7 -1
- package/cli/engine/node/file-system.mjs +16 -2
- package/cli/engine/registry/antipatterns.mjs +41 -6
- package/cli/engine/rules/checks.mjs +408 -48
- package/cli/engine/shared/constants.mjs +11 -0
- package/cli/lib/impeccable-config.mjs +9 -1
- package/package.json +3 -2
|
@@ -82,6 +82,15 @@ const GENERIC_FONTS = new Set([
|
|
|
82
82
|
const WCAG_LARGE_TEXT_PX = 18 * (96 / 72);
|
|
83
83
|
const WCAG_LARGE_BOLD_TEXT_PX = 14 * (96 / 72);
|
|
84
84
|
|
|
85
|
+
// Em-dash overuse (advisory) thresholds, shared by the regex/static-HTML
|
|
86
|
+
// analyzer and the browser DOM check so both fire on the same saturation
|
|
87
|
+
// pattern. Two gates must hold: an absolute floor of EM_DASH_FLOOR dashes, and
|
|
88
|
+
// a density of at least one dash per EM_DASH_CHARS_PER_DASH characters of body
|
|
89
|
+
// text. A long article that uses a few em-dashes is left alone; a short,
|
|
90
|
+
// dash-per-clause page is not.
|
|
91
|
+
const EM_DASH_FLOOR = 8;
|
|
92
|
+
const EM_DASH_CHARS_PER_DASH = 500;
|
|
93
|
+
|
|
85
94
|
// Serif faces that show up in italic-display heroes. The rule also fires when
|
|
86
95
|
// the primary face is unknown but the stack ends in the generic `serif` token,
|
|
87
96
|
// which catches custom/private faces with a serif fallback.
|
|
@@ -251,6 +260,15 @@ const ANTIPATTERNS = [
|
|
|
251
260
|
skillSection: 'Color & Contrast',
|
|
252
261
|
skillGuideline: 'dark mode with glowing accents',
|
|
253
262
|
},
|
|
263
|
+
{
|
|
264
|
+
id: 'radial-spotlight-glow',
|
|
265
|
+
category: 'slop',
|
|
266
|
+
name: 'Decorative radial spotlight glow',
|
|
267
|
+
description:
|
|
268
|
+
'A soft, low-opacity accent-colored radial gradient fading to transparent, dropped behind a hero or section as a "spotlight." It is a reflex AI decoration — the translucent cousin of the saturated radial halo. Let the surface stand on its own, or light the composition with a deliberate material accent rather than a floating colored haze.',
|
|
269
|
+
skillSection: 'Color & Contrast',
|
|
270
|
+
skillGuideline: 'dark mode with glowing accents',
|
|
271
|
+
},
|
|
254
272
|
{
|
|
255
273
|
id: 'marquee',
|
|
256
274
|
category: 'slop',
|
|
@@ -291,15 +309,14 @@ const ANTIPATTERNS = [
|
|
|
291
309
|
skillGuideline: 'tiny uppercase tracked label above the hero headline',
|
|
292
310
|
},
|
|
293
311
|
{
|
|
294
|
-
id: '
|
|
312
|
+
id: 'kicker-above-heading',
|
|
295
313
|
category: 'slop',
|
|
296
314
|
scopes: ['type'],
|
|
297
|
-
|
|
298
|
-
name: 'Repeated section kicker labels',
|
|
315
|
+
name: 'Kicker / eyebrow label above heading',
|
|
299
316
|
description:
|
|
300
|
-
'
|
|
317
|
+
'A tiny tracked uppercase or small-caps label sitting as its own block directly above a heading is banned outright, repeated or not. Generated kickers never earn their place: the heading carries its own weight. Delete the label and let the heading speak; if the words matter, work them into the heading or the body.',
|
|
301
318
|
skillSection: 'Typography',
|
|
302
|
-
skillGuideline: '
|
|
319
|
+
skillGuideline: 'kicker or eyebrow labels above headings',
|
|
303
320
|
},
|
|
304
321
|
{
|
|
305
322
|
id: 'numbered-section-labels',
|
|
@@ -315,9 +332,14 @@ const ANTIPATTERNS = [
|
|
|
315
332
|
{
|
|
316
333
|
id: 'em-dash-overuse',
|
|
317
334
|
category: 'slop',
|
|
335
|
+
// Advisory: humans use em-dashes legitimately, so this rule is opt-in noise
|
|
336
|
+
// rather than a failure. It fires only on the AI saturation pattern, not on
|
|
337
|
+
// ordinary prose. Advisory findings are surfaced separately, never counted
|
|
338
|
+
// as failures, and skipped by the design hook unless a project opts in.
|
|
339
|
+
advisory: true,
|
|
318
340
|
name: 'Em-dash overuse',
|
|
319
341
|
description:
|
|
320
|
-
'
|
|
342
|
+
'Em-dash saturation in body copy is an AI cadence tell. Advisory only: humans use em-dashes legitimately, so this fires only on saturation — at least 8 em-dashes (— or --) at a density near one per 500 characters of body text — never on a long article that uses a few. Prefer commas, colons, periods, or parentheses.',
|
|
321
343
|
skillSection: 'Copy',
|
|
322
344
|
skillGuideline: 'no em dashes',
|
|
323
345
|
},
|
|
@@ -507,6 +529,14 @@ const ANTIPATTERNS = [
|
|
|
507
529
|
description:
|
|
508
530
|
'Body text below 12px is hard to read, especially on high-DPI screens. Use at least 14px for body content, 16px is ideal.',
|
|
509
531
|
},
|
|
532
|
+
{
|
|
533
|
+
id: 'undersized-ui-text',
|
|
534
|
+
category: 'quality',
|
|
535
|
+
scopes: ['type'],
|
|
536
|
+
name: 'Undersized functional text',
|
|
537
|
+
description:
|
|
538
|
+
'Interactive and content-bearing UI text (links, buttons, nav items, labels, table cells, meta rows, timecodes) below 11px is a legibility failure, not a style choice. WCAG sets no absolute pixel floor, but functional text under 11px is a defensible quality bar: it fails on high-DPI and small viewports and it degrades tap and read targets. The 11px floor holds even inside a footer; only non-interactive legal smallprint gets the softer 10px floor. Being ON the DESIGN.md size ramp does not exempt a value here: adding 8px to the ramp launders the token but not the legibility problem, and that is exactly the escape hatch this rule closes. Exempts sup/sub, visually-hidden (sr-only) text, and code/terminal contexts. Decorative letterspaced micro-labels are still functional and stay in scope.',
|
|
539
|
+
},
|
|
510
540
|
{
|
|
511
541
|
id: 'all-caps-body',
|
|
512
542
|
category: 'quality',
|
|
@@ -880,9 +910,21 @@ function checkColors(opts) {
|
|
|
880
910
|
const findings = [];
|
|
881
911
|
|
|
882
912
|
if (hasDirectText && textColor && !isEmojiOnly) {
|
|
913
|
+
// Gradient-clipped text (`background-clip: text`, typically with a
|
|
914
|
+
// transparent text-fill) paints its glyphs *with* the element's own
|
|
915
|
+
// gradient. The `color` value the cascade still reports is never painted,
|
|
916
|
+
// and the gradient is the fill, not a backdrop — so measuring `color`
|
|
917
|
+
// against that gradient (which resolveGradientStops picks up as the
|
|
918
|
+
// element's own background-image) is a guaranteed false positive
|
|
919
|
+
// (issue #409 Case A). Skip the backdrop-contrast checks; the gradient-text
|
|
920
|
+
// rule below still flags the pattern itself. Skipping a rule beats a false
|
|
921
|
+
// positive here — the true painted contrast can't be measured from `color`.
|
|
922
|
+
const isGradientClippedText = bgClip === 'text';
|
|
883
923
|
// Run background-dependent checks against either a solid bg or, if the
|
|
884
924
|
// ancestor is a gradient, against every gradient stop (use the worst case).
|
|
885
|
-
const bgs =
|
|
925
|
+
const bgs = isGradientClippedText
|
|
926
|
+
? null
|
|
927
|
+
: (effectiveBg ? [effectiveBg] : (effectiveBgStops && effectiveBgStops.length ? effectiveBgStops : null));
|
|
886
928
|
if (bgs) {
|
|
887
929
|
// Gray on colored background — flag if every stop is chromatic
|
|
888
930
|
const textLum = relativeLuminance(textColor);
|
|
@@ -1215,12 +1257,15 @@ function checkHeroEyebrow(opts) {
|
|
|
1215
1257
|
}];
|
|
1216
1258
|
}
|
|
1217
1259
|
|
|
1218
|
-
|
|
1219
|
-
|
|
1220
|
-
|
|
1260
|
+
// Outright ban: one kicker is one too many, so every collected candidate is
|
|
1261
|
+
// a finding. The judgment lives in the candidate gate (isKickerCandidate) and
|
|
1262
|
+
// the collector's context skips, not in a repetition count.
|
|
1263
|
+
function checkKickerAboveHeading(opts) {
|
|
1264
|
+
const { candidates } = opts;
|
|
1265
|
+
if (!Array.isArray(candidates)) return [];
|
|
1221
1266
|
return candidates.map(candidate => ({
|
|
1222
|
-
id: '
|
|
1223
|
-
snippet: `
|
|
1267
|
+
id: 'kicker-above-heading',
|
|
1268
|
+
snippet: `kicker "${candidate.kickerText}" above ${candidate.headingTag} "${candidate.headingText}"`,
|
|
1224
1269
|
}));
|
|
1225
1270
|
}
|
|
1226
1271
|
|
|
@@ -1582,7 +1627,13 @@ function isZeroOffset(value) {
|
|
|
1582
1627
|
// never see it — pseudo-elements aren't part of the DOM the cascade walks —
|
|
1583
1628
|
// so this scans stylesheet text directly, mirroring the border rule's
|
|
1584
1629
|
// gates: >= 3px thick, chromatic fill, full height against a side edge.
|
|
1585
|
-
function scanCssTextForPseudoStripe(
|
|
1630
|
+
function scanCssTextForPseudoStripe(rawContent) {
|
|
1631
|
+
// Blank comment bodies byte-for-byte so commented-out rules are not
|
|
1632
|
+
// scanned as live CSS and every rule keeps its source offset (each
|
|
1633
|
+
// finding carries `index` so line-based callers can attribute it and
|
|
1634
|
+
// line-scoped inline ignores can match).
|
|
1635
|
+
const content = String(rawContent || '').replace(/\/\*[\s\S]*?\*\//g,
|
|
1636
|
+
(block) => block.replace(/[^\n]/g, ' '));
|
|
1586
1637
|
const customProps = collectCssCustomProps(content);
|
|
1587
1638
|
const findings = [];
|
|
1588
1639
|
const seen = new Set();
|
|
@@ -1691,9 +1742,13 @@ function scanCssTextForPseudoStripe(content) {
|
|
|
1691
1742
|
|
|
1692
1743
|
if (seen.has(selector)) continue;
|
|
1693
1744
|
seen.add(selector);
|
|
1745
|
+
// The selector group absorbs whitespace trailing the previous rule;
|
|
1746
|
+
// advance past it so `index` points at the selector itself.
|
|
1747
|
+
const selectorStart = m.index + (m[1].length - m[1].trimStart().length);
|
|
1694
1748
|
findings.push({
|
|
1695
1749
|
id: 'side-tab',
|
|
1696
1750
|
snippet: `${selector} — absolute ${thicknessPx}px pseudo-element stripe (${edge}: 0)`,
|
|
1751
|
+
index: selectorStart,
|
|
1697
1752
|
});
|
|
1698
1753
|
}
|
|
1699
1754
|
return findings;
|
|
@@ -2440,29 +2495,54 @@ function resolveBackground(el, win, customPropMap) {
|
|
|
2440
2495
|
// Walk parents looking for a gradient background and return its color stops.
|
|
2441
2496
|
// Used as a fallback when resolveBackground() returns null because the
|
|
2442
2497
|
// effective background is a gradient (no single solid color to compare against).
|
|
2443
|
-
function resolveGradientStops(el, win) {
|
|
2498
|
+
function resolveGradientStops(el, win, customPropMap) {
|
|
2444
2499
|
let current = el;
|
|
2445
2500
|
while (current && current.nodeType === 1) {
|
|
2446
2501
|
const style = DETECTOR_IS_BROWSER ? getComputedStyle(current) : win.getComputedStyle(current);
|
|
2447
2502
|
const bgImage = style.backgroundImage || '';
|
|
2503
|
+
let stops = null;
|
|
2448
2504
|
if (bgImage && bgImage !== 'none' && /gradient/i.test(bgImage)) {
|
|
2449
|
-
const
|
|
2450
|
-
if (
|
|
2505
|
+
const parsed = parseGradientColors(bgImage);
|
|
2506
|
+
if (parsed.length > 0) stops = parsed;
|
|
2451
2507
|
}
|
|
2452
|
-
if (!DETECTOR_IS_BROWSER) {
|
|
2508
|
+
if (!stops && !DETECTOR_IS_BROWSER) {
|
|
2453
2509
|
// jsdom doesn't decompose `background:` shorthand — peek at the raw inline style
|
|
2454
2510
|
const rawStyle = current.getAttribute?.('style') || '';
|
|
2455
2511
|
const bgMatch = rawStyle.match(/background(?:-image)?\s*:\s*([^;]+)/i);
|
|
2456
2512
|
if (bgMatch && /gradient/i.test(bgMatch[1])) {
|
|
2457
|
-
const
|
|
2458
|
-
if (
|
|
2513
|
+
const parsed = parseGradientColors(bgMatch[1]);
|
|
2514
|
+
if (parsed.length > 0) stops = parsed;
|
|
2459
2515
|
}
|
|
2460
2516
|
}
|
|
2517
|
+
if (stops) return compositeGradientStops(stops, current, win, customPropMap);
|
|
2461
2518
|
current = current.parentElement;
|
|
2462
2519
|
}
|
|
2463
2520
|
return null;
|
|
2464
2521
|
}
|
|
2465
2522
|
|
|
2523
|
+
// A translucent gradient stop (e.g. a faint `rgba(52,192,168,0.09)` accent
|
|
2524
|
+
// glow) paints over whatever surface sits beneath the gradient — the browser
|
|
2525
|
+
// composites it, so its effective color is far closer to the base than to the
|
|
2526
|
+
// full-opacity accent. Treating the stop as opaque flags every text child of a
|
|
2527
|
+
// softly-glowing section as low-contrast (issue #409 Case B). Composite each
|
|
2528
|
+
// alpha stop over the resolved surface beneath the gradient element. When that
|
|
2529
|
+
// surface isn't resolvable (another gradient above, no opaque ancestor), drop
|
|
2530
|
+
// the translucent stop rather than guess: a dropped stop can't manufacture a
|
|
2531
|
+
// false finding, and skipping beats a wrong ratio.
|
|
2532
|
+
function compositeGradientStops(stops, gradientEl, win, customPropMap) {
|
|
2533
|
+
const hasAlpha = stops.some(s => (s.a ?? 1) < 0.99);
|
|
2534
|
+
if (!hasAlpha) return stops;
|
|
2535
|
+
const base = resolveBackground(gradientEl.parentElement || gradientEl, win, customPropMap);
|
|
2536
|
+
const out = [];
|
|
2537
|
+
for (const s of stops) {
|
|
2538
|
+
const a = s.a ?? 1;
|
|
2539
|
+
if (a >= 0.99) { out.push(s); continue; }
|
|
2540
|
+
if (base) out.push(compositeColorOver(s, base));
|
|
2541
|
+
// else: unresolvable base — drop the translucent stop (skip, don't guess).
|
|
2542
|
+
}
|
|
2543
|
+
return out.length ? out : null;
|
|
2544
|
+
}
|
|
2545
|
+
|
|
2466
2546
|
// Parse a single CSS length token to pixels. Accepts "12px", "50%", a
|
|
2467
2547
|
// shorthand like "12px 4px" (uses the first value), or empty / null.
|
|
2468
2548
|
// Returns the pixel value, or null when the input is unparseable.
|
|
@@ -3112,7 +3192,7 @@ function parseColorResolved(str, customPropMap) {
|
|
|
3112
3192
|
return parseAnyColor(resolved);
|
|
3113
3193
|
}
|
|
3114
3194
|
|
|
3115
|
-
const
|
|
3195
|
+
const KICKER_SKIP_SELECTOR = [
|
|
3116
3196
|
'nav',
|
|
3117
3197
|
'form',
|
|
3118
3198
|
'table',
|
|
@@ -3131,7 +3211,7 @@ const REPEATED_KICKER_SKIP_SELECTOR = [
|
|
|
3131
3211
|
'[data-impeccable-allow-kickers]',
|
|
3132
3212
|
].join(',');
|
|
3133
3213
|
|
|
3134
|
-
const
|
|
3214
|
+
const KICKER_CARD_CONTEXT_SELECTOR = [
|
|
3135
3215
|
'article',
|
|
3136
3216
|
'button',
|
|
3137
3217
|
'a',
|
|
@@ -3149,23 +3229,32 @@ function cleanInlineText(el) {
|
|
|
3149
3229
|
.trim();
|
|
3150
3230
|
}
|
|
3151
3231
|
|
|
3152
|
-
function
|
|
3153
|
-
const item = heading.closest?.(
|
|
3232
|
+
function isKickerCardContext(heading, kicker) {
|
|
3233
|
+
const item = heading.closest?.(KICKER_CARD_CONTEXT_SELECTOR);
|
|
3154
3234
|
return Boolean(item && (!item.contains || item.contains(kicker)));
|
|
3155
3235
|
}
|
|
3156
3236
|
|
|
3157
|
-
|
|
3237
|
+
// Meta lines above headlines join category and date (or path crumbs) with
|
|
3238
|
+
// separator glyphs, or carry a year. A kicker is one short phrase; metadata
|
|
3239
|
+
// keeps its markers.
|
|
3240
|
+
const KICKER_META_TEXT_RE = /[·•|]|\s[\/›»>]\s|\b(19|20)\d{2}\b/;
|
|
3241
|
+
// Legal and document numbering: "Section 4.2", "Article IX", "§ 12.3",
|
|
3242
|
+
// dotted decimal outlines. The label identifies the clause, so it stays.
|
|
3243
|
+
const KICKER_DOC_NUMBERING_RE = /^(§|\d+(\.\d+)+\b|(section|article|clause|appendix|exhibit|schedule|chapter|part|rule|title)\s+([\divxlc]+\b|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve)\b)/i;
|
|
3244
|
+
|
|
3245
|
+
function isKickerCandidate(opts) {
|
|
3158
3246
|
const {
|
|
3159
|
-
|
|
3247
|
+
headingLevel,
|
|
3160
3248
|
headingText,
|
|
3161
3249
|
headingFontSize,
|
|
3162
3250
|
kickerTag,
|
|
3163
3251
|
kickerText,
|
|
3164
3252
|
kickerTextTransform,
|
|
3253
|
+
kickerFontVariant,
|
|
3165
3254
|
kickerFontSize,
|
|
3166
3255
|
kickerLetterSpacing,
|
|
3167
3256
|
} = opts;
|
|
3168
|
-
if (!
|
|
3257
|
+
if (!headingLevel || headingLevel > 4) return false;
|
|
3169
3258
|
if (!headingText || headingText.length < 3) return false;
|
|
3170
3259
|
if (/^\/[\w-]+/i.test(headingText.replace(/^"|"$/g, '').trim())) return false;
|
|
3171
3260
|
if (!(headingFontSize >= 20)) return false;
|
|
@@ -3173,9 +3262,13 @@ function isRepeatedKickerCandidate(opts) {
|
|
|
3173
3262
|
if (!['p', 'span', 'div', 'small'].includes(kickerTag)) return false;
|
|
3174
3263
|
if (!kickerText || kickerText.length < 2 || kickerText.length > 34) return false;
|
|
3175
3264
|
if (/^step\s*\d+/i.test(kickerText) || /^\d{1,2}$/.test(kickerText)) return false;
|
|
3265
|
+
if (KICKER_META_TEXT_RE.test(kickerText)) return false;
|
|
3266
|
+
if (KICKER_DOC_NUMBERING_RE.test(kickerText)) return false;
|
|
3176
3267
|
|
|
3268
|
+
const isSmallCaps = /small-caps/.test(kickerFontVariant || '');
|
|
3177
3269
|
const isUppercased = kickerTextTransform === 'uppercase'
|
|
3178
|
-
|| (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText))
|
|
3270
|
+
|| (/[A-Z]/.test(kickerText) && !/[a-z]/.test(kickerText))
|
|
3271
|
+
|| isSmallCaps;
|
|
3179
3272
|
if (!isUppercased) return false;
|
|
3180
3273
|
if (!(kickerFontSize > 0 && kickerFontSize <= 14)) return false;
|
|
3181
3274
|
const minTrackedSpacing = Math.max(1, kickerFontSize * 0.08);
|
|
@@ -3183,37 +3276,64 @@ function isRepeatedKickerCandidate(opts) {
|
|
|
3183
3276
|
return true;
|
|
3184
3277
|
}
|
|
3185
3278
|
|
|
3186
|
-
|
|
3279
|
+
// Resolve a heading level for the anchor element: 1-4 for h1-h4, aria-level
|
|
3280
|
+
// (default 2) for role="heading" elements, 0 otherwise.
|
|
3281
|
+
function kickerHeadingLevel(heading) {
|
|
3282
|
+
const tag = heading.tagName.toLowerCase();
|
|
3283
|
+
const byTag = /^h([1-6])$/.exec(tag);
|
|
3284
|
+
if (byTag) return parseInt(byTag[1], 10);
|
|
3285
|
+
const role = heading.getAttribute?.('role') || '';
|
|
3286
|
+
if (role.toLowerCase() !== 'heading') return 0;
|
|
3287
|
+
const ariaLevel = parseInt(heading.getAttribute?.('aria-level') || '', 10);
|
|
3288
|
+
return Number.isFinite(ariaLevel) && ariaLevel >= 1 ? ariaLevel : 2;
|
|
3289
|
+
}
|
|
3290
|
+
|
|
3291
|
+
function collectKickerCandidates(doc, getStyle, resolveLetterSpacing) {
|
|
3187
3292
|
const candidates = [];
|
|
3188
|
-
for (const heading of doc.querySelectorAll('h2, h3, h4')) {
|
|
3189
|
-
|
|
3293
|
+
for (const heading of doc.querySelectorAll('h1, h2, h3, h4, [role="heading"]')) {
|
|
3294
|
+
const headingLevel = kickerHeadingLevel(heading);
|
|
3295
|
+
if (!headingLevel || headingLevel > 4) continue;
|
|
3296
|
+
if (heading.closest?.(KICKER_SKIP_SELECTOR)) continue;
|
|
3297
|
+
// Application contexts (tab panels, dialogs) use compact context labels
|
|
3298
|
+
// above headings to describe state, not to decorate. Same carve-out the
|
|
3299
|
+
// hero-eyebrow rule makes.
|
|
3300
|
+
if (heading.closest?.('[role="tabpanel"], [role="dialog"], [role="application"], dialog')) continue;
|
|
3190
3301
|
const kicker = heading.previousElementSibling;
|
|
3191
|
-
if (!kicker || kicker.closest?.(
|
|
3192
|
-
if (
|
|
3302
|
+
if (!kicker || kicker.closest?.(KICKER_SKIP_SELECTOR)) continue;
|
|
3303
|
+
if (isKickerCardContext(heading, kicker)) continue;
|
|
3193
3304
|
|
|
3194
3305
|
const headingStyle = getStyle(heading);
|
|
3195
3306
|
const kickerStyle = getStyle(kicker);
|
|
3307
|
+
const headingTag = heading.tagName.toLowerCase();
|
|
3196
3308
|
const headingText = (heading.textContent || '').replace(/\s+/g, ' ').trim();
|
|
3197
3309
|
const kickerText = cleanInlineText(kicker) || (kicker.textContent || '').replace(/\s+/g, ' ').trim();
|
|
3198
3310
|
const headingFontSize = resolveLetterSpacing(headingStyle.fontSize || '', 16) || parseFloat(headingStyle.fontSize) || 0;
|
|
3199
3311
|
const kickerFontSize = resolveLetterSpacing(kickerStyle.fontSize || '', 16) || parseFloat(kickerStyle.fontSize) || 0;
|
|
3200
3312
|
const kickerLetterSpacing = resolveLetterSpacing(kickerStyle.letterSpacing || '', kickerFontSize);
|
|
3201
3313
|
|
|
3202
|
-
if (!
|
|
3203
|
-
|
|
3314
|
+
if (!isKickerCandidate({
|
|
3315
|
+
headingLevel,
|
|
3204
3316
|
headingText,
|
|
3205
3317
|
headingFontSize,
|
|
3206
3318
|
kickerTag: kicker.tagName.toLowerCase(),
|
|
3207
3319
|
kickerText,
|
|
3208
3320
|
kickerTextTransform: kickerStyle.textTransform || '',
|
|
3321
|
+
kickerFontVariant: `${kickerStyle.fontVariant || ''} ${kickerStyle.fontVariantCaps || ''}`,
|
|
3209
3322
|
kickerFontSize,
|
|
3210
3323
|
kickerLetterSpacing,
|
|
3211
3324
|
})) {
|
|
3212
3325
|
continue;
|
|
3213
3326
|
}
|
|
3214
3327
|
|
|
3328
|
+
// A tracked-caps eyebrow above a hero-scale h1 belongs to
|
|
3329
|
+
// hero-eyebrow-chip (which also covers the accent-bold and dash-prefix
|
|
3330
|
+
// stylings there). Stand down so one element gets one finding.
|
|
3331
|
+
if (headingTag === 'h1' && headingFontSize >= 48 && kickerLetterSpacing >= 1.6) {
|
|
3332
|
+
continue;
|
|
3333
|
+
}
|
|
3334
|
+
|
|
3215
3335
|
candidates.push({
|
|
3216
|
-
headingTag
|
|
3336
|
+
headingTag,
|
|
3217
3337
|
headingText: headingText.replace(/^"|"$/g, '').slice(0, 60),
|
|
3218
3338
|
kickerText: kickerText.slice(0, 40),
|
|
3219
3339
|
});
|
|
@@ -3221,17 +3341,17 @@ function collectRepeatedSectionKickerCandidates(doc, getStyle, resolveLetterSpac
|
|
|
3221
3341
|
return candidates;
|
|
3222
3342
|
}
|
|
3223
3343
|
|
|
3224
|
-
function
|
|
3225
|
-
const candidates =
|
|
3344
|
+
function checkKickerAboveHeadingDOM() {
|
|
3345
|
+
const candidates = collectKickerCandidates(
|
|
3226
3346
|
document,
|
|
3227
3347
|
(el) => getComputedStyle(el),
|
|
3228
3348
|
(value, fontSize) => resolveLengthPx(value, fontSize) || 0,
|
|
3229
3349
|
);
|
|
3230
|
-
return
|
|
3350
|
+
return checkKickerAboveHeading({ candidates });
|
|
3231
3351
|
}
|
|
3232
3352
|
|
|
3233
3353
|
// ── Numbered section labels ─────────────────────────────────────────────────
|
|
3234
|
-
// Sibling of the
|
|
3354
|
+
// Sibling of the kicker-above-heading rule: instead of a tracked uppercase word,
|
|
3235
3355
|
// the section scaffold is a tiny numeric index riding beside each section
|
|
3236
3356
|
// heading — bare and zero-padded, or an index joined to a short micro-label
|
|
3237
3357
|
// by a separator glyph. The kicker rule deliberately excludes bare 1-2 digit
|
|
@@ -3285,7 +3405,7 @@ function collectNumberedSectionLabelCandidates(doc, getStyle, resolveLetterSpaci
|
|
|
3285
3405
|
const candidates = [];
|
|
3286
3406
|
const seenLabels = new Set();
|
|
3287
3407
|
for (const heading of doc.querySelectorAll('h2, h3, h4')) {
|
|
3288
|
-
if (heading.closest?.(
|
|
3408
|
+
if (heading.closest?.(KICKER_SKIP_SELECTOR)) continue;
|
|
3289
3409
|
// The index sits either directly before the heading, or before the
|
|
3290
3410
|
// wrapper the heading leads (label | <div><h2>…</h2>…</div>).
|
|
3291
3411
|
let label = heading.previousElementSibling;
|
|
@@ -3295,9 +3415,9 @@ function collectNumberedSectionLabelCandidates(doc, getStyle, resolveLetterSpaci
|
|
|
3295
3415
|
if (firstChild === heading) label = parent.previousElementSibling;
|
|
3296
3416
|
}
|
|
3297
3417
|
if (!label || seenLabels.has(label)) continue;
|
|
3298
|
-
if (label.closest?.(
|
|
3418
|
+
if (label.closest?.(KICKER_SKIP_SELECTOR)) continue;
|
|
3299
3419
|
if (HEADING_TAGS.has(label.tagName.toLowerCase())) continue;
|
|
3300
|
-
if (
|
|
3420
|
+
if (isKickerCardContext(heading, label)) continue;
|
|
3301
3421
|
|
|
3302
3422
|
const labelText = cleanInlineText(label) || (label.textContent || '').replace(/\s+/g, ' ').trim();
|
|
3303
3423
|
const parsed = parseNumberedLabelText(labelText);
|
|
@@ -3367,6 +3487,33 @@ function checkNumberedSectionLabelsDOM() {
|
|
|
3367
3487
|
return checkNumberedSectionLabels({ candidates });
|
|
3368
3488
|
}
|
|
3369
3489
|
|
|
3490
|
+
// Em-dash overuse (ADVISORY) — pure logic shared by the browser DOM check.
|
|
3491
|
+
// Mirrors the regex/static-HTML analyzer in engines/regex/detect-text.mjs:
|
|
3492
|
+
// two gates (absolute floor + density) so a long article using a few dashes is
|
|
3493
|
+
// left alone while a short, dash-per-clause page is flagged. Operates on
|
|
3494
|
+
// already-rendered text, so no HTML-entity decoding is needed (the browser has
|
|
3495
|
+
// resolved `—` to the literal glyph). Exported for jsdom unit tests.
|
|
3496
|
+
function checkEmDashOveruse(text) {
|
|
3497
|
+
const body = typeof text === 'string' ? text.replace(/\s+/g, ' ') : '';
|
|
3498
|
+
let count = 0;
|
|
3499
|
+
const re = /[—]|--(?=\S)/g;
|
|
3500
|
+
while (re.exec(body) !== null) count++;
|
|
3501
|
+
if (count < EM_DASH_FLOOR) return [];
|
|
3502
|
+
if (body.length > count * EM_DASH_CHARS_PER_DASH) return [];
|
|
3503
|
+
return [{ id: 'em-dash-overuse', snippet: `${count} em-dashes in body text` }];
|
|
3504
|
+
}
|
|
3505
|
+
|
|
3506
|
+
function checkEmDashOveruseDOM() {
|
|
3507
|
+
const body = document.body;
|
|
3508
|
+
if (!body) return [];
|
|
3509
|
+
// innerText reflects rendered, visible text; fall back to textContent for
|
|
3510
|
+
// engines (jsdom) that don't compute innerText.
|
|
3511
|
+
const text = typeof body.innerText === 'string' && body.innerText
|
|
3512
|
+
? body.innerText
|
|
3513
|
+
: (body.textContent || '');
|
|
3514
|
+
return checkEmDashOveruse(text);
|
|
3515
|
+
}
|
|
3516
|
+
|
|
3370
3517
|
function checkElementMotionDOM(el) {
|
|
3371
3518
|
const tag = el.tagName.toLowerCase();
|
|
3372
3519
|
if (SAFE_TAGS.has(tag)) return [];
|
|
@@ -3473,6 +3620,131 @@ function checkElementAIPaletteDOM(el) {
|
|
|
3473
3620
|
return findings;
|
|
3474
3621
|
}
|
|
3475
3622
|
|
|
3623
|
+
// ─── Decorative radial spotlight glow ───────────────────────────────────────
|
|
3624
|
+
// A soft, low-opacity chromatic radial-gradient fading to transparent, painted
|
|
3625
|
+
// as a decorative wash behind a hero or section. The translucent sibling of the
|
|
3626
|
+
// `radial-halo` tell: `radial-halo` requires a saturated, near-opaque center on
|
|
3627
|
+
// a dark page; this catches the low-alpha "spotlight" the halo gate lets slip
|
|
3628
|
+
// (e.g. `radial-gradient(circle at 52% 38%, rgba(80,111,255,0.26),
|
|
3629
|
+
// transparent 44%)`). The two alpha bands are disjoint, so they never
|
|
3630
|
+
// double-report the same declaration.
|
|
3631
|
+
const SPOTLIGHT_COLOR_TOKEN_RE = /(?:rgba?|hsla?|oklch|oklab|lab|lch|hwb|color-mix)\([^)]*(?:\([^)]*\))?[^)]*\)|#[0-9a-f]{3,8}\b|\btransparent\b/i;
|
|
3632
|
+
|
|
3633
|
+
// Parse the FIRST non-repeating radial-gradient in a background value into its
|
|
3634
|
+
// ordered color stops. Each stop is { color: {r,g,b,a} | null, transparent }.
|
|
3635
|
+
// Returns null when there is no plain radial-gradient to read.
|
|
3636
|
+
function parseRadialGradientStops(value) {
|
|
3637
|
+
if (!value || !/radial-gradient/i.test(value)) return null;
|
|
3638
|
+
const gradRe = /(repeating-)?radial-gradient\(/gi;
|
|
3639
|
+
let g;
|
|
3640
|
+
while ((g = gradRe.exec(value)) !== null) {
|
|
3641
|
+
if (g[1]) continue; // repeating-* is a pattern, not a spotlight
|
|
3642
|
+
let depth = 0, end = -1;
|
|
3643
|
+
const open = value.indexOf('(', g.index);
|
|
3644
|
+
for (let i = open; i < value.length; i++) {
|
|
3645
|
+
if (value[i] === '(') depth++;
|
|
3646
|
+
else if (value[i] === ')') { depth--; if (depth === 0) { end = i; break; } }
|
|
3647
|
+
}
|
|
3648
|
+
if (end < 0) return null;
|
|
3649
|
+
const args = splitTopLevelCommas(value.slice(open + 1, end));
|
|
3650
|
+
// The optional prelude (shape / size / `at <pos>`) carries no color token.
|
|
3651
|
+
const stopArgs = args.filter(a => SPOTLIGHT_COLOR_TOKEN_RE.test(a));
|
|
3652
|
+
if (stopArgs.length < 2) return null;
|
|
3653
|
+
return stopArgs.map(a => {
|
|
3654
|
+
const tok = a.match(SPOTLIGHT_COLOR_TOKEN_RE);
|
|
3655
|
+
if (!tok) return { color: null, transparent: false };
|
|
3656
|
+
if (/^transparent$/i.test(tok[0])) return { color: null, transparent: true };
|
|
3657
|
+
const color = parseAnyColor(tok[0]);
|
|
3658
|
+
return { color, transparent: !!color && (color.a ?? 1) <= 0.05 };
|
|
3659
|
+
});
|
|
3660
|
+
}
|
|
3661
|
+
return null;
|
|
3662
|
+
}
|
|
3663
|
+
|
|
3664
|
+
// Pure gate. `label` is a stable identifier the fixture test keys on.
|
|
3665
|
+
function checkRadialSpotlight({ gradientValue, width, height, label }) {
|
|
3666
|
+
const stops = parseRadialGradientStops(gradientValue);
|
|
3667
|
+
if (!stops || stops.length < 2) return [];
|
|
3668
|
+
|
|
3669
|
+
// Must fade OUT: the last stop is transparent / near-zero alpha. A gradient
|
|
3670
|
+
// between two visible surfaces is a real background, not a floating glow.
|
|
3671
|
+
const last = stops[stops.length - 1];
|
|
3672
|
+
const lastAlpha = last.transparent ? 0 : (last.color ? (last.color.a ?? 1) : 1);
|
|
3673
|
+
if (lastAlpha > 0.05) return [];
|
|
3674
|
+
|
|
3675
|
+
// The visible (non-transparent, parseable) color stops.
|
|
3676
|
+
const colored = stops.filter(s => !s.transparent && s.color && (s.color.a ?? 1) > 0.05);
|
|
3677
|
+
if (colored.length === 0) return [];
|
|
3678
|
+
// One soft glow, not a multi-color composition: at most two visible stops.
|
|
3679
|
+
if (colored.length > 2) return [];
|
|
3680
|
+
// Every visible stop must be LOW opacity. Any opaque stop means a real fill
|
|
3681
|
+
// or a saturated halo (`radial-halo`'s job), not this translucent spotlight.
|
|
3682
|
+
if (colored.some(s => (s.color.a ?? 1) >= 0.45)) return [];
|
|
3683
|
+
// At least one visible stop must be chromatic. A neutral (grayscale)
|
|
3684
|
+
// near-black / near-white vignette is a legitimate lighting move, exempt.
|
|
3685
|
+
const chromatic = colored.find(s => hasChroma(s.color, 24));
|
|
3686
|
+
if (!chromatic) return [];
|
|
3687
|
+
|
|
3688
|
+
// Decorative-scale gate. Badges, avatars, and actual small "lights" are
|
|
3689
|
+
// exempt; a spotlight glow only reads as slop when it washes a large surface.
|
|
3690
|
+
if (!(width >= 240 && height >= 160)) return [];
|
|
3691
|
+
|
|
3692
|
+
const alpha = (chromatic.color.a ?? 1).toFixed(2);
|
|
3693
|
+
const name = label || 'section';
|
|
3694
|
+
return [{
|
|
3695
|
+
id: 'radial-spotlight-glow',
|
|
3696
|
+
snippet: `radial-gradient spotlight glow "${name}" (${colorToHex(chromatic.color)} a${alpha} → transparent) on ${Math.round(width)}x${Math.round(height)} surface`,
|
|
3697
|
+
}];
|
|
3698
|
+
}
|
|
3699
|
+
|
|
3700
|
+
// Read the raw radial-gradient source off an element's computed style, with a
|
|
3701
|
+
// fallback to the `background` shorthand and the inline style attribute for
|
|
3702
|
+
// engines that don't decompose the shorthand into backgroundImage.
|
|
3703
|
+
function elementGradientValue(style, el) {
|
|
3704
|
+
const bgImage = style.backgroundImage && style.backgroundImage !== 'none' ? style.backgroundImage : '';
|
|
3705
|
+
if (/radial-gradient/i.test(bgImage)) return bgImage;
|
|
3706
|
+
const bg = style.background || '';
|
|
3707
|
+
if (/radial-gradient/i.test(bg)) return bg;
|
|
3708
|
+
const rawStyle = el?.getAttribute?.('style') || '';
|
|
3709
|
+
const m = rawStyle.match(/background(?:-image)?\s*:\s*([^;]+)/i);
|
|
3710
|
+
if (m && /radial-gradient/i.test(m[1])) return m[1];
|
|
3711
|
+
return '';
|
|
3712
|
+
}
|
|
3713
|
+
|
|
3714
|
+
function spotlightLabel(el) {
|
|
3715
|
+
const dataName = el.getAttribute?.('data-name');
|
|
3716
|
+
if (dataName) return dataName;
|
|
3717
|
+
if (typeof el.id === 'string' && el.id) return el.id;
|
|
3718
|
+
const cls = typeof el.className === 'string' ? el.className.trim().split(/\s+/)[0] : '';
|
|
3719
|
+
if (cls) return cls;
|
|
3720
|
+
return el.tagName ? el.tagName.toLowerCase() : 'section';
|
|
3721
|
+
}
|
|
3722
|
+
|
|
3723
|
+
function checkElementRadialSpotlightDOM(el) {
|
|
3724
|
+
const style = getComputedStyle(el);
|
|
3725
|
+
const gradientValue = elementGradientValue(style, el);
|
|
3726
|
+
if (!gradientValue) return [];
|
|
3727
|
+
const rect = el.getBoundingClientRect();
|
|
3728
|
+
return checkRadialSpotlight({
|
|
3729
|
+
gradientValue,
|
|
3730
|
+
width: rect.width,
|
|
3731
|
+
height: rect.height,
|
|
3732
|
+
label: spotlightLabel(el),
|
|
3733
|
+
});
|
|
3734
|
+
}
|
|
3735
|
+
|
|
3736
|
+
function checkElementRadialSpotlight(el, style, tag, window) {
|
|
3737
|
+
const gradientValue = elementGradientValue(style, el);
|
|
3738
|
+
if (!gradientValue) return [];
|
|
3739
|
+
// Static engine does no layout — read explicit pixel dimensions from CSS.
|
|
3740
|
+
return checkRadialSpotlight({
|
|
3741
|
+
gradientValue,
|
|
3742
|
+
width: parseFloat(style.width) || 0,
|
|
3743
|
+
height: parseFloat(style.height) || 0,
|
|
3744
|
+
label: spotlightLabel(el),
|
|
3745
|
+
});
|
|
3746
|
+
}
|
|
3747
|
+
|
|
3476
3748
|
const QUALITY_TEXT_TAGS = new Set(['p', 'li', 'td', 'th', 'dd', 'blockquote', 'figcaption']);
|
|
3477
3749
|
|
|
3478
3750
|
// Resolve a CSS font-size value to pixels by walking up the parent chain.
|
|
@@ -3594,6 +3866,55 @@ function textDescendantsFlushSides(el, rect) {
|
|
|
3594
3866
|
return flush;
|
|
3595
3867
|
}
|
|
3596
3868
|
|
|
3869
|
+
// Screen-reader-only ("visually hidden") text is exempt from the tiny-text
|
|
3870
|
+
// floors: it is never rendered, so its size is irrelevant. Detect the two
|
|
3871
|
+
// standard idioms — a known sr-only class on the element or an ancestor, and
|
|
3872
|
+
// the clip / 1px-box pattern. Works in both jsdom (declared styles) and the
|
|
3873
|
+
// browser (computed styles).
|
|
3874
|
+
const SR_ONLY_SELECTOR = '.sr-only, .visually-hidden, .visuallyhidden, .screen-reader, .screen-reader-only, .screenreader, .a11y-hidden, .hidden-visually, [class*="sr-only" i], [class*="visually-hidden" i], [class*="visuallyhidden" i], [class*="screen-reader" i], [class*="screenreader" i]';
|
|
3875
|
+
function isVisuallyHidden(el, style) {
|
|
3876
|
+
if ((el.matches && el.matches(SR_ONLY_SELECTOR)) || (el.closest && el.closest(SR_ONLY_SELECTOR))) return true;
|
|
3877
|
+
const pos = style.position || '';
|
|
3878
|
+
if (pos === 'absolute' || pos === 'fixed') {
|
|
3879
|
+
const clip = style.clip || '';
|
|
3880
|
+
const clipPath = style.clipPath || style.webkitClipPath || style['clip-path'] || '';
|
|
3881
|
+
if (/rect\(\s*0/.test(clip) || /inset\(\s*(?:50%|99|100%)/.test(clipPath)) return true;
|
|
3882
|
+
const w = parseFloat(style.width);
|
|
3883
|
+
const h = parseFloat(style.height);
|
|
3884
|
+
const overflow = style.overflow || '';
|
|
3885
|
+
if ((w === 1 || h === 1) && (overflow === 'hidden' || overflow === 'clip')) return true;
|
|
3886
|
+
}
|
|
3887
|
+
return false;
|
|
3888
|
+
}
|
|
3889
|
+
|
|
3890
|
+
// Elements whose text is never painted: document metadata and script/style
|
|
3891
|
+
// payloads. Their JS / CSS / JSON-LD text satisfies `hasDirectText`, and on
|
|
3892
|
+
// sites that set `html { font-size: 62.5% }` their inherited computed size is
|
|
3893
|
+
// 10px — so the text-size floors flag them as tiny body copy even though
|
|
3894
|
+
// nothing renders (issue #408: dozens of phantom "10px body text" findings on
|
|
3895
|
+
// every Shopify page). Exclude them, plus anything the cascade resolves to
|
|
3896
|
+
// display:none / visibility:hidden. The jsdom path can't lay out, so the
|
|
3897
|
+
// tag/attribute-based exclusions carry the weight there; the display checks are
|
|
3898
|
+
// computed-style reads that resolve without layout in both adapters.
|
|
3899
|
+
const NON_RENDERED_TAGS = new Set([
|
|
3900
|
+
'script', 'style', 'title', 'noscript', 'template', 'head',
|
|
3901
|
+
'meta', 'link', 'base', 'param', 'source', 'track', 'datalist',
|
|
3902
|
+
'col', 'colgroup', 'map', 'area',
|
|
3903
|
+
]);
|
|
3904
|
+
function isNonRenderedText(el, tag, style) {
|
|
3905
|
+
const t = (tag || '').toLowerCase();
|
|
3906
|
+
if (NON_RENDERED_TAGS.has(t)) return true;
|
|
3907
|
+
// Descendants of <head> never render even when the tag itself would
|
|
3908
|
+
// (some sites nest <noscript>/<template> content there).
|
|
3909
|
+
if (el && el.closest && el.closest('head')) return true;
|
|
3910
|
+
if (style) {
|
|
3911
|
+
if (style.display === 'none') return true;
|
|
3912
|
+
const vis = style.visibility;
|
|
3913
|
+
if (vis === 'hidden' || vis === 'collapse') return true;
|
|
3914
|
+
}
|
|
3915
|
+
return false;
|
|
3916
|
+
}
|
|
3917
|
+
|
|
3597
3918
|
// Pure quality checks. Most run on computed CSS and DOM-only inputs (work in
|
|
3598
3919
|
// jsdom and the browser). Two checks (line-length, cramped-padding) gate on
|
|
3599
3920
|
// element rect dimensions, which jsdom can't compute — pass `rect: null` from
|
|
@@ -3604,8 +3925,13 @@ function textDescendantsFlushSides(el, rect) {
|
|
|
3604
3925
|
function checkQuality(opts) {
|
|
3605
3926
|
const { el, tag, style, hasDirectText, textLen, fontSize, lineHeightPx, letterSpacingPx, rect, lineMax = 80, viewportWidth = 0, win = null } = opts;
|
|
3606
3927
|
const findings = [];
|
|
3607
|
-
// Skip browser extension injected elements
|
|
3608
|
-
|
|
3928
|
+
// Skip browser extension injected elements. Read the id via getAttribute
|
|
3929
|
+
// whenever `el.id` is not a string: on a <form> (and other
|
|
3930
|
+
// [LegacyOverrideBuiltIns] hosts) a named control like <input name="id">
|
|
3931
|
+
// shadows the builtin `id` getter and returns the control element, whose
|
|
3932
|
+
// `.startsWith` is undefined and throws (issue #407 — every Shopify product
|
|
3933
|
+
// form ships an <input name="id">).
|
|
3934
|
+
const elId = typeof el.id === 'string' ? el.id : (el.getAttribute?.('id') || '');
|
|
3609
3935
|
if (elId.startsWith('claude-') || elId.startsWith('cic-')) return findings;
|
|
3610
3936
|
|
|
3611
3937
|
// --- Line length too long --- (browser-only: needs rect.width)
|
|
@@ -3873,11 +4199,67 @@ function checkQuality(opts) {
|
|
|
3873
4199
|
const skipTags = ['sub', 'sup', 'code', 'kbd', 'samp', 'var', 'caption', 'figcaption'];
|
|
3874
4200
|
const inUIContext = el.closest && el.closest('button, a, label, summary, pre, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="option"], nav, footer, [aria-hidden="true"], [class*="badge" i], [class*="caption" i], [class*="chip" i], [class*="code" i], [class*="console" i], [class*="diff" i], [class*="label" i], [class*="meta" i], [class*="mock" i], [class*="pill" i], [class*="preview" i], [class*="tag" i], [class*="terminal" i], [class*="writes" i]');
|
|
3875
4201
|
const isUppercase = style.textTransform === 'uppercase';
|
|
3876
|
-
if (!skipTags.includes(tag) && !inUIContext && !isUppercase) {
|
|
4202
|
+
if (!skipTags.includes(tag) && !inUIContext && !isUppercase && !isNonRenderedText(el, tag, style)) {
|
|
3877
4203
|
findings.push({ id: 'tiny-text', snippet: `${fontSize}px body text` });
|
|
3878
4204
|
}
|
|
3879
4205
|
}
|
|
3880
4206
|
|
|
4207
|
+
// --- Undersized functional / UI text ---
|
|
4208
|
+
// Complements `tiny-text` above, which owns long body copy and deliberately
|
|
4209
|
+
// EXEMPTS the UI furniture layer (nav, footer, links, buttons, labels,
|
|
4210
|
+
// uppercase micro-labels). This rule targets exactly that blind spot: the
|
|
4211
|
+
// interactive and short content-bearing text — nav items, buttons, labels,
|
|
4212
|
+
// table cells, meta rows, timecodes — shipped below an 11px floor.
|
|
4213
|
+
//
|
|
4214
|
+
// The live failure it closes: a build shipped its entire furniture layer at
|
|
4215
|
+
// 8px, and the design hook waved it through because 8px had been added to
|
|
4216
|
+
// the DESIGN.md size ramp. Being on the ramp is a token argument, not a
|
|
4217
|
+
// legibility one, so this rule ignores the design system entirely — a value
|
|
4218
|
+
// on the ramp is still flagged.
|
|
4219
|
+
//
|
|
4220
|
+
// Floors: 11px for anything functional. The floor holds inside a footer;
|
|
4221
|
+
// only NON-interactive legal smallprint gets the softer 10px floor. Exempts
|
|
4222
|
+
// sup/sub, visually-hidden (sr-only) text, and code/terminal contexts.
|
|
4223
|
+
// Uppercase letterspaced micro-labels are still functional — not exempt.
|
|
4224
|
+
{
|
|
4225
|
+
const directText = [...el.childNodes]
|
|
4226
|
+
.filter(n => n.nodeType === 3)
|
|
4227
|
+
.map(n => n.textContent || '')
|
|
4228
|
+
.join('')
|
|
4229
|
+
.replace(/\s+/g, ' ')
|
|
4230
|
+
.trim();
|
|
4231
|
+
const dtLen = directText.length;
|
|
4232
|
+
// `option` renders (in native select popups) so it stays a local skip;
|
|
4233
|
+
// script/style/title/noscript/head-descendants and display:none /
|
|
4234
|
+
// visibility:hidden are handled by isNonRenderedText (shared with tiny-text).
|
|
4235
|
+
const UI_SKIP_TAGS = new Set(['sub', 'sup', 'option']);
|
|
4236
|
+
// jsdom resolves the parent chain in resolveFontSizePx, so em/rem/%-sized
|
|
4237
|
+
// text that computes at or above the floor never reaches here. The browser
|
|
4238
|
+
// adapter additionally catches values only resolvable with real layout
|
|
4239
|
+
// (e.g. viewport-relative units, cascade winners set in linked sheets).
|
|
4240
|
+
if (fontSize > 0 && fontSize < 11 && dtLen >= 2 && !UI_SKIP_TAGS.has(tag) && !isNonRenderedText(el, tag, style)) {
|
|
4241
|
+
const EXEMPT_CONTEXT = 'pre, code, kbd, samp, var, svg, [aria-hidden="true"], [class*="terminal" i], [class*="console" i], [class*="code" i], [class*="mock" i], [class*="editor" i], [class*="syntax" i], [class*="diff" i]';
|
|
4242
|
+
const isExemptContext = (el.matches && el.matches(EXEMPT_CONTEXT)) || (el.closest && el.closest(EXEMPT_CONTEXT));
|
|
4243
|
+
if (!isExemptContext && !isVisuallyHidden(el, style)) {
|
|
4244
|
+
const INTERACTIVE = 'a[href], button, summary, label, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="option"], [role="checkbox"], [role="radio"], [role="switch"], [role="treeitem"], [tabindex]';
|
|
4245
|
+
const FURNITURE = 'nav, [role="navigation"], td, th, [role="gridcell"], [role="cell"], caption, figcaption, dt, dd, footer, [class*="meta" i], [class*="label" i], [class*="badge" i], [class*="chip" i], [class*="pill" i], [class*="tag" i], [class*="kicker" i], [class*="eyebrow" i], [class*="breadcrumb" i], [class*="timestamp" i], [class*="category" i], [class*="caption" i], [class*="nav" i]';
|
|
4246
|
+
const SMALLPRINT = 'small, footer, [class*="legal" i], [class*="copyright" i], [class*="fineprint" i], [class*="fine-print" i], [class*="smallprint" i], [class*="small-print" i], [class*="disclaimer" i], [class*="disclosure" i], [class*="footnote" i]';
|
|
4247
|
+
const isInteractive = (el.matches && el.matches(INTERACTIVE)) || (el.closest && el.closest(INTERACTIVE));
|
|
4248
|
+
const isFurniture = (el.matches && el.matches(FURNITURE)) || (el.closest && el.closest(FURNITURE));
|
|
4249
|
+
const isSmallprint = (el.matches && el.matches(SMALLPRINT)) || (el.closest && el.closest(SMALLPRINT));
|
|
4250
|
+
const floor = (!isInteractive && isSmallprint) ? 10 : 11;
|
|
4251
|
+
// Fire on functional text only: interactive, structural furniture, or
|
|
4252
|
+
// any short (<=20-char) run — the label / meta / timecode shape. Long
|
|
4253
|
+
// non-furniture body copy stays with `tiny-text`, so the two rules
|
|
4254
|
+
// never double-flag the same element.
|
|
4255
|
+
if (fontSize < floor && (isInteractive || isFurniture || dtLen <= 20)) {
|
|
4256
|
+
const excerpt = directText.slice(0, 40);
|
|
4257
|
+
findings.push({ id: 'undersized-ui-text', snippet: `${fontSize}px functional text "${excerpt}" (below ${floor}px floor)` });
|
|
4258
|
+
}
|
|
4259
|
+
}
|
|
4260
|
+
}
|
|
4261
|
+
}
|
|
4262
|
+
|
|
3881
4263
|
// --- All-caps body text ---
|
|
3882
4264
|
if (hasDirectText && textLen > 30 && style.textTransform === 'uppercase') {
|
|
3883
4265
|
if (!['h1','h2','h3','h4','h5','h6'].includes(tag)) {
|
|
@@ -4068,7 +4450,7 @@ function checkElementColors(el, style, tag, window, customPropMap, hasAnchorInhe
|
|
|
4068
4450
|
textColor,
|
|
4069
4451
|
bgColor: ownBg,
|
|
4070
4452
|
effectiveBg: finalEffectiveBg,
|
|
4071
|
-
effectiveBgStops: finalEffectiveBg ? null : resolveGradientStops(el, window),
|
|
4453
|
+
effectiveBgStops: finalEffectiveBg ? null : resolveGradientStops(el, window, customPropMap),
|
|
4072
4454
|
fontSize: parseFloat(style.fontSize) || 16,
|
|
4073
4455
|
fontWeight: parseInt(style.fontWeight) || 400,
|
|
4074
4456
|
hasDirectText,
|
|
@@ -4208,13 +4590,13 @@ function checkElementHeroEyebrow(el, style, tag, window, customPropMap) {
|
|
|
4208
4590
|
});
|
|
4209
4591
|
}
|
|
4210
4592
|
|
|
4211
|
-
function
|
|
4212
|
-
const candidates =
|
|
4593
|
+
function checkKickerAboveHeadingFromDoc(doc, win) {
|
|
4594
|
+
const candidates = collectKickerCandidates(
|
|
4213
4595
|
doc,
|
|
4214
4596
|
(el) => win.getComputedStyle(el),
|
|
4215
4597
|
(value, fontSize) => resolveLengthPx(value, fontSize) || 0,
|
|
4216
4598
|
);
|
|
4217
|
-
return
|
|
4599
|
+
return checkKickerAboveHeading({ candidates });
|
|
4218
4600
|
}
|
|
4219
4601
|
|
|
4220
4602
|
function checkElementMotion(tag, style) {
|
|
@@ -6373,7 +6755,11 @@ if (IS_BROWSER) {
|
|
|
6373
6755
|
function generateSelector(el) {
|
|
6374
6756
|
if (el === document.body) return 'body';
|
|
6375
6757
|
if (el === document.documentElement) return 'html';
|
|
6376
|
-
|
|
6758
|
+
// Read via getAttribute when `el.id` is not a string — a <form> with a
|
|
6759
|
+
// named control (e.g. <input name="id">) shadows the builtin getter and
|
|
6760
|
+
// returns the element, producing a garbage `#[object …]` selector (#407).
|
|
6761
|
+
const elId = typeof el.id === 'string' ? el.id : (el.getAttribute('id') || '');
|
|
6762
|
+
if (elId) return '#' + CSS.escape(elId);
|
|
6377
6763
|
|
|
6378
6764
|
const parts = [];
|
|
6379
6765
|
let current = el;
|
|
@@ -7066,6 +7452,10 @@ if (IS_BROWSER) {
|
|
|
7066
7452
|
type: f.type || f.id,
|
|
7067
7453
|
category: ap ? ap.category : 'quality',
|
|
7068
7454
|
severity: f.severity || ap?.severity || 'warning',
|
|
7455
|
+
// Advisory findings (em-dash overuse, etc.) are surfaced but never
|
|
7456
|
+
// treated as failures; carry the flag so the overlay/extension can
|
|
7457
|
+
// render them with the mildest affordance and consumers can filter.
|
|
7458
|
+
advisory: (ap && ap.advisory === true) || f.advisory === true,
|
|
7069
7459
|
detail: f.detail || f.snippet,
|
|
7070
7460
|
ignoreValue: f.ignoreValue || f.value || '',
|
|
7071
7461
|
name: ap ? ap.name : (f.type || f.id),
|
|
@@ -7306,8 +7696,11 @@ if (IS_BROWSER) {
|
|
|
7306
7696
|
for (const el of document.querySelectorAll('*')) {
|
|
7307
7697
|
// Skip impeccable's own elements and any descendants (overlays, labels, banner, nav buttons)
|
|
7308
7698
|
if (el.closest('.impeccable-overlay, .impeccable-label, .impeccable-banner, .impeccable-tooltip')) continue;
|
|
7309
|
-
// Skip browser extension elements (Claude, etc.)
|
|
7310
|
-
|
|
7699
|
+
// Skip browser extension elements (Claude, etc.). Use getAttribute when
|
|
7700
|
+
// `el.id` is not a string: a <form> with a named control like
|
|
7701
|
+
// <input name="id"> shadows the builtin `id` getter and returns the
|
|
7702
|
+
// element, whose `.startsWith` throws (issue #407).
|
|
7703
|
+
const elId = typeof el.id === 'string' ? el.id : (el.getAttribute('id') || '');
|
|
7311
7704
|
if (elId.startsWith('claude-') || elId.startsWith('cic-')) continue;
|
|
7312
7705
|
// Skip the impeccable live-mode overlay (highlight, tooltip, bar, picker, toast).
|
|
7313
7706
|
// These are inspector chrome, not part of the user's design.
|
|
@@ -7322,6 +7715,7 @@ if (IS_BROWSER) {
|
|
|
7322
7715
|
...checkElementMotionDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
|
7323
7716
|
...checkElementGlowDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
|
7324
7717
|
...checkElementAIPaletteDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
|
7718
|
+
...checkElementRadialSpotlightDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
|
7325
7719
|
...checkElementIconTileDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
|
7326
7720
|
...checkElementItalicSerifDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
|
7327
7721
|
...checkElementQualityDOM(el).map(f => ({ type: f.id, detail: f.snippet })),
|
|
@@ -7360,7 +7754,7 @@ if (IS_BROWSER) {
|
|
|
7360
7754
|
addBrowserFindings(groupMap, document.body, typoFindings);
|
|
7361
7755
|
}
|
|
7362
7756
|
|
|
7363
|
-
const sectionKickerFindings =
|
|
7757
|
+
const sectionKickerFindings = checkKickerAboveHeadingDOM()
|
|
7364
7758
|
.map(f => ({ type: f.id, detail: f.snippet }))
|
|
7365
7759
|
.filter(f => _ruleOk(f.type));
|
|
7366
7760
|
if (sectionKickerFindings.length > 0) {
|
|
@@ -7384,6 +7778,17 @@ if (IS_BROWSER) {
|
|
|
7384
7778
|
addBrowserFindings(groupMap, document.body, repeatedTextFindings);
|
|
7385
7779
|
}
|
|
7386
7780
|
|
|
7781
|
+
// Em-dash overuse (advisory): browser parity with the static/regex path.
|
|
7782
|
+
// Reads rendered body text so it catches dashes written as HTML entities.
|
|
7783
|
+
// serializeFindings stamps the advisory flag from the registry.
|
|
7784
|
+
const emDashFindings = checkEmDashOveruseDOM()
|
|
7785
|
+
.map(f => ({ type: f.id, detail: f.snippet }))
|
|
7786
|
+
.filter(f => _ruleOk(f.type));
|
|
7787
|
+
if (emDashFindings.length > 0) {
|
|
7788
|
+
pageLevelFindings.push(...emDashFindings);
|
|
7789
|
+
addBrowserFindings(groupMap, document.body, emDashFindings);
|
|
7790
|
+
}
|
|
7791
|
+
|
|
7387
7792
|
const layoutFindings = checkLayout().filter(f => _ruleOk(f.type));
|
|
7388
7793
|
for (const f of layoutFindings) {
|
|
7389
7794
|
const el = f.el || document.body;
|