qa-detect-ux-icons
Catches icon UX problems: icon-only buttons without tooltip, icons without accessible labels, ambiguous icon meaning, oversized/undersized icons, icon-text gap inconsistency. Goes beyond qa-detect-a11
SKILL.mdskills/qa-detect-ux-icons/SKILL.md
GitHubWhat it catches — 9 issue types
| issueType | severity | What |
|---|---|---|
iconButtonNoTooltip |
high | Icon-only button (no visible text) has no title attribute AND no tooltip element nearby — sighted users have no way to know what it does |
iconAmbiguousMeaning |
medium | Icon-only button uses an ambiguous symbol (3 dots, arrows, generic shapes) with no label or tooltip — purpose unclear |
iconUndersized |
low | Icon visible but rendered < 12px square — too small to recognize at a glance |
iconAspectExtreme |
high | Icon rendered with extreme aspect ratio (>3:1 or <1:3) — looks squashed/sliver-like instead of square. Indicates CSS width/height bug or broken SVG dimensions |
iconClippedInButton |
high | Icon inside a button is < 25% of the button's height (e.g. 8px icon in a 60px button) — visually a tiny dot/sliver above text. Indicates parent overflow:hidden, missing icon font-size, or wrong SVG sizing |
iconOversized |
low | Decorative icon > 64px square — wastes screen real estate especially on mobile |
iconTextGapInconsistent |
low | Icons next to text labels use inconsistent gaps (some 4px, some 12px) across the same view |
iconDuplicatedMeaning |
low | Same icon (same SVG path or class) used for two different actions on the same page |
iconColorAmbiguous |
medium | Icon used as status indicator (red/green/yellow) without text alternative — color-blind users can't decode it |
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') return false;
const r = el.getBoundingClientRect();
return r.width > 0 && r.height > 0;
};
const out = [];
// Find all icon-only buttons (button/a with no text but contains svg/i/img)
const interactives = document.querySelectorAll('button, a[href], [role="button"], input[type="button"], input[type="submit"]');
let nooTooltipFlagged = 0, ambiguousFlagged = 0;
const ambiguousIcons = /^(more|menu|kebab|dots|three-dots|ellipsis|arrow|chevron|caret|swap|exchange|sort)$/i;
// Skip elements that are clearly logos / brand glyphs / home links — these are NOT
// "icon-only action buttons" even when they have only an image inside.
const isLogoOrBrandLink = (el) => {
// (a) href points to home/root
const href = (el.getAttribute('href') || '').trim();
if (href === '/' || href === '#' || href === '/home' || href === '/dashboard' || href === '#/') return true;
// (b) any ancestor up to 4 levels has a logo/brand-shaped class
if (el.closest('[class*="logo"], [class*="Logo"], [class*="brand"], [class*="Brand"], [class*="navbar-brand"], [class*="sidebar-brand"], [class*="app-bar"], [class*="appbar"]')) return true;
// (c) the inner image is a logo (alt text or src filename)
const inner = el.querySelector('img, svg');
if (inner) {
const alt = (inner.getAttribute('alt') || '').toLowerCase();
const src = (inner.getAttribute('src') || '').toLowerCase();
if (/^(logo|brand|favicon|app\s*logo|site\s*logo)\b/.test(alt)) return true;
if (/\/(logo|brand|favicon)[-_]?[\w-]*\.(png|jpe?g|svg|webp)/.test(src)) return true;
const cls = ((inner.className && typeof inner.className === 'string') ? inner.className : '').toLowerCase();
if (/\b(logo|brand|favicon)\b/.test(cls)) return true;
}
// (d) link is positioned in the top-left of the page AND contains an image (classic logo slot)
const r = el.getBoundingClientRect();
if (r.left < 240 && r.top < 80 && el.querySelector('img, svg')) {
// Top-left corner of a typical sidebar/header layout → almost always a logo
return true;
}
return false;
};
for (const el of interactives) {
if (!visible(el)) continue;
if (isLogoOrBrandLink(el)) continue; // skip site logo / brand link
const text = (el.innerText || el.value || '').trim();
const ariaLabel = (el.getAttribute('aria-label') || '').trim();
const ariaLabelledBy = (el.getAttribute('aria-labelledby') || '').trim();
const title = (el.getAttribute('title') || '').trim();
if (text.length > 0) continue; // has visible text — not icon-only
if (ariaLabelledBy) continue; // labeled via reference
const icons = el.querySelectorAll('svg, i.fa, i.material-icons, i[class*="icon"], img');
if (icons.length === 0) continue; // not icon button
const iconClass = [...icons].map(i => i.className.toString()).join(' ');
const ariaHidden = el.getAttribute('aria-hidden') === 'true';
// 1. iconButtonNoTooltip — no aria-label AND no title AND no aria-describedby
if (!ariaLabel && !title && !ariaHidden) {
if (nooTooltipFlagged < 6) {
nooTooltipFlagged++;
out.push({
issueType: 'iconButtonNoTooltip', severity: 'high',
selector: sel(el), bbox: bb(el),
description: `Icon-only ${el.tagName.toLowerCase()} has no aria-label, no title, no nearby tooltip. Sighted users can't discover the action; screen readers announce it as unnamed.`
});
}
continue;
}
// 2. iconAmbiguousMeaning — has label but icon class matches ambiguous pattern AND label is generic
if (ambiguousFlagged < 4) {
const labelLow = (ariaLabel || title).toLowerCase();
const looksAmbiguous = ambiguousIcons.test(iconClass.replace(/.*[ -](\w+)$/, '$1'));
const labelIsGeneric = /^(button|action|more|menu|click|open)$/.test(labelLow);
if (looksAmbiguous && labelIsGeneric) {
ambiguousFlagged++;
out.push({
issueType: 'iconAmbiguousMeaning', severity: 'medium',
selector: sel(el), bbox: bb(el),
description: `Icon ${iconClass.slice(0, 40)} has generic label "${labelLow}" — users won't know what action it triggers.`
});
}
}
}
// 3 + 4. Icon size — find all visible <svg> + <i>+ <img class*="icon">
const iconEls = document.querySelectorAll('svg, i[class*="icon"], i.fa, i.material-icons, img[class*="icon"], img[alt=""]');
let sizeFlagged = 0;
let aspectFlagged = 0;
let clippedFlagged = 0;
for (const ic of iconEls) {
if (sizeFlagged >= 4 && aspectFlagged >= 4 && clippedFlagged >= 4) break;
if (!visible(ic)) continue;
const r = ic.getBoundingClientRect();
const dim = Math.min(r.width, r.height);
// 3a. iconUndersized — both dimensions tiny
if (dim < 12 && sizeFlagged < 4) {
sizeFlagged++;
out.push({
issueType: 'iconUndersized', severity: 'low',
selector: sel(ic), bbox: bb(ic),
description: `Icon rendered at ${r.width.toFixed(0)}×${r.height.toFixed(0)}px — too small to read at a glance. Use ≥16px for UI icons.`
});
continue;
}
// 3b. iconAspectExtreme — squashed/stretched (e.g. 16×4 or 4×16) — clearly broken rendering
if (r.width > 0 && r.height > 0 && aspectFlagged < 4) {
const ratio = r.width / r.height;
if (ratio > 3 || ratio < 0.33) {
aspectFlagged++;
out.push({
issueType: 'iconAspectExtreme', severity: 'high',
selector: sel(ic), bbox: bb(ic),
description: `Icon rendered ${r.width.toFixed(0)}×${r.height.toFixed(0)}px (aspect ${ratio.toFixed(2)}:1) — icons should be roughly square. Likely a CSS height/width bug squashing the icon. Visible icon looks like a sliver instead of a recognizable shape.`
});
continue;
}
}
// 3c. iconClippedInButton — small icon (< 16px tall) inside a tall button (>= 50px)
// where icon takes < 20% of button height — clear visual mismatch, button looks like
// it has a dot/sliver above the text instead of a real icon.
if (clippedFlagged < 4 && r.height < 16 && r.height >= 3) {
const btn = ic.closest('button, a[href], [role="button"], .btn, [class*="quick-action"]');
if (btn && btn !== ic) {
const br = btn.getBoundingClientRect();
if (br.height >= 50 && r.height / br.height < 0.20) {
clippedFlagged++;
out.push({
issueType: 'iconClippedInButton', severity: 'high',
selector: sel(ic), bbox: bb(ic),
description: `Icon is only ${r.height.toFixed(0)}px tall inside a ${br.height.toFixed(0)}px button (${((r.height/br.height)*100).toFixed(0)}% of button height). Icon appears clipped or undersized — looks like a sliver/dot instead of a clear icon. Check for parent overflow:hidden with too-small height, missing icon font-size, or broken SVG dimensions.`
});
continue;
}
}
}
// 4. iconOversized — decorative icon way too big
if (r.width > 64 && r.height > 64 && !ic.closest('button, a, [role="button"]') && sizeFlagged < 4) {
sizeFlagged++;
out.push({
issueType: 'iconOversized', severity: 'low',
selector: sel(ic), bbox: bb(ic),
description: `Decorative icon ${r.width.toFixed(0)}×${r.height.toFixed(0)}px — wastes screen space especially on mobile.`
});
}
}
// 5. Icon-text gap inconsistency — buttons with text+icon
const iconTextButtons = [...document.querySelectorAll('button, a[href]')].filter(b => {
if (!visible(b)) return false;
const hasIcon = b.querySelector('svg, i[class*="icon"], i.fa, i.material-icons, img');
const text = (b.innerText || '').trim();
return hasIcon && text.length > 0;
});
if (iconTextButtons.length >= 4) {
const gaps = new Map();
for (const b of iconTextButtons) {
const cs = getComputedStyle(b);
// Use gap property (flex/grid) OR padding+icon-margin heuristic
let gap = parseFloat(cs.gap) || parseFloat(cs.columnGap);
if (isNaN(gap) || gap === 0) {
// Fallback: measure space between icon and first text node
const ic = b.querySelector('svg, i, img');
if (ic) {
const ir = ic.getBoundingClientRect();
const br = b.getBoundingClientRect();
gap = Math.round(Math.abs(ir.right - br.left - parseFloat(cs.paddingLeft) || 0));
}
}
const rounded = Math.round(gap / 2) * 2;
gaps.set(rounded, (gaps.get(rounded) || 0) + 1);
}
if (gaps.size >= 3) {
const values = [...gaps.keys()].sort((a, b) => a - b);
out.push({
issueType: 'iconTextGapInconsistent', severity: 'low',
selector: 'body', description: `Icon-to-text gap varies across buttons: ${values.join('px, ')}px. Inconsistent spacing reads as sloppy design.`
});
}
}
// 6. Icon duplicated meaning — count uses of each unique icon class signature
const iconSigs = new Map();
for (const ic of iconEls) {
if (!visible(ic)) continue;
let sig = '';
if (ic.tagName === 'SVG') {
const path = ic.querySelector('path');
sig = (ic.getAttribute('viewBox') || '') + '|' + (path ? (path.getAttribute('d') || '').slice(0, 50) : '');
} else {
sig = ic.className.toString();
}
if (!sig || sig.length < 4) continue;
// Get the parent action label
const parent = ic.closest('button, a, [role="button"]');
const label = parent ? ((parent.getAttribute('aria-label') || parent.getAttribute('title') || parent.innerText || '').trim().toLowerCase().slice(0, 40)) : '';
if (!label) continue;
if (!iconSigs.has(sig)) iconSigs.set(sig, new Set());
iconSigs.get(sig).add(label);
}
let dupFlagged = 0;
for (const [sig, labels] of iconSigs) {
if (dupFlagged >= 2) break;
if (labels.size >= 2) {
dupFlagged++;
out.push({
issueType: 'iconDuplicatedMeaning', severity: 'low',
selector: 'body', description: `Same icon used for different actions: ${[...labels].slice(0, 3).join(' / ')}. Users will conflate them.`
});
}
}
// 7. Color-only status icon — icons with red/green/yellow color and no nearby text
const statusIcons = document.querySelectorAll('svg, i, span[class*="status"], span[class*="badge"], [class*="indicator"]');
let colorFlagged = 0;
for (const ic of statusIcons) {
if (colorFlagged >= 3) break;
if (!visible(ic)) continue;
const cs = getComputedStyle(ic);
const color = cs.color || cs.fill || cs.backgroundColor;
// Detect red/green/yellow-ish status colors
const m = color.match(/rgb\((\d+),\s*(\d+),\s*(\d+)\)/);
if (!m) continue;
const [r, g, b] = [+m[1], +m[2], +m[3]];
const isStatusColor = (r > 180 && g < 100 && b < 100) || // red
(g > 150 && r < 120 && b < 120) || // green
(r > 200 && g > 150 && b < 100); // yellow
if (!isStatusColor) continue;
const parent = ic.parentElement;
const sibText = parent ? (parent.innerText || '').trim() : '';
if (sibText.length < 2 || sibText.length > 50) {
// No nearby text label
const r2 = ic.getBoundingClientRect();
if (r2.width < 32 && r2.height < 32) { // small status indicator
colorFlagged++;
out.push({
issueType: 'iconColorAmbiguous', severity: 'medium',
selector: sel(ic), bbox: bb(ic),
description: `Status icon uses color (rgb ${r},${g},${b}) with no adjacent text label. Color-blind users can't tell the state.`
});
}
}
}
return out;
}
Notes
- Self-skips: page with no icons / no icon-only buttons returns []
- Bounded: 6 noTooltip + 4 ambiguous + 4 size + 1 gap + 2 dup + 3 color-only = max ~20 findings
- The
iconButtonNoTooltipcheck is the highest-value: every icon-only button without tooltip is a UX failure for sighted users (a11y skill catches the screen-reader half; this catches the discovery half)