sow-nodebb-theme/docs/superpowers/specs/2026-06-26-global-topbar-design.md

# Global Topbar Design Spec

Date: 2026-06-26
Status: draft, goal definition

## Goal

Complete the Westgate global topbar as the theme-owned replacement for
Harmony's NodeBB sidebars.

The current `custom_pages/westgate-pages/top-bar.html` and
`custom_pages/westgate-pages/topbar-custom.js` files are reference material from
the design extraction. They show the intended visual language and rough
interaction shape, but they are not production behavior. The finished topbar
belongs in this theme as global chrome, not as ACP Custom Content pasted onto
individual pages.

The topbar must make website pages, wiki pages, and forum pages feel like one
Westgate application while preserving real NodeBB account, navigation, search,
notification, chat, draft, and status behavior.

## Evidence Checked

- `docs/superpowers/specs/2026-06-26-website-pages-design.md` already defines
  the topbar as the owner of Harmony sidebar functions.
- `custom_pages/westgate-pages/THEME-INTEGRATION.md` recommends a
  `templates/partials/header/topbar.tpl` theme partial and reuse of Harmony live
  components.
- `custom_pages/westgate-pages/top-bar.html` is a visual/reference draft with
  placeholder avatar, notification, chat, and draft data.
- `custom_pages/westgate-pages/topbar-custom.js` is a paste-ready preview
  controller for ACP Custom JavaScript, with comments noting where live NodeBB
  behavior still needs to replace preview behavior.
- `templates/header.tpl` currently imports `partials/sidebar-left.tpl` and lays
  out `#panel` beside the sidebar.
- Harmony still supplies the inherited right sidebar through its footer unless
  Westgate overrides that path.
- `theme.scss` is imports-only and already imports focused files from
  `scss/westgate/`.

## Required Behavior

The Westgate topbar replaces the NodeBB sidebar experience. It must own every
user-facing button or action that currently lives in Harmony's desktop sidebars
or duplicate mobile bars:

- Brand/home entry.
- ACP Navigation links and active states.
- Forum/category entry points.
- Search, including NodeBB quick search behavior.
- Notifications, with real unread counts and notification list behavior.
- Chats when chat is available to the user.
- Drafts, with real draft count, open, and delete behavior.
- User avatar menu using the logged-in user's real avatar.
- User status controls that set the user's actual NodeBB status, including
  online, away, and invisible when supported by the running NodeBB version.
- Profile, bookmarks, edit profile, settings, moderator/admin affordances, and
  logout.
- Guest login and register actions.
- Mobile equivalents for the same primary actions.

The topbar is not allowed to pretend that live data exists. If the current user
has no notifications, chats, or drafts, the topbar must show the real empty or
hidden state. Counts must come from NodeBB data, not hard-coded badge text.

## Visual Direction

Use the draft topbar as a visual target, not as final source. The production
topbar should keep the black velvet, near-black plum, muted gold, restrained
contrast, and small red state detail direction already established by the
Westgate theme.

All substantive styling belongs in a focused SCSS partial such as
`scss/westgate/_topbar.scss`, imported from `theme.scss`. The partial should use
existing `--wg-*` tokens where possible and should not introduce a second visual
system.

Harmony sidebar buttons should be restyled as topbar controls. They should feel
native to the topbar, not like sidebar markup awkwardly placed in a horizontal
row.

## Post-Review Refinements

Screenshots captured on 2026-06-26 show the topbar working visually, but with
three refinements needed before the topbar feels fully integrated.

Drawer and dropdown menus must be opaque. The current translucent treatment lets
page content show through account, forum, and drawer surfaces, which weakens
readability and makes the controls feel less deliberate. Keep the near-black and
plum surface direction, but use an opaque panel base; decorative highlights,
borders, and shadows may remain subtle.

The brand lockup should be simplified to one identity line: the circular mark
followed by `SHADOWS OVER WESTGATE`. Do not repeat `Shadows Over Westgate` as a
subtitle in the topbar, and do not allow the primary brand name to truncate in
normal desktop layouts. Longer project context such as `An NWN:EE Roleplaying
Experience` belongs on larger page surfaces, not in the dense global chrome.

