Plantuml

PlantUML Diagram Generator

Generate professional PlantUML diagrams from natural language descriptions. This skill handles the full pipeline: requirement analysis → PlantUML code generation → image rendering.

Trigger Phrases

Use this skill when the user asks to:

• "Generate/draw/create a PlantUML diagram for..."
• "Create a sequence/class/activity/... diagram showing..."
• "Visualize this flow/architecture/process as..."
• "Turn this description into a UML diagram"
• "Make a flowchart / ERD / Gantt chart from..."
• Any request involving diagram generation from text descriptions

Mandatory Style Requirements

ALL diagrams generated by this skill MUST adhere to the uml-diagrams.org reference style — strict OMG UML 2.x rendered with Visio UML 2.x stencils (black-and-white, no decoration). This is the canonical style used throughout https://www.uml-diagrams.org and serves as the authoritative visual reference for every diagram this skill produces. No exceptions unless the user explicitly requests otherwise.

• Black and white only: Pure black lines (#000000) on a pure white background (#FFFFFF). No colors, no grayscale fills, no gradients, no themed accents.
• Thin uniform line weight: All borders, arrows and connectors use the default hair-line stroke (≈0.75pt). Never thicken or stylize lines.
• No circle visibility icons: Class attributes MUST NOT show colored circle icons (● public / ◐ protected / ○ private). Enforced via skinparam classAttributeIconSize 0. Use + - # ~ text markers only.
• No circle stereotype icons: Class and interface headers MUST NOT show circle-with-letter icons (Ⓒ / Ⓘ / Ⓐ / Ⓔ). Instead of relying on skinparam style strictuml (which degrades actors into plain text and use cases into rectangles — see Common Failure Patterns), we suppress the circle adornments purely at the syntax level: always declare interfaces / abstract classes / enumerations via a class <> / class <> / class <> text stereotype — never use the interface / abstract class / enum keywords, which are what trigger the circle icons in the first place.
• Abstract classifiers in italics: Per UML 2.5 §9 and uml-diagrams.org "Name of an abstract classifier is shown in italics" — the <> text stereotype combined with {abstract} method markers renders correctly without needing strictuml.
• No 3D effects: Drop shadows MUST be disabled (skinparam shadowing false).
• Clean typography: Sans-serif font (Helvetica, equivalent to the Arial used by Visio stencils on uml-diagrams.org), 12pt default. No colored or bold text except diagram titles. When CJK characters are present, use --cjk flag to switch to a CJK-compatible font (see CJK Font Support).
• Aspect ratio: Generated diagrams are automatically validated for an aspect-ratio band. By default the renderer tries to keep width/height between 0.7 and 1.4 (a comfortable page-like shape), re-rendering with layout corrections when the output falls outside that band. Diagrams that cannot be fixed safely after a few attempts are kept with a warning, so unusual diagrams are not destroyed. Use --no-fix to disable this behavior (see Step 3).
• A4 paper fit: After aspect-ratio validation passes, the diagram is checked against A4 paper (210×297 mm). At the 96 DPI CSS standard, this works out to 794×1123 px portrait and 1123×794 px landscape. The renderer accepts the diagram if it fits in EITHER orientation; otherwise it injects a computed PlantUML scale N directive and re-renders up to once. The default body font of 12 px (from the mandatory preamble) shrinks proportionally; if the estimated on-paper font drops below --min-font-pt (default 8 pt), the script prints a legibility warning — at that point no further down-scaling helps and the user must split the diagram or abbreviate labels. A4 fit is ON by default; disable with --no-a4-check.
• Standard UML shapes:
  • Actors are stick figures (never Visio icons or images).
  • Classes / components / nodes are plain rectangles; activities are round-cornered rectangles with the activity name in the upper-left.
  • Dependencies and realizations use dashed lines; lifelines use dashed vertical lines (uml-diagrams.org explicitly: "a rectangle forming its head followed by a vertical line (which may be dashed) that represents the lifetime of the participant").
  • Notes are white folded-corner rectangles; no shading.
• Sequence diagram specifics (matching uml-diagrams.org figures exactly):
  • Lifeline head is a white rectangle; the vertical lifeline is a dashed black line.
  • Execution specification / activation bar is a "thin grey or white rectangle on the lifeline" — this skill renders it as a thin white rectangle with a black border (no yellow PlantUML default).
  • Destruction occurrence is shown as an X at the bottom of the lifeline (PlantUML ! syntax).
  • Synchronous messages use a filled solid triangle arrowhead on a solid line.
  • Asynchronous messages use an open stick arrowhead on a solid line.
  • Reply / return messages use an open stick arrowhead on a dashed line.
• Activity diagram specifics: round-cornered action rectangles, solid arrows with open arrowheads for control flow, diamond decisions/merges, thick horizontal/vertical bar for forks/joins, filled black dot for initial node, bull's-eye for activity final.
• Use case diagram specifics: stick-figure actor on the left, ellipses for use cases inside a rectangle subject boundary, «include» / «extend» as dashed open arrows.
• Class diagram specifics: associations are plain solid lines, aggregation = hollow diamond, composition = filled diamond, generalization = hollow triangle arrowhead on solid line, realization = hollow triangle arrowhead on dashed line, dependency = open arrow on dashed line.

Every .puml file MUST include the mandatory uml-diagrams.org-style preamble as its first lines after @startuml (see Style Configuration).

---

Workflow

Step 1: Parse and Confirm Requirements

Extract from the user's description:

• Diagram type — which PlantUML diagram fits best
• Actors/participants — who/what is involved
• Relationships/flows — how they interact
• Constraints/rules — conditions, ordering, cardinality
• Output format — svg (default), png, pdf, or txt (ASCII art)

If the diagram type is not explicitly stated, infer it from the description:

If ambiguous, ask the user to clarify the diagram type before proceeding.

Step 2: Generate PlantUML Code

Write the PlantUML source following these rules:

1. Start EVERY file with one of the two mandatory uml-diagrams.org-style preambles immediately after @startuml:
   • Default: the skinparam preamble — see OMG-UML / uml-diagrams.org Style Configuration. Maximum backward compatibility, used by every example except #07. (Example #07 is a legacy alias of #01_css — same OAuth2 sequence diagram, same CSS preamble.)
   • Backup option: the CSS-style ` skinparam classAttributeIconSize 0

title Payment System

class User { +id: UUID +email: String +name: String +register() }

class Order { +id: UUID +total: Decimal +status: OrderStatus +calculateTotal() }

class PaymentProcessor <> { +processPayment(amount: Decimal): Boolean +refund(transactionId: UUID): Boolean }

class NotificationService <> { #enabled: Boolean +{abstract} send(to: String, body: String) }

enum OrderStatus { PENDING CONFIRMED SHIPPED DELIVERED }

User "1" -- "*" Order : places Order ..|> PaymentProcessor NotificationService <|-- EmailNotifier @enduml

Key syntax: `+` public, `-` private, `#` protected, `{abstract}` abstract method,
`class Foo <>` (interface via text stereotype — NOT `interface Foo`),
`class Bar <>` (abstract class — NOT `abstract class Bar`),
`enum`, relationships: `--` association, `*--` composition, `o--` aggregation,
`<|--` inheritance, `..|>` realization

### Activity Diagram

@startuml title Order Processing

start :Receive Order; if (Payment Valid?) then (yes) :Reserve Inventory; if (Inventory Available?) then (yes) :Confirm Order; :Ship Order; stop else (no) :Notify Customer; :Cancel Order; stop endif else (no) :Reject Order; stop endif @enduml

Key syntax: `start/stop/end`, `if/then/else/endif`, `repeat/repeat while`,
`fork/fork again/end fork` (parallel), `split/split again/end split`,
`partition "name" { ... }` (swimlane), `:Text;` action

### Use Case Diagram

@startuml title E-Commerce System

left to right direction

actor Customer actor Admin

rectangle "E-Commerce" { usecase "Browse Products" as UC1 usecase "Place Order" as UC2 usecase "Manage Inventory" as UC3 usecase "Process Returns" as UC4 }

Customer --> UC1 Customer --> UC2 Admin --> UC3 Admin --> UC4 UC2 ..> UC1 : <> @enduml

Key syntax: `actor`, `usecase`, `rectangle/package` for system boundary,
`-->` association, `..>` dependency, `<>` / `<>` stereotypes

### Component Diagram

@startuml title Microservice Architecture

package "Frontend" { [Web App] [Mobile App] }

package "API Gateway" { [Gateway] }

package "Services" { [User Service] [Order Service] [Payment Service] }

database "PostgreSQL" as DB cloud "Message Queue" as MQ

[Web App] --> [Gateway] [Mobile App] --> [Gateway] [Gateway] --> [User Service] [Gateway] --> [Order Service] [Order Service] --> [Payment Service] [User Service] --> DB [Order Service] --> DB [Order Service] --> MQ @enduml

Key syntax: `[Component]`, `package "name" { }`, `database`, `cloud`, `node`,
`frame`, `interface`, `()--` required interface, `--()` provided interface

### Deployment Diagram

@startuml title Production Deployment

node "AWS us-east-1" { node "VPC" { node "Public Subnet" { [Load Balancer] [Bastion Host] } node "Private Subnet" { node "App Server 1" { [Application] } node "App Server 2" { [Application] } database "RDS Primary" } } cloud "CDN" } @enduml

Key syntax: `node "name" { }`, nested `node`, `database`, `cloud`, `actor`

### State Diagram

@startuml title Order Lifecycle

[] --> Draft Draft --> Submitted : submit() Submitted --> Paid : processPayment() Submitted --> Cancelled : cancel() Paid --> Shipped : ship() Shipped --> Delivered : confirmDelivery() Delivered --> [] Cancelled --> [*]

state Paid { [] --> Authorizing Authorizing --> Captured : success Authorizing --> Failed : decline Captured --> [] } @enduml

Key syntax: `[*]` start/end, `-->` transition with optional `: label`,
`state Name { }` composite state, `state "Name" as Alias`

### Gantt Chart

@startuml title Project Roadmap

project starts 2025-01-06

[Design] lasts 10 days [Development] lasts 20 days [Development] starts at [Design]'s end [Testing] lasts 10 days [Testing] starts at [Development]'s end [Deployment] lasts 3 days [Deployment] starts at [Testing]'s end

[Frontend] lasts 12 days [Frontend] starts at [Design]'s end [Backend] lasts 15 days [Backend] starts at [Design]'s end @enduml

Key syntax: `project starts YYYY-MM-DD`, `[Task] lasts N days`,
`[Task] starts at [Other]'s end`, `--` separator for dependency,
`printscale weekly/monthly`, `@dailymail`, `@weeklymail`

### Mind Map

@startmindmap title System Architecture

• Root Node ** Level 1 A *** Level 2 A1 *** Level 2 A2 ** Level 1 B *** Level 2 B1 **** Level 3 B1a **** Level 3 B1b ** Level 1 C @endmindmap

Key syntax: `*` root, `**` level 1, `***` level 2, etc.
Use `@startmindmap` / `@endmindmap` (not `@startuml`).
Affix `_` to markdown-style side notation, e.g., `***_ Right side node`.
Colors: ``

---

## OMG-UML / uml-diagrams.org Style Configuration (MANDATORY)

Every generated `.puml` file MUST include this CSS-style preamble immediately after `@startuml`.
It locks PlantUML's rendering to the **uml-diagrams.org reference style** (strict OMG UML 2.x,
black-and-white Visio stencils).

