How Semantic Patterns Differ from Visual Types in Diagram Design

Semantic patterns define the abstract logical flow and accessibility structure of a diagram, while visual types implement the concrete graphical representation in specific formats like Mermaid or Excalidraw.

In the cathrynlavery/diagram-design repository, the architecture strictly separates what a diagram communicates from how it appears. This distinction ensures that diagram logic remains platform-agnostic and accessible while allowing flexible rendering across multiple diagramming tools.

Core Architectural Distinction

Semantic Patterns (The "What")

Semantic patterns describe the abstract motion and logical flow of a diagram. They are platform-agnostic constructs that define the meaning of each animation step without prescribing visual appearance.

These patterns live in semantic-patterns.md and consist of numbered steps (typically 1–8) paired with aria-labels that provide accessibility context. For example, a "Fan-in queue / bottleneck" pattern defines steps like:

1. “Start” – aria-label: “Initialize”
2. “Process” – aria-label: “Transform data”
3. “Finish” – aria-label: “Complete”

The verify-semantic-motion.py script enforces that every skill routes through these patterns before any visual rendering occurs, ensuring step counts are contiguous and each step has a meaningful, non-color aria-label.

Visual Types (The "How")

Visual types define the concrete visual representation—shapes, arrows, colors, and layout—that a diagram renders as. Each visual type implements a specific diagramming language or tool format.

Implementation resides in extractor scripts such as mermaid_extract.py, excalidraw_extract.py, and drawio_extract.py. These files contain functions like extract_mermaid() that convert abstract diagram objects into language-specific syntax. As noted in the source, only semantic label and shape data crosses the trust boundary during this extraction:

def extract_mermaid(diagram: Diagram) -> str:
    """
    Convert a Diagram object into a Mermaid code block.
    Only semantic label/shape data crosses the trust boundary.
    """
    # Parsing logic converts abstract steps to Mermaid syntax

    return mermaid_source

Source Code Validation

Enforcing Semantic Integrity

The verify-semantic-motion.py verifier ensures that SKILL.md files link to semantic-patterns.md before declaring any visual type. It validates that:

• Every skill references the semantic patterns file
• Step sequences are contiguous
• Each step includes an aria-label for accessibility

Validating Visual Output

Each visual type has dedicated verification scripts—verify-mermaid-import.py, verify-excalidraw-import.py, and verify-drawio-import.py—that confirm extracted visual data preserves intended semantics. For instance, these scripts verify that bidirectional arrows maintain their directional semantics when translated into specific diagram syntax.

The high-level scripts/verify-motion.py coordinates both semantic and visual validation pipelines, ensuring that visual outputs faithfully reflect the underlying logical patterns.

Workflow Integration

The design workflow follows a strict sequence: first select a semantic pattern (the logic), then choose a visual type (the presentation). A typical skill definition links to both:

# Skill: fan-in-queue

[semantic-patterns.md](../references/semantic-patterns.md#1-fan-in-queue)

## Visual type

[mermaid.md](../visual-types/mermaid.md)

At runtime, the semantic pattern drives the animation engine—determining which elements to highlight, hide, or move—while the visual type produces the rendered diagram by translating abstract steps into concrete visual changes on the chosen platform.

Summary

• Semantic patterns provide platform-agnostic logical flow and accessibility metadata via semantic-patterns.md, verified by verify-semantic-motion.py.
• Visual types deliver concrete graphical implementations through extractors like mermaid_extract.py and excalidraw_extract.py.
• The repository enforces a separation of concerns where semantics define what happens and visual types define how it looks.
• High-level validation in scripts/verify-motion.py ensures visual outputs maintain semantic integrity across all diagram formats.

Frequently Asked Questions

What is the primary purpose of semantic patterns in diagram design?

Semantic patterns establish the abstract logical flow and accessibility structure of a diagram independent of any rendering technology. They ensure that the underlying meaning—captured through numbered steps and aria-labels in semantic-patterns.md—remains consistent regardless of whether the final output uses Mermaid, Excalidraw, or Draw.io syntax.

How do visual type extractors maintain semantic integrity?

Extractors such as mermaid_extract.py handle the trust boundary between abstract semantic data and concrete visual syntax. Companion verification scripts like verify-mermaid-import.py check that directional relationships, step sequences, and logical connections preserved in the visual output match the definitions in the semantic patterns.

Why does the repository separate semantic patterns from visual types?

This separation allows the cathrynlavery/diagram-design architecture to support multiple diagramming tools without duplicating logical definitions. By decoupling what the diagram communicates (semantics) from how it appears (visuals), developers can add new visual types—such as additional export formats—without modifying the underlying semantic logic or accessibility structure.

Which files validate the relationship between semantics and visuals?

The verify-semantic-motion.py script ensures skills correctly reference semantic patterns, while verify-motion.py orchestrates the complete validation pipeline. Visual-specific verifiers—including verify-mermaid-import.py, verify-excalidraw-import.py, and verify-drawio-import.py—confirm that each visual type accurately represents the semantic steps defined in the master patterns file.

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