Skip to content

fix(onboarding): make Accept/Install reachable on small screens#999

Merged
web3dev1337 merged 1 commit into
mainfrom
fix/onboarding-small-screen-accept
May 31, 2026
Merged

fix(onboarding): make Accept/Install reachable on small screens#999
web3dev1337 merged 1 commit into
mainfrom
fix/onboarding-small-screen-accept

Conversation

@web3dev1337
Copy link
Copy Markdown
Owner

Summary

The dependency setup wizard had reachability bugs on short viewports (landscape phones, small laptops, resized windows): the I Agree button on the Terms screen — and the Install/Next buttons on every setup step — could be pushed below the visible viewport with no way to scroll.

Root causes

  1. .onboarding-container used 100vh + overflow: hidden. On iOS Safari, 100vh includes the URL bar, so the container was larger than the actual visible viewport, and overflow: hidden clipped anything that overflowed.
  2. .onboarding-welcome-card, .onboarding-legal-card, and .onboarding-step-card set min-height: clamp(min, vh, max) where the min clamp value (320–360px) was enforced even on viewports shorter than ~600px. Combined with header + footer + paddings, the action row was pushed past the bottom of the viewport — and the container would not scroll.
  3. The body-level body.dependency-onboarding-active #dependency-setup-modal override had higher specificity than .onboarding-overlay, so any padding/overflow fix had to be applied at both selectors.

What changed

  • 100vh100dvh everywhere (accurate mobile viewport)
  • overflow: hiddenoverflow-y: auto on the container + the body-active modal selector, with scrollbar-gutter: stable and overscroll-behavior: contain
  • New @media (max-height: 800px) and (max-height: 600px) rules drop the decorative min-height clamps and tighten paddings/typography so the action row is reachable on 320–800px-tall windows
  • align-items: flex-start on short viewports so the modal starts at the top and users can scroll down naturally
  • Safe-area insets (env(safe-area-inset-*)) added to all overlay paddings for notched devices

Test plan

Tested with Puppeteer at 6 viewport sizes — every size passes (I Agree button is either initially in view or reachable via container scroll):

Viewport Before After
1920×1080 (desktop) in-view in-view
1280×600 (laptop short) in-view (tight) in-view
1024×500 (laptop short) clipped, no scroll scrollable, reachable
390×844 (iPhone portrait) clipped, partial scroll scrollable, reachable
844×390 (iPhone landscape) clipped, no scroll scrollable, reachable
667×375 (small landscape) clipped, no scroll scrollable, reachable

Manual:

  • Launch dev orchestrator, clear localStorage, reload — Terms screen appears
  • Resize window height to 500px, confirm I Agree button visible after natural scroll
  • Proceed through Install step pages, confirm Next/Install buttons reachable on short viewports

🤖 Generated with Claude Code

The dependency setup wizard had three reachability bugs on short viewports
(landscape phones, small laptops, resized windows):

1. `.onboarding-container` used `100vh` + `overflow: hidden`. On iOS Safari
   the URL bar makes `100vh` larger than the actual visible viewport, and
   `overflow: hidden` clipped any content that overflowed.
2. `.onboarding-welcome-card`, `.onboarding-legal-card`, and
   `.onboarding-step-card` all set `min-height: clamp(min, vh, max)` where
   the *min* clamp value (320-360px) was enforced even on viewports
   shorter than ~600px. Combined with header + footer + paddings, the
   action row (I Agree, Start setup, Install, Next/Back) was pushed
   past the bottom of the viewport with no way to scroll.
3. The body-level `body.dependency-onboarding-active #dependency-setup-modal`
   override had higher specificity than `.onboarding-overlay`, so any
   padding/overflow changes had to be applied at both selectors.

Fix:
- `100vh` → `100dvh` for accurate mobile viewport
- `overflow: hidden` → `overflow-y: auto` on the container + the body-active
  modal selector, with `scrollbar-gutter: stable` and
  `overscroll-behavior: contain` so the wider page never bounce-scrolls
- New `@media (max-height: 800px)` and `(max-height: 600px)` rules that
  drop the decorative `min-height` clamps and tighten paddings so the
  action row is always reachable, even on 320-600px-tall windows
- `align-items: flex-start` on short viewports so content begins at the
  top and the user can scroll down naturally
- Safe-area insets (`env(safe-area-inset-*)`) added to all overlay
  paddings for notched devices
@web3dev1337 web3dev1337 merged commit 4fc897d into main May 31, 2026
4 checks passed
This was referenced May 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant