Design System
The visual language and interaction patterns for arXiv's public pages —
tokens, components, page mockups, and the policies behind them. Every
rendered sample on this page is drawn live from
design-system.css: the directory is itself built from the
system it documents.
Start here
Using the design system
Which files to link, in what order, what the two tiers mean, and the five things that go wrong if you guess. Read this before the component pages.
Design policies
The hard constraints: accessibility floor, the two accents, browser support, spacing, target size. Non-negotiable, and the first thing to read.
Components
Buttons
Primary (Open Blue) and secondary, V3 construction: gradient border, inner vignette, brighten-on-hover.
Links
Inline link grammar: Link Blue, underlined, hover-darken, visited purple. Light and dark.
Alerts
Success / info / warning / error — icon + leading word, never color alone. Light and dark.
Site header
Announcement band + black bar. Skip link, "archive" pronunciation, search-as-link enhancement.
Site footer
Acknowledgment line, footer nav, funder logos. The most-validated component in the system.
arXiv Chrome surfaces
Popovers, inline active states, element pills — the light-blue family that means "arXiv chrome speaking."
The system in use — page mockups
Abstract page
arXiv's most-visited page: title, authors, downloads with sizes, accessibility notes, citation workshop, Labs.
HTML paper
Citation popovers, footnote marginalia, figure lightbox, read-aloud, section permalinks, equation tools.
About these mockups
What's preview vs. validated, what to try, where the source of truth lives.
Foundations
Color
The full palette, rendered with contrast ratios — browns and blues, both context accents, the never-cross rule, status family.
Typography
Specimens of the IBM Plex stack + STIX Two Math, with the rules that travel with the type (rem sizing, fallbacks, don't fight the reader).
Spacing
The 4px-based scale (--ds-space-1…--ds-space-12) and the proximity rule: space between sections ≈ 3× space within, so grouping reads without boxes.
Patterns
Buttons
One mechanical spec, two context accents — Open Blue public, Access Lime internal, never crossed — with states, .on-tint, and the internal hierarchy.
Alerts & messaging
The .ds-alert status banner, the announcement band, and inline form errors — with live token values and writing guidance.
Versions
Submission and revision dates, inline version links, and the older-version warning — one grammar from one version to twenty.
Organizing content
The reading-column + rail model, accordions, cards, and content-anchored chrome (popovers, element pills) — whitespace first, boxes second.
Modal dialogs
The most expensive thing the system can put in front of a reader — built on native <dialog>, which gets four of the five hard parts right unasked.
Progressive disclosure
Every way a page shows less than it has: accordions, show-more, popovers — and which one to reach for, since each makes a different promise about what is behind it.
Dark mode
How the colors flip, what is dark-aware today, the traps a token-driven page still falls into, and the rule that new pages lock to light.
Outreach sites
The blog, event and campaign mini-sites: the public design as-is, plus a short list of agreed differences — and what keeps those differences from spreading to arxiv.org.
Principles
Design policies
The non-negotiables: WCAG 2.2 AA, tokens, self-hosted fonts, no metrics, sticky-chrome-is-exceptional, progressive enhancement.
Proposed guidelines
Rules the patterns embody, under universality review — each with evidence and disposition.
Accessibility priorities
Decisions and rationale for the public pages, grounded in 42 interviews and four research datasets.
Process
Component audit — 2026
Operational: component inventory across nine pages, responsiveness review at six widths, and the evaluation pass.
Verification harness
29 automated checks — reflow, ARIA, no-JS, axe-core — each annotated with its research basis.
Visual audit — 2025
Strategic: the platform-wide 11-silo audit that motivated the design system (the "why").