The custom right-side `Forums` dropdown is redundant when ACP Navigation already
contains a Forums entry. Prefer one seamless navigation model: remove the
separate desktop Forums dropdown and let forum entry points live in ACP
Navigation or in the mobile drawer as direct links. If ACP-managed navigation
needs to drop text bubbles or helper labels to make this feel clean, that is
acceptable.

## Implementation Direction

The production implementation should be theme-first:

- Add a focused topbar partial, likely
  `templates/partials/header/topbar.tpl`.
- Mount the topbar from `templates/header.tpl`.
- Remove the global Harmony left sidebar from the main layout.
- Override the Harmony footer path if needed so the right sidebar no longer
  renders as a separate global sidebar.
- Let `#panel` become the normal main content column under the topbar.
- Keep `theme.scss` imports-only.
- Put topbar CSS under `scss/westgate/`.
- Put topbar client behavior in the theme client bundle unless an ACP bridge is
  explicitly chosen as a temporary deployment step.

Where possible, reuse Harmony or NodeBB partials and component hooks for live
behavior instead of rebuilding dynamic systems. Important hooks include search,
notifications, chat, drafts, user controls, and status controls. If preserving
Harmony selectors would produce brittle markup, update the theme JavaScript
intentionally and document the changed selector contract.

## Reference Files

The reference files may be copied from selectively, but they should not be
treated as production source:

- `custom_pages/westgate-pages/top-bar.html`: visual structure, states, and
  scoped CSS ideas.
- `custom_pages/westgate-pages/topbar-custom.js`: preview interaction patterns
  for menus, search expansion, mobile drawer, and escape/outside-click handling.
- `custom_pages/Westgate Top Bar.dc.html`: original visual design export.

Preview-only behavior to remove or replace includes hard-coded notifications,
hard-coded chats, hard-coded drafts, fake status persistence in `localStorage`,
demo member/guest switching, and placeholder avatar rendering.

## Risks

Harmony JavaScript currently assumes sidebar-oriented selectors for search,
drafts, notification/chat counts, sidebar toggles, tooltips, and layout offsets.
The topbar implementation must account for those assumptions directly. A
visually correct topbar is not complete if NodeBB's live sidebar behavior stops
working.

The mobile experience also needs an explicit decision during implementation:
once the Westgate topbar drawer owns the same actions, Harmony's inherited
mobile bars should not duplicate those controls.

## Acceptance Criteria

- No Harmony left or right global sidebar is visible on normal Westgate pages.
- All former sidebar actions remain reachable from the topbar or its mobile
  drawer.
- Logged-out users see real login/register actions.
- Logged-in users see their real avatar and the correct account menu.
- Notifications, chats, and drafts use real NodeBB counts and lists.
- Empty notification, chat, and draft states are real states, not mock rows.
- User status buttons call the real NodeBB status behavior and reflect the
  resulting state.
- Search uses NodeBB search behavior rather than a visual-only input.
- The topbar appears consistently on Custom Pages, wiki routes, and normal forum
  routes.
- Drawer, dropdown, account, and notification surfaces are opaque enough that
  underlying page content does not show through.
- The brand appears once as the mark plus `SHADOWS OVER WESTGATE`; no duplicate
  topbar subtitle repeats the site name.
- Desktop navigation has one Forums entry model, not both ACP Navigation Forums
  and a separate right-side Forums dropdown.
- The topbar styling follows Westgate theme tokens and lives under
  `scss/westgate/`.
- The implementation remains a child theme over `nodebb-theme-harmony`.

## Decisions For Implementation Planning

- Whether to temporarily ship any part of the topbar through ACP Custom Content
  for visual validation before moving it fully into the theme.
- Whether the skin switcher remains exposed, and if so where it belongs in the
  topbar or account menu.
- Whether legacy `sidebar-footer` widget content is deprecated, moved to a real
  footer, or exposed through another intentional surface.
- Which Harmony selectors are preserved for compatibility and which are replaced
  with Westgate topbar selectors.