Skip to content

vt-c-mermaid-diagrams-branded

Creates Mermaid diagrams with VisiTrans brand colors and styling. Automatically applies corporate design color schemes (Orange

Plugin: core-standards
Category: Documentation Pipeline
Command: /vt-c-mermaid-diagrams-branded

Mermaid Diagrams with VisiTrans Branding

Overview

This skill creates Mermaid diagrams that automatically follow VisiTrans Corporate Design guidelines. It injects brand-compliant color themes into diagram definitions, ensuring consistency across all technical documentation.

Supported Diagram Types

  • Flowcharts - Process flows, decision trees
  • Sequence Diagrams - Interaction flows, API calls
  • Class Diagrams - System architecture, data models
  • State Diagrams - State machines, workflows
  • Gantt Charts - Project timelines
  • Pie Charts - Data visualization
  • Entity Relationship - Database schemas
  • User Journey - UX flows
  • Git Graphs - Version control workflows
  • C4 Context Diagrams - System context from YAML frontmatter
  • C4 Container Diagrams - Container architecture from YAML frontmatter

Quick Start

Create a Simple Flowchart

python scripts/create_diagram.py \
  --type flowchart \
  --product visitrans \
  --output diagram.mmd \
  --title "API Request Flow"

With Custom Content

python scripts/create_diagram.py \
  --type sequence \
  --product visimatch \
  --output payment-flow.mmd \
  --content "$(cat my-diagram-content.txt)"

VisiTrans Brand Color Themes

Product-Specific Themes

Each VisiTrans product has its own color scheme derived from the corporate design:

VisiTrans (General/Corporate)

Primary: #FC9E00 (Orange)
Secondary: #000000 (Black)
Tertiary: #3F51B5 (Dunkelblau)
Accent: #FFEB3B (Gelb)
Background: #FFFFFF
Text: #000000

VisiMatch (Smart Logistics)

Primary: #FC9E00 (Orange)
Secondary: #3F51B5 (Dunkelblau)
Tertiary: #00697C (Petrol)
Accent: #FFEB3B (Gelb)
Background: #FFFFFF
Text: #000000

VisiFair (Smart Fairgrounds)

Primary: #FC9E00 (Orange)
Secondary: #B2FF59 (Hellgrün)
Tertiary: #3F51B5 (Dunkelblau)
Accent: #FFEB3B (Gelb)
Background: #FFFFFF
Text: #000000

VisiArea (Smart Access)

Primary: #FC9E00 (Orange)
Secondary: #D32F2F (Rot)
Tertiary: #3F51B5 (Dunkelblau)
Accent: #9C27B0 (Lila/Magenta)
Background: #FFFFFF
Text: #000000

Theme Injection

Automatic Theme Configuration

The skill automatically prepends Mermaid theme configuration to all diagrams:

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#FC9E00',
    'primaryTextColor': '#000000',
    'primaryBorderColor': '#000000',
    'lineColor': '#3F51B5',
    'secondaryColor': '#3F51B5',
    'tertiaryColor': '#FFEB3B',
    'background': '#FFFFFF',
    'mainBkg': '#FFFFFF',
    'secondBkg': '#FFF8E1',
    'tertiaryBkg': '#E3F2FD'
  }
}}%%

Manual Theme Customization

For specific needs, you can customize theme variables:

python scripts/apply_theme.py \
  --input diagram.mmd \
  --product visimatch \
  --custom-primary '#FF9800' \
  --output themed-diagram.mmd

Diagram Templates

Template: Flowchart

python scripts/create_from_template.py \
  --template flowchart \
  --product visitrans

Generates: 

%%{init: {'theme':'base','themeVariables':{...}}}%%
flowchart TD
    Start([Start]) --> ProcessA[Process A]
    ProcessA --> Decision{Decision?}
    Decision -->|Yes| ProcessB[Process B]
    Decision -->|No| ProcessC[Process C]
    ProcessB --> End([End])
    ProcessC --> End

Template: Sequence Diagram

python scripts/create_from_template.py \
  --template sequence \
  --product visimatch

Generates: 

%%{init: {'theme':'base','themeVariables':{...}}}%%
sequenceDiagram
    participant Client
    participant API
    participant Database

    Client->>API: Request Data
    API->>Database: Query
    Database-->>API: Results
    API-->>Client: Response

