Typography tokens

Five selectable typefaces over three system fallback stacks, an eight-step fluid scale whose slopes are calculated rather than guessed, four line heights that leave room for translated text, and the small set of weight, tracking and numeral controls that everything else is built from.

Font stacks

Typography is in three tiers. The three --stack-* tokens are the system fallbacks, one per voice. The five --family-* tokens are the selectable typefaces, each one webfont hook in front of a --stack-*. The --font-* tokens are the roles that base.css, the components and the utilities actually read. Picking a typeface moves one role; see Choosing the typeface.

The shipped path is still all system stacks, and that is a decision rather than an omission: linking src/index.css alone means zero network requests, zero flash of unstyled text, no font files to self-host and no licence to track. The five typefaces only become distinct once you also link the opt-in sidecar; without it they resolve to their --stack-* and nothing can fail to load. The leading faces in every stack cover Latin, Latin Extended and Cyrillic, including the Cyrillic Extended letters (U+04E9 and U+04AF, for example) that most Latin-first stacks fall back to a different face for, producing a visible mismatch mid-word.

Sans

The body voice: copy, controls, nav, and everything a typeface preset moves. Not headings: those read --font-display, which is Geologica on the default.

Serif

The reading voice for long-form material, and, as --font-serif, a role no preset ever re-points, for the case where one pull quote wants a serif on a page that is not.

Mono

Code, token names, identifiers, and anything that has to align by column.

Display

Large headings. base.css points h1–h6 at it, and it is Geologica over an Inter body: that pairing is the default. Every typeface preset moves this role alongside the body role, so picking a typeface changes headings and copy together; inter is the one preset that keeps Geologica here, because it is the default restated. To make headings track the body face on the default too, set --font-display: var(--font-sans).

Choosing the typeface

One attribute picks the reading voice, choosing from five presets:

<html lang="en" data-font="literata">

The five are inter, geologica, plex, literata and plex-mono, named after the faces, not after roles, because three of them are sans and sans could not say which. inter is the shipped default, and writing it is a true no-op: data-font="inter" and omitting the attribute entirely compute identically, because the preset restates what :root already holds. Same contract as data-brand="blue".

Each preset re-points the body role --font-sans and the display role --font-display together, so a preset is a whole voice rather than half of one. inter is the exception, and only because it is the default restated: it keeps Geologica on headings. What no preset touches is --font-mono: code, a token name and a money figure are monospaced because they need the column to line up, not as a stylistic choice, and a serif page still wants them monospaced. --font-serif is never re-pointed either, for the mirror reason.

Mono as a reading voice is the one that looks like a mistake and is not. Under that preset body copy and a <code> inside it resolve to the same stack, so the page reads as one technical document rather than as prose with insertions.

It works on any subtree

Unlike data-brand, this one scopes. Put it on a region and the region changes:

If you need identical rendering everywhere

A system stack picks a voice, not a face: the same page is Segoe UI on Windows and San Francisco on macOS. Where that is not good enough, the package ships an opt-in sidecar, src/fonts.css, which is a second link tag and nothing else:

<link rel="stylesheet" href="node_modules/@arag/css/src/index.css">
<link rel="stylesheet" href="node_modules/@arag/css/src/fonts.css">

Link order does not matter. The sidecar declares the @font-face faces and sets one hook property per face: --webfont-inter, --webfont-geologica, --webfont-plex, --webfont-literata, --webfont-plex-mono, which tokens.css reads at the head of each typeface as var(--webfont-inter, ). Setting a hook prepends the face and leaves the --stack-* fallback behind it; unset, the empty fallback substitutes to nothing and the typeface is its stack. That is why the sidecar needs no copy of the stacks, and a second copy of a stack is a copy that drifts.

The five faces are Inter, Geologica, Literata, IBM Plex Sans and IBM Plex Mono. All five are SIL OFL 1.1, and all five carry Cyrillic and Cyrillic Extended: the gate a face has to pass to be on this list at all, because letters such as U+04E9 and U+04AF live in the extended range and a face that stops at cyrillic renders them as boxes mid-word. They are declared under renamed families ("Arag Inter" and friends) because a file served under the real name collides with a copy the platform may already have installed, and that collision resolves differently per platform, which defeats the point of using webfonts at all.

