How Diagram Design Separates Behavioral Semantics from Structural Representations in Diagram Type Selection

Diagram Design enforces a strict two-step selection process where behavioral semantics (what a system does) are resolved before structural representations (how it is visualized), ensuring that layout choices always follow functional intent.

The open-source Diagram Design skill (cathrynlavery/diagram-design) implements a strict architectural boundary between what a system describes and how that description is rendered. By decoupling behavioral semantics from structural layout, the system prevents taxonomy explosion while maintaining precise visual communication.

The Two-Step Selection Process

Diagram Design resolves diagram types through a mandatory sequential pipeline: behavioral intent is determined first, and only then is the structural grammar applied.

Step 1: Prioritizing Semantic Patterns

The skill begins by loading references/semantic-patterns.md to identify the primary semantic pattern that captures the behavior, state, enforcement, or risk of the figure (see lines 11‑17). Each pattern defines required primitives—such as queues, stages, or trust boundaries—and maps to a nearest visual type that best expresses that specific behavior.

For example, if the diagram must illustrate a queue with back-pressure, the "Fan-in queue / bottleneck" pattern is selected, defaulting to the Data flow visual type. Alternatively, the "Stage framework with semantic slots" pattern routes to the Process visual type. This ensures that the behavioral semantics drive the visualization, not the other way around.

Step 2: Loading Structural Layout Definitions

Once the semantic pattern is fixed, the system loads the concrete layout definition from references/type-*.md (e.g., type-data-flow.md, type-process.md). These files contain the grammar, connector rules, and visual constraints for the chosen structural representation.

According to the "Selection: semantic pattern, then visual type" rule documented in SKILL.md (lines 65‑79), the visual type is always loaded after the semantic pattern is confirmed. This guarantees that structural representations provide the layout grammar only after the behavioral intent has been established.

Key Files Enforcing the Separation

The architecture relies on specific reference files to maintain this separation of concerns:

• skills/diagram-design/SKILL.md – The core skill specification that mandates the two-step selection workflow and defines the fallback logic (lines 81‑112).
• skills/diagram-design/references/semantic-patterns.md – Defines all behavioral semantics and maps each pattern to its nearest visual type.
• skills/diagram-design/references/type-*.md – Individual files (such as type-data-flow.md) containing layout grammars, connector rules, and visual constraints for each structural representation.
• scripts/verify-semantic-motion.py – Validation script that enforces the "semantic pattern → visual type" ordering in the skill file, ensuring the architecture cannot be bypassed accidentally.

Practical Implementation and CLI Usage

When invoking Diagram Design, the --semantic pattern argument conceptually selects the appropriate entry from semantic-patterns.md, while the --type flag optionally forces the visual type but is normally inferred from the pattern.

# Example: Rendering a queue-behavior diagram

diagram-design render \
  --type data-flow \          # forced visual type (optional)

  --semantic pattern=fan-in \ # chosen semantic pattern

  --detail balanced \
  input.mmd

# Example: Rendering a stage-framework diagram

diagram-design render \
  --type process \
  --semantic pattern=stage-framework \
  --detail faithful \
  workflow.mmd

In both examples, the behavioral semantics specified via --semantic pattern determine the rendering strategy, while the --type parameter overrides the structural representation only when explicitly required.

Fallback Strategy When No Pattern Matches

If no semantic pattern matches the use case, the skill falls back to selecting a visual type directly from the 27-row visual-type guide documented in SKILL.md (lines 81‑112). This constraint ensures that the taxonomy remains fixed at 27 structural representations regardless of how many new semantic behaviors are added. New behaviors are expressed by reusing existing visual types through semantic mapping, preventing the system from accumulating infinite layout variations.

Summary

• Behavioral semantics (defined in semantic-patterns.md) are always evaluated before structural representations (defined in type-*.md files).
• The selection rule in SKILL.md (lines 65‑79) mandates semantic pattern resolution as the first step.
• Specific patterns like "Fan-in queue" map to Data flow, while "Stage framework" maps to Process, demonstrating how behavior drives layout.
• The 27-type visual guide provides a constrained fallback when semantic patterns do not apply.
• Validation scripts ensure the semantic-first ordering cannot be violated during skill execution.

Frequently Asked Questions

What is the difference between a semantic pattern and a visual type in Diagram Design?

A semantic pattern describes what a system does—capturing behaviors like queuing, staging, or trust boundaries—while a visual type defines how that behavior is structurally arranged through layout grammars and connector rules. The semantic pattern is selected first to ensure the diagram communicates the correct behavior, and the visual type provides the concrete rendering instructions afterward.

Can I force a specific visual type without using a semantic pattern?

Yes. The --type flag in the CLI allows you to force a specific visual type (e.g., data-flow or process) directly, bypassing semantic pattern resolution. However, this is optional; normally, the system infers the appropriate visual type from the selected semantic pattern. If no pattern is specified and no match is found, the system falls back to the 27-row visual-type guide.

How does the 27-type constraint keep the taxonomy manageable?

By limiting the visual-type inventory to 27 structural representations, Diagram Design prevents taxonomy explosion. New behavioral semantics are accommodated by mapping them to existing visual types rather than creating new layout grammars. This means the type-*.md files remain stable even as semantic-patterns.md expands to cover new use cases.

Where is the validation logic that enforces semantic-first selection?

The validation is implemented in scripts/verify-semantic-motion.py, which checks that the skill file (SKILL.md) maintains the correct ordering: semantic pattern resolution must precede visual type loading. This script ensures the architectural boundary between behavioral semantics and structural representations cannot be accidentally violated during modifications to the skill.

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