# The Four Dials for Importing Diagrams in Diagram-Design: Format, Size, Detail, and Audience > Master Diagram-Design's four import dials Format Size Detail and Audience to control diagram rendering saving and presentation for optimal results. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: how-to-guide - Published: 2026-08-18 --- **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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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: ```bash 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: ```bash 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) — Contains the pre-draw checklist validating dial configuration (lines 525-532). - [`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) — CLI documentation consuming the four dials. - [`prompts/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/prompts/import-mermaid.md) and [`prompts/export-diagram.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md): `html` for Format, `doc-inline` for Size, `balanced` for Detail, and `mixed` for Audience. However, the [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md) (lines 44-52), including mappings for documents, slides, and social media cards.