Diagram Design Typography Standards: Font Roles and Specifications

Diagram Design maintains a strict three-font typography system where Instrument Serif handles editorial titles and callouts, Geist Sans manages human-readable node labels, and Geist Mono reserves technical details like ports and protocols, as defined in the repository's centralized style guide.

The cathrynlavery/diagram-design repository implements a single-source-of-truth approach to visual consistency. These Diagram Design typography standards assign discrete semantic roles to each font family, ensuring that regardless of whether a diagram originates from Mermaid, draw.io, or custom SVG, the text remains scannable, accessible, and visually coherent.

The Three-Font Architecture

The typography stack defined in [skills/diagram-design/references/style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) relies on three distinct families to create visual hierarchy and semantic clarity.

Instrument Serif for Editorial Hierarchy

Instrument Serif serves as the editorial voice of the system. The font appears at 1.75 rem with a weight of 400 for page-level title roles (equivalent to <h1> headings), providing a refined, publication-quality feel to diagram headers. For callout roles—editorial asides and annotation notes—the system uses Instrument Serif italic at 14 px, creating a distinct visual separation from technical content.

Geist Sans for Human-Readable Labels

All human-readable identifiers use Geist (sans-serif). The node-name role employs 12 px at 600 weight for clear, legible node labels. This family carries the narrative burden of the diagram, ensuring that service names, component titles, and body text remain clean and approachable without monospaced "code" aesthetics.

Geist Mono for Technical Precision

Geist Mono handles every technical element. The sublabel role uses 9 px at 400 weight for ports, protocols, URLs, and field types. Smaller variants include the eyebrow role at 7–8 px (weight 500, uppercase, letter-spacing 0.18 em) for type tags and axis labels, and the arrow-label role at 8 px (letter-spacing 0.06 em) for connection annotations. This containment prevents technical content from "leaking" a developer-font aesthetic into the entire diagram.

Semantic Role Specifications

The mapping between semantic tokens and font specifications is rigidly defined in the Typography section of [style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) (lines 74–82):

Role (semantic token)	Font family	Size	Weight	Typical use
title	Instrument Serif	1.75 rem	400	Page-level headings
node-name	Geist (sans-serif)	12 px	600	Human-readable node labels
sublabel	Geist Mono	9 px	400	Technical sub-labels (ports, protocols, URLs)
eyebrow	Geist Mono	7–8 px	500 (tracked 0.18 em, uppercase)	Type tags, axis labels
arrow-label	Geist Mono	8 px	400 (tracked 0.06 em)	Arrow annotations
callout	Instrument Serif italic	14 px	400	Editorial asides, annotation callouts

Load-Bearing Typography Rules

The system enforces three non-negotiable constraints documented in [style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) (lines 89–90) and reiterated in [SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) section 5:

• Mono is reserved for technical content —anything resembling code (commands, URLs, field types)—to prevent monospace fonts from dominating the visual field.
• Names use Geist sans —all human-readable labels (node names, titles, body copy) utilize the clean sans-serif family for maximum legibility.
• Page titles use Instrument Serif —the serif typeface provides editorial weight, while its italic variant remains exclusive to callout roles.

These rules ensure clarity by separating technical "mono" text from narrative "sans" text, consistency across all diagram sources, and accessibility through WCAG AA-compliant contrast ratios for the default ink color on paper backgrounds.

SVG Implementation Examples

The following SVG snippets demonstrate the correct font-family declarations for each semantic role. These patterns mirror the reference type files (e.g., type-node-name.md, type-arrow-label.md) used throughout the codebase.

<!-- Title – Instrument Serif -->
<text x="20" y="30" fill="#2d3142"
      font-family="'Instrument Serif', serif"
      font-size="1.75rem">Diagram Design Overview</text>

<!-- Node name – Geist sans -->
<text x="20" y="70" fill="#2d3142"
      font-family="'Geist', sans-serif"
      font-size="12px"
      font-weight="600">User Service</text>

<!-- Sublabel – Geist Mono (technical) -->
<text x="20" y="90" fill="#4f5d75"
      font-family="'Geist Mono', monospace"
      font-size="9px">GET /api/users</text>

<!-- Eyebrow – Geist Mono, uppercase, tracked -->
<text x="20" y="110" fill="#7a8399"
      font-family="'Geist Mono', monospace"
      font-size="8px"
      font-weight="500"
      letter-spacing="0.18em"
      text-transform="uppercase">API</text>

<!-- Arrow label – Geist Mono -->
<text x="150" y="120" fill="#4f5d75"
      font-family="'Geist Mono', monospace"
      font-size="8px"
      letter-spacing="0.06em">writes</text>

<!-- Callout – Instrument Serif italic -->
<text x="20" y="150" fill="#2d3142"
      font-family="'Instrument Serif', serif"
      font-style="italic"
      font-size="14px">Note: This service is rate‑limited.</text>

Summary

• Three fonts govern the system: Instrument Serif (editorial), Geist Sans (human-readable), and Geist Mono (technical).
• Semantic roles are strict: title, node-name, sublabel, eyebrow, arrow-label, and callout each map to specific families, sizes, and weights defined in skills/diagram-design/references/style-guide.md.
• Technical containment: Geist Mono is exclusively reserved for code-like content to maintain visual hierarchy.
• Accessibility compliance: All specifications meet WCAG AA contrast requirements for the default color palette.

Frequently Asked Questions

Which font should I use for API endpoint labels in Diagram Design?

Use Geist Mono at 9 px with weight 400 for the sublabel role. According to the load-bearing rules in style-guide.md, monospaced fonts are strictly reserved for technical content including ports, protocols, URLs, and field types to prevent a "dev-font" aesthetic from overwhelming the diagram.

Where are the official Diagram Design typography standards documented?

The authoritative specifications reside in [skills/diagram-design/references/style-guide.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md), specifically lines 74–82 for the type mapping and lines 89–90 for load-bearing rules. High-level design system philosophy is further elaborated in [skills/diagram-design/SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) section 5.

Why does Diagram Design specify a serif font for page titles?

Instrument Serif provides an editorial, publication-quality feel that distinguishes page-level title roles from technical diagrams. This creates immediate visual hierarchy: users perceive serif headings as narrative context while sans-serif and mono text deliver functional information. The italic variant is reserved exclusively for callout roles to maintain semantic consistency.

How do the typography standards ensure accessibility?

The style guide specifies font sizes and weights that maintain WCAG AA contrast ratios when rendered in the default ink color against the paper background. By segregating technical content into Geist Mono and human-readable labels into Geist Sans, the system also improves cognitive accessibility, allowing users to instantly distinguish between narrative elements and technical specifications.

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