qa-detect-ux-table-layout
Catches table layout UX bugs: header bar narrower than container (dead space on the right), header doesn't align with body columns, last column has header but no body cells, Actions column empty in ev
SKILL.mdskills/qa-detect-ux-table-layout/SKILL.md
GitHubWhat it catches — 7 issue types
| issueType | severity | What |
|---|---|---|
tableHeaderShortOfContainer |
medium | Table header bar is narrower than its container by > 16px — visible dead space on the right (your Departments page bug) |
tableLastColumnHasNoCells |
medium | Table has a trailing header column but ZERO matching body cells — phantom column |
tableHeaderBodyWidthMismatch |
low | Table header row total width differs from body row total width by > 8px — columns visually drift |
tableActionsColumnEmpty |
low | Header has "Actions" / "Operations" column but no row contains action buttons/icons |
tableNoStickyHeader |
low | Table with > 20 visible rows has no sticky header — users scroll past column labels |
tableNoZebraStriping |
low | Table with > 8 rows uses no alternating row background (zebra striping) — eye loses position |
tableEmptyHeaderCell |
low | Table has a header cell with no text, no aria-label, no icon — phantom column header |
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 = [];
const tables = [...document.querySelectorAll('table, [role="table"], [role="grid"]')].filter(visible);
let containerFlagged = 0, phantomColFlagged = 0, widthFlagged = 0,
actionsFlagged = 0, stickyFlagged = 0, zebraFlagged = 0, emptyHdrFlagged = 0;
for (const tbl of tables.slice(0, 5)) {
// ── 1. Header bar shorter than container ──────────────────────────────
if (containerFlagged < 3) {
const head = tbl.querySelector('thead, [role="rowgroup"]:first-child') || tbl.querySelector('thead');
const headRow = head ? head.querySelector('tr, [role="row"]') : tbl.querySelector('tr:first-child, [role="row"]:first-child');
if (headRow && visible(headRow)) {
const headR = headRow.getBoundingClientRect();
// Find the parent wrapper (often .table-wrapper or the immediate parent)
const wrap = tbl.closest('.table-wrapper, .table-container, .table-responsive, .data-table, .mat-table-container') || tbl.parentElement;
if (wrap && visible(wrap)) {
const wrapR = wrap.getBoundingClientRect();
// Only flag if there's significant unused space on the right
const deadSpace = wrapR.right - headR.right;
if (deadSpace > 16 && headR.width < wrapR.width * 0.95) {
containerFlagged++;
out.push({
issueType: 'tableHeaderShortOfContainer', severity: 'medium',
selector: sel(tbl), bbox: bb(tbl),
description: `Table header is ${headR.width.toFixed(0)}px wide but container is ${wrapR.width.toFixed(0)}px (${deadSpace.toFixed(0)}px dead space on right). Either expand columns to fill, or shrink container — current layout looks broken/cut.`
});
}
}
}
}
// ── 2 + 3. Last column has no cells / header-body width mismatch ─────
const headerCells = [...tbl.querySelectorAll('thead th, thead [role="columnheader"], [role="row"]:first-child > [role="columnheader"]')].filter(visible);
const bodyRows = [...tbl.querySelectorAll('tbody tr, [role="rowgroup"]:not(:first-child) [role="row"]')].filter(visible);
if (headerCells.length > 0 && bodyRows.length > 0) {
// 2. Trailing header with zero body cells in that column
if (phantomColFlagged < 2) {
const lastHdr = headerCells[headerCells.length - 1];
const lastHdrR = lastHdr.getBoundingClientRect();
// Count how many body rows have a cell in the last column's X range
let cellsInLastCol = 0;
for (const row of bodyRows.slice(0, 10)) {
const cells = [...row.querySelectorAll('td, [role="cell"], [role="gridcell"]')];
if (cells.length === 0) continue;
const lastCell = cells[cells.length - 1];
const cellR = lastCell.getBoundingClientRect();
// Cell sits under the last header (overlap > 50% of header width)
const overlap = Math.min(cellR.right, lastHdrR.right) - Math.max(cellR.left, lastHdrR.left);
if (overlap > lastHdrR.width * 0.5) cellsInLastCol++;
}
if (cellsInLastCol === 0) {
phantomColFlagged++;
const lastHdrText = (lastHdr.innerText || '').trim().slice(0, 40);
out.push({
issueType: 'tableLastColumnHasNoCells', severity: 'medium',
selector: sel(lastHdr), bbox: bb(lastHdr),
description: `Header column "${lastHdrText}" exists but no body row has a cell underneath it. Phantom column — either populate it or remove the header.`
});
}
}
// 3. Header total width vs body row width
if (widthFlagged < 2) {
const headRow = headerCells[0].parentElement;
const firstBodyRow = bodyRows[0];
if (headRow && firstBodyRow) {
const hr = headRow.getBoundingClientRect();
const br = firstBodyRow.getBoundingClientRect();
const widthDiff = Math.abs(hr.width - br.width);
if (widthDiff > 8 && Math.min(hr.width, br.width) > 100) {
widthFlagged++;
out.push({
issueType: 'tableHeaderBodyWidthMismatch', severity: 'low',
selector: sel(tbl), bbox: bb(tbl),
description: `Header row width ${hr.width.toFixed(0)}px vs body row width ${br.width.toFixed(0)}px (${widthDiff.toFixed(0)}px drift). Columns visually misaligned.`
});
}
}
}
}
// ── 4. Actions column has no buttons ─────────────────────────────────
if (actionsFlagged < 2 && headerCells.length > 0 && bodyRows.length > 0) {
const actionsHdr = headerCells.find(h => /^(actions?|operations?|do|controls?)$/i.test((h.innerText || '').trim()));
if (actionsHdr) {
const actHdrR = actionsHdr.getBoundingClientRect();
let actionsFound = 0;
for (const row of bodyRows.slice(0, 10)) {
const cells = [...row.querySelectorAll('td, [role="cell"]')];
for (const c of cells) {
const cellR = c.getBoundingClientRect();
const overlap = Math.min(cellR.right, actHdrR.right) - Math.max(cellR.left, actHdrR.left);
if (overlap > actHdrR.width * 0.5) {
if (c.querySelector('button, a, [role="button"], svg, i')) actionsFound++;
break;
}
}
}
if (actionsFound === 0) {
actionsFlagged++;
out.push({
issueType: 'tableActionsColumnEmpty', severity: 'low',
selector: sel(actionsHdr), bbox: bb(actionsHdr),
description: `"Actions" column header exists but no row contains action buttons / icons. Empty column.`
});
}
}
}
// ── 5. Long table without sticky header ──────────────────────────────
if (stickyFlagged < 2 && bodyRows.length > 20) {
const head = tbl.querySelector('thead');
if (head) {
const cs = getComputedStyle(head);
const pos = cs.position;
if (pos !== 'sticky' && pos !== 'fixed') {
stickyFlagged++;
out.push({
issueType: 'tableNoStickyHeader', severity: 'low',
selector: sel(tbl), bbox: bb(tbl),
description: `Table with ${bodyRows.length} rows has no sticky/fixed header. Users scroll past column labels and lose context.`
});
}
}
}
// ── 6. Long table without zebra striping ─────────────────────────────
if (zebraFlagged < 2 && bodyRows.length > 8) {
const r0 = bodyRows[0];
const r1 = bodyRows[1];
if (r0 && r1) {
const bg0 = getComputedStyle(r0).backgroundColor;
const bg1 = getComputedStyle(r1).backgroundColor;
// Identical AND not transparent → no striping
if (bg0 === bg1 && !/(transparent|rgba\(.*,\s*0\))/i.test(bg0)) {
zebraFlagged++;
out.push({
issueType: 'tableNoZebraStriping', severity: 'low',
selector: sel(tbl), bbox: bb(tbl),
description: `Table with ${bodyRows.length} rows has uniform row background (${bg0}). Add nth-child striping for readability.`
});
}
}
}
// ── 7. Empty header cell (no text, no aria-label, no icon) ───────────
if (emptyHdrFlagged < 2) {
for (const h of headerCells) {
const text = (h.innerText || '').trim();
const ariaLabel = (h.getAttribute('aria-label') || '').trim();
const hasIcon = !!h.querySelector('svg, i, img');
if (text.length === 0 && ariaLabel.length === 0 && !hasIcon) {
emptyHdrFlagged++;
out.push({
issueType: 'tableEmptyHeaderCell', severity: 'low',
selector: sel(h), bbox: bb(h),
description: `Empty table header cell — no text, no aria-label, no icon. Phantom column with no purpose.`
});
break;
}
}
}
}
return out;
}
Notes
- Bounded: 3 header-container + 2 phantom + 2 width-drift + 2 actions + 2 sticky + 2 zebra + 2 empty-hdr = max ~15 findings
- Self-skips: page with no tables returns []
- The
tableHeaderShortOfContaineris the EXACT bug from the user's Departments screenshot (red box on right side of header) - Viewport-sensitive: layout issues manifest differently at mobile/tablet/desktop widths