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.

7.1 KiB Raw Blame History