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 <<interface>> / class <<abstract>> / class <<enumeration>> 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 <<abstract>> 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 <participant> ! 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:

Description signalsRecommended diagram"A sends X to B", "request/response", "handshake"Sequence"inherits from", "has many", "belongs to", entities & fieldsClass"if/then", "approve/reject", workflow, pipelineActivity"user can", "admin manages", roles & permissionsUse Case"depends on", "connects to", services & interfacesComponent"deployed on", "hosted on", nodes & serversDeployment"transitions from", "changes state", lifecycleStatetimeline, milestones, phases, scheduleGantthierarchy, brainstorming, tree structureMind Map

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 <style> preamble — see Alternative — CSS-style Preamble. Recommended on PlantUML ≥ 1.2019.9 where skinparam is being phased out. Pick ONE per file — never mix both inside the same .puml.

2. Use @startuml / @enduml delimiters

3. Include a descriptive title

4. Use proper PlantUML syntax for the chosen diagram type (see Reference below)

5. Keep the diagram focused — don't add unnecessary elements

6. NEVER add color, themed backgrounds, or decorative styling — strict black and white

Save the PlantUML source to a .puml file in the working directory.

Step 3: Render to Image#

Use the bundled conversion script. It is a single, unified Python 3.8+ script that works identically on Linux, macOS, and Windows (native PowerShell, cmd, Git Bash, WSL — anywhere python is on PATH):

bash

python skills/plantuml/scripts/generate_plantuml.py <input.puml> <output_dir> --format <svg|png|pdf|txt>

On Windows PowerShell / cmd the invocation is identical (use backslashes if you prefer):

powershell

python skills\plantuml\scripts\generate_plantuml.py <input.puml> <output_dir> --format <svg|png|pdf|txt>

Historical note — earlier versions shipped a generate-plantuml.sh / generate-plantuml.ps1 pair. Those have been consolidated into this single Python script. All flags use the same --kebab-case names on every OS; the previous PowerShell-style -CamelCase flag names are no longer used.

The script tries three backends in strict priority order — local-first. Docker and the local JAR are tried first; the Kroki public server is OPT-IN ONLY because it uploads your diagram source to a third-party service (kroki.io by default):

