# How Diagram-Design Separates Semantic Patterns from Visual Types

> Discover how diagram-design separates semantic patterns from visual types using a two-layer architecture. Learn how it ensures correct selection order for system meaning and layout rendering.

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

---

**Diagram-Design enforces a strict two-layer architecture where semantic patterns define system meaning while visual types handle layout rendering, with validation scripts ensuring the correct selection order.**

This open-source diagram framework from cathrynlavery/diagram-design prevents visual design from corrupting system semantics. The architecture guarantees that diagrams remain meaningful across different rendering engines and export formats.

## The Core Separation: Meaning vs. Layout

Diagram-Design divides every diagram into two independent layers. **Semantic patterns** capture *what* a system does—its behavior, state, enforcement, or risk. **Visual types** determine *how* that meaning is displayed through SVG shapes, connectors, and spacing rules.

This separation enables the same semantic model to render correctly as a flowchart, sequence diagram, or custom layout without losing meaning.

## How Semantic Patterns Work

Semantic patterns live in [`references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/references/semantic-patterns.md). Each pattern defines a reusable system concept:

- **Stage framework with semantic slots**: Represents phased workflows with defined entry and exit points
- **Secure paved road**: Models security enforcement boundaries and compliance checkpoints

The routing table inside this file maps every pattern to its **nearest visual type**—the layout grammar best suited to express that pattern's structure.

```markdown

## 3. Selection: semantic pattern, then visual type

When behavior, state, enforcement, or risk carries the meaning, first load
`references/semantic-patterns.md` and choose one primary pattern.
Then choose the nearest visual type for layout.

```

This instruction appears in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md), the master workflow file that orchestrates the entire diagram creation process.

## How Visual Types Work

Visual types are static layout grammars—27 total—defined across `type-*.md` files such as:

- [`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-process.md): Linear flow with decision diamonds and process rectangles
- [`type-data-flow.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-data-flow.md): Pipeline structures with stores, transforms, and sinks
- [`type-state-machine.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-state-machine.md): State nodes with transition triggers

These files specify:

- SVG node shape geometries
- Connector syntax and routing rules
- Minimum and maximum spacing constraints
- Label positioning algorithms

Crucially, visual types carry **no intrinsic meaning**. A rectangle in [`type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/type-process.md) does not mean "process"—it means "container shape for the semantic role assigned at build time."

## Validation: Enforcing Correct Selection Order

The repository includes [`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py) to programmatically enforce the semantic-first rule:

```python
if "Selection: semantic pattern, then visual type" not in skill:
    errors.append("SKILL.md must choose semantic pattern before visual type")
router_position = skill.find("semantic-patterns.md")
if router_position == -1:
    errors.append("SKILL.md must link to semantic-patterns.md")

# ensure the router appears before the visual-type guide

if router_position > skill.find("type-"):
    errors.append("semantic-pattern router must precede the visual-type guide")

```

This validation prevents contributors from accidentally prioritizing aesthetic layout over semantic accuracy.

## Runtime Building: From Import to Semantic IR

During diagram import, whether from Mermaid or Draw.io, the framework builds a **semantic intermediate representation (IR)** before any visual rendering occurs.

### Mermaid Import Pipeline

From [`import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-mermaid.md):

```markdown

## Step 4 — Build the semantic model

- Use semantic treatments from the chosen type.
- A Mermaid cylinder becomes Store/State; a rhombus stays a decision only in a flowchart.

```

The parser strips Mermaid's visual assumptions and reclassifies shapes by semantic role.

### Draw.io Import Pipeline

From [`import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-drawio.md):

```markdown

## Step 4 — Build the semantic model

- **Discard source colors.** Map them to semantic roles instead:
  e.g., a red fill becomes the semantic role `accent` (security concern).

```

Source colors, icons, and proprietary styling are **discarded entirely**. The framework maps visual artifacts to standardized semantic roles defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md): "paper" (background), "ink" (primary content), "accent" (emphasis), and others.

## Output: Semantic Markup with Visual Rendering

The final HTML/SVG preserves the semantic layer through:

- `data-step` attributes on DOM elements
- ARIA labels for accessibility
- Semantic labels independent of CSS classes

If animation is requested, [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/animation.md) animates **semantic steps**—the progression of meaning through the system—not visual transitions. The underlying semantics remain unchanged regardless of motion effects.

## Key Files in the Architecture

| Purpose | File Path |
|---------|-----------|
| Master workflow definition | [`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) |
| Semantic patterns and routing | [`skills/diagram-design/references/semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md) |
| Visual type specifications (Process example) | [`skills/diagram-design/references/type-process.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-process.md) |
| Visual type specifications (Data Flow example) | [`skills/diagram-design/references/type-data-flow.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-data-flow.md) |
| Routing order validation | [`scripts/verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-semantic-motion.py) |
| Mermaid import semantic builder | [`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md) |
| Draw.io import semantic builder | [`skills/diagram-design/references/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-drawio.md) |
| Semantic role definitions | [`skills/diagram-design/references/style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/style-guide.md) |
| Semantic step animation contract | [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) |

## Summary

- **Semantic patterns** in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) define system meaning through behavior, state, enforcement, and risk models
- **Visual types** in `type-*.md` files provide layout grammars with 27 rendering options that carry no intrinsic semantics
- **Validation scripts** in [`verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-semantic-motion.py) enforce selection order: semantic pattern first, visual type second
- **Import pipelines** strip source visual styling and build a pure semantic IR before any rendering occurs
- **Final output** contains semantic markup accessible to screen readers and parseable by downstream tools regardless of visual presentation

## Frequently Asked Questions

### What happens if I select a visual type before a semantic pattern?

The validation script [`verify-semantic-motion.py`](https://github.com/cathrynlavery/diagram-design/blob/main/verify-semantic-motion.py) will throw an error during CI. According to the check `router_position > skill.find("type-")`, any configuration where visual-type guides appear before the semantic-pattern router is rejected.

### Can the same semantic pattern render with different visual types?

Yes. The routing table in [`semantic-patterns.md`](https://github.com/cathrynlavery/diagram-design/blob/main/semantic-patterns.md) maps each pattern to its *nearest* visual type—the default layout—but you can override this during the "Selection" phase in [`SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/SKILL.md) if a different visual grammar better serves your audience.

### How does Diagram-Design handle colorblind accessibility?

Colors from source files are discarded during import. The framework replaces them with semantic roles ("paper", "ink", "accent") defined in [`style-guide.md`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md). These roles render to accessible color palettes that maintain distinguishability across color vision deficiencies.

### Why discard source colors instead of preserving them?

Source colors encode *visual* decisions made in external tools like Draw.io that may conflict with the semantic model. A red shape might indicate "error" in one diagram and "marketing brand" in another. By mapping to semantic roles, Diagram-Design ensures consistent, meaningful styling across all outputs.