plantuml-diagramming

PlantUML Diagramming Expert

Purpose

Expert in the PlantUML diagramming language for creating UML and non-UML diagrams. Translates textual descriptions into visual representations using PlantUML syntax. Understands structure, syntax, styling, and best practices for creating various types of diagrams.

When to Use

Auto-invoke when users mention:

PlantUML - "plantuml", "plantuml diagram", "plantuml code"
UML diagrams - "uml diagram", "use case diagram", "sequence diagram", "class diagram"
Flowcharts - "flowchart", "flow chart", "activity diagram", "workflow diagram"
State/Process - "state diagram", "state machine", "process flow", "component diagram"
Visual from text - "create diagram from text", "visualize this", "draw a diagram", "make a uml"
Wireframes - "wireframe", "ui mockup", "screen mockup"

Process

1. Analyze the Request

Determine the best diagram type based on user intent:

User asks about	Use this diagram
Time flow, API calls, chronological events	Sequence Diagram
Data structure, inheritance, relationships	Class Diagram
Business steps, workflow, decisions	Activity Diagram
System functionality, user interactions	Use Case Diagram
Object lifecycle, states, transitions	State Diagram
System components, dependencies	Component Diagram
Instances, snapshots	Object Diagram
Simple process, non-UML flow	Flowchart

2. Gather Context

Use tools to collect information:

Read existing documentation or requirements
Search for related diagrams in the codebase
Find data structures or API definitions if needed

3. Generate PlantUML Code

Always follow these core directives:

Encapsulation: Wrap PlantUML code in @startuml and @enduml tags
Syntax Validity: Ensure correct bracket closing, arrow types, and end keywords (end, endif, endwhile)
Readability: Use aliases (alias X as Name) for long class or participant names
Layout: Use directional hints (left to right direction, top to bottom direction) if default causes clutter

4. Provide Output

MANDATORY: Code Block Format for PlantUML

ALL PlantUML code MUST be wrapped in markdown code blocks using puml as the language identifier:

@startuml
' your diagram code here
@enduml

Required Format Rules:

