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

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【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 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.

# 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

# 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, while validation occurs in 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 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, 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 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.

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