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

> Discover how semantic patterns map to visual types using a complete routing guide. Learn to arrange information flexibly with 27 visual types and behavior-driven layout selection.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-08-15

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), this table defines how seven specific semantic patterns route to their nearest visual type. According to [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```python

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