Presentation Diagrams

Presentation Diagrams

Child of presentation-builder. Generates architecture diagrams, flowcharts, sequence diagrams, and system visuals for embedding into presentation slides.

Sibling Skills

• presentation-narrative — Outline generation, storytelling structure, slide sequencing
• presentation-datavis — Charts, data visualization, data-driven slides
• presentation-styling — Templates, branding, colour palettes, typography
• presentation-renderer — Final assembly, PPTX/HTML export, format conversion

When NOT to Use This Skill

1. Tool Selection

Select the rendering tool based on the diagram's purpose. Priority order:

1. mermaid-cli (mmdc) — Deterministic flowcharts, sequence diagrams, ER diagrams, state diagrams, class diagrams, Gantt charts
2. graphviz (dot) — Architecture/topology diagrams, network diagrams, complex directed/undirected graphs
3. plantuml — UML-specific diagrams (activity, component, deployment) when Mermaid lacks coverage
4. vertex-banana (AI image gen) — Cover art, illustrative visuals, icons, conceptual images ONLY
5. ASCII art — Always works, zero dependencies; use as last resort or for quick inline previews

Critical Rules

• Deterministic renderers (mermaid, graphviz, plantuml) for: architecture diagrams, flowcharts, sequence diagrams, ER diagrams, class diagrams, state diagrams, network diagrams — anything with precise labels and connections.
• AI image generation (vertex-banana) ONLY for: cover art, illustrative visuals, icons, conceptual images that do not require precise text labels.
• NEVER use AI image generation for architecture diagrams, flowcharts, sequence diagrams, or anything requiring precise text labels. Deterministic renderers only.

2. Diagram Type Routing

When the capability map (from presentation-builder) shows a tool is unavailable, fall back to the next available tool in the priority list. If no renderer is available, generate ASCII art.

3. Auto-Generation from Project Context

When a project context exists, automatically generate diagrams from available artifacts:

Process

1. Read the source artifact(s).
2. Extract entities, relationships, and data flows.
3. Select the appropriate diagram type from the routing table above.
4. Generate the diagram source file (.mmd, .dot, or .puml).
5. Render to the output format (.svg preferred, .png fallback).
6. Return file paths for presentation-renderer to embed.

4. Generation Patterns

Mermaid

# Write the diagram source
cat > .presentations/output/assets/diagram-name.mmd << 'EOF'
graph TD
    A[Service A] --> B[Service B]
    B --> C[(Database)]
EOF

# Render to SVG (dark theme for dark slide backgrounds)
npx @mermaid-js/mermaid-cli -i .presentations/output/assets/diagram-name.mmd \
    -o .presentations/output/assets/diagram-name.svg \
    -t dark

# Or default theme for light slide backgrounds
npx @mermaid-js/mermaid-cli -i .presentations/output/assets/diagram-name.mmd \
    -o .presentations/output/assets/diagram-name.svg \
    -t default

Graphviz

# Write the diagram source
cat > .presentations/output/assets/diagram-name.dot << 'EOF'
digraph architecture {
    rankdir=LR;
    node [shape=box, style=filled, fillcolor="#e8e8e8", fontsize=14];

    ServiceA -> ServiceB [label="REST"];
    ServiceB -> Database [label="SQL"];
    Database [shape=cylinder];
}
EOF

# Render to SVG
dot -Tsvg .presentations/output/assets/diagram-name.dot > .presentations/output/assets/diagram-name.svg

PlantUML

# Write the diagram source
cat > .presentations/output/assets/diagram-name.puml << 'EOF'
@startuml
component "Service A" as A
component "Service B" as B
database "Database" as DB

A --> B : REST
B --> DB : SQL
@enduml
EOF

# Render (requires plantuml.jar or plantuml CLI)
plantuml -tsvg .presentations/output/assets/diagram-name.puml

AI Image Generation (Creative Visuals Only)

Invoke the vertex-banana skill for illustrative visuals, cover art, or conceptual images. Never for architecture or labeled diagrams.

Output Location

All outputs are saved to:

<project>/.presentations/output/assets/

Both the source file (.mmd, .dot, .puml) and the rendered output (.svg, .png) are saved side by side.

5. Diagram Styling

Palette Matching

• Query presentation-styling for the active colour palette before rendering.
• Apply palette colours to node fills, borders, and connection lines.
• If no palette is set, use a clean neutral palette (greys, blues, whites).

Shape Conventions

Readability Rules

• Labels must be readable at slide size: 12pt+ equivalent font size in rendered output.
• Clean, minimal style — no decorative borders, shadows, or gradients.
• Use whitespace and grouping (subgraphs, clusters) to separate logical domains.
• Connection labels should be concise (1-3 words): protocol, data type, or action.
• Limit nodes per diagram to ~15. Split into multiple diagrams if more complex.

Theme Selection

• Use -t dark (Mermaid) or dark-background colours when slides use a dark theme.
• Use -t default (Mermaid) or light-background colours when slides use a light theme.
• Match the theme to the presentation palette from presentation-styling.

6. Hard Rules

1. Never use AI image generation for architecture diagrams. Deterministic renderers only for anything with labels, connections, or structural meaning.
2. Always label all nodes and connections. Unlabeled nodes or unnamed arrows are not permitted.
3. Diagrams must be self-explanatory without speaker notes. A viewer should understand the diagram without additional verbal context.
4. Save both source and rendered output. Always keep the source file (.mmd, .dot, .puml) alongside the rendered file (.svg, .png) so diagrams can be edited later.
5. Return file paths for presentation-renderer to embed. Every generated diagram must report its output path so the renderer can include it in the final deck.
6. One concept per diagram. Do not overload a single diagram. Split complex systems into multiple focused diagrams.
7. Verify rendering succeeded. After running the render command, confirm the output file exists and has non-zero size before reporting success.

Anti-Patterns