Skip to content

docs: draw the introduction diagram as columns on narrow screens - #22

Merged
ChristopherPHolder merged 1 commit into
mainfrom
docs/mobile-diagram
Nov 14, 2026
Merged

ChristopherPHolder merged 1 commit into
mainfrom
docs/mobile-diagram

Conversation

@ChristopherPHolder

Copy link
Copy Markdown
Collaborator

Closes #21

The page load vs. soft navigation diagram on the Introduction page had a fixed 770px wide viewBox. On a phone it was drawn at 0.4× and its notes came out at 4.8px.

What changed

  • The figure holds two drawings of the same lanes: rows (the current layout) and columns, with the steps running top to bottom.
  • A container query on the figure shows the columns when it is under 640px wide. Below that, the rows would shrink the 12px notes under 10px. It queries the figure, not the window, so the sidebar and the table of contents count.
  • The columns are 312 wide, so a phone draws them at about 1×, and each step sits next to its counterpart in the other lane (GET /products ↔ pushState, and so on).
  • The figure padding goes down to 12px at the sides below 480px.
  • The lanes are defined once and both drawings read from them.

Measured (puppeteer, the drawing that is shown)

Viewport Before After
1440 desktop rows, 0.84×, notes 10.1px unchanged, pixel-identical
820 tablet rows, 0.96×, notes 11.5px unchanged, pixel-identical
390 phone rows, 0.40×, notes 4.8px columns, 1.03×, notes 12.4px
360 phone rows, 0.36×, notes 4.3px columns, 0.94×, notes 11.2px

No horizontal scroll at any width. Lint, typecheck and build pass.

Screenshots

Mobile (390 × 844)

Before After, dark After, light
Before: the diagram on a phone, too small to read After: the diagram as two columns on a phone, dark After: the diagram as two columns on a phone, light
360px phone, and the diagram alone
360 phone, after Diagram, 390 dark Diagram, 390 light
After on a 360px phone The column diagram, dark The column diagram, light

Desktop (1440 × 900), unchanged

Light Dark
The row diagram on desktop, light The row diagram on desktop, dark
Full desktop pages
Light Dark
Introduction page on desktop, light Introduction page on desktop, dark

Screenshots live on the pr-media/mobile-diagram branch, which can be deleted once this is merged.

The page load vs. soft navigation diagram had a fixed 770px wide viewBox,
so on a phone it was drawn at 0.4x and its notes came out under 5px.

The figure now holds two drawings of the same lanes: rows, as before, and
columns with the steps running top to bottom. A container query on the
figure shows the columns when it is under 640px wide, where the rows
would shrink the notes below 10px. The columns are about 312 wide, so a
phone draws them close to their own size and each step stays next to its
counterpart in the other lane.

Closes #21
@ChristopherPHolder ChristopherPHolder added the documentation Improvements or additions to documentation label Nov 14, 2026
@ChristopherPHolder
ChristopherPHolder merged commit 9302225 into main Nov 14, 2026
1 check passed
@ChristopherPHolder
ChristopherPHolder deleted the docs/mobile-diagram branch November 14, 2026 11:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: the introduction diagram is unreadable on mobile

1 participant