Skip to content

Land the accepted navigation model: one app bar for every page - #507

Merged
mtaanquist merged 4 commits into
developfrom
feat/navigation-model
Jul 30, 2026
Merged

Land the accepted navigation model: one app bar for every page#507
mtaanquist merged 4 commits into
developfrom
feat/navigation-model

Conversation

@mtaanquist

@mtaanquist mtaanquist commented Jul 29, 2026

Copy link
Copy Markdown
Owner

Ports the accepted navigation model from design-pass session 2. Every page now
wears one bar; the three bars it replaces are gone. Behaviour is unchanged
except where the model changes it.

What migrated, per screen

Screen Now
Editor (Write, Plan, Notes, Review) .appbar with the full path; the story name is a menu, "Go to the story" first. Save pill stays in the tools cluster
Universe Plan and Notes .appbar; the universe crumb has one destination, its Plan. Four modes with the mode-note line
Library .appbar with Library as current text; each universe row carries "Insights" and "Settings" text buttons in place of the gear
Story settings .appbar with the full path; sidebar swapped to .side-nav; the back link is gone
Universe settings .appbar with the full path; .side-nav plus a "Back to the universe" group (Plan, Insights)
Insights .appbar with Library / Universe / Insights; .side-nav over its existing in-page anchors
Account, admin .appbar with Library / Account and Library / Site admin. Their icon-led .admin-nav sidebars stay as they are: not a straight class swap
Print preview .appbar with the full path; Print and Page setup are page-header actions; the one-off print bar is deleted; the paper wears data-theme="light" so its white and its ink are tokens
Guest review .appbar.guest with the "Review only" pill, theme and help tools, and "Reviewing as ..."
Help .appbar plus the article list in the left slot and a "Back to your work" group. The bare pages and the modal are both gone
Reading pages (/@handle, story reader) .appbar.reader with theme support. Prose presentation untouched; full reader retheming is session 3

Deleted

