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 ships with two typefaces, both served via the font plugin.

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.

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.