Typography

Which faces where — the three contexts

One family, three contexts. Internal tools and the public site share the working set; outreach properties add the upright serif and the heaviest sans. A face without a mark is not used in that context.

• 700 is the ceiling. IBM Plex ships no heavier weight, so a CSS 800 either falls back or gets faux-bolded, differently per browser. Ask for the weight that exists.
• Two serif jobs, kept apart. Upright serif is the editorial voice — headlines, quotes, drop caps. Italic serif stays the annotation voice everywhere. A heading that must not read as "another article" uses the heavy sans instead, which is why 700 exists in this context at all.
• Mono as display type is an outreach liberty: the typewriter register echoes the main site's identifiers. On the public site, mono still means "this is an identifier or code."

Headings

Space is given as spacing tokens, not pixels, because that is what design-system.css implements — --ds-space-8 is 2rem, --ds-space-6 is 1.5rem, and so on down the scale.

• The ratio is 1.25 — a major third — rounded to quarter-rem steps: 1, 1.25, 1.5, 2rem. A strict geometric run would put h2 at 1.5625rem; a quarter of a rem is the number a person can hold in their head and type without checking. The rounding is what makes h1 land on exactly double the body size.
• 700 appears once, at h1. IBM Plex ships nothing heavier, so 700 is the ceiling and it is spent on the one heading that names the page. Everything below is 600. Always state the weight: a rule that sets only font-size inherits the browser default bold, which is how several pages ended up with an h3 heavier than the h2 above it.
• Space above is about three times the space below. A heading belongs to the text it introduces, not the text it follows, and the gap has to say so. The values sit on the 4px rhythm in Spacing.
• Long titles clamp. An h1 that can run to seven words uses clamp() between rem bounds rather than a fixed 2rem — see "Fluid where titles meet phones" below.
• The 11px uppercase Condensed label is not a heading level. Set in --ds-font-condensed and --ds-text-muted, it marks a panel or a column and stays out of the document outline. If a reader needs to navigate to it, it is an h3 or an h4 at the size above, not a label.

The copy button

• There is no markup for the button, and that is the design. copy-code.js walks every <pre> on the page, wraps it in .ds-code and inserts the control, which is .ds-code-copy. A block added next year is covered without anyone remembering, which a per-block wrapper would not be. Every page under docs/ already loads the script.
• The button reserves a strip at the top, not the side. A <pre> scrolls horizontally, so padding at its inline end does not hold the visible right edge clear — a long line runs straight under a right-hand button. A lane across the top works at every line length.
• It is an icon, and it still says “Copy”. The two overlapping sheets are the glyph people already know, so the control needs no label taking up room over the code. Both SVGs are aria-hidden and the button carries aria-label="Copy code", which is what a screen reader announces. The title is the pointer affordance only — assistive technology takes the aria-label and ignores it.
• Success is announced, not just shown. The icon becomes a green tick, and a visually hidden role="status" region says “Copied to clipboard”. Both are needed: a tick is invisible to a screen reader, and the button’s own name does not change because its action did not change — it is still the copy button. Both reset after two seconds.
• The name stays put while the icon moves. Relabelling a control to report a result is the same mistake as bolding a switch label on toggle: the name of a control is what it does, not what just happened. The result belongs in the live region.
• It works from disk. The asynchronous Clipboard API needs a secure context, which file:// is not, and it rejects when the window is not focused. Both cases fall back to execCommand, and if that fails too the status region says so rather than the button quietly doing nothing.
• Without JavaScript there is no button and the code is still selectable. The button is a convenience; it is never the only way to get the text.
• Opt a block out with <pre data-no-copy> — for a block that is an illustration of output rather than something to take away.

Sizes are rem, and a box that holds text scales with its text

A browser font-size setting has to reach arXiv content (accessibility-priorities.md, cognitive/dyslexia track), so every type size is rem. But a label that grows inside a box that does not is no better than a label that never grew: set a control's padding and minimum width in em, against its own label, and the whole control follows the reader. Absolute floors stay absolute — min-height: 24px is a WCAG target size, not a type size.

Self-hosted, with honest fallbacks

No Google Fonts, no Typekit, no CDN fonts (DESIGN-POLICIES.md). Every font-family declaration carries system fallbacks; text fonts load with font-display: swap (readability first), STIX Two Math with font-display: auto (math must render in the correct face).

