school_compare/MOBILE.md

Mobile design baseline

Mobile (≥55% of traffic) is the primary target for this app. Any new screen or component must be designed at the 360 px viewport first and verified at three reference widths before merge.

Reference viewports

Width	Device class	Purpose
360 px	Low-end Android (Samsung A-series, older Pixels)	Hard floor — if it doesn't fit here it isn't shipping
390 px	iPhone 14 / 15 / 16 (38% of mobile traffic)	Primary iOS target
430 px	iPhone 16 Pro Max, large Android	Upper mobile bound

Acceptance checks for any screen change

Before raising a PR that touches user-visible UI, confirm at each reference width:

1. No horizontal overflow. document.documentElement.scrollWidth === window.innerWidth. The most reliable check: in DevTools console run

   document.documentElement.scrollWidth - innerWidth
   

   It must read 0. Any positive number means something is bleeding past the right edge — usually a fixed-width element, an inline-block that didn't wrap, or a flex row missing flex-wrap: wrap.
2. Tap targets ≥ 44 × 44 px on every interactive element (iOS Human Interface Guidelines minimum). Probe with:

   Array.from(document.querySelectorAll('a, button, [role=button], input, select'))
     .filter(el => el.offsetParent)
     .map(el => ({ t: el.innerText?.trim().slice(0,30), r: el.getBoundingClientRect() }))
     .filter(o => o.r.width < 44 || o.r.height < 44)
   

3. No text below 11 px in any visible-by-default block. Decorative demo content (illustrations, mocked previews) should either scale up or be hidden under the 640 px breakpoint — see MOB-04 for the pattern used on the home page's "What you'll see" section.
4. iOS Chrome bottom-bar parity. The fixed Navigation bottom tab bar already compensates for the auto-hiding URL bar via the Visual Viewport API (Navigation.tsx). New fixed-bottom elements must either use the same offset (read var(--mobile-bar-offset)) or sit inside the existing tab-bar container.
5. Safe-area insets on any new sticky/fixed chrome: padding-bottom: env(safe-area-inset-bottom) for bottom-pinned UI, padding-inline: env(safe-area-inset-left/right) for header-class chrome that runs full bleed.
6. dvh, not vh. iOS Safari's collapsing toolbar makes raw vh units jump. Prefer 100dvh (with a 100vh fallback if you support older engines) for any height that needs to track the visible viewport.

Component patterns

• Hide-on-mobile decoration: wrap with @media (max-width: 640px) { .x { display: none; } } — examples in HomeView.module.css (.hiwVisual), MetricTooltip.module.css (.wrapper).
• Right-edge scroll-fade for horizontal scrollers: mask-image: linear-gradient(to right, #000 calc(100% - 28px), transparent); Drop the fade when scrolled to the end with a JS-toggled class — see SchoolDetailView.tsx's sectionNavAtEnd state for the pattern.

Automation (future)

A Playwright regression test that asserts docW === vw at the three reference widths on /, /rankings, /admissions, /compare, and a representative /school/:urn page would catch overflow regressions immediately. Not added yet — Playwright isn't currently in the project dependency set, and the existing Jest setup doesn't compute layout. Worth adding if mobile overflow regressions recur.