Skip to content

web: make the docs site usable on phones - #32

Merged
rgamba merged 2 commits into
mainfrom
web-mobile-layout
Sep 18, 2026
Merged

rgamba merged 2 commits into
mainfrom
web-mobile-layout

Conversation

@rgamba

@rgamba rgamba commented Sep 18, 2026

Copy link
Copy Markdown
Member

Summary

The docs site at skipper.airbnb.tech was broken on phones: the homepage rendered 480px wide on a 375px screen, the Quickstart forced a 434px layout viewport, and every primary nav link disappeared below 860px with nothing in its place. This PR fixes the overflow at its causes and adds the two mobile affordances the site was missing.

What changed

Overflow root causes, not symptoms. Two things were widening the page:

  • The hero and "show me the code" grids let the LangTabs code block dictate the column width. Grid items default to min-width: auto, so the longest unbroken line of Kotlin became the column's minimum. Both grids now give their children min-width: 0, and the <pre> scrolls internally as intended.
  • Inline <code> in prose (Maven coordinates, class names) had no break opportunities. It now uses overflow-wrap: anywhere. Table cells keep nowrap because the table already scrolls.

A body { overflow-x: clip } safety net is added as well. clip rather than hidden so body does not become a scroll container and sticky positioning keeps working.

Mobile nav. Below 860px the Docs / Examples / Community links collapse behind a hamburger that opens a full-width dropdown panel under the header, with "Get Started" added since the ghost button is hidden there. On the homepage's blue hero nav, opening the menu also applies the white "scrolled" style so the panel and header read as one surface. Closes on link click, Escape, outside click, or crossing back to the desktop breakpoint. Under 520px the GitHub button drops to an icon.

Docs sidebar. On narrow screens the sidebar sits above the article, and its ~25 links pushed the content well below the fold. The nav list now collapses behind a "Browse the docs" toggle; search stays visible. Prev/next pager links stack vertically.

Spacing pass at ≤600px. 16px gutters, tighter section and hero padding, smaller hero heading, full-width "how it works" steps, footer brand spanning both columns, and the scroll-padding offset reduced to match the shorter header.

Trade-offs

  • Menus are plain CSS class toggles driven by a few lines of vanilla TS in the existing component scripts, matching how the site already handles the Kotlin/Java tabs. No dependency added.
  • The docs nav is collapsed by default on mobile rather than showing the current section expanded. Simpler, and the active page is one tap away.
  • No changes above 900px; desktop layout is byte-for-byte the same CSS path.

Testing

Verified in a 375×812 mobile-emulated browser against the dev server, before and after:

Page Before (layout width) After
/ hero column 480px, clipped by hero overflow 375px, no overflow
/docs/quickstart/ 434px layout viewport (inline code) 375px
/docs/reference/configuration/ (tables) tables scroll 375px, tables scroll internally
/examples/, /community/, /docs/ ok 375px

Also exercised: hamburger open/close (button, Escape), docs "Browse the docs" toggle, footer at phone width, and a 1280px desktop check of the homepage and Quickstart to confirm no regression. npm run build completes with all 32 pages.

Ricardo Gamba Lavin added 2 commits September 18, 2026 11:51
The site overflowed horizontally at phone widths and hid all primary navigation
below 860px with no replacement.

- Hero and code-layout grid columns get min-width: 0 so a code block's longest
  line no longer sizes the column past the viewport (the homepage was 480px wide
  on a 375px screen).
- Inline code in prose wraps (overflow-wrap: anywhere) instead of widening the
  page; the Quickstart's Maven coordinate forced a 434px layout viewport.
- Nav collapses the Docs/Examples/Community links behind a hamburger with a
  dropdown panel; the hero nav turns white while the menu is open so the panel
  reads as one surface. The GitHub button shrinks to an icon under 520px.
- Docs sidebar collapses its ~25 links behind a "Browse the docs" toggle on
  narrow screens so the article is not pushed below the fold; search stays
  visible. Pager links stack.
- Phone-width spacing pass: 16px gutters, tighter section padding, smaller hero
  type, full-width flow steps, footer brand spanning both columns, and a
  body-level overflow-x: clip as a safety net.
.hero__inner set the padding shorthand with 0 on the sides, overriding the
container's 24px gutters at every breakpoint. Use 24px (16px on phones) so
the hero content aligns with the header and the rest of the page.
@rgamba
rgamba marked this pull request as ready for review September 18, 2026 19:21
@rgamba
rgamba merged commit 619a628 into main Sep 18, 2026
8 checks passed
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