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

> Explore diagram-design's four-dial output specification: Format, Size, Detail, and Audience. Control diagram appearance and enforce quality gates for reproducible deliverables.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: api-reference
- Published: 2026-08-14

---

**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/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/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md)).

## The Output-Spec Checklist

Section 6 of [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) §9) and validated by verification scripts.

## Verification and Enforcement

Two scripts enforce output specification compliance:

- [`scripts/verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py) — Validates draw.io source handling
- [`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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/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/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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/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:

```bash

# 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

```

```bash

# 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

```

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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)](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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.