Universal Anti-Patterns to Avoid in Diagram Design

Diagram design anti-patterns are visual or semantic choices that dilute clarity, mislead readers, or break automated validation gates, ranging from unnecessary diagrams that add noise to bottlenecks hidden by equal-width pipelines.

The cathrynlavery/diagram-design repository separates what a system does (semantic patterns) from how it is laid out (visual types), codifying strict rules that prevent common design failures. Mastering these universal anti-patterns ensures your diagrams communicate architectural intent without triggering CI failures in verification scripts like scripts/verify-deployment.py.

General Anti-Patterns: When Not to Draw

The most fundamental anti-pattern appears in skills/diagram-design/SKILL.md: drawing a diagram when a paragraph, table, or list would be clearer. This choice adds visual noise without providing additional insight, violating the repository’s principle that diagrams must earn their space through structural complexity that text cannot convey.

Semantic Pattern Anti-Patterns

Semantic patterns in skills/diagram-design/references/semantic-patterns.md define how systems behave, and each carries specific failure modes that obscure rather than clarify system behavior.

Fan-In Queue Bottleneck Mistakes

The fan-in queue pattern exposes contention points, but several anti-patterns hide the very bottlenecks the diagram should reveal:

• Equal-width pipelines that conceal traffic volume differences
• Merging arrows before they can be traced to sources
• Implying capacity only by box size instead of explicit numeric labels
• Decorative pile-ups and animations that change item order
• Using red to indicate overload without accompanying numeric labels

These violations cause scripts/verify-semantic-motion.py to fail with flags like “Equal-width pipeline that hides contention.”

Stage Framework Violations

The stage framework requires each stage to use the same slot grid with explicit labels. Breaking this rule includes:

• Inventing different internal layouts per stage
• Encoding slot meaning by position alone without labels
• Adding fake precision with dozens of cells
• Mixing stage order with ownership lanes
• Shrinking text to fit a canvas instead of respecting the nine-node budget

Unstructured Input Transformations

When mapping unstructured input to structured artifacts, avoid:

• “AI magic” sparkles between boxes that misrepresent automated processes
• Showing artifacts as chat bubbles instead of concrete data structures
• Fields appearing without source provenance
• Inventing certainty for missing facts
• Using typing animation as the only readable content

These choices destroy traceability and misrepresent transformation processes.

Paired Policy-Evaluation Traces

For policy comparison diagrams, anti-patterns include:

• Comparing independently ordered flows that prevent direct comparison
• Using color-only status dots without semantic labels
• Conflating “skipped” and “not reached” states
• Highlighting every difference instead of just the divergence point
• Continuing a denied trace as if downstream rules executed

These obscure the exact point of divergence and mislead about policy outcomes.

Deployment Diagram Anti-Patterns

skills/diagram-design/references/type-deployment.md defines the most commonly violated universal anti-patterns, each checked by scripts/verify-deployment.py.

Logical Architecture Redraws

The most common deployment anti-pattern is redrawing logical architecture with hostnames bolted on. If no physical placement decision is visible, the diagram belongs in type-architecture.md instead. Deployment diagrams must show concrete topology decisions, not just decorated logic.

Zone and Version Violations

• Zones without real boundaries: Visual groupings must convey genuine environment or network boundaries (prod, staging, dev), not just aesthetic clustering.
• Artifact chips without version tags: The version is the primary reason for a deployment diagram; an un-versioned chip is a wasted box that fails validation.

Layout and Labeling Mistakes

• One node per replica: Violates the nine-node budget rule from SKILL.md §6. Use a replica badge (e.g., “x3”) instead of duplicating nodes.
• Icon soup: Filling diagrams with vendor icons instead of naming hosts/services undermines concrete topology communication.
• Unlabelled network paths: Protocol and port are core data; unlabeled paths become decoration.
• Mixed environments: Combining staging and production without explicit zone boundaries creates confusion about artifact placement.

Validating Your Diagrams

The repository enforces these rules through automated verification scripts. Run these locally before committing:

# Validate deployment diagrams

python3 scripts/verify-deployment.py my-deployment.html

# Validate semantic motion diagrams

python3 scripts/verify-semantic-motion.py my-queue.mmd

Correct Deployment Example

# Generate from template

cp skills/diagram-design/assets/template.html my-deployment.html

# Edit adhering to conventions:

# - Use ≤3 zones with real environment names (prod, staging, dev)

# - Place infrastructure nodes inside zones using the node-box pattern

# - Add artifact chips with version tags (e.g., "service-api v2.4.1")

# - Show replica count with badges (e.g., "x3"), not separate nodes

# - Label every network path with protocol:port (e.g., "HTTPS:443")

# - Limit accent elements to ≤2

Incorrect Deployment Example

graph LR
    subgraph Prod
        A[host-a] --> B[host-b] --> C[service-api]
    end
    A --> D[service-api]
    A -.-> B

This triggers multiple validation errors: no zone boundaries, missing version tags, separate nodes for replicas, and unlabelled network paths.

Correct Fan-In Queue Example

/diagram-design:import-mermaid my-queue.mmd --detail=balanced

Ensure my-queue.mmd contains:

• Clearly labeled sources
• Numeric capacity on bottleneck nodes (e.g., “capacity = 5 req/s”)
• No equal-width pipelines
• Highlighted bottleneck with accent color
• ≤9 nodes total

Incorrect Fan-In Queue Example

flowchart LR
    A -->|8 req/s| B
    C --> B
    D --> B
    style B fill:#f00,stroke:#000

This fails validation due to equal-width pipelines hiding contention, missing capacity labels, and decorative red coloring without numeric context.

Summary

• Avoid unnecessary diagrams: Use text or tables when structural relationships are simple, as mandated in SKILL.md.
• Respect semantic constraints: Never hide bottlenecks with equal-width pipelines or represent AI processes with decorative sparkles.
• Follow deployment rules: Always include version tags, use replica badges instead of duplicate nodes, and label every network path with protocol and port.
• Validate before shipping: Run verify-deployment.py and verify-semantic-motion.py to catch anti-patterns before CI fails.

Frequently Asked Questions

What is the most common deployment diagram anti-pattern?

According to skills/diagram-design/references/type-deployment.md, the most common violation is redrawing logical architecture with hostnames bolted on. This occurs when diagrams show physical hostnames without displaying actual placement decisions, conflating logical architecture with deployment topology. Such diagrams should be reclassified under type-architecture.md instead.

How do equal-width pipelines create anti-patterns in fan-in queue diagrams?

Equal-width pipelines hide contention by visually suggesting all incoming flows carry equal volume, when the pattern’s purpose is to expose bottlenecks. The semantic-patterns.md documentation requires showing capacity with numeric labels (e.g., “capacity = 5 req/s”) and using varying widths or accent colors to distinguish traffic volumes. Verification scripts flag equal-width designs as hiding contention.

Why must deployment diagrams use replica badges instead of multiple nodes?

Drawing one node per replica violates the nine-node budget defined in SKILL.md and inflates complexity beyond human parsing limits. Replica badges (e.g., “x3”) consolidate this information into a single node, keeping diagrams within the complexity budget while clearly communicating scale. The verify-deployment.py script explicitly checks for this anti-pattern.

Which verification scripts enforce these anti-pattern rules?

The repository provides scripts/verify-deployment.py for deployment-specific checks and scripts/verify-semantic-motion.py for semantic pattern validation. These scripts parse diagram files and fail CI when they detect violations like unlabelled network paths, missing version tags, or hidden bottlenecks. Run them locally to ensure diagrams pass automated gates before submission.

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