Skip to content
Documentation

ADR-003: Typography & Density

Decision

Typography uses the system font stack only — no custom or brand web fonts. Hierarchy comes from the type scale (size and weight) and the spacing tokens, not from a typeface. Text and spacing use the semantic type and density utility classes, never raw combinations.

Key rules

  • The only font family is the system UI stack: -apple-system, "Segoe UI", system-ui, sans-serif. Do not load or apply web fonts — no Fraunces, Source Sans 3, Inter, Roboto, or Arial. The font-serif / font-body tokens resolve to this system stack.
  • Use the semantic type classes (ui-type-label, ui-type-body-sm, ui-type-title-lg, …) for size, weight, and letter-spacing — not raw text-sm font-medium combinations.
  • Hierarchy is expressed through size and weight (titles are larger and font-semibold), never through a separate display typeface.
  • Use density classes (ui-pad-row, ui-pad-card, …) for spacing, not arbitrary p-3 / gap-2.
  • Run pnpm density:check to audit non-compliant raw spacing.
  • Heading hierarchy must be semantically correct; type classes carry the visual, not the semantics.

Why

A system-font-only stack ships zero web fonts: faster first paint, a native feel on every platform, and no font-licensing or self-hosting burden. Hierarchy from the token scale keeps typography consistent and theme-able without depending on a brand typeface.

Applies when

You are applying text styles, choosing a font, or setting spacing on any component or layout.

  • ADR-001 — design tokens.
  • ADR-002 — radius and shape.