mobile-ui-audit
Audit websites the way a phone visitor would fail on them — iOS zoom traps, sideways overflow, locked scroll, tap targets, tiny text, dead links — on real WebKit and Chromium phone profiles, optionall
SKILL.mdskills/mobile-ui-audit/SKILL.md
GitHubMobile UI audit
One script, two phone engines, every site. Run it before believing an emulator.
pip install playwright && playwright install webkit chromium
python audit.py "https://example.com/" --devices iphone
VERCEL_TOKEN=... VERCEL_TEAM_ID=... python audit.py --vercel --crawl 4 --json /tmp/audit.json --shots /tmp/shots
Exit 1 on any FAIL. --links HTTP-checks the order/book/shop/menu links plus 40 others;
--hop also audits the first same-origin order/book/shop/menu page one click deep (a site
takes ~2 min with both, so shard ~10 processes for 150 sites). Cross-origin frame errors
(Cloudflare Turnstile, booking iframes) are not the site's own JS and stay INFO.
--vercel reads the team's projects off the API and picks the custom domain or the
shortest <name>.vercel.app; team-scoped aliases sit behind Vercel SSO and audit as a
login page with a 200, so the picker skips them.
The rule this skill exists for
No text-entry control under 16px on a touch screen. Mobile Safari scales the page
until a focused input, textarea or select reads 16px and does not scale back on blur.
A 12px field means a 1.33x page, the header off the top-left, and a visitor who says
"scroll is broken." No emulator shows it: headless Chrome, Playwright WebKit and the
iPhone device profiles all auto-zoom nothing, which is why the audit measures the static
property instead of trusting a scrolled page.
Fix shape, by stack:
- Hand-written CSS:
@media (pointer:coarse){ input:not([type=checkbox]):not([type=radio]):not([type=file]),textarea,select{font-size:16px !important} }.pointer:coarsemeans "a finger" and leaves every desktop size alone.!importantbecause small sizes often sit on id selectors. - A plain
font-size: 15pxon inputs: raise it to 16. - Tailwind:
text-base, nevertext-sm, on an input. - Never
maximum-scale=1in the viewport meta. iOS ignores it for pinch but Chrome/Android honours it, so it kills pinch-zoom for the people who need it. The audit WARNs on it.
Checkboxes, radios and file inputs do not trigger the zoom and are excluded.
What a row means
| Severity | Finding | Why it is that severity |
|---|---|---|
| FAIL | iOS zoom trap | the visitor loses the page (above) |
| FAIL | sideways overflow, unclipped | iOS does not honour overflow-x:hidden on body reliably; the page pans |
| FAIL | document locked, no inner scroller | content below the fold is unreachable |
| FAIL | page error, HTTP >= 400, did not load | nothing to audit |
| FAIL | page renders blank (<40 chars of visible text after load) | the visitor sees nothing |
| FAIL | sideways overflow that pans (panX > 0 after scrollTo(400,0)) |
reproduced, not inferred; a leak that does not pan is WARN |
| FAIL | dead link (--links): >= 400 on two GETs |
401/403/429/503/999 are blocked (a bot wall), never reported dead. Tap it before believing it: restaurant menu tabs (href="991408", SpotHopper/BentoBox-style) 404 on GET but JS swaps the tab on click |
| WARN | wrong phone keyboard: an email/phone field declared type=text |
the letters keyboard comes up for a number |
| WARN | autofill disabled: autocomplete=off on a name/email/phone/address/card field |
autofill reads autocomplete; off kills it |
| WARN | broken image (complete, naturalWidth 0) |
visible hole on the page |
| WARN | tap target under 24px | WCAG 2.5.8 minimum; Apple asks 44 |
| WARN | text under 12px | a count, not a verdict — some designs run 10-11.5px mono on purpose |
| WARN | fixed/sticky layer covering >= 40% | usually a modal or a hero card; check it dismisses. The 'document locked' FAIL fires on the same pages while a modal is open; tap the close button by hand before calling it broken |
| WARN | header not at y=0 after a scroll round-trip | a sticky or anchor is fighting the scroll |
| WARN | viewport meta caps zoom | see above |
| INFO | scroll model, weight, inner scrollers | context for reading the rest |
The "wide element" check only counts elements no ancestor clips before body, so a
960px table inside a .tscroll{overflow-x:auto} is not a finding. A naive rect check
flags dozens of such pages.
Single-page apps whose views render client-side: --crawl only sees the sitemap. Audit
the real view URLs directly (e.g. /?view=<id>). A deliberately locked shell
(html{overflow:hidden} with an inner scroller) reports as INFO, not FAIL.
When the audit says ok and the phone still disagrees
The next tier is a real Mobile Safari: a headless iOS simulator driven by
sim_probe.sh in this directory. Tap the field, close the keyboard, compare
screenshots. zoomtest.html is a control page: a 12px field whose page prints
visualViewport.scale (1.33 = trap, 1.00 = clean).
./sim_probe.sh "<url>" /tmp/out 201 369 # tap in points
What it takes:
- Xcode from the Mac App Store (~3.7 GB complete) may ship no Simulator.app;
xcodebuild,simctland headless rendering all work without it. - iOS runtime:
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer xcodebuild -downloadPlatform iOS(8 GB). It can end with a "manifest couldn't be opened" error and still register the runtime. - Taps:
brew trust facebook/fb && brew install idb-companion, pluspip install fb-idb.idb connect <udid>again after every boot. Coordinates are points; measure a field with Playwright WebKit at 402x874 and tap its rect centre. The firstopenurlafter a boot times out; the second lands. - The software keyboard appears headless, so the focus zoom runs. A control tap that "did nothing" is usually a dead idb companion after a reboot.
- Playwright WebKit cannot stand in for this: it does not auto-zoom. Chrome and Android never zoom on focus at all, which is why Android visitors never see the bug.
Other tiers: a real iPhone on USB with Safari's Develop menu; paid real-device clouds.
Interactive poking: the playwright MCP (@playwright/mcp --browser webkit --device "iPhone 13") and the chrome-devtools MCP. If the playwright MCP errors that its browser
is missing, run npx -y @playwright/mcp install-browser webkit. Use them for poking,
audit.py for the sweep, sim_probe.sh for the one thing only real iOS shows.