Diagram-Design Size Presets: Complete Guide to Aspect Ratios and Export Targets

Diagram-design provides nine distinct size presets—including doc-inline, slide-16x9, social-og, and fit—that determine the SVG viewBox, PNG export resolution, aspect ratio, and type-size ramp to optimize diagrams for documentation, presentations, social media, and print.

The diagram-design CLI tool from the cathrynlavery/diagram-design repository uses a size dial to control the canvas dimensions and typography scale. Selecting the correct preset ensures your diagram renders crisply at its intended reading distance, whether embedded in a README, projected on a slide, or printed as a handout.

The Nine Size Presets Defined

All presets are formally defined in skills/diagram-design/references/output-spec.md【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/output-spec.md†L44-L53】. Each preset maps to specific viewBox coordinates, pixel densities, and typographic scales.

Preset	SVG viewBox	Aspect Ratio	PNG Export	Type Ramp	Primary Use Case
doc-inline	0 0 960 600	8:5	1920 × 1200 (@2x)	standard	Default for body-width diagrams in documentation
doc-wide	0 0 1280 720	16:9	2560 × 1440 (@2x)	standard	Full-width documentation or wiki pages
slide-16x9	0 0 1280 720	16:9	2560 × 1440 (@2x)	presentation	Modern 16:9 slide decks (Keynote, PowerPoint)
slide-4x3	0 0 1024 768	4:3	2048 × 1536 (@2x)	presentation	Legacy 4:3 presentation formats
social-og	0 0 1200 632	~1.9:1	2400 × 1264 (@2x)	presentation	Open Graph link previews (LinkedIn, X)
social-square	0 0 1080 1080	1:1	2160 × 2160 (@2x)	presentation	Square feed posts and carousel cards
print-a4-landscape	0 0 1120 792	~1.41:1	3360 × 2376 (@3x)	print	A4 landscape handouts and PDFs
print-letter-landscape	0 0 1056 816	~1.29:1	3168 × 2448 (@3x)	print	US Letter landscape physical prints
fit	content-derived	variable	@2x	standard	Vector hand-off for editing in Figma/Illustrator

When to Use Each Size Preset

Documentation Layouts (doc-inline, doc-wide)

Use doc-inline (the default) when embedding diagrams within text flows such as GitHub READMEs, blog posts, or documentation pages. The 960 × 600 canvas maintains readability without overwhelming surrounding prose. Choose doc-wide for full-width layouts like Confluence pages or internal wikis where horizontal space is abundant; the 1280 × 720 viewBox utilizes the extra real estate while keeping the standard type ramp optimized for screen reading.

Presentation Decks (slide-16x9, slide-4x3)

Select slide-16x9 for modern Keynote, PowerPoint, or Google Slides decks. The 1280 × 720 viewBox matches standard 16:9 templates, and the presentation type ramp (40 pt titles, 16 pt node names) ensures legibility from the back of a room. For legacy 4:3 projectors or templates, use slide-4x3 with its 1024 × 768 viewBox.

Social Media Cards (social-og, social-square)

The social-og preset generates 1200 × 632 viewBox diagrams optimized for Open Graph protocol link previews on LinkedIn and X. This preset includes a 64 px outer margin to prevent platform-specific thumbnail generators from cropping critical content【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/output-spec.md†L78-L80】. For Instagram-style square posts or carousel cards, social-square provides a 1080 × 1080 canvas at 1:1 aspect ratio.

Print Materials (print-a4-landscape, print-letter-landscape)

When generating physical handouts or PDFs, use print-a4-landscape (1120 × 792) or print-letter-landscape (1056 × 816). These presets export PNGs at @3x resolution (3360 × 2376 and 3168 × 2448 respectively) to ensure high-quality print output, and they activate the print type-size ramp optimized for paper reading distances.

Vector Editing Workflows (fit)

Use the fit preset when handing off diagrams to design tools like Figma or Adobe Illustrator. Rather than a fixed canvas, this preset calculates the viewBox from the content bounding box plus a 40 px outer margin and a 60 px bottom legend strip【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/output-spec.md†L54-L60】. This creates a tight, editable SVG without excess whitespace.

CLI Implementation and Grid Validation

Pass the preset to the CLI via the --size flag. The underlying scripts enforce that all viewBox values are divisible by 4, adhering to the grid rule specified in skills/diagram-design/SKILL.md【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/SKILL.md†L558-L560】. Additionally, validation scripts such as scripts/verify-drawio-import.py check that the generated SVG viewBox exactly matches the selected preset【/cache/repos/github.com/cathrynlavery/diagram-design/main/scripts/verify-drawio-import.py†L456-L456】.

# Embed in documentation (default size)

diagram-design import-mermaid \
  --format html \
  --size doc-inline \
  --input flowchart.mmd \
  --output diagram.html

# Generate slide-ready PNG

diagram-design import-mermaid \
  --format png \
  --size slide-16x9 \
  --input flowchart.mmd \
  --output slide.png

# Create Open Graph social card

diagram-design import-mermaid \
  --format png \
  --size social-og \
  --input flowchart.mmd \
  --output og.png

# Export editable SVG with auto-fitting canvas

diagram-design import-mermaid \
  --format svg \
  --size fit \
  --input flowchart.mmd \
  --output diagram.svg

Summary

• Nine presets cover every major output context: documentation, presentations, social media, print, and vector editing.
• doc-inline is the default 8:5 ratio for READMEs and docs, while doc-wide offers 16:9 for full-width layouts.
• Presentation presets (slide-16x9, slide-4x3) use enlarged type ramps for projection readability.
• Social presets match platform specifications exactly, with social-og including protective margins for link previews.
• Print presets render at @3x resolution for high-DPI physical output.
• fit auto-calculates canvas dimensions from content for downstream design tool workflows.

Frequently Asked Questions

How do I choose between doc-inline and doc-wide for my documentation?

Select doc-inline when the diagram sits inside a constrained text column or standard GitHub README, as its 960 × 600 viewBox respects body-width layouts. Use doc-wide when your documentation platform supports full-width content blocks, allowing the 1280 × 720 canvas to utilize extra horizontal space for complex diagrams.

Why do print presets use @3x PNG exports while others use @2x?

Print media requires higher pixel density (typically 300 dpi) to appear crisp on paper, whereas screen displays are optimized for 72–96 dpi. The print-a4-landscape and print-letter-landscape presets export at @3x (e.g., 3360 × 2376 pixels) to ensure raster elements remain sharp when physically printed, while documentation and social presets use @2x for efficient file sizes on screens.

What happens when I use the fit preset with the PNG format?

The fit preset still exports a PNG at @2x resolution, but the canvas dimensions are derived from the diagram content bounding box plus a 40 px margin and 60 px legend strip. This produces a PNG that tightly wraps the diagram without fixed aspect ratio constraints, ideal for insertion into documents where the diagram should occupy only its natural footprint.

Where are the preset dimensions defined in the source code?

All viewBox coordinates, aspect ratios, and PNG export sizes are defined in skills/diagram-design/references/output-spec.md lines 44–58【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/references/output-spec.md†L44-L58】. The type ramp mappings and grid divisibility rules (values must be divisible by 4) are documented in skills/diagram-design/SKILL.md lines 558–560【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/SKILL.md†L558-L560】.

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