1. Docker ( plantuml/plantuml:latest) — preferred default, fully local
2. Local plantuml.jar (requires Java) — offline fallback
3. Kroki public server ( https://kroki.io by default) — OPT-IN via --use-public-server. Override the host with the PLANTUML_PUBLIC_SERVER=<url> environment variable to point at a self-hosted Kroki instance.

⚠ Privacy notice — passing --use-public-server POSTs the entire .puml source to kroki.io (or your override host). Never enable this flag for diagrams containing confidential architecture, credentials, customer data, or proprietary business logic. When in doubt, stay with the default (Docker / local JAR). See the Privacy & Backend Selection section below for the full data-flow contract.

CJK font support: When the .puml contains Chinese, Japanese, or Korean characters, add the --cjk flag:

bash

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

The --cjk flag:

• Replaces Helvetica with WenQuanYi Micro Hei (a CJK-compatible font)
• For Docker: mounts host font directories ( /usr/share/fonts, /usr/local/share/fonts) into the container and refreshes the font cache before rendering
• For local JAR: uses system-installed CJK fonts
• If CJK fonts are not installed on the system, characters will not render correctly. Install them via:
  • Debian/Ubuntu: sudo apt install fonts-wqy-zenhei
  • Fedora: sudo dnf install wqy-zenhei-fonts
  • macOS: CJK fonts are pre-installed (PingFang SC)

Aspect ratio validation: After rendering (SVG or PNG), the script measures width/height and checks whether it sits inside the configured band. The default band is 0.7–1.4 (width/height), i.e. diagrams should be neither extremely tall nor extremely wide. If the output falls outside the band, the script injects layout corrections and re-renders:

• Too tall (width/height < --min-aspect): applies left to right direction and adds spacing guards so labels do not crowd.
• Too wide (width/height > --max-aspect): applies top to bottom direction and adds spacing guards.
• Sequence, activity, and state diagrams skip the direction directive because it is either unsupported or counter-productive for those diagram types; only spacing guards are applied.
• Up to 3 correction attempts are made. If a diagram still cannot be brought into the band (for example a very narrow use-case or state machine), the script keeps the best output and prints a warning rather than forcing an unusable layout.

Spacing guards added during auto-fix include Padding, BoxPadding, ParticipantPadding, MinClassWidth, WrapWidth, NodeSep, and RankSep. These prevent text from becoming cramped when the layout is re-directed.

To disable automatic correction:

bash

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

To set a custom band:

bash

python skills/plantuml/scripts/generate_plantuml.py diagram.puml ./output --min-aspect 0.6 --max-aspect 1.5

Dark mode (opt-in): The default output follows the strict uml-diagrams.org black-and-white style. When the user explicitly asks for a dark variant, add --dark-mode. This emits both the regular light output and a dark companion named <basename>.dark.<fmt>:

bash

python skills/plantuml/scripts/generate_plantuml.py diagram.puml ./output --format svg --dark-mode

Behaviour:

• Light output is rendered normally with the monochrome preamble.
• The dark companion is produced by injecting a CSS @media (prefers-color-scheme: dark) block into the SVG, which automatically adapts to the user's system theme.
• SVG is fully supported. PNG is supported when ImageMagick convert is available. PDF/TXT dark companions are not generated because there is no reliable local post-processor.
• The dark palette uses #1e1e2e canvas, #c9d1d9 text/strokes, #f0f6fc bold text, and #6e7681 lifelines.
• Bare-stroke injection: PlantUML's CSS mode may render some elements (use case ellipses, component rects, actor paths) with fill="none" and no stroke attribute. The script injects CSS rules to add strokes to these elements in both light ( #000000) and dark ( #c9d1d9) variants.
• skinparam style strictuml is FORBIDDEN — despite past documentation claiming it was "essential", strictuml actively degrades key UML shapes: actors collapse into plain-text labels, use cases collapse from ellipses into rectangles, and classes lose their header separator. The correct fix is a complete per-element skinparam block (see OMG-UML Style Configuration) that explicitly sets BackgroundColor/ BorderColor/ FontColor for every element category. The render script also defensively strips any leftover skinparam style strictuml line before dispatching to the backend, so even if a diagram source accidentally re-introduces it, the rendering pipeline will remove it.

A4 paper fit validation: After the aspect-ratio check passes, the render script validates the diagram's pixel dimensions against A4 paper. PlantUML writes SVG in CSS pixels at the 96 DPI standard, so A4 (210×297 mm = 8.27×11.69 in) maps to 794×1123 px portrait or 1123×794 px landscape. The check is ON by default and runs right after the aspect check.

Behaviour:

• If the rendered image already fits within EITHER A4 box — nothing changes, the diagram is reported as A4-ready.
• If the image exceeds both boxes, the script computes the smallest scale factor that lets it fit either orientation, clamps to ≤1.0 and a hard floor of 0.15, injects a scale N directive into a working copy of the .puml, then re-renders once.
• After re-rendering the script estimates the effective on-paper font size: scale × 12 px × 0.75 ≈ pt (the 0.75 factor converts px to pt at 96 DPI). If this is below --min-font-pt it prints a legibility warning — at that point further down-scaling cannot help; the user must split the diagram, shorten labels, or switch to a smaller font.

Flags:

FlagPurposeDefault--no-fixDisable automatic aspect-ratio correctionoff (correction ON)--min-aspect NLower bound of acceptable width/height band0.7``--max-aspect NUpper bound of acceptable width/height band1.4``--no-a4-checkDisable A4 fit validation entirelyoff (check ON)--min-font-pt NMinimum legible on-paper font size in pt8.0``--dark-modeAlso emit a dark companion ( <basename>.dark.<fmt>) with CSS @media themeoff

Examples:

bash

# Disable A4 fit
python skills/plantuml/scripts/generate_plantuml.py diagram.puml ./output --no-a4-check

# Tighten legibility threshold (warn if effective font drops below 10 pt)
python skills/plantuml/scripts/generate_plantuml.py diagram.puml ./output --min-font-pt 10

# Allow narrower diagrams and also emit a dark SVG companion
python skills/plantuml/scripts/generate_plantuml.py diagram.puml ./output --format svg --min-aspect 0.5 --dark-mode

On Windows the same commands work verbatim in PowerShell / cmd — just swap forward slashes for backslashes if you prefer native path style. There is no longer a separate PowerShell flag namespace.

A4 fit is skipped automatically for txt and pdf output (TXT has no image dimensions; PDF is already a print-oriented format the PlantUML renderer pages itself). The check shares the same 3-attempt auto-fix budget as aspect-ratio correction — running both does not double the cap.

After rendering, show the user the output. If SVG is generated, read and display it inline. If PNG/PDF is generated, tell the user where the file is saved.

---

Privacy & Backend Selection#

This skill is local-first. By default, all rendering happens on the user's own machine — diagram source code never leaves the host.

Default behaviour (no flags)#

text

.puml ──► Docker (plantuml/plantuml)  ──► output.svg     [LOCAL, preferred]
   └────► local plantuml.jar (Java)   ──► output.svg     [LOCAL, fallback]

No network calls are made; nothing is uploaded.

Opt-in remote rendering#

The Kroki public server ( https://kroki.io) can render diagrams without any local installation, but doing so POSTs the full .puml source to a third party. To use it you must explicitly opt in:

bash

# Explicit opt-in required (same flag on every OS)
python skills/plantuml/scripts/generate_plantuml.py diagram.puml ./output --use-public-server

When opt-in is active, the script:

1. Prints a runtime privacy warning identifying the destination URL and operator
2. POSTs the full .puml contents to kroki.io (or your override host)
3. Saves the returned SVG/PNG/PDF/TXT locally

Self-hosted Kroki override#

Kroki is open source and self-hostable ( github.com/yuzutech/kroki). To route opt-in traffic to your own instance instead of the public kroki.io, set the PLANTUML_PUBLIC_SERVER env var to your base URL:

bash

# Linux / macOS / Git Bash / WSL
PLANTUML_PUBLIC_SERVER=https://kroki.internal.example.com \
  python skills/plantuml/scripts/generate_plantuml.py diagram.puml ./output --use-public-server

powershell

# Windows PowerShell
$env:PLANTUML_PUBLIC_SERVER = 'https://kroki.internal.example.com'
python skills\plantuml\scripts\generate_plantuml.py diagram.puml .\output --use-public-server

The runtime privacy warning surfaces the resolved host name so you can confirm the traffic destination before any data leaves the machine. Custom hosts must expose the standard Kroki endpoint shape <base>/plantuml/<format>.

Why Kroki replaced the legacy plantuml.com backend (v1.4.1)#

Earlier versions of this script POSTed to https://www.plantuml.com/plantuml/<format>. That endpoint now sits behind a Cloudflare + Ezoic consent wall: a POST returns 302 redirecting to a JavaScript-only HTML consent page, making non-browser automation impossible. Kroki replaces it because:

• It re-runs the official upstream PlantUML JAR server-side, so the output is byte-for-byte the same family of SVG/PNG/PDF/TXT.
• It is open source and trivially self-hostable in Docker, restoring the "render off-host but in your trust boundary" option that the plantuml.com default once provided.
• The Yuzu Tech operated public instance is EU-hosted, which moves the default jurisdiction closer to GDPR-style baseline expectations than the prior US-CDN-fronted plantuml.com path.

When NOT to use --use-public-server#

Never enable remote rendering for diagrams that contain any of the following:

• Internal system / service / hostname identifiers
• Credentials, tokens, API keys, connection strings (even as placeholders)
• Customer data, PII, or any regulated content
• Proprietary architecture, design IP, or trade-secret business logic
• Source code excerpts or unreleased features

If you are unsure whether the diagram is safe to upload, don't opt in — install Docker (one command: docker pull plantuml/plantuml:latest) or download plantuml.jar and render locally.

CJK Docker mode and host font directories#

When --cjk is combined with the Docker backend, the script mounts host font directories read-only into the container so PlantUML can discover system-installed CJK fonts. The mounts are:

• Linux/macOS: /usr/share/fonts, /usr/local/share/fonts, /System/Library/Fonts
• Windows (Git Bash/WSL): /c/Windows/Fonts or /mnt/c/Windows/Fonts
• Windows (PowerShell): %WINDIR%\Fonts

These mounts are read-only ( :ro), are scoped to font directories only, and are used only inside the throwaway PlantUML container. No font data is written back to the host. If you do not need CJK rendering, omit the flag and no host directories are mounted.

---

Step 4: Iterate on Feedback#

If the user requests changes:

1. Modify the .puml file
2. Re-run the conversion script
3. Show the updated result

---

PlantUML Syntax Reference#

Note: All examples below omit the mandatory monochrome preamble for brevity. In actual generated code, EVERY file MUST include the OMG-UML style preamble immediately after @startuml. The class diagram example shows the full preamble inline as a reference.

Sequence Diagram#

text

@startuml
title Authentication Flow

actor User
participant "Web App" as App
participant "Auth Service" as Auth
database "User DB" as DB

User -> App: Login (email, password)
App -> Auth: POST /auth/login
Auth -> DB: SELECT user WHERE email
DB --> Auth: user record
Auth -> Auth: Verify password hash
alt Success
    Auth --> App: JWT token
    App --> User: Dashboard
else Failure
    Auth --> App: 401 Unauthorized
    App --> User: Error message
end
@enduml

Key syntax: -> sync message, --> async/return, ->> async, alt/else/end branching, loop/end loops, opt/end optional, activate/deactivate lifeline, note left/right

Class Diagram#

text

@startuml
' OMG-UML Monochrome Style — CSS variant
<style>
root {
  FontName Helvetica
  FontSize 12
  FontColor #000000
  BackGroundColor #FFFFFF
  LineColor #000000
  LineThickness 0.75
  RoundCorner 0
  Shadowing 0
}
title {
  FontSize 14
  FontStyle bold
  FontColor #000000
  BackGroundColor transparent
  LineColor transparent
  LineThickness 0
}
note {
  BackGroundColor #FFFFFF
  LineColor #000000
  FontColor #000000
}
classDiagram {
  class { BackGroundColor #FFFFFF; LineColor #000000; FontColor #000000 }
  arrow { LineColor #000000; LineThickness 0.75 }
}
</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 <<interface>> {
    +processPayment(amount: Decimal): Boolean
    +refund(transactionId: UUID): Boolean
}

class NotificationService <<abstract>> {
    #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>> (interface via text stereotype — NOT interface Foo), class Bar <<abstract>> (abstract class — NOT abstract class Bar), enum, relationships: -- association, *-- composition, o-- aggregation, <|-- inheritance, ..|> realization

Activity Diagram#

text

@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#

text

@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 : <<include>>
@enduml

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

Component Diagram#

text

@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#

text

@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#

text

@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#

text

@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#

text

@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: <style> * { BackgroundColor lightblue } </style>

---

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 <style> block ( plantuml.com/style-evolution) as the preferred styling mechanism — " skinparam is being phased out … users should migrate to style".

Do NOT mix both inside the same .puml file. Pick one preamble per diagram.

Primary — CSS <style> Preamble (recommended)#

text

@startuml
<style>
root {
  FontName Helvetica
  FontSize 12
  FontColor #000000
  BackGroundColor #FFFFFF
  LineColor #000000
  LineThickness 0.75
  RoundCorner 0
  Shadowing 0
}

title {
  FontSize 14
  FontStyle bold
  FontColor #000000
  BackGroundColor transparent
  LineColor transparent
  LineThickness 0
}

note {
  BackGroundColor #FFFFFF
  LineColor #000000
  FontColor #000000
}

sequenceDiagram {
  actor       { BackGroundColor #FFFFFF; LineColor #000000; FontColor #000000 }
  participant { BackGroundColor #FFFFFF; LineColor #000000; FontColor #000000 }
  lifeLine    { BackGroundColor #FFFFFF; LineColor #000000; LineStyle 5-5; LineThickness 0.75 }
  reference   { BackGroundColor #FFFFFF; LineColor #000000 }
  group       { BackGroundColor #FFFFFF; LineColor #000000 }
  arrow       { LineColor #000000; LineThickness 0.75; FontColor #000000 }
}

classDiagram {
  class { BackGroundColor #FFFFFF; LineColor #000000; FontColor #000000 }
  arrow { LineColor #000000; LineThickness 0.75 }
}

activityDiagram {
  activity { BackGroundColor #FFFFFF; LineColor #000000; FontColor #000000; RoundCorner 10 }
  arrow    { LineColor #000000; LineThickness 0.75 }
  diamond  { BackGroundColor #FFFFFF; LineColor #000000 }
}

useCaseDiagram {
  actor     { BackGroundColor #FFFFFF; LineColor #000000 }
  usecase   { BackGroundColor #FFFFFF; LineColor #000000 }
  rectangle { BackGroundColor #FFFFFF; LineColor #000000 }
}

componentDiagram {
  component { BackGroundColor #FFFFFF; LineColor #000000 }
  package   { BackGroundColor #FFFFFF; LineColor #000000 }
}

stateDiagram {
  state { BackGroundColor #FFFFFF; LineColor #000000; FontColor #000000 }
  arrow { LineColor #000000 }
}
</style>

' ── Per-element skinparam fallback (mandatory) ─────────────────────────────
' The CSS <style> block above does NOT cover every PlantUML element category.
' Without the following block, some shapes fall back to PlantUML defaults
' (yellow activation bars, coloured actors, grey component fills, etc.).
' NEVER add `skinparam style strictuml` — it degrades actors into plain text
' and use cases into rectangles.
skinparam classAttributeIconSize 0
skinparam shadowing false
skinparam backgroundColor #FFFFFF
skinparam defaultFontColor #000000

skinparam actor       { BackgroundColor #FFFFFF; BorderColor #000000; FontColor #000000 }
skinparam usecase     { BackgroundColor #FFFFFF; BorderColor #000000; FontColor #000000 }
skinparam rectangle   { BackgroundColor #FFFFFF; BorderColor #000000; FontColor #000000 }
skinparam class       { BackgroundColor #FFFFFF; BorderColor #000000; FontColor #000000 }
skinparam object      { BackgroundColor #FFFFFF; BorderColor #000000; FontColor #000000 }
skinparam component   { BackgroundColor #FFFFFF; BorderColor #000000; FontColor #000000 }
skinparam interface   { BackgroundColor #FFFFFF; BorderColor #000000; FontColor #000000 }
skinparam package     { BackgroundColor #FFFFFF; BorderColor #000000; FontColor #000000 }
skinparam node        { BackgroundColor #FFFFFF; BorderColor #000000; FontColor #000000 }
skinparam database    { BackgroundColor #FFFFFF; BorderColor #000000; FontColor #000000 }
skinparam cloud       { BackgroundColor #FFFFFF; BorderColor #000000; FontColor #000000 }
skinparam state       { BackgroundColor #FFFFFF; BorderColor #000000; FontColor #000000 }
skinparam activity    { BackgroundColor #FFFFFF; BorderColor #000000; FontColor #000000 }
skinparam sequence    { ArrowColor #000000; LifeLineBorderColor #000000; LifeLineBackgroundColor #FFFFFF; ParticipantBackgroundColor #FFFFFF; ParticipantBorderColor #000000; ActorBackgroundColor #FFFFFF; ActorBorderColor #000000; BoxBackgroundColor #FFFFFF; BoxBorderColor #000000 }
skinparam note        { BackgroundColor #FFFFFF; BorderColor #000000; FontColor #000000 }

What each CSS block does (mapped to uml-diagrams.org figures):

CSS BlockEffect / uml-diagrams.org referencerootGlobal defaults: Helvetica 12px black-on-white, 0.75pt lines, no shadows, square corners. Matches Visio UML 2.x stencil look.root > Shadowing 0Disables drop shadows — uml-diagrams.org figures never have shadows.root > RoundCorner 0Square corners on rectangles (matches Visio stencils). activityDiagram.activity overrides to 10 for round-cornered actions.titleBold 14px black text, transparent background/border.noteWhite fill, black border, black text — matches uml-diagrams.org note style.sequenceDiagram.lifeLineDashed black lines ( LineStyle 5-5) — exactly the lifeline notation on uml-diagrams.org/sequence-diagrams.html.sequenceDiagram.arrowThin black arrows (0.75pt) — matches Visio stencil hair-line strokes.classDiagram.classWhite fill, black border — no grey fills.activityDiagram.activityWhite fill with round corners ( RoundCorner 10) — matches uml-diagrams.org activity shape.activityDiagram.diamondWhite fill, black border for decision/merge diamonds.useCaseDiagramWhite actors, use cases, and rectangles — no colored fills.componentDiagramWhite components and packages — no colored fills.stateDiagram.stateWhite fill, black border — no grey fills.

STYLING POLICY — keep the FULL preamble, NEVER use strictuml

The CSS <style> block above tells PlantUML how to render CSS-aware elements (sequence lifelines, class boxes, activity nodes, notes). It does NOT cover every PlantUML element category — actor stick-figures, use case ellipses, component silhouettes, database cylinders and cloud shapes still fall back to PlantUML's built-in defaults (colored fills, yellow activation bars, missing borders on white canvas) when only a <style> block is present.

The per-element skinparam block immediately after </style> 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:

SymptomRoot causeFixActor rendered as bare text, no stick figureskinparam style strictuml in the sourceRemove 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 ellipseSame as above ( strictuml)Same as above.Class header separator line missing / name+attributes mergedSame as above ( strictuml)Same as above.Ellipses / actor paths lose their black border on light backgroundCSS <style> alone is used; the per-element skinparam actor/usecase block is missingRestore the full preamble including the per-element skinparam fallback block.Sequence activation bar rendered yellow instead of whiteMissing skinparam sequence { ActorBackgroundColor #FFFFFF ... }Restore the full preamble.Class attributes show ● / ◐ / ○ visibility iconsMissing skinparam classAttributeIconSize 0Add the line.Header header sub-elements show Ⓒ/ Ⓘ/ Ⓐ/ Ⓔ circle iconsDiagram used interface Foo / abstract class Foo / enum Foo keywordsRewrite as class Foo <<interface>> / class Foo <<abstract>> / class Foo <<enumeration>>.Any decorative color / gradient / drop shadow appearsA !theme directive or extra skinparam ...Color overrides sneaked inRemove 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.

text

' 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 <style> block with a CJK-compatible font:

css

root {
  FontName "WenQuanYi Micro Hei"
}

For the skinparam preamble (backward-compatible):

text

skinparam defaultFontName "WenQuanYi Micro Hei"

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

bash

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:

OSPackageDebian/Ubuntufonts-wqy-zenheiFedora/RHELwqy-zenhei-fontsArchwqy-zenheiAlpinefont-wqy-zenheimacOSBuilt-in (PingFang SC / Hiragino Sans)

---

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