Import Detail Level Options in diagram-design: Faithful, Balanced, and Simplified Explained

The diagram-design tool offers three import detail levels—faithful (up to 24 nodes), balanced (up to 12 nodes), and simplified (up to 7 nodes)—that control how much complexity is retained when redrawing source diagrams.

Importing external diagrams into cathrynlavery/diagram-design requires choosing an import detail level that matches your audience and complexity constraints. The --detail flag configures whether the engine preserves every node from the source or abstracts the view down to critical elements only.

Understanding the Three Import Detail Levels

The source specification in skills/diagram-design/SKILL.md defines three presets, each with strict node budgets and layout behaviors that determine how the tool redraws imported diagrams.

Faithful (Up to 24 Nodes)

Use faithful when you need a complete, one-to-one representation of the source diagram. This level maintains exhaustive component mapping but enforces specific complexity thresholds:

• 1–9 nodes: Rendered as-is without zoning.
• 10–24 nodes: Automatically zoned (grouped into logical zones) to manage visual density.
• >24 nodes: The engine splits output into an overview file plus separate detail files.

According to the skill definition, faithful is the only level that can exceed the standard 9-node budget, provided the diagram is zoned or split accordingly【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/SKILL.md#L555-L558】.

Balanced (Up to 12 Nodes)

Balanced is the default import detail level. It produces a medium-complexity view suitable for engineering audiences:

• Merges or omits duplicate and low-value nodes.
• Stays within the 12-node standard budget.
• Never triggers zoning or file splitting.

This level strikes a compromise between completeness and readability for most technical documentation.

Simplified (Up to 7 Nodes)

Select simplified for executive briefings or high-level overviews where speed of comprehension matters more than exhaustive detail:

• Collapses clusters and merges non-critical elements.
• Caps representation at 7 nodes maximum.
• Produces highly abstracted views emphasizing only the most critical architectural components.

How the Engine Enforces Node Budgets

The complexity budget engine applies different rules based on your selected level. When --detail=faithful encounters more than 9 nodes, the layout engine activates zoning logic to group related nodes into logical zones. If the node count exceeds 24, the engine automatically partitions the output into multiple files: an overview file containing the high-level zones and separate detail files containing the full node expansion【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/SKILL.md#L555-L558】.

Balanced and simplified levels operate under stricter limits (≤12 and ≤7 nodes respectively) and do not invoke zoning or splitting mechanisms. These constraints are documented in the output specification at references/output-spec.md, which lists the three options alongside their node limits【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/SKILL.md#L549-L556】.

CLI Usage Examples

Specify the import detail level using the --detail flag on any import command.

Importing Mermaid Diagrams

# Faithful: Full detail with automatic zoning/splitting

diagram-design:import-mermaid architecture.mmd --detail=faithful --format=html

# Balanced: Default medium complexity (≤12 nodes)

diagram-design:import-mermaid architecture.mmd --detail=balanced --format=svg

# Simplified: Executive overview (≤7 nodes)

diagram-design:import-mermaid architecture.mmd --detail=simplified --format=png

Importing Draw.io Files

# Faithful with zoning (if >9 nodes) and split (if >24 nodes)

diagram-design:import-drawio system.drawio --size=slide-16x9 --detail=faithful

# Balanced for documentation inline

diagram-design:import-drawio system.drawio --size=doc-inline --detail=balanced

# Simplified for wide executive slides

diagram-design:import-drawio system.drawio --size=doc-wide --detail=simplified

Importing Excalidraw Sketches

# Verify node count first, then import with balanced detail

python3 scripts/verify-excalidraw-import.py sketch.excalidraw
diagram-design:import-excalidraw sketch.excalidraw --detail=balanced

Source Code References

The import detail level behavior is defined across these repository files:

• skills/diagram-design/SKILL.md: Defines node budgets, zoning logic, and split behavior for faithful imports【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/SKILL.md#L549-L558】.
• prompts/import-mermaid.md: Documents the --detail flag syntax for Mermaid sources.
• prompts/import-excalidraw.md: Documents the same flag for Excalidraw imports.
• commands/import-drawio.md: Explains detail-level handling, zoning triggers, and file splitting for Draw.io inputs.
• references/output-spec.md: Lists the three detail options with their defaults and limits.

Summary

• Faithful: Up to 24 nodes, zones above 9, splits above 24. Use for complete architectural accuracy.
• Balanced: Up to 12 nodes, default setting. Use for clear technical documentation.
• Simplified: Up to 7 nodes. Use for executive overviews and high-level communication.
• Set via --detail flag on import-mermaid, import-drawio, or import-excalidraw commands.
• Zoning and splitting only occur at the faithful level when exceeding 9 and 24 nodes respectively.

Frequently Asked Questions

What is the default import detail level?

The default import detail level is balanced. If you omit the --detail flag from any import command, the engine automatically applies the balanced preset with its 12-node budget.

When should I use the faithful detail level?

Use faithful when you require an exhaustive representation of the source diagram and the node count does not exceed 24 (or you are prepared to manage split output files). This is ideal for full-scale architecture diagrams where every component must be preserved in a one-to-one mapping with the source.

What happens if a faithful import exceeds 24 nodes?

When a faithful import exceeds 24 nodes, the engine automatically splits the output into multiple files: one overview file containing the zoned high-level structure, and one or more detail files containing the complete node expansion【/cache/repos/github.com/cathrynlavery/diagram-design/main/skills/diagram-design/SKILL.md#L555-L558】.

Can I use different detail levels for different output formats?

Yes. The --detail flag operates independently of the --format flag. You can generate a faithful HTML export, a balanced SVG, or a simplified PNG from the same source file by adjusting both flags accordingly in the CLI command.

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