# How the Output-Spec Format/Size/Detail Degradation Ladder Works in Diagram-Design

> Understand the output-spec format size detail degradation ladder in diagram-design. This six-step process automatically reduces diagram complexity to fit your budget.

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

---

**The degradation ladder is a deterministic six-step trimming process defined in [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md) that automatically reduces diagram complexity—from removing decorative cells to collapsing leaf clusters—until the node and edge count fits within the budget set by the Format, Size, Detail-Level, and Audience dials.**

The `cathrynlavery/diagram-design` repository implements a strict **output-spec** system to ensure every technical diagram meets specific delivery constraints. Four configurable dials—**Format**, **Size**, **Detail Level**, and **Audience**—define the canvas dimensions, file type, complexity budget, and terminology before any drawing begins. When source material exceeds the node or edge limits defined by these dials, the system applies a **degradation ladder** to intelligently prune elements while preserving the core architectural narrative, recording all omissions in a fidelity ledger.

## The Four Dials Controlling Diagram Output

According to [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md)【output‑spec.md†L5-L13】, all diagrams are generated according to four dials set before the drawing phase. These dials determine the deliverable characteristics and complexity budget.

### Format Dial

The **Format** dial determines the file type emitted and the source of truth for the diagram. As implemented in the diagram-design skill, HTML serves as the mandatory single source of truth; SVG and PNG are derived via extraction【output‑spec.md†L25-L26】.

- **`html`** (default): Generates a self-contained `.html` file retaining headers, summary cards, footers, and live fonts.
- **`svg`**: Exports a stand-alone `.svg` containing the `<svg>` node and vector text, dropping the editorial wrapper and font substitution.
- **`png`**: Produces a raster image at a chosen device-scale factor, sacrificing vector editability for pixel-perfect rendering.
- **`html+png`**: Generates both HTML and PNG deliverables.

Hand-authoring SVG is prohibited because the HTML must pass the taste-gate defined in SKILL §9.

### Size Dial

The **Size** dial configures the SVG `viewBox`, PNG pixel dimensions via `device_scale_factor`, and the type ramp (scaling for fonts and UI elements). All presets follow the grid rule in SKILL §7, using dimensions divisible by 4【output‑spec.md†L60-L71】.

Key presets include:
- **`doc-inline`** (default): `0 0 960 600` viewBox (8:5 aspect), PNG @2x yields 1920×1200, using standard type ramp for body-width embeddings.
- **`doc-wide`**: `0 0 1280 720` viewBox (16:9), PNG @2x yields 2560×1440 for full-width documentation.
- **`slide-16x9`**: `0 0 1280 720` viewBox with presentation type ramp for deck slides.
- **`slide-4x3`**: `0 0 1024 768` viewBox (4:3), PNG @2x yields 2048×1536 for legacy templates.
- **`social-og`**: `0 0 1200 632` viewBox (~1.9:1), PNG @2x yields 2400×1264 for link-preview cards.
- **`social-square`**: `0 0 1080 1080` viewBox (1:1), PNG @2x yields 2160×2160 for feed carousels.
- **`print-a4-landscape`**: `0 0 1120 792` viewBox (~1.41:1), PNG @3x yields 3360×2376 with print type ramp.
- **`print-letter-landscape`**: `0 0 1056 816` viewBox (~1.29:1), PNG @3x yields 3168×2448.
- **`fit`**: Derives viewBox from content with any aspect ratio, PNG @2x, using standard type ramp for vector hand-offs.

Every preset enforces safe-area margins of 40px outer margin and 60px legend strip【output‑spec.md†L76-L81】.

### Detail-Level Dial

The **Detail Level** dial controls the maximum node and edge budget, determining how many source elements survive the import transformation. This is a count-based dial, not a styling dial【output‑spec.md†L16-L23】.

- **`faithful`** (詳細): Budget of ≤24 nodes (zoned) and ≤32 edges. Preserves every distinct component, port, protocol, and version. Exceeds the standard complexity budget in SKILL §7, requiring mandatory zoning for >9 nodes and mandatory splitting when >24 nodes【output‑spec.md†L94-L100】.
- **`balanced`** (default): Budget of ≤12 nodes and ≤16 edges. Preserves core story components; technical sub-labels appear on ≤4 nodes only. Collapses leaf clusters and duplicates.
- **`simplified`** (簡略): Budget of ≤7 nodes and ≤9 edges. Preserves only high-level capabilities and sequence; omits infrastructure and sub-labels entirely.

### Audience Dial

Unlike the detail dial, the **Audience** dial controls terminology and phrasing without affecting the node budget. It determines how surviving elements are labeled【output‑spec.md†L16-L23】.

