# When Should You Use Semantic Pattern Routing for Diagrams? > Learn when to use semantic pattern routing for diagrams. Discover how to visually represent behavior, state changes, rules, and primitives that go beyond simple visual types. Optimize your diagram design. - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: best-practices - Published: 2026-08-19 --- **Use semantic pattern routing for diagrams whenever behavior, state changes, enforcement rules, or domain-specific primitives carry meaning that a visual type alone cannot express.** The `cathrynlavery/diagram-design` repository separates *what* a system does from *how* information is arranged visually. Semantic pattern routing for diagrams acts as the first decision gate in this framework, ensuring you choose the correct behavioral abstraction before selecting a layout. ## What Is Semantic Pattern Routing? Semantic pattern routing is a design process that matches diagram requests to behavioral abstractions before selecting a visual type. According to [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), the framework requires loading [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) whenever behavior, state, enforcement, or risk carries the meaning. This routing layer prevents visual-type taxonomies from expanding beyond their structural purpose, as documented in ADR [`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). ## 5 Conditions That Require Semantic Pattern Routing for Diagrams You should route a diagram through a semantic pattern first when any of the following conditions apply. ### 1. Behavior-Driven Content Route through a semantic pattern when the diagram must convey **state changes**, **enforcement rules**, **risk mitigation**, or **policy decisions**. The skill guide in [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) explicitly states: "when behavior, state, enforcement, or risk carries the meaning, first load [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) and choose one primary pattern." ### 2. Domain-Specific Primitives Use semantic routing when the request requires specialized primitives such as **queues**, **trust boundaries**, **governance catalogs**, or **layered security controls**. Each pattern in [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) lists required primitives. For example, the **Fan-in queue / bottleneck** pattern requires "Distinct sources; fanned ingress; an ordered queue." ### 3. Complex Decision Logic Apply semantic pattern routing when the diagram must show **rule-by-rule evaluation**, **divergence points**, or **paired policy traces**. The **Paired policy-evaluation traces** pattern in [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) explains the need for two parallel rule flows with explicit divergence markers. ### 4. Security or Governance Focus Trigger routing for any scenario highlighting **trust boundaries**, **permitted/blocked routes**, or **control enforcement surfaces**. The **Secure paved road** and **Governance / control catalog** patterns in [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) describe these use cases and prescribe the nearest visual type, such as Architecture or Layer stack. ### 5. Visual Type Alone Cannot Express the Semantics Route semantically when the meaning of the diagram is lost or ambiguous without a higher-level behavioral description. ADR [`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) clarifies that "semantic patterns never expand the visual-type taxonomy; they are the axis for behavior." ## How Semantic Pattern Routing Works in Practice The practical workflow defined in `cathrynlavery/diagram-design` follows a strict sequence. 1. Load the `semantic-patterns` reference. 2. Identify which pattern matches the request using the routing table. 3. Apply the pattern's budget and primitive constraints. 4. Let the pattern select the nearest visual type, such as Data flow, Process, or Architecture. 5. Render the diagram using the chosen visual type. If no pattern fits, skip routing and pick a visual type directly. ## Practical Command-Line Routing Examples The following CLI snippets illustrate routing decisions using the `diagram-design` skill. All commands assume the skill is installed. ### Fan-in Queue (Behavior Matters) ```bash diagram-design import-mermaid sample-flowchart.mmd --type=data-flow --detail=balanced ``` This command handles a request where "many arrivals compete for finite service capacity." That description matches the **Fan-in queue / bottleneck** pattern in [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md), which routes to the **Data flow** visual type via the `--type` flag. ### Stage Framework with Semantic Slots ```bash diagram-design import-mermaid sample-process.mmd --type=process --detail=balanced ``` When a lifecycle repeats the same question-input-governance-output slots across stages, the **Stage framework** pattern applies. As documented in the semantic patterns reference, this routes to the **Process** visual type. ### Secure Paved Road (Security Focus) ```bash diagram-design import-mermaid sample-architecture.drawio --type=architecture --detail=balanced ``` The presence of trust boundaries and permitted/blocked routes triggers the **Secure paved road** pattern. According to [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md), this pattern selects **Architecture** as the nearest visual type. ### Direct Visual Type Selection (No Pattern Needed) ```bash diagram-design import-mermaid sample-tree.mmd --type=tree --detail=balanced ``` Simple hierarchical structures with no behavioral semantics bypass pattern routing entirely. The tool uses the **Tree** visual type directly without consulting [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md). ## Summary - Use semantic pattern routing for diagrams whenever behavior, state, enforcement, or risk carries the core meaning. - The routing decision is governed by [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) and defined in [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md). - Five primary triggers exist: behavior-driven content, domain-specific primitives, complex decision logic, security or governance focus, and insufficient visual-type semantics. - Patterns select the nearest visual type automatically; if no pattern matches, pick a visual type directly. ## Frequently Asked Questions ### What file controls the semantic pattern routing decision? The routing decision is controlled by [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), which mandates loading [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) whenever behavioral semantics matter. ADR [`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) provides the architectural rationale. ### Can I skip semantic pattern routing? Yes. If the diagram describes a simple structural relationship with no state changes, enforcement rules, or domain primitives, you can bypass routing and select a visual type directly. The Tree visual type example demonstrates this direct selection. ### How do semantic patterns differ from visual types? Semantic patterns describe *what* a system does, while visual types describe *how* information is arranged. According to ADR [`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), patterns are a separate behavioral axis that never expands the visual-type taxonomy. ### Which semantic pattern handles security and trust boundaries? The **Secure paved road** pattern handles trust boundaries and permitted/blocked routes, while the **Governance / control catalog** pattern handles control enforcement surfaces. Both are defined in [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md) and route to Architecture or Layer stack visual types.