What the Four Import Dials Control in diagram-design: Format, Size, Detail, and Audience

The four import dials—format, size, detail, and audience—control the output file type, canvas dimensions, element budget, and lexical style of every diagram imported through the diagram-design toolchain.

In the cathrynlavery/diagram-design repository, these dials act as pre-flight parameters that shape the final deliverable before any redraw occurs. They are validated by the taste-gate logic in SKILL.md and must be recorded in the fidelity ledger whenever reductions are applied.

Format Dial: Output File Type and Content Scope

The format dial determines the file type emitted by the import process and which parts of the diagram are preserved or discarded.

• html produces a self-contained HTML file including the header, diagram, summary cards, footer, and live fonts. This is the default.
• svg and png are derived from the HTML but contain only the <svg> node—the diagram itself.
• html+png returns both the full HTML page and the rasterized image.

According to skills/diagram-design/references/output-spec.md § 1, the format directly drives the "Keeps / Drops" table for each deliverable. Only selected fragments survive based on this dial.

Size Dial: Canvas Preset and ViewBox

The size dial sets the SVG viewBox preset, which defines the physical dimensions, aspect ratio, and type-ramp that scales typography.

Available presets include:

• doc-inline
• doc-wide
• slide-16x9
• social-og
• print-a4-landscape

The default is doc-inline. As defined in skills/diagram-design/references/output-spec.md § 2, this dial controls canvas layout, outer margins, and the type-ramp that keeps text readable at the target resolution.

Detail Level Dial: Element Budget and Degrade Ladder

The detail dial controls how many elements from the source diagram survive the import.

• faithful keeps every node and edge up to a budget of 24 nodes.
• balanced keeps a reduced but detailed set of roughly 12 nodes. This is the default.
• simplified retains only core capabilities—approximately 7 nodes.

When the source exceeds the node budget, the dial drives the "degrade ladder" that decides what to trim, collapse, or merge. This behavior is documented in skills/diagram-design/references/output-spec.md § 3 and enforced before the HTML generator runs.

Audience Dial: Wording and Label Granularity

The audience dial determines the wording used for node names, sublabels, and edge labels.

• engineer uses precise service and component names along with low-level protocol details.
• mixed applies mid-level descriptions suitable for a mixed technical audience. This is the default.
• executive uses high-level business-oriented terms and omits technical minutiae.

As specified in skills/diagram-design/references/output-spec.md § 4, this dial adjusts the lexical style without altering the underlying topology.

Using the Four Import Dials in Practice

All four import dials are passed as CLI flags to the import commands. The taste-gate in skills/diagram-design/SKILL.md (§ 9) validates that they are set and consistent, and any reduction must be reported in the fidelity ledger.

Mermaid Import with Explicit Dials

# Example: Import a Mermaid file with explicit dials

diagram-design:import-mermaid \
  sample-flowchart.mmd \
  --format=svg \
  --size=slide-16x9 \
  --detail=faithful \
  --audience=engineer \
  --output=out/flowchart

Draw.io Import with Defaults

# Example: Import a Draw.io file, letting defaults apply (balanced / mixed / doc-inline / html)

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

When defaults apply, the system uses balanced detail, mixed audience, doc-inline size, and html format.

Social Card Export for Executives

# Example: Force a PNG output for a social-OG card, simplified for an executive audience

diagram-design:import-drawio \
  product-overview.drawio \
  --format=png \
  --size=social-og \
  --detail=simplified \
  --audience=executive \
  --output=out/overview

Each command reads the four dials and then invokes the HTML generator followed by the export step for SVG or PNG.

Key Source Files

The following files define and enforce the four import dials:

• skills/diagram-design/references/output-spec.md — Defines the dials, their defaults, and their effects on deliverables.
• skills/diagram-design/SKILL.md — Contains the taste-gate checklist that validates the dials.
• commands/import-mermaid.md — CLI documentation for the Mermaid import command.
• commands/import-drawio.md — CLI documentation for the Draw.io import command.

Summary

• Format controls the deliverable file type and whether headers, footers, or live fonts are included.
• Size sets the SVG viewBox preset and the type-ramp that preserves readability.
• Detail sets the node budget and triggers the degrade ladder when the source is too complex.
• Audience changes the lexical granularity of labels without modifying the diagram structure.
• All four import dials are validated by the taste-gate in SKILL.md and must appear in the fidelity ledger when reductions occur.

Frequently Asked Questions

What is the default setting for each of the four import dials?

The defaults are html for format, doc-inline for size, balanced for detail, and mixed for audience. These are defined in skills/diagram-design/references/output-spec.md §§ 1–4 and applied automatically when flags are omitted.

How does the detail dial decide what to remove from a complex diagram?

The detail dial enforces a hard node budget: up to 24 nodes for faithful, roughly 12 for balanced, and roughly 7 for simplified. When the source exceeds that budget, the degrade ladder trims, collapses, or merges elements according to the rules in output-spec.md § 3.

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

Yes. Setting --format=html+png returns both the full self-contained HTML file and the rasterized PNG image derived from the <svg> node, as described in output-spec.md § 1.

Where does the diagram-design toolchain validate the four import dials?

The dials are validated by the taste-gate checklist located in skills/diagram-design/SKILL.md § 9. The gate ensures all four values are set and consistent before the redraw begins.

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