- **`engineer`**: Uses exact service names, protocols, ports, versions, and detailed verbs like `POST /v2/orders`. Disallows vague terminology.
- **`mixed`** (default): Expands acronyms, uses plain verbs (`verifies`, `writes`), and omits ports and internal codenames unless technically decisive.
- **`executive`**: Labels nodes as capabilities and outcomes, uses business verbs (`approves`, `pays out`), and disallows vendor names and infrastructure terminology.

## The Six-Step Degradation Ladder

When source material exceeds the node or edge budget defined by the Detail-Level dial, the system executes a strict **degradation ladder** in sequential order until the budget is satisfied【output‑spec.md†L101-L110】.

1. **Decorative cells**: Removes sticky notes, free-floating text, title blocks, watermarks, and source legends. At most two decorative elements may survive as annotation callouts per [`primitive-annotation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/primitive-annotation.md).
2. **Exact duplicates**: Collapses identical workers, replicas, or shards into a single node with a multiplicative label (e.g., `Worker × N`).
3. **Leaf clusters**: Collapses containers whose children are all leaves into the parent container node (e.g., consolidating three boxes into "Core Services").
4. **Degree-1 sinks**: Removes monitoring hooks, log buckets, and archive tiers that do not affect the core story.
5. **Cross-cutting infrastructure**: Removes logging, metrics, secrets, and CI pipelines. At `simplified` level, these disappear automatically; at `balanced`, at most one infrastructure node survives only if the diagram's purpose concerns that infrastructure.
6. **Split-over**: If the diagram remains over budget after steps 1–5, the system splits it into an **overview** diagram (zones as nodes, using `balanced` grammar) and separate **detail** diagrams per zone. Splitting is preferred to further shrinking【output‑spec.md†L106-L110】.

All cuts made during steps 2–6 are recorded in the **fidelity ledger**, ensuring users know exactly what has been omitted【output‑spec.md†L12-L13】.

## Configuring Dials via Command Line

The four dials map directly to command-line flags when invoking diagram imports. Below are practical examples using the `diagram-design` CLI.

Generate a slide-ready PNG with faithful detail for engineers:

```bash
diagram-design import-drawio my-diagram.drawio \
  --format png \
  --size slide-16x9 \
  --detail faithful \
  --audience engineer

```

Produce an embeddable HTML diagram for a README using balanced defaults:

```bash
diagram-design import-mermaid my-diagram.mmd \
  --size doc-inline

```

Export a social-OG card with simplified detail for a mixed audience:

```bash
diagram-design import-excalidraw my-sketch.excalidraw \
  --format png \
  --size social-og \
  --detail simplified \
  --audience mixed

```

In each example, if `my-diagram.drawio` contains 30 nodes but `--detail balanced` (max 12) is requested, the CLI runs the six-step degradation ladder automatically and emits the fidelity ledger upon completion.

## Summary

- The **output-spec** in [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md) governs all diagram generation through four dials: Format, Size, Detail Level, and Audience.
- **HTML is the single source of truth**; SVG and PNG are derived extractions, not primary sources【output‑spec.md†L25-L26】.
- The **degradation ladder** applies six deterministic steps—decorative removal, duplicate collapsing, leaf collapsing, sink removal, infrastructure pruning, and split-over—to enforce node/edge budgets【output‑spec.md†L101-L110】.
- **Faithful mode** permits up to 24 nodes but requires mandatory zoning for counts exceeding 9 and splitting beyond 24【output‑spec.md†L94-L100】.
- All reductions are tracked in a **fidelity ledger** to maintain transparency about omitted elements【output‑spec.md†L12-L13】.

## Frequently Asked Questions

### What triggers the degradation ladder in diagram-design?

The ladder triggers automatically when the imported source material exceeds the node or edge budget defined by the Detail-Level dial (≤24 nodes for `faithful`, ≤12 for `balanced`, or ≤7 for `simplified`). The system applies the six-step sequence described in [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md)【output‑spec.md†L101-L110】 until the diagram fits within budget or requires splitting into overview and detail diagrams.

### Can I bypass the degradation ladder to force a complex diagram into a smaller format?

No. The degradation ladder is mandatory and deterministic. You cannot disable it, but you can select the `faithful` detail level to accommodate up to 24 nodes (with mandatory zoning for >9 nodes) or allow the system to split the diagram into an overview plus detail diagrams via the **split-over** step rather than further shrinking content.

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

The **Detail-Level** dial controls how many nodes and edges survive (the complexity budget), while the **Audience** dial controls the terminology and phrasing used for labels after the detail level has been applied. For example, setting `--audience engineer` keeps technical ports and protocols in labels, but only if the node itself survived the detail-level degradation【output‑spec.md†L16-L23】.

### Why must HTML be generated before SVG or PNG?

According to [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md), HTML serves as the mandatory single source of truth for the taste-gate (SKILL §9). The workflow always generates HTML first; SVG and PNG are later extracted via the export pipeline【output‑spec.md†L25-L26】. This ensures consistency across formats and prevents divergence between vector and raster outputs.