How Diagram Design Handles Requests Involving Semantic Patterns: A Complete Technical Breakdown

Diagram Design handles requests involving semantic patterns through an eight-step pipeline that separates behavioral semantics from visual layout, enforcing strict validation via Python contract verification before rendering self-contained HTML diagrams.

Diagram Design (cathrynlavery/diagram-design) is an open-source diagramming skill that processes complex architectural requests through a unique semantic-first approach. When users submit prompts requiring behavioral or policy-level information—such as queue depths, trust boundaries, or policy traces—the system routes these requests through specialized semantic patterns rather than treating them as generic visualization tasks. This article examines the complete technical flow, from initial prompt parsing to final HTML rendering, based on the actual source code implementation.

The Semantic Pattern Processing Pipeline

The architecture enforces a strict separation between behavior (semantic pattern) and layout (visual type). This ensures that policy-level concepts are handled with appropriate primitives while maintaining consistent visual grammar.

Step 1: Prompt Parsing and Style-Guide Gate

The process begins when the skill receives a natural-language request via Claude Code, Codex, Factory Droid, or Pi. Before any semantic analysis occurs, the system enforces a style-guide gate defined in skills/diagram-design/SKILL.md.

The skill verifies that a custom style-guide.md exists in the project context. If missing, the skill prompts the user to create one, aborting further processing until this prerequisite is satisfied. This gate ensures brand consistency and prevents unauthorized visual variations across organizational outputs.

Step 2: Semantic-Pattern Routing

Once past the gate, the request undergoes semantic-pattern routing. The parser scans for trigger phrases defined in skills/diagram-design/references/semantic-patterns.md, which catalogs seven distinct patterns including:

• Secure paved road (deployment pipelines with trust zones)
• Queue depth (buffer and backlog visualization)
• Policy evaluation (authorization flow traces)

When the parser detects keywords like "queue depth," "trust boundary," or "policy evaluation," it records the chosen pattern (e.g., Secure paved road) and prepares the corresponding primitive set. Lines 75-81 of semantic-patterns.md specifically define the trigger logic for the Secure paved road pattern.

Step 3: Visual-Type Selection

After semantic classification, the skill consults the Visual-type guide table in SKILL.md to map the semantic pattern to its nearest layout grammar. For example:

• Secure paved road → Architecture visual type
• Queue depth → Flow visual type
• Policy trace → Sequence visual type

This mapping occurs at line 85 of SKILL.md, ensuring that behavioral semantics dictate the available visual primitives without dictating specific layout algorithms.

Step 4: Reference Loading and Assembly

The skill loads two critical reference files simultaneously:

1. The visual-type reference (e.g., type-architecture.md) providing layout grammar, spacing rules, and composition algorithms
2. The semantic-patterns reference (semantic-patterns.md) providing pattern-specific primitives, complexity budgets, and behavioral constraints

This dual-loading ensures the renderer understands both how to arrange elements (visual type) and what those elements represent (semantic pattern). For the Secure paved road pattern, the system enforces constraints such as ≤ 3 trust zones and ≤ 8 components total.

Step 5: Motion and Animation Handling

If the request includes motion directives—reveal, step, or loop—the skill loads skills/diagram-design/references/animation.md alongside the static references. Motion primitives are defined in scripts/verify-semantic-motion.py through the constants MOTION_MODES and MOTION_PRIMITIVES.

Motion attributes are embedded as data attributes (data-motion-root, data-motion-item) in the generated HTML, enabling client-side JavaScript to control playback without external dependencies.

Step 6: Contract Verification

Before rendering completes, scripts/verify-semantic-motion.py executes the verify_markdown function to validate contract compliance. The verifier parses the generated HTML (referenced against example-policy-trace-animated.html) and checks:

• Correct routing: Verifies the diagram correctly references semantic-patterns.md and the appropriate visual type
• Motion attributes: Confirms presence of required data attributes (data-motion-root, data-motion-item, etc.)
• Asset safety: Ensures no disallowed remote assets exist (only approved Google Fonts permitted)
• Accessibility: Validates step counts, aria-labels, and motion control actions (play, pause, reset)

Errors accumulate in an internal errors list; any validation failure causes immediate abort with a descriptive error message, preventing malformed output from reaching the user.

Step 7: Final Rendering

Upon passing verification, the skill renders the diagram as a self-contained HTML file embedding SVG vector graphics, CSS styling, and optional JavaScript motion controllers. The output respects the pattern's required primitives and complexity budget, producing static-by-default diagrams that optionally support the requested motion directives.

