What Are the Four Dials That Shape draw.io Imports?

The four dials that shape draw.io imports are Format, Size, Detail, and Audience—configurable parameters that determine output media type, dimensions, visual fidelity, and target styling when transforming .drawio files into editorial-quality diagrams.

When the Diagram-Design skill processes source files from the cathrynlavery/diagram-design repository, it does not merely copy the original graphic. Instead, the import-drawio slash command applies four transformational controls defined in commands/import-drawio.md to convert raw diagrams into production-ready assets.

The Four Dials Explained

Each dial corresponds to a specific command-line argument passed to the import utility. These settings dictate how drawio_extract.py (located at skills/diagram-design/scripts/drawio_extract.py) parses the compressed .drawio payload and generates the structured intermediate representation.

Format

The Format dial controls the output media type. Available options include HTML, SVG, PNG, or a HTML+PNG combination. This determines whether the final asset renders as a web-ready vector, a raster image for slides, or a dual-format package for documentation systems.

Size

The Size dial defines the overall canvas dimensions and aspect ratio. Preset options include slide-16x9 for presentation decks, doc-inline for embedded documentation figures, and doc-full for full-page technical diagrams. This ensures the output matches the destination container without manual resizing.

Detail

The Detail dial sets the level of visual fidelity. The three modes are:

• faithful: Preserves every element from the source diagram
• balanced: Applies typical editorial compression for clarity
• simplified: Generates a high-level overview suitable for executive summaries

Audience

The Audience dial tailors styling and complexity for specific viewers. Options include engineer (technical notation emphasis), mixed (general technical audiences), and executive (simplified visual language for decision-makers).

Configuring the Import Dials

You invoke these parameters via the /diagram-design:import-drawio slash command or its programmatic equivalent. The dials are passed as arguments to override defaults.

A basic import uses default values (HTML output, slide-16x9 size, balanced detail, mixed audience):

/diagram-design:import-drawio platform.drawio

To generate a PNG for executive review with simplified detail:

/diagram-design:import-drawio platform.drawio \
    --format=png \
    --size=slide-16x9 \
    --detail=simplified \
    --audience=executive

For technical documentation requiring faithful element preservation with dual-format output:

/diagram-design:import-drawio platform.drawio \
    --format=html+png \
    --size=doc-inline \
    --detail=faithful \
    --audience=engineer

Technical Implementation

According to the cathrynlavery/diagram-design source code, the extraction pipeline begins when drawio_extract.py decodes the compressed XML payload within the .drawio file. This script produces a structured intermediate representation (IR) that captures geometry, styling, and connectivity. The four dials then act as transformation filters applied to this IR before final rendering.

The canonical reference for these controls resides in commands/import-drawio.md, while detailed user-facing documentation appears in skills/diagram-design/references/import-drawio.md.

Summary

• Format selects the output media type: HTML, SVG, PNG, or HTML+PNG
• Size sets canvas dimensions using presets like slide-16x9 or doc-inline
• Detail controls fidelity through faithful, balanced, or simplified modes
• Audience adjusts styling complexity for engineer, mixed, or executive viewers
• The drawio_extract.py script parses source files before the dials transform the intermediate representation
• Configuration occurs via command-line arguments to the import-drawio command

Frequently Asked Questions

What are the four dials that shape draw.io imports?

The four dials are Format (output media type), Size (canvas dimensions), Detail (visual fidelity level), and Audience (target styling profile). These parameters control how the Diagram-Design skill transforms source .drawio files into final editorial assets.

How do I export a draw.io diagram as both HTML and PNG?

Use the Format dial with the html+png value. For example: /diagram-design:import-drawio diagram.drawio --format=html+png. This generates both a web-ready vector version and a raster image simultaneously.

What is the difference between the faithful and simplified detail settings?

The faithful setting preserves every element from the original diagram, maintaining maximum information density. The simplified setting filters out minor elements to create a high-level overview suitable for executive presentations or quick reference materials.

Where does the extraction logic for draw.io files reside?

The extraction logic is implemented in skills/diagram-design/scripts/drawio_extract.py within the cathrynlavery/diagram-design repository. This script decompresses the .drawio payload and creates a structured intermediate representation that the four dials subsequently transform.

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