How to Use the Seven Semantic Patterns in Diagram-Design: A Complete Reference

Diagram-Design's seven semantic patterns separate what a system does from how information is arranged, giving you domain-specific primitives and complexity budgets that map onto standard visual types like Data flow, Process, and Architecture.

Diagram-Design, an open-source diagramming skill in the cathrynlavery/diagram-design repository, uses semantic patterns to solve a common problem: most diagrams fail because they mix behavioral intent with layout concerns. The seven semantic patterns provide a routing layer—you select a pattern based on your system's behavior, then pair it with a nearest visual type that handles the actual layout. This article explains when to use each pattern, referencing the canonical definitions in semantic-patterns.md.

What Are Semantic Patterns?

Semantic patterns sit between your system description and the final diagram. According to SKILL.md §3, the routing workflow is:

1. Choose a semantic pattern when behavior, state, enforcement, or risk is load-bearing
2. Load the pattern reference from semantic-patterns.md to obtain primitives, complexity budget, and anti-patterns
3. Select the nearest visual type (Data flow, Process, Flowchart, Architecture, Layer stack, etc.)
4. Render the diagram by mapping pattern primitives onto the visual type's connectors and nodes

Crucially, patterns never create new layout grammars—they only augment existing visual types with domain-specific semantics.

The Seven Semantic Patterns: When and How to Use Each

Fan-In Queue / Bottleneck

Use when: Multiple producers converge on a single constrained service—API rate-limiters, code review queues, or gated deployments.

This pattern focuses on arrival rate, queue depth, capacity, and back-pressure. You'll show producers, the constrained resource, and how pressure builds or releases.

Nearest visual type: Data flow (or Process if sequential stages dominate)

instagit diagram \
  --semantic-pattern "Fan-in queue / bottleneck" \
  --visual-type data-flow \
  --size preset-medium \
  --title "API Rate‑limit Bottleneck"

Reference: semantic-patterns.md#L19-L33

---

Stage Framework with Semantic Slots

Use when: A lifecycle or operating model repeats the same questions, inputs, governance, or outputs across stages—CI pipelines, maturity models, or repeatable workflows.

This pattern emphasizes cross-stage comparability. Each stage has identical semantic slots (input, process, output, governance), making differences between stages immediately visible.

Nearest visual type: Process (or Swimlane for owner-centric views)

instagit diagram \
  --semantic-pattern "Stage framework with semantic slots" \
  --visual-type process \
  --size preset-large \
  --title "CI Pipeline Stages"

Reference: semantic-patterns.md#L33-L46

---

Unstructured Input → Structured Artifact

Use when: Raw dialogue, notes, or prompts are normalized into durable artifacts—tickets, schemas, reports, or database records.

This pattern highlights transformation and provenance: where the unstructured input originated, what normalization occurred, and how the structured artifact persists.

Nearest visual type: Data flow (or Process if many ordered gates)

instagit diagram \
  --semantic-pattern "Unstructured input → structured artifact" \
  --visual-type data-flow \
  --size preset-small \
  --title "Ticket Creation Flow"

Reference: semantic-patterns.md#L47-L60

---

Paired Policy-Evaluation Traces

Use when: Two similar requests produce divergent outcomes and readers must see rule-by-rule differences—policy compliance checks, feature flag evaluations, or authorization decisions.

This pattern runs parallel traces through the same policy engine, exposing exactly where and why decisions diverged.

Nearest visual type: Flowchart (or Sequence if temporal messaging matters)

instagit diagram \
  --semantic-pattern "Paired policy‑evaluation traces" \
  --visual-type flowchart \
  --size preset-medium \
  --title "Policy Decision Comparison"

Reference: semantic-patterns.md#L61-L74

---

Secure Paved Road

Use when: An architecture defines a bounded, trusted route from intake to deployment, with explicit trust boundaries, permitted/blocked ingress points, and privileged gates.

This pattern documents the "golden path" for secure operations: what is allowed, what is blocked, and where verification occurs.

Nearest visual type: Architecture

instagit diagram \
  --semantic-pattern "Secure paved road" \
  --visual-type architecture \
  --size preset-large \
  --title "Secure Deployment Path"

