agentleFS
textura-agencytextura-agency/next16-claude-starter/.claude/skills/mobile-device-qa/SKILL.md

mobile-device-qa

Skill141 starsChanged 34 days agoUnlicenseView on GitHub

Make a site behave on real phones — the defects no Lighthouse run or headless scroll test sees, learned from site owners reviewing production sites on an iPhone. Covers iOS URL-bar resizes (scene boxes, width-only resize, worker side), WebGL context loss and canvases that stop drawing, 120 Hz speed and frame caps, full-screen mobile menus (dvh + safe area, portals, focus, dark mode), touch sliders, horizontal overflow, split headlines breaking mid-word, custom cursors on touch, gyroscope hero motion, the first scroll after a loader, phone stills, Figma-absolute phone layouts, and reproducing iOS-only bugs in WebKit. Use when the user says "on my iPhone", "iOS", "Safari", "on mobile it…", "flickers when I scroll", "the scene disappears", "low fps on the phone", "too fast on the phone", "mobile menu", "can't swipe", "page zooms out", "gyroscope", "test on real devices", or before handing a site to a client who will open it on a phone.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Fix: no fixed phone frame caps.

    line 108
  2. Very specific:

    Fix: stop Lenis while the loader is up and through its reveal, and check no effect restarts it.

    line 256
  3. Distinctive:

    Run, and report each as passed / failed-and-fixed / not verifiable here:

    line 301

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Mobile device QA

Lighthouse loads a page nobody touches; the scroll test scrolls it in desktop Chrome with a phone's viewport and a throttled CPU. Neither has Safari's collapsing toolbar, a 120 Hz panel, a finger, a gyroscope, iOS's memory pressure or a phone in dark mode. Every item below passed both instruments on production sites and was then found by a person holding an iPhone. This skill is that person's checklist, with the mechanism, the fix and a way to prove it without the phone — and an honest line for what still needs one.

Each item: symptom (what a reviewer saw) → cause → fix → prove it. Rule = held on ≥ 3 sites; observed = 1–2.

Setup. yarn build && yarn start, yarn qa:setup once. Every tool takes --url (tools/qa/README.md). Probes run with a person's UA — the default headless UA gets the robot form (no motion, no scene, no cursor) and "proves" a bug gone that a person still sees. Look at every screenshot (Read the image). Copy-paste probes and code shapes: references/recipes.md.

When the bug is iOS-only, reproduce it in WebKit first. Twice a fix passed every headless-Chrome probe and failed on the phone (a hero scene vanishing after scroll). node tools/qa/webkit-probe.mjs --url … runs Playwright's WebKit with an iPhone profile and touch. Reproduce → fix → the same probe passes. If WebKit can't reproduce it either, ship a fix that removes the mechanism and a self-check that recovers the state, and say plainly it is unverified on iOS.

1. The iOS toolbar resizes the viewport mid-scroll

Symptom: "the scene flickers when I scroll", "the hero re-renders when I change scroll direction", "the section resizes on iOS", balls in a physics scene jump. Rule (5 sites).

Cause: Safari's URL bar collapses and expands as you scroll: innerHeight changes and resize fires. Boxes sized 100dvh / 100vh-via-JS / fixed inset-0 / innerHeight change height; a WebGL renderer that follows reallocates its drawing buffer (cleared → a blank frame) and redraws; code that re-randomises or re-lays-out on resize visibly jumps. r3f's <Canvas frameloop="never"> re-applies the prop on each re-render — after the second resize one scene stayed black.

Fix:

  • Scene boxes at the large viewport: src/components/common/scene-viewport.tsx / src/utils/stable-viewport.ts — 100lvh measured once, re-measured on touch devices only when the width changes (rotation), a rotation settled ~300 ms later. Desktop windows still follow every resize.
  • Renderers: skip a resize whose CSS size and DPR didn't change; on a real one, draw immediately (setSize clears the buffer).
  • Keep listening for resize — never only orientationchange on touch: a width change (split screen, a DevTools preset back to desktop) then left the canvas phone-sized (observed).
  • Worker scenes resize in the worker too — one OffscreenCanvas worker cleared its own buffer on every height step; guard it the same way.
  • Anything else that reads innerHeight per resize — a scroll-scrubbed section's fit(), visualViewport listeners, ResizeObservers on scene wrappers, ScrollTrigger.refresh / Lenis recomputes — reads the stable height instead.
  • Static UI is the opposite (§4): menus use dvh.

