Diagram Design Principles Explained: A Complete Guide to Editorial Minimalism, Accessibility, and Visual Systems

Diagram Design is built around a tightly-controlled editorial design system that treats every diagram as a self-contained, accessible SVG/HTML artifact with strict rules for minimalism, semantic selection, and technical robustness.

The Diagram Design project by Cathryn Lavery codifies eight core design principles in its SKILL.md specification. These principles enforce consistency across all generated diagrams while maintaining accessibility, readability, and brand flexibility. Each principle is backed by concrete rules, automated checks, and a skinnable token system.

---

Editorial Minimalism: Deletion as the Highest-Quality Move

The foundational philosophy of Diagram Design appears in SKILL.md under "Philosophy" (§3.1): "The highest-quality move is usually deletion."

• Node consolidation: Distinct ideas become single nodes; elements that "always travel together" merge
• Connection elimination: Remove connectors when the spatial layout already implies the relationship
• Visual silence: Every element must earn its presence through explicit semantic value

This principle prevents diagram bloat and forces designers to clarify information hierarchy before rendering.

---

Focus and Accent Limitation: The Focal Rule

Diagram Design enforces strict signal discipline through its focal rule defined in SKILL.md §7.8.

Only 1-2 focal elements may use the accent color. Everything else renders in ink, muted, or soft tones. Over-accenting constitutes an anti-pattern that breaks visual hierarchy.

# Custom accent applied—skill automatically limits to 2 nodes maximum

echo "accent: #ff5722" >> references/style-guide.md
diagram-design --type flowchart --profile default --output flow.html

The color tokens live in references/style-guide.md, the single source-of-truth for the skinnable design system.

---

Density Budget: Managing Visual Complexity

The density budget in SKILL.md §6.3 establishes a target visual density of 4/10.

Density Score	Action Required
≤ 4/10	Optimal—proceed
5-8/10	Review for consolidation opportunities
> 9 nodes	Mandatory split into overview + detail diagrams

This budget prevents cognitive overload and ensures diagrams maintain their explanatory power at a glance.

---

Six Mandatory Connector Rules: Geometric Precision

All connectors in Diagram Design must satisfy six unambiguous rules specified in SKILL.md §6.4 ("Mandatory connector rules"):

1. Rounded right-angle orthogonal connectors only—no diagonals or curves
2. 6-10 px gap between label mask and arrow head
3. No overlapping connectors—paths must not intersect
4. Fan attach points when multiple arrows share a destination edge
5. Connectors must not pass behind non-endpoint boxes (unless unavoidable, then dashed)
6. Label masks must not overlap nodes drawn later in the render order

The scripts/verify-geometry.py tool automates rule 6 validation:

python3 scripts/verify-geometry.py path/to/generated.html

# Fails if any label mask overlaps a later-drawn node

---

Grid-Based Layout: The 4px Foundation

Every coordinate, dimension, and gap in Diagram Design is a multiple of 4px. This 4px grid system (SKILL.md §4.5) ensures:

• Predictable alignment across all diagram types
• Pixel-perfect rendering at any scale
• Consistent spacing relationships that "feel" intentional

The grid applies to node sizes, connector paths, padding, and label positioning.

---

Semantic-First Selection: Behavior Before Layout

Diagram Design reverses the typical workflow through semantic-first selection (SKILL.md §6.5):

1. Choose a semantic pattern (behavior) from references/semantic-patterns.md
2. Then select a visual type (layout) from type-*.md files like type-architecture.md

# Pattern chosen first, then visual type

diagram-design \
  --import-mermaid diagram.mmd \
  --pattern fan-in-queue \
  --type data-flow \
  --output dataflow.html

This prevents format-driven design—where a familiar layout forces inappropriate semantics—and ensures the "what" drives the "how."

---

Skinnable Design System: Token-Driven Branding

All visual properties centralize in references/style-guide.md. This architecture enables:

