# What the Four Import Dials Control in diagram-design: Format, Size, Detail, and Audience > Master diagram design by understanding the four import dials: format, size, detail, and audience. Control output file type, canvas dimensions, element budget, and lexical style effortlessly. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: deep-dive - Published: 2026-08-19 --- **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`](https://github.com/cathrynlavery/diagram-design/blob/main/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 `` 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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 ```bash # 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 ```bash # 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 ```bash # 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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md) — Defines the dials, their defaults, and their effects on deliverables. - [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) — Contains the taste-gate checklist that validates the dials. - [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) — CLI documentation for the Mermaid import command. - [`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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 `` node, as described in [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) § 9. The gate ensures all four values are set and consistent before the redraw begins.