Prove it: node tools/qa/ios-toolbar-probe.mjs --url … --scroll 0.3 — an iPhone viewport, height stepped 844 → 760 → 844 → 700 → 844 while scrolled: no canvas buffer or box change, no worker size message, no blank screenshot, the loop still drawing; then a rotation that does resize. FAIL on production → PASS on the fix, for every site this was applied to. Headless height steps shrink lvh sections with the window (a real iPhone doesn't) — compare positions relative to the section, not the page.

2. The scene disappears (and never comes back)

Symptom: "after scrolling the whole site and back, the hero scene is gone"; "the scene disappears after a little scroll on iOS". Observed (1 site, three review rounds).

Causes, in the order they were found:

  1. A visible canvas stopped drawing. A "freeze the hero after 10 % scroll" optimisation trusted the browser to keep the last frame; iOS drops it after a toolbar resize / re-composite and a stopped scene never repaints. Rule now: never stop drawing a canvas that is on screen — pause only when off screen.
  2. A lost WebGL context. iOS drops contexts under memory pressure (the page decoded three 3× stills while the hero was off screen); three.js preventDefaults the loss but nothing rebuilt the scene.

Fix: keepSceneAlive in src/lib/scene/webgl-context.ts — preventDefault the webglcontextlost; on approach (IntersectionObserver with lead), visibilitychange and pageshow, check gl.isContextLost() and rebuild a lost or restored scene on a fresh context at rest (no intro replay), ≥ 1 s apart, 3 retries; forceContextLoss() on every teardown (a rebuild never holds two contexts); don't allocate desktop-only render targets on phones; a live scene re-sizes only if its buffer is actually stale.

Prove it: node tools/qa/context-loss-probe.mjs --url … — scroll bottom ↔ top cycles, WEBGL_lose_context.loseContext() off screen (with and without a restore) and on screen, assert the hero draws again with the same lit-pixel count. Then tools/qa/webkit-probe.mjs with touch momentum, since Chrome did not reproduce the original bug. Say "unverified on a real iPhone" if it is.

3. Frame rate and speed on 120 Hz phones

Symptom A — "low fps, looks really bad": a scene capped "to save the phone". Rule (5+ sites). A t - last <= 1000/30 throttle draws every 3rd frame on 60 Hz (20 fps) and every 5th on a 120 Hz iPhone (26 fps). A cap can also trip the scene's own fps → DPR fallback: one hero dropped every phone to DPR 0.75 within 2 s ("too noisy"). Fix: no fixed phone frame caps. Draw at the display rate and pay with a cheaper frame (DPR 1–1.5, fewer samples/particles, lighter bloom). Lifting caps took scenes 26 → 120 fps with the phone scroll test unchanged or better. Prove it: node tools/qa/fps-probe.mjs --url … — the scene's draws/s vs the page's rAF/s at rest and touch-scrolling; draws ≈ rAF/3 or rAF/5 is a leftover cap. Grep: 1000 / 30, 1000/30, MOBILE_FRAME, frameBudget, frameloop.

Symptom B — "animates 2–4× too fast and shakes" before the first scroll. Causes: per-frame increments (x += 0.02, lerp(a, b, 0.1)) not scaled by delta time run 2× at 120 Hz — 4× when two loops tick (StrictMode double mount, a loop started on mount and resize, a worker loop + a page loop); a worker fed the clock in milliseconds where the page path used seconds ran every timed motion ~1000× fast, aliased into jitter (observed). Fix: src/lib/scene/per-frame.ts — createFrameClock() (one clock in seconds shared by every path, dt clamped), += k * dt * 60, x += (target - x) * perFrame(k, dt) or damp(...); one loop per scene. Prove it: speed is invisible to Lighthouse and the scroll test (they count frames). Simulate 120 Hz by replacing requestAnimationFrame with an 8 ms timer (references/recipes.md) and compare pixel change per 1/60 s at rest against 60 Hz; log the scene's time value on both paths for one second.

Desktop is 120 Hz too — cap a GPU-bound WebGL scene's draw at 60 fps there (optimize-3d-scene §5). That is the one cap that is a rule.

4. Full-screen mobile menus

Symptoms: "make it a proper full-screen immersive menu"; "it appears instantly"; "the bottom button is cut off by the iOS bar"; "the text has no contrast, content not seen"; "the cross doesn't match the burger"; "focus is lost a second after opening". Rule (10+ menus built).

Causes and fixes:

  • Height. inset-0 / h-lvh / 100vh puts the menu's foot under Safari's bottom toolbar. Menus are static UI: top-0 h-dvh, bottom padding max(<pad>, calc(env(safe-area-inset-bottom) + <pad>)). (viewport-fit=cover only where no text sits in the landscape notch gutter.) Canvases are the opposite — lvh (§1).
  • It doesn't cover the screen. A fixed overlay inside a transformed or separately layered header is fixed to that box. Portal it under <body>. A portal loses CSS variables set on wrappers (a scene colour) — render it inside the element that carries them, or copy them over.
  • Focus can't move in / is lost after ~1 s. Show the panel in the same render that opens it, then focus; a portal returned straight from a react-spring useTransition render callback remounts (focus dropped ~1 s after opening) — create the portal inside the panel component instead.
  • Dark mode. A menu on a theme token (bg-background) turns near-black on a dark-mode phone while a fixed-colour page stays light — one read ~1:1. Give the menu its own tokens; check with prefers-color-scheme: dark emulated. (Assume the reviewer's phone is in dark mode.)
  • Behaviour: scroll locked while open (stop Lenis / the scroll API; restore after — src/hooks/use-scroll-lock.ts), Escape closes, a link closes then scrolls to its target, focus moves in and back to the toggle, Tab stays inside, aria-expanded + aria-controls, the page behind inert, the closed menu inert/unmounted (A11y must stay 100), reduced motion = a plain fade. Keep a scene behind it paused or running — never remount it.
  • Motion (springs only): the panel enters by clip-path / scale / translate (a circle or wipe from the toggle, a curtain), links stagger in 40–60 ms apart with transform + mask, the toggle morphs burger ↔ cross in place (same box, same lines), the exit is the reverse and faster. Reuse the site's eases, colours and display face; large links (clamp(2.5rem, 11vw, 4rem)), secondary info (CTA, contact) at the foot. Burger lines sized against the wordmark's stroke and aligned to the header padding — "the closed burger looks off" was 1 px rules at 3× next to a 2 px stem.
  • Before redesigning, find which menu is mounted — one site carried an unused full-screen menu next to the live dropdown.

Prove it: screenshots at 390×844 — closed, mid-open, open at rest, closing, after a link — in light and dark scheme, in WebKit (webkit-probe.mjs); check focus lands on the first link and returns to the toggle, scrollY unchanged after a swipe while open, the foot clear of a 34 px safe-area inset. Lighthouse A11y stays 100.

5. Touch: sliders, swipes, overflow, cursors

  • A horizontal slider won't swipe. touch-action: pan-y blocks the finger when its drag handlers skip touch (leaving it to native scroll). Use touch-action: manipulation (or pan-x pan-y) and handle pointer events. Observed. <model-viewer> is the reverse: it swallows vertical scrolling unless touch-action="pan-y". Prove: emulated touch — a sideways swipe moves the slider, a vertical one scrolls the page.
  • A finger drag scrolls nothing on Android, the wheel works. The page locks the document and scrolls a position: fixed inner scroller, with full-screen position: fixed panels inside it (pinned scene layers, a fixed cookie banner). Chrome chains a touch scroll along the containing block, not the DOM: a fixed panel's containing block is the viewport, whose document is locked, so the drag dies there (0 px); wheel events bubble through the DOM to the scroller and still work — which is why desktop review never sees it. Fix: @media (pointer: coarse) → pointer-events: none on those panels (and the fixed banner), pointer-events: auto again on their controls, links and canvases. A drag that starts on a re-enabled button still won't scroll (Lenis syncTouch would, at the cost of native momentum — a design call). Observed — phone scroll coverage 0 % → 100 %. Prove: node tools/qa/scroll-test.mjs --url … --touch-drag — a real finger drag (CDP touch events, headed) from each fixed full-screen panel must move the page; it prints what the finger hit and the wheel result at the same spot. The phone scroll test of such a page errors ("touch never moved it") instead of passing.
  • The whole page is zoomed out. One section wider than the viewport (a box-content w-full with side padding) makes iOS fit the page. Prove: document.documentElement.scrollWidth === innerWidth at 320, 360, 390, 430 after any phone layout change (resize-check.mjs reports overflow too).
  • Headlines break mid-word ("DA/TA", "ADVANT/AGE") when a split-letter effect makes every letter an inline-block. Group letters in a white-space: nowrap word span; fit the phone headline size to its widest line (calc((100vw - 2 × gutter) / <widest line in em>)). Prove: screenshots at 360/390/414/430, no overflow.
  • A custom cursor / "floating pointer" on a phone. Mount cursor followers and hover pills only under (hover: hover) and (pointer: fine) — a tap's synthetic mousemove left one floating. Same gate for hover springs (also a TBT win).
  • Overlapping loader numbers / dense desktop ornaments on a phone — hide or reflow them below md rather than shrinking them to illegibility.

6. Gyroscope hero motion (opt-in)

When: a static hero model on phones may "breathe" with the phone instead of following a cursor that doesn't exist. It is a taste call — on production sites it was kept on most and removed on some. Ask first.

Fix: src/lib/scene/device-tilt.ts — startTilt() on mount, const t = readTilt(dt) per frame ({x, y} in [-1, 1], eased, relative to how the phone was first held, slowly re-centred), stopTilt() on unmount. Apply small amounts layered on the model's own motion (≈ ±8–15° yaw from x, ±5–8° pitch from y, or a small parallax) — calm, never jittery. iOS 13+ sends nothing until DeviceOrientationEvent.requestPermission() runs inside a tap; a scroll's touchend is rejected, so the module re-arms for the next tap. Idle sway covers "before permission", "declined" and "no sensor". Off for the robot form and reduced motion; coarse pointers only. A worker scene: read on the page, post only on change, rounded to 0.01.

Prove it: mobile emulation with touch, dispatch synthetic deviceorientation events (references/recipes.md), screenshot two tilts; the robot form and reduced motion don't move; no permission prompt on load; Lighthouse A11y/BP/SEO unchanged. Unverifiable here: the real iOS permission sheet and a real gyroscope's feel — say so.

7. The first scroll after a loader

Symptom: "during the loader the site scrolls a few sections down"; "on PC the first scroll has so many freezes". Observed.

Causes: a preloader's overflow: hidden stops the browser, not Lenis — Lenis scrolls the window itself (a wheel flick under one loader landed the page 1,643 px down; an effect restarting Lenis on mount undid the stop); scroll restoration put a reload ~500 px down; and the scene build + section hydration landed exactly on the first wheel after the lift — a moment the scroll test (which starts ~1 s after unlock) never sees.

Fix: stop Lenis while the loader is up and through its reveal, and check no effect restarts it; history.scrollRestoration = "manual" in the head script; reset to the top as the loader leaves; build the scene and hydrate the sections under the loader in short steps, one per idle callback; split the lift's entrances into their own tasks.

Prove it: probe scrollY per frame with wheel/swipe input during the loader (→ 0), reload after scrolling (→ 0), and a wheel from the exact unlock frame with Long Animation Frames recorded — node tools/qa/scroll-test.mjs --url … --first-scroll does this; references/recipes.md has the raw probe. No script frame in the first seconds.

8. Stills shown full-screen on phones

When: a pinned scroll-story's phone version — the hero stays live, later sections scroll in normal flow over stills of the scene (only with the client's sign-off; it took two sites' phone scroll from janky to ideal). Or a poster.

Symptom: "the mobile stills must be high quality" — soft beads, a grey field. Cause: captured from the phone-tier scene at low DPR, then recompressed by next/image at q75. Recipe (observed, accepted in review): capture from the desktop-quality scene in a phone-shaped viewport at the phone's real density (3×, ~1182×2559), best of several frames, UI hidden; AVIF q≈70 + WebP q≈88 at 2× and 3× in a <picture> with sizes="100vw", served as captured (unoptimized), and fetched on first input or ~3 s after load so Lighthouse doesn't download them. node tools/qa/capture-still.mjs --url … does the capture. Look at them at 100 % next to the live scene; re-capture when the scene's look changes.

9. Phone layouts and padding

  • "Side padding 1rem" on a layout absolutely positioned from a 390-wide Figma frame can't be done element by element (one site: ~30 files). Scale the root font so the edge lands at 16 px and centre the column; tell the client type grows up to ~14 % at 430 px. Observed.
  • Never decide the phone layout from JS width on the server — a hook reading width 0 during SSR hydrates the desktop composition on phones, then rebuilds (observed: ~0.25 s of the longest task). CSS breakpoints; or render both and hide one.
  • Hero height on phones is a design decision (reviewers asked for shorter heroes and darker overlays as often as for anything technical) — but whatever the box, a scene canvas inside it stays lvh and width-only-resized (§1).

Close-out

Run, and report each as passed / failed-and-fixed / not verifiable here:

node tools/qa/ios-toolbar-probe.mjs  --url …   # §1 (any full-viewport scene)
node tools/qa/context-loss-probe.mjs --url …   # §2 (any long page with a live scene)
node tools/qa/fps-probe.mjs          --url …   # §3
node tools/qa/resize-check.mjs       --url …                # rotation, device presets, overflow
node tools/qa/webkit-probe.mjs       --url …   # iOS engine: menus, overflow, the bug at hand
node tools/qa/scroll-test.mjs        --url …   # no regression on the phone scroll
node tools/qa/scroll-test.mjs        --url … --touch-drag   # §5: a finger drag moves the page (fixed panels, inner scrollers)
node tools/qa/lighthouse.mjs         --url …   # A11y/BP/SEO stay 100

Then yarn lint, npx tsc --noEmit -p ., yarn build, .claude/scripts/verify.sh. The final check is a real phone — push a preview and ask the client (or a teammate) to open it, naming exactly what to try (scroll down and back, change scroll direction, open the menu, rotate). Write what you could not verify. Log the change in obsidian/meta/changelog.md; a new iOS lesson → obsidian/knowledge/pitfalls.md / fix-catalog.md; the workflow lives in obsidian/workflows/mobile-device-qa.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.