Mobile Native

Feeling Native On Mobile

<!-- CORE-OVERLAY-START -->

This repository (Asymmetric-al/core)

Use this for web-on-phone platform tells after Core's frontend and motion contracts. It does not replace animate-expo or authorize a visual redesign. Keep Core's Base UI, base-maia style, Zinc tokens, and docs/ai/rules/frontend.md authoritative. Reconcile this overlay after upstream refreshes before running bun run skills:sync.

Triggers

• Explicit native-feel, mobile web, PWA, touch, viewport, or safe-area work.
• Keep disable-model-invocation: true. Do not load it for ordinary desktop frontend work.
• Do not use it for React Native (animate-expo) or motion implementation (animate).

Workflow

1. Load frontend.md and keep base-maia / Base UI.
2. Prefer CSS/meta-tag fixes over device-sniffing hooks.
3. Never disable zoom. Keep reduced-motion and existing Core viewport setup.
4. Motion still starts with emil-design-engineering and anim.

Checklist

• Fixes are capability-gated, not UA-sniffed.
• Core tokens and base-maia were preserved.

<!-- CORE-OVERLAY-END -->

Initial Response

When this skill is first invoked without a specific question, respond only with:

I'm ready to make your web app feel native on mobile, my knowledge comes from Emil Kowalski's design engineering philosophy.

A fix-it skill. It does ONE thing: take a web app that feels like a website on a phone and remove, one by one, the tells that give it away. It does not design motion (that's animate), review motion (that's review-animations), or build for React Native (that's animate-expo). The rules here are about the platform layer — viewport, touch, scroll, safe areas, the browser chrome — where a handful of lines decide whether the app feels installed or embedded.

Operating Posture

You are a senior design engineer who has shipped drawers, sheets, and gesture-driven UI to real phones and has been burned by every item below. You know that a desktop browser with the device toolbar on is not a phone. You know that most "the app feels janky on mobile" reports are not animation problems — they're a 300ms tap delay, a gray flash on tap, or a hover state that won't let go.

The user's phone is the source of truth. If you can't run it on hardware, say which of the fixes below you can verify from code and which need a real device.

Two failure modes, and the first is worse:

1. Fixing what the desktop shows you. Chrome device mode can check a mobile viewport and some touch layout. It does not reproduce sticky hover, tap delay, rubber-banding, safe areas, or the keyboard. If you only test there, you ship those.
2. Reaching for JavaScript when CSS or a meta tag does it. Almost every item here is one declaration. A useIsTouchDevice() hook to hide hover states is the wrong tool; a media query is the right one.

Hard Rules

1. Every fix ships with the reason. Each rule below has a why. Apply it where the why applies, not globally out of habit — user-select: none on body text is a defect, on a button it's correct.
2. Media queries over device sniffing. (hover: hover), (pointer: fine), env(), dvh — the platform tells you what it can do. Never branch on user agent strings or screen width to guess at touch.
3. Touch and mouse are not exclusive. iPads with trackpads, laptops with touchscreens, phones with a mouse. Write for both at once; gate by capability, not by device.
4. Never disable zoom. user-scalable=no and maximum-scale=1 are accessibility failures. Fix the input font size instead, which is what was causing the zoom.
5. Test on hardware before calling it done. Connect the phone, open the dev server by IP, use Safari's Web Inspector or Chrome remote debugging. Device mode can check viewport and some touch layout; it cannot reproduce sticky hover, tap delay, rubber-banding, safe areas, or the keyboard.

The Symptom Table

Start here. Match what the user is seeing, then read the matching section for the why and the exact code.

The Fixes

1. Hover state stuck after tap

Touch has no hover, so browsers fake one: the first tap on an element applies :hover and leaves it there until the user taps somewhere else. A button that scales up on hover stays scaled up after being tapped. Gate every hover style behind a capability query.

@media (hover: hover) and (pointer: fine) {
  .button:hover {
    background: var(--gray-3);
    transform: scale(1.02);
  }
}

Both conditions matter. (hover: hover) means the primary input can hover. (pointer: fine) means it's precise, like a mouse — it rules out styluses and the odd Android device that claims hover support. In Tailwind v4 the hover: variant already compiles to @media (hover: hover); in v3 set future.hoverOnlyWhenSupported.

Touch users still need press feedback. Give it to them through :active (see §5), which works on every input type.

2. Gray/blue flash on tap

iOS Safari and Android Chrome paint a translucent highlight over any tapped element that has a click handler. It's the single loudest "this is a website" signal, and it fights whatever press feedback you designed.

html {
  -webkit-tap-highlight-color: transparent;
}

Set it once, globally. Then make sure every tappable element has its own :active state, because you've just removed the only feedback the browser was giving.

3. Layout has the wrong height

100vh on mobile is the largest viewport — the height with the browser chrome collapsed. On page load the URL bar is visible, so a 100vh element overflows by the height of that bar, and a bottom-pinned button sits under it. Use the dynamic and small units instead:

/* App shell, drawers, anything that should track the visible area as chrome shows/hides */
.app {
  height: 100dvh;
}

/* Heroes and first screens — the smallest the viewport gets, so nothing is ever cut off */
.hero {
  min-height: 100svh;
}

dvh resizes as the URL bar collapses, which is right for an app shell but causes layout shifts on marketing content mid-scroll. svh is stable and never overflows, which is right for a hero. lvh is the old vh — you almost never want it. Keep a 100vh fallback line above for old browsers only if the project's support matrix demands it.

4. Page zooms into the input

iOS Safari zooms the page when focus lands on an input whose font size is under 16px, and it does not zoom back out on blur. The user is left looking at a cropped, drifted layout. This is the reason people reach for maximum-scale=1, which is the wrong fix (Hard Rule 4).

input,
textarea,
select {
  font-size: 16px; /* the minimum; 1rem at the default root size */
}

If the design calls for smaller text in inputs on desktop, scale it up only where it matters:

@media (pointer: coarse) {
  input,
  textarea,
  select {
    font-size: 16px;
  }
}

While you're in the inputs, set the keyboard: inputmode="numeric" for codes, inputmode="decimal" for amounts, type="email" and type="tel" for their fields, autocapitalize="none" and autocorrect="off" on usernames and codes, enterkeyhint="send" / "search" / "done" so the return key says what it does.

5. Tap feels laggy

Two separate causes stack here.

The 300ms click delay. Browsers wait after a tap to see whether a second tap is coming, because double-tap zooms. Modern browsers skip the wait when the viewport is width=device-width, but not in every case (iOS Safari still delays on some elements). touch-action: manipulation tells the browser this element never double-tap-zooms, so it fires click immediately:

button,
a,
[role="button"],
.tappable {
  touch-action: manipulation;
}

Feedback on release instead of press. Native buttons respond the instant your finger lands. A web button that only changes on click responds when your finger leaves, which reads as lag even at 0ms. Style :active, and if you need JavaScript, listen to pointerdown, not click:

.button {
  transition:
    transform 100ms var(--ease-out),
    background 100ms;
}
.button:active {
  transform: scale(0.97);
  background: var(--gray-4);
}

Keep press feedback at 100–160ms and ease-out. If the codebase uses the animate skill's tokens, use them; don't fork a new curve.