Reference: semantic-patterns.md#L75-L88

---

Governance / Control Catalog

Use when: Cataloguing controls by enforcement surface—authoring, CI, runtime, audit—so each surface's responsibilities are visible and comparable.

This pattern answers "where is this control enforced?" rather than "what does this control do?" It exposes gaps and overlaps in control coverage.

Nearest visual type: Layer stack (or Data Protection security matrix for role-based comparison)

instagit diagram \
  --semantic-pattern "Governance / control catalog" \
  --visual-type layer-stack \
  --size preset-medium \
  --title "CI/CD Control Matrix"

Reference: semantic-patterns.md#L89-L101

---

Compensating Security Layers

Use when: A defense-in-depth view is required, where each layer mitigates failures of the previous one and residual risk must be shown flowing through the stack.

This pattern documents failure propagation: what each layer stops, what leaks through, and how subsequent layers respond.

Nearest visual type: Layer stack (or Nested when containment boundaries matter)

instagit diagram \
  --semantic-pattern "Compensating security layers" \
  --visual-type layer-stack \
  --size preset-large \
  --title "Defense‑in‑Depth Stack"

Reference: semantic-patterns.md#L103-L115

Quick Reference: Pattern Selection Guide

Pattern	Trigger Condition	Visual Type
Fan-in queue / bottleneck	Many producers, one constrained resource	Data flow
Stage framework	Repeating lifecycle with comparable stages	Process
Unstructured → structured	Transformation from raw to normalized	Data flow
Paired policy traces	Side-by-side rule evaluation comparison	Flowchart
Secure paved road	Bounded, trusted deployment path	Architecture
Governance / control catalog	Controls mapped to enforcement surfaces	Layer stack
Compensating security layers	Defense-in-depth with residual risk flow	Layer stack

Pattern Validation and Testing

The repository includes scripts/verify-semantic-motion.py, which validates that every semantic pattern is correctly routed, documented, and mapped to its nearest visual type. This ensures the pattern system remains consistent as the skill evolves.

Additionally, skills/diagram-design/assets/example-queue-animated.html provides a visual reference for the Fan-in queue pattern with animation, demonstrating how queue dynamics render in practice.

Summary

• Semantic patterns encode behavioral intent—queue dynamics, policy divergence, security posture—separate from layout mechanics
• Each pattern carries a complexity budget and anti-patterns, enforced by the routing system in SKILL.md
• Patterns never replace visual types—they augment Data flow, Process, Flowchart, Architecture, and Layer stack with domain-specific primitives
• Selection depends on system behavior: convergence, repetition, transformation, comparison, bounded paths, surface mapping, or layered defense
• CLI integration via instagit diagram automatically loads pattern references and validates budgets before rendering

Frequently Asked Questions

How do I know if I need a semantic pattern or just a visual type?

Use a semantic pattern when behavior is load-bearing—when queue depth, policy divergence, security layers, or transformation logic is central to what you're communicating. If you're simply showing steps in order, a raw Process visual type suffices. As noted in SKILL.md §3, the routing step exists precisely to test whether behavioral semantics justify the pattern overhead.

Can I use the same pattern with different visual types?

Yes, but with constraints. Each pattern has a nearest visual type that provides optimal layout grammar. You can substitute alternatives (Fan-in queue works as Process if stages dominate), but you may lose expressive fidelity. The semantic-patterns.md reference explicitly documents these fallback options and their trade-offs.

What happens if I exceed a pattern's complexity budget?

The instagit diagram CLI validates your diagram against the pattern's defined budget during rendering. Exceeding it triggers either a warning with simplification suggestions or a hard failure, depending on severity. This enforcement prevents semantic patterns from degrading into undecipherable complexity—one of the anti-patterns documented in semantic-patterns.md.

Where can I find complete worked examples?

The docs/cookbook.md file contains practical guidance including the pattern selection step, and skills/diagram-design/assets/example-queue-animated.html demonstrates the Fan-in queue pattern with full animation. The verify-semantic-motion.py script also serves as executable documentation of valid pattern configurations.

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