• Single-file branding: Replace or override tokens for client-specific output
• Consistent application: Colors, typography, spacing, and motion parameters propagate automatically
• Profile switching: Use --profile to load alternate style guides without changing diagram logic

The design system separation from content generation embodies true design-system architecture.

---

Pre-Output Quality Gates: The "Taste Gate"

Before any diagram emits, it passes through a pre-output checklist (SKILL.md §9.0) executed by scripts/self_check.py:

• Type fit verification—does the visual type match the semantic pattern?
• Removal tests—can any element be deleted without information loss?
• Signal limit validation—focal rule compliance, accent limits
• Technical SVG contract—valid markup, unique IDs, accessibility attributes

diagram-design --type architecture --size doc-inline --detail balanced --output my-arch.html

# Taste gate runs automatically; failure blocks output

---

Accessibility-First SVG Contract

Every Diagram Design artifact satisfies SKILL.md §6.3's accessible SVG contract:

<svg role="img" aria-labelledby="title desc">
  <title id="title">System Architecture Overview</title>
  <desc id="desc">Three-tier application showing web, API, and data layers</desc>
  <!-- diagram content with uniquely prefixed IDs -->
</svg>

Requirements include:

• role="img" on root <svg>
• Proper aria-labelledby referencing <title> and <desc>
• Unique ID prefixes per diagram to prevent collisions in composite documents

---

Key Implementation Files

File	Purpose
skills/diagram-design/SKILL.md	Master specification of all principles, rules, and workflows
references/style-guide.md	Central token store for colors, typography, spacing
references/semantic-patterns.md	Semantic behavior patterns for selection-first workflow
references/type-*.md	Layout grammars per visual type (e.g., type-architecture.md)
scripts/verify-geometry.py	Automated connector rule 6 enforcement
scripts/self_check.py	Full pre-output taste gate validation
assets/template.html	Base HTML template for minimal light variant output

---

Summary

The design principles behind Diagram Design create a disciplined, reproducible editorial system:

• Editorial Minimalism treats deletion as the primary design tool
• Focal and density rules enforce visual hierarchy and cognitive limits
• Six mandatory connector rules guarantee geometric precision
• 4px grid system ensures pixel-perfect, predictable layouts
• Semantic-first selection prioritizes meaning over familiar formats
• Skinnable tokens enable single-file branding without structural changes
• Automated taste gates block substandard output before publication
• Accessibility-first contracts make every diagram screen-reader compatible

These principles, codified in SKILL.md and enforced through verify-geometry.py and self_check.py, make Diagram Design suitable for production documentation systems requiring both visual consistency and technical rigor.

---

Frequently Asked Questions

What makes Diagram Design "editorial" rather than just a diagram generator?

Diagram Design applies content editing discipline to visual work. The SKILL.md specification explicitly treats diagrams as published artifacts requiring the same rigor as prose: information hierarchy, cruft elimination, and quality gates before publication. The "highest-quality move is usually deletion" principle mirrors editorial cutting rooms more than traditional drawing tools.

How does the 4px grid interact with responsive or zoomed diagrams?

The 4px grid provides relative rather than absolute alignment. Coordinates and dimensions scale proportionally, maintaining the underlying grid relationships at any zoom level. This prevents the "jagged" appearance of misaligned elements when SVGs render at non-integer device pixel ratios.

Can I disable the taste gate or density budget rules?

No—these are hard constraints in the reference implementation. The self_check.py script runs automatically during generation, and violations block output. This enforces consistency across all diagrams produced with the skill. Forking the repository would be required to modify or remove these gates.

What's the difference between a semantic pattern and a visual type?

Semantic patterns (in semantic-patterns.md) describe behavior: fan-in queues, request-response cycles, state transitions. Visual types (in type-*.md files) describe rendering mechanics: architecture diagrams, flowcharts, swimlanes. The semantic-first rule requires selecting behavior before format, preventing the common anti-pattern of forcing content into a favorite layout shape.

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