Key Files and Their Roles

Understanding the repository structure clarifies how semantic pattern handling is implemented:

• skills/diagram-design/SKILL.md – The primary entry point containing the style-guide gate, visual-type selection logic, and the mapping table between semantic patterns and visual layouts.

• skills/diagram-design/references/semantic-patterns.md – Defines the seven semantic patterns, their trigger phrases, required primitives, and complexity constraints (e.g., maximum trust zones for security patterns).

• skills/diagram-design/references/type-architecture.md (and similar type-*.md files) – Provide layout grammar specific to each visual type, including spacing algorithms and composition rules.

• skills/diagram-design/references/animation.md – Catalogs optional motion primitives and their semantic meanings (e.g., step indicating sequential reveal of trust boundaries).

• scripts/verify-semantic-motion.py – Contains the verify_markdown function and constants MOTION_MODES/MOTION_PRIMITIVES that enforce the validation contract before final output.

• example-policy-trace-animated.html – The reference HTML template used by the verifier to ensure generated output meets structural and security standards.

Practical Implementation Examples

Triggering a semantic pattern request requires specific syntax to activate the routing logic.

Using Python within a Claude Code session:

# Example: request a "Secure paved road" diagram with optional motion

request = {
    "prompt": "Show a secure paved road for our deployment pipeline, with animation that steps through each zone.",
    "size": "medium",
    "motion": "step"
}

# Invoke via:

# /skill:diagram-design {"prompt": "...", "size": "...", "motion": "..."}

Using the Pi CLI:

# Install the skill and trigger semantic pattern routing

pi install https://github.com/cathrynlavery/diagram-design
pi run /skill:diagram-design "Show a secure paved road for our deployment pipeline, animate stepwise."

The skill executes the full pipeline:

1. Detects the Secure paved road trigger via semantic-patterns.md (lines 75-81)
2. Routes to the Architecture visual type per SKILL.md (line 85)
3. Loads type-architecture.md and semantic-patterns.md references
4. Applies step motion via animation primitives
5. Runs verify-semantic-motion.py to validate data attributes and asset safety
6. Returns diagram.html containing the fully-rendered, self-contained diagram

Summary

• Diagram Design processes semantic pattern requests through an eight-step gated pipeline that enforces strict separation between behavioral semantics and visual layout.
• The style-guide gate in SKILL.md acts as a prerequisite checkpoint before any semantic analysis begins.
• Semantic-pattern routing scans for specific trigger phrases defined in semantic-patterns.md, activating one of seven specialized patterns.
• The system validates all output through scripts/verify-semantic-motion.py, checking data attributes, asset safety, and accessibility before rendering.
• Final output is a self-contained HTML file with embedded SVG, respecting pattern-specific complexity budgets and optional motion directives.

Frequently Asked Questions

What triggers a semantic pattern route in Diagram Design?

Semantic pattern routing activates when the parser detects specific keywords in the user prompt, such as "queue depth," "trust boundary," or "policy evaluation," as defined in skills/diagram-design/references/semantic-patterns.md. These triggers indicate the request involves behavioral or policy-level information requiring specialized primitives rather than generic shapes. The system matches these against seven predefined patterns, including Secure paved road and Policy evaluation.

How does the style-guide gate work?

The style-guide gate is a mandatory checkpoint defined in skills/diagram-design/SKILL.md that executes before any diagram generation. The skill verifies the presence of a custom style-guide.md file in the project context; if absent, the skill prompts the user to create one and aborts processing. This ensures all subsequent semantic pattern diagrams adhere to organizational branding and visual standards.

What validation does verify-semantic-motion.py perform?

The verify_markdown function in scripts/verify-semantic-motion.py parses the generated HTML and validates four critical areas: correct routing to semantic-patterns.md, presence of required motion data attributes (data-motion-root, data-motion-item), absence of disallowed remote assets (only approved Google Fonts permitted), and proper accessibility markup including step counts and motion control actions. Validation failures accumulate in an errors list and cause immediate pipeline abortion.

Can semantic pattern diagrams include animation?

Yes, semantic pattern diagrams support optional animation through motion primitives defined in animation.md and implemented via scripts/verify-semantic-motion.py constants MOTION_MODES and MOTION_PRIMITIVES. Users specify motion directives (reveal, step, or loop) in their requests, which embed as data attributes in the final HTML. The verifier ensures these animations meet accessibility standards and contain proper aria-labels before the skill returns the final output.

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