Typography

Typography in Nubisco is built on three layers: a raw scale of discrete sizes, a set of semantic tokens for line-height and letter-spacing, and type sets — pre-configured roles that bundle everything together into a named identity like body-md or heading-03. Components always use type sets, never raw scale values directly.

Typefaces ​

Nubisco declares two typefaces as its defaults: Plus Jakarta Sans for all UI text and Fira Code for code. These are the values of --nb-font-family-sans and --nb-font-family-mono. They are not bundled or loaded automatically: until you load them (or override the two variables), text falls back to the system stack. See Loading the fonts below.

Plus Jakarta Sans — sans-serif ​

The primary typeface for all UI text. It is a geometric sans-serif with strong legibility at small sizes and enough personality to work at display scale. Used for labels, body copy, headings, and display type.

Fira Code — monospace ​

Used exclusively for code, JSON viewers, technical values, and keyboard shortcuts. Its ligatures are enabled by default.

Loading the fonts ​

NubiscoUI references --nb-font-family-sans and --nb-font-family-mono everywhere, but it does not ship or auto-load any font files. This keeps the bundle free of fonts you may not want: consumers who already serve their own typefaces pay zero cost. There are two ways to get real fonts on the page.

Option A: override the family variables (bring your own) ​

If your app already loads fonts (its own @font-face, a bundler plugin, an @fontsource/* package, etc.), just point the two variables at them on :root. You load the files; NubiscoUI uses them.

/* main.css or App.vue <style>: load Inter + JetBrains Mono yourself, then: */
:root {
  --nb-font-family-sans: 'Inter', system-ui, sans-serif;
  --nb-font-family-mono: 'JetBrains Mono', ui-monospace, monospace;
}

Every type set resolves its family through these two variables. body, label, code, heading, and display all re-point automatically the moment the variables change. There is nothing else to override.

Option B: use the bundled defaults via the fonts plugin ​

NubiscoUI exports a Vite plugin that self-hosts the default Plus Jakarta Sans + Fira Code (via Fontsource, no third-party CDN, RGPD-friendly). Install the source packages and add the plugin:

pnpm add -D @fontsource/plus-jakarta-sans @fontsource/fira-code

// vite.config.ts
import { defineConfig } from 'vite'
import { fonts } from '@nubisco/ui/plugins/fonts'

export default defineConfig({
  plugins: [fonts()],
})

Then add the matching CSS import to your application entry, once. unplugin-fonts does not inject it automatically:

// src/main.ts (or your equivalent entry)
import 'unfonts.css'

TypeScript users may need to declare the module in their env.d.ts:

declare module 'unfonts.css'

Called with no arguments, fonts() loads the library defaults: Plus Jakarta Sans (weights 400/500/600/700) and Fira Code (400/600), normal styles, font-display: swap. Because these match the declared --nb-font-family-* defaults, you do not need to touch any CSS variable.

To load different families or weights, pass options (they fully replace the defaults). Any provider unplugin-fonts supports works, including custom for your own self-hosted woff2 files:

fonts({
  fontsource: {
    families: [
      { name: 'Inter', weights: [400, 600], styles: ['normal'] },
      { name: 'JetBrains Mono', weights: [400], styles: ['normal'] },
    ],
  },
})

The name passed to each family must match the value used in --nb-font-family-sans / --nb-font-family-mono exactly, including the quoting around multi-word names like 'JetBrains Mono'. Fontsource emits the @font-face under that exact family name, so if the override does not match, the browser falls through to the next fallback in the stack.

Then set --nb-font-family-sans / --nb-font-family-mono (Option A) so NubiscoUI uses the family names you just loaded.

Not on Vite? The plugin is a convenience, not a requirement. Load the fonts however your toolchain prefers (hand-written @font-face, your own bundler plugin, etc.), then use Option A to wire them into NubiscoUI.

Preloading critical weight ​

Fontsource sets font-display: swap, so text never blocks render. For first-paint LCP screens (login, dashboard landing), preloading the single weight that body-md uses removes the flash-of-fallback-text:

<!-- path is the hashed woff2 your bundler emits for the 400 weight -->
<link
  rel="preload"
  href="/path/to/your-body-weight.woff2"
  as="font"
  type="font/woff2"
  crossorigin
/>

The scale ​

The font-size scale is a curated set of values from 8px to 76px. Values are named by their pixel equivalent and exposed as CSS custom properties on :root.

How CSS variables are generated ​

All typographic values are derived from SCSS maps in src/styles/variables/_type.scss and emitted as CSS custom properties on :root by _theme.scss. Three categories:

Hierarchy through scale ​

Nubisco UI is primarily a product interface library — dashboards, forms, data-heavy views. At this density, the default reading size is body-md (14px), not 16px. Reserve body-lg for settings screens, onboarding flows, and other low-density contexts where users read more than they interact.

The hierarchy descends from the most prominent element on the page toward the least:

1. Page title — one per view, heading-04 or higher
2. Section heading — groups of content, heading-02 or heading-03
3. Card/panel title — scoped context, heading-01
4. Body — primary readable content, body-md
5. Supporting text — descriptions, help text, captions, body-sm
6. Labels — form labels, column headers, badges — label-md or label-lg
7. Meta — timestamps, IDs, secondary counts — label-sm with --nb-c-text-muted

Line-height rationale ​

Line-height is the most common typographic mistake in UI systems. Nubisco uses tighter leading as sizes grow:

Never set line-height equal to font-size — this produces lh = 1 regardless of font size and makes body text illegible.

Letter-spacing at large sizes ​

At display and heading sizes, the optical spacing between glyphs appears too loose due to how fonts are designed (they assume small text). Nubisco applies negative letter-spacing to headings and display type:

• heading-02 and up: -0.01em to -0.025em
• display-01 / display-02: -0.03em

Never apply negative letter-spacing to body or label text — it tightens to the point of illegibility at small sizes.

Semibold vs bold ​

• Semibold (600) — headings at heading-01 through heading-03, all labels. Enough weight for hierarchy without heaviness in dense UIs.
• Bold (700) — only for heading-04 and above, plus display. The visual jump to 700 is intentional at large sizes; at small sizes it reads as shouting.
• Regular (400) — all body and code.
• Light (300) — reserved for decorative large numbers or editorial use; avoid in core product UI.

Code typography ​

Always use code-* type sets for any monospaced content — not raw font-family: mono with an arbitrary size. This ensures Fira Code is paired with the right line-height for readability and the correct weight (ligatures only activate at regular).

Colour and text roles ​

The following semantic tokens are available for text colour:

Type sets are the primary way to apply typography. Each set bundles font-size, weight, line-height, letter-spacing, and font-family into a single named role. Apply them with the .type-{name} utility class or via CSS custom properties.

Labels ​

Used in UI controls — form field labels, column headers, badges, chips, tabs.

Body ​

Used for readable content — paragraphs, descriptions, help text, notifications.

Code ​

Used for monospaced content — code blocks, inline code, JSON viewers, keyboard shortcuts.

Headings ​

Used for page titles, section headings, card headers, and dialog titles. Headings 01–06 map directly to h6–h1 respectively.

Display ​

Used for hero sections, onboarding screens, marketing surfaces, and large statistical callouts.

CSS custom properties ​

Every type set generates four CSS variables on :root:

--nb-type-{name}-size
--nb-type-{name}-weight
--nb-type-{name}-line-height
--nb-type-{name}-letter-spacing
--nb-type-{name}-family

Full reference:

Utility classes ​

Apply a complete type set in one class:

<p class="type-body-md">Readable paragraph text</p>
<span class="type-label-md">Form label</span>
<h2 class="type-heading-03">Section title</h2>
<code class="type-code-md">const x = 1</code>

h1–h6 elements are already wired to their corresponding type sets by default (h1 → heading-06, h6 → heading-01). You only need .type-heading-* when applying heading styling to a non-heading element.

SCSS usage in components ​

Inside component <style> blocks, reference type set variables directly:

.my-component__title {
  font-size: var(--nb-type-heading-02-size);
  font-weight: var(--nb-type-heading-02-weight);
  line-height: var(--nb-type-heading-02-line-height);
  letter-spacing: var(--nb-type-heading-02-letter-spacing);
}

.my-component__description {
  font-size: var(--nb-type-body-md-size);
  font-weight: var(--nb-type-body-md-weight);
  line-height: var(--nb-type-body-md-line-height);
}

Line-height and letter-spacing scale utilities ​

Independent scale values are also available when you need to override a single property:

/* Line heights */
--nb-line-height-none: 1 --nb-line-height-tight: 1.1 --nb-line-height-snug: 1.25
  --nb-line-height-normal: 1.5 --nb-line-height-relaxed: 1.625
  --nb-line-height-loose: 1.75 /* Letter spacing */
  --nb-letter-spacing-tighter: -0.05em --nb-letter-spacing-tight: -0.02em
  --nb-letter-spacing-normal: 0em --nb-letter-spacing-wide: 0.02em
  --nb-letter-spacing-wider: 0.05em;

Adding a new type set ​

Edit $typeSets in src/styles/variables/_type.scss:

$typeSets: (
  // ...existing sets...
  caption: (
      size: 11,
      weight: regular,
      line-height: 1.4,
      letter-spacing: 0.01em,
    )
) !default;

This automatically generates --nb-type-caption-* variables and a .type-caption utility class.