What Target Density Is Recommended for Diagrams Generated by diagram-design?

Diagram-design recommends a target density of 4/10 to keep diagrams technically complete without excessive clutter.

The diagram-design repository, authored by Cathryn Lavery, enforces this density standard through its core skill definition. When diagrams exceed roughly nine nodes, the tool recommends splitting into multiple diagrams rather than increasing density further.

Where the 4/10 Target Density Is Defined

The primary source for this recommendation lives in [skills/diagram-design/SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md). This file establishes the "target density" rule as a fundamental constraint for all diagram generation.

The same 4/10 recommendation appears in the project's [README.md](https://github.com/cathrynlavery/diagram-design/blob/main/README.md), ensuring users encounter this guideline immediately upon exploring the repository.

How Target Density Affects Diagram Generation

The 4/10 density value serves as a default threshold across the diagram-design workflow. The CLI tool respects this value automatically, though it can be overridden when necessary.

Default Diagram Generation (4/10 Density)

Run the standard export command to generate diagrams using the recommended target density:

diagram-design export-diagram --input src/example.mmd --output diagram.svg

This applies the default 4/10 density defined in the skill configuration.

Overriding Target Density for Specific Use Cases

When higher information density is required, override via CLI flag:

diagram-design export-diagram \
  --input src/example.mmd \
  --output diagram.svg \
  --target-density 6/10

The --target-density parameter accepts fractional values and clamps them to the allowed operational range.

Automatic Splitting for Large Diagrams

When node count exceeds nine, the tool automatically partitions output to maintain near-4/10 density:

diagram-design export-diagram \
  --input src/large-graph.mmd \
  --output diagram-part1.svg diagram-part2.svg

Rather than compressing additional nodes into a single diagram, diagram-design creates separate files to preserve readability.

Related Configuration and Verification Files

• commands/export-diagram.md — Documents CLI options affecting density calculations, including override behaviors.

• scripts/verify-beeswarm.py — Contains verification logic that checks density cues such as visual thickness and over-printing ratios against the target density standard.

Summary

• diagram-design target density: 4/10, defined in skills/diagram-design/SKILL.md.
• Automatic enforcement: CLI defaults to this value; splits diagrams when node count exceeds ~9.
• Override capability: --target-density flag allows temporary adjustments.
• Design rationale: Balances technical completeness with visual clarity, preventing diagram clutter.

Frequently Asked Questions

What happens if I don't specify a target density when running diagram-design?

The CLI automatically applies the 4/10 default defined in SKILL.md. You receive standard density without passing any additional flags.

Can I set a permanent custom target density for my project?

The source analysis does not indicate persistent configuration files for density defaults. You must pass --target-density on each relevant command invocation.

Why does diagram-design split diagrams at nine nodes rather than adjust density?

The 4/10 target density represents an optimal balance between information and legibility. Beyond approximately nine nodes, maintaining this ratio while keeping diagrams readable requires fragmentation rather than compression, according to the skill definition.

Does the verify-beeswarm.py script enforce the 4/10 density rule?

The script checks density-related visual cues including thickness and over-printing, which correlate with the target density standard. It serves as a quality verification mechanism rather than a direct enforcement tool.

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