How Semantic Pattern Routing Works in Diagram Design: A 4-Step Guide

Semantic pattern routing separates what a system does from how it is laid out by mapping domain-specific semantic patterns to existing visual types through a strict priority-based routing table.

The cathrynlavery/diagram-design repository implements semantic pattern routing to maintain diagram clarity without expanding the existing taxonomy of 39 visual types. This approach enforces a "semantic-first" selection process that routes seven distinct behavioral patterns to appropriate layout grammars, ensuring that load-bearing concerns like state, enforcement, and risk are explicitly modeled before visual representation.

The Core Principle: Semantic vs. Visual Separation

Diagram Design distinguishes between the semantic pattern (what the system does) and the visual type (how information is laid out). The semantic pattern defines domain-specific primitives, complexity budgets, and anti-patterns for behaviors such as bottlenecks, governance catalogs, or staged workflows. The visual type provides the underlying layout grammar—including axes, connector rules, and spacing constraints—that renders the final diagram.

This separation allows the routing table in skills/diagram-design/references/semantic-patterns.md to map each of the seven semantic patterns to its nearest compatible visual type. For example, the Fan-in queue / bottleneck pattern routes to Data flow, while Stage framework with semantic slots routes to Process, and Governance / control catalog routes to Layer stack.

How Semantic Pattern Routing Functions

The routing process follows a strict four-step workflow defined in the repository's SKILL documentation and enforced by validation scripts.

Step 1: Select the Semantic Pattern

Whenever a diagram's behavior, state, enforcement, or risk constitutes a load-bearing concern, you must choose the appropriate semantic pattern first. Each pattern provides a constrained vocabulary of primitives—such as add_queue(), add_sink(), or add_outcome()—and imposes a tighter complexity budget than generic layout types. This selection occurs before any visual styling decisions are made, as documented in SKILL.md.

Step 2: Lookup the Nearest Visual Type

After pattern selection, the system consults the routing table to identify the compatible visual type. The table maintains mappings for all seven semantic patterns to existing visual types, ensuring that no new layout grammars are required. The nearest_visual_type() method performs this lookup automatically, returning the appropriate VisualType enum value (such as VisualType.DATA_FLOW or VisualType.PROCESS) based on the selected pattern's structural requirements.

Step 3: Apply Visual Layout Rules

Once routed, the diagram applies the visual type's layout rules—including axes, connector grammar, spacing, and node limits—on top of the pattern's primitives. The composition rules in semantic-patterns.md specify that the stricter of the two complexity budgets (pattern vs. visual type) takes precedence. This guarantees that the resulting diagram remains readable while accurately conveying behavioral semantics.

Step 4: Validate the Routing

The repository enforces routing correctness through scripts/verify-semantic-motion.py. This verification script checks that SKILL files mention "semantic pattern, then visual type" in the correct order and validates that each pattern correctly routes to its designated visual type. Running this script ensures that diagrams maintain the required separation of concerns and do not bypass the routing mechanism.

Implementation Example

The following Python example demonstrates the complete routing workflow from pattern selection to rendering:

from diagram_design import Diagram, SemanticPattern, VisualType

# Step 1: Pick the semantic pattern

pattern = SemanticPattern.FAN_IN_QUEUE   # "Fan-in queue / bottleneck"

# Step 2: Automatic routing selects the nearest visual type

visual = pattern.nearest_visual_type()  # returns VisualType.DATA_FLOW

# Step 3: Build diagram using routed visual type with pattern primitives

diag = Diagram(visual_type=visual, pattern=pattern)

# Add primitives required by the pattern

diag.add_source("Client A")
diag.add_source("Client B")
diag.add_queue("Load-balancer", slots=5)
diag.add_sink("Service X")
diag.add_outcome("Accepted")
diag.add_outcome("Rejected")

# Render final output

svg = diag.render()
print(svg)

You can also invoke this routing through the CLI using the profile command:

diagram-design profile \
    --semantic-pattern "Fan-in queue / bottleneck" \
    --size small \
    --output diagram.svg

Both approaches enforce the selection-first → routing → render flow required by the library's architecture.

Key Files in the Routing System

File	Role
skills/diagram-design/references/semantic-patterns.md	Defines the seven semantic patterns, their primitives, complexity budgets, and the routing table mapping each pattern to its nearest visual type.
skills/diagram-design/SKILL.md	Documents the "semantic pattern first, then visual type" decision flow and overall methodology.
scripts/verify-semantic-motion.py	Automated verification that ensures SKILL files respect the routing order and that patterns correctly map to visual types.
skills/diagram-design/references/type-*.md	Visual type reference files (e.g., type-data-flow.md, type-process.md) providing layout grammars used after routing.

Summary

• Semantic pattern routing separates behavioral modeling from visual layout by processing domain concerns before visual styling.
• The routing table in semantic-patterns.md maps seven specific patterns to existing visual types without expanding the 39-type taxonomy.
• Pattern methods like nearest_visual_type() automate the lookup of compatible layout grammars based on structural requirements.
• The verify-semantic-motion.py script validates that diagrams follow the "semantic-first" selection order and correct routing mappings.
• Composition rules ensure the stricter complexity budget between pattern and visual type governs the final diagram density.

Frequently Asked Questions

What is a semantic pattern in Diagram Design?

A semantic pattern is a domain-specific template that defines behavioral primitives, complexity constraints, and anti-patterns for specific system concerns like bottlenecks, governance, or staged processing. According to the source code in semantic-patterns.md, these patterns provide tighter complexity budgets than generic visual types to ensure diagrams remain readable while conveying precise behavioral information.

How does the routing table determine the visual type?

The routing table maps each of the seven semantic patterns to its nearest visual type based on structural compatibility. For instance, patterns describing data movement route to VisualType.DATA_FLOW, while organizational governance patterns route to VisualType.LAYER_STACK. This mapping ensures that existing layout grammars can render new behavioral concepts without requiring additional visual types in the taxonomy.

Why must I select the semantic pattern before the visual type?

Selecting the semantic pattern first enforces a complexity budget and specific primitives appropriate to the domain behavior. The repository's verify-semantic-motion.py script explicitly checks for this order because reversing it could allow visual styling to override behavioral constraints, resulting in diagrams that misrepresent system state or risk factors. This selection order guarantees that load-bearing concerns drive the layout rather than aesthetic preferences.

How can I verify my diagram uses correct semantic pattern routing?

Run the scripts/verify-semantic-motion.py script against your SKILL files. This verification tool checks that your documentation mentions "semantic pattern, then visual type" in the correct sequence and validates that selected patterns route to their designated visual types according to the routing table in semantic-patterns.md.

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