Diagram-Design Output Specification Details: The Four-Dial System Explained

Diagram-Design uses a four-dial specification—Format, Size, Detail level, and Audience—to control every aspect of generated diagram appearance, enforce quality gates, and produce reproducible, audience-aware deliverables.

The [output-spec.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md) file in the cathrynlavery/diagram-design repository defines the complete output specification details for diagrams. This specification drives the entire generation pipeline, from source parsing through final export.

The Four Dials: Core Output Controls

Every diagram is configured through four parameters set before redrawing the source (Mermaid or draw.io). These dials determine the final deliverable type, canvas dimensions, visual density, and vocabulary style.

Dial	Controls	Default	Key Behavior
Format	Destination file type	html	HTML serves as the source of truth; SVG and PNG are derived via export
Size	viewBox, aspect ratio, PNG scaling	doc-inline	Presets define exact viewBox values and safe margins
Detail level	Node/edge retention strategy	balanced	Hard limits trigger automatic degradation when exceeded
Audience	Vocabulary and label sophistication	mixed	Rewrites node names, sub-labels, and edge captions

Format Options

The Format dial accepts four values:

• html — Primary artifact, editable and source-of-truth
• svg — Vector export derived from HTML
• png — Raster export with configurable scaling
• html+png — Both primary and raster outputs

HTML remains the canonical format. All other formats pass through the export pipeline defined in [export.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md).

Size Presets and viewBox Configuration

The Size dial provides predefined canvas configurations:

• doc-inline — Default for documentation embedding
• slide-16x9 — Presentation-optimized aspect ratio
• social-og — Open Graph image dimensions
• print-a4-landscape — Print-ready layout
• fit — Dynamic sizing to content

Each preset specifies exact viewBox values and safe margins (see §2 of output-spec.md).

Detail Level and the Degrade Ladder

The Detail level dial enforces hard node limits through a degrade ladder (§3):

Level	Node Limit	Use Case
faithful	≤24 nodes	Complete technical accuracy
balanced	≤12 nodes	Default compromise
simplified	≤7 nodes	Executive summaries, social media

When source diagrams exceed the limit, the degrade ladder automatically trims elements according to priority rules while maintaining semantic integrity.

Audience Vocabulary Rewriting

The Audience dial performs label transformation:

• engineer — Preserves technical specificity, nested details, protocol names
• mixed — Moderate abstraction for cross-functional teams
• executive — Capability-focused, outcome-oriented phrasing

This affects node names, sub-labels, and edge captions (see §4 of output-spec.md).

The Output-Spec Checklist

Section 6 of output-spec.md defines a mandatory checklist ensuring:

• All four dials explicitly set
• Generated SVG respects margin constraints
• Type ramps correctly applied
• Node counts within specified limit
• Audience-consistent labeling throughout
• CJK font fallbacks configured
• Fidelity ledger documenting any omitted elements

This checklist is enforced by the skill's pre-output taste gate (SKILL.md §9) and validated by verification scripts.

Verification and Enforcement

Two scripts enforce output specification compliance:

• scripts/verify-drawio-import.py — Validates draw.io source handling
• scripts/verify-mermaid-import.py — Validates Mermaid source handling

These ensure the four-dial system produces valid intermediate representations before rendering.

Complete Generation Pipeline

The output specification integrates with import workflows to drive five sequential stages:

1. Parse source — Mermaid via [import-mermaid.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md) or draw.io via [import-drawio.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md)
2. Apply the four dials — Format, Size, Detail, Audience
3. Run quality gates — Taste gate (SKILL.md §9) and output-spec checklist
4. Render HTML — Primary artifact generation
5. Export derivatives — SVG/PNG production per [export.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/export.md)

Command-Line Usage Examples

These commands demonstrate the four-dial system in practice:

# Redraw a Mermaid diagram for a slide deck with high detail

diagram-design import-mermaid examples/sample-flowchart.mmd \
  --format html \
  --size slide-16x9 \
  --detail faithful \
  --audience engineer \
  --output my-slide

# Produce PNG for a LinkedIn post, letting the tool infer defaults (mixed audience)

diagram-design import-drawio examples/sample-architecture.drawio \
  --format png \
  --size social-og \
  --output linkedin-post

# Export both SVG and PNG from an existing HTML output

diagram-design export-diagram my-slide.html \
  --svg-only \
  --png-only \
  --scale 2 \
  --output final-assets

Each command internally references output-spec.md to set flags, execute degrade-ladder trimming, apply audience-level rewriting, and handle format-specific export logic.

Summary

• Four-dial system (Format, Size, Detail, Audience) controls all output characteristics in output-spec.md
• HTML is source-of-truth; SVG/PNG are derived exports
• Hard node limits (faithful ≤24, balanced ≤12, simplified ≤7) with automatic degradation
• Audience rewriting transforms technical vocabulary to executive language
• Taste gate and verification scripts enforce quality before final output
• Fidelity ledger provides audit trail of any content compromises

Frequently Asked Questions

What file contains the complete output specification for diagram-design?

The authoritative specification lives in [skills/diagram-design/references/output-spec.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md). This file defines the four dials, presets, degrade ladder logic, and the mandatory pre-output checklist.

How does diagram-design handle diagrams that exceed node limits?

The degrade ladder (§3 of output-spec.md) automatically trims elements when source complexity exceeds the selected Detail level's hard limit. The process preserves semantic meaning while reducing visual density, and documents all omissions in a fidelity ledger.

Can I export multiple formats from a single diagram-design command?

Yes. Use html+png for simultaneous generation, or run export-diagram on existing HTML outputs to produce additional derivatives. The --svg-only and --png-only flags allow selective export with --scale controlling PNG resolution.

What determines the vocabulary style in generated diagrams?

The Audience dial rewrites all labels: engineer preserves full technical detail, mixed moderates for cross-functional teams, and executive emphasizes capabilities and outcomes. This transformation applies to node names, sub-labels, and edge captions before final rendering.

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