Since PlantUML `1.2019.9` the project officially recommends the **CSS-like `

' ── Per-element skinparam fallback (mandatory) ─────────────────────────────
' The CSS ` is therefore
mandatory — treat CSS and skinparam as **complementary layers**, not
alternatives. Together they guarantee black borders + white fills for actor /
usecase / rectangle / class / component / interface / package / node / database
/ cloud / state / activity / sequence / note across every diagram type and both
light and dark backgrounds.

The **only** allowed `skinparam ... style` value is the default — do NOT add
`skinparam style strictuml`. Even though `strictuml` sounds like a "make it
more UML-compliant" flag, in practice it:

- collapses `actor Foo` from a stick figure into a plain text label
- collapses `usecase "X" as UC` from an ellipse into a plain rectangle
- removes the class-header separator line so name/attribute/method sections merge

The render script also **defensively strips** any leftover
`skinparam style strictuml` line before dispatching to the backend, so
accidental re-introductions from user edits or LLM output are neutralized at
the pipeline level.

`skinparam classAttributeIconSize 0` is retained separately because it only
removes the colored visibility dots (●/◐/○) and has no side effects on shapes.

### Common Failure Patterns

Symptoms and their root cause — check this list first if a rendered diagram
looks visually wrong:

| Symptom | Root cause | Fix |
|---|---|---|
| Actor rendered as bare text, no stick figure | `skinparam style strictuml` in the source | Remove the line; rely on the per-element skinparam fallback (the render script also auto-strips it). |
| Use case rendered as a plain rectangle instead of an ellipse | Same as above (`strictuml`) | Same as above. |
| Class header separator line missing / name+attributes merged | Same as above (`strictuml`) | Same as above. |
| Ellipses / actor paths lose their black border on light background | CSS `` alone is used; the per-element `skinparam actor/usecase` block is missing | Restore the full preamble including the per-element skinparam fallback block. |
| Sequence activation bar rendered yellow instead of white | Missing `skinparam sequence { ActorBackgroundColor #FFFFFF ... }` | Restore the full preamble. |
| Class attributes show `●` / `◐` / `○` visibility icons | Missing `skinparam classAttributeIconSize 0` | Add the line. |
| Header header sub-elements show `Ⓒ`/`Ⓘ`/`Ⓐ`/`Ⓔ` circle icons | Diagram used `interface Foo` / `abstract class Foo` / `enum Foo` keywords | Rewrite as `class Foo <>` / `class Foo <>` / `class Foo <>`. |
| Any decorative color / gradient / drop shadow appears | A `!theme` directive or extra `skinparam ...Color` overrides sneaked in | Remove them; the mandatory preamble is the single source of styling truth. |

