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

> Understand how semantic pattern routing in diagram design maps domain patterns to visual types. Follow our 4-step guide for a clear explanation.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

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

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Documents the "semantic pattern first, then visual type" decision flow and overall methodology. |
| [`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/type-data-flow.md), [`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md).