Diagram-Design Font Families: Title, Node Name, and Sublabel Typography Explained

Diagram-Design uses three distinct font families: Instrument Serif for titles, Geist for node names, and Geist Mono for sublabels. These families are defined in the project's Style Guide and implemented via CSS custom properties across all HTML and SVG templates.

The cathrynlavery/diagram-design repository enforces a strict typographic system to ensure visual consistency between page-level headings, human-readable diagram labels, and technical metadata. Understanding these font family assignments is essential for contributors creating new diagrams or customizing the design system.

Title Font Family: Instrument Serif

Page-level headings in diagram-design use Instrument Serif, a classic serif typeface that provides visual hierarchy and distinguishes titles from functional diagram elements.

According to skills/diagram-design/references/style-guide.md (lines 76-77), the title family is explicitly specified for "page titles and high-level headings." This family maps to the CSS custom property --font-serif in skills/diagram-design/assets/template.html:

<style>
  :root {
    --font-serif: 'Instrument Serif', 'Noto Serif KR', serif;
  }
</style>

When rendered, an <h1> element inherits this family automatically:

<h1 class="title">My Diagram Title</h1>

The Korean fallback (Noto Serif KR) ensures proper character rendering for internationalized diagrams.

Node Name Font Family: Geist

Human-readable labels on diagram nodes use Geist, the primary sans-serif family. As specified in style-guide.md (lines 77-78), this applies to all node identifiers and functional labels that users read to understand diagram structure.

The CSS root variable --font-sans assigns this family:

:root {
  --font-sans: 'Geist', system-ui, sans-serif;
}

In SVG diagrams, node names explicitly reference this family:

<text class="node-name"
      x="200" y="100"
      fill="#2d3142"
      font-size="12"
      font-weight="600"
      font-family="Geist, sans-serif">
  Payments
</text>

The system-ui fallback ensures readable text if Geist fails to load.

Sublabel Font Family: Geist Mono

Technical details—ports, protocols, field types, and API endpoints—use Geist Mono, a monospaced variant designed for code-like content. The style guide (lines 78-79) designates this family for "technical details" that benefit from fixed-width character alignment.

The custom property --font-mono implements this mapping:

:root {
  --font-mono: 'Geist Mono', ui-monospace, monospace;
}

SVG implementations apply this directly:

<text class="sublabel"
      x="200" y="120"
      fill="#4f5d75"
      font-size="9"
      font-family="Geist Mono, monospace">
  https://api.example.com
</text>

The ui-monospace system font provides a native fallback on Apple platforms before Geist Mono loads.

Where Font Families Are Defined

Three files control the complete typographic system:

• skills/diagram-design/references/style-guide.md — Central specification document listing all font families, sizes, and weights with usage guidelines
• skills/diagram-design/assets/template.html — HTML template defining CSS custom properties at :root scope (lines 15-17)
• skills/diagram-design/references/type-line.md — Reference file containing example SVG snippets demonstrating proper family application

The separation between specification (style-guide.md) and implementation (template.html) allows contributors to update font families centrally while templates inherit changes automatically.

How to Override Font Families

To customize the font system for a specific diagram:

1. Local CSS override: Redefine the custom property in a scoped <style> block
2. Inline SVG: Specify font-family directly on <text> elements
3. Template fork: Modify template.html for project-wide changes

For localized overrides, prefer CSS specificity:

.my-custom-diagram {
  --font-sans: 'Inter', system-ui, sans-serif;
}

This preserves the design system's architecture while accommodating brand requirements.

Summary

• Instrument Serif — Title font family for page headings and diagram titles, defined in style-guide.md lines 76-77
• Geist — Node name font family for human-readable diagram labels, mapped to --font-sans in template.html
• Geist Mono — Sublabel font family for technical metadata, mapped to --font-mono with monospace fallbacks
• All three families derive from CSS custom properties in skills/diagram-design/assets/template.html lines 15-17

Frequently Asked Questions

What happens if Geist fonts fail to load?

The CSS custom properties include system font fallbacks. For --font-sans, system-ui and generic sans-serif activate. For --font-mono, ui-monospace and monospace provide equivalent spacing. Titles fall back to Noto Serif KR then generic serif.

Can I use different font families for specific diagram types?

Yes. The CSS custom property architecture supports scoped overrides. Define new families within a specific class or inline style without modifying the global template. The style guide recommends maintaining the three-family structure for consistency.

Where does the style guide specify font sizes and weights?

Beyond font families, style-guide.md contains complete specifications for sizes, weights, and line heights. The type-line.md reference file provides working SVG examples combining these properties with the correct font families.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}