qa-detect-rtl-layout
Switches the document to RTL (dir='rtl') and detects layout breakage — overflow, mirrored asymmetry, and non-logical CSS properties that don't flip. Runs as ONE in-page async probe (no AI hand-driving
SKILL.mdskills/qa-detect-rtl-layout/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 separate browser_evaluate round-trips for apply/scan/restore. Instead make ONE call:
result = browser_evaluate(<the async function in "## Interactive Probe" below>)
The function captures the baseline, flips document.documentElement.dir = 'rtl', waits in-page for CSS to recompute, scans for new overflow + side-anchoring bugs, restores the original direction, and returns findings[] — all inside the page, in one round-trip. There is no AI reasoning between steps (this is what makes it cheap + fast + un-skippable). 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 sleep = ms => new Promise(r => setTimeout(r, ms));
const out = [];
const sel = el => { const id = el.id ? `#${el.id}` : ''; return (el.tagName.toLowerCase() + id).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) }; };
// ── capture baseline (original dir + pre-existing horizontal overflow count) ──
const html = document.documentElement;
const originalDir = html.getAttribute('dir') || 'ltr';
let baselineOverflow = 0;
for (const el of document.querySelectorAll('*')) {
if (baselineOverflow >= 30) break;
if (el.scrollWidth > el.clientWidth + 2 && getComputedStyle(el).overflowX !== 'hidden') baselineOverflow++;
}
// ── apply RTL ──
html.setAttribute('dir', 'rtl');
await sleep(500); // let CSS recompute, transforms apply
try {
// 1. Page-level horizontal overflow in RTL
if (document.documentElement.scrollWidth > window.innerWidth + 2) {
out.push({ skill: 'qa-detect-rtl-layout', issueType: 'rtlPageOverflow', severity: 'high', selector: 'html',
description: `Page has horizontal overflow when dir="rtl" — scrollWidth ${document.documentElement.scrollWidth}px vs viewport ${window.innerWidth}px. Likely hardcoded margin-left/padding-right or left:0 instead of inset-inline-*`,
bbox: { x: 0, y: 0, w: 200, h: 60 } });
}
// 2. Element-level overflow that appeared because of RTL
let perElementOverflow = 0;
for (const el of document.querySelectorAll('header, nav, aside, main, section, [class*="container"]')) {
if (perElementOverflow >= 6) break;
const style = getComputedStyle(el);
if (style.overflowX === 'hidden') continue;
if (el.scrollWidth > el.clientWidth + 4) {
perElementOverflow++;
out.push({ skill: 'qa-detect-rtl-layout', issueType: 'rtlElementOverflow', severity: 'medium', selector: sel(el),
description: `Element ${sel(el)} overflows horizontally in RTL — scrollWidth ${el.scrollWidth}px > clientWidth ${el.clientWidth}px. Likely hardcoded directional CSS.`,
bbox: bb(el) });
}
}
// 3. Fixed-position elements anchored to "left" but expected to be on the start side
for (const el of document.querySelectorAll('[class*="sidebar"], [class*="drawer"], [class*="sticky"], [class*="fixed"]')) {
if (out.length >= 15) break;
const style = getComputedStyle(el);
if (style.position !== 'fixed' && style.position !== 'sticky') continue;
// In RTL, "start" is right. If left:0 is set, the element is now on the "end" side — usually wrong.
if (style.left === '0px' && style.right !== '0px') {
out.push({ skill: 'qa-detect-rtl-layout', issueType: 'rtlFixedSidewrong', severity: 'medium', selector: sel(el),
description: `Fixed/sticky ${sel(el)} is anchored to left:0 in RTL — should use inset-inline-start:0 so it flips to the right side in RTL.`,
bbox: bb(el) });
}
}
} finally {
// ── restore original direction (MANDATORY — runs even if scan threw) ──
if (originalDir.toLowerCase() === 'rtl') html.setAttribute('dir', 'rtl');
else if (originalDir.toLowerCase() === 'ltr') html.setAttribute('dir', 'ltr');
else html.removeAttribute('dir');
}
return out;
}
Issues
| issueType | severity | description |
|---|---|---|
| rtlPageOverflow | high | "Page has horizontal overflow in RTL — hardcoded directional CSS" |
| rtlElementOverflow | medium | "Element overflows in RTL — needs logical properties (inset-inline-, margin-inline-)" |
| rtlFixedSidewrong | medium | "Fixed element anchored to left in RTL — should use inset-inline-start" |
Notes on this conversion
- The old multi-probe playbook (captureDirAndCount → applyRtl → scanRtlBreaks → restoreDir) is folded into ONE async
browser_evaluatecall. Same checks, same issueTypes. - RTL is set/restored entirely in-page (
document.documentElement.dir) — no real viewport change needed, so this runs as a single round-trip withexecutable: true. - Direction restore is in a
finallyblock, so the page is never left in RTL even if the scan throws.