App flow — docs sidebars: orbit stations, the trajectory and the horizon
What a reader sees around a docs page: the planet row and orbit stations, the trajectory, its bar on phones and the horizon below.
- Status: Current
- Last updated: 2026-11-01
- Related ADRs: ADR-0019, ADR-0018, ADR-0017, ADR-0027, ADR-0030
Snapshot of the system as it stands today. Edit in place; never record what changed.
What a reader sees around a docs page (ADR-0018): the left sidebar's planet row
and orbit stations, the right-hand "On this page" trajectory, its bar on phones, and the full
horizon below. Sample values are invented (ADR-0008): lodestar is not a real package. Phone
width first; desktop differences are noted under each screen. The marks (planet, moons, sun and
moon) are those of The solar system; the characters in the wireframes stand
for drawn SVG.
The flow and every screen are drawn with Archify; the page shows them and its Markdown
carries their Mermaid (ADR-0022). Their sources are in diagrams/docs/: docs-sidebars.json for the
flow, one docs-sidebars-screen-<n>.json per screen.
Entry points
- Every page inside a package or project,
/<slug>/…, and this site's own pages under/docs. - On phones the left sidebar is Fumadocs' drawer, opened from the header; the trajectory is the bar under the header.
- Everyone sees the same pages. Nothing here depends on who the reader is.
- The per-page Markdown (
/<page>.md) andllms.txtcarry none of this; they are the page's content only.
Flow
Screens
1. Planet row and orbit stations — the left sidebar, /lodestar/use/v0.1/install
The planet row: the chip links to /lodestar; the sun and moon buttons open the same page on
Use or Maintain ("Use, the day side" and "Maintain, the night side" as names and tooltips).
Below it the sidebar is a scale ladder (The sidebar's scale ladder,
ADR-0027): top-level pages are landmarks, separators are belts, folders are orbits. A closed
orbit is a row with its ring, name and page count; the open one is the sidebar's one card, its
border in the ecosystem colour when it holds the current page, its ring with a planet inside.
Its pages are satellites on one outward-bowing arc, and the current page is the teal probe. One
orbit is open at a time at each level: opening one closes the open one beside it, and a page
change opens that page's orbits and closes the rest (One open station).
Desktop: the same, in the sidebar column; the sidebar's collapse button works as today. Phone: the same inside Fumadocs' drawer.
A nested folder is a smaller orbit inside its parent's card, never a card of its own. A folder
holding only its index page is an orbit link, with no count. A folder named
adr is a constellation instead, one moon per ADR (The ADR constellation).
States
- Empty: a track with no folders shows only its landmarks; a track without separators shows no belts.
- Loading: none; the sidebar is prerendered with the page. Before scripts load, orbits show in their starting state (the current one lifted, others as rows) and the chevrons do nothing until hydration.
- Not found: an unknown page gets the out-of-orbit 404, which has no sidebar.
- Refused: not applicable; every page is public.
- Error: not applicable at runtime; a broken
meta.jsonfails the build (ADR-0013). - Degraded: with reduced motion, orbits lift and drop without animation. On touch screens no tooltips; the buttons' names are read out.
- One track: no sun and moon buttons. Maintain: no moon picker.
- Success: a moon opens its page; the sun or moon opens the same page on the other side when it exists, else that side's first page.
2. Trajectory — "On this page", desktop column
The path curves through every dot: shallow outward arcs between headings of the same depth, an S-curve where depth changes. The read stretch is solid accent with filled dots; ahead is dashed and muted with hollow dots. The probe planet glides along the path as the reader scrolls. The column sits to the right of the page from Fumadocs' desktop breakpoint up.
States
- Empty: a page without headings shows "On this page", its reading time, and "This page has no sections."; no path.
- One heading: one dot and the probe on it; no path.
- Loading: none; prerendered. Before scripts load the whole path is drawn dashed with hollow dots, no probe, and the header shows the total, "4 min read".
- Long lists: the column scrolls, and keeps the probe's row in view.
- Not found, refused, error: not applicable.
- Degraded: with reduced motion the probe jumps from dot to dot and headings scroll into view instantly. Without scripts the headings are plain links that still jump.
- A page under one minute: no time shown. At the end of the page: "End of page".
- Success: choosing a heading scrolls to it; Back to top returns to the top of the page.
3. Phone bar and sheet — under the header, phone width
The bar replaces Fumadocs' table-of-contents bar: a small ring with the probe at the reading position, the current heading (truncated), the time left and a chevron. Tapping opens the same trajectory as a sheet; choosing a heading scrolls there and closes it.
States
- Empty: a page without headings has no bar.
- Before the first heading: the bar shows the first heading, muted, and the total time.
- Degraded: with reduced motion the sheet opens without sliding. Without scripts the bar does not open; the page reads normally.
- Success: the reader jumps to a section and the sheet closes.
4. Full horizon — below every docs page
The same footer as the home page (The solar system, screen 5), across the full width; its last link reads "Back to top". It rises over the sidebar and the trajectory, which set below its dusk edge as it comes into view (The living horizon, screen 2).
States
- Empty: with no public entries, the planet row is left out.
- Degraded: with reduced motion Back to top jumps instead of scrolling, the sky is still and the sidebar does not set. Without scripts Search and Back to top do nothing and the sky is still; the links work.
- Success: a planet link opens its overview; Search opens the dialog; Back to top returns to the top of the page.