72 lines
3.4 KiB
Markdown
72 lines
3.4 KiB
Markdown
|
# 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
|
|||
|
|
```js
|
|||
|
|
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:
|
|||
|
|
```js
|
|||
|
|
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.
|