# Navigation

> Kwark has one ladder (Home, project, phase, module, page), one breadcrumb that switches between neighbours, two phases named Write and Prepare to shoot, and a project home that orients before it sends you anywhere.

Source: https://kwark.space/designSystem/patterns/navigation

## The problem

A director is in the Breakdown for Scene 12 and wants to see whether the props she just tagged reached the Schedule. In the old Kwark she had to back out to the project page, find Prepare to shoot, and go in again. The trail at the top looked different in every module: Prepare to shoot drew its own switcher with menu rows centred down the middle; some Write modules showed a trail with no switcher; one screen showed two trails nested inside each other.

At the same time, a first-time writer did not know where to go at all. The phases were called "Understanding" and "Pre-production": not a pair, and jargon to someone who just wants to write.

Navigation has two jobs in Kwark: say where you are in words a writer uses, and let you move to the neighbour you need without going home first.

## Kwark's answer

### One ladder

Everything sits on one ladder, named in plain words:

**Home** (your library) › **Project** (one film, series or franchise) › **Phase** (Write or Prepare to shoot) › **Module** (Outline, Breakdown…) › **Page** (Scene 12, Day 3, Mira).

A franchise adds one rung between Home and the project. Nothing else does. The audit dropped "Personal", "workspace", "Studio" and "story" as container names in menus; a production house is the owner of projects, shown on Home, not a rung of its own.

### Two phases: Write and Prepare to shoot (Decision 0009)

User-facing labels are **Write** and **Prepare to shoot**. "Understanding" survives only as a code name (`?phase=understanding`). The words say what the person is doing, and they are a pair.

**Write** holds: Screenplay, Outline, Characters & Locations, World & Lore, Idea & Themes, Research, Pitch, and Episodes for a series.

**Prepare to shoot** groups its modules by how tightly they are bound to the screenplay:

| Group | Line shown | Modules |
|---|---|---|
| Bound to the script | Rebuilt from the screenplay as it changes. | Breakdown, Shots & Boards, Schedule & Call Sheets, Calendar |
| Departments | Each reads its part of the breakdown. | Camera & Light, Art, Costume & Makeup, Sound & Music, Stunts & Effects, VFX (only the desks this film has) |
| Draws on the script | Its own records, using the script's people and places. | Filming locations, Cast & Crew, Budget, Paperwork |
| Stands on its own | The director's thinking and the film's look. | Director's Book, Look Book |

### Opening a project goes to project home (Decision 0018)

A tap on a story on Home opens **Project home** by default: the poster, the phases and their modules, where work stopped. Some writers want to land straight on the page, so Project settings has one choice, **When I open a project: Project home** (default) **/ Where I left off**. The explicit **Continue writing** button always goes to where work stopped. The default orients; the shortcut for returning writers is one setting away.

### One breadcrumb (Decision 0044)

Every breadcrumb in the app is drawn by `components/ui/Breadcrumb.tsx`, styled only by `--k-crumb-*` tokens, and built by one trail builder (`buildModuleTrail` with `ProjectModuleBreadcrumb`):

`Home ▸ [Franchise ▸] Project ▸ Phase ▾ ▸ Module ▾ [▸ Sub-page ▾]`

- The **Phase** dropdown switches between Write, Prepare to shoot, and **Back to the project**.
- The **Module** dropdown lists the sibling modules the person is allowed into, in the active phase, grouped as above in Prepare to shoot.
- A **non-last** crumb that has both a destination and a dropdown is split: the label navigates, only the chevron opens the menu.
- The **last** crumb (where you are) opens its dropdown wherever you click it.
- Menus open as portals, stay inside the viewport, align icon and label to the left, and answer Arrow Up and Down, Home, End, Enter, Space, Escape and Tab.
- Past five segments, the middle collapses into an ellipsis; never before.

**No breadcrumb** on: the screenplay editor (it has its five menus, Decision 0015), the shot listing workbench (a dense single-row toolbar), phones (they use a one-line header, Decision 0016), and Home, sign-in, About and this design system.

## Anatomy

| Part | Means |
|---|---|
| Home crumb | Your library. Never labelled with a product or company name. |
| Project crumb | The project's name, as the writer wrote it, truncated with an ellipsis at the end. |
| Phase crumb and chevron | Which phase; the chevron opens the phase switcher. |
| Module crumb and chevron | Which module; the chevron opens its siblings. |
| Current crumb | `aria-current="page"`; full contrast; opens its own menu. |
| Separator | A quiet chevron, hidden from screen readers. |

## Rules

- **Must** render every app breadcrumb through the shared `Breadcrumb` component and the shared trail builder. The build enforces it.
- **Must** use the words Write and Prepare to shoot wherever a phase is named: hub, tabs, breadcrumbs, menus.
- **Must** offer only modules the person is allowed into in the module switcher.
- **Must** open a project on Project home unless the person chose Where I left off.
- **Never** centre menu rows; icon and label align left.
- **Never** draw a second, local trail inside a module that already has the shared one.
- **Never** show a breadcrumb on a phone; show back and the one-word title.
- **Never** use internal names in navigation: no "Understanding", "creative lock", "scene database", "visual language".
- **Always** keep the person's place: back returns to the scroll position and selection they left.
- **Always** use the names on the cards: Shots & Boards, Director's Book, Look Book, Camera & Light, Costume & Makeup, Filming locations (Decision 0034).

