How Semantic Patterns Work in Diagram‑Design vs Direct Type Selection

Use semantic patterns first to define what a diagram does, then let the system choose the visual type; direct type selection skips this semantic layer entirely.

In the cathrynlavery/diagram-design repository, diagram creation follows a deliberate two-stage workflow that separates meaning from layout. This article explains how semantic patterns act as a pre-filter that shapes diagram content before any visual representation is chosen, and when direct type selection becomes the fallback path.

What Are Semantic Patterns in Diagram‑Design?

A semantic pattern describes the behavioral intent of a diagram—not how it looks, but what system dynamic it captures. According to the skill specification in skills/diagram-design/SKILL.md, these patterns include concepts like stage frameworks, secure paved roads, risk propagation, and enforcement boundaries.

Each pattern carries five defining characteristics:

• Selection trigger – the condition that activates this pattern
• Required primitives – mandatory visual elements the pattern needs
• Complexity budget – cognitive load limits for the diagram
• Anti-patterns – common misapplications to avoid
• Nearest visual type – the layout grammar that best expresses this pattern

The canonical reference defining all seven primary patterns lives in skills/diagram-design/references/semantic-patterns.md.

The Pattern‑First Workflow: How It Works

The core skill definition enforces strict sequencing: semantic pattern selection precedes visual type selection. This guarantees that a diagram's meaning drives its form rather than the reverse.

from diagram_design import DiagramBuilder

builder = DiagramBuilder()

# Stage 1: Define what the diagram communicates

builder.select_semantic_pattern("Stage framework with semantic slots")

# Stage 2: System automatically routes to optimal layout

# The builder selects "Process" as the nearest visual type

diagram = builder.render()

Behind the scenes, the DiagramBuilder class consults the routing table in semantic-patterns.md to map the chosen pattern to its recommended visual type. This abstraction shields users from layout decisions until the semantic foundation is locked.

Direct Type Selection: When and How to Use It

Direct type selection bypasses the semantic layer entirely. This path exists for diagrams where no established pattern captures the intent, or when prototyping layout without behavioral constraints.

from diagram_design import DiagramBuilder

builder = DiagramBuilder()

# Skip semantic pattern—select layout grammar directly

builder.select_visual_type("Data flow")

diagram = builder.render()

Use direct selection sparingly. Without a semantic pattern, the builder cannot enforce complexity budgets, validate primitives, or suggest anti-pattern warnings. The resulting diagram may look correct but communicate poorly.

Key Differences: Semantic Patterns vs Direct Type Selection

Aspect	Semantic Pattern First	Direct Type Selection
Starting point	System behavior/intent	Layout grammar
Primitives	Enforced by pattern	User-defined
Complexity control	Budget enforced	No limits
Anti-pattern detection	Active warnings	None
Visual type	Auto-selected from routing table	Manual override
Verification	Checked by verify-semantic-motion.py	Basic verify-motion.py only

Verification: How the System Enforces Pattern‑First Design

Two verification scripts validate correct workflow usage:

• scripts/verify-semantic-motion.py – Lints SKILL files to confirm every diagram links to a valid semantic pattern reference and respects the pattern→type routing order
• scripts/verify-motion.py – General validation for animated diagrams, checking semantic steps and motion constraints regardless of selection path

A diagram failing verify-semantic-motion.py cannot proceed to rendering if it claims pattern-based construction but bypasses the reference table.

Practical Example: Building a Secure Paved Road Diagram

from diagram_design import DiagramBuilder, SemanticPattern

builder = DiagramBuilder()

# Pattern defines: enforcement boundaries, guardrail primitives, 

# complexity cap of 7 elements, anti-pattern "leaky abstraction"

builder.select_semantic_pattern("Secure paved road")

# System selects "Pipeline" visual type based on routing table

# Primitives auto-populated: entry gate, verification stage, exit gate

diagram = builder.render(
    title="Deployment Pipeline Controls",
    show_budget=True  # Visual indicator of complexity usage

)

Attempting to build this as direct type selection would require manual primitive selection and offer no protection against the "leaky abstraction" anti-pattern.

Summary

• Semantic patterns in diagram-design capture system behavior and automatically determine optimal visual representation
• The workflow硬性 mandates pattern selection before type selection in skills/diagram-design/SKILL.md
• Seven primary patterns are fully specified in skills/diagram-design/references/semantic-patterns.md with routing tables to visual types
• Direct type selection exists as an escape hatch when no pattern matches, but sacrifices validation, budget enforcement, and anti-pattern protection
• Verification scripts verify-semantic-motion.py and verify-motion.py enforce these rules at build time

Frequently Asked Questions

What happens if I select a visual type that doesn't match my semantic pattern?

The verify-semantic-motion.py script flags this as a routing violation. The builder will either reject the combination or emit a warning, depending on configuration. The routing table in semantic-patterns.md exists precisely to prevent visual/type mismatches.

Can I extend diagram-design with custom semantic patterns?

Yes. Add new pattern definitions to skills/diagram-design/references/semantic-patterns.md following the established schema: trigger, primitives, budget, anti-patterns, and nearest visual type. Run verify-semantic-motion.py to validate the new entry.

Does direct type selection affect rendering performance?

No performance difference exists at render time. The distinction affects correctness and maintainability: pattern-based diagrams carry semantic metadata that enables automated refactoring, complexity audits, and cross-diagram consistency checks that direct selection cannot provide.

How do I know if my diagram needs a semantic pattern or direct selection?

Start with pattern selection. If diagram-design reports "no matching pattern" after reviewing all seven primary patterns and their triggers, fall back to direct type selection. Document this decision in your SKILL file comments for future maintainers.

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