How Diagram-Design Separates Semantic Patterns from Visual Types

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. 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.

## 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, 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: Linear flow with decision diamonds and process rectangles
• type-data-flow.md: Pipeline structures with stores, transforms, and sinks
• 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 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 to programmatically enforce the semantic-first rule:

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:

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

## 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: "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 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
Semantic patterns and routing	skills/diagram-design/references/semantic-patterns.md
Visual type specifications (Process example)	skills/diagram-design/references/type-process.md
Visual type specifications (Data Flow example)	skills/diagram-design/references/type-data-flow.md
Routing order validation	scripts/verify-semantic-motion.py
Mermaid import semantic builder	skills/diagram-design/references/import-mermaid.md
Draw.io import semantic builder	skills/diagram-design/references/import-drawio.md
Semantic role definitions	skills/diagram-design/references/style-guide.md
Semantic step animation contract	skills/diagram-design/references/animation.md

Summary

• Semantic patterns in 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 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 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 maps each pattern to its nearest visual type—the default layout—but you can override this during the "Selection" phase in 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. 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.

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