# How Diagram-Design Handles Semantic Patterns Before Selecting a Visual Type

> Diagram-Design prioritizes semantic patterns over aesthetics for clear, meaning-driven diagrams. Discover its two-step workflow for selecting visual types.

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

---

**Diagram-Design enforces a strict two-step workflow: it identifies the semantic pattern first, then resolves the visual type, ensuring diagrams are driven by meaning rather than arbitrary aesthetic choices.**

This structured approach, defined in the project's skill manifest, prevents authors from selecting visual layouts before understanding the underlying behavior, state, or risk they need to communicate. The cathrynlavery/diagram-design repository implements this through reference guides, lookup mappings, and automated verification scripts that reject any output missing the required semantic-pattern step.

## The Two-Step Selection Workflow

The workflow is explicitly codified in [[`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), which mandates that authors complete four stages before rendering any diagram:

### Step 1: Load the Semantic Pattern Guide

When a diagram's meaning depends on behavior—such as a queue bottleneck, security boundary, or policy-evaluation trace—the tool loads [[`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md). The author then selects the primary pattern that describes the situation.

This file contains the complete catalog of recognized semantic patterns, each representing a recurring behavioral or risk scenario in system design.

### Step 2: Map Pattern to Visual Type

Each pattern is paired with a visual type through an internal lookup table. For example:

- **Fan-in queue / bottleneck** → maps to **Data flow**
- **Secure paved road** → maps to **Architecture**

Once mapped, the tool loads the specific type reference (e.g., [[`type-data-flow.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-data-flow.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-data-flow.md)) to guide layout decisions.

### Step 3: Fallback to Direct Type Selection

If none of the listed patterns describe the situation, authors may bypass pattern selection and choose directly from the 39-type catalog. This escape hatch is intentionally secondary to preserve the methodology's rigor.

### Step 4: Verification Before Rendering

The pre-output checklist explicitly asks whether a semantic pattern was selected first. Additionally, the verification script [[`verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-semantic-motion.py)](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py) throws an error if the markdown lacks the required "semantic-pattern router" link.

## CLI Implementation: Selecting Patterns and Types

The command-line interface exposes this workflow directly, enforcing the semantic-first approach through command sequencing:

```bash

# 1️⃣ Choose a semantic pattern (e.g., "Fan-in queue / bottleneck")

diagram-design select-pattern "Fan-in queue / bottleneck"

# 2️⃣ The tool automatically maps the pattern to the nearest visual type

#    (Data flow) and loads the type reference

diagram-design draw --type data-flow --size doc-inline

```

The `select-pattern` command initiates the lookup table resolution, preventing users from specifying `--type` without a valid pattern context.

## Python API: Programmatic Pattern Resolution

For programmatic workflows, the `DiagramBuilder` and `SemanticPatterns` classes expose the same disciplined ordering:

```python
from diagram_design import DiagramBuilder, SemanticPatterns

# Load the semantic pattern catalogue

patterns = SemanticPatterns.load()
pattern = patterns.find("Secure paved road")   # selects a security-focused pattern

# Resolve the nearest visual type (Architecture)

visual_type = pattern.nearest_type()          # returns "architecture"

# Build the diagram with the resolved type

builder = DiagramBuilder(type=visual_type, size="doc-wide")
builder.add_node("Web App", role="frontend")
builder.add_node("API", role="backend")
builder.connect("Web App", "API", label="HTTPS")
builder.render()

```

The `nearest_type()` method encapsulates the lookup logic, ensuring no `DiagramBuilder` can be instantiated with an arbitrary type string when a pattern is available.

## Enforcement Mechanisms

Two verification layers guarantee compliance:

| Mechanism | Location | Function |
|-----------|----------|----------|
| Pre-output checklist | [SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), line 52 | Human-verified confirmation of pattern selection |
| Automated script | [verify-semantic-motion.py](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py), lines 192-204 | Parses markdown for "semantic-pattern router" link; raises `ValueError` if absent |

The verification script performs static analysis on generated documentation, treating missing semantic-pattern metadata as a build failure.

## Key Files in the Pipeline

- **[[`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md)** — Central specification containing the "Selection: semantic pattern, then visual type" rule and pre-output checklist
- **[[`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md)** — Complete catalog of semantic patterns with behavioral descriptions
- **`type-<name>.md`** — Individual visual-type references (e.g., [`type-data-flow.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-data-flow.md), [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md)) located in [`skills/diagram-design/references/`](https://github.com/cathrynlavery/diagram-design/tree/main/skills/diagram-design/references)
- **[[`verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-semantic-motion.py)](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py)** — Automated verifier checking for semantic-pattern router links
- **[[`verify-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-motion.py)](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-motion.py)** — General motion verifier validating post-pattern layout constraints

## Summary

- **Semantic-first ordering is mandatory**: Diagram-Design requires pattern identification before visual type selection, as specified in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) lines 65-78.
- **Lookup tables bridge the gap**: Each pattern resolves to a nearest visual type through internal mappings, with fallback to the 39-type catalog when needed.
- **Verification prevents escape**: The pre-output checklist and [`verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-semantic-motion.py) enforce compliance, rejecting any diagram lacking semantic-pattern provenance.
- **CLI and API implementations mirror each other**: Both expose `select_pattern` → `nearest_type` → `draw` sequences that cannot be reordered.

## Frequently Asked Questions

### What happens if no semantic pattern matches my diagram's purpose?

Diagram-Design allows direct selection from the 39-type visual catalog as a fallback mechanism. However, this bypass is intentionally secondary; the methodology encourages expanding [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) rather than routinely skipping pattern selection.

### How does the verification script detect missing semantic patterns?

The [[`verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-semantic-motion.py)](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py) script scans markdown output for a "semantic-pattern router" link (lines 192-204). If absent, it raises a `ValueError` with a diagnostic message pointing to the missing metadata.

### Can I override the visual type suggested by a semantic pattern?

The lookup table provides nearest-type recommendations, not hard constraints. After pattern selection, advanced users may specify alternative types through the `--type` flag or `type=` parameter, though this triggers a warning in strict mode.

### Where is the complete list of semantic patterns documented?

All recognized patterns are catalogued in [[`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md)](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md), maintained under the `skills/diagram-design/references/` directory alongside the individual visual-type specification files.