Outreach sites — arXiv Design System

Contents

What outreach sites may do differently

Every difference from arxiv.org that has been agreed. If a difference is not in this table, it is a mistake rather than a decision. Trials are live now and may be withdrawn; adopted entries are settled.

What is different	The normal rule	Where it runs	Status
Open Blue header bar	Public header is black, moving to Repository Brown; Open Blue is reserved as the primary-action color	blog.arxiv.org	Trial · 2026-07-31
Serif editorial register	Public site uses Plex Serif italic for annotation only	Post titles, bylines, display headings	Adopted · 2026-07-31
Smileybones Yellow image bookends	Public site has no decorative rules; the yellow appears only as the mark itself	Featured post, in-article figures	Trial · 2026-08-03
Pinned identity field	Backgrounds are built from tokens, so they flip in dark mode	Masthead band (Archival Blue, both modes)	Trial · 2026-08-05
Mono display register	Public site uses Plex Mono for identifiers, not prose	Masthead description, wordmark	Trial · 2026-08-11
Editorial list styling	Public lists use browser markers at the default indent	Em-dash bullets and condensed tabular numerals, both Archival Blue	Adopted · 2026-08-03
Decorative illustration and photography	Public pages carry no decorative imagery	Post thumbnails, homepage cards, bands	Adopted · 2026-07-31

None of this belongs on arxiv.org itself

Nothing in the table above may appear on the main site — not the Open Blue header, not the yellow rules, not decorative photography. arxiv.org is a working tool for people who are trying to read a paper, and keeping it plain is the point.

What these look like

Drawn with the real public stylesheet. The whole-page pieces (header bar, color panel) are examples only — they are described here and built into each site's own theme, not shipped as something you can drop in.

Open Blue header bar

Every pairing follows the rules for Open Blue backgrounds already set out in color-mapping.md: Repository Brown is the only text color on Open Blue, boundaries use Library Grey, and hover steps to Open Blue Bright. The liberty is the header's fill — nothing else is bent to accommodate it.

Relevant code

<header class="ds-site-header">
  <a class="ds-site-header-logo" href="/">arXiv News</a>
  <nav class="ds-site-header-nav" aria-label="Blog">
    <a href="/">Blog home</a>
    <a href="/about">About arXiv</a>
  </nav>
</header>

.ds-site-header: The shared component, unchanged; see Header. The fill is the site's own theme re-pointing the header's surface tokens (--ds-hdr-bg and the rest) to Open Blue, the same way .ds-site-header--light re-points them to white.

Committed color field, with the on-dark secondary button

Updates on all things arXiv

Policy changes, projects, hires, tech improvements and outages, accessibility work.

Donate Subscribe

.on-dark is a real part of the shared stylesheet now — the sibling of .on-tint, for buttons on a background dark enough to host white text. It drops the fill so the color shows through, and it keeps that construction in dark mode because the panel behind it is pinned to one color. It lives in shared CSS but is used only here, because committed color panels are an outreach thing: arxiv.org has none. See Buttons.

Relevant code

<a class="ds-btn ds-btn-primary" href="/donate">Donate</a>
<a class="ds-btn on-dark" href="/subscribe">Subscribe</a>

.on-dark: The secondary button on a committed color field. Specified on Buttons.

Smileybones Yellow bookends

image

Rules bracket the whole plate — caption included.

The yellow runs horizontal, framing an image. It is never a vertical column divider, never text, never a boundary that has to meet contrast requirements — at roughly 1.3:1 on white it cannot carry meaning on its own. The token is --ds-smileybones-yellow, and this framing rule is its only documented use outside the mark itself.

Relevant code

<figure style="border-top: 4px solid var(--ds-smileybones-yellow); border-bottom: 4px solid var(--ds-smileybones-yellow)">
  <img src="…" alt="…">
  <figcaption>…</figcaption>
</figure>

--ds-smileybones-yellow: The token both rules take. There is no class for the framing; see color-mapping.md.

Rules

What stays shared, and how it stays shared

That list is deliberately short, because everything else is shared. Three rules stop the shared parts from quietly growing apart.

Rule What it means in practice

Borrowing goes one way

Rule	What it means in practice
Borrowing goes one way	An outreach site may use anything from the public arxiv.org design. It does not work in reverse. A style invented for the blog stays on the blog until a second outreach site needs the same thing; only then does it move into the shared stylesheet, so both sites draw it from one place instead of keeping their own copies. The `.on-dark` button made that move today. Sharing the code is not the same as widening where it is allowed. The shared stylesheet is only about where CSS lives. A style sitting in it is still outreach-only until someone decides otherwise and writes that decision into the design policies. Nothing appears on arxiv.org because it happened to be available.
Never repeat a rule that applies everywhere	Write each shared rule down once — in DESIGN-POLICIES.md if it is a hard rule, on the relevant pattern page if it is a way of building something. This page says only what is different about outreach sites. When a rule is written in two places, one copy eventually gets edited on its own and the two stop agreeing.
A script checks the copies we cannot avoid	Two copies are unavoidable. The WordPress blog cannot load a stylesheet from another server, so it ships its own copy of ours; and the dark-mode colors are written twice so that a light/dark switch can work. `python3 verification/check-drift.py` compares both against the originals and fails if they have drifted apart. Run it after changing either stylesheet.

An outreach site may use anything from the public arxiv.org design. It does not work in reverse. A style invented for the blog stays on the blog until a second outreach site needs the same thing; only then does it move into the shared stylesheet, so both sites draw it from one place instead of keeping their own copies. The .on-dark button made that move today.

Sharing the code is not the same as widening where it is allowed. The shared stylesheet is only about where CSS lives. A style sitting in it is still outreach-only until someone decides otherwise and writes that decision into the design policies. Nothing appears on arxiv.org because it happened to be available.

Never repeat a rule that applies everywhere Write each shared rule down once — in DESIGN-POLICIES.md if it is a hard rule, on the relevant pattern page if it is a way of building something. This page says only what is different about outreach sites. When a rule is written in two places, one copy eventually gets edited on its own and the two stop agreeing.

A script checks the copies we cannot avoid Two copies are unavoidable. The WordPress blog cannot load a stylesheet from another server, so it ships its own copy of ours; and the dark-mode colors are written twice so that a light/dark switch can work. python3 verification/check-drift.py compares both against the originals and fails if they have drifted apart. Run it after changing either stylesheet.

The accessibility rules never bend

Outreach sites get to differ in tone. They do not get to differ on color contrast, keyboard focus, self-hosted fonts, tap-target sizes, or the color palette. Those apply everywhere at arXiv and are written once, in the design policies.

Adding a new one

Agree it with Shamsi before building it, then add a row to the table above with an honest status. A trial that holds up in front of a real audience becomes adopted; a trial nobody defends gets removed, along with its code. The reason for writing these down at all is so that a year from now, someone can tell the difference between a decision and an accident.