Nepal Dev VerseGitHub

ADR-0027 — The sidebar is a scale ladder with one lifted orbit

The sidebar is drawn as a ladder of ever smaller bodies, from planet and moon down to belts, orbits and satellites, with only the open orbit lifted.

Context

The owner reported on 2026-11-01 that the docs sidebar does not feel good: "so many card like view, while overview and maintainer documentation is small". The hierarchy should be rethought now that the content is known.

What the sidebar shows today (ADR-0018 decision 2, ADR-0023, ADR-0025; src/components/docs/orbit-station.tsx, src/app/site.css):

  • Every folder is a card, open or closed: a bordered panel with a glyph, the name, a count pill and a chevron. This site's Maintain track has 12 folders holding 0 to 25 pages, so its sidebar is a column of 12 equal cards, and a folder with one page weighs as much as the ADRs.
  • Top-level pages are the smallest rows. Overview and Maintainer documentation, the two entry points, are 13.5px muted rows on a short arc above the cards.
  • Nothing groups the folders. Fumadocs separators (---Label--- in a meta.json) render as a dotted rule, but no track uses them.
  • The content is now known: a package's Use line holds a few pages and a few folders (getting started, guides, reference); a project of several repositories adds a folder per repository (ADR-0024); this site's Maintain holds 2 pages and 12 folders, the ADRs among them.

The owner chose on 2026-11-01:

  • One lifted card: only the open folder is a card; closed folders are plain rows; top-level pages are full-size rows;
  • group labels for long tracks, starting with this site's Maintain;
  • the scale ladder: each sidebar level is a smaller body than the one above it, following the universe hierarchy the owner wants for the whole site;
  • the rename to the first Verse name and the whole-site universe theme in a separate ADR (ADR-0028), after this one.

