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

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/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/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/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/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:

# 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:

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, line 52	Human-verified confirmation of pattern selection
Automated script	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/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/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, type-architecture.md) located in skills/diagram-design/references/
• [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/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 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 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 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/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/skills/diagram-design/references/semantic-patterns.md), maintained under the skills/diagram-design/references/ directory alongside the individual visual-type specification files.

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