# How Semantic Pattern Routing Separates Behavior from Visual Layout in Diagram Design

> Learn how semantic pattern routing in diagram design separates behavior from visual layout. Discover the two-step process and automated validation for cleaner diagrams.

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

---

**Semantic pattern routing enforces a strict two-step process where diagram authors select a behavioral pattern before choosing a visual layout, enforced by automated validation scripts that prevent mixing concerns during generation.**

In the `cathrynlavery/diagram-design` repository, semantic pattern routing serves as the core architectural mechanism that isolates diagram meaning from presentation. This approach ensures that behavioral semantics remain stable regardless of visual styling changes, enabling authors to define *what* a diagram communicates independently of *how* it appears.

## The Two-Step Routing Architecture

The routing system implements a deliberate decoupling of concerns through a mandated selection order. Authors must first choose a semantic pattern that defines behavioral intent, then map that pattern to a compatible visual type that governs layout geometry. This separation ensures that visual styles can be swapped or restyled without affecting underlying behavioral logic.

## Step 1: Selecting the Semantic Pattern

The process begins in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), which requires authors to select a semantic pattern before any visual type is considered.

### Validation of Pattern-First Selection

The markdown validator [`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py) enforces this routing by checking that the phrase *"Selection: semantic pattern, then visual type"* appears in the skill definition. According to the source code, the validator also verifies that the link to [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) appears **before** the visual-type guide in the document structure (lines 93-99 of [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md)). If these ordering constraints are violated, the build aborts.

### Behavioral Primitives in Pattern References

Each semantic pattern lives in [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md) and defines specific behavioral primitives such as "Fan-in queue / bottleneck" or "Stage framework with semantic slots." These entries specify complexity budgets, anti-patterns, static fallbacks, and nearest visual type mappings (lines 26-34 and 36-43). The repository contains **eight distinct semantic patterns**, each modeling a specific behavioral contract independent of visual representation.

## Step 2: Routing to Visual Layout

After pattern selection, the system routes to layout specifications that contain zero behavioral semantics.

### The Visual Type Mapping

The visual-type guide in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) (lines 65-73) maps the chosen semantic pattern to the nearest visual type from a catalog of **39 concrete diagram types**. These include architecture diagrams, flowcharts, and data flows, each backed by separate reference files such as [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md) and [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md) (lines 84-99).

### Layout-Only Specifications

Visual type references in `references/type-*.md` files provide strictly layout rules—grid systems, node dimensions, connector styles—without containing behavioral semantics. This isolation allows visual presentations to evolve independently while preserving the underlying behavioral meaning encoded by the semantic pattern.

## Build-Time Verification

The [`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py) script validates the routing contract at build time. It checks that the markdown contains the required routing order, verifies that every pattern has required fields (complexity budget, anti-patterns, static fallback), and confirms the visual-type guide contains exactly 39 rows (lines 82-106 and 112-124). Any validation failure aborts diagram generation, preventing mixed-concern documents from progressing.

## Implementation Example

To verify that a [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) file follows the routing contract programmatically:

```python

# Example: Verifying that a SKILL.md follows the routing contract

from scripts.verify_semantic_motion import verify_markdown

errors = verify_markdown()
if errors:
    print("Routing errors:", errors)
else:
    print("Semantic pattern routing OK")

```

The routing structure appears in the skill definition as:

```yaml

# Example excerpt from SKILL.md (lines 65-73)

## 3. Selection: semantic pattern, then visual type

When behavior, state, enforcement, or risk carries the meaning, first load
`references/semantic-patterns.md` and choose one primary pattern.
Then choose the nearest visual type for layout.

```

A semantic pattern entry defines behavioral constraints:

```markdown

# Example entry in semantic-patterns.md (lines 26-33)

## 1. Fan-in queue / bottleneck

**Selection triggers:** Fan-in, queue depth, finite capacity, bottleneck
**Required primitives:** …
**Complexity budget:** …
**Anti-patterns:** …
**Static fallback:** …
**Nearest visual type:** Data flow

```

## Key Files in the Routing System

| File | Role |
|------|------|
| [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) | Central skill definition enforcing the semantic-pattern-then-visual-type workflow |
| [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md) | Defines 8 semantic patterns and their behavioral contracts |
| `skills/diagram-design/references/type-*.md` | Layout-only specifications for 39 visual types |
| [`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py) | Validation script checking routing order and contract integrity |
| [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) | Optional motion contract loaded after pattern/type resolution |

## Summary

- **Semantic pattern routing** mandates selecting behavioral semantics before visual layout in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md).
- The [`verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-semantic-motion.py) validator enforces this order at build time, checking document structure and required fields.
- **Semantic patterns** in [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) define behavioral primitives, complexity budgets, and anti-patterns.
- **Visual types** in `references/type-*.md` contain only layout rules (grids, dimensions, connectors) with no behavioral logic.
- This architecture allows the 8 semantic patterns and 39 visual types to evolve independently while maintaining contract guarantees.

## Frequently Asked Questions

### What enforces the pattern-first routing order in diagram design?

According to the `cathrynlavery/diagram-design` source code, the [`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py) script enforces the routing order by validating that [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) contains the phrase "Selection: semantic pattern, then visual type" and that the link to [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) appears before the visual-type guide. If these constraints are violated, the script aborts the build process (lines 82-106).

### How many semantic patterns and visual types does the system support?

The [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) file defines **8 semantic patterns**, each representing a distinct behavioral contract. The visual-type guide catalogs **39 concrete diagram types**, each with dedicated layout specifications in `references/type-*.md` files such as [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md) and [`type-flowchart.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-flowchart.md).

### Can visual layouts be changed without affecting diagram behavior?

Yes. Because visual type references contain only layout rules (grid systems, node dimensions, connector styles) and no behavioral semantics, you can swap or restyle the visual presentation without altering the underlying meaning encoded by the semantic pattern. This separation is the core architectural benefit of semantic pattern routing.

### What happens if a semantic pattern is missing required fields?

The [`verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-semantic-motion.py) validator checks that every pattern includes required fields: complexity budget, anti-patterns, and static fallback (lines 112-124). If any required fields are missing or incomplete, the script reports routing errors and prevents diagram generation, ensuring all behavioral contracts remain complete and testable.