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

> Understand the faithful detail level for complex imports. Learn how it splits diagrams over 24 nodes into an overview and zone-specific details for clarity.

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

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) enforces these rules proactively. Requesting `--detail=faithful` for an oversized source produces an explicit rejection with remediation guidance:

```sh

# 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):

```python
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:

```sh
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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Core specification of detail levels, zoning rules, and connector constraints |
| [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md) | Node budgets, edge limits, and fidelity ledger schema |
| [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) | CLI behavior enforcing faithful constraints |
| [`scripts/verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.