Two costs, stated rather than buried. This set is five faces from four foundries, where the previous set was one Noto superfamily: a superfamily guarantees the presets cannot disagree about how Cyrillic looks, and four foundries do not, so check a Cyrillic paragraph in each preset before shipping a page that switches between them. And IBM Plex Mono has no variable cut upstream, so it is declared as four static weights across four subsets: sixteen @font-face blocks, against eight each for Inter, Literata and IBM Plex Sans (four subsets, roman and italic) and four for Geologica, which has no italic upstream. A page still only fetches the weights and ranges it actually renders.

Each family is split by unicode-range, so a page fetches only the ranges it renders: an all-Latin page never downloads the Cyrillic files. Read the ranges before deleting any of them. The cyrillic subset is U+0400-045F plus four strays and does not contain U+04E9 or U+04AF: both live in cyrillic-ext. Drop the cyrillic-ext blocks as "the extended one, probably not needed" and every page that uses those letters falls back to the system face for exactly those two characters, mid-word, which is the defect the stacks were ordered to avoid in the first place.

The fluid scale

Eight steps, --text-xs through --text-4xl, each a single clamp(). The slopes are derived rather than eyeballed. For a 16px root, 1vi is V/1600 rem where V is the viewport inline size in pixels. Anchoring the minimum at 20rem (320px) and the maximum at 96rem (1536px) means the vi term has to cover the difference across 0.96 - 0.2 = 0.76:

slope     = (max - min) / 0.76
intercept = min - 0.2 * slope

/* --text-lg: min 1.125rem, max 1.375rem */
slope     = (1.375 - 1.125) / 0.76 = 0.3289
intercept = 1.125 - 0.2 * 0.3289   = 1.0592

--text-lg: clamp(1.125rem, 1.0592rem + 0.3289vi, 1.375rem);

The unit is vi rather than vw, so the scale stays correct if a consumer ever switches writing-mode.

Specimen

One English line per step, set at the step's own size. Leave room for it to grow: the same message routinely runs 15–25% longer once translated, and that is a layout constraint, not a translation problem.

Line height

Four steps. --leading-normal is deliberately more generous than an English-only system would choose, because other scripts and accented text set taller at the same font size: the x-height can be larger relative to the em, and accents and descenders reach further. A leading that reads as comfortable in English can close up once the text is translated.

--leading-tight is for display headings only. It is safe on two or three words set large; it is not safe on running text, where the descenders start touching the line below.

Each block below is the same paragraph at the full measure, so it wraps to several lines and the difference is visible rather than theoretical.

Weight, tracking and numerals

Weight

Four steps, no more. The --stack-* fallbacks do not all ship every intermediate weight, and asking for one that does not exist gets you a synthesised face that looks wrong in any non-Latin script before it looks wrong in Latin. The sidecar faces do carry all four (every one of their weight axes spans 400 to 700), but the ceiling stays at four steps, because the tokens have to mean the same thing whether or not the faces loaded.

Tracking

Tabular numerals

--font-numeric-tabular is a font-feature string, not a length: . tnum makes every digit the same advance width so columns line up; lnum forces lining figures so digits do not sit at different heights beside each other. Currency columns need both.

src/base.css wires this up for you. Any cell marked data-numeric gets end alignment and both features, so a table author never writes the token by hand:

td[data-numeric],
th[data-numeric] {
  text-align: end;
  font-variant-numeric: tabular-nums;
  font-feature-settings: var(--font-numeric-tabular);
}

<table>
  <thead>
    <tr><th scope="col">Account</th><th scope="col" data-numeric>Balance</th></tr>
  </thead>
  <tbody>
    <tr><th scope="row">5401 2233</th><td data-numeric>1,240,500</td></tr>
  </tbody>
</table>

Underlines

Two tokens, applied by base.css to links.

How headings map

src/base.css assigns one scale step per heading level. Nothing else in the system sets a heading size, so this table is the whole mapping.

It also sets the face, which the table below does not repeat because it is the same for every level: h1–h6 read --font-display, not --font-sans. That is what makes headings Geologica over an Inter body, and what a typeface preset moves along with the copy.