How Semantic Patterns Map to Visual Types: The Complete Routing Guide

Semantic patterns describe what a system does (its behavior) and map to specific visual types—which define how information is arranged—via a fixed routing table that keeps the visual taxonomy at exactly 27 types while providing flexible, behavior-driven layout selection.

In the cathrynlavery/diagram-design repository, diagram authors navigate a strict taxonomy of 27 visual types when documenting system architecture. When behavior is load-bearing, the workflow requires selecting a semantic pattern first, then mapping it to the appropriate visual type using the routing table defined in skills/diagram-design/references/semantic-patterns.md. This guide explains exactly how semantic patterns map to visual types according to the source code, implementation logic, and architectural decisions recorded in the codebase.

Understanding the Routing Table

The routing table serves as the authoritative mapping mechanism between behavioral descriptions and layout grammars. Located in semantic-patterns.md, this table defines how seven specific semantic patterns route to their nearest visual type. According to SKILL.md, authors must follow a two-step selection process: first identify the semantic pattern that describes the system's load-bearing behavior, then consult the routing table to determine the concrete layout.

The mapping prioritizes the semantic intent over arbitrary aesthetic choice. For example, a Fan-in queue pattern—representing a bottleneck where multiple inputs converge—routes to Data Flow diagrams by default, but switches to Process when stage dominance is the primary concern. This conditional routing ensures the visual structure accurately reflects the underlying behavioral semantics.

The Seven Semantic Patterns and Their Visual Targets

Fan-in Queue and Bottleneck Patterns

The Fan-in queue / bottleneck pattern describes systems where multiple inputs converge into a constrained processing point. According to the routing table in semantic-patterns.md, this pattern maps to Data Flow as the nearest visual type. However, when the diagram emphasizes distinct processing stages over the convergence itself, it routes to Process instead. This distinction appears in the verification logic where the prefers_process flag triggers the alternative mapping.

Stage Frameworks and Semantic Slots

Systems organized as Stage frameworks with semantic slots—where processing occurs in defined phases with specific entry points—route primarily to Process diagrams. The routing table specifies Swimlane as the alternative when the stages are organized by owner or actor rather than by function. This mapping is implemented in the choose_visual_type function where owner-based row requirements override the default process layout.

Input Structuring and Data Transformation

The Unstructured input → structured artifact pattern captures ETL-like transformations where raw inputs become structured outputs. The routing table directs this pattern to Data Flow for general data movement visualization, or to Process when the diagram must emphasize ordered gates or validation stages. This dual routing accommodates both data-centric and process-centric interpretations of transformation workflows.

Policy Evaluation and Decision Traces

Paired policy-evaluation traces—representing parallel evaluation paths or A/B policy tests—map to Flowchart as the default visual type. The routing table specifies Sequence diagrams as the alternative when temporal ordering or actor interactions matter more than the decision logic itself. This ensures policy diagrams can shift from static decision trees to time-ordered interactions without changing the underlying semantic pattern.

Secure Paved Road Patterns

The Secure paved road pattern, representing standardized secure paths through a system, routes directly and exclusively to Architecture diagrams. Unlike other patterns that offer conditional alternatives, this one-to-one mapping reflects the pattern's focus on high-level structural components and their secure relationships.

Governance and Control Catalogs

Governance / control catalog patterns—documenting compliance frameworks or control matrices—route to Layer stack diagrams by default. When role-based permissions dominate the behavioral description, the routing table redirects to DP security matrix (Data Protection security matrix). This conditional mapping ensures governance diagrams emphasize either hierarchical control layers or cross-cutting permission structures depending on the primary concern.

Compensating Security Layers

The Compensating security layers pattern describes defense-in-depth strategies where multiple security controls mitigate risk. This routes to Layer stack for standard hierarchical visualization, or to Nested diagrams when containment boundaries and encapsulation boundaries are the key communicative elements. The routing choice depends on whether the author needs to show stacked capabilities or contained scope.

