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.

## 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.
- 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.