Decision

  1. Each level of the sidebar is a smaller body than the one above it. From the top:

    LevelBodyMark and type
    The entryPlanetThe planet row: chip and the sun and moon (ADR-0018 decision 1), unchanged
    A version lineMoonThe moon picker (ADR-0013), unchanged
    A top-level pageLandmark satelliteAn 8px satellite dot, the name in 14.5px Text 500, Frost Ink
    A groupBeltA small label (11px Text 600, uppercase, 0.08em tracking, Steel Faint) on a dotted hairline running to the edge
    A folderOrbitA 12px ring, the name in 14px Text 500, the page count in 11.5px Data, Steel Faint, at the right
    A page in a folderSatelliteA 6px hollow dot on the orbit's arc, the name in 13.5px Text
    The current pageProbeA 9px teal dot with its glow, the row tinted with 10% of the ecosystem colour, Frost Ink 500

    Moons stay version lines only (DESIGN.md, The Mark Means Rule); a page is a satellite.

  2. Only the open orbit is a card. A closed folder is a plain row: no border and no fill, its ring, name and count, and a chevron in Steel Faint. The open folder lifts into the one card in the sidebar: Graphite Panel, a hairline border, 12px corners; its ring fills with a planet (as the station glyph does today), and its satellites follow on their arc. When it holds the current page its border takes 45% of the ecosystem colour, as today. Opening a folder lifts it and drops the open one back to a row (ADR-0023, unchanged).

  3. Nested folders stay inside the card. A folder inside the open orbit is a smaller orbit row (a 10px ring, 13.5px name). Opening it shows its satellites indented inside the same card; there is never a card inside a card. ADR-0023 holds at each level.

  4. Top-level pages are landmarks. Pages directly in a track or line (the Overview item of ADR-0025, a track's own index listed in its pages, any other top-level page) sit above the first belt or orbit as full-size rows. The current one is the probe.

  5. Belts group orbits. A Fumadocs separator in a meta.json is drawn as a belt (decision 1), with 18px above it. A track without separators shows no belts. This site's Maintain track gets four, in content/docs/maintain/meta.json:

    BeltFolders
    DecisionsADRs
    DesignArchitecture, App flows, Product requirements, API, Data flow diagrams, Sequence diagrams, State machines, ERD
    SecurityAccess control, Security
    TemplatesTemplates

    PROJECT_AGENTS.md tells consuming repositories they may group their own tracks the same way.

  6. A folder holding only its index is a plain orbit link. It shows its ring and name, no count and no chevron, and opens its index page (today it shows a count of 0).

  7. The ADR constellation (ADR-0019) is unchanged, inside the ADRs' card when it is open.

  8. Unchanged: the planet row, the moon picker, the trajectory, the version notices, the pages' arc, one open orbit at each level (ADR-0023), the overview's sidebar (ADR-0025), keyboard behaviour (Fumadocs' collapsible trigger and aria-expanded), and the phone drawer, which shows the same sidebar. With reduced motion an orbit lifts and drops without animation.

Options considered

ConcernOptionProsConsVerdict
ShapeA — one lifted cardSmallest change; the card says "you are in this orbit"Closed folders lose their glyph-in-a-box lookChosen (owner)
ShapeB — orbit rail: no cards, one continuous orbit line with every page and folder on itEchoes the trajectory on the rightThe biggest change; a long rail is hard to scanRejected (owner)
ShapeC — drill-in levels: one level at a time, ← backCalm at every sizeHides the sibling folders; replaces ADR-0023Rejected (owner)
MarksA — scale ladder: a body per level, sized to its rankFollows the universe hierarchy; rank shows in sizeOne more mark (the ring) per closed rowChosen (owner)
MarksB — bodies only up top, plain type belowQuietestLoses the theme below the planet rowRejected (owner)
GroupsA — belts from meta.json separatorsUses Fumadocs' own separators; a content choice per trackEach track's maintainers place themChosen (owner)
GroupsB — one listNothing to maintainTwelve folders in one runRejected (owner)

Consequences

Positive

  • One card in the sidebar at a time, so the reader sees where they are at a glance.
  • The two entry points, Overview and the track's own index, read as the most important rows.
  • Long tracks scan by group.

Negative / accepted trade-offs

  • A closed folder is quieter than today; its count and ring carry its weight.
  • Belts need a separator per group in each track's meta.json; a track without them shows one list.
  • The sidebar's look changes on every docs page at once.

Content invariants

None touched: the change is to how the sidebar looks, and to the order labels of this site's own Maintain track. Pages, URLs, per-page Markdown and llms.txt stay as they are (a separator adds a bold label line to llms.txt, which keeps it readable).

Security considerations

None — this change touches no data, no endpoint and no secret. It changes the sidebar's presentation and one meta.json.

Implementation notes

  • src/components/docs/orbit-station.tsx: a closed folder is a row and the open one the card (decisions 2, 3), through Fumadocs' data-open on the folder; landmarks (decision 4); belts (decision 5); a folder holding only its index as an orbit link (decision 6). The tree and ADR-0023's group logic are unchanged. The open orbit's planet sits at the ring's centre: on the ring it read as a broken ring at 12px.
  • src/app/site.css: the ladder's marks and type (decision 1), the card only on the open orbit, the belt; reduced motion.
  • content/docs/maintain/meta.json: the four belts (decision 5).
  • Tests (ADR-0007, ADR-0021): countPages(), pageBody() and folderBody() in src/lib/sidebar-ladder.ts as pure functions, and the belts in this site's Maintain meta.json (src/lib/sidebar-ladder.test.ts). The rendered client component is checked in Chrome until a DOM is chosen.
  • Checked in Chrome on localhost at desktop width, dark and light: /docs/maintain/prd/diagrams (landmarks, belts, rows, the one card), an ADR page (the constellation inside the ADRs card; ERD and Access control as orbit links), and a temporary invented package (content/lodestar/, deleted afterwards) with a nested folder inside the card; opening Reference lifted it and dropped Guides back to a row, its ring still in the ecosystem colour. The phone drawer was not seen: the automated window does not resize.
  • impeccable detect over the changed files: one advisory, font-size: 11px in the existing profile chip (ADR-0020), not in this change. bun run test, bun run types:check and bunx next build pass; bun run lint is reported while it stays blocked.

Docs to update on implementation

ADR-0026 — The moon picker on an overview opens a line's first page

On an overview, choosing a version line in the moon picker opens that line's first page, since the overview itself has one copy.

ADR-0028 — The site gets its first Verse name

The site takes its first Verse name, shown in its header, titles and share images, and its own documentation takes the same name with Docs.

On this page

9 min read
  1. Context
  2. Decision
  3. Options considered
  4. Consequences
  5. Content invariants
  6. Security considerations
  7. Implementation notes
  8. Docs to update on implementation