Turn the download page into a stepped installation flow - #23
Merged
Conversation
/download becomes /installation, and the single download panel becomes a four-step sequence: check your machine, download a build, get set up, and an optional feedback step. The steps are a wizard rather than a stacked page. Only the active step is expanded; the rest collapse to a titled row. Navigation lives entirely on the connectors between the cards -- the pulsing chevron below the open step goes forward, the quieter one above it goes back -- so the rail is both the ordering signal and the only way to move. Collapsed headings are inert on purpose: two competing navigation affordances is how a visitor loses track of which step they are on. Collapsed bodies stay mounted behind `hidden` rather than being unmounted, so the server-rendered version numbers are still in the HTML for crawlers and no-JS readers even while the download step sits behind the gate. The OS selection is lifted into InstallFlowClient because it spans two cards: the build you take and the instructions for installing it. Step titles are named once in INSTALL_STEPS, since each is shown both as a panel heading and as the destination its connector announces, and the two drifted apart the first time they were separate strings. The feedback form composes a mailto rather than posting anywhere -- this site has no backend to receive form posts, and a form that discarded what someone wrote would be worse than no form. /download permanently redirects to /installation, so existing links and anything indexed keep working.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
The steps opened and closed by toggling the `hidden` attribute, which is an instant `display: none` with nothing to transition. The body now eases `grid-template-rows` between `0fr` and `1fr` -- the one way to animate to a content-determined height without measuring it in JavaScript or inventing a max-height that content will outgrow. `inert` takes over what `hidden` was doing for focus and the accessibility tree, and the body stays laid out so the server-rendered version numbers remain in the HTML. Pressing continue now centres the opened panel in the space below the navbar. This cannot be a scrollIntoView: two panels resize at once, so the target's height and its distance down the page are both still changing when the scroll starts, and a single scroll issued at the start of that is aiming at geometry that will not exist by the time it arrives. Instead the destination is recomputed every frame and the scroll eases towards whatever it currently is, converging as the panels settle. Decay is time-based so it behaves the same at 60Hz and 120Hz, and any real scroll input cancels it. Two related fixes fall out of the same problem. Connectors are now a fixed height, because their three roles had different footprints and shifted the column on every step change. And the flow sets `overflow-anchor: none`: collapsing a panel above the viewport made the browser adjust scrollTop to keep its own chosen anchor still, which fought the flow's scrolling and read as the scrollbar twitching. The feedback form gains the hardest-step and duration questions. The step options are derived from INSTALL_STEP_ORDER so renaming a step relabels the question, and "I gave up" is on the duration list because someone who abandoned the install is who the form most needs to hear from.
Collapsed steps were lighter than the card surface used everywhere else on the site, so an unopened step read as a rule on the page rather than an object. Every state now sits on the features page's tile treatment, with the active step the same surface turned up rather than the only one present. The check slot also stays occupied: before a step is finished it shows that step's letter, which turns into the check on completion. Letters rather than numbers -- the rail is what counts progress, and a number in the heading invites disagreeing with it. Drop the "how long did the whole thing take" question from the feedback form.
The topic covered the same ground as the installation page's first three steps -- requirements, download, per-OS setup -- from a page that could not know which build you had taken. It had already drifted: it still described dragging from a relative path and named a `download` nav item that no longer exists. Deleting the entry removes both its card on /help and its route, so it redirects to /installation alongside /download. The home page's two CTAs pointing at it now point at the install flow, and the footer's "Tutorials" link becomes "Install Guide".
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
/downloadbecomes/installation, the single download panel becomes a four-step sequence, and the "Getting Started" help topic — which described the same install a page away — is folded into it.A wizard, not a stacked page
Only the active step is expanded; the rest collapse to a titled row. Navigation lives entirely on the connectors between the cards — the pulsing chevron below the open step goes forward, the quieter one above it goes back. The rail is both the ordering signal and the only way to move.
Collapsed headings are inert on purpose. Two competing navigation affordances is how a visitor loses track of which step they're actually on.
Every state sits on the card surface the features page already uses, so a collapsed step reads as an object rather than a rule across the page; the active step is that same surface turned up, not the only one present. The check slot stays occupied throughout — before a step is finished it holds that step's letter, which becomes the check on completion. Letters rather than numbers: the rail is what counts progress, and a number in the heading invites disagreeing with it.
Opening and closing
Panels ease
grid-template-rowsbetween0frand1fr— the one way to animate to a content-determined height without measuring it in JS or inventing a max-height the content will outgrow.inertdoes whathiddenused to for focus and the accessibility tree, while the body stays laid out so the server-rendered version numbers remain in the HTML.Pressing continue centres the opened panel below the navbar. This can't be a
scrollIntoView: two panels resize at once, so the target's height and its distance down the page are both still changing when the scroll starts, and one scroll issued at that moment aims at geometry that won't exist by the time it arrives. The destination is recomputed every frame and the scroll eases toward whatever it currently is, converging as the panels settle. Decay is time-based, so it behaves the same at 60Hz and 120Hz, and any real scroll input cancels it.Two related fixes fall out of the same problem: connectors are a fixed height (their three roles had different footprints and shifted the column on every step change), and the flow sets
overflow-anchor: none, because collapsing a panel above the viewport made the browser adjustscrollTopto keep its own chosen anchor still — a second hand on the wheel that read as the scrollbar twitching.Removing the Getting Started help topic
The topic covered step A through step C from a page that couldn't know which build you'd taken, and it had already drifted from reality: it described dragging from a relative path and pointed at a
downloadnav item that no longer exists. Deleting the entry removes both its card on/helpand its route, so/help/getting-startednow redirects to/installationalongside/download. The home page's two CTAs that pointed at it now point at the install flow (the hero CTA, and the bottom row's "Getting Started" button, which merged into the adjacent install CTA), and the footer's "Tutorials" link becomes "Install Guide".Notes for review
InstallFlowClientbecause it spans two cards — the build you take and the instructions for installing it. Step C can't describe a platform you didn't download.INSTALL_STEPS. Each is shown both as a panel heading and as the destination its connector announces; they drifted apart the first time they were separate strings. The feedback form's "which step gave you the most trouble?" options derive fromINSTALL_STEP_ORDERfor the same reason.mailto:rather than posting anywhere — this site has no backend to receive form posts, and a form that silently discarded what someone wrote would be worse than no form. Swapping in a real endpoint is a change tohandleSubmitalone. Worth a decision: if you'd rather this posted to an API route or a GitHub issue prefill, say so.prefers-reduced-motion— the chevron glide, the pulse halo, and the transitions that move things all stop, while the ones that only recolour or fade stay. The button keeps its ring, fill, and label, so it's no less obviously a control.next.config.ts), so existing links and anything indexed keep working. Nav, footer, home/features CTAs, the revalidation cron path, and CONTRIBUTING.md were all updated.Checks
lint,typecheck,format:check, andnext buildall pass./installationprerenders with the 1d revalidate intact.