Manual UX And Navigation

1. Compact Navigation Must Behave Like A Real Menu

If the manual switches to a compact navigation shell on smaller viewports, the navigation must act like a real menu:

• closed by default on compact widths
• open by default on larger widths
• able to open through a native interaction primitive, not only through fragile runtime state
• visually attached to the sticky header without a drifting gap
• the same width as the shared shell at that breakpoint
• closed again after the reader chooses a destination

If any of those behaviors are missing, the bug belongs in the shared manual navigation contract, not in one proof page.

2. UI Audits Must Test Stateful Navigation, Not Only Static Layout

It is not enough for a UI audit to read one static screenshot and approve the typography.

For navigation-heavy docs surfaces, the audit lane must also check:

• desktop to compact breakpoint transitions
• sticky header and sticky menu handoff
• menu open and close state
• what happens after a navigation click on compact viewports
• what happens when a compact viewport is resized back to desktop width
• the actual delivered host, not only a raw build or a static screenshot

Otherwise the audit can praise a surface that still fails in real use.

3. Sticky Offsets Must Be Measured Or Strictly Owned

The manual menu loop returned because the sticky handoff was treated as a cosmetic spacing tweak instead of a layout contract.

The stable rule is:

• if a sticky surface must meet another sticky surface exactly, its offset must come from the real shared owner
• guessed breakpoint offsets are only acceptable as fallback values
• compact navigation state must not share the same interaction primitive as desktop navigation if that coupling can hide the desktop menu after a resize

4. Shared Runtime Assets Must Bust Stale Browser State

If shared CSS or JS assets keep stable filenames across deploys, a browser can render a mixed state:

• new HTML
• old CSS
• or old runtime JS

That class of drift is especially dangerous for interactive shell contracts such as compact navigation because the markup can look current while the behavior still follows an older runtime.

The stable rule is:

• shared static assets must expose a versioned href or fingerprinted path
• deploy verification must not assume that Cache-Control: no-cache alone is enough to prevent mixed asset state

Otherwise the audit can praise a surface that still fails in real use.

5. Security Headers Must Match Shared Runtime Ownership

If every manual page loads one shared runtime such as manual-nav.js, the page CSP must allow that runtime on every page in the surface.

It is not enough for one proof page to work because it happens to need a looser CSP for another reason.

The stable rule is:

• page-level CSP must be derived from the full shared runtime contract, not from one optional feature such as Mermaid alone
• audits must compare the root page and at least one representative internal page
• a UI bug that appears only on some pages can still be a global delivery bug

6. Public Manual Lists Should Stay Flat

The public manual is easier to scan when list structures stay flat and when continuation lines follow the text instead of drifting under a nested marker stack.

The stable rule is:

• public manual pages should prefer flat bullets or short tables over nested list levels
• TOC numbering and list markers need one shared spacing contract
• mixed inline list items such as link + trailing sentence need one shared rendered body wrapper; CSS must not rely on anonymous text nodes
• nested markdown lists in public manual pages now fail the build instead of silently drifting the style surface