Template: Class Diagram

python scripts/create_from_template.py \
  --template class \
  --product visiarea

Layout Optimization for Portrait Pages

Automatic Width Optimization

Flowcharts are automatically optimized for portrait-oriented pages (aspect ratio 3:4) to ensure diagrams fit well without excessive scaling.

Goal: Create diagrams with aspect ratio of 0.7:1 to 0.9:1 (height:width ratio)

Problem: Standard TD (top-down) flowcharts create very narrow diagrams (aspect ratio ~0.3-0.4) that waste horizontal page space.

Solution: The skill automatically configures Mermaid flowchart spacing to create wider diagrams in TD orientation.

Spacing Configuration

The skill automatically adds flowchart configuration to the Mermaid init block:

{
  'flowchart': {
    'nodeSpacing': 250,    // Increase horizontal spacing between nodes
    'rankSpacing': 25,     // Minimize vertical spacing between ranks
    'padding': 15          // Minimal padding around diagram
  }
}

Results

Before Optimization (Standard TD): - Dimensions: 636×1990 pixels - Aspect ratio: 0.32:1 (very narrow) - File size: 111KB - Problem: Wastes horizontal space on portrait pages

After Optimization (Tuned TD): - Dimensions: 717×964 pixels - Aspect ratio: 0.74:1 ✅ (optimal for portrait) - File size: 48KB - Result: Fits naturally on portrait pages

Manual Direction Override

While TD with width optimization is default, you can still specify other directions:

# Use default TD with width optimization (recommended)
python scripts/create_diagram.py \
  --type flowchart \
  --product visitrans \
  --output diagram.mmd

# Force landscape orientation
python scripts/create_diagram.py \
  --type flowchart \
  --product visitrans \
  --direction LR \
  --output diagram.mmd

Available directions: - TD = Top Down (default, optimized for portrait pages) - LR = Left to Right (landscape, very wide) - RL = Right to Left - BT = Bottom to Top

Page-Friendly Defaults

All flowchart diagrams use TD direction with optimized spacing for portrait pages:

flowchart TD
    Start([Start]) --> Process[Process Step]
    Process --> Decision{Decision?}
    Decision -->|Yes| ActionA[Action A]
    Decision -->|No| ActionB[Action B]
    ActionA --> End([End])
    ActionB --> End

Format Selection Heuristic

Before creating a diagram, check element count to select the right output format:

Element Count Recommended Format Action
< 10 Mermaid Proceed with Mermaid (default)
10–15 Mermaid or PlantUML Ask user which format they prefer
> 15 PlantUML Warn user; generate Mermaid but note layout risk

Why this matters: Mermaid's Dagre layout engine provides limited control over element positioning. For 15+ elements, persistent edge crossings and element overlap can make the diagram unreadable. PlantUML's layout engine handles large graphs significantly better.

PlantUML suggestion (when > 15 elements): Produce the Mermaid output AND display:

"⚠ This diagram has {N} elements. For complex diagrams, PlantUML produces better layouts. Use a PlantUML renderer (e.g., https://www.plantuml.com/plantuml/) to render the source manually, or convert using mmdc or IntelliJ's PlantUML plugin."

Note: This skill does NOT build a PlantUML renderer. The suggestion is informational only.

Automatic check: create_diagram.py invokes count_elements.py automatically when --content is provided, printing a warning to stdout for the 10–15 and 15+ buckets.

Integration with Other Skills

Works With

  • mermaid-to-images: Pass generated .mmd files for PNG conversion
  • visitrans_cd: Validates color compliance
  • markdown-diagram-processor: Embeds diagrams in markdown (with smart scaling)
  • document-converter-branded: Includes diagrams in final documents

Output Format

