Editorial Diagrams and Visual Explanations

Visual diagrams generated by autonomous AI agents often degrade into generic “rounded-box slop” or illegible spaghetti graphs when unconstrained. Editorial Diagramming treats technical diagrams as precise communication artifacts where every visual token, line, and color must carry semantic meaning.

Pioneered by cathryn lavery in the Diagram Design specification, the approach bridges technical architecture representation and cognitive debt and walkthroughs.

Core Principles

1. Deletion & Target Density

• Deletion over Addition: The quality of a technical schematic is determined by what can be removed without losing core informational structure.
• Merge Coupled Nodes: If two components always operate together, represent them as a single node.
• Remove Obvious Connectors: If spatial proximity and containment convey hierarchy or flow, drop connecting lines to reduce visual noise.
• Density Budget: Aim for a target visual density of 4/10. Graphs with more than 9 nodes should be split into multi-stage overviews or detail sub-diagrams.

2. The Editorial Accent Rule

• Accent color is an informational pointer, not decoration.
• Reserve accent styling for 1–2 focal elements per diagram (e.g. the active bottleneck, the primary decision gate, or the specific step under audit).
• Applying accent color across multiple nodes erases visual hierarchy.

3. Semantic Patterns vs. Visual Layout Grammars

Select the behavioral dynamic before picking the physical layout:

• Behavioral Patterns: Identify whether the system represents a fan-in queue, an unstructured-to-structured pipeline, a governance control catalog, or a paired policy-divergence trace.
• Layout Grammars: Map the behavioral pattern to an appropriate spatial layout (Architecture, Sequence, State Machine, Layer Stack, Flywheel/Loop, Data Flow, Tree, or Matrix).

4. Technical Construction Standards

• 4px Coordinate Grid: All coordinates, dimensions, padding, and gaps must align to a strict 4px grid to prevent the floaty, unanchored appearance common in AI visual generation.
• Self-Contained Deliverables: Diagrams are compiled as standalone HTML files with embedded CSS and inline SVG, ensuring portability and offline rendering.
• Accessibility by Default: Inline SVGs carry role="img", namespaced aria-labelledby, and <title>/<desc> elements providing structural summaries rather than literal shape descriptions.
• Fidelity Ledgers: When importing or redrawing source diagrams (from Mermaid, draw.io, or raw codebases), provide an explicit ledger detailing merged, collapsed, and dropped components.

Related

• cathryn lavery
• cognitive debt and walkthroughs
• agentic engineering patterns
• context engineering
• progressive disclosure
• build from scratch pedagogy