Do not fight the reader

No fixed line-heights, no pinned letter-spacing, no !important on font-family in content areas. User stylesheets, reader-mode extensions, and OS settings win — "HTML gives you freedom: you can use software to change colors or typefaces" (research, dyslexia track).

Fluid where titles meet phones

Paper titles use clamp() between rem bounds (22px–32px equivalent) so a seven-word title does not wrap to five lines at 320px. Body text never scales fluidly — it tracks the user's base size exactly.

Why IBM Plex

Open source under the SIL Open Font License, so there is no licensing cost and no vendor dependency; self-hostable as woff2 from arXiv's own assets; one designer's family covering Sans, Condensed, Mono and Serif so nothing is mixed; broad language coverage including Latin Extended, Cyrillic, Greek, Arabic, Hebrew, Devanagari and Thai; and it pairs with STIX Two Math, which is built for the same technical context. The family was re-evaluated in June 2026 against Atkinson Hyperlegible Next, Source Sans 3, Inter and Public Sans, and kept — that comparison lives in planning/proposals, not here.

Tokens

--ds-font-sans:      "IBM Plex Sans", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
--ds-font-condensed: "IBM Plex Sans Condensed", "IBM Plex Sans", sans-serif;
--ds-font-mono:      "IBM Plex Mono", ui-monospace, "SF Mono", Menlo, monospace;
--ds-font-serif:     "IBM Plex Serif", Georgia, "STIX Two Text", "Times New Roman", serif;

Every stack carries system fallbacks so text stays readable if the web fonts fail: sans falls to the OS system font, mono to the platform monospace. There is no math token — STIX Two Math is applied by the paper renderer on HTML paper pages, not by the design system, so the stylesheet does not declare one.

Available weights, and sanctioned ones

Every weight and style IBM Plex ships is self-hosted — Thin 100, ExtraLight 200, Light 300, Regular 400, Text 450, Medium 500, SemiBold 600 and Bold 700, each with an italic, across Sans, Sans Condensed, Mono and Serif. That is 64 files and about 4 MB in the repository, and it costs a reader nothing: a @font-face rule downloads only when a page uses that face.

Available is not the same as approved. Only the faces the design system uses are declared in fonts.css; the rest are present but commented out, so you can see what exists without going to look for it. Uncommenting one is how you turn it on — and it is a decision, not a formality.

The files

Self-hosted woff2, from arXiv's static assets. No external font service — see DESIGN-POLICIES for why that one is a hard constraint.

/static/fonts/
  IBMPlexSans-*.woff2            8 weights x roman/italic  = 16 files
  IBMPlexSansCondensed-*.woff2   8 weights x roman/italic  = 16 files
  IBMPlexMono-*.woff2            8 weights x roman/italic  = 16 files
  IBMPlexSerif-*.woff2           8 weights x roman/italic  = 16 files
  STIXTwoMath-Regular.woff2      ← HTML paper pages only

This repo's pattern pages serve the same files from docs/fonts/, declared in fonts.css, which every page links ahead of the stylesheet. The @font-face rules live in that separate file rather than in the design system itself, because consumers bundle the design system with their own font paths. Files come from IBM/plex (OFL).

@font-face

@font-face {
  font-family: "IBM Plex Sans";
  font-weight: 400;
  font-style: normal;
  font-display: swap;
  src: url("/static/fonts/IBMPlexSans-Regular.woff2") format("woff2");
}
/* …one per weight and style… */

@font-face {
  font-family: "STIX Two Math";
  font-weight: 400;
  font-display: auto;
  src: local("STIX Two Math"),
       url("/static/fonts/STIXTwoMath-Regular.woff2") format("woff2");
}

• font-display: swap for text: the fallback shows immediately and swaps when the real font arrives. Readability beats visual stability.
• font-display: auto for STIX Two Math: maths in a fallback font can be actively wrong, so it is better to wait briefly.
• local() for STIX Two Math skips the ~300KB download if the reader already has it.
• Total: about 135KB for the Plex woff2 files, plus STIX only on paper pages.

Which faces each surface uses

Sizes in use

Not yet a formal scale — these are the sizes used consistently across the mockups, recorded so the scale can be settled from what exists rather than invented.