Default output location: docs/markdown_mermaid/mermaid/*.mmd

Files follow naming convention: {source}_{number}_{type}.mmd

Example: architecture_01_flowchart.mmd

Usage Examples

Example 1: Create VisiMatch Payment Flow

python scripts/create_diagram.py \
  --type flowchart \
  --product visimatch \
  --output visimatch_payment_flow.mmd \
  --description "Payment processing workflow"

User provides content, script adds branding:

Input content: 

flowchart LR
    Customer --> Gateway
    Gateway --> Validation
    Validation --> Processing
    Processing --> Confirmation

Output (with theme): 

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#FC9E00',
    'secondaryColor': '#3F51B5',
    'tertiaryColor': '#00697C',
    ...
  }
}}%%
flowchart LR
    Customer --> Gateway
    Gateway --> Validation
    Validation --> Processing
    Processing --> Confirmation

Example 2: Batch Create Diagrams from Descriptions

python scripts/batch_create.py \
  --input diagram-descriptions.json \
  --product visifair \
  --output-dir docs/markdown_mermaid/mermaid/

Input JSON: 

{
  "diagrams": [
    {
      "name": "visitor-flow",
      "type": "flowchart",
      "description": "Visitor registration and entry flow",
      "content": "flowchart TD\n    Start --> Register\n    ..."
    },
    {
      "name": "booth-assignment",
      "type": "sequence",
      "description": "Booth assignment process",
      "content": "sequenceDiagram\n    ..."
    }
  ]
}

Example 3: Apply Theme to Existing Diagram

python scripts/apply_theme.py \
  --input existing-diagram.mmd \
  --product visiarea \
  --output branded-diagram.mmd

Validation

Brand Compliance Check

After creating diagrams, validate against brand guidelines:

python scripts/validate_diagram.py \
  --input diagram.mmd \
  --strict

Checks: - ✓ Theme configuration present - ✓ Colors match VisiTrans palette - ✓ No accessibility issues (color contrast) - ✓ Proper naming convention

Accessibility Validation

Ensures diagrams meet WCAG AA standards:

python scripts/check_accessibility.py \
  --input diagram.mmd

Validates: - Color contrast ratios (≥4.5:1 for text) - No color-only communication - Clear labels and descriptions

Advanced Features

Custom Color Overrides

For special cases (while staying brand-compliant):

# scripts/create_diagram.py with custom colors
from visitrans_brand import EXTENDED_COLORS

custom_theme = {
    'primaryColor': EXTENDED_COLORS['orange'],
    'secondaryColor': EXTENDED_COLORS['petrol'],
    'tertiaryColor': EXTENDED_COLORS['hellgruen'],
    'accentColor': EXTENDED_COLORS['gelb']
}

Multi-Product Diagrams

For diagrams showing multiple products:

python scripts/create_diagram.py \
  --type flowchart \
  --product visitrans \
  --subproducts visimatch,visifair \
  --output integration-flow.mmd

Uses general VisiTrans colors with subtle product accents.

File Structure

~/.claude/skills/vt-c-mermaid-diagrams-branded/
├── SKILL.md (this file)
├── scripts/
│   ├── create_diagram.py           # Main diagram creation
│   ├── apply_theme.py              # Add/update theme
│   ├── validate_diagram.py         # Brand compliance check
│   ├── check_accessibility.py      # Accessibility validation
│   ├── create_from_template.py     # Template-based creation
│   ├── batch_create.py             # Batch processing
│   └── brand_colors.py             # Color definitions
├── templates/
│   ├── flowchart.mmd
│   ├── sequence.mmd
│   ├── class.mmd
│   ├── state.mmd
│   ├── gantt.mmd
│   └── er.mmd
└── examples/
    ├── visimatch-payment-flow.mmd
    ├── visifair-visitor-journey.mmd
    └── visiarea-access-control.mmd

Best Practices

✅ Do

  • Always specify product context (visitrans, visimatch, visifair, visiarea)
  • Use templates as starting points
  • Validate accessibility for public-facing diagrams
  • Keep diagrams simple and focused
  • Use consistent naming conventions

❌ Don't

  • Hardcode colors (use theme variables)
  • Mix brand colors with non-brand colors
  • Create overly complex diagrams (split into multiple)
  • Skip validation for production diagrams
  • Modify theme after generation (use apply_theme.py)

Error Handling

Common Issues

Issue: Invalid Mermaid syntax 

# Validate syntax before applying theme
python scripts/validate_diagram.py --syntax-only diagram.mmd

Issue: Theme not rendering 

# Re-apply theme
python scripts/apply_theme.py --input diagram.mmd --force

Issue: Colors not brand-compliant 

# Check which colors are off
python scripts/validate_diagram.py --detailed diagram.mmd

Integration Points

Input

  • Plain Mermaid diagram content (no theme)
  • Diagram type specification
  • Product context

Output

  • Branded .mmd files with theme configuration
  • Manifest file with metadata
  • Validation report

Expected By

  • mermaid-to-images skill for PNG generation
  • markdown-diagram-processor skill for embedding
  • docs-pipeline-orchestrator skill for workflows

Complexity-Aware Format Selection

Before generating any diagram, count the total elements (nodes, actors, participants, entities, states) in the diagram content.

Element Count Thresholds

Elements Action
< 10 Generate Mermaid (default). No warning needed.
10–15 Generate Mermaid with layout optimization. Add subgraph grouping to reduce edge crossings. Use rankSpacing: 30 and nodeSpacing: 200. Consider splitting into sub-diagrams if logical groupings exist.
> 15 Warn the user before generating. Mermaid's Dagre layout engine often produces unreadable results at this scale (persistent edge crossings, element overlap). Recommend: (a) split into multiple focused diagrams, (b) use subgraph boundaries to cluster related elements, or (c) simplify by removing less critical edges.

Layout Optimization Techniques (10+ Elements)

When element count exceeds 10, apply these techniques:

  1. Subgraph grouping: Cluster related nodes into subgraph blocks to help Dagre's layout engine
  2. Direction hints: Use TD for hierarchical flows, LR for sequential processes
  3. Edge reduction: Combine parallel edges where semantically equivalent
  4. Label brevity: Shorten node labels to prevent overlap (use tooltips or footnotes for details)

Example — splitting a 20-node architecture into 2 focused diagrams: 

Instead of one monolithic diagram:
  ❌ 20 nodes, 30 edges → unreadable spaghetti

Split into:
  ✅ "Frontend Architecture" (8 nodes) + "Backend Architecture" (12 nodes)
  ✅ Each diagram is clear and readable
  ✅ A simple C4 Context diagram can show the high-level relationship between them

C4 Diagram Generation from YAML

Generate C4 architecture diagrams from structured YAML definitions. Uses Mermaid's built-in C4 syntax (C4Context, C4Container) with VisiTrans branding.

C4 YAML Schema

System documentation files can include a c4: frontmatter block. When present, use it to generate C4 diagrams automatically.

c4:
  system:
    name: "VisiMatch Platform"
    description: "Smart logistics matching platform"
  actors:
    - name: Consignee
      description: Import cargo recipient
      type: person           # person | external_system
    - name: Carrier
      description: Transport service provider
      type: person
    - name: SAP ERP
      description: Enterprise resource planning
      type: external_system
  containers:
    - name: Web Portal
      technology: Angular 21, PrimeNG
      description: User-facing application
    - name: API Gateway
      technology: Node.js, Express
      description: REST API layer
    - name: Matching Engine
      technology: Python, scikit-learn
      description: AI-powered carrier matching
    - name: PostgreSQL
      technology: PostgreSQL 16
      description: Primary data store
  relationships:
    - from: Consignee
      to: Web Portal
      description: Manages shipments via
    - from: Carrier
      to: Web Portal
      description: Views and accepts matches via
    - from: Web Portal
      to: API Gateway
      description: REST calls
    - from: API Gateway
      to: Matching Engine
      description: Triggers matching
    - from: API Gateway
      to: PostgreSQL
      description: Reads/writes data
    - from: SAP ERP
      to: API Gateway
      description: Sends shipment data via EDI

Schema Field Reference

Field Required Description
c4.system.name Yes System name shown in the boundary box
c4.system.description No Description shown below name
c4.actors[].name Yes Actor display name
c4.actors[].description No Actor description
c4.actors[].type No person (default) or external_system
c4.containers[].name Yes Container display name
c4.containers[].technology No Technology stack label
c4.containers[].description No Container description
c4.relationships[].from Yes Source actor or container name
c4.relationships[].to Yes Target actor or container name
c4.relationships[].description No Relationship label

C4 Context Diagram Generation

From the YAML above, generate a C4Context diagram showing actors and the system boundary:

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#FC9E00',
    'primaryTextColor': '#000000',
    'primaryBorderColor': '#000000',
    'lineColor': '#3F51B5',
    'secondaryColor': '#3F51B5',
    'tertiaryColor': '#FFEB3B'
  }
}}%%
C4Context
    title VisiMatch Platform — System Context

    Person(consignee, "Consignee", "Import cargo recipient")
    Person(carrier, "Carrier", "Transport service provider")
    System_Ext(sap, "SAP ERP", "Enterprise resource planning")

    System_Boundary(visimatch, "VisiMatch Platform") {
        System(platform, "VisiMatch", "Smart logistics matching platform")
    }

    Rel(consignee, platform, "Manages shipments via")
    Rel(carrier, platform, "Views and accepts matches via")
    Rel(sap, platform, "Sends shipment data via EDI")

C4 Container Diagram Generation

From the same YAML, generate a C4Container diagram showing internal containers:

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#FC9E00',
    'primaryTextColor': '#000000',
    'primaryBorderColor': '#000000',
    'lineColor': '#3F51B5',
    'secondaryColor': '#3F51B5',
    'tertiaryColor': '#FFEB3B'
  }
}}%%
C4Container
    title VisiMatch Platform — Container Diagram

    Person(consignee, "Consignee", "Import cargo recipient")
    Person(carrier, "Carrier", "Transport service provider")
    System_Ext(sap, "SAP ERP", "Enterprise resource planning")

    Container_Boundary(visimatch, "VisiMatch Platform") {
        Container(web, "Web Portal", "Angular 21, PrimeNG", "User-facing application")
        Container(api, "API Gateway", "Node.js, Express", "REST API layer")
        Container(engine, "Matching Engine", "Python, scikit-learn", "AI-powered carrier matching")
        ContainerDb(db, "PostgreSQL", "PostgreSQL 16", "Primary data store")
    }

    Rel(consignee, web, "Manages shipments via")
    Rel(carrier, web, "Views and accepts matches via")
    Rel(web, api, "REST calls")
    Rel(api, engine, "Triggers matching")
    Rel(api, db, "Reads/writes data")
    Rel(sap, api, "Sends shipment data via EDI")

C4 Generation Rules

  1. Actor mapping: type: person → Person(), type: external_system → System_Ext()
  2. Container mapping: Regular containers → Container(), databases (name contains "DB", "database", "PostgreSQL", "MySQL", "Redis", "Mongo") → ContainerDb()
  3. ID generation: Lowercase the name, remove spaces, truncate to 20 chars (e.g., "API Gateway" → apigateway)
  4. Brand colors: Always apply the product-appropriate VisiTrans theme from the themes section above
  5. Title format: {system.name} — {Context|Container} Diagram

Post-Render Validation Gate

After rendering a diagram to PNG (via mermaid-to-images or mmdc), perform a visual quality check:

  1. Read the rendered PNG using the Read tool (multimodal image reading)
  2. Check 6 criteria:
  3. Labels are readable (not truncated or overlapping)
  4. Nodes are distinguishable (not stacked on top of each other)
  5. Edge crossings are minimal (target: <5 for complex diagrams, 0 for simple)
  6. All elements from the source definition appear in the render
  7. Colors render correctly (brand colors not garbled)
  8. Overall layout is balanced (no single node far away from the cluster)
  9. If any criterion fails: revise the Mermaid source (adjust layout direction, add spacing, simplify labels) and re-render
  10. Max 3 iterations to prevent infinite loops. If still failing after 3, output the best result with a warning noting which criteria remain unsatisfied.

Skip this gate for draft/preview renders or when the user explicitly requests fast output.

Version History

  • v1.0 (2025-10-23): Initial release with VisiTrans brand themes
  • Supports: VisiTrans, VisiMatch, VisiFair, VisiArea
  • Compatible with: Mermaid 10.2.4+

Post-Render Validation (Optional)

After rendering a diagram to PNG, run /vt-c-diagram-validate to check quality: - Inspects 6 criteria: element accuracy, relationships, readability, abstraction, style, edge crossings - Auto-revises on failure (max 3 attempts) if Mermaid source is provided - Recommends PlantUML for complex diagrams (>15 elements)

To skip validation for quick iterations, pass --skip to the validation skill.

References

  • VisiTrans brand guidelines: See visitrans_cd skill
  • Mermaid documentation: https://mermaid.js.org/
  • WCAG accessibility: https://www.w3.org/WAI/WCAG21/quickref/