How the Four Import Dials (Format, Size, Detail, Audience) Affect Diagram Output

The four import dials—Format, Size, Detail, and Audience—control every aspect of how diagrams are redrawn from an intermediate representation, determining file types, canvas dimensions, element budgets, and vocabulary choices.

When importing diagrams from Mermaid or draw.io sources into the cathrynlavery/diagram-design skill, the system extracts an intermediate representation (IR) and then redraws the visualization according to four configurable dials. These settings govern everything from the physical pixel dimensions to the sophistication of technical language used in labels.

Understanding the Four Import Dials

Format Dial

The Format dial determines the destination file type and packaging method. With a default value of html, this setting controls whether the output is a self-contained HTML file or if additional SVG and PNG files are generated via the export process.

According to [skills/diagram-design/references/output-spec.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md), HTML serves as the single source of truth, while SVG and PNG formats are derived from the HTML rendering pipeline. This ensures consistent accessibility attributes and rendering across all output types.

Size Dial

The Size dial configures canvas dimensions, typographic scaling, and safe margins. Defaulting to doc-inline (960×600 pixels), this dial selects preset viewBoxes that control the SVG viewport and PNG pixel dimensions.

Size presets also define type-specific typographic ramps—adjusting node-name font sizes, box heights, and gaps based on the intended destination. For example, the slide-16x9 preset enlarges titles for presentation visibility, while doc-inline optimizes for technical documentation readability.

Detail Dial

The Detail dial establishes a quantitative budget for how many source elements survive the redraw process. Defaulting to balanced, this setting caps the maximum number of nodes and edges:

• faithful: Up to 24 nodes (with zoning support)
• balanced: Up to 12 nodes (default)
• simplified: Up to 7 nodes

When source diagrams exceed these budgets, the skill executes a structured degrade ladder as documented in [output-spec.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md): first dropping decorative cells, then merging duplicates, collapsing leaf clusters, pruning degree-1 sinks, and finally removing cross-cutting infrastructure. Each modification is recorded in a fidelity ledger that reports exactly which elements were altered or removed.

Audience Dial

The Audience dial controls vocabulary and phrasing without changing the element count. Defaulting to mixed, this setting offers three distinct language profiles:

• engineer: Prescise service names, port numbers, and protocol specifications
• mixed: Modest acronyms with plain verbs for cross-functional teams
• executive: Abstracted capabilities and business-oriented verbs, stripping all technical details

This dial applies after the Detail dial's pruning process, ensuring the remaining nodes speak the appropriate stakeholder language as defined in the [output-spec.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md) specification.

How the Dials Drive the Rendering Pipeline

The four dials orchestrate the rendering pipeline through four distinct stages:

1. ViewBox and Type Ramp Configuration – The Size preset establishes the canvas dimensions and automatically adjusts the typographic scale. If too many nodes exist for the selected canvas size (e.g., a slide format), the system forces the Detail dial to a lower setting to maintain readability.

2. Element Budget Enforcement – The Detail level caps the maximum node and edge count. When sources exceed these caps, the degrade ladder activates, and the system documents all changes in the fidelity ledger (see §5 of output-spec.md).

3. Label Vocabulary Transformation – After pruning completes, the Audience level rewrites node and edge labels to match the target stakeholder vocabulary without altering the structural budget.

4. Export Format Generation – The Format dial determines the final output package. The system always renders to HTML first, then conditionally generates SVG or PNG derivatives based on the format selection, never producing raster or vector files directly from hand-authored sources.

Practical CLI Examples

Both the [commands/import-mermaid.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) and [commands/import-drawio.md](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md) documents specify how to pass these dials as command-line flags:

# Mermaid import with explicit dials for high-fidelity engineering docs

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

# Draw.io import using defaults (html, doc-inline, balanced, mixed)

diagram-design:import-drawio diagram.drawio \
  --output=out/diagram

# Generate simplified SVG for executive stakeholders

diagram-design:import-drawio diagram.drawio \
  --format=svg \
  --size=fit \
  --detail=simplified \
  --audience=executive \
  --output=out/diagram

These commands illustrate how the dials translate directly into file outputs and visual density adjustments as implemented in the cathrynlavery/diagram-design repository.

Summary

• Format controls the output file types (HTML, SVG, PNG) with HTML serving as the rendering source of truth.
• Size determines canvas dimensions (viewBox) and typographic scaling via presets like doc-inline and slide-16x9.
• Detail enforces node budgets (7/12/24) and triggers the degrade ladder when source complexity exceeds the selected threshold.
• Audience rewrites labels for technical precision (engineer), accessibility (mixed), or business abstraction (executive) without changing element counts.
• All dials are configurable via CLI flags in both import-mermaid and import-drawio commands.

Frequently Asked Questions

What happens if my source diagram exceeds the Detail dial's node budget?

When the source contains more elements than the Detail dial permits (24 for faithful, 12 for balanced, or 7 for simplified), the skill automatically executes a degrade ladder. This process sequentially removes decorative cells, merges duplicate nodes, collapses leaf clusters, prunes degree-1 sinks, and strips cross-cutting infrastructure until the diagram fits within budget. Every change is logged in the fidelity ledger, which documents exactly which elements were modified or removed to achieve the target complexity.

Can I generate multiple output formats from a single import command?

Yes. Setting --format=html+png or similar composite values instructs the pipeline to first render the HTML source of truth, then derive additional formats via the export process. According to the source code in [output-spec.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md), you can request HTML alone, HTML plus derivatives, or specific single formats like SVG, always maintaining consistent rendering across all outputs.

How does the Audience dial handle highly technical terminology?

The engineer setting preserves precise service names, port numbers, and protocol specifications in node labels. When switched to executive, the same nodes are relabeled with business-oriented verbs and capability abstractions, stripping technical details entirely. The mixed setting provides a middle ground using modest acronyms and plain language suitable for cross-functional stakeholders. This transformation occurs after the Detail dial's pruning step, ensuring vocabulary changes never affect the structural node count.

What is the fidelity ledger and where can I find it?

The fidelity ledger is a reporting mechanism generated during the Detail dial's degrade process. When the skill modifies, merges, or removes nodes to meet the quantitative budget, it records each action in this ledger. Documentation in [references/import-mermaid.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md) describes how this artifact allows developers to audit exactly how the imported diagram differs from the original source, providing transparency for compliance and accuracy verification.

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