Typography Structure in Diagram Design Diagrams: The Three-Font System Explained

Diagram Design centralizes all typography decisions in the style-guide.md file, enforcing a strict three-family system (serif, sans-serif, and monospace) that ensures visual consistency across all generated SVG diagrams.

In the cathrynlavery/diagram-design repository, typography is not treated as an afterthought but as a core design token. The system organizes fonts into three distinct roles that every diagram element must follow, with the central reference file acting as the single source of truth for all visual styling decisions.

The Three-Family Typography System

The architecture mandates exactly three complementary font families to maintain hierarchy and readability while preventing visual clutter.

Serif for Titles and Callouts

The serif family provides visual contrast for headings and emphasized elements. According to skills/diagram-design/references/style-guide.md at line 179, the guide explicitly limits typography to "three families, not more" to maintain design discipline.

Sans-Serif for Body Text

Sans-serif serves as the default for body text and most diagram elements. This family handles the majority of content, ensuring high readability at various sizes within SVG outputs.

Monospace for Code and Data Labels

The monospace family is reserved for code snippets, axis labels, and data-dense text. This implementation appears in skills/diagram-design/assets/example-timeline.html, where a monospace label displays the text "typography pass" at coordinates (500, 344) using the 'Geist Mono' family.

Technical Implementation of Typography

The codebase implements this system through centralized configuration, automated detection, and runtime font injection.

Centralized Configuration References

The definitive typography rules reside in skills/diagram-design/references/style-guide.md. Line 3 establishes this file as the "single source of truth for colors, typography, and tokens," while line 179 enforces the architectural constraint of exactly three complementary families.

Custom Typography Detection

The primary skill logic in skills/diagram-design/SKILL.md implements the detection algorithm that identifies when users supply brand stylesheets. When triggered, the onboarding workflow documented in skills/diagram-design/references/onboarding.md extracts both the color palette and font families from the source website, then overwrites style-guide.md with the new typography selections.

SVG Export Mechanics

During rendering, the export engine processes these font definitions as specified in skills/diagram-design/references/export.md. The system injects a Google Fonts @import statement into the SVG document, applying XML escaping to ampersands within the URL to ensure strict parsing compliance while guaranteeing the three selected families render correctly in any modern browser.

Practical Typography Examples

The following snippets demonstrate how the three-family system appears in generated output.

<!-- Title using Serif family -->
<text x="10" y="20"
      font-family="'Instrument Serif', serif"
      font-size="14"
      fill="#000">Diagram Title</text>

<!-- Body text using Sans-serif -->
<text x="10" y="40"
      font-family="'Instrument Sans', sans-serif"
      font-size="10"
      fill="#333">Supporting description</text>

// Injecting Google Fonts with XML-escaped ampersands for SVG compatibility
const style = document.createElement('style');
style.textContent = "@import url('https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400&family=Instrument+Serif:wght@600&family=Geist+Mono:wght@400&display=swap');";
document.head.appendChild(style);

The reference asset skills/diagram-design/assets/example-timeline.html implements this system precisely, utilizing the monospace stack for data labels to maintain strict typographic hierarchy.

Summary

• Diagram Design uses exactly three font families (serif, sans-serif, monospace) defined in skills/diagram-design/references/style-guide.md
• The style-guide.md file serves as the single source of truth for all typography decisions, referenced at line 3 and constrained at line 179
• SVG exports inject Google Fonts via XML-escaped @import statements as detailed in skills/diagram-design/references/export.md
• Custom brands override defaults through the onboarding process described in skills/diagram-design/references/onboarding.md, which extracts and saves new font families to the style guide
• Monospace fonts label data points while serif handles titles, as demonstrated in skills/diagram-design/assets/example-timeline.html

Frequently Asked Questions

How does Diagram Design prevent font overload in diagrams?

The system enforces a strict limit of three font families as coded in skills/diagram-design/references/style-guide.md at line 179. This architectural constraint prevents visual clutter by mandating that designers choose one family for each specific role rather than mixing arbitrary typefaces.

Can I use custom fonts with Diagram Design?

Yes. The onboarding workflow described in skills/diagram-design/references/onboarding.md automatically extracts typography from your brand's source website. It identifies the font families in use and overwrites style-guide.md with these selections, causing all subsequent diagrams to render with your custom typography.

Why are Google Fonts XML-escaped in the SVG output?

The export process documented in skills/diagram-design/references/export.md requires XML-escaping the @import URL to maintain strict SVG parsing compliance. Since SVG is an XML-based format, unescaped ampersands in the Google Fonts URL would break the document structure, so the engine converts them to ensure the typography loads correctly in browsers.

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