qa-detect-typography
Detects small fonts, tight line-height, clipped text, oversized headings on mobile, and unbreakable long words causing overflow
SKILL.mdskills/qa-detect-typography/SKILL.md
GitHubWhat it checks
smallFont— font-size < 10px (genuinely too small). NOTE: WCAG has NO minimum font size; 10–11px secondary text (table cells, captions, labels) is normal and readable, so it is NOT flagged. Only < 10px — which is hard to read for most users — is reported, at LOW severity (advisory, not a WCAG violation).tightLineHeight— line-height / font-size < 1.2 (and font >= 10px)textClipped— element with overflow:hidden where scrollHeight > clientHeight + 4oversizedHeading— H1/H2 font-size > 36px on mobile (≤768px viewport)longWordNoBreak— leaf text element with word ≥25 chars causing overflow, without word-break/overflow-wrap
Probe (browser_evaluate)
() => {
const sel = el => (el.tagName.toLowerCase() + (el.id ? `#${el.id}` : '')).slice(0,120);
const out = [];
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 vw = innerWidth;
const isMobile = vw <= 768;
const q = 'p,span,a,li,td,th,label,button,h1,h2,h3,h4,h5,h6,div';
for (const el of document.querySelectorAll(q)) {
if (out.length >= 20) break;
if (!el.innerText || !el.innerText.trim()) continue;
const r = el.getBoundingClientRect();
if (r.width === 0 && r.height === 0) continue;
const s = getComputedStyle(el);
const fs = parseFloat(s.fontSize);
const lh = parseFloat(s.lineHeight);
// Structural exemption: icon-font glyphs (Material Icons / FontAwesome — the "text" is a
// ligature rendered as an icon) and aria-hidden decorative text are NOT readable content.
// Flagging them as "small font" is a false positive regardless of px. Skip them.
const fam = (s.fontFamily || '').toLowerCase();
const decorative = el.getAttribute('aria-hidden') === 'true'
|| /icon|material|fontawesome|fa-|glyph/.test(fam);
// 1. smallFont — WCAG has NO minimum font size. 10-11px is normal, readable secondary text.
// Only flag < 10px (genuinely too small) on REAL readable text, at LOW severity (advisory).
if (!decorative && fs < 10) {
out.push({ issueType:'smallFont', severity:'low', selector:sel(el),
description:`Text on ${sel(el)} is ${fs}px — below 10px is hard to read for most users (advisory; not a WCAG minimum).`, bbox: bb(el) });
} else if (lh && lh/fs < 1.2
// line-height ONLY matters when text WRAPS to 2+ lines. A single-line element
// (button, label, icon, the "···" kebab menu, table cell, badge) has no line
// below to crowd, so a tight ratio is harmless — do NOT flag it.
&& el.clientHeight >= lh * 1.8 // renders as ≥ ~2 lines (actually wraps)
&& !el.closest('button, a, label, th, summary, [role="button"], [role="menuitem"], [role="tab"], [contenteditable], [class*="btn"], [class*="badge"], [class*="chip"], [class*="tag"], [class*="icon"], [class*="action"], [class*="kebab"], [class*="menu"]')
&& !/^H[1-6]$/.test(el.tagName) // headings use tight line-height by design
&& getComputedStyle(el).cursor !== 'pointer' // clickable controls aren't body text
&& (el.innerText || '').trim().split(/\s+/).length >= 8) { // a real sentence, not a 1–3 word label/glyph
// 2. tightLineHeight — multi-line body/paragraph text only (single-line UI is exempt)
out.push({ issueType:'tightLineHeight', severity:'low', selector:sel(el),
description:`Typography issue on ${sel(el)}: line-height/font-size = ${(lh/fs).toFixed(2)} < 1.2 on multi-line text`, bbox: bb(el) });
}
// 3. textClipped — actual text being cut, not just container overflow.
// Real clip patterns:
// a) horizontal: white-space:nowrap + text-overflow:ellipsis|clip
// AND scrollWidth > clientWidth (text wider than container).
// b) vertical: -webkit-line-clamp: N AND scrollHeight > clientHeight
// (text has more lines than allowed).
// Skip containers (any element with non-inline element children) — overflow on
// containers is layout overflow (sidebar menu, card stack, toast animation),
// NOT text being cut. Also skip <div> unless its only children are inline
// formatting elements (span/b/i/em/strong/u/sup/sub/br/mark/code/small).
const INLINE_OK = new Set(['SPAN','I','EM','STRONG','B','U','SUP','SUB','BR','MARK','CODE','SMALL','A','LABEL']);
const isTextLeaf = el.children.length === 0 ||
[...el.children].every(c => INLINE_OK.has(c.tagName));
const isDivContainer = el.tagName === 'DIV' && !isTextLeaf;
if (isTextLeaf && !isDivContainer) {
const ws = s.whiteSpace;
const to = s.textOverflow;
const ovf = s.overflow;
// (a) horizontal ellipsis/clip
const horizCss = (ws === 'nowrap') && (to === 'ellipsis' || to === 'clip') &&
(ovf === 'hidden' || ovf === 'clip');
const horizClipped = horizCss && el.scrollWidth > el.clientWidth + 2;
// (b) vertical line-clamp
const clampN = parseInt(s.webkitLineClamp || s.lineClamp || '0', 10) || 0;
const vertCss = clampN > 0 && (ovf === 'hidden' || ovf === 'clip');
const vertClipped = vertCss && el.scrollHeight > el.clientHeight + 2;
if (horizClipped || vertClipped) {
const dir = horizClipped ? 'horizontally' : `to ${clampN} line(s)`;
out.push({ issueType:'textClipped', severity:'low', selector:sel(el),
description:`Text in ${sel(el)} is clipped ${dir} (content ${horizClipped ? `${el.scrollWidth}px wide vs ${el.clientWidth}px container` : `${el.scrollHeight}px tall vs ${el.clientHeight}px container`}). If this is intentional truncation, add a title attribute so the full text is reachable on hover.`,
bbox: bb(el) });
}
}
// 4. oversizedHeading — H1/H2 with fontSize > 36px on mobile
if (isMobile && (el.tagName === 'H1' || el.tagName === 'H2') && fs > 36) {
out.push({ issueType:'oversizedHeading', severity:'medium', selector:sel(el),
description:`${el.tagName} font-size ${fs}px exceeds 36px on mobile (viewport=${vw}px)`, bbox: bb(el) });
}
// 5. longWordNoBreak — leaf elements with a very long word that ACTUALLY
// overflows its container. A long word that fits (there's room, or it wraps,
// or the container scrolls) is NOT a defect, so we require the word's own
// rendered width to exceed the element's content box. We also:
// - require the element to be genuinely visible (not hidden/offscreen),
// - exempt code/pre/<a> URL displays and elements that opt into horizontal
// scrolling (overflow-x:auto|scroll) — breaking there would be WRONG.
if (el.children.length === 0) {
const text = el.innerText || '';
const words = text.split(/\s+/);
const longWord = words.find(w => w.length >= 25);
// visibility: must be on-screen and not visibility:hidden / opacity:0
const visible = r.width > 1 && r.height > 1 &&
s.visibility !== 'hidden' && parseFloat(s.opacity || '1') > 0.01 &&
r.bottom > 0 && r.right > 0 && r.top < innerHeight && r.left < vw;
// exemptions: code/pre/URL-display elements, and containers that opt into
// horizontal scrolling (the long word is meant to scroll, not break).
const tag = el.tagName;
const inCodeOrPre = tag === 'CODE' || tag === 'PRE' ||
!!el.closest('code,pre,kbd,samp,[class*="code" i],[class*="mono" i],[class*="url" i],[class*="hash" i],[class*="token" i]');
const scrolls = s.overflowX === 'auto' || s.overflowX === 'scroll' ||
s.overflow === 'auto' || s.overflow === 'scroll';
if (longWord && visible && !inCodeOrPre && !scrolls) {
const wb = s.wordBreak;
const ow = s.overflowWrap || s.wordWrap;
const allowsBreak = wb === 'break-all' || wb === 'break-word' ||
ow === 'anywhere' || ow === 'break-word';
if (!allowsBreak) {
// Measure the long word's actual rendered width and compare to the
// element's CONTENT box width (clientWidth minus horizontal padding).
let wordW = 0;
try {
const cv = document.createElement('canvas').getContext('2d');
cv.font = `${s.fontStyle} ${s.fontWeight} ${s.fontSize} ${s.fontFamily}`;
wordW = cv.measureText(longWord).width;
} catch (_) {}
const padL = parseFloat(s.paddingLeft) || 0;
const padR = parseFloat(s.paddingRight) || 0;
const contentW = el.clientWidth - padL - padR;
// REQUIRE real overflow: element actually scrolls horizontally AND the
// single long word is wider than the content box (so the word — not some
// sibling/padding — is what overflows). 4px tolerance for sub-pixel rounding.
const elOverflows = el.scrollWidth > el.clientWidth + 4;
const wordOverflows = wordW > contentW + 4;
if (elOverflows && wordOverflows && contentW > 0) {
out.push({ issueType:'longWordNoBreak', severity:'medium', selector:sel(el),
description:`Long word "${longWord.slice(0,30)}${longWord.length>30?'…':''}" (${longWord.length} chars, ~${Math.round(wordW)}px) overflows its ${Math.round(contentW)}px container with no word-break/overflow-wrap set`, bbox: bb(el) });
}
}
}
}
}
// 6. allCapsMicroLabel — ALL CAPS text at very small size (≤13px).
// Double readability penalty: all-caps removes ascender/descender variation AND
// tiny size reduces legibility. Common pattern in stat card labels: "TOTAL STUDENTS".
for (const el of document.querySelectorAll('span,p,label,div,h1,h2,h3,h4,h5,h6')) {
if (out.length >= 20) break;
const r = el.getBoundingClientRect();
if (r.width === 0 || r.height === 0) continue;
const text = (el.innerText || '').trim();
if (text.length < 3 || text.length > 60) continue;
const s = getComputedStyle(el);
const fs = parseFloat(s.fontSize);
if (fs > 13) continue;
const isUpperTransform = s.textTransform === 'uppercase';
const isAllCapsText = text === text.toUpperCase() && /[A-Z]/.test(text);
if (isUpperTransform || isAllCapsText) {
out.push({ issueType:'allCapsMicroLabel', severity:'medium', selector:sel(el),
description:`All-caps label "${text.slice(0,30)}" at ${fs}px — both small font and all-caps hurt readability. Use normal-case with font-weight:600 instead of all-caps, or increase font-size to ≥14px.`,
bbox: bb(el) });
}
}
// 7. metaLabelLowContrast — meta/sync/timestamp text that is both small AND light-colored.
// "Last synced: 8h ago" style labels tell users if data is stale — if styled with
// light gray at 10–11px they become nearly invisible on white backgrounds.
const META_PATTERN = /\b(sync(ed?|ing)?|last\s+(sync|update|refresh)|ago|updated?|refresh(ed)?|stale|live|online|offline)\b/i;
for (const el of document.querySelectorAll('span,p,small,div,label')) {
if (out.length >= 20) break;
const text = (el.innerText || '').trim();
if (!META_PATTERN.test(text) || text.length > 80) continue;
const r = el.getBoundingClientRect();
if (r.width === 0 || r.height === 0) continue;
const s = getComputedStyle(el);
const fs = parseFloat(s.fontSize);
if (fs > 13) continue;
const cm = (s.color || '').match(/rgba?\((\d+),\s*(\d+),\s*(\d+)/);
if (cm) {
const lum = (0.299 * +cm[1] + 0.587 * +cm[2] + 0.114 * +cm[3]) / 255;
if (lum > 0.55) {
out.push({ issueType:'metaLabelLowContrast', severity:'medium', selector:sel(el),
description:`Meta/sync label "${text.slice(0,40)}" is ${fs}px with light color (luminance ${lum.toFixed(2)}) — low contrast on white background. Increase font-size or darken text color for readability.`,
bbox: bb(el) });
}
}
}
return out;
}
Issues
| issueType | severity | description |
|---|---|---|
| smallFont | medium | "Typography issue on {sel}: {fontSize}px < 12px" |
| tightLineHeight | low | "Typography issue on {sel}: line-height/font-size = {ratio} < 1.2" |
| textClipped | low | "Typography issue on {sel}: Text clipped by overflow:hidden" |
| oversizedHeading | medium | "{tag} font-size {fs}px exceeds 36px on mobile" |
| longWordNoBreak | medium | "Long word ({n} chars) overflows container, no word-break/overflow-wrap" |
| allCapsMicroLabel | medium | "All-caps label '{text}' at {fs}px — both small size and all-caps hurt readability" |
| metaLabelLowContrast | medium | "Meta/sync label '{text}' is {fs}px with light color (luminance {n}) — low contrast on white background" |