How cathrynlavery/diagram-design's Semantic Pattern Routing System Maps Behavior to Visual Types

The cathrynlavery/diagram-design repository routes semantic patterns to visual types by evaluating a request's "load-bearing" behavioral aspects and selecting the corresponding pattern from the Semantic-Pattern Routing Table, which automatically maps to a predefined visual type that supplies the layout grammar.

The cathrynlavery/diagram-design project separates what a system does from how it is displayed through a sophisticated semantic pattern routing system. This architecture ensures that expressive, behavior-centric diagrams can be generated without expanding the taxonomy of visual layout types. By consulting a centralized routing table defined in skills/diagram-design/references/semantic-patterns.md, the system translates abstract semantic concepts like "Fan-in queue" or "Secure paved road" into concrete visual grammars such as Data flow or Architecture diagrams.

Core Architecture: Separating Semantics from Layout

The routing system is built on a strict separation between semantic patterns and visual types. Semantic patterns capture the what—behavioral details like state, enforcement, or risk—while visual types define the how—the layout grammar that renders the diagram. This decoupling allows new behaviors to be expressed without inventing new visual layouts, preserving the stability of the visual taxonomy as documented in ADR 0002.

The Semantic-Pattern Routing Table

The routing logic is implemented in skills/diagram-design/references/semantic-patterns.md (lines 9–19). This file defines the canonical mapping between the reader's understanding requirements and the corresponding visual representation.

Understanding Goal	Semantic Pattern	Nearest Visual Type
Many arrivals competing for finite service capacity	Fan-in queue / bottleneck	Data flow
Repeated questions, inputs, controls, and outputs across stages	Stage framework with semantic slots	Process
A loose conversation becoming a durable structured record	Unstructured input → structured artifact	Data flow
Why two policy decisions differ and where they first diverge	Paired policy-evaluation traces	Flowchart
Which routes cross a trust boundary and which routes are blocked	Secure paved road	Architecture
Which controls apply at each enforcement surface	Governance / control catalog	Layer stack
How defenses reduce risk and what risk remains	Compensating security layers	Layer stack
Which sub-elements a system decomposes into, each independently citable	Traceable block decomposition	Tree

Each row represents a routing decision: when the system detects the described situation, it selects the semantic pattern and immediately routes to the corresponding visual type.

The Four-Step Routing Mechanism

1. Pattern Selection

The skill analyzes the request to identify "load-bearing" aspects—behavior, state, security, or risk characteristics. Based on this evaluation, it selects the matching semantic pattern from the routing table in semantic-patterns.md.

2. Budget Enforcement

Each pattern defines a complexity budget that specifies maximum limits for sources, slots, or nodes (lines 36–38). The system enforces the stricter budget between the pattern's requirements and the visual type's capabilities, preventing diagrams from exceeding readable complexity.

3. Routing to Visual Type

Once a pattern is selected, the system automatically uses the nearest visual type listed in the routing table to generate the diagram. This ensures that new semantic behaviors do not create new visual types, maintaining the constraint that the visual taxonomy remains stable and unexpanded.

4. Static Fallback

If a pattern cannot be fully expressed within its complexity budget—for example, due to node overflow—the system triggers a static fallback (lines 30–33). This renders the essential semantics without animation, ensuring the diagram remains meaningful even when dynamic features are unavailable.

Practical Implementation Examples

The routing system exposes a simple interface through the Skill object. Users select patterns by semantic name; the system resolves the visual type internally via the routing table.

Example: Fan-in Queue Bottleneck

# Assume `skill` is a Diagram-Design Skill object

skill.select_pattern("Fan-in queue / bottleneck")

# The system routes to the Data-flow visual type internally

svg = skill.render()

Example: Traceable Block Decomposition

skill.select_pattern("Traceable block decomposition")

# Nearest visual type is Tree

svg = skill.render()

In both examples, the user never invokes visual types directly. The routing table defined in semantic-patterns.md manages the mapping transparently.

Key Files in the Routing Architecture

File	Role
skills/diagram-design/references/semantic-patterns.md	Contains the routing table and detailed pattern specifications with complexity budgets
docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md	Documents the architectural decision requiring patterns to route to existing visual types
scripts/verify-semantic-motion.py	Validates that each skill file correctly routes a semantic pattern before visual-type selection

Summary

• cathrynlavery/diagram-design implements semantic pattern routing to separate behavioral intent from visual representation.
• The Semantic-Pattern Routing Table in skills/diagram-design/references/semantic-patterns.md maps eight core semantic patterns to specific visual types like Data flow, Process, and Layer stack.
• Complexity budgets at both the pattern and visual-type levels prevent diagram overflow by enforcing strict node and slot limits.
• The system preserves visual taxonomy stability by routing all new behaviors to existing visual types rather than creating new layout grammars, as mandated by ADR 0002.
• Static fallbacks ensure semantic meaning persists when animation budgets are exceeded or dynamic rendering fails.

Frequently Asked Questions

What is the difference between a semantic pattern and a visual type in cathrynlavery/diagram-design?

A semantic pattern captures what a system does—behavioral aspects like state transitions, enforcement surfaces, or risk compensation—while a visual type defines how that information is laid out, supplying the grammar for rendering the diagram. The routing system maps the abstract pattern to the concrete visual type automatically.

How does the routing system handle diagrams that exceed complexity limits?

Each pattern enforces a complexity budget specifying maximum nodes, sources, or slots (lines 36–38 in semantic-patterns.md). If a request exceeds these limits, the system renders a static fallback diagram that preserves essential semantics without animation, ensuring the diagram remains interpretable.

Where is the semantic pattern routing logic defined?

The routing logic is defined in skills/diagram-design/references/semantic-patterns.md, which contains the canonical routing table mapping semantic patterns to their nearest visual types. This file also specifies the complexity budgets and fallback behaviors for each pattern.

Why doesn't cathrynlavery/diagram-design create new visual types for new behaviors?

According to ADR 0002 (docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md), the system intentionally routes new semantic patterns to existing visual types to prevent taxonomy expansion. This architectural constraint ensures the visual-type count remains stable while allowing unlimited expressive capability through semantic abstraction.

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