PRD — the universe theme
Why the site needed a wider sky than one solar system, and what the Verse must do for readers moving between its levels.
- Status: Current
- Last updated: 2026-11-01
- Related ADRs: ADR-0029
Snapshot of the system as it stands today. Edit in place; never record what changed.
Problem
The site is named Nepal Dev Verse, but nothing on it is bigger than one solar system. The brand mark borrows the project mark, reading pages have no sky, and moving between the home page, a planet and its pages feels like any other page change. The levels above a folder are named nowhere on a docs page.
Goal
- One mark and one still sky on every page (stage 1).
- One scale ladder readers can see and move through: a strip on every docs page, a Verse view on the home page, and a zoom when they move up or down it (stage 2).
- Words that describe the site in its own terms without renaming a single control (stage 3).
Non-goals
- Changing the solar-system metaphor, the marks' meanings or the sidebar (ADR-0017, ADR-0027).
- Any motion that keeps going besides the turning system.
- Showing private projects in a new way; the Verse view uses the invented names already shown.
- Changing URLs or any Markdown surface.
User stories
| # | Story | Acceptance criteria |
|---|---|---|
| US-1 | As a reader, I want every page to look like the same place, so that I know I am still on Nepal Dev Verse. | - The header shows the Verse mark on every page, and the browser tab shows it as the icon. - Every page stands on the same still sky, in both themes. - No star sits behind text; every text contrast in DESIGN.md is unchanged. |
| US-2 | As a reader, I want to see where a page sits, so that I can go up a level in one tap. | - Every docs page shows the scale strip from Verse down to the page, with each level's mark. - On a phone it shows the parent level with a back arrow and the current page. - The current page has aria-current="page"; the strip is a nav labelled Scale. |
| US-3 | As a visitor on the home page, I want to zoom out past the system, so that I see what the Verse is. | - Zoom out to the Verse eases out to the Verse view; Back to the system or the system eases back. - /#verse opens the Verse view.- With reduced motion it changes instantly. |
| US-4 | As a reader, I want opening a planet to feel like moving closer, so that I keep track of what I chose. | - The card's planet morphs into the overview's planet header, and back. - Strip and planet chip links zoom in going down and out going up. - Without view transitions or with reduced motion, navigation is unchanged. |
| US-5 | As a reader in a hurry, I want controls to keep their plain names, so that the theme never slows me down. | - Search, Overview, Use, Maintain, On this page and version names are unchanged. - Every space word appears next to a plain sentence. |
Success
- The owner, reviewing each stage in the working tree, accepts it before the next starts.
impeccable detectreports nothing new in the changed files.- No change to
/<page>.md,llms.txtorllms-full.txtfor any page.
PRD — site pages: root URLs, versions, user and maintainer docs, one look
What the site's structure must do for readers: short addresses, version lines, separate user and maintainer docs, and one look throughout.
API
Contracts for every route another client or system calls: Markdown, llms.txt, search records, crawler routes and any future integration.