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

> Discover the Geist and Instrument Serif font families used in Diagram Design for labels, body text, annotations, and titles. Learn about their CSS implementation and system fallbacks.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-08-16

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```html
<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:**

```svg
<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.

```svg
<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."

```svg
<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`](https://github.com/cathrynlavery/diagram-design/blob/main/template.html) follows this structure:

```html
<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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) specifies extended font stacks. Individual `<text>` elements override the default variables with CJK-friendly alternatives.

**Japanese example:**

```svg
<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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) | Official typography specification mapping label types to families and sizes |
| [`template-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-full.html) | Full-page diagram showing all three fonts in coordinated hierarchy |
| [`type-gantt.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-gantt.md) | Geist sans for task names, Geist Mono for time-axis labels |
| [`type-org-chart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-org-chart.md) | Geist sans for role titles, Geist Mono for technical department tags |
| [`type-primitive-annotation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/template.html) to reference local paths.