## Edge cases

- **A module the person cannot open.** It is left out of the switcher. If they arrive by link, they see "{Owner} hasn't shared {module} with you." with **Back to the project**.
- **A series.** Episodes join Write's module list and the screenplay shows the episode in its own dropdown.
- **A very long project name.** Truncate the project crumb at the end with an ellipsis; the full name is in its tooltip and accessible name.
- **A department this film does not have.** Its desk is not listed. Desks that would reach an unbuilt page are hidden, never shown as "still being built".
- **Deep pages.** Scene 12 inside Shots & Boards adds one sub-page crumb with its own dropdown of neighbouring scenes.

## Phone and desktop

On a phone there is no breadcrumb. The header is one line: back chevron, one-word title, **Menu ▾** (see [Phones](https://kwark.space/designSystem/patterns/phones.md)). The Menu sheet carries what the breadcrumb's dropdowns do on desktop: switch phase, switch module, back to the project, each as a row that drills down one page. On tablet and desktop the breadcrumb is one 32px bar under the app header.

## Writing

- Phase names: **Write**, **Prepare to shoot**. The switcher's last row: **Back to the project**.
- Setting: **When I open a project** · **Project home** · **Where I left off**.
- Buttons on Home's desktop rows: **Project home**, **Continue writing**.
- Module names as on their cards, with "&" where the card uses it.

## Accessibility

- The trail is a `nav` with `aria-label="Breadcrumb"`; the current item has `aria-current="page"`.
- Dropdown triggers carry `aria-haspopup="menu"` and `aria-expanded`; a split crumb has two focus stops (the link, then the chevron button named "Choose module" or similar).
- Menus trap arrow keys, close on Escape, and return focus to their trigger.
- Separators are `aria-hidden`.

**Do:** `Blank Pages › Prepare to shoot ▾ › Breakdown ▾`: the chevron on Breakdown lists Shots & Boards and Schedule & Call Sheets, so the director moves sideways in one step.

**Don't:** A Back to project link as the only way out, so every move between modules goes through the hub.

**Do:** Phase switcher rows with icon and label aligned left.

**Don't:** Rows centred in the popover, so icons and labels drift down the middle.

## Demo

```html
<nav class="kw-crumb" aria-label="Breadcrumb"><a class="kw-crumb__item" href="#">Home</a><span class="kw-crumb__sep" aria-hidden="true">›</span><a class="kw-crumb__item" href="#">Blank Pages</a><span class="kw-crumb__sep" aria-hidden="true">›</span><details class="kw-crumb__disclosure"><summary class="kw-crumb__item">Prepare to shoot <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></summary><div class="kw-menu"><a class="kw-menu-item" href="#">Write</a><a class="kw-menu-item" href="#" aria-current="true">Prepare to shoot</a><div class="kw-menu-sep" role="separator"></div><a class="kw-menu-item" href="#">Back to the project</a></div></details><span class="kw-crumb__sep" aria-hidden="true">›</span><details class="kw-crumb__disclosure"><summary class="kw-crumb__item"><span aria-current="page">Breakdown</span> <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="m6 9 6 6 6-6"/></svg></summary><div class="kw-menu"><span class="kw-meta" style="padding:4px 8px">Bound to the script</span><a class="kw-menu-item" href="#" aria-current="true">Breakdown</a><a class="kw-menu-item" href="#">Shots &amp; Boards</a><a class="kw-menu-item" href="#">Schedule &amp; Call Sheets</a><a class="kw-menu-item" href="#">Calendar</a><div class="kw-menu-sep" role="separator"></div><span class="kw-meta" style="padding:4px 8px">Draws on the script</span><a class="kw-menu-item" href="#">Filming locations</a><a class="kw-menu-item" href="#">Budget</a></div></details></nav>
<div class="kw-card" style="display:grid;gap:8px;max-width:420px"><strong>When I open a project</strong><label class="kw-check"><input type="radio" name="open-at" checked><span class="kw-box"></span>Project home</label><label class="kw-check"><input type="radio" name="open-at"><span class="kw-box"></span>Where I left off</label></div>
```

## Related

[Breadcrumb](https://kwark.space/designSystem/components/breadcrumb.md), [Page header](https://kwark.space/designSystem/components/page-header.md), [Menu](https://kwark.space/designSystem/components/menu.md), [Phones](https://kwark.space/designSystem/patterns/phones.md), [Menus and shortcuts](https://kwark.space/designSystem/patterns/menus-and-shortcuts.md), [Sharing and roles](https://kwark.space/designSystem/patterns/sharing-and-roles.md).

## AI readiness test

**Task:** Add the new Paperwork module's pages to navigation.

**Give the agent:** This page, Decisions 0009, 0018, 0044, components/ui/Breadcrumb.tsx.

**Constraint:** No new breadcrumb code.

**A reliable answer:**
- Uses buildModuleTrail and ProjectModuleBreadcrumb, not a local trail
- Lists Paperwork under Draws on the script in the module switcher, only for people allowed in
- Sub-pages get one crumb with a sibling dropdown
- Phone shows back, "Paperwork" and Menu, no breadcrumb
- Uses Prepare to shoot, never Pre-production, in visible text
