qa-detect-reflow
WCAG 1.4.10 — detects content that requires horizontal scroll at 320px, fixed-width elements, non-shrinking tables, and oversized images. Runs as ONE in-page async probe (no AI hand-driving).
SKILL.mdskills/qa-detect-reflow/SKILL.md
GitHubHow the orchestrator runs this (ONE call — no hand-driving)
🚨 This skill is an EXECUTABLE in-page probe, not a prose playbook. Do NOT drive it with a browser_resize + separate scan. Instead make ONE call:
result = browser_evaluate(<the async function in "## Interactive Probe" below>)
WCAG 1.4.10 (Reflow) requires content to be presentable at 320 CSS pixels wide without horizontal scrolling. This skill is applyOn: [mobile], so it already runs on a small viewport. Rather than do a real browser_resize(320, 568) (a costly extra round-trip that perturbs every later skill in the cell), the probe measures everything against the 320px reflow threshold in-page: it flags fixed-width / non-shrinking / oversized elements whose geometry would force horizontal scroll at 320px, plus any actual page-level horizontal scroll at the current mobile width. It returns findings[] in one round-trip and changes no DOM/viewport state. Transcribe each returned finding verbatim into the cell JSONL; add only the envelope fields (runId, cellId, route, viewport, …).
Interactive Probe (browser_evaluate, async)
async () => {
const out = [];
const VP = 320; // WCAG 1.4.10 reflow threshold
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) }; };
// 1. Page-level horizontal scroll — primary reflow violation.
// Flag if the document already overflows the current (mobile) viewport,
// OR if its content box is wider than the 320px reflow threshold.
const docW = document.documentElement.scrollWidth;
if (docW > Math.max(VP, window.innerWidth) + 2) {
out.push({ skill: 'qa-detect-reflow', issueType: 'reflowHorizontalScroll', severity: 'high', selector: 'html',
description: `Page content is ${docW}px wide and exceeds the 320px reflow threshold — requires horizontal scroll at 320px viewport (WCAG 1.4.10 Reflow violation)`,
bbox: { x: 0, y: 0, w: Math.min(320, window.innerWidth), h: Math.min(80, window.innerHeight) } });
}
// 2. Tables that won't fit 320px (fixed/non-shrinking content wider than 320)
for (const tbl of document.querySelectorAll('table')) {
if (out.length >= 15) break;
const r = tbl.getBoundingClientRect();
if (r.width === 0 && r.height === 0) continue;
if (tbl.scrollWidth > VP + 2) {
out.push({ skill: 'qa-detect-reflow', issueType: 'tableNotResponsive', severity: 'high', selector: sel(tbl),
description: `Table ${sel(tbl)} has ${Math.round(tbl.scrollWidth)}px of content and won't fit a 320px viewport — wrap in overflow-x:auto container or use stacked-row pattern`,
bbox: bb(tbl) });
}
}
// 3. Images that exceed 320px without a responsive max-width (likely missing max-width:100%)
for (const img of document.querySelectorAll('img')) {
if (out.length >= 15) break;
const r = img.getBoundingClientRect();
if (r.width === 0 && r.height === 0) continue;
const natural = img.naturalWidth || 0;
const effWidth = Math.max(r.width, natural);
if (effWidth > VP + 2) {
const style = getComputedStyle(img);
const responsive = style.maxWidth === '100%' || style.maxWidth.includes('%') || style.width.includes('%');
if (!responsive) {
out.push({ skill: 'qa-detect-reflow', issueType: 'imageNotResponsive', severity: 'medium', selector: sel(img),
description: `Image ${sel(img)} is ${Math.round(effWidth)}px and lacks a relative max-width — overflows a 320px viewport. Add max-width:100% or use srcset/picture`,
bbox: bb(img) });
}
}
}
// 4. Block elements with an AUTHOR-SET fixed px width that ACTUALLY overflows.
//
// ROOT-CAUSE FIX: getComputedStyle(el).width returns the *resolved used*
// width in px for EVERY block element, so `width:100%` on a 360px viewport
// reports "360px" — endsWith('px') does NOT mean the author set a fixed
// width. We must read the element's OWN inline/declared width and confirm
// it is a non-relative px (or absolute) value, AND that it does not shrink
// (max-width that caps it), AND that it actually causes horizontal overflow
// the user hits, AND that it is rendered (not in a closed drawer), AND that
// it is not inside an intentionally horizontally-scrollable container.
const REL = /(%|vw|vmin|vmax|auto|calc)/i; // relative/fluid → not a fixed-width defect
const isRenderedR = (el) => {
const s = getComputedStyle(el);
if (s.display === 'none' || s.visibility === 'hidden' || s.visibility === 'collapse') return false;
if (parseFloat(s.opacity || '1') === 0) return false;
if (el.closest('[aria-hidden="true"],[hidden],[inert]')) return false;
const r = el.getBoundingClientRect();
if (r.width === 0 || r.height === 0) return false;
if (r.right <= 0 || r.bottom <= 0) return false; // off-canvas (closed drawer)
return true;
};
// True if el sits inside a container that scrolls horizontally on purpose.
const inScrollContainer = (el) => {
let p = el.parentElement;
while (p && p !== document.documentElement) {
const ox = getComputedStyle(p).overflowX;
if (ox === 'auto' || ox === 'scroll') return true;
p = p.parentElement;
}
return false;
};
const blockTags = ['div', 'section', 'article', 'header', 'footer', 'main', 'nav', 'aside', 'form', 'fieldset'];
for (const el of document.querySelectorAll(blockTags.join(','))) {
if (out.length >= 20) break;
const style = getComputedStyle(el);
// (a) Author actually declared a fixed, non-relative width.
// Prefer the inline style; fall back to the cascaded declaration only
// when it is clearly a fixed px (not a resolved % / auto / calc).
const declared = (el.style && el.style.width) ? el.style.width : '';
const minW = style.minWidth || '';
let fixedPx = 0;
if (declared && declared.endsWith('px') && !REL.test(declared)) {
fixedPx = parseFloat(declared);
} else if (minW.endsWith('px') && !REL.test(minW) && parseFloat(minW) > VP + 2) {
// A min-width larger than the reflow threshold also prevents shrinking.
fixedPx = parseFloat(minW);
}
if (!fixedPx || fixedPx <= VP + 2) continue;
// (b) A max-width that caps the element at/under 320px means it DOES shrink → not a defect.
const maxW = style.maxWidth || '';
if (maxW && maxW !== 'none' && (maxW.includes('%') || (maxW.endsWith('px') && parseFloat(maxW) <= VP + 2))) continue;
// (c) Must be visible to a real user.
if (!isRenderedR(el)) continue;
// (d) Must ACTUALLY cause horizontal overflow the user hits: its right edge
// extends past the current viewport, OR its used width still exceeds 320px
// AND the page itself overflows horizontally.
const r = el.getBoundingClientRect();
const overflowsViewport = r.right > window.innerWidth + 2;
const widerThanReflow = r.width > VP + 2 && document.documentElement.scrollWidth > window.innerWidth + 2;
if (!overflowsViewport && !widerThanReflow) continue;
// (e) Exempt content inside an intentionally horizontal-scroll container.
if (inScrollContainer(el)) continue;
out.push({ skill: 'qa-detect-reflow', issueType: 'fixedWidthOverflow', severity: 'medium', selector: sel(el),
description: `Element ${sel(el)} has an author-set fixed width (${declared || minW}) of ${Math.round(fixedPx)}px exceeding the 320px reflow threshold and overflows the viewport — convert to %, rem, em, or use max-width`,
bbox: bb(el) });
}
return out;
}
Issues
| issueType | severity | description |
|---|---|---|
| reflowHorizontalScroll | high | "Page requires horizontal scroll at 320px width — WCAG 1.4.10 violation" |
| tableNotResponsive | high | "Table {selector} overflows 320px viewport — wrap in overflow-x:auto or use stacked rows" |
| imageNotResponsive | medium | "Image {selector} too wide at 320px — add max-width:100% or srcset" |
| fixedWidthOverflow | medium | "Element {selector} has fixed px width exceeding 320px — use relative units" |
Notes on this conversion
- The old
captureOriginalSize → browser_resize(320) → scanReflow → browser_resize(restore)flow is folded into ONE asyncbrowser_evaluatecall. Per the conversion brief, reflow is measured against the 320px threshold in-page using the existing (mobile) viewport rather than doing a real resize — checking fixed-width / non-shrinking / oversized geometry that would force horizontal scroll at 320px. Same issueTypes. applyOn: [mobile]— runs only on the mobile viewport cell. No viewport state is changed, so it does not perturb downstream skills.- The orchestrator already has native-viewport overflow detection via
qa-detect-overflow; this skill is specifically the 320px reflow gate.