How Diagram-Design Uses Semantic Patterns to Select Diagram Types

Diagram-Design enforces a two-stage selection workflow that maps system behavior to semantic patterns before binding to a visual layout type, ensuring architectural meaning remains independent of rendering.

The cathrynlavery/diagram-design repository implements a strict separation between what a diagram communicates and how it appears. By treating semantic patterns as the primary selection mechanism, the system ensures that layout choices never override the underlying architecture being documented. This approach creates an intermediate representation where semantics drive the structure while visual types merely provide the rendering grammar.

The Architecture: Semantics Versus Layout

Diagram-Design operates on a clear architectural boundary: semantic patterns describe what a system does, while visual types dictate how that information is laid out. This separation prevents the accidental coupling of meaning with presentation that plagues traditional diagramming tools.

Semantic patterns capture behavior, state, enforcement mechanisms, and risk domains. These patterns live in skills/diagram-design/references/semantic-patterns.md and include definitions like Stage framework with semantic slots and Secure paved road. Each pattern functions as a conceptual routing table, mapping abstract system characteristics to compatible visualization needs without prescribing specific shapes or colors.

Visual types provide the layout grammar. Defined across 27 distinct specification files (such as skills/diagram-design/references/type-process.md and type-data-flow.md), these files control SVG node shapes, connector syntax, spacing rules, and structural limits. Crucially, visual types carry no intrinsic meaning—they exist solely as rendering engines for the semantic model.

The Selection Workflow

The orchestration logic resides in skills/diagram-design/SKILL.md, which mandates a strict ordering: semantics first, layout second.

Step 1: Pattern Selection

When behavior, state, enforcement, or risk carries the architectural meaning, the system first loads references/semantic-patterns.md and selects one primary pattern. This decision anchors the diagram to its conceptual foundation before any visual decisions occur.

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

Step 2: Validation

The repository enforces this ordering through automated validation. The script scripts/verify-semantic-motion.py audits SKILL.md to confirm that semantic pattern selection precedes visual type binding and that routing entries point to correct visual type references.

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 guarantees that the routing table maintains the correct hierarchy, preventing developers from accidentally selecting a flowchart layout before defining the architectural state machine it represents.

Building the Semantic Intermediate Representation

During import operations from Mermaid or Draw.io, the system constructs a semantic intermediate representation (IR) that strips away presentation artifacts and replaces them with meaning-based annotations.

Import Pipeline

The import guides (skills/diagram-design/references/import-mermaid.md and import-drawio.md) specify a four-step process where visual decorations are discarded and replaced by semantic roles. For example, a red fill in a source diagram does not remain red; instead, it becomes the semantic role accent indicating a security concern, as defined in skills/diagram-design/references/style-guide.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).

Similarly, Mermaid syntax undergoes transformation where cylinders become Store/State nodes and rhombuses retain decision semantics only within flowchart contexts, ensuring the IR captures architectural intent rather than drawing commands.

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

Rendering and Output

The final output generation relies entirely on the semantic IR. The resulting HTML/SVG contains semantic markup—including labels, data-step attributes, and ARIA labels—that remains valid regardless of which visual type renders it.

If animation is requested, the system animates semantic steps defined in skills/diagram-design/references/animation.md rather than geometric transitions. This ensures that motion reinforces meaning rather than merely showing layout changes.

Summary

• Semantic patterns in references/semantic-patterns.md define architectural meaning (behavior, state, risk) and route to compatible visual types.
• Visual types (27 layout grammars in type-*.md files) provide SVG rendering rules but no intrinsic semantics.
• The SKILL.md workflow enforces pattern selection before layout binding, validated by verify-semantic-motion.py.
• Import pipelines strip source colors and map elements to semantic roles (paper, ink, accent) defined in style-guide.md.
• Output contains semantic markup independent of visual type, enabling consistent animation of architectural steps.

Frequently Asked Questions

What is the difference between a semantic pattern and a visual type in Diagram-Design?

A semantic pattern describes the architectural meaning of what you are documenting—such as a security enforcement point or a state transition framework—while a visual type provides the layout grammar (SVG shapes, spacing, and connectors) used to render that meaning. The system selects the pattern first to capture intent, then chooses the visual type that best expresses that intent spatially.

How does Diagram-Design prevent visual styling from corrupting semantic meaning?

During the import phase defined in import-mermaid.md and import-drawio.md, the system discards source colors and visual decorations. It maps these to semantic roles like accent or paper according to style-guide.md. This ensures that a red security boundary in a source file becomes a semantic security annotation in the intermediate representation, not a hardcoded red line in the output.

What validates that semantic patterns are selected before visual types?

The Python script scripts/verify-semantic-motion.py audits skills/diagram-design/SKILL.md to verify two conditions: first, that the instruction to select a semantic pattern appears before any visual type selection; and second, that the routing table in semantic-patterns.md is referenced prior to any type-*.md file references. If the ordering is violated, the script raises validation errors.

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, but this is a recommendation, not a hard constraint. Because the semantic intermediate representation contains no visual specifics—only architectural roles and relationships—the same pattern can theoretically render through different visual types (such as Process or Data Flow) depending on which layout best communicates the specific context.

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