# PRD — docs sidebars: orbit stations, the trajectory and the horizon (/docs/maintain/prd/docs-sidebars)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0018](../adr/ADR-0018-docs-pages-get-orbit-stations-a-trajectory-and-the-full-horizon.mdx),
  [ADR-0027](../adr/ADR-0027-the-sidebar-is-a-scale-ladder-with-one-lifted-orbit.mdx),
  [ADR-0030](../adr/ADR-0030-the-horizon-rises-over-the-page-and-its-sky-comes-alive.mdx)

> Snapshot of the system as it stands today. Edit in place; never record what changed.

## Problem [#problem]

Readers spend most of their time on docs pages, between the left sidebar and "On this page".
Both are Fumadocs' defaults with a dot added: long sidebars, such as this site's Maintain track
with twelve sections, are a long list of rows, and "On this page" is a straight line on any page
whose headings are one depth. Neither says how much of the page is left. Docs pages also end on a
shortened footer that differs from every other page's.

## Goal [#goal]

- Each sidebar level reads as a smaller body than the one above it: landmarks, belts, orbits,
  satellites; only the open orbit is a card (ADR-0027).
- "On this page" curves on every page, shows where the reader is, and how long is left.
- Every page, docs pages included, ends on the same full horizon, with a living sky, and nothing
  of the sidebar or the trajectory sits on it.

## Non-goals [#non-goals]

- Changing page headings, body text or the reading column.
- Changing the moon picker, version notices or planet header (ADR-0017).
- Search, the header and the theme switch.

## User stories [#user-stories]

| # | Story | Acceptance criteria |
|---|---|---|
| US-1 | As a **reader**, I want **to see the sections of a package at a glance**, so that **I can find the right page in a long sidebar**. | - Each folder is an orbit row with its ring, name and page count; the open one is the sidebar's one card (ADR-0027).<br />- The orbit holding the current page is open; the others are rows.<br />- Separators group orbits under belts; top-level pages are landmarks above them.<br />- The chevron opens and closes an orbit; opening one closes the open one beside it, at every level (ADR-0023). |
| US-2 | As a **reader**, I want **to see where I am in the sidebar**, so that **I keep my place**. | - The current page is the teal probe on its orbit's arc, its row tinted, with `aria-current="page"`.<br />- Its orbit's ring takes the ecosystem colour, with a planet inside while it is open. |
| US-3 | As a **reader**, I want **to switch between Use and Maintain from the sidebar's first row**, so that **it takes no extra space**. | - The chip and the sun and moon buttons share one row.<br />- Each button has its full name as its accessible name and tooltip. |
| US-4 | As a **reader**, I want **to see how far through a page I am**, so that **I know what is left**. | - The read stretch of the path is solid with filled dots; ahead is dashed with hollow dots.<br />- A probe rides the path at the reading position. |
| US-5 | As a **reader**, I want **to know how long the rest of the page takes**, so that **I can decide to read now or later**. | - The header shows the minutes left, from the build-time word count at 220 a minute, rounded up.<br />- "End of page" at the end; no time for a page under a minute. |
| US-6 | As a **reader on a phone**, I want **the same progress and section list**, so that **I can jump without scrolling back up**. | - The bar under the header shows the ring, the current heading and the time left.<br />- Tapping opens the trajectory; choosing a heading scrolls there and closes it. |
| US-7 | As a **reader at the end of a docs page**, I want **the same footer as every page**, so that **the site feels like one place**. | - The full horizon, with its closing line and scene, closes every docs page.<br />- Its last link reads "Back to top".<br />- The sidebar and the trajectory set below its dusk edge as it comes into view, and come back as the reader scrolls up. |
| US-8 | As a **reader who prefers less motion, or uses a keyboard or a screen reader**, I want **the same information**, so that **nothing depends on animation or pointing**. | - With reduced motion, stations and the sheet open without animation and the probe jumps.<br />- Stations, headings and buttons are reachable by keyboard and named for screen readers. |

## Rules and edge cases [#rules-and-edge-cases]

- A track with no folders shows its landmarks only. A nested folder is a smaller orbit inside
  its parent's card. A folder holding only its index page is an orbit link with no count.
- A page without headings shows its reading time and "This page has no sections." on desktop,
  and no bar on phones. One heading: one dot, no path.
- Before scripts load, stations show their starting state, the path is dashed throughout with
  the total reading time, and there is no probe.
- Reading time counts the page's headings, paragraphs, quotes, tables and components, not its
  code blocks.
- While the horizon is in view, the bottom of the sidebar is hidden under it; on a page shorter
  than the window the sidebar stands partly below the horizon on arrival, and its upper part and
  its own scrolling still work.
- The horizon's sky loops only while it is on screen; with reduced motion it is still and the
  sidebar does not set.

## Out of scope for now [#out-of-scope-for-now]

- Remembering which stations a reader opened, across pages or visits: it would need browser
  storage and a decision of its own.

## Open questions [#open-questions]

None.