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

> Diagram Design handles semantic patterns via an 8-step pipeline. It separates behavior from layout, validates with Python contracts, and renders self-contained HTML diagrams.

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

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md).

The skill verifies that a custom [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md)) providing layout grammar, spacing rules, and composition algorithms
2. **The semantic-patterns reference** ([`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) alongside the static references. Motion primitives are defined in [`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/example-policy-trace-animated.html)) and checks:

- **Correct routing**: Verifies the diagram correctly references [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```python

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

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) (lines 75-81)
2. Routes to the *Architecture* visual type per [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) (line 85)
3. Loads [`type-architecture.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-architecture.md) and [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) references
4. Applies `step` motion via animation primitives
5. Runs [`verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-semantic-motion.py) to validate data attributes and asset safety
6. Returns [`diagram.html`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), activating one of seven specialized patterns.
- The system validates all output through **[`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) that executes before any diagram generation. The skill verifies the presence of a custom [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py) parses the generated HTML and validates four critical areas: correct routing to [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) and implemented via [`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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.