Mobile

mobile

Using this skill: announce "Using mobile", make a todo per numbered step in ## Steps, and do not skip the gates. This skill's worth is its process, not a hand-reproduced outcome. If you were told to "run mobile", run it, do not improvise its result. (Suite standard: https://github.com/horizon-foundry/foundry/blob/main/reference/skill-authoring.md)

Overview

This is a ship gate where a mobile surface exists, and its weight follows the project's declared release policy (the foundry skill owns the required/optional/waived semantics). Absent a declared policy, required is the default for any real audience: a core flow that breaks on a phone holds the release.

Desktop-designed UI does not degrade gracefully to a phone. It breaks in specific, repeatable ways. The core discipline is not a list of CSS fixes. It is a loop: reproduce the exact reported state and instrument it before you change anything. The most common mobile failure is not the bug itself. It is misdiagnosing the bug and fixing the wrong mechanism. Everything below the loop is a catalog of diagnostic candidates: the usual suspects the probe confirms or clears, never fixes to apply blind.

When NOT to use

• A product with no mobile surface (a headless service, a CLI, a desktop-only internal tool): the honest gate status is not-applicable with a one-line reason (the same status production-audit's shipGates carry). Do not invent work; declare the status and move on.
• General visual or interaction polish with no mobile defect or gate in play: that is design work, not this loop.
• Weighing mobile findings into a release verdict: the audit and the release policy own the weighing; this skill produces the filled matrix they cite.

Steps

The pressure-test loop and the verification matrix below are the reference these steps point at; the steps carry the order and the evidence.

1. Reproduce and instrument the exact broken state first, untouched, with the loop's probes (document.activeElement, scroll position, getComputedStyle, matchMedia('(pointer: coarse)')). Check: the observed mechanism is recorded before anything changes.
2. Diagnose against the candidate catalog, naming the confirmed cause. Check: the cause is stated with its probe evidence, not assumed.
3. Fix minimally at the confirmed cause. Check: the change touches the confirmed mechanism, nothing speculative.
4. Re-verify the original probe on the fixed state. Check: the probe that showed the failure now shows it resolved.
5. Walk the verification matrix through the core flows. Check: every matrix row has a result.
6. Emit the filled matrix as the run's artifact (see "The verification matrix"): report it in the closing output and write it to <project>/tmp/mobile-matrix-<date>.md. Check: the file exists and every row reads pass, fail, or unverified with the exact check to run.

The pressure-test loop

1. Reproduce the exact state, untouched. Load the surface at a real device width and look before you touch. If the report is "on first load X happens", capture first-load-untouched, not the state after you interact.
2. Instrument before diagnosing. Read the actual mechanism, not the symptom. document.activeElement (is something autofocused?), scroll position (did the page scroll to an input?), getComputedStyle, and matchMedia('(pointer: coarse)').matches. A white bar or a scrolled page has several possible causes. Confirm which one before fixing. Fixing the plausible cause instead of the real one is the biggest mobile time sink.
3. Verify at a real device width. 393px (a Pixel-class width) is the working verification width. Check zero horizontal overflow (document.documentElement.scrollWidth <= innerWidth) on every state, including any fullscreen/overlay.
4. Close the loop on a real device. Headless Chromium cannot emulate a real soft keyboard or a coarse pointer. Force matchMedia to exercise the coarse branches in automation. But treat anything involving the keyboard, autofill, or touch gestures as unverified until a real device confirms it. A real-device screenshot only confirms a captured layout state; it cannot confirm a gesture, the software keyboard's behavior, autofill, or a focus transition, which need a real interaction pass. Match the evidence to the claim: say what a screenshot actually proved, and say what still needs hands on a device, rather than claiming it works.

Touch is not mouse

Branch behavior on input capability. Do not assume one input model. (pointer: coarse) is the working probe, with a caveat: it detects the primary pointer, not "a phone". Touch laptops and tablets with keyboards carry both input kinds. So treat it as "touch is likely", confirm with the instrumentation step, and never use it to hide functionality:

• Never grab focus unsolicited on a coarse pointer. Autofocusing an input on mount pops the keyboard and autofill and scrolls the page before the user acts. On a coarse pointer, do not autofocus at all: let the keyboard open on the user's tap. focus({ preventScroll: true }) stops the scroll jump but not the keyboard pop, so it is a mitigation for the rare justified autofocus, not a blanket rule.
• Desktop-only event bindings silently break on touch. wheel, mouseenter, hover never fire the same way (or at all) on touch. Prefer Pointer Events (pointerdown/pointermove), which unify mouse, touch, and pen so one path covers all of them. Where a legacy wheel/mouse* binding is unavoidable, add a parallel touchstart/touchmove path feeding the same logic and keep the two in sync.
• Put hover states in CSS, not JS, or touch devices get stuck in hover.
• Gestures differ by input. A precise pointer can afford a deliberate two-step gesture. A thumb wants a single decisive swipe. Tune per input type.

The usual suspects (diagnose, then fix)

Each of these is a candidate cause to check against the probe, with its tradeoff named. None is a rule to apply unprompted:

• Overscroll / rubber-band: when an overlay or gesture surface misbehaves, suspect scroll chaining. The fix is overscroll-behavior: none on the relevant scroll container (plus a body-lock class during overlays). It has a real cost: on html/body it also kills pull-to-refresh, which users expect on content pages. Contain it to the surfaces that need it. Only go global deliberately.
• The keyboard occluding bottom-docked controls: prefer the no-JS path. Set interactive-widget=resizes-content in the viewport meta, so the keyboard shrinks the layout viewport and your bottom: 0 controls ride above it. Reach for a visualViewport height sync only if that is not enough.
• Treat 100vw as a suspect, not an automatic bug. It overflows when a classic scrollbar gutter exists (desktop, some Android settings), because it measures the viewport including the scrollbar. When the probe shows scrollWidth > innerWidth, check for it. Where it is confirmed as the mechanism, left: 0; right: 0 (or 100%) is the fix.
• Fixed heights clip content on small screens. Prefer height: auto (or min-height) below your breakpoint.
• Viewport height: 100vh is inconsistent on mobile (browser chrome is counted differently across browsers and scroll states). Where a full-viewport height is genuinely needed, use 100dvh. Often the better fix is to not need a full-viewport height.
• Safe areas: on notched devices, pad with env(safe-area-inset-*) and set viewport-fit=cover when content goes edge to edge.
• Touch targets too small: interactive controls target 44px (the iOS minimum). For a small visual glyph, keep the glyph small and expand the hit area with padding plus negative margin (or a ::before { position:absolute; inset:-N }); the tap target is then 44px while the visible pixels stay small, and it is snapshot-safe.
• A fix entangled with fragile code: when the fix touches a surface with animation, FLIP, or gesture physics, prefer the CSS-only or declarative mechanism (a body-lock class, interactive-widget, overscroll-behavior) over JS that threads into the physics. The mobile fix should be additive and removable, not entangled.

iOS Safari caveats

Where the product supports iOS, verify separately on it. Android + Chromium is not a proxy, so a product that ships to both platforms checks both; one scoped to a single managed platform checks that one and says so. Known differences: overscroll-behavior is Safari 16+; body { overflow: hidden } does not fully lock iOS (you may need a position: fixed body lock that preserves scroll position); interactive-widget support varies; 100dvh and a visualViewport sync are often needed where Android was fine.

The verification matrix

One width is a spot check, not verification. When mobile is a release gate, walk the core flows through:

The filled matrix is the run's artifact. One row per case (three widths, landscape, text zoom, software keyboard, keyboard-only, iOS Safari, Android Chrome), marked pass, fail, or unverified with the exact check to run, per core flow. Report it in the run's closing output and write it to <project>/tmp/mobile-matrix-<date>.md, so a later foundry check or audit can cite a record instead of a claim. An unfilled matrix means the skill did not run.

Anything the run could not cover is reported as unverified, with the check to run. This is the same honesty rule the audit uses. "Works on mobile" with an untested matrix row is a claim, not a result.

Red flags

Symptoms that you skipped something above, not new rules: a symptom fixed before document.activeElement and scroll position were read; the suspect catalog applied as blanket rules (global overscroll-behavior: none, a mechanical 100vw ban); a gesture or exit bound to wheel/mouseover only; autofocus on mount; "works on mobile" after one width or headless Chromium alone; mobile work invented for a product with no mobile surface.

Version check

At most once a day, a run of this skill checks whether a newer suite exists. The command enforces the whole contract: the FOUNDRY_NO_VERSION_CHECK opt-out, the daily stamp-file rate limit, a 10s timeout, and silence on any failure. Never block or fail a run over this check.

[ -n "${FOUNDRY_NO_VERSION_CHECK:-}" ] || find "$HOME/.claude/.foundry-version-checked" -mmin -1440 2>/dev/null | grep -q . || { mkdir -p "$HOME/.claude" 2>/dev/null; curl -m 10 -fsS "https://foundry.thehorizonfoundry.com/api/version?skill=mobile&v=0.2.0"; touch "$HOME/.claude/.foundry-version-checked" 2>/dev/null; } || true

If the response carries a version newer than this file's version: frontmatter, tell the user once: a newer Foundry suite is out; update with npx skills@latest add horizon-foundry/foundry, or git pull && make install for a source install. If it prints nothing, fails, or the versions match, say nothing and proceed. What it sends: this skill's name and installed version, nothing else; it writes ~/.claude/.foundry-version-checked as the rate-limit stamp (full disclosure: the README section "Version check").