qa-detect-ux-nav-icons
Detects nav/sidebar/tab consistency issues: icons mixed with iconless items, icon size variance across siblings, icon style mix (filled/outlined/colored), label-icon vertical misalignment, missing act
SKILL.mdskills/qa-detect-ux-nav-icons/SKILL.md
GitHubWhat it catches — 7 issue types
| issueType | severity | What |
|---|---|---|
navItemIconInconsistent |
medium | Sibling nav/tab items in same list: some have icons, others don't — visual rhythm broken |
navItemIconSizeInconsistent |
low | Sibling nav items have icons with differing rendered sizes (> 4px delta) |
navItemIconStyleInconsistent |
low | Sibling nav items mix icon styles (filled + outlined, colored + monochrome) |
navItemLabelIconMisaligned |
low | Nav item's label and icon are vertically misaligned (> 4px diff between icon center and label baseline) |
navItemLabelTruncated |
medium | Nav item label is visually truncated with no title attribute / no tooltip — user can't read it |
navItemActiveStateMissing |
medium | Nav list has a clearly-active page (URL match) but the corresponding nav item has no visible distinguishing style |
navItemHeightInconsistent |
low | Sibling nav items have differing heights (> 4px delta) — visual asymmetry |
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 nav containers
const navContainers = document.querySelectorAll('nav, [role="navigation"], .sidebar, .side-nav, .nav-menu, [role="tablist"], .mat-tab-list, ul.nav, ul.menu, ul.list-group, .nav-list, [class*="sidenav"]');
let containers = [...navContainers].filter(visible).slice(0, 4);
for (const nav of containers) {
// Find sibling nav items — direct children that are clickable list items
let items = [...nav.querySelectorAll(':scope > li, :scope > a, :scope > [role="tab"], :scope > [role="menuitem"], :scope > .nav-item, :scope > .menu-item, :scope > .sidebar-item')]
.filter(visible);
// If no direct children, look one level deeper
if (items.length < 2) {
items = [...nav.querySelectorAll('li, a.nav-link, [role="tab"], [role="menuitem"], .nav-item, .menu-item, .sidebar-item, .mat-list-item, [class*="nav-item"], [class*="menu-item"], [class*="sidebar-item"]')]
.filter(visible).slice(0, 12);
}
// Last resort for generic nav containers: direct child divs/buttons that look item-shaped
if (items.length < 2) {
items = [...nav.children]
.filter(c => visible(c) && (c.tagName === 'DIV' || c.tagName === 'BUTTON' || c.tagName === 'A'))
.filter(c => {
const txt = (c.innerText || '').trim();
return txt.length > 1 && txt.length < 80;
})
.slice(0, 12);
}
if (items.length < 3) continue; // need ≥3 to spot inconsistency
// ── 1. Icon present/absent inconsistency ─────────────────────────────
const iconCounts = items.map(it => {
const icons = it.querySelectorAll('svg, i.fa, i.material-icons, i[class*="icon"], img');
return [...icons].filter(visible).length;
});
const withIcon = iconCounts.filter(n => n > 0).length;
const withoutIcon = items.length - withIcon;
if (withIcon > 0 && withoutIcon > 0 && withIcon !== items.length && withoutIcon !== items.length) {
// Mixed — but only flag if substantial (>= 2 of each side)
if (withIcon >= 2 && withoutIcon >= 2) {
out.push({
issueType: 'navItemIconInconsistent', severity: 'medium',
selector: sel(nav), bbox: bb(nav),
description: `Nav list has ${items.length} items: ${withIcon} with icons, ${withoutIcon} without. Inconsistent — either icon every item or none.`
});
}
}
// ── 2. Icon size variance among items WITH icons ─────────────────────
const iconSizes = [];
for (const it of items) {
const ic = it.querySelector('svg, i.fa, i.material-icons, i[class*="icon"], img');
if (!ic || !visible(ic)) continue;
const r = ic.getBoundingClientRect();
iconSizes.push({ size: Math.round(Math.max(r.width, r.height)), item: it, icon: ic });
}
if (iconSizes.length >= 3) {
const sizes = iconSizes.map(s => s.size);
const sizeDelta = Math.max(...sizes) - Math.min(...sizes);
if (sizeDelta >= 5) {
out.push({
issueType: 'navItemIconSizeInconsistent', severity: 'low',
selector: sel(nav), bbox: bb(nav),
description: `Nav icons range ${Math.min(...sizes)}-${Math.max(...sizes)}px across ${iconSizes.length} items (${sizeDelta}px variance). Use one icon size.`
});
}
}
// ── 3. Icon style mix (filled vs outlined) — best-effort heuristic ───
if (iconSizes.length >= 3) {
const styles = new Set();
for (const { icon } of iconSizes) {
const cls = icon.className.toString().toLowerCase();
const tag = icon.tagName.toLowerCase();
let style = 'other';
if (cls.includes('fa-solid') || cls.includes('-fill') || cls.includes('solid')) style = 'filled';
else if (cls.includes('fa-regular') || cls.includes('-outline') || cls.includes('outline')) style = 'outlined';
else if (tag === 'svg') {
// Check fill vs stroke
const path = icon.querySelector('path');
if (path) {
const fill = path.getAttribute('fill') || icon.getAttribute('fill') || '';
const stroke = path.getAttribute('stroke') || icon.getAttribute('stroke') || '';
if (fill && fill !== 'none' && (!stroke || stroke === 'none')) style = 'filled';
else if (stroke && stroke !== 'none' && (!fill || fill === 'none')) style = 'outlined';
}
}
styles.add(style);
}
styles.delete('other');
if (styles.size >= 2) {
out.push({
issueType: 'navItemIconStyleInconsistent', severity: 'low',
selector: sel(nav), bbox: bb(nav),
description: `Nav icons mix styles: ${[...styles].join(' + ')}. Pick one (filled OR outlined) for visual coherence.`
});
}
}
// ── 4. Label-icon vertical misalignment ──────────────────────────────
let misalignFlagged = 0;
for (const it of items) {
if (misalignFlagged >= 2) break;
const ic = it.querySelector('svg, i.fa, i.material-icons, i[class*="icon"], img');
if (!ic || !visible(ic)) continue;
// Find first text node inside the item
const txt = (it.innerText || '').trim();
if (txt.length < 2) continue;
const labelSpan = [...it.querySelectorAll('span, label, .label, .nav-text')].find(s => visible(s) && (s.innerText || '').trim().length > 0);
const label = labelSpan || it;
const ir = ic.getBoundingClientRect();
const lr = label.getBoundingClientRect();
const iconCenterY = ir.top + ir.height / 2;
const labelCenterY = lr.top + lr.height / 2;
const drift = Math.abs(iconCenterY - labelCenterY);
if (drift > 4 && ir.height > 12 && lr.height > 12) {
misalignFlagged++;
out.push({
issueType: 'navItemLabelIconMisaligned', severity: 'low',
selector: sel(it), bbox: bb(it),
description: `Nav item "${txt.slice(0, 30)}" — icon center is ${drift.toFixed(0)}px off label center. Use flex align-items: center.`
});
}
}
// ── 5. Label truncation without tooltip ──────────────────────────────
let truncFlagged = 0;
for (const it of items) {
if (truncFlagged >= 3) break;
const labelSpan = [...it.querySelectorAll('span, .label, .nav-text')].find(s => visible(s) && (s.innerText || '').trim().length > 0) || it;
if (labelSpan.scrollWidth > labelSpan.clientWidth + 2) {
const cs = getComputedStyle(labelSpan);
if (cs.textOverflow === 'ellipsis' || cs.overflow === 'hidden') {
const hasTooltip = it.getAttribute('title') || it.getAttribute('aria-label') || labelSpan.getAttribute('title');
if (!hasTooltip) {
truncFlagged++;
const fullText = (labelSpan.innerText || '').trim();
out.push({
issueType: 'navItemLabelTruncated', severity: 'medium',
selector: sel(it), bbox: bb(it),
description: `Nav item label "${fullText.slice(0, 30)}..." is truncated with ellipsis and no title/aria-label tooltip. User can't read full label.`
});
}
}
}
}
// ── 6. Active-state indicator missing ────────────────────────────────
const currentPath = location.pathname.toLowerCase();
let activeMissingFlagged = 0;
if (activeMissingFlagged < 1) {
// Find item whose href matches current path
const matchingItem = items.find(it => {
const a = it.tagName === 'A' ? it : it.querySelector('a[href]');
if (!a) return false;
const href = a.getAttribute('href') || '';
return href.length > 1 && currentPath.endsWith(href.toLowerCase().replace(/^\/+/, '/'));
});
if (matchingItem) {
const cs = getComputedStyle(matchingItem);
const hasActiveClass = /\b(active|selected|current|is-active|router-link-active)\b/.test(matchingItem.className.toString());
const hasAriaCurrent = matchingItem.getAttribute('aria-current');
// Compare background to sibling — distinct background = active state shown
const sibling = items.find(it => it !== matchingItem);
let hasDistinctBg = false;
if (sibling) {
const sibCs = getComputedStyle(sibling);
if (cs.backgroundColor !== sibCs.backgroundColor || cs.color !== sibCs.color || cs.fontWeight !== sibCs.fontWeight) {
hasDistinctBg = true;
}
}
if (!hasActiveClass && !hasAriaCurrent && !hasDistinctBg) {
activeMissingFlagged++;
out.push({
issueType: 'navItemActiveStateMissing', severity: 'medium',
selector: sel(matchingItem), bbox: bb(matchingItem),
description: `Nav item matches current URL (${currentPath}) but has no .active class, no aria-current, no distinguishing background/color. Users can't tell which page they're on.`
});
}
}
}
// ── 7. Item height inconsistency ─────────────────────────────────────
const heights = items.map(it => Math.round(it.getBoundingClientRect().height));
if (heights.length >= 3) {
const hDelta = Math.max(...heights) - Math.min(...heights);
if (hDelta >= 5 && Math.max(...heights) > 0) {
out.push({
issueType: 'navItemHeightInconsistent', severity: 'low',
selector: sel(nav), bbox: bb(nav),
description: `Nav items heights range ${Math.min(...heights)}-${Math.max(...heights)}px (${hDelta}px variance). Set uniform line-height/padding.`
});
}
}
}
return out;
}
Notes
- Bounded: max ~14 findings (1-3 per container × 4 containers)
- Self-skips: page with no nav containers returns []
- The
navItemIconInconsistent+navItemIconSizeInconsistentcatch the exact bug pattern from the user's sidebar screenshot (Administrative Units with icon, Departments without — or with different icon size/style) - The
navItemActiveStateMissingis the highest-impact: it tells users "you're on the wrong page" until they figure out where they are