spec

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

@@ -0,0 +1,158 @@
+# 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.