Design tokens

DataLeaf’s visual language is defined by CSS custom properties in the theme’s assets/css/tokens.css. Components use only these tokens, so a site can adjust the design by overriding them in custom CSS without touching component selectors. The regression tests keep this page in sync with the stylesheet and check that the default colors meet WCAG 2.2 AA in both color schemes.

The design is editorial rather than app-like: reading text and titles are set in a serif, the interface and metadata in a sans, and structure comes from thin rules, alignment, and whitespace instead of cards and shadows. Color is restrained: one accent for links and focus, a muted second color for annotations, and semantic tints for callouts.

Each stack names the bundled face first, then installed fonts of similar proportions, so the design holds when the bundle is disabled. With the bundle, a metric-matched fallback follows each text face: Arial or a metric-compatible clone for IBM Plex Sans, and Georgia, or Times New Roman and its clones where Georgia is missing, scaled to the width of Source Serif 4. Text is set in it while the bundled fonts load, so lines keep their breaks and the page does not shift when the fonts arrive. IBM Plex Sans, the interface face, is preloaded and loaded with font-display: optional: it is used from the first render when it arrives promptly, and otherwise from the next page, so a late font never rewraps the navigation.

Components choose a role, not a family. To set reading text in the sans, override --dl-font-body with var(--dl-font-sans).

The theme bundles Source Serif 4, IBM Plex Sans, IBM Plex Mono, and STIX Two Math under the SIL Open Font License 1.1 and serves them from your own site: no font service, CDN, or tracking request is involved. Browsers download a file only when a page renders characters in that face and its unicode-range; a typical English page needs about 140 KB, and STIX Two Math (about 400 KB) loads only on pages with formulas when it is not installed.

To rely on installed fonts instead, disable the bundle:

[params.fonts]
  bundled = false

The theme then publishes no font files and no @font-face rules. The family stacks above fall back to installed fonts: Iowan Old Style, Charter, Sitka Text, Cambria, or Georgia for the serif; the system interface font for the sans; and the system monospace. A locally installed copy of a bundled family is still used when present. To use other web fonts, keep the bundle disabled, declare your own @font-face rules in custom CSS, and override the family tokens.

Interface sizes are fixed; reading text and titles grow slightly with the viewport.

Paragraph spacing is relative to the text it separates, so it follows the body size.

Media queries cannot read custom properties, so the layout changes at four fixed widths rather than at tokens. Visual checks cover 320, 375, 768, 1024, 1280, 1440, and 1920px around them.

Components use these steps rather than one-off values.

Dark mode is a separate palette for reading on a dark ground, not an inversion: a warm charcoal page rather than black or navy, warm off-white text, a lighter and less saturated accent, strong rules softened to grey so tables and lists do not glare, and its own code surface and syntax colors. Figures keep a light backdrop. Both the automatic and the explicit scheme use it, and the browser interface color (theme-color) follows --dl-bg in each. Tokens without a dark value keep their light value; role tokens such as --dl-link follow the color they reference.

Callouts keep a restrained tint and a rule in their semantic color. Mathematical statements have no tint: a thin rule in the colors below and a small label identify them.

Code sits on a quiet tint of the page between hairlines, with a restrained syntax palette in each scheme.