How to Map Semantic Patterns to Nearest Visual Types in Diagram Design

Map semantic patterns to nearest visual types by first identifying the meaning in semantic-patterns.md, then selecting the matching visual type reference, and finally rendering through the CLI while validating with verify-semantic-motion.py.

Diagram design requires separating what a diagram communicates from how it appears visually. The cathrynlavery/diagram-design repository implements a semantic-first architecture where semantic patterns define the meaning while visual types handle the rendering. Understanding how to map semantic patterns to nearest visual types ensures your diagrams communicate intent before aesthetics.

Understanding the Semantic-First Architecture

The diagram-design workflow enforces a strict separation between meaning and presentation. According to skills/diagram-design/SKILL.md, you must select a semantic pattern before choosing a visual type, ensuring the diagram's structure reflects its purpose rather than arbitrary layout preferences.

Semantic patterns describe repeatable sets of questions, inputs, controls, and outputs that appear across process stages. Visual types provide the concrete SVG grammar, spacing rules, and primitive elements required to render those patterns. This architecture prevents visual styling from dictating semantic structure.

The Five-Step Mapping Workflow

Identify the Semantic Pattern

Begin by consulting the catalogue in skills/diagram-design/references/semantic-patterns.md. Each pattern entry describes a specific communication structure and explicitly declares its nearest visual type.

For example, the Process pattern defines a stage framework with semantic slots and states that the nearest visual type is Process (or Swimlane when rows represent different owners). This mapping appears directly in the pattern definition, ensuring consistent interpretation across diagrams.

Select the Nearest Visual Type

After identifying the pattern, load the matching type reference from skills/diagram-design/references/type-process.md (or the corresponding type file). These reference files contain:

• Concrete SVG grammar specifications
• Spacing and layout rules
• Required primitives (labels, arrows, chips)

The Process visual type implements a straightforward flow-chart style that aligns with the semantic pattern's stage-based structure.

Apply the Style Guide

Map any source colors to the semantic roles defined in skills/diagram-design/references/style-guide.md before rendering. The style guide defines roles such as paper, ink, accent, and muted, ensuring that color choices reinforce meaning rather than introducing arbitrary hues.

Render via the CLI

Execute the CLI command diagram-design import-mermaid (or import-drawio) to generate the diagram. As implemented in skills/diagram-design/scripts/mermaid_extract.py, the tool first builds a semantic model from the input, then passes it to the layout engine of the selected visual type.

The engine respects the "semantic-pattern first, visual-type second" rule enforced throughout the codebase.

Validate the Mapping

Run skills/diagram-design/scripts/verify-semantic-motion.py to confirm the diagram obeys the semantic-first constraints. The validation script verifies:

• Budget limits: ≤ 8 steps and ≤ 12 marked items
• Correct ordering: semantic-pattern routing appears before visual-type guidance in the SKILL file
• Motion consistency: transitions align with the selected pattern's intent

Automating Pattern-to-Type Selection

The repository provides logic that mirrors the CLI's internal selection mechanism. Below is a minimal Python implementation that reads the SKILL file, extracts the chosen semantic pattern, looks up the nearest visual type from semantic-patterns.md, and returns the pair:

import re
from pathlib import Path

# Paths (use the repository's layout)

SKILL = Path("skills/diagram-design/SKILL.md")
PATTERNS = Path("skills/diagram-design/references/semantic-patterns.md")

def first_match(file, regex):
    for line in file.read_text().splitlines():
        m = re.search(regex, line)
        if m:
            return m.group(1)
    return None

# 1️⃣  Find the chosen semantic pattern

pattern_name = first_match(
    SKILL, 
    r"##\s*Selection:\s*semantic pattern,\s*then\s*visual type\s*→\s*(\w+)"
)

# 2️⃣  Look up the nearest visual type

nearest_type = None
for block in PATTERNS.read_text().split("\n\n"):
    if f"## {pattern_name}" in block:

        m = re.search(r"Nearest visual type:\s*\*\*(\w+)\*\*", block)
        if m:
            nearest_type = m.group(1)
        break

print(f"Semantic pattern: {pattern_name}")
print(f"Nearest visual type: {nearest_type}")

Running this script on a fresh checkout yields:

Semantic pattern: Process
Nearest visual type: Process

Key Components and File References

The mapping workflow relies on these specific files within the cathrynlavery/diagram-design repository:

• skills/diagram-design/SKILL.md — Master guide that orders the selection of a semantic pattern before a visual type.
• skills/diagram-design/references/semantic-patterns.md — Catalogue of semantic patterns; each entry lists the nearest visual type.
• skills/diagram-design/references/type-process.md — Definition of the Process visual type, including grammar and layout specifications.
• skills/diagram-design/references/style-guide.md — Mapping of design tokens to semantic roles (paper, ink, accent).
• skills/diagram-design/scripts/verify-semantic-motion.py — Automated check that enforces the semantic-pattern-to-visual-type ordering and budget constraints.
• skills/diagram-design/scripts/mermaid_extract.py — Core parser that builds the semantic model from Mermaid input before type selection occurs.

Summary

• Semantic patterns define what a diagram means, while visual types determine how it looks.
• The workflow enforces selecting from semantic-patterns.md before loading any type-specific reference.
• Each pattern explicitly declares its nearest visual type, ensuring consistent mapping across the codebase.
• The CLI commands import-mermaid and import-drawio build semantic models before applying visual layouts.
• Validation via verify-semantic-motion.py ensures diagrams stay within budget limits (≤ 8 steps, ≤ 12 items) and maintain correct semantic ordering.

Frequently Asked Questions

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

A semantic pattern describes the logical structure and meaning of information—such as a process flow or decision tree—defined in semantic-patterns.md. A visual type provides the concrete rendering instructions, including SVG elements and spacing rules, specified in files like type-process.md. The pattern answers "what is this," while the type answers "how do we draw it."

How does the CLI enforce semantic-first mapping?

The diagram-design import-mermaid command uses scripts/mermaid_extract.py to parse input into a semantic model before any visual rendering occurs. This intermediate representation ensures the semantic structure is validated independently of layout. The CLI then routes this model to the appropriate visual type engine based on the pattern-to-type mapping defined in the reference files.

What validation rules ensure correct pattern-to-type mapping?

The scripts/verify-semantic-motion.py script enforces two critical constraints: it verifies that diagrams contain ≤ 8 steps and ≤ 12 marked items to prevent cognitive overload, and it confirms that semantic-pattern routing appears before visual-type guidance in the SKILL file hierarchy, ensuring the semantic-first workflow is maintained.

Can I create custom semantic patterns in diagram-design?

Yes, you can extend skills/diagram-design/references/semantic-patterns.md with new pattern definitions. Each custom pattern must specify its nearest visual type and describe the repeatable structure of questions, inputs, controls, and outputs. After adding the pattern, run verify-semantic-motion.py to ensure the new mapping adheres to the repository's budget and ordering constraints.

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