# Using the Four Dials: Format, Size, Detail, and Audience for Diagram-Design Imports

> Master diagram-design imports with four dials: Format, Size, Detail, and Audience. Configure output, dimensions, density, and tone before redrawing for optimal results. Learn more.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-09-09

---

**The four dials—Format, Size, Detail, and Audience—are pre-import configuration parameters in cathrynlavery/diagram-design that determine output file type, canvas dimensions, information density, and lexical tone before any redrawing occurs.**

Diagram-Design is a self-contained skill that transforms raw architecture specifications and flow diagrams into editorial-quality deliverables. The import workflow centers on four configurable dials defined in [[`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md) that must be set before processing draw.io files or Mermaid source blocks. Selecting these parameters triggers a deterministic pipeline that extracts structural intent, applies degradation rules, and renders brand-consistent SVG outputs through a rigorous taste-gate validation.

## Understanding the Four Dials

The four dials represent the primary control surfaces for diagram generation. According to the source code in `cathrynlavery/diagram-design`, these settings are applied immediately after extraction by [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) or [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) and before the rendering phase loads [`assets/template.html`](https://github.com/cathrynlavery/diagram-design/blob/main/assets/template.html). Each dial maps to a specific technical concern in the output specification.

### Format Dial

The **Format** dial controls the output file type delivered to the user. Valid options include `html`, `svg`, `png`, or combined formats like `html+png`.

When set to `html` (the default), the skill generates a self-contained HTML file embedding the SVG directly for web integration. Selecting `svg` produces a standalone vector file for design tool handoffs, while `png` renders raster images suitable for slide decks. The format selection determines which rendering branch executes in the pipeline and influences whether the optional motion template ([`template-motion.html`](https://github.com/cathrynlavery/diagram-design/blob/main/template-motion.html)) loads for animated outputs.

### Size Dial

The **Size** dial fixes the canvas dimensions and SVG `viewBox` while enforcing a 4-pixel grid for typographic consistency. The default preset is `doc-inline`, which sets a viewBox of `0 0 960 600` optimized for documentation embeds.

Alternative presets adjust the aspect ratio and pixel density for specific contexts such as social cards or printed handouts. This dial directly configures the spacing ramp for node labels, ensuring that text hierarchy remains legible across different physical scales without manual adjustment.

### Detail Dial

The **Detail** dial governs information density through a systematic degrade ladder applied to the extracted graph structure. The available levels are `faithful`, `balanced` (default), and `simplified`.

The degrade ladder executes the following elimination sequence: decorative cells are removed first, followed by exact duplicates, leaf clusters, degree-1 sinks, and finally cross-cutting infrastructure nodes. The `balanced` setting applies an intermediate number of these cuts, while `simplified` aggressively prunes to show only core architectural relationships. After processing, the skill automatically emits a fidelity ledger documenting which nodes were merged or dropped during import.

### Audience Dial

The **Audience** dial adjusts the vocabulary and phrasing used in node names, edge labels, and sub-labels without inventing new facts. Options include `engineer`, `mixed` (default), and `executive`.

When set to `executive`, the skill substitutes technical jargon for business-friendly language that aligns with stakeholder mental models. The `engineer` setting preserves precise technical terminology, while `mixed` strikes a balance suitable for cross-functional teams. This lexical transformation occurs during the rendering phase, ensuring the underlying structural data remains consistent regardless of presentation tone.

## The Import Pipeline Architecture

The four dials operate within a three-stage pipeline implemented in the skill's core scripts. First, extraction scripts ([`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) for draw.io files or [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) for Mermaid blocks) parse the source into an intermediate representation. Second, the dial settings are applied to shape the diagram according to the specifications in [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md), filtering content and adjusting view parameters. Finally, the system renders the output through [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py), which enforces the pre-output checklist defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) (the taste-gate) to ensure accessibility compliance and connector consistency before file generation.

The design system references [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) as a single source of truth for brand tokens, allowing the dials to propagate color and typography decisions automatically across all output variants.

## Practical Import Examples

Import a draw.io file for executive presentation with simplified detail:

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

```

Import Mermaid from a Markdown file using balanced detail for mixed technical audiences:

```bash
/diagram-design:import-mermaid README.md \
    --diagram=all \
    --detail=balanced \
    --audience=mixed

```

Export a generated diagram to PNG at 2x scale for high-DPI displays:

```bash
/export-diagram output/architecture.html --png-only --scale=2

```

Run the taste-gate validator manually for CI integration:

```bash
python3 skills/diagram-design/scripts/self_check.py output/architecture.html

```

Onboard brand tokens before generating diagrams:

```bash
/diagram-design:onboard https://mycompany.com

```

## Summary

- The **Format** dial selects output file types (`html`, `svg`, `png`) and determines rendering pathways.
- The **Size** dial configures SVG `viewBox` dimensions and typographic grids, defaulting to `doc-inline` (960×600).
- The **Detail** dial applies a degrade ladder (decorative cells → duplicates → leaf clusters → sinks → infrastructure) with levels `faithful`, `balanced`, or `simplified`.
- The **Audience** dial swaps vocabulary between `engineer`, `mixed`, and `executive` without altering underlying structure.
- The pipeline extracts source data via [`drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/drawio_extract.py) or [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py), applies dial configurations, and validates output through [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py) against the taste-gate requirements in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md).

## Frequently Asked Questions

### What are the default settings for the four dials?

The default configuration uses `html` for Format, `doc-inline` for Size, `balanced` for Detail, and `mixed` for Audience. These presets generate web-embeddable HTML files with 960×600 viewBox dimensions, moderate information density, and cross-functional vocabulary suitable for general documentation.

### How does the Detail dial determine which content survives the import?

The Detail dial implements a deterministic degrade ladder defined in the source code. It first eliminates decorative cells, then exact duplicates, followed by leaf clusters, degree-1 sinks, and finally cross-cutting infrastructure. The `faithful` setting skips most cuts, `balanced` applies intermediate filtering, and `simplified` executes the full ladder. The system generates a fidelity ledger reporting exactly which nodes were removed or merged.

### Can I export diagrams to multiple formats simultaneously?

Yes. Setting the Format dial to `html+png` generates both a self-contained HTML file and a raster PNG image in a single execution. Alternatively, you can generate HTML initially and use the `/export-diagram` command with `--svg-only` or `--png-only` flags to create additional formats from the existing output file without re-processing the source.

### How does the skill ensure quality across different dial configurations?

Every generated diagram must pass the taste-gate checklist defined in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), enforced by [`self_check.py`](https://github.com/cathrynlavery/diagram-design/blob/main/self_check.py). This validator checks connector spacing, accessibility attributes, and brand consistency against [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) regardless of the specific dial settings used during import. The validator can run manually in CI pipelines or automatically during the standard render phase.