---
name: responsive-navigation-debugging
description: Fix responsive header/topbar overflow and cramped navigation on public websites and dashboards. Use when a user reports desktop/tablet navigation items overlapping, wrapping awkwardly, or not fitting in a single horizontal bar.
---

# Responsive Navigation Debugging

Use this skill for website header/topbar bugs where too many controls compete for one horizontal row: nav links, language switchers, auth/account chips, mode toggles, live badges, and secondary actions.

## Core principle

Do not just shrink everything. Preserve the primary navigation path, then move secondary actions into a menu before overlap starts.

## Workflow

1. **Reproduce visually**
   - Inspect the screenshot or browser page at the reported viewport.
   - Identify which elements are primary vs secondary:
     - Primary: brand, main nav, current mode/status.
     - Secondary: ask/help panels, control-room shortcuts, long account metadata, verbose mode labels.

2. **Trace active header code**
   - Find the actual header component and its CSS selectors.
   - Verify whether the reported state is anonymous/authenticated, visitor/full HUD, language, and desktop/tablet width.
   - Do not patch a public landing header if the screenshot is the authenticated story shell, or vice versa.

3. **Apply a tiered responsive fix**
   - Add an earlier desktop/tablet breakpoint before real overflow begins (often 1100–1350px for dense app headers).
   - Reduce gaps/padding modestly.
   - Truncate brand/email with `min-width: 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap`.
   - Hide long optional labels before hiding whole controls.
   - Move secondary actions into the dropdown/menu at the same breakpoint where they disappear from the row.
   - Keep the mobile breakpoint separate; do not wait until mobile widths to fix desktop overflow.

4. **Verify with real layout, not only screenshots**
   - Build the frontend.
   - Browser-check the affected route with cache-busting.
   - Inspect console errors.
   - When possible, verify `scrollWidth <= clientWidth` for the topbar at widths like 1440, 1366, 1280, 1180, and 1024.

## Implementation notes

- For authenticated applications where login and app shells both need responsive QA, see `references/authenticated-responsive-app-qa.md`: test a five-width matrix, inject a short-lived session without printing it, probe drawer focus/resize behavior, guard live-search races, and verify runtime file readability plus post-deploy logs.
- For wide pricing/comparison/audit tables where the requirement is **no horizontal scrolling at all**, see `references/mobile-data-table-cardification.md`: emit `data-label` values in the renderer, preserve semantic table markup, stack rows into labeled cards on phones, patch both generated output and its owning generator, then verify numeric overflow and screenshots.
- For dense non-header card/diagram surfaces, see `references/mobile-doctrine-card-overlap.md` for the late-override + containment + screenshot verification pattern.
- For dense monitoring/admin dashboards with KPI cards, chart canvases, range controls, and long process tables, see `references/mobile-dashboard-overflow.md`: use shrinkable grids (`minmax(0,1fr)`), visible mobile control grids when everything must fit, table-to-card conversion, and iframe viewport-matrix verification.
- For static SaaS/proof-hub pages that need a mobile-friendly pass, see `references/static-saas-mobile-pass.md`: patch the generator/shared template, add an intermediate breakpoint, use horizontal scroll-chip nav on mobile when acceptable, make CTAs thumb-friendly, and verify both desktop and mobile/no-overflow after regenerating.
- Use CSS breakpoints and existing menu components first; avoid adding new state unless the header lacks a menu.
- If an action is hidden from the horizontal row, add it to the menu before shipping.
- Account chips should usually keep icon + role visible and truncate or hide email first.
- Language selectors should stay visible longer than optional links because they affect the whole page.
- Live status can stay visible as a compact dot+label; it is usually cheaper than a full secondary CTA.

## Pitfalls

- A header that fits at 1440px can still fail on common desktop widths like 1366px or browser windows docked beside other apps.
- `grid-template-columns: auto 1fr auto` can still overflow if the right `auto` column contains unshrinkable pills; set min/max widths on children and hide secondary controls earlier.
- If the menu button is `display:none !important`, remember to override it at the intermediate breakpoint when moving actions into the menu.
- Do not rely on a single screenshot after CSS edits; async auth/session state can add wider controls after the initial load.
- Mobile overlap is often caused by CSS order, not just missing breakpoints: an early `@media` rule can be overridden by later desktop-style component rules. Put final mobile overrides after the base component block, use `min-width: 0`, `box-sizing: border-box`, `overflow-wrap: anywhere`, and force dense grids/cards/definition lists to one column at phone widths.
- Numeric page overflow checks can pass while a mobile nav is still visually clipped because the nav itself is intentionally scrollable or hidden-scrollbar. After `documentElement.scrollWidth <= viewport`, also take a 375px real/mobile-iframe screenshot and inspect whether every primary nav item is readable. If a static public page has no hamburger/menu, prefer wrapping nav links into pill rows at phone widths (`flex-wrap: wrap; overflow: visible`) over hidden horizontal scrolling.
- For glassmorphism/diagram UIs with decorative pills, verify not only `scrollWidth <= clientWidth` but also visual stacking: badges may wrap without horizontal overflow yet still visually collide with cards. Use a real mobile screenshot pass after the numeric overflow check.

## Argorium example

Dense authenticated Argorium topbar fix:

- At `max-width: 1320px`, reduce header gaps and padding, truncate brand/email, hide `Ask city` and `Control room` from the row, and show the menu button.
- Add `Ask city` to the dropdown menu so it remains reachable.
- At `max-width: 1120px`, hide email and collapse the HUD toggle to the active half.
- Keep the existing `max-width: 820px` mobile rules for the fully compact header.