App navigation
Generated from
openspec/specs/app-navigation/spec.md— edit that file, not this page.
Purpose
Section titled “Purpose”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 theadmin/salesrules anywhere else: who may see a destination isauth-orgs-admin’s requirement, and this capability only consumes it. - The trail is derived, not stored —
apps/web/lib/nav/crumbs.tsmaps 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 anash-*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).
Requirements
Section titled “Requirements”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.
Scenario: Hovering a destination
Section titled “Scenario: Hovering a destination”- 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.
Scenario: Changing route
Section titled “Scenario: Changing route”- WHEN the user activates a different navigation destination
- THEN the current-route indicator moves from the old destination to the new one
Scenario: Loading a page directly
Section titled “Scenario: Loading a page directly”- 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.
Scenario: A fast navigation shows nothing
Section titled “Scenario: A fast navigation shows nothing”- WHEN a navigation completes faster than the reporting threshold
- THEN no progress indication is ever shown
Scenario: A slow navigation is reported
Section titled “Scenario: A slow navigation is reported”- 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.
Scenario: Inside the editor
Section titled “Scenario: Inside the editor”- 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
Scenario: Inside the walkthrough
Section titled “Scenario: Inside the walkthrough”- 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
Scenario: The current surface is not a link
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.
Scenario: Opening and jumping
Section titled “Scenario: Opening and jumping”- WHEN the user presses the palette shortcut and chooses a result
- THEN the application navigates to that destination
Scenario: Results respect role gating
Section titled “Scenario: Results respect role gating”- WHEN a user whose platform role permits only the invoice surface opens the palette
- THEN no other admin destination appears among the results
Scenario: Dismissal
Section titled “Scenario: Dismissal”- 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.
Scenario: Reduced motion requested
Section titled “Scenario: Reduced motion requested”- 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.
Scenario: The editor is open
Section titled “Scenario: The editor is open”- WHEN a surface with a live 3D canvas is mounted
- THEN shell navigation chrome changes state without animating