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

The degradation ladder is a deterministic six-step trimming process defined in 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【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.
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:

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:

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

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

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

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