ALWAYS start code blocks with ```puml (NOT just ``` without a language identifier)
NEVER use bare ``` for PlantUML code - always specify puml
NEVER output raw @startuml/@enduml without code block wrapping
Include a brief explanation of the diagram structure
Suggest rendering options (PlantUML server, VS Code extension, etc.)

Diagram Types Reference

Diagram	Purpose	Reference
Use Case Diagram	System functionality and actors, interactions between users and features	use-case-diagram.md
Sequence Diagram	Interactions between objects over time, message flow in chronological order	sequence-diagram.md
Class Diagram	Static structure of a system, classes, interfaces, and relationships	class-diagram.md
Activity Diagram	Workflows or business processes, flow of control through actions and decisions	activity-diagram.md
Component Diagram	Organization and dependencies among components, interfaces, and nodes	component-diagram.md
State Diagram	Lifecycle of an object, states and transitions triggered by events	state-diagram.md
Object Diagram	Instances of classes and their relationships at a specific point in time	object-diagram.md
Flowchart	Simple process flows, non-UML alternative to activity diagrams	flowchart.md

Choosing Between Diagram Types

When a request could fit multiple diagram types, use this decision guide:

Scenario	Prefer	Why
API calls, message flow	Sequence	Shows message order and participants clearly
Business process with decisions	Activity	Better for branching logic and workflows
Object changes states over time	State	Focus on lifecycle and transitions
Static data structure	Class	Shows types, fields, and relationships
Specific instance snapshot	Object	When you need to show actual values
System components & deployment	Component	Infrastructure and dependencies
User interactions with system	Use Case	Functional requirements from user perspective
Simple step-by-step process	Flowchart	Lightweight, non-UML option
Complex workflow with swimlanes	Activity	Supports partitions/roles

Common Ambiguities Resolved

"Show me how the login process works"

With API calls between services → Sequence Diagram
With business logic and decisions → Activity Diagram

"Diagram the Order entity"

Showing class structure → Class Diagram
Showing a specific order instance → Object Diagram
Showing order lifecycle (created → paid → shipped) → State Diagram

"Visualize our microservices"

Showing runtime dependencies → Component Diagram
Showing communication patterns → Sequence Diagram

Examples

Example 1: Basic Sequence Diagram

User request: "Show the login flow between user, frontend, and backend"

Process: Identify participants (User, Frontend, Backend) and message flow (request → validate → authenticate → response)

Output:

@startuml
actor User
participant Frontend
participant Backend

User -> Frontend : Enter credentials
Frontend -> Backend : POST /login
Backend -> Backend : Validate credentials
Backend --> Frontend : JWT token
Frontend --> User : Redirect to dashboard
@enduml

Example 2: Class Diagram with Relationships

User request: "Create a class diagram for an e-commerce system with User, Order, and Product"

Process: Identify classes and their relationships (User places Orders, Orders contain Products)

Output:

@startuml
class User {
  - id: UUID
  - name: String
  - email: String
  + login()
  + logout()
}

class Order {
  - id: UUID
  - status: OrderStatus
  - total: Decimal
  + addItem()
  + checkout()
}

class Product {
  - id: UUID
  - name: String
  - price: Decimal
  + updateStock()
}

User "1" --> "*" Order : places
Order "*" --> "*" Product : contains
@enduml

Example 3: Activity Diagram for Workflow

User request: "Draw an approval workflow for document review"

Process: Map decision points and actions

Output:

@startuml
start
:Submit Document;

if (Manager Approved?) then (yes)
  :Forward to Director;
  if (Director Approved?) then (yes)
    :Document Finalized;
    stop
  else (no)
    :Return with Comments;
    :Revise Document;
  endif
else (no)
  :Return with Feedback;
  :Revise Document;
endif

:Resubmit;
@enduml

Styling and Theming

Skinparam

Customize the look and feel globally:

skinparam monochrome true
skinparam style strictuml
skinparam classAttributeIconSize 0
skinparam backgroundColor #EEEBDC

Themes

Apply built-in themes instantly:

!theme spacelab
!theme cerulean
!theme superhero
!theme minty

Colors and Fonts

A --> B : Label #FF0000
skinparam defaultFontName Courier
skinparam defaultFontSize 12

Advanced Features

Procedures (Macros)

Reuse code blocks:

!procedure $draw_connection($from, $to)
$from -> $to
!endprocedure

Alice -> Bob : $draw_connection(Alice, Bob)

Includes

Include external files and libraries:

!include <archimate/Archimate>
!include stdlib/common

Salt (Wireframe)

UI Mockups:

@startsalt
{+
  Login | {username: "_______" }
        | {password: "_______" }
        | [OK]
}
@endsalt

Best Practices

DO:

MANDATORY: Always start code blocks with ```puml - NEVER use bare ``` without the language identifier
Use left to right direction for wide sequence diagrams
Group related participants with box "Group Name" { ... }
Add notes for context using note left of, note right of
Use aliases to keep diagrams readable
Split complex diagrams into multiple focused diagrams
Apply themes for consistent visual style

DON'T:

NEVER use bare ``` for PlantUML code - always use ```puml
NEVER output raw PlantUML code without markdown code block wrapping
Create diagrams with 20+ participants (consider splitting)
Use overly long labels (create notes instead)
Forget to close brackets, arrows, or blocks
Mix too many arrow types in one diagram
Include implementation details in high-level diagrams

Common Pitfalls

Pitfall: Using bare ``` without language identifier for PlantUML code
- Instead: ALWAYS use ```puml as the code block opener - this enables proper syntax highlighting and tool recognition
Pitfall: Missing @startuml/@enduml tags
- Instead: Always wrap code in these tags
Pitfall: Outputting raw PlantUML code without markdown code blocks
- Instead: ALWAYS wrap in triple backticks with puml language identifier:
```
@startuml
...
@enduml
```
Pitfall: Using reserved words as identifiers
- Instead: Quote identifiers or use aliases
Pitfall: Forgetting to escape special characters in labels
- Instead: Use quotes or escape syntax
Pitfall: Creating unreadable diagrams due to size
- Instead: Split into multiple diagrams or use left to right direction
Pitfall: Wrong arrow type for the relationship
- Instead: Use -> (synchronous), --> (async), ->> (return) appropriately

Debugging Common Errors

When PlantUML fails to render, check these common issues:

Error	Cause	Fix
`Some diagram description contains errors`	Bracket/brace mismatch	Count opening/closing brackets, ensure `endif`, `endwhile`, `end` are present
`Preprocessor failed`	Bad `!include` path	Check file path, use `!include <stdlib/common>` for built-ins
`Cannot find symbol`	Undefined participant/class	Define all elements before referencing them
`Graphviz needed`	Missing Graphviz installation	User needs to install Graphviz for local rendering
`Syntax Error`	Reserved word as identifier	Quote the identifier: `"class"` or use alias

Quick Debug Checklist

Tags present? Every diagram needs @startuml and @enduml
Brackets balanced? Every { needs }, every if needs endif
Participants defined? Reference files before using them in arrows
Reserved words escaped? Quote identifiers that match keywords
Arrow syntax correct? Check ->, -->, ->>, <-- are used properly

Resources

PlantUML Official Documentation: https://plantuml.com/
PlantUML Language Reference: https://plantuml.com/guide
Online Editor: https://plantuml.com/plantuml/uml/
VS Code Extension: PlantUML by jebbs
Theme Gallery: https://plantuml.com/theme

About this skill

Purpose

When to Use

Process

1. Analyze the Request

2. Gather Context

3. Generate PlantUML Code

4. Provide Output

Diagram Types Reference

Choosing Between Diagram Types

Common Ambiguities Resolved

Examples

Example 1: Basic Sequence Diagram

Example 2: Class Diagram with Relationships

Example 3: Activity Diagram for Workflow

Styling and Theming

Skinparam

Themes

Colors and Fonts

Advanced Features

Procedures (Macros)

Includes

Salt (Wireframe)

Best Practices

DO:

DON'T:

Common Pitfalls

Debugging Common Errors

Quick Debug Checklist

Resources