Semantic Patterns vs. Visual Types in Diagram-Design: Understanding Meaning and Layout

Semantic patterns define the underlying behavior and governance model of a diagram (what it means), while visual types provide the concrete SVG layout grammar (how it renders), and the diagram-design workflow requires selecting the semantic pattern before choosing a compatible visual type.

The cathrynlavery/diagram-design repository enforces a strict separation between meaning and presentation to prevent taxonomy inflation and ensure semantic integrity. Understanding how semantic patterns differ from visual types is essential for creating diagrams that carry rich behavioral metadata while maintaining correct geometric layouts.

What Are Semantic Patterns?

Semantic patterns capture the underlying behavior, state, or governance that a diagram must convey. According to [semantic-patterns.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md), these patterns define reusable behavioral models—such as traceable block decomposition—that record inputs, outputs, constraints, and implementation paths as metadata attributes.

Each pattern supplies semantic primitives through metadata attributes prefixed with data-block-*. These attributes populate the Stage framework with semantic slots, allowing the diagram to carry behavior-specific constraints such as block-level IDs and traceability requirements. Crucially, semantic patterns do not dictate rendering; they only supply the "what" (the meaning) that must be visualized.

What Are Visual Types?

Visual types (also called "types" or "layout grammars") provide the concrete SVG-compatible visual grammar that renders the diagram. As documented in [SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), visual types such as trees, flowcharts, and polar charts dictate the placement of nodes, the routing of connectors, and the specific SVG primitives used for display.

Unlike semantic patterns, visual types serve as the structural canvas. They consume the metadata attributes supplied by patterns to produce the final layout but do not alter the underlying semantics. The [type-tree.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/type-tree.md) reference details how the hierarchical tree layout handles semantic primitives without modifying their behavioral context.

Key Differences Between Semantic Patterns and Visual Types

The architecture separates concerns into two distinct layers:

• Semantic patterns answer "what" the diagram represents. They define behavioral models, governance steps, and metadata constraints using the Stage framework.
• Visual types answer "how" the diagram appears. They control SVG routing algorithms, node positioning, and geometric primitives.

This separation allows you to apply the same traceable-block-decomposition pattern to a tree layout, a flowchart, or a polar chart without changing the underlying meaning. The pattern enriches the visual type with metadata, while the visual type provides the rendering engine that interprets that metadata spatially.

The Pattern-First Workflow

The diagram-design CLI enforces a mandatory selection order to maintain semantic integrity. As specified in [SKILL.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) section 3, you must choose a semantic pattern first if your diagram involves repeated questions, inputs, governance steps, or outputs across stages.

Step 1: Select the Semantic Pattern

Choose a pattern that matches your behavioral requirements. For example, use traceable-block-decomposition when you need to track inputs, outputs, and constraints through a decomposition hierarchy, including specific constraints like latency ≤ 200ms.

Step 2: Choose a Compatible Visual Type

Select the nearest visual type that can display the semantic primitives your pattern provides. The visual type supplies the layout grammar (tree, process, polar) but cannot modify the semantics.

# Example: Traceable block decomposition (semantic pattern) with tree layout

# Load the semantic pattern

pattern: traceable-block-decomposition

# Select visual type for hierarchical data

type: tree

# Provide block metadata (inputs, outputs, constraints)

blocks:
  - id: PAY-001-01
    name: Fraud Screening
    input: raw-transactions
    output: screened-transactions
    constraint: latency ≤ 200ms

Step 3: Generate the Diagram

Combine the pattern metadata with the visual layout using the CLI:

diagram-design draw \
  --pattern traceable-block-decomposition \
  --type tree \
  --data blocks.yaml \
  --output diagram.svg

In this workflow, the pattern supplies the data-block-* attributes that the tree visual type consumes, producing an SVG that maintains both semantic richness and correct hierarchical layout.

Why This Separation Matters

This architectural decision prevents taxonomy inflation while supporting unlimited behavioral extensions. As documented in [docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0002-semantic-patterns-do-not-expand-the-taxonomy.md) (see lines 7-14), the project explicitly caps the count of distinct layout grammars (visual types) while allowing new behaviors to be added through semantic patterns.

The validation script scripts/verify-semantic-motion.py enforces this boundary, ensuring that patterns enrich existing visual types without creating new layout grammars. This keeps the visual type taxonomy stable—preventing the proliferation of similar layout variants—while allowing domain-specific behaviors to evolve independently.

Summary

• Semantic patterns define behavioral meaning, governance models, and metadata constraints using attributes like data-block-*, independent of layout.
• Visual types provide SVG layout grammars (tree, flowchart, polar) that render semantic primitives geometrically without altering their meaning.
• The workflow requires selecting the semantic pattern first, then choosing a compatible visual type that can display the pattern's metadata slots.
• This separation prevents visual type proliferation (maintaining a capped taxonomy per ADR 0002) while supporting unlimited semantic extensions.

Frequently Asked Questions

What is the correct order for selecting patterns and types in diagram-design?

You must choose the semantic pattern first, then select the visual type that can display its primitives. This pattern-first workflow, documented in SKILL.md section 3, ensures that behavioral metadata and governance constraints are defined before any layout decisions are made.

Can I use multiple visual types with the same semantic pattern?

Yes. The same traceable-block-decomposition pattern can render as a tree, flowchart, or other compatible layout. The visual type changes the geometry and connector routing, but the underlying inputs, outputs, and traceability constraints remain semantically identical.

Where are semantic patterns defined in the repository?

All supported semantic patterns, their semantic slots, and required metadata attributes are defined in [skills/diagram-design/references/semantic-patterns.md](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/semantic-patterns.md). This file specifies the Stage framework integration and behavior-specific constraints for each pattern.

How does diagram-design prevent having too many visual types?

The project caps the taxonomy of layout grammars as documented in ADR 0002. New behaviors are added through semantic patterns rather than new visual types, ensuring the count of distinct SVG layout grammars remains stable. The scripts/verify-semantic-motion.py script validates that patterns do not illegally expand the visual type taxonomy.

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