#1 Docs frontend navigation and theme controls

Overview

This technical specification fixes the final frontend requirements for documentation navigation behavior and theme controls across desktop, tablet, and phone layouts.

Scope and goals

  • Applies to docs pages using shared docs frontend assets and internal layout chrome.
  • Covers the main navigation experience: title row, Menu button, drawer, top navigation groups, and theme toggle.
  • Covers responsive behavior by platform width: desktop, tablet, and phone.
  • Defines final behavior for Quick actions on mobile vs desktop.

Platform model (breakpoints)

  • Desktop: width >= 1025px.
  • Tablet: width 761px ... 1024px.
  • Phone: width <= 760px.

Breakpoints for drawer and internal title row behavior are aligned with JavaScript/CSS implementation.

Menu and drawer requirements

  • Drawer direction is always left-to-right (panel opens from the left edge).
  • On internal-layout pages, Menu launcher is attached near h1 in a dedicated title row.
  • Menu launcher is visible on tablet and phone, and hidden on desktop.
  • Drawer must keep keyboard and screen-reader semantics (role="dialog", aria-modal, aria-controls, aria-expanded).
  • Drawer closes on phone after navigation click; supports Escape and backdrop close.
  • Drawer should not blur text or break link activation; navigation links must route reliably.

Project / Code blocks requirements

  • Desktop: top navigation groups Project and Code are visible on page.
  • Tablet and phone: top navigation groups Project and Code are hidden in top nav, available via drawer blocks.
  • Drawer top sections include Project links (Home, Internal docs, Assessments, Backlog).
  • Drawer top sections include Code links (OpenAPI explorer, Pdoc API docs).
  • Active-state matching must work for directory prefixes, not only exact file path.

Theme control ("flashlight") requirements

  • Theme toggle is a compact flashlight icon control, not a text label button.
  • Flashlight orientation is vertical with beam pointing up.
  • On internal-layout pages, flashlight aligns with the same title row as h1 (desktop and mobile).
  • Theme cycle order: automatic (system) -> light -> dark -> automatic.
  • When explicit dark mode is selected, flashlight receives a yellow lit state.
  • Control must keep accessibility attributes and clear aria-label text describing active mode and action.

Theme switch notification ("pillow")

  • On each theme change, show top-centered pill-shaped toast notification.
  • Toast messages: Automatic theme, Light theme, Dark theme.
  • Toast should be non-blocking, auto-dismissed, and animated.
  • For reduced-motion users, transition is removed.
  • Toast has role="status" and aria-live="polite" for assistive tech.

Quick actions requirements

  • Desktop only: page actions toolbar and quick-actions dialog are enabled.
  • Tablet and phone: page actions and quick-actions UI are disabled/hidden.
  • Desktop keyboard shortcuts (for quick actions) must not hijack behavior on mobile widths.

Wide-screen layout stability requirements

  • Desktop must not reuse mobile narrow-column visual proportions.
  • Internal shell uses two-column layout with stable sidebar + flexible main content area.
  • Main content should avoid accidental narrow clamp from mobile-oriented caps.
  • Desktop overrides must be placed late enough in CSS cascade so they win over base rules.

Acceptance checklist

  • Phone <=760px: Menu works, drawer opens from left, Project/Code available in drawer, quick actions hidden.
  • Tablet 761...1024px: same as phone behavior for top groups and drawer availability.
  • Desktop >=1025px: Project/Code visible in top nav, flashlight in title row with h1, Menu hidden.
  • Theme cycle and yellow lit state in dark mode work consistently.
  • Theme toast appears and auto-dismisses without breaking focus/navigation.

Reference implementation files

  • docs/assets/internal-sidebar.js — drawer lifecycle, content cloning, drawer sections, navigation handling.
  • docs/assets/internal-layout.css — shell layout, title row, drawer styling, responsive rules.
  • docs/assets/docs-nav.js — top-nav render, Menu mount, theme flashlight logic, toast behavior, quick actions viewport sync.
  • docs/assets/docs-site-nav.css — top-nav groups visibility rules by viewport and flashlight visual styling.
  • docs/assets/docs.css — quick-actions styles and theme toast ("pillow") styling.

Page history

This block captures the latest agreed frontend behavior changes for docs navigation and theme controls.

  • Navigation model finalized: left drawer is primary on narrow screens; desktop keeps stable top navigation groups and non-degraded wide layout.
  • Project/Code visibility split: desktop shows blocks directly in top nav; tablet/phone hide them in top nav and expose them through documentation drawer.
  • Menu and title row behavior: Menu launcher is attached to title row for narrow screens, with expected auto-close and accessibility semantics.
  • Theme control redesign: text theme toggle replaced with minimalist flashlight icon; explicit dark mode activates yellow lit state.
  • Theme switch feedback: top-centered pill notification added on every theme switch (automatic/light/dark), with reduced-motion support.
  • Quick actions policy: desktop-only availability retained; mobile and tablet variants are intentionally hidden.
  • Desktop layout fixes: cascade-safe wide-screen overrides added to prevent narrow mobile-like rendering on large viewports.