Site header — arXiv Design System

Contents

The header unit

Rendered directly from design-system.css. Resize the window: at ≤599px the nav collapses behind the hamburger (the approved mobile treatment); without JS it wraps to a second row instead — every item stays visible, passing WCAG 1.4.10 reflow at 320px and keeping voice-control working. The header is static — it scrolls away with the page (the site header is never the sticky bar — DESIGN-POLICIES.md).

Relevant code

<!-- First focusable element on the page -->
<a class="ds-skip-link" href="#main">Skip to main content</a>

<header class="ds-site-header">
  <a href="/" class="ds-site-header-logo" aria-label="archive home">
    <img src="logo_arxiv-primary.svg" alt="archive">
  </a>
  <button type="button" id="ds-nav-toggle" class="ds-site-header-nav-toggle" aria-label="Open menu" aria-controls="ds-site-header-nav" aria-expanded="false">
    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
      <line x1="3" y1="6" x2="21" y2="6"/>
      <line x1="3" y1="12" x2="21" y2="12"/>
      <line x1="3" y1="18" x2="21" y2="18"/>
    </svg>
  </button>
  <nav class="ds-site-header-nav" id="ds-site-header-nav" aria-label="Main navigation">
    <a href="/search">
      <svg class="ds-nav-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
        <circle cx="11" cy="11" r="8"/>
        <line x1="21" y1="21" x2="16.65" y2="16.65"/>
      </svg>
      Search
    </a>
    <a href="/submit">Submit</a>
    <a href="/about/donate">Donate</a>
    <span class="ds-site-header-divider" aria-hidden="true"></span>
    <a href="/login" class="ds-site-header-login">Log in</a>
  </nav>
</header>

.ds-skip-link: The skip link. The first focusable element on the page, visible only on keyboard focus. Its href is the id of the main content.
.ds-site-header: The bar. Bare, it is the arXiv header — arxiv.org cannot forget a class it never has to write.
.ds-site-header-logo: The brand slot, image or wordmark. Takes margin-right: auto. On arxiv.org it is the logo image, never the word typed out; its alt text says “archive”.
.ds-site-header-nav: The links, in a <nav> with an aria-label. The Search control is an <a href="/search"> that JS may upgrade to open a search overlay. Never a dead button — without JS it navigates to the search page.
.ds-nav-icon: An icon beside a link label, sized by the stylesheet and quieter than the text. aria-hidden="true"; the label carries the name.
.ds-site-header-divider: A vertical hairline between groups of links, on the bar’s own divider token. Takes aria-hidden="true".
.ds-site-header-login: The emphasis slot: the last item in the bar, and the only nav item that takes weight. Signed out it says Log in. Signed in it says Account, with the greeting beside it.
.ds-site-header-nav-toggle, .is-collapsible, .is-open: At ≤599px the nav collapses behind a hamburger only after JS enables it: the header script adds .is-collapsible to .ds-site-header and wires the toggle (.is-open on the nav, aria-expanded in sync) in the same call, so the hamburger appears only when it actually works. The default — including no JS — is the wrap (all items visible, WCAG 1.4.10 reflow).
.ds-site-header-dropdown: A menu group in the bar, built on <details>; it is documented with the other disclosures on Progressive disclosure.

Signed out, and signed in

The bar's last item is the emphasis slot — the only nav item that takes weight. Signed out it says Log in. Signed in it says Account, with the greeting beside it.

Relevant code

<nav class="ds-site-header-nav" aria-label="Main navigation">
  <a href="/search">
    <svg class="ds-nav-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
      <circle cx="11" cy="11" r="8"/>
      <line x1="21" y1="21" x2="16.65" y2="16.65"/>
    </svg>
    Search
  </a>
  <a href="/submit">Submit</a>
  <span class="ds-site-header-divider" aria-hidden="true"></span>
  <span class="ds-site-header-greeting">Welcome <b>Ada</b></span>
  <a href="/account" class="ds-site-header-login">Account</a>
</nav>

.ds-site-header-greeting: The greeting takes the given name only — its first word — because the bar is chrome and a full legal name is more of it than the job needs. Even one word is user data of unbounded length in any script, so it is capped at 14 characters with an ellipsis, as the second example shows. A bar that reflows or overflows on a long name breaks for exactly the people whose names get tested least. The greeting is not a link. It is a statement; the thing you can act on is the Account link beside it. Making the name itself the link would give that link the accessible name “Ada”, which says nothing about where it goes. It is the first thing dropped on a narrow bar: below 600px the greeting hides and Account stays — the link is the useful half, and the reader already knows their own name.
.ds-site-header-login: The same emphasis slot as when signed out, now reading Account. The slot is about rank in the bar, not about which of the two words is in it.