Components: HelpModal.svelte, TopBar.svelte, PageTopBar.svelte,
PaletteButton.svelte (folded into the bar's .tool-search).

CSS, each grepped for references first: .topbar and .page-shell .topbar,
.crumbs/.crumbs .sep, .topbar-right, .brand-mark, .back-link, the
.breadcrumb family, .divider, .save-status, the .review-guest-bar
family, .universe-edit. .app.focus-mode .topbar became
.app.focus-mode .appbar.

Ratified decisions

  1. Place-crumbs are menus. Clicking the universe or story name opens its
    menu; "Go to the universe" / "Go to the story" is the first item, ticked
    when you are already there. No split-click, no gear anywhere in the chrome.
    Menus are real popovers composing .popover/.menu-item, with the repo's
    dismiss action, aria-haspopup/aria-expanded, arrow keys and Escape.
  2. The help modal is deleted. The ? navigates to the help pages, lights
    up via aria-current while there, and returns to the previous location
    when pressed again.

Visible differences to expect, all intentional

  • The story title in the path no longer opens settings. It opens a menu that
    names every destination, settings included.
  • There is no gear anywhere in the chrome, and no icon-only destination.
  • The universe crumb always goes to the same place.
  • Help never opens over the top of your work.
  • The print page and the reading pages gained 52px of chrome at the top.
  • Guests gained a theme control and a help link, and lost nothing.
  • The mode strip is the same width on every screen that has one.

Chrome layer

chrome.css landed as src/lib/styles/chrome.css, imported last in
+layout.svelte after primitives.css. Two fixes while landing it, as
briefed: the header comment described an abandoned iteration ("settings is
never a crumb, it is the gear at the end of the path") and now describes the
final model; .tool-search .kbd targeted a class the primitives
consolidation deleted and now targets the kbd element.

Theme tool

Reconciled with the existing theme.ts rather than added beside it.
flipTheme (light/dark, resolving through the saved system mappings) is
replaced by cycleTheme, which walks the three concrete palettes
dark -> light -> warm. ThemeToggle.svelte became the bar's theme tool, and
UserMenu's theme item now calls the same cycleTheme so there is one
cycle in the product, not two. Signed-in viewers persist through the existing
appearance API; guests and readers keep it in localStorage.

Scope fences honoured

  • Right pane untouched. The tab strip is still
    Reference/History/Session/Assistant. The nav-write mock's "Notes 2" tab was
    ignored as filler.
  • Universe overview restructure deferred. The universe Plan page keeps its
    existing PlanSidebar entity list. Only the app bar, the four-mode strip
    with its note, and a small "Across the universe / Insights" group at the
    foot of the sidebar landed. The mock's side-nav of
    Overview/Characters/Places/... and its new centre sections are not built.
  • Settings content untouched. No universe Colour field (the mock invents
    one; the schema has no such column), no section renames, no new sections.
    Only chrome, paths, and the sidebar skin changed.
  • No schema changes.

Two things worth a decision

  • The reading-page menu item appears only when the story has a current,
    non-removed edition, so the menu never offers a link that 404s. That needed
    a readingPageRef helper in server/publish.ts and a reading field on
    the six story-scoped page loads. When there is no edition the item is
    omitted entirely.
  • /docs is public now (PUBLIC_PATHS plus a /docs/ prefix). The guest
    and reader shells keep the help tool per the shells table, and neither has
    an account, so help had to stop redirecting to /login.
  • The universe mode-note wording is the mock's verbatim: "Write and Review
    need a story open. Both take you to the story list below." In our layout the
    story board is the centre column, to the right of the strip, not below it.
    Kept as briefed, flagged here: say the word and it becomes "Both take you to
    this universe's story list".

Docs and kit

  • design-system.md: new Chrome section (app bar and the three shells, path
    and crumb-menu rules, side-nav, tool-search, mode-strip constants, and the
    rule that anything reachable only from the palette is a bug), shells table
    updated, and the stale TopBar/PageTopBar/HelpModal references cleared
    from the modal section, the new-page checklist and the component index.
  • design.md: the navigation paragraph, the universe four-mode behaviour, and
    the focus-mode sentence now match what ships.
  • Help articles: editor.md (the gear/breadcrumb sentence is now the story
    menu), getting-started.md (the ? is a page you can go back from),
    account.md.
  • New kit card scratch/design-kit/appbar.html with the three shells stacked
    and the crumb menu open, added to the README card list.

Verified locally

  • npm run lint clean, npm run check clean (0 errors, 0 warnings).
  • npm run test:unit: 1077 passed, 1 skipped, 132 files.
  • e2e: 49 passed, 3 failed. All three fail at the same "Prepare ... (.zip)"
    export step (core-flow, import-story, universe-settings): this
    checkout has no .env and so no ASSET_S3_BUCKET, which is the documented
    local baseline. Every chrome assertion passes, including the rewritten ones.
  • Specs updated to the new chrome, keeping the assertions at least as strong
    and preferring role and label selectors: core-flow (crumb menu contents
    and its ticked current item, .appbar in focus mode, settings reached
    through the story menu, the help tool as a place), docs (path, ticked
    article, plus a new test that the ? navigates and returns), review
    (guest shell tools, the four-mode strip with three aria-disabled and the
    note), account (the three-palette cycle; Theme disambiguated from the
    bar's theme tool).
  • Render-verified the new kit card headless in all three themes and read the
    screenshots, plus the library, docs article, print preview, story settings,
    universe Plan and the open story crumb menu in the running app.

Not verified locally

The export-dependent paths (they need MinIO), and everything in core-flow
after its export step, which the local suite cannot reach for the same reason.
CI is the backstop and earned it: it caught one stale selector in that
unreachable stretch, page.locator('.brand'), left over from the deleted
bars. Fixed in the second commit to select the brand by its accessible name.
All three CI checks pass now: Lint/check/unit/build, End-to-end, Docker stack
boots.

mtaanquist and others added 4 commits July 30, 2026 00:19
Every page now wears the same bar - brand, path, tools - replacing the
editor's .topbar, the pages' .page-shell .topbar with its .back-link, the
print page's one-off bar, and .review-guest-bar. Three shells share it:
author, guest, reader.

The two contested decisions, as ratified. A place in the path is a menu:
clicking the universe or story name opens everything that belongs to it,
starting with "Go to the universe" / "Go to the story", settings included as
a word rather than a glyph. There is no gear anywhere in the chrome. And the
help modal is gone: the ? tool navigates to the help pages, lights up via
aria-current while you are there, and returns to where you were when pressed
again, so help is openable in another tab and never covers your work.

Paths are built in $lib/chrome.ts so every screen spells the same
destinations the same way. The theme tool cycles dark -> light -> warm
through the existing theme.ts, persisting to the account when signed in and
to localStorage for guests and readers; the avatar menu's theme item now
walks the same cycle instead of a parallel light/dark flip. The mode strip is
always four modes: at universe scope Write and Review open the universe's
story list, and for a guest three are switched off in place, each case with
one rendered line under the strip saying why.

Deleted: HelpModal, TopBar, PageTopBar, PaletteButton, and the .topbar,
.crumbs, .back-link, .breadcrumb, .save-status, .review-guest-bar and
.universe-edit CSS. /docs is public now, because the guest and reader shells
keep the help tool and neither has an account.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The old bars carried .brand; the app bar's is .appbar-brand. This click sits
past the export step, which the local suite cannot reach without MinIO, so
only CI caught it. Selects by accessible name instead of by class.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@mtaanquist
mtaanquist marked this pull request as ready for review July 30, 2026 03:23
@mtaanquist
mtaanquist merged commit 41151fd into develop Jul 30, 2026
3 checks passed
@mtaanquist
mtaanquist deleted the feat/navigation-model branch July 30, 2026 03:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant