--- name: mobile-web-ui description: Use when building responsive web UI for phones, or when /ibr:build preamble returns platform=web mobile. Covers viewport/safe-area, thumb zones, touch, Material 3, iOS Safari, WCAG 2.2. version: 0.1.0 user-invocable: false --- # Mobile Web UI Opinionated rules for mobile-first web. Full research context + citations: `docs/research/2026-04-13-mobile-ui-best-practices.md`. ## Non-negotiables - `` — prevents iOS 300ms click delay - `100dvh` for true viewport (not `100vh` — includes dynamic chrome) - `env(safe-area-inset-bottom)` for home-indicator clearance - `prefers-reduced-motion` honored for every non-essential animation (WCAG SC 2.3.3) ## Touch targets (WCAG 2.2) | Standard | Size | Use as | |---|---|---| | WCAG 2.5.8 (AA minimum) | 24×24 CSS px | Legal floor — not a design target | | WCAG 2.5.5 (AAA enhanced) | 44×44 CSS px | Working minimum | | Material Design 3 | 48×48 dp | Preferred for Android-targeted web | Default: **44×44 px** for tap targets. Full-width primary CTAs in the bottom 25–40% of viewport (natural thumb zone — NN/g: 96% tap accuracy vs 61% in stretch zone). ## Color roles (Material 3) Never hardcode hex. Use role tokens so dark mode + theming work. - **Semantic**: `on-surface`, `surface`, `outline`, `error` - **Accent/Tint**: `primary`, `secondary`, `tertiary` - **Surface containers** (5 levels): `surface-container-lowest` → `-highest` — tonal elevation replaces shadow-only depth ## Typography (Material 3) 5 roles × 3 sizes — Display (57/45/36), Headline (32/28/24), Title (22/16/14), Body (16/14/12), Label (14/12/11). Weights limited to Regular or Medium. Body Large (16px) for primary reading. ## Forms - `inputmode` / `type="email|tel|number|url"` for correct mobile keyboard - `autocomplete` tokens for autofill - Labels outside inputs — never placeholder-as-label (fails WCAG 1.3.1) - Error states = color + icon + text (WCAG 1.4.1 — not color alone) - Field height ≥ 44px ## iOS Safari specifics - No hover — use `@media (hover: hover)` for desktop-only affordances - No automatic PWA install prompt — instruct user to Share → Add to Home Screen - Push notifications supported since iOS 16.4 - **50 MB Safari cache ceiling** — plan offline-first accordingly - No access to Face ID / Touch ID / BLE / USB / full accelerometer from web ## Material 3 motion Use the motion-physics springs for interactive transitions (M3 Expressive, May 2025). Durations/easings still documented for non-interactive. Always respect `prefers-reduced-motion`. ## Performance budgets that shape UX - LCP < 2.5s, INP < 200ms, CLS < 0.1 - Chunk main-thread tasks >50ms - Prefer `transform` / `opacity` for animation (compositor-only) ## Anti-patterns - `:hover` used to reveal primary content → broken on touch - Fixed headers/FABs that eat >30% of viewport - Hardcoded hex instead of role tokens - Color-only error signaling