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

> Learn how to map semantic patterns to nearest visual types in diagram design. Identify meaning, select visuals, and render via CLI with this guide.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-09-09

---

**Map semantic patterns to nearest visual types by first identifying the meaning in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), then selecting the matching visual type reference, and finally rendering through the CLI while validating with [`verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md), and returns the pair:

```python
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:

```text
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md). A **visual type** provides the concrete rendering instructions, including SVG elements and spacing rules, specified in files like [`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-semantic-motion.py) to ensure the new mapping adheres to the repository's budget and ordering constraints.