Font Family

Vectis UI does not bundle any external web fonts. Its typographical configuration relies exclusively on three family tokens, each associated by default with a platform system font stack. The interface thus benefits from a native, fast, and consistent rendering across all environments, without requiring any preliminary typographical setup.

The 3 Default Fonts

--vectis-font-family-sans: System font stack for the user interface (system-ui, -apple-system, Segoe UI, Roboto, etc.). Serves as the default typographical family for all components.
--vectis-font-family-display: Family reserved for titles. Its value defaults to var(--vectis-font-family-sans). This indirection avoids variable duplication: a single override is enough to dissociate headings from the rest of the interface.
--vectis-font-family-mono: Native monospace stack (ui-monospace, Cascadia Code, Source Code Pro, Menlo, Consolas, etc.). Ensures support for code and tabular data by leveraging local platform resources.

A second abstraction layer introduces three semantic tokens (or roles) directly consumed by the interface: --vectis-text-family, --vectis-text-family-heading, and --vectis-text-family-code. By binding component CSS to these roles rather than typographical primitives, Vectis UI enables scoping overrides to a specific DOM subtree without affecting the global configuration of the document.

Integrating a Web Font

Integrating a custom font takes place in two steps, both independent of the design system: loading the typographical resource, and then associating its name with the corresponding family token. Since tokens are simple CSS variables (custom properties), a declaration at the :root selector level propagates the modification across the entire interface, while a declaration targeted at a specific container restricts the new font to its DOM subtree.

css

/* Your own stylesheet, in no layer. */
@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');

:root {
  --vectis-font-family-sans: 'Inter', system-ui, sans-serif;
  --vectis-font-family-display: 'Inter', system-ui, sans-serif;
}

Local hosting of font files (declared via @font-face and served from your own origin) is the recommended approach for offline builds, applications guaranteeing zero third-party requests, or direct control over HTTP caching. Only the resource loading method differs: connection to Vectis UI's design tokens remains strictly identical.

css

/* Your own stylesheet, in no layer. The files are served from your origin. */
@font-face {
  font-family: 'Inter';
  src: url('/fonts/inter-variable.woff2') format('woff2-variations');
  font-weight: 400 700;
  font-display: swap;
}

:root {
  --vectis-font-family-sans: 'Inter', system-ui, sans-serif;
  --vectis-font-family-display: 'Inter', system-ui, sans-serif;
}

Typographical Role Mapping

Assigning a display font is done through a single CSS re-declaration. However, this modification remains targeted: only five typographical roles consume the display family, while the rest of the interface retains the main text font. The nomenclature below details the affected elements to guide you in choosing a suitable typography.
This behavior requires no wiring: the VTypography component determines its role via the variant property, while composite components (dialog titles or accordion headers) automatically apply their respective semantic role.

Display family (--vectis-text-family-heading): Consumed exclusively by the 5 heading variants: display (48px), heading-1 (36px), heading-2 (24px), heading-3 (18px), and heading-4 (16px).
Body text family (--vectis-text-family): Applied by default to all other variants (subtitle, the 4 levels of body text, label, caption, overline) as well as the internal typography of all control components (v-control).
Code family (--vectis-text-family-code): Strictly restricted to the code role.

Icon Font Management (Optional Dependency)

The --vectis-font-family-icon token defaults to referencing the Material Symbols Rounded font. True to the principle of zero network dependencies, the library does not perform any automatic loading of this file. This resource is solely required for rendering icons via ligatures outside of the native registry. To free the application from this dependency, refer to the section Iconography to implement a custom resolver.