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

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/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 or mermaid_extract.py and before the rendering phase loads 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) 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 for draw.io files or 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, filtering content and adjusting view parameters. Finally, the system renders the output through self_check.py, which enforces the pre-output checklist defined in SKILL.md (the taste-gate) to ensure accessibility compliance and connector consistency before file generation.

The design system references 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:

/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:

/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:

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

Run the taste-gate validator manually for CI integration:

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

Onboard brand tokens before generating diagrams:

/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 or mermaid_extract.py, applies dial configurations, and validates output through self_check.py against the taste-gate requirements in 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, enforced by self_check.py. This validator checks connector spacing, accessibility attributes, and brand consistency against 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.

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