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

> Master diagram-design's seven semantic patterns to separate system function from information structure. Learn when to use these domain-specific primitives for clearer diagrams.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: api-reference
- Published: 2026-09-06

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md).

## What Are Semantic Patterns?

Semantic patterns sit between your system description and the final diagram. According to [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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)

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

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

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

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

```

Reference: [`semantic-patterns.md#L61-L74`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/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

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

```

Reference: [`semantic-patterns.md#L75-L88`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/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)

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

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md).

### Where can I find complete worked examples?

The [`docs/cookbook.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/cookbook.md) file contains practical guidance including the pattern selection step, and [`skills/diagram-design/assets/example-queue-animated.html`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/assets/example-queue-animated.html) demonstrates the Fan-in queue pattern with full animation. The [`verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-semantic-motion.py) script also serves as executable documentation of valid pattern configurations.