Diagram Design Font Families: A Complete Guide to Typography in cathrynlavery/diagram-design

Diagram Design uses three core font families—Geist (sans-serif) for labels and body text, Geist Mono for technical annotations, and Instrument Serif for titles—implemented through CSS custom properties in template.html with system fallbacks and CJK extensions.

Diagram typography determines whether your architecture diagrams look polished or amateur. In the cathrynlavery/diagram-design repository, every font choice is deliberate, mapped to specific diagram elements through a type system defined in the core templates and style guide documentation.

The Three Core Font Families in Diagram Design

The repository declares all fonts as CSS custom properties in skills/diagram-design/assets/template.html. This centralization ensures consistent typography across every generated diagram.

Geist Sans: The Default Workhorse

Geist serves as the primary sans-serif for human-readable content.

• Declared as: --font-sans: 'Geist', system-ui, sans-serif;
• Used for: Node names, headings, titles, body text, labels, and general diagram content

Geist provides a clean, modern aesthetic that remains legible at small sizes typical in dense architecture diagrams. The variable font includes weights 400, 500, and 600 as imported from Google Fonts.

<link href="https://fonts.googleapis.com/css2?family=Geist:wght@400;500;600&display=swap" rel="stylesheet">

<style>
  :root {
    --font-sans: 'Geist', system-ui, sans-serif;
  }
</style>

SVG implementation:

<text x="150" y="30" font-family="var(--font-sans)" font-size="16" font-weight="600">
  Service Name
</text>

Geist Mono: Technical Precision

Geist Mono handles anything requiring alignment or code-like presentation.

• Declared as: --font-mono: 'Geist Mono', ui-monospace, monospace;
• Used for: Arrow annotations, field names, port numbers, URLs, timestamps, API endpoints, and technical sub-labels

Monospaced characters align vertically, making multi-line technical data scannable at a glance. This is critical for diagrams showing request flows or configuration values.

<text x="150" y="55" font-family="var(--font-mono)" font-size="12">
  GET /api/v1/resource
</text>

Instrument Serif: Distinctive Titles

Instrument Serif adds visual weight to high-level hierarchy elements.

• Declared as: --font-serif: 'Instrument Serif', serif;
• Used for: Page titles, document headings, and occasional annotation callouts

The serif style creates separation from the sans-serif body, signaling "this is the container, not the content."

<text x="150" y="80" font-family="var(--font-serif)" font-size="20">
  Architecture Diagram
</text>

Font Implementation Architecture

CSS Custom Property Pattern

The complete font stack in template.html follows this structure:

<link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Geist:wght@400;500;600&family=Geist+Mono:wght@400;500;600&display=swap"
      rel="stylesheet">

<style>
  :root {
    --font-sans:  'Geist', system-ui, sans-serif;
    --font-mono:  'Geist Mono', ui-monospace, monospace;
    --font-serif: 'Instrument Serif', serif;
  }
  
  body { font-family: var(--font-sans); }
  .eyebrow { font-family: var(--font-mono); }
  h1 { font-family: var(--font-serif); }
</style>

This pattern allows single-point updates: change the custom property, and every diagram element using that variable updates automatically.

System Fallback Strategy

Each font family includes platform-native fallbacks:

Custom Property	Primary Font	Fallback Chain
--font-sans	Geist	system-ui, sans-serif
--font-mono	Geist Mono	ui-monospace, monospace
--font-serif	Instrument Serif	serif

These fallbacks guarantee legibility when custom fonts fail to load or when diagrams are viewed offline.

CJK and International Font Support

For non-Latin scripts, the style guide in skills/diagram-design/references/style-guide.md specifies extended font stacks. Individual <text> elements override the default variables with CJK-friendly alternatives.

Japanese example:

<text font-family="'Geist', 'Hiragino Sans', 'Noto Sans JP', 'Yu Gothic', sans-serif"
      x="200" y="120" font-size="14">
  認証サービス
</text>

Recommended CJK fallbacks:

• Hiragino Sans — macOS/iOS default
• Noto Sans JP — Google cross-platform solution
• Yu Gothic — Windows Japanese system font

Type System in Practice: File-by-File Usage

The repository demonstrates deliberate font application across reference documents:

File	Font Usage Pattern
style-guide.md	Official typography specification mapping label types to families and sizes
template-full.html	Full-page diagram showing all three fonts in coordinated hierarchy
type-gantt.md	Geist sans for task names, Geist Mono for time-axis labels
type-org-chart.md	Geist sans for role titles, Geist Mono for technical department tags
type-primitive-annotation.md	Instrument Serif for annotation callouts and emphasis

Visual Hierarchy Principles

The three-font system creates immediate scannable structure:

1. Glance level — Instrument Serif titles orient the viewer to diagram purpose
2. Navigation level — Geist sans labels identify components and relationships
3. Detail level — Geist Mono exposes precise technical values without cluttering the visual field

This hierarchy mirrors how viewers process architecture diagrams: first the scope, then the components, finally the specifics.

Summary

• Geist (sans) is the default for all human-readable labels, headings, and body text in diagrams
• Geist Mono handles technical data requiring alignment: APIs, ports, timestamps, field names
• Instrument Serif reserves visual weight for document titles and standout callouts
• All fonts are declared as CSS custom properties in skills/diagram-design/assets/template.html with system-ui and generic fallbacks
• CJK support extends the stack through per-element overrides using Hiragino Sans, Noto Sans JP, and Yu Gothic
• The type system is documented in style-guide.md and demonstrated across specialized reference files

Frequently Asked Questions

How do I add a new font to Diagram Design?

Define a new CSS custom property in template.html following the existing pattern: --font-custom: 'Font Name', fallback, generic;. Import the font via <link> or @import, then reference the variable in your SVG font-family attributes. Update style-guide.md to document the new font's designated purpose.

Why does Geist Mono use ui-monospace as a fallback?

ui-monospace is a system font keyword that selects the platform's native monospace interface font (SF Mono on macOS, Consolas on Windows). This preserves the intended aesthetic closer than generic monospace, which often maps to Courier or other less suitable alternatives.

Can I use these fonts in exported PNG/SVG files?

Yes. The fonts render correctly in SVG exports since they reference web fonts. For PNG rasterization, ensure the rendering environment has font access or embed the fonts as data URIs. The Google Fonts CDN links in template.html support both screen display and automated export pipelines.

What happens if Google Fonts is unavailable?

The CSS fallback chain activates: system-ui or ui-monospace provide near-equivalent aesthetics on modern operating systems. For offline or air-gapped environments, self-host the font files and update the @font-face declarations in template.html to reference local paths.

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