How the 'Faithful' Detail Level Works for Complex Imports Over 24 Nodes

The faithful detail level caps single-canvas diagrams at 24 nodes and enforces automatic splitting into an overview diagram plus zone-specific detail diagrams when imports exceed this limit.

The faithful detail level represents the highest-fidelity rendering mode in the diagram-design tool. It preserves every distinct component from source files including ports, protocols, and version labels—yet it imposes strict structural rules when node counts climb. This article explains exactly how the system handles complex imports that breach the 24-node threshold, based on the source code in cathrynlavery/diagram-design.

Node Budget and Layout Constraints

At faithful detail, the renderer operates within a hard node budget defined in skills/diagram-design/references/output-spec.md:

• Maximum 24 nodes per single canvas
• Maximum 32 edges per node
• All ports, protocols, and versions retained

These constraints ensure the resulting diagram remains legible at standard presentation sizes. The system validates these limits before any drawing begins—if your import exceeds them, the tool refuses a monolithic render and triggers an alternative workflow.

Zoning Requirements for Medium Complexity

Once a diagram crosses 9 nodes, layout rules tighten. Every node must reside inside a labeled zone with these specifications:

• 2–4 zones total
• Thin borders with paper-2 fill
• Uppercase zone label positioned at top-left

This zoning requirement prevents the "wiring-dump" effect—where dense interconnections obscure readability. The rule is encoded in skills/diagram-design/SKILL.md under the faithful-level specification. For diagrams between 10–24 nodes, zoning occurs on a single canvas. Beyond 24, the structure fundamentally changes.

The Splitting Rule: Overview Plus Detail Diagrams

When node count exceeds 24, the faithful level cannot satisfy its fidelity promise on one canvas. The system generates two output types:

1. Overview diagram (<base>-overview.html): Each zone collapses to a single node using the balanced grammar—simpler, relationship-focused, and scannable
2. Detail diagrams (<base>-<zone>.html): One per zone containing full node sets with complete port and protocol fidelity

File naming follows strict conventions so downstream tools can discover related outputs programmatically.

Connector Rules Persist Across Splits

Even during split workflows, constraints from §6 of SKILL.md remain active:

• No overlapping edges
• Maximum 5 connectors per node

If a zone's internal layout cannot satisfy these rules, the system escalates—potentially triggering sub-zone splits or flagging the diagram as unrenderable at faithful detail.

Fidelity Ledger Reporting

Every split operation produces a fidelity ledger: a structured log documenting merged, collapsed, or dropped elements. This ledger emits to console output after file generation completes, providing audit trails for compliance or debugging.

CLI Enforcement of Faithful Limits

The command-line interface in commands/import-mermaid.md enforces these rules proactively. Requesting --detail=faithful for an oversized source produces an explicit rejection with remediation guidance:

# Attempt to import a 30-node Mermaid diagram at faithful detail

diagram-design:import platform.mmd --detail=faithful --size=slide-16x9 --output=out/diagram

The tool responds:

Faithful detail cannot be rendered on a single canvas for 30 nodes.
I will generate an overview diagram and one detail diagram per zone.

This behavior prevents silent degradation—users understand exactly what fidelity trade-offs occur.

Internal Rendering Logic

The decision flow resides in the diagram-design core (simplified pseudo-code):

if detail == "faithful":
    if node_count > 24:
        # Trigger split workflow

        generate_overview(diagram, zone_summary=True)
        for zone in zones:
            generate_detail(diagram, zone=zone)
    elif node_count > 9:
        # Single canvas with mandatory zoning

        layout = zone_layout(diagram)
    else:
        # Simple faithful render, no zoning required

        layout = simple_faithful_layout(diagram)

The zone_layout() function assigns nodes to 2–4 zones based on connectivity clustering, while generate_overview() applies the balanced grammar to zone abstractions.

Output File Structure

A typical split workflow produces this directory layout:

out/
├── diagram-overview.html      # balanced grammar, zone-as-node view

├── diagram-zoneA.html         # faithful detail: zone A contents

├── diagram-zoneB.html         # faithful detail: zone B contents

└── diagram-zoneC.html         # faithful detail: zone C contents

Each HTML file embeds the diagram plus metadata headers. The fidelity ledger appears only in console output, not embedded files, to keep renders lightweight.

Key Source Files

Understanding the faithful detail implementation requires reference to these canonical sources:

File	Purpose
skills/diagram-design/SKILL.md	Core specification of detail levels, zoning rules, and connector constraints
skills/diagram-design/references/output-spec.md	Node budgets, edge limits, and fidelity ledger schema
commands/import-mermaid.md	CLI behavior enforcing faithful constraints
scripts/verify-drawio-import.py	Validation script checking faithful conditions for draw.io sources

Summary

• Faithful detail preserves complete fidelity but caps single-canvas diagrams at 24 nodes
• Medium diagrams (10–24 nodes) require mandatory zoning with 2–4 labeled zones
• Complex imports (>24 nodes) trigger automatic splitting into overview plus zone-specific detail diagrams
• Fidelity ledgers document every transformation for audit purposes
• CLI proactively rejects impossible faithful requests and proposes alternatives

Frequently Asked Questions

Can I force faithful detail on a 50-node diagram without splitting?

No. The tool rejects this request explicitly. The import-mermaid.md specification mandates CLI enforcement: attempting --detail=faithful on oversized sources produces an error message explaining the 24-node limit and offering the split workflow instead.

What determines how nodes are assigned to zones?

The zone_layout() function clusters nodes by connectivity patterns, aiming to minimize cross-zone edges. While the algorithm isn't fully specified in public documentation, SKILL.md requires 2–4 zones with clear structural boundaries.

Does the overview diagram use faithful detail?

No. The overview employs the balanced grammar—a distinct detail level optimized for relationship visibility over component fidelity. This deliberate downshift makes the multi-zone structure comprehensible at a glance.

Where does the fidelity ledger appear?

The ledger emits to console output after file generation completes. It does not appear inside the generated HTML files, keeping renders lightweight while providing machine-parseable transformation records for debugging or compliance pipelines.

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