Diagram Design Typography Settings: Semantic Font Roles and Implementation Guide

Diagram Design centralizes all typography settings in skills/diagram-design/references/style-guide.md, defining six semantic font roles using Instrument Serif, Geist, and Geist Mono families loaded via Google Fonts.

The cathrynlavery/diagram-design repository implements a strict typographic system to ensure consistent visual hierarchy across all generated diagrams. Understanding the typography settings for Diagram Design is essential for customizing exports or extending the rendering engine, as every font choice is semantically mapped to specific content types rather than hard-coded in individual diagram specifications.

Semantic Font Roles

According to the source code analysis of style-guide.md (lines 72–82), Diagram Design defines six semantic typography roles that determine how text renders across all diagram types. Each role binds to a specific font family, size, weight, and intended usage to maintain visual consistency.

• title — Uses Instrument Serif at 1.75 rem with weight 400 for page H1 headings.
• node-name — Uses Geist (sans-serif) at 12 px with weight 600 for human-readable node labels.
• sublabel — Uses Geist Mono at 9 px with weight 400 for technical details like ports, protocols, URLs, and field types.
• eyebrow — Uses Geist Mono at 7–8 px with weight 500, letter-spacing of 0.18 em, and uppercase transform for type tags and axis labels.
• arrow-label — Uses Geist Mono at 8 px with weight 400 and letter-spacing of 0.06 em for arrow annotations.
• callout — Uses Instrument Serif Italic at 14 px with weight 400 exclusively for editorial asides.

The rendering engine reads these settings when building SVG or HTML outputs, ensuring every diagram inherits the same typographic language without embedding font values in individual diagram specs.

Font Stack and Loading Strategy

A single Google Fonts <link> tag loads all three required families. As implemented in style-guide.md (lines 85–88), the font stack URL is:

<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">

This URL requests Instrument Serif in both regular and italic styles, Geist sans-serif in weights 400–600, and Geist Mono in weights 400–600. The export.md file describes how the Diagram Design skill automatically injects this link into exported SVG and HTML files during the build process.

Design Rationale

The typography system follows a strict "three families, not more" rule documented at line 137 of style-guide.md. This constraint prevents font bloat while preserving clear visual hierarchy.

• Geist Mono is reserved strictly for technical content such as commands, ports, and URLs.
• Geist Sans handles human-readable interface elements like node names.
• Instrument Serif carries editorial weight for page titles and callouts, with italics restricted to editorial asides only.

This separation ensures that users can instantly distinguish between data (mono), interface labels (sans), and narrative content (serif) across all diagram types.

Implementation Examples

HTML Export Integration

When building custom HTML exports outside the standard Diagram Design pipeline, reference the semantic roles using the exact CSS properties defined in the style guide:

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <!-- Load Diagram Design fonts -->
  <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>
    .title    { font-family: "Instrument Serif", serif; font-size: 1.75rem; font-weight: 400; }
    .node     { font-family: "Geist", sans-serif; font-size: 12px; font-weight: 600; }
    .sublabel { font-family: "Geist Mono", monospace; font-size: 9px; font-weight: 400; }
    .eyebrow  { font-family: "Geist Mono", monospace; font-size: 7px; font-weight: 500; text-transform: uppercase; letter-spacing: .18em; }
    .arrow    { font-family: "Geist Mono", monospace; font-size: 8px; font-weight: 400; letter-spacing: .06em; }
    .callout  { font-family: "Instrument Serif", serif; font-style: italic; font-size: 14px; font-weight: 400; }
  </style>
</head>
<body>
  <h1 class="title">Diagram Design – Typography Overview</h1>
  <div class="node">Server</div>
  <div class="sublabel">port 443</div>
  <div class="eyebrow">API</div>
  <div class="arrow">← request</div>
  <p class="callout">Note: keep the accent colour to one hue only.</p>
</body>
</html>

Mermaid Diagram Integration

For Mermaid-based diagrams processed by the Diagram Design skill, map semantic roles to classDef statements that reference the font families:

```mermaid
flowchart LR
  A[<span class="title">Title Node</span>] --> B[<span class="node-name">Server</span>]
  B --> C[<span class="sublabel">port 443</span>]
  classDef title     fill:#f5f5f5,stroke:#2d3142,font-family:'Instrument Serif',font-size:1.75rem;
  classDef node-name fill:#ffffff,stroke:#2d3142,font-family:'Geist',font-size:12px,font-weight:600;
  classDef sublabel  fill:#f5f5f5,stroke:#4f5d75,font-family:'Geist Mono',font-size:9px;
  class A title;
  class B node-name;
  class C sublabel;

The `classDef` statements inject the correct font families during rendering, ensuring the output matches the canonical definitions in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md).

## Key Source Files

The following files contain the authoritative source for Diagram Design’s typographic system:

- **[`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md)** — Canonical definition of all typography roles, font stack, and the three-family rule.
- **[`skills/diagram-design/references/type-timeline.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-timeline.md)** — Concrete example showing how `title`, `node-name`, and other roles appear in a specific diagram type.
- **[`skills/diagram-design/assets/example-timeline-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-timeline-full.html)** — HTML snapshot of a rendered diagram demonstrating the typography in `<text>` elements.
- **[`skills/diagram-design/references/export.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md)** — Documentation for how the skill injects the Google Fonts link into exported files.

## Summary

- Diagram Design stores all typography settings in [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) (lines 72–82).
- The system uses six semantic roles (`title`, `node-name`, `sublabel`, `eyebrow`, `arrow-label`, `callout`) mapped to three font families.
- **Instrument Serif**, **Geist**, and **Geist Mono** are loaded via a single Google Fonts request (lines 85–88).
- The "three families, not more" rule (line 137) prevents visual clutter and maintains strict content hierarchy.
- Implementation requires referencing the semantic roles rather than hard-coding font values in diagram specifications.

## Frequently Asked Questions

### Where are the typography settings defined in Diagram Design?

All typography settings are defined in [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md), specifically in the table at lines 72–82. This file acts as the single source of truth for font families, sizes, weights, and semantic roles across the entire repository.

### What font families does Diagram Design use?

Diagram Design uses three font families: **Instrument Serif** for editorial titles and callouts, **Geist** (sans-serif) for human-readable node names, and **Geist Mono** for technical content like ports and protocols. These are loaded from Google Fonts via a single link tag specified at lines 85–88 of [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md).

### How do I implement Diagram Design typography in custom HTML exports?

Reference the semantic CSS classes (`.title`, `.node`, `.sublabel`, etc.) with the exact font-family, size, and weight values defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md), and include the Google Fonts link in your HTML `<head>`. The [`example-timeline-full.html`](https://github.com/cathrynlavery/diagram-design/blob/main/example-timeline-full.html) file demonstrates how these properties render in actual diagram output.

### Why does Diagram Design restrict fonts to three families?

The restriction to "Serif + sans + mono – three families, not more" documented at line 137 prevents font bloat and preserves visual hierarchy. This constraint ensures that technical data (mono), interface labels (sans), and editorial content (serif) remain instantly distinguishable across all diagram types.

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