Implementation: Mapping Logic in Code

The repository's verification scripts implement this routing logic in Python. The PATTERN_TO_VISUAL dictionary encodes the primary mappings, while conditional statements handle the secondary preferences documented in the routing table.

# Map a semantic pattern to its nearest visual type

PATTERN_TO_VISUAL = {
    "fan_in": "data_flow",
    "stage_framework": "process",
    "unstructured_input": "data_flow",
    "policy_traces": "flowchart",
    "secure_road": "architecture",
    "governance_catalog": "layer_stack",
    "compensating_layers": "layer_stack",
}

def choose_visual_type(pattern: str, prefers_process: bool = False) -> str:
    """Return the visual type for a given semantic pattern."""
    visual = PATTERN_TO_VISUAL.get(pattern)
    if pattern == "fan_in" and prefers_process:
        visual = "process"
    if pattern == "stage_framework" and prefers_process:
        visual = "process"
    return visual

# Example usage

pattern = "stage_framework"
visual_type = choose_visual_type(pattern, prefers_process=True)
print(f"Pattern `{pattern}` maps to visual type `{visual_type}`")

This implementation mirrors the decision logic described in lines 9-16 of semantic-patterns.md, demonstrating how the repository validates that behavioral descriptions correctly resolve to layout grammars without expanding the visual type taxonomy.

Architectural Constraints on the Taxonomy

docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md formalizes a critical architectural constraint: semantic patterns must route only to existing visual types and cannot introduce new ones. This decision keeps the visual type count fixed at exactly 27, preventing taxonomy bloat while allowing flexible behavioral expression through the routing table.

As documented in README.md, if none of the seven routed patterns match a given behavioral description, authors bypass the routing table entirely and select a visual type directly. This fallback mechanism ensures the fixed taxonomy remains manageable while the routing table handles the most common complex behavioral scenarios.

Summary

• Semantic patterns describe system behavior (what the system does), while visual types define layout grammar (how information is spatially arranged).
• Seven specific semantic patterns route to nearest visual types via the routing table defined in skills/diagram-design/references/semantic-patterns.md.
• Data Flow and Process diagrams serve as common targets for queue, framework, and input-structuring patterns, with conditional logic selecting between them based on dominance criteria.
• Layer stack handles governance and security layer patterns, with alternatives available for role-based permissions (DP security matrix) and containment boundaries (Nested).
• ADR 0002 enforces that patterns route only to existing types, maintaining the strict 27-type taxonomy limit and preventing visual type proliferation.

Frequently Asked Questions

What is the difference between a semantic pattern and a visual type?

Semantic patterns describe behavioral intent—what a system does—such as fan-in queues or compensating security layers. Visual types describe the layout grammar—the spatial arrangement of diagram elements—such as Data Flow, Process, or Architecture diagrams. The routing table bridges these domains by mapping behavioral descriptions to their nearest spatial representation.

What happens if my diagram doesn't match any of the seven semantic patterns?

If your behavioral description does not align with the seven routed patterns (fan-in queue, stage framework, unstructured input, policy traces, secure paved road, governance catalog, or compensating layers), you should bypass the routing table and select a visual type directly. As noted in README.md, the routing table only applies when behavior is load-bearing and matches one of these specific scenarios.

Can new semantic patterns add new visual types to the taxonomy?

No. ADR 0002 explicitly forbids semantic patterns from expanding the visual-type taxonomy. New behavioral patterns must route to existing visual types among the fixed set of 27, ensuring the taxonomy remains stable and manageable while accommodating new behavioral descriptions through the routing mechanism.

How do I choose between primary and alternative visual types for a pattern?

The choice depends on which aspect of the behavior dominates the communication goal. For Fan-in queue patterns, select Process over Data Flow when processing stages dominate over the convergence point. For Stage framework patterns, choose Swimlane over Process when owner-based rows matter more than functional stages. The choose_visual_type function implements these preferences through boolean flags like prefers_process.

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