Relevant code

<span class="ds-site-header-greeting">Welcome <b>Sivaramakrishnan</b></span>

.ds-site-header-greeting > b: The name. The stylesheet caps it at 14 characters and ends it with an ellipsis; the host passes the given name and nothing else.

Accessibility essentials

The skip link comes first. .ds-skip-link is the first focusable element on the page, visible only on keyboard focus, and it goes to the main content.
Name the navigation. The bar’s links sit in a <nav> with an aria-label, such as “Main navigation”, so a screen reader user can tell it from the other landmarks on the page.
The wordmark is an image with alt text. Logo alt text and aria-labels say “archive” — the spoken form of “arXiv” (screen readers otherwise produce “ar-zhiv” or Roman-numeral gibberish).
Nothing in this unit is sticky. The whole header scrolls away with the page (the one bar a page may keep in view is the contents bar — DESIGN-POLICIES). No scroll-padding duty applies.

Modifiers

With the announcement band

When arXiv has something to say to everyone, the announcement band sits directly above the bar, and the two scroll away together. The band itself, its registers and its tone are on Special messages; this page shows only where it sits.

arXiv is now an independent nonprofit! Learn more

Relevant code

<a class="ds-skip-link" href="#main">Skip to main content</a>

<div class="ds-announcement" role="region" aria-label="Announcement">
  <img class="ds-announcement-glyph" src="icon_small-smileybones.svg" alt="">
  <span class="ds-announcement-text">arXiv is now an independent nonprofit!</span>
  <a class="ds-announcement-link" href="/about">Learn more</a>
  <button type="button" class="ds-close">
    <svg viewBox="0 0 24 24" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
      <path d="M18 6 6 18"/>
      <path d="m6 6 12 12"/>
    </svg>
    <span class="is-sr-only">Dismiss announcement</span>
  </button>
</div>

<header class="ds-site-header">…</header>

.ds-announcement: The band, placed before .ds-site-header and after the skip link. See Special messages for its parts.

The light variant

A secondary property, like this documentation, differentiates itself from the main arXiv with a light header variant. Adding .ds-site-header--light re-points seven surface tokens but declares no property of its own. The token values are listed under Surface tokens.

The bar at the top of this page is the light variant, with dropdown groups.

Relevant code

<nav class="ds-site-header ds-site-header--light" aria-label="Design system">
  <a href="/" class="ds-site-header-logo">arXiv Design System</a>
  <nav class="ds-site-header-nav" aria-label="Site navigation">
    <a href="/patterns">Patterns</a>
    <a href="/mockups">Mockups</a>
    <a href="/docs">Docs</a>
  </nav>
</nav>

.ds-site-header--light: Seven token values. No property overrides. The bar is white (--ds-surface) with Library Grey links, Repository Brown emphasis, and a Border Light bottom edge; the standard focus ring replaces the on-dark one.
.ds-site-header-logo: On a property that is not arxiv.org, the slot may hold that property’s own wordmark as text; it takes the bar’s emphasis colour.

Internal header

Rules

Hosting the header

The announcement is temporal. Render only while active, persist dismissal in production, and never attach page-critical function to it.
No more than four top-level links. The logo and Log in do not count. More than four causes cognitive overload and reduces comprehension; resist link-creep permanently (DESIGN-POLICIES).
Log out is not in the bar. It belongs on the account page. A destructive-adjacent action one mis-tap from Search is a bad trade for the two seconds it saves.
Type sizes are rem so browser font-size overrides propagate; both bands are hidden in print.

Spec

Surface tokens

How the bar is coloured, and how a variant changes it.

.ds-site-header declares seven --ds-hdr-* tokens on itself: background, text, emphasis text, hover, focus ring, bottom border and divider. Every rule in the bar reads one of them, so a variant is a re-pointing of tokens and never a property override: .ds-site-header--light sets all seven and nothing else. A property with its own colours does the same.

The focus ring is the one to notice: the standard Link Blue ring is invisible against Repository Brown, so the dark surface needs its own. Because it is a token rather than a rule, a property that switches surface gets the correct ring without knowing that it needed to.