# Understanding the Four Dials (Format, Size, Detail, Audience) in the Diagram-Design Import Process

> Master the four dials format size detail audience in cathrynlavery/diagram-design import process. Control output type dimensions density and labeling depth for better diagrams.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-09-13

---

**The four dials—Format, Size, Detail, and Audience—must be configured before rendering to control output file type, canvas dimensions, node density, and technical labeling depth in cathrynlavery/diagram-design.**

When importing diagrams into the `cathrynlavery/diagram-design` system, these four configurable "dials" determine how source material is transformed into the final deliverable. They must be resolved before the diagram is redrawn because they affect the final file format, canvas viewBox, node density, and vocabulary choices. The complete specification for these parameters resides in [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md)【5†L5-L10】.

## The Four Dials Explained

### Format – Controlling Output File Types

The **Format** dial determines the file type the diagram is saved as and where the output ultimately lands. Valid options include `html`, `svg`, `png`, or combined formats such as `html+png`.

- **Default value**: `html`【5†L7-L8】
- **Behavior**: Non-HTML formats are generated from the HTML base via an export procedure【5†L20-L25】
- **CLI flag**: `--format`

### Size – Setting Canvas Dimensions and Reading Distance

The **Size** dial controls the SVG `viewBox` dimensions, associated PNG pixel dimensions, and the intended reading distance. It uses presets that map to typical destinations such as documentation, slide decks, or social cards.

- **Default value**: `doc-inline` (maps to a 960×600 viewBox and 1920×1200 PNG output)【5†L8-L9】【5†L44-L52】
- **Available presets**: `doc-inline`, `slide-16x9`, `social-og`, `fit`, and others defined in the specification【5†L44-L53】
- **CLI flag**: `--size`

### Detail – Managing Node and Edge Density

The **Detail** dial acts as a "count" parameter that limits how much of the source diagram is retained versus collapsed. It controls the survival of nodes, edges, and sub-labels through explicit numerical caps.

- **Default value**: `balanced`【5†L9-L10】
- **Available levels**:
  - `faithful`: Retains maximum node/edge count
  - `balanced`: Moderate retention (default)
  - `simplified`: Aggressive collapse with strict caps on nodes, edges, and sub-labels【5†L88-L92】
- **CLI flag**: `--detail`

### Audience – Adjusting Technical Depth

The **Audience** dial adjusts the technical depth of labeling independently from the Detail level. It modifies node names, sub-labels, and edge verbs to match the expertise of the target readers.

- **Default value**: `mixed`【5†L9-L10】
- **Available levels**:
  - `engineer`: Technical terminology, precise edge verbs
  - `mixed`: Balanced technical depth
  - `executive`: Simplified naming conventions for high-level stakeholders【5†L20-L25】
- **CLI flag**: `--audience`

## How the Dials Interact

The four dials operate independently but must all be resolved before the diagram is drawn:

1. **Format** dictates the deliverable destination, determining whether the pipeline produces self-contained HTML, raw SVG, or raster PNG assets.

2. **Size** selects a preset that directly sets the SVG `viewBox` attribute and corresponding PNG pixel dimensions. For example, the `doc-inline` preset creates assets optimized for embedded documentation.

3. **Detail** performs a quantitative filter, limiting how many nodes and edges survive the import process based on the selected level's predefined caps.

4. **Audience** performs a qualitative transformation, changing what content is called rather than how much content survives.

The [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) file contains a validation checklist that verifies all four dials are explicitly set or correctly defaulted before the drawing phase begins【5†L68-L73】【5†L525-L532】.

## Practical CLI Examples

The following command-line invocations demonstrate how to set each dial when importing Mermaid or Draw.io sources. The flags correspond directly to the four dials defined in the specification.

```bash

# Import a Mermaid file for a slide deck, high-detail, engineered audience.

diagram-design:import-mermaid diagrams/architecture.mmd \
  --format=png \
  --size=slide-16x9 \
  --detail=faithful \
  --audience=engineer \
  --output=out/architecture

```

```bash

# Import a Draw.io file for a blog post, moderate detail, mixed audience,

# generating both HTML and PNG outputs.

diagram-design:import-drawio diagrams/infra.drawio \
  --format=html+png \
  --size=doc-inline \
  --detail=balanced \
  --audience=mixed \
  --output=out/infra

```

These examples map the CLI flags to the dials as follows:

| Flag | Corresponding Dial | Example Values |
|------|-------------------|----------------|
| `--format` | Format | `html`, `svg`, `png`, `html+png` |
| `--size` | Size | `doc-inline`, `slide-16x9`, `social-og`, `fit` |
| `--detail` | Detail | `faithful`, `balanced`, `simplified` |
| `--audience` | Audience | `engineer`, `mixed`, `executive` |

## Summary

- The **four dials** (Format, Size, Detail, Audience) control every aspect of the import process in `cathrynlavery/diagram-design`.
- **Defaults are** `html` (Format), `doc-inline` (Size), `balanced` (Detail), and `mixed` (Audience).
- Configuration specifications live in [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md), while validation occurs in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md).
- All dials must be resolved via CLI flags or inference before the diagram rendering pipeline executes.

## Frequently Asked Questions

### What are the default values for the four dials in diagram-design?

The default configuration uses `html` for Format, `doc-inline` for Size, `balanced` for Detail, and `mixed` for Audience. These values 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) lines 7 through 10 and are applied when explicit values are not provided via CLI flags.

### How does the Detail dial differ from the Audience dial?

The **Detail** dial is a quantitative filter that limits how many nodes, edges, and sub-labels survive the import process through explicit numerical caps. The **Audience** dial is a qualitative transformation that changes the naming conventions, edge verbs, and technical depth of the labels without removing content. They operate independently to control density versus terminology.

### Can I export to multiple formats simultaneously?

Yes, the **Format** dial accepts combined values such as `html+png`. According to the export procedure in [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md), non-HTML formats are generated from the HTML base, allowing the pipeline to produce both interactive HTML and static raster assets in a single invocation.

### Where is the configuration validated in the codebase?

The four dials are validated against a checklist in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) before the drawing phase begins. This checkpoint ensures that Format, Size, Detail, and Audience have been explicitly requested, inferred from the destination, or defaulted correctly according to the specification.