# PRD — the universe theme (/docs/maintain/prd/universe-theme)

- **Status:** Current
- **Last updated:** 2026-11-01
- **Related ADRs:** [ADR-0029](../adr/ADR-0029-the-verse-is-a-still-sky-you-zoom-through.mdx)

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

## Problem [#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 [#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 [#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 [#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.<br />- Every page stands on the same still sky, in both themes.<br />- 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.<br />- On a phone it shows the parent level with a back arrow and the current page.<br />- 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.<br />- `/#verse` opens the Verse view.<br />- 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.<br />- Strip and planet chip links zoom in going down and out going up.<br />- 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.<br />- Every space word appears next to a plain sentence. |

## Success [#success]

- The owner, reviewing each stage in the working tree, accepts it before the next starts.
- `impeccable detect` reports nothing new in the changed files.
- No change to `/<page>.md`, `llms.txt` or `llms-full.txt` for any page.