qa-detect-typography-advanced
Real typography DEFECTS only (trimmed 2026-06-09 to remove cosmetic/opinion noise): failed web fonts, real WCAG contrast failures, tofu/replacement glyphs, mixed-content (blocked) fonts, and missing/i
SKILL.mdskills/qa-detect-typography-advanced/SKILL.md
GitHubWhat it catches — 5 REAL defect types only
| issueType | severity | What — and why it's a real defect (not an opinion) |
|---|---|---|
webFontFailed |
high | A declared @font-face file failed to load → users see the wrong (fallback) font. Objectively broken. |
contrastFail |
high | Real WCAG 2.1 luminance ratio below 4.5:1 (normal) / 3:1 (large). Measured, not guessed — accessibility failure. |
tofuGlyph |
high | Visible □ / � replacement characters rendering on the page (font missing the glyph). Broken text. |
mixedContentFont |
high | HTTPS page references an http:// font URL — the browser BLOCKS it, so the font silently never loads. |
missingHtmlLang |
medium | <html> has no lang — breaks screen-reader pronunciation, hyphenation, and quote glyphs (WCAG 3.1.1). |
Removed as noise (2026-06-09): syntheticWeight, noFontDisplay, noGenericFallback, tooManyFontFamilies, missingH1/multipleH1 (covered by qa-detect-a11y → noH1), headingSkip, linkNoDecoration, fontSizePxBased, allCapsBodyCopy, italicOnlyEmphasis, invalidHtmlLang, deepHeadingHierarchy, h2MissingInHierarchy, emptyTextElement, extremeLetterSpacing, wallOfText, unstyledPullQuote, tooManyFontSizes, noFontPreload, corsFontPreloadMissing, unreadableTextShadow, fontPayloadCount, fontPayloadHeavy, fallbackMetricMismatch, fontFileNotSubsetted, inconsistentRhythm, measureTooLong, measureTooShort, baselineGridOff, widowLine, noOpticalSizing, variableFont*, languageFontMismatch, fontDisplayBlock, unusedFontWeight, iconFontAsWebFont, ellipsisNoOverflow. These are best-practice advisories, not defects — they were flooding the bug tracker with false positives.
Probe (browser_evaluate)
() => {
const sel = el => {
const id = el.id ? `#${el.id}` : '';
const cls = (el.className && typeof el.className === 'string')
? '.' + el.className.trim().split(/\s+/).slice(0, 2).join('.') : '';
return (el.tagName.toLowerCase() + id + cls).slice(0, 120);
};
const bb = el => { const r = el.getBoundingClientRect(); return { x: Math.round(r.left), y: Math.round(r.top), w: Math.round(r.width), h: Math.round(r.height) }; };
const visible = el => {
if (!el || el.nodeType !== 1) return false;
const cs = getComputedStyle(el);
if (cs.display === 'none' || cs.visibility === 'hidden' || +cs.opacity === 0) return false;
const r = el.getBoundingClientRect();
return r.width > 0 && r.height > 0;
};
const out = [];
const TEXT_SEL = 'p, span, a, li, td, th, label, button, h1, h2, h3, h4, h5, h6, div';
const sample = [...document.querySelectorAll(TEXT_SEL)]
.filter(el => el.innerText && el.innerText.trim().length > 5)
.filter(visible)
.slice(0, 40);
// 1. Web font load failures (real: wrong font renders)
try {
for (const ff of document.fonts) {
if (ff.status === 'error') {
out.push({ issueType:'webFontFailed', severity:'high', selector:`@font-face[${ff.family}]`,
description:`Web font "${ff.family}" (${ff.weight} ${ff.style}) failed to load — users see a system fallback font instead.` });
}
}
} catch (_) {}
// 2. Real WCAG contrast ratio (verbatim luminance math — measured, not guessed)
const lin = c => { c /= 255; return c <= 0.03928 ? c/12.92 : Math.pow((c+0.055)/1.055, 2.4); };
const lum = (r,g,b) => 0.2126*lin(r) + 0.7152*lin(g) + 0.0722*lin(b);
const parseRgb = s => { const m = s.match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/); return m ? [+m[1], +m[2], +m[3]] : null; };
// effBg walks ancestors for a SOLID, OPAQUE background color. Crucially, if any ancestor in the
// chain carries a background-image / gradient (which we cannot read pixel colors from), the real
// background is INDETERMINATE → return null so the caller SKIPS rather than fabricating white.
// Returning a hard-coded white fallback was the root cause of the contrast false positives:
// text over images/gradients/transparent surfaces was measured against an invented white bg.
const effBg = el => {
let cur = el;
while (cur && cur !== document.documentElement) {
const cs = getComputedStyle(cur);
// text painted over an image/gradient — can't compute a real ratio, bail as indeterminate.
if (cs.backgroundImage && cs.backgroundImage !== 'none') return null;
const rgb = parseRgb(cs.backgroundColor);
const am = cs.backgroundColor.match(/rgba\([^,]+,[^,]+,[^,]+,\s*([\d.]+)\)/);
const alpha = am ? parseFloat(am[1]) : 1;
if (rgb && alpha > 0.5) return rgb;
cur = cur.parentElement;
}
// reached the root with no solid bg found — check the root itself, else indeterminate.
const rootCs = getComputedStyle(document.documentElement);
if (rootCs.backgroundImage && rootCs.backgroundImage !== 'none') return null;
const rootRgb = parseRgb(rootCs.backgroundColor);
if (rootRgb) return rootRgb;
const bodyRgb = document.body ? parseRgb(getComputedStyle(document.body).backgroundColor) : null;
return bodyRgb || null; // null === indeterminate → skip, never fabricate white
};
// WCAG 1.4.3 exempts disabled controls and pure-decorative text. A placeholder is allowed to be
// low-contrast (it's a hint, not content). Detect these and skip.
const isExempt = el => {
if (el.disabled) return true;
if (el.closest && el.closest('[disabled], [aria-disabled="true"], fieldset:disabled')) return true;
const cs = getComputedStyle(el);
if (cs.cursor === 'not-allowed') return true;
if (cs.pointerEvents === 'none') return true; // decorative / non-interactive overlay text
if (cs.userSelect === 'none' && el.getAttribute('aria-hidden') === 'true') return true;
if (el.getAttribute('aria-hidden') === 'true') return true; // decorative, not announced
return false;
};
let cFails = 0;
for (const el of sample) {
if (cFails >= 5) break;
if (el.children.length > 0) continue; // leaf text only
if (isExempt(el)) continue; // WCAG: disabled / decorative text exempt
const txt = (el.innerText || '').trim();
if (txt.length < 3) continue;
const cs = getComputedStyle(el);
// skip effectively-invisible text (already covered by visibility filter, but guard opacity/clip).
if (+cs.opacity < 0.1) continue;
const fg = parseRgb(cs.color);
if (!fg) continue;
// foreground alpha < 1 (e.g. rgba(...,0.4)) means semi-transparent text composited over an
// unknown surface — ratio isn't reliably computable, skip rather than over-report.
const fgAlpha = (cs.color.match(/rgba\([^,]+,[^,]+,[^,]+,\s*([\d.]+)\)/) || [])[1];
if (fgAlpha !== undefined && parseFloat(fgAlpha) < 0.9) continue;
const bg = effBg(el);
// INDETERMINATE background (image/gradient/transparent-to-root) → cannot compute a real ratio.
// Skip, never fabricate a white background. This kills the "white-on-image" false positives.
if (!bg) continue;
// belt-and-suspenders: exact fg===bg means the bg resolution collapsed — skip the artifact.
if (fg[0] === bg[0] && fg[1] === bg[1] && fg[2] === bg[2]) continue;
const L1 = lum(...fg), L2 = lum(...bg);
const ratio = (Math.max(L1,L2)+0.05) / (Math.min(L1,L2)+0.05);
const fs = parseFloat(cs.fontSize) || 16;
const bold = (parseInt(cs.fontWeight) || 400) >= 700;
const isLarge = fs >= 24 || (fs >= 18.66 && bold);
const min = isLarge ? 3.0 : 4.5;
if (ratio < min) {
cFails++;
out.push({ issueType:'contrastFail', severity:'high', selector:sel(el), bbox:bb(el),
description:`WCAG contrast ${ratio.toFixed(2)}:1 is below the ${min}:1 minimum for ${isLarge?'large':'normal'} text "${txt.slice(0,40)}". color=${cs.color} bg=rgb(${bg.join(',')}).` });
}
}
// 3. Tofu / replacement glyphs (real: broken text)
let tofu = 0;
for (const el of sample) {
if (tofu >= 3) break;
if (el.children.length > 0) continue;
const txt = el.innerText || '';
if (/[�□]/.test(txt) || / ?\uE0[0-9A-F]{2}/.test(txt)) {
tofu++;
out.push({ issueType:'tofuGlyph', severity:'high', selector:sel(el), bbox:bb(el),
description:`Replacement / tofu glyph (□ or �) rendering in "${txt.replace(/[�□]/g,'[?]').slice(0,40)}" — the font is missing this character.` });
}
}
// 4. Mixed-content fonts (real: browser blocks the font on HTTPS)
if (location.protocol === 'https:') {
let mixed = 0;
for (const sheet of document.styleSheets) {
if (mixed >= 2) break;
let rules; try { rules = sheet.cssRules; } catch (_) { continue; }
if (!rules) continue;
for (const r of rules) {
if (mixed >= 2) break;
if (r.type === CSSRule.FONT_FACE_RULE && r.style) {
const src = r.style.getPropertyValue('src') || '';
if (/url\(\s*['"]?http:\/\//i.test(src)) {
mixed++;
out.push({ issueType:'mixedContentFont', severity:'high', selector:'@font-face',
description:`@font-face on this HTTPS page references an http:// font URL — the browser blocks it, so the font never loads.` });
}
}
}
}
}
// 5. Missing html lang (real: a11y — pronunciation/hyphenation)
const htmlLang = document.documentElement.getAttribute('lang');
if (!htmlLang || !htmlLang.trim()) {
out.push({ issueType:'missingHtmlLang', severity:'medium', selector:'html',
description:`<html> has no lang attribute — screen readers can't pick the right voice, and hyphenation/quote glyphs break (WCAG 3.1.1).` });
}
return out;
}
Notes
- Trimmed 2026-06-09 from 43 → 5 issue types. Every remaining type is an objective, measurable defect, not a best-practice opinion.
- Bounded: ≤5 contrast + ≤3 tofu + ≤2 mixed-content + webfont + lang = max ~12 findings/cell.
- Self-skips: a page with no text returns
[]. - Contrast uses real relative-luminance math (WCAG 2.1), resolving the effective background up the ancestor chain.