Skip to content

App navigation

Generated from openspec/specs/app-navigation/spec.md — edit that file, not this page.

How a signed-in user moves around Tinkerspace: the destinations the shell offers, what it reports while a navigation is in flight, and what remains visible when a surface takes over the whole screen.

Covers the left rail, the position trail (breadcrumbs), the route-progress indicator, and the ⌘K jump palette — on shell pages and on the full-screen editor and walkthrough, which sit outside AppShell and would otherwise each invent their own way back.

Integrating without duplicating:

  • Which destinations a user may reach is decided in one place — apps/web/lib/nav/destinations.ts. The rail and the palette both read it. Adding a destination means adding it there, not in a component. Do not restate the admin / sales rules anywhere else: who may see a destination is auth-orgs-admin’s requirement, and this capability only consumes it.
  • The trail is derived, not stored — apps/web/lib/nav/crumbs.ts maps a pathname plus whatever context the caller already has (org name, project name) to the crumb list. A new route that should appear in the trail is an entry in that map.
  • Motion is gated in one stylesheet — apps/web/app/_components/nav/nav-chrome.ts. Both the reduced-motion rule and the “yield to the 3D canvas” rule live there. New navigation chrome should take an ash-* class rather than inline its own transitions, or it will silently escape both gates.
  • Not in scope here: the editor’s own toolbar chrome (floorplan-editor, modeling-tools), the walkthrough’s in-scene HUD (walkthrough), and authentication or role assignment (auth-orgs-admin).

Requirement: Every navigation control reports its interactive state

Section titled “Requirement: Every navigation control reports its interactive state”

The signed-in shell’s navigation SHALL give each destination a resting, hover, pressed and keyboard-focus appearance, distinct from one another. A destination that looks identical whether or not the pointer is over it gives the user no way to confirm what they are about to click.

Keyboard focus SHALL be visible without a pointer, and SHALL NOT be conveyed by the same treatment as the active route — a user tabbing through the nav must be able to tell where focus is from where they currently are.

  • WHEN the pointer rests over a navigation destination that is not the current route
  • THEN its background and label change to indicate it is the thing that would be activated

Scenario: Focusing a destination by keyboard

Section titled “Scenario: Focusing a destination by keyboard”
  • WHEN the user moves keyboard focus onto a navigation destination
  • THEN a focus indicator is shown that is distinguishable from the current-route treatment

Requirement: The current destination is marked by one continuous indicator

Section titled “Requirement: The current destination is marked by one continuous indicator”

The shell SHALL mark the current route with a single indicator shared across the navigation, and SHALL move it from the previous destination to the new one when the route changes, rather than removing one mark and drawing another elsewhere.

The indicator SHALL be positioned without animation on first paint, so that arriving at a page does not animate the marker in from an unrelated position.

  • WHEN the user activates a different navigation destination
  • THEN the current-route indicator moves from the old destination to the new one
  • WHEN a page is loaded directly at its URL
  • THEN the indicator is already at the correct destination on first paint, without travelling to it

Requirement: Only a slow navigation is reported

Section titled “Requirement: Only a slow navigation is reported”

The shell SHALL indicate that a navigation is in flight, and SHALL NOT show that indication for a navigation that resolves quickly. A navigation indicator that appears on every click is noise the user learns to ignore, which costs the indication its meaning when a wait is genuinely long.

The indication SHALL be cleared when the navigation completes, and SHALL NOT persist if a navigation never completes.

  • WHEN a navigation completes faster than the reporting threshold
  • THEN no progress indication is ever shown
  • WHEN a navigation remains in flight past the reporting threshold
  • THEN a progress indication appears, and is removed once the destination has rendered

Scenario: An abandoned navigation does not strand the indicator

Section titled “Scenario: An abandoned navigation does not strand the indicator”
  • WHEN a navigation is superseded or never resolves, and the user arrives at some other route
  • THEN the progress indication is cleared rather than remaining on screen

Requirement: Hierarchy remains visible on full-screen surfaces

Section titled “Requirement: Hierarchy remains visible on full-screen surfaces”

Surfaces that take over the whole screen — the project editor and the walkthrough — SHALL show the user’s position as a trail from their workspace down to the current surface, and SHALL let the user move to any ancestor in that trail.

The trail SHALL name the active workspace, so a user who belongs to more than one organization can tell which one the open project belongs to without leaving the surface.

Offering only a return to the projects list is insufficient: it discards the intermediate steps, so a user who wants the project rather than the list has no way to ask for it.

  • WHEN a project is open in the editor
  • THEN the workspace and the projects list are shown and are activatable, and the open project is named as the current surface
  • WHEN a project is open in the walkthrough
  • THEN the same trail is shown, and leaving the walkthrough for the project does not require going out to the projects list first
Section titled “Scenario: The current surface is not a link”
  • WHEN the trail is shown on any surface
  • THEN the final entry is the current surface and is not activatable

Requirement: Any permitted destination is reachable from one keyboard command

Section titled “Requirement: Any permitted destination is reachable from one keyboard command”

The shell SHALL provide a single keyboard command that opens a search over the user’s projects and every navigation destination, and SHALL navigate to a chosen result.

The destinations offered SHALL be exactly those the user is permitted to see. The command SHALL NOT offer a destination that the navigation itself would hide from that user — in particular a user whose platform role grants one admin surface SHALL NOT be offered any other admin surface.

  • WHEN the user presses the palette shortcut and chooses a result
  • THEN the application navigates to that destination
  • WHEN a user whose platform role permits only the invoice surface opens the palette
  • THEN no other admin destination appears among the results
  • WHEN the palette is open and the user presses Escape or activates outside it
  • THEN it closes without navigating

Requirement: Navigation motion honours the user’s motion preference

Section titled “Requirement: Navigation motion honours the user’s motion preference”

Where the user’s system requests reduced motion, the shell SHALL present navigation state changes without animating them, and SHALL stop continuous looping animations such as spinners and loading shimmers.

No navigation state SHALL be conveyed by motion alone: the current destination, a pending navigation and the user’s position in the hierarchy SHALL each be readable from a single still frame.

  • WHEN the user’s system requests reduced motion
  • THEN navigation state changes take effect immediately rather than animating, and looping loading animations do not run

Scenario: State is readable without motion

Section titled “Scenario: State is readable without motion”
  • WHEN navigation is rendered with all animation suppressed
  • THEN the current destination, any pending navigation, and the position trail are all still distinguishable

Requirement: Shell animation yields to the 3D canvas

Section titled “Requirement: Shell animation yields to the 3D canvas”

The shell SHALL suppress its own animations while a 3D canvas is mounted, so that navigation chrome does not compete for frame budget with the editor or the walkthrough.

  • WHEN a surface with a live 3D canvas is mounted
  • THEN shell navigation chrome changes state without animating