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

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, 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 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 appears before the visual-type guide in the document structure (lines 93-99 of 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 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 (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 and 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 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 file follows the routing contract programmatically:

# 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:

# 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:

# 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	Central skill definition enforcing the semantic-pattern-then-visual-type workflow
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	Validation script checking routing order and contract integrity
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.
• The verify-semantic-motion.py validator enforces this order at build time, checking document structure and required fields.
• Semantic patterns in 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 script enforces the routing order by validating that SKILL.md contains the phrase "Selection: semantic pattern, then visual type" and that the link to 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 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 and 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 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.

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