werkator/docs/prs/2026-09-12-PR#56-mobile-nav-icons.md

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR-documentation is not maintained along with new PRs — treat it as a snapshot, not as current documentation.

The Problem

On a phone, the instance navigation (Home, Repositories, System, the live indicator, the icon buttons) is wider than the labels need it to be, and the header has no rule stopping the page from scrolling sideways once it no longer fits — a phone should never gain a horizontal scrollbar just because a row of text labels is wide. The wordmark and the logo already link home, so a separate "Home" entry in the navigation is a second control for the same destination — worth keeping on a desktop, where space is not the constraint, but not on a phone.

Non-Goals

• No change to what each destination does or which repository/build data it shows.
• No change to the Repositories page itself (it already exists behind multiRepo; this PR only touches how its nav entry is presented).
• No new icon library: the existing CSS-mask glyph technique (RFC 0001) is reused.

The Scenarios

Feature: the instance navigation adapts to the viewport

Background

• The instance navigation is the site-nav in the header (fragments.html's siteHeader fragment): Home, Repositories (only with multiRepo), System, the live indicator and the icon buttons.
• Narrow means a viewport at or below 680px, where werkator.css already switches tables to cards and collapses the live indicator to its dot.

Scenario#56.01: Every navigation entry carries an icon

So that Home, Repositories and System read the same way at a glance, instead of only some of them having a glyph.

• Given the instance navigation on a wide viewport
• When the header renders
• Then Home, Repositories and System each show their icon before their label

Verified by

• Manual verification: local server run at a 1200px viewport, Home and System (the served instance is single-repository, so Repositories does not render) both show icon and label.

Scenario#56.02: The navigation does not force the page to scroll sideways

So that a phone never gains a horizontal scrollbar just because the header's labels are wide.

• Given the instance navigation on a narrow viewport
• When the header renders
• Then the page's scrollable width equals the viewport width

Verified by

• Manual verification: local server run at a 375px viewport, document.documentElement.scrollWidth === window.innerWidth.

Scenario#56.03: Home drops out on a narrow viewport

So that the header does not carry two controls for the same destination where space is scarce — the wordmark and logo already lead home.

• Given the instance navigation on a narrow viewport
• When the header renders
• Then the Home entry is not shown
  • and the logo/wordmark link to / still is

Verified by

• Manual verification: local server run at a 375px viewport, screenshot shows no "Home" entry in the nav.

Scenario#56.04: Repositories and System collapse to their icon on a narrow viewport

So that both destinations stay reachable from the header without the width their labels would cost.

• Given the instance navigation on a narrow viewport
• When the header renders
• Then Repositories and System each show only their icon, with no visible label

Verified by

• Manual verification: local server run at a 375px viewport, screenshot shows the System entry as an icon with no label text (the served instance is single-repository, so Repositories is not in the nav to begin with — the same nav-label rule applies to both).

The Solution

Icon on every entry, label as a separate span. fragments.html's siteHeader fragment now wraps each of Home, Repositories and System in <span class="nav-item">/<a class="nav-item">, holding an <span class="icon icon-…"> before an <span class="nav-label">. System reuses the existing icon-usage gauge glyph (already the right shape for "metrics"); Home and Repositories are two new glyphs added to werkator.css's icon-glyph section, drawn in the same stroke style as the others.

Two rules, one media query. Inside the existing @media (max-width: 680px) block: .nav-item-home { display: none; } drops the Home entry entirely (the logo already goes home, per the brand link at the top of the header, itself already collapsing to logo-only there since PR#1's follow-on work), and .nav-label { display: none; } collapses every remaining entry's text, leaving only its icon. html, body { overflow-x: hidden; } was added in the same block as a backstop: the header's own content no longer overflows once the labels are gone, but a phone's app area must not scroll sideways from any overly wide content, not only the nav.

Additional Changes

• Added .claude/launch.json so a local server run can be previewed from the in-app browser (runtimeExecutable: java, port 18080 — the default from WerkatorConfig.server.port).

Follow-up PRs

• None planned; the Repositories entry's icon-collapse behavior could not be screenshotted directly since this instance serves a single repository, but it shares the same nav-item/nav-label markup as Home and System, so it behaves identically once multiRepo is true.