### Backup - `skinparam` Preamble (backward-compatible)

Use this preamble only when you need maximum backward compatibility with PlantUML < 1.2019.9.
Both preambles produce the **same uml-diagrams.org reference look**.

' uml-diagrams.org reference style — strict OMG UML 2.x, monochrome skinparam monochrome true skinparam backgroundColor #FFFFFF skinparam defaultFontName Helvetica skinparam defaultFontSize 12 skinparam shadowing false skinparam classAttributeIconSize 0 skinparam sequenceMessageAlign center skinparam roundCorner 0

' Force every fill to white so monochrome never falls back to grey skinparam ActorBackgroundColor #FFFFFF skinparam ParticipantBackgroundColor #FFFFFF skinparam NoteBackgroundColor #FFFFFF skinparam SequenceGroupBackgroundColor #FFFFFF skinparam PackageBackgroundColor #FFFFFF skinparam ClassBackgroundColor #FFFFFF skinparam ObjectBackgroundColor #FFFFFF skinparam StateBackgroundColor #FFFFFF skinparam UsecaseBackgroundColor #FFFFFF skinparam ComponentBackgroundColor #FFFFFF skinparam ActivityBackgroundColor #FFFFFF skinparam NodeBackgroundColor #FFFFFF skinparam DatabaseBackgroundColor #FFFFFF skinparam StereotypeCBackgroundColor #FFFFFF skinparam StereotypeIBackgroundColor #FFFFFF skinparam StereotypeABackgroundColor #FFFFFF skinparam StereotypeEBackgroundColor #FFFFFF

