The Four Dials for Importing Diagrams in Diagram-Design: Format, Size, Detail, and Audience

Diagram-Design uses four configurable dials—Format, Size, Detail, and Audience—to control how imported diagrams are rendered, saved, and presented before the final canvas is drawn.

The cathrynlavery/diagram-design repository provides a structured system for importing technical diagrams through four critical configuration parameters defined in skills/diagram-design/references/output-spec.md. These settings determine everything from file output types to audience-appropriate labeling and node density. Understanding how to manipulate these four dials ensures your diagrams land correctly across documentation, presentations, and social platforms.

Understanding the Four Configuration Dials

Format Dial

The Format dial determines the file type of the saved diagram. According to the source specification in output-spec.md (lines 7-8), valid options include html, svg, png, or combined formats like html+png. The default value is html. This dial dictates where the output "lands" and whether the deliverable is a self-contained HTML file, a raw SVG for editing, or a raster PNG for static embedding.

Size Dial

The Size dial controls the canvas dimensions through SVG viewBox attributes and associated PNG pixel dimensions. As documented in output-spec.md (lines 8-9, 44-52), this dial uses presets like doc-inline (default), slide-16x9, social-og, or fit to map to typical destinations. For example, the doc-inline preset renders at a 960×600 viewBox for SVG and 1920×1200 pixels for PNG output.

Detail Dial

The Detail dial (also referred to as Detail level) governs how much of the source diagram survives the import process. The three levels—faithful, balanced (default), and simplified—impose explicit caps on node counts, edge counts, and sub-labels (lines 9-10, 88-92 in output-spec.md). This acts as a "count" dial that limits node density for different consumption contexts.

Audience Dial

The Audience dial adjusts the technical depth of labeling independently from detail density. With settings of engineer, mixed (default), or executive, this dial changes node names, sub-labels, and edge verbs to match technical sophistication (lines 9-10, 20-25 in output-spec.md). Engineers see full technical nomenclature, while executive settings simplify terminology for stakeholder presentations.

How the Dials Interact During Import

These four parameters must be resolved—either explicitly requested, inferred from the destination, or defaulted—before the diagram is redrawn. The interaction follows a strict pipeline:

1. Format drives the export procedure, determining whether non-HTML formats are generated from the base HTML canvas (lines 20-25).
2. Size selects the preset that establishes the viewBox and pixel dimensions for the target medium.
3. Detail applies compression logic to limit node/edge survival rates based on the selected level.
4. Audience transforms the labeling layer without affecting the structural density controlled by Detail.

The SKILL.md checklist (lines 525-532) validates that all four dials are correctly set before the drawing phase begins.

Configuring the Dials via Command Line

Both the import-mermaid and import-drawio commands consume these dials through explicit CLI flags. The flags map directly to the configuration schema defined in the output specification.

Import a Mermaid file for high-detail engineering slides:

diagram-design:import-mermaid diagrams/architecture.mmd \
  --format=png \
  --size=slide-16x9 \
  --detail=faithful \
  --audience=engineer \
  --output=out/architecture

Import a Draw.io file for mixed-audience documentation with multiple output formats:

diagram-design:import-drawio diagrams/infra.drawio \
  --format=html+png \
  --size=doc-inline \
  --detail=balanced \
  --audience=mixed \
  --output=out/infra

Each flag corresponds exactly to the dial specifications in output-spec.md, ensuring consistent behavior across import methods.

Key Source Files and References

The implementation and validation of these dials span several critical files in the repository:

• skills/diagram-design/references/output-spec.md — Master reference defining dial defaults, options, and the complete configuration matrix (lines 5-10, 44-53, 88-92).
• skills/diagram-design/SKILL.md — Contains the pre-draw checklist validating dial configuration (lines 525-532).
• commands/import-mermaid.md and commands/import-drawio.md — CLI documentation consuming the four dials.
• prompts/import-mermaid.md and prompts/export-diagram.md — User-facing documentation describing flag behaviors.

Summary

• Format, Size, Detail, and Audience are the four required dials configured before diagram generation in Diagram-Design.
• Defaults are html (Format), doc-inline (Size), balanced (Detail), and mixed (Audience).
• All four parameters must be resolved before drawing, as enforced by the SKILL.md checklist.
• CLI commands import-mermaid and import-drawio expose these dials via --format, --size, --detail, and --audience flags.
• The canonical specification lives in skills/diagram-design/references/output-spec.md.

Frequently Asked Questions

What happens if I don't specify all four dials when importing a diagram?

The system applies default values defined in output-spec.md: html for Format, doc-inline for Size, balanced for Detail, and mixed for Audience. However, the SKILL.md checklist validates that these are explicitly acknowledged before drawing to prevent accidental misconfiguration.

Can I use different dials for the same source diagram in multiple outputs?

Yes. Each import invocation is independent, allowing you to render the same architecture.mmd source with --size=slide-16x9 for presentations and --size=doc-inline for documentation, changing only the output directory and dial parameters.

How does the Detail dial differ from the Audience dial?

Detail controls structural density—how many nodes, edges, and sub-labels physically survive the import process. Audience controls linguistic transformation—changing technical terminology into business-friendly language without removing structural elements. They operate on independent layers of the rendering pipeline.

Where are the valid Size presets documented?

The complete matrix of Size presets and their corresponding viewBox and pixel dimensions is defined in skills/diagram-design/references/output-spec.md (lines 44-52), including mappings for documents, slides, and social media cards.

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