' Sequence diagrams — match the lifeline / activation look on uml-diagrams.org: ' * lifeline = dashed black vertical line ' * activation bar = thin WHITE rectangle with black border (NOT yellow) skinparam SequenceLifeLineBorderColor #000000 skinparam SequenceLifeLineBackgroundColor #FFFFFF skinparam SequenceLifeLineBorderThickness 0.75 skinparam SequenceActivationBackgroundColor #FFFFFF skinparam SequenceActivationBorderColor #000000 skinparam SequenceArrowColor #000000 skinparam SequenceArrowThickness 0.75 skinparam SequenceBoxBackgroundColor #FFFFFF

' Default arrow / border colour everywhere skinparam ArrowColor #000000 skinparam ArrowThickness 0.75 skinparam DefaultTextColor #000000

**NEVER** apply colored themes (`!theme blueprint`, `!theme cerulean`, etc.), custom colors,
gradients, shadows, or decorative styling — doing so breaks compliance with the
uml-diagrams.org reference style. If a user explicitly and unambiguously requests colour,
add it on top of this preamble rather than removing the preamble.

### CJK (Chinese/Japanese/Korean) Font Support

When diagrams contain CJK characters, `Helvetica` cannot render them — characters will appear as empty boxes (□) or tofu (▯).

**In `.puml` files**: Replace `FontName Helvetica` in the CSS `` block with a CJK-compatible font:
```css
root {
  FontName "WenQuanYi Micro Hei"
}

For the skinparam preamble (backward-compatible):

skinparam defaultFontName "WenQuanYi Micro Hei"

When rendering: Use the --cjk flag, which automatically applies the font substitution and configures Docker font mounting if needed:

python skills/plantuml/scripts/generate_plantuml.py diagram.puml ./output --cjk

Host prerequisites for CJK rendering:

• Docker method: CJK fonts must exist on the host at /usr/share/fonts (or /usr/local/share/fonts, /System/Library/Fonts). The script mounts these into the container.
• Local JAR method: CJK fonts must be installed system-wide (Java uses system fontconfig).
• Public server method: The server handles font rendering automatically.

Common CJK font packages:

---

Error Recovery

If the PlantUML server returns an error:

1. Check for syntax errors in the .puml file
2. Validate that @startuml / @enduml are properly paired
3. Ensure diagram-type-specific syntax is correct (e.g., @startmindmap for mind maps)
4. Try the Docker fallback: docker pull plantuml/plantuml:latest && python skills/plantuml/scripts/generate_plantuml.py ...
5. If all else fails, offer to install Java + plantuml.jar

If CJK characters render as empty boxes (□):

1. Ensure the --cjk flag was passed when rendering
2. Verify CJK fonts are installed on the host: fc-list :lang=zh
3. If using Docker, check that font directories are mounted (the script handles this automatically with --cjk)

If aspect ratio warnings appear:

1. The script applies up to 3 automatic corrections (direction toggle + scale)
2. If warnings persist, manually adjust the .puml:
   • For too-wide diagrams: add top to bottom direction and reduce skinparam BoxPadding
   • For too-tall diagrams: add left to right direction and reduce skinparam ParticipantPadding
   • Try scale 0.75 or scale 0.5 for extreme cases
3. For sequence diagrams with many participants: consider splitting into multiple diagrams or abbreviating participant names

If A4 fit warnings appear (the script prints 📄 A4 fit: ... exceeds A4 ...):

1. The script has already re-rendered once with a scale N directive computed from the smaller required factor. Check the loop output for "A4 fit ✓" on the second render — if present, the diagram now fits within A4.
2. If "Estimated font ≈ Npt on A4" message shows a value BELOW your --min-font-pt threshold (default 8 pt), further down-scaling will not make the diagram readable on print. To fix manually:
   • Split the diagram at a natural boundary (per use case, per subsystem, per actor).
   • Shorten long labels — e.g. replace client_id, redirect_uri with shortened param names.
   • For sequence diagrams with many participants: group messages into sub-diagrams, or abbreviate participant display names.
3. If you do not need A4 conformance for the current output, re-run with --no-a4-check to keep the larger original.
4. To let the diagram stretch across multiple A4 sheets, set --min-font-pt 6 (or lower) and accept reduced legibility — the script will warn but still emit the smaller-than-A4 final image.

---

Output Expectations

After successful generation:

1. Show the generated PlantUML source (collapsed if long)
2. Show the rendered output (SVG inline if possible)
3. Report the saved file paths for both .puml and the rendered image
4. Note any aspect ratio corrections that were applied (with dimensions before/after)
5. Note whether A4 fit was met natively, applied a re-scale (report the scale N factor and the post-fix dimensions), or skipped due to legibility threshold; if the legibility warning fired, surface it and propose